Initial commit

skills/status-progression/SKILL.md

@@ -0,0 +1,352 @@
+---
+skill: status-progression
+description: Navigate status workflows with user's config. Use when asked "What's next?", "Can I move to X?", or "Why did this fail?". Delegates to get_next_status tool, interprets StatusValidator errors, explains forward/backward/emergency patterns. Lightweight coordinator - validates nothing, explains everything.
+---
+
+# Status Progression Skill
+
+**Role:** Workflow interpreter and guide. Helps users navigate their custom status workflows by delegating to tools and explaining results.
+
+**Complementary Architecture:**
+- **get_next_status tool** - Reads config, analyzes state, recommends next status (read-only)
+- **StatusValidator** - Validates transitions at write-time, enforces rules, checks prerequisites (write-time)
+- **This Skill** - Interprets recommendations and errors, explains user's config rules (guidance)
+
+## When to Use This Skill
+
+**Activate for:**
+- "What status comes next?"
+- "Can I move to testing/completed/etc?"
+- "Why did my status change fail?"
+- "Am I ready to complete this?"
+- "What's my workflow?"
+- "How do backward transitions work?"
+
+## Core Responsibilities
+
+1. **Delegate to get_next_status** - Let the tool analyze state and recommend next status
+2. **Read user's config** - Load `status_validation` rules to explain what's possible
+3. **Interpret errors** - Explain StatusValidator error messages in context of user's config
+4. **Guide transitions** - Explain forward, backward, and emergency movements
+
+## Tools Available
+
+- `Read` - Load `.taskorchestrator/config.yaml` (status_validation section only)
+- `get_next_status` - Intelligent status recommendations (delegates to MCP tool)
+- `query_workflow_state` - Complete workflow state with cascade events (**NEW**)
+- `query_container` - Check entity state (status, tags) when interpreting errors
+
+**Critical:** This skill does NOT validate transitions. StatusValidator handles that automatically at write-time. This skill interprets results and explains user's workflow rules.
+
+## Workflow Patterns: Forward, Backward, and Emergency
+
+### Pattern 1: Forward Progression (Happy Path)
+
+**When:** Moving through normal workflow sequence
+
+**Example:**
+```javascript
+// User asks: "What's next?"
+recommendation = get_next_status(containerId="task-uuid", containerType="task")
+
+// Guide user:
+"You're at: in-progress
+Next step: testing
+
+Your bug_fix_flow: pending → in-progress → testing → completed
+StatusValidator will verify prerequisites when you transition."
+```
+
+**Why forward?** Normal progression toward completion.
+
+### Pattern 2: Backward Movement (Rework/Iteration)
+
+**When:** Need to fix issues, iterate on work, or respond to changes
+
+**Example:**
+```javascript
+// User asks: "Can I move back to in-progress from in-review?"
+config = Read(".taskorchestrator/config.yaml")
+
+if (config.status_validation.allow_backward == true) {
+  "✅ Yes! Your config allows backward movement.
+
+  in-review → in-progress (backward to implement changes)
+
+  Why: Code review requested changes, found a bug, requirements changed
+  Then re-submit: in-progress → in-review"
+}
+```
+
+**Why backward?** Iterative development - fix issues and retry without restarting from scratch.
+
+**For detailed review iteration patterns:**
+Read `./config-reference.md`
+
+### Pattern 3: Emergency Transitions (Blockers/Cancellations)
+
+**When:** Unexpected blockers, priority changes, or cancellations
+
+**Example:**
+```javascript
+// User asks: "Task is blocked by external API, what do I do?"
+config = Read(".taskorchestrator/config.yaml")
+
+emergencyStatuses = config.status_progression.tasks.emergency_transitions
+// Returns: [blocked, on-hold, cancelled, deferred]
+
+"✅ Use emergency transition to: blocked
+in-progress → blocked (emergency - can happen from any state)
+
+Why emergency transitions exist:
+- blocked: External dependency or technical issue
+- on-hold: Priority shift, paused temporarily
+- cancelled: Task no longer needed
+- deferred: Postponed indefinitely"
+```
+
+**Why emergency?** Real-world interruptions don't follow linear workflows.
+
+## Quick Action Patterns
+
+### Action 1: What's Next?
+
+**User:** "What status comes next?"
+
+**Workflow:**
+```javascript
+// Delegate to tool
+recommendation = get_next_status(containerId="task-uuid", containerType="task")
+```
+
+**Response:**
+```
+Next: testing
+
+Your position: in-progress [YOU ARE HERE]
+Flow: pending → in-progress → testing → completed
+Using: bug_fix_flow (matched your tags: [bug, backend])
+
+To transition:
+manage_container(operation="setStatus", containerType="task", id="...", status="testing")
+```
+
+### Action 2: Try Transition (Let StatusValidator Check)
+
+**User:** "Can I mark this complete?"
+
+**Workflow:**
+```javascript
+// Don't manually validate - delegate to get_next_status
+recommendation = get_next_status(containerId="task-uuid", containerType="task")
+
+// Guide user to try it
+"get_next_status recommends: completed
+
+Try it! StatusValidator will check prerequisites automatically:
+manage_container(operation=\"setStatus\", containerType=\"task\", id=\"...\", status=\"completed\")
+
+If prerequisites aren't met, StatusValidator will explain what's missing.
+I'll help interpret any errors."
+```
+
+**Key:** Let StatusValidator do validation. This skill interprets results.
+
+### Action 3: Interpret StatusValidator Error
+
+**User gets error:** "Cannot skip statuses. Must transition through: in-progress"
+
+**Workflow:**
+```javascript
+// Read user's config to explain the rule
+config = Read(".taskorchestrator/config.yaml")
+
+"StatusValidator blocked this because YOUR config has:
+  enforce_sequential: true
+
+You tried: pending → testing (skipped in-progress)
+
+Your options:
+1. Follow sequential flow: pending → in-progress → testing
+2. Change your config: Set enforce_sequential: false in config.yaml
+
+Recommended next step:
+manage_container(operation=\"setStatus\", containerType=\"task\", id=\"...\", status=\"in-progress\")"
+```
+
+**For detailed error interpretation patterns:**
+Read `./validation-errors.md`
+
+### Action 4: Check Complete Workflow State (NEW)
+
+**User asks:** "Show me everything about this task's workflow"
+
+**Workflow:**
+```javascript
+// Get comprehensive workflow state
+workflowState = query_workflow_state(
+  containerType="task",
+  id="task-uuid"
+)
+
+// Explain complete state
+"📊 Workflow State:
+
+Current: ${workflowState.currentStatus}
+Active Flow: ${workflowState.activeFlow}
+
+✅ Allowed Next Steps:
+${workflowState.allowedTransitions.map(s => `  → ${s}`).join('\n')}
+
+⚠️ Cascade Events Detected:
+${workflowState.detectedEvents.map(e => `  • ${e.event}: ${e.reason}`).join('\n')}
+
+📋 Prerequisites for Each Transition:
+${Object.entries(workflowState.prerequisites).map(([status, prereq]) =>
+  `  ${status}: ${prereq.met ? '✅' : '❌'} ${prereq.blockingReasons.join(', ')}`
+).join('\n')}"
+```
+
+**Benefits:**
+- Single call gets complete workflow context
+- Shows all allowed transitions from config
+- Detects cascade events automatically
+- Validates prerequisites for each option
+- Works with user's custom workflows
+
+### Action 5: Phase 3 Handoff (Tasks Ready to Execute)
+
+**Scenario:** Feature has tasks created and ready to execute, but feature status is still "planning" or "draft"
+
+**User asks:** "Progress feature to in-development before executing tasks"
+
+**Workflow:**
+```javascript
+// Check feature status
+feature = query_container(operation="get", containerType="feature", id=featureId)
+
+if (feature.status == "planning" || feature.status == "draft") {
+  // Get recommendation
+  recommendation = get_next_status(containerId=featureId, containerType="feature")
+
+  // Explain the cascade event and use recommendation
+  "✅ Feature ready to progress from: ${feature.status}
+  Recommended next status: ${recommendation.recommendedStatus}
+  Active flow: ${recommendation.activeFlow}
+
+  Cascade Event: tasks_ready_to_execute
+  Trigger: Tasks created and ready for specialist execution
+
+  Why this matters:
+  - Feature status must reflect current development phase
+  - Config determines execution phase status name (not hardcoded)
+  - Your workflow uses: ${recommendation.activeFlow}
+
+  To progress:
+  manage_container(operation=\"setStatus\", containerType=\"feature\", id=\"${featureId}\", status=\"${recommendation.recommendedStatus}\")
+
+  Then delegate to Task Orchestration Skill for parallel execution."
+}
+```
+
+**When this applies:**
+- After Phase 2 (task breakdown) completes
+- Before Phase 3 (task execution) begins
+- When resuming paused feature work with pending tasks
+
+**Why critical:**
+- Prevents feature from jumping directly to completion (skips execution phase)
+- Enables proper cascade event detection (tasks_ready_to_execute)
+- Ensures workflow state reflects reality (config-driven status progression)
+- Required for StatusValidator prerequisite checks
+- Respects user's custom workflow (not hardcoded to specific status names)
+
+## Understanding User-Defined Flows
+
+**Critical:** Flows are defined by the USER in their config.yaml. Don't assume any specific flows exist.
+
+**Check user's actual flows:**
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+taskFlows = Object.keys(config.status_progression.tasks).filter(key => key.endsWith('_flow'))
+// Tell user: "Your config has these task flows: [list]"
+```
+
+**Default config has** (IF user hasn't customized):
+- Tasks: `default_flow`, `bug_fix_flow`, `documentation_flow`, `hotfix_flow`, `with_review`
+- Features: `default_flow`, `rapid_prototype_flow`, `with_review_flow`
+- Projects: `default_flow`
+
+**For custom flow examples (research, compliance, experiments, etc.):**
+Read `./examples.md`
+
+**For tag-based flow selection details:**
+Read `./examples.md`
+
+## What to Read from Config
+
+**Read selectively** - only load sections needed to explain user's rules:
+
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+
+// Section 1: Validation rules (always useful)
+validationRules = config.status_validation
+// - enforce_sequential: Can skip statuses?
+// - allow_backward: Can move backwards?
+// - allow_emergency: Can jump to blocked/cancelled?
+// - validate_prerequisites: Does StatusValidator check requirements?
+
+// Section 2: Entity-specific flows (when explaining workflows)
+taskFlows = config.status_progression.tasks
+emergencyStatuses = config.status_progression.tasks.emergency_transitions
+terminalStatuses = config.status_progression.tasks.terminal_statuses
+```
+
+**For detailed config structure reference:**
+Read `./config-reference.md`
+
+## Best Practices
+
+1. **Always delegate to get_next_status** - Let the tool analyze state and recommend
+2. **Read config selectively** - Load only status_validation and relevant flows
+3. **Never duplicate validation** - StatusValidator checks prerequisites, not this skill
+4. **Explain user's specific config** - Don't assume default flows exist
+5. **Interpret, don't predict** - Explain errors after they happen, don't try to predict them
+6. **Use progressive loading** - Load supporting files (examples.md, validation-errors.md, config-reference.md) only when needed
+7. **Emphasize user control** - Flows are defined by user, not hardcoded by system
+
+## Supporting Files
+
+**Load on demand for specific scenarios:**
+
+- **./examples.md** - Custom flow examples, tag-based selection patterns
+  - Load when: User asks about custom flows, workflow possibilities, tag routing
+
+- **./validation-errors.md** - Common errors, prerequisite failures, fix patterns
+  - Load when: StatusValidator error occurs, user asks about validation rules
+
+- **./config-reference.md** - Detailed config structure, backward movement, integration
+  - Load when: User asks about configuration, how to customize workflows
+
+## Key Reminders
+
+**Your Role (Lightweight Coordination):**
+- ✅ Delegate to get_next_status for all recommendations
+- ✅ Read config.status_validation to explain user's rules
+- ✅ Interpret StatusValidator errors with context
+- ✅ Show forward/backward/emergency patterns with WHY explanations
+- ✅ Reference user's ACTUAL config, not assumed defaults
+- ✅ Load supporting files only when needed (progressive loading)
+
+**What You DON'T Do:**
+- ❌ Don't manually validate transitions (StatusValidator's job)
+- ❌ Don't check prerequisites before transitions (StatusValidator's job)
+- ❌ Don't duplicate logic from get_next_status (delegate to tool)
+- ❌ Don't assume specific flows exist (user-defined, could be customized)
+- ❌ Don't load all supporting files upfront (use progressive loading)
+
+**Complementary Roles:**
+- **get_next_status** reads config, analyzes tags, recommends (read-only)
+- **StatusValidator** enforces rules, checks prerequisites (write-time)
+- **You** interpret results, explain possibilities (guidance)

skills/status-progression/config-reference.md

@@ -0,0 +1,463 @@
+# Status Progression - Configuration Reference
+
+This file contains detailed config structure and backward movement patterns. Load this when users ask about configuration or how to customize workflows.
+
+## Config Structure
+
+**File location:** `.taskorchestrator/config.yaml`
+
+### Full Structure Overview
+
+```yaml
+version: "2.0.0"
+
+status_progression:
+  features:
+    default_flow: [...]           # Always exists
+    custom_flow: [...]            # User-defined (optional)
+    flow_mappings: [...]          # Tag → flow routing
+    emergency_transitions: [...]  # Statuses from any state
+    terminal_statuses: [...]      # End states
+
+  tasks:
+    default_flow: [...]
+    custom_flow: [...]
+    flow_mappings: [...]
+    emergency_transitions: [...]
+    terminal_statuses: [...]
+
+  projects:
+    default_flow: [...]
+    emergency_transitions: [...]
+    terminal_statuses: [...]
+
+status_validation:
+  enforce_sequential: true/false  # Sequential progression required?
+  allow_backward: true/false      # Backward movement allowed?
+  allow_emergency: true/false     # Emergency transitions allowed?
+  validate_prerequisites: true/false # Prerequisite checking enabled?
+```
+
+### What Each Section Controls
+
+**status_progression.{entityType}.default_flow:**
+- **Purpose:** Fallback flow when no tags match flow_mappings
+- **Required:** Yes (at least one flow per entity type)
+- **Format:** Array of status names in kebab-case
+- **Example:** `[pending, in-progress, testing, completed]`
+
+**status_progression.{entityType}.flow_mappings:**
+- **Purpose:** Route entities to flows based on tags
+- **Required:** No (can be empty array)
+- **Format:** Array of {tags, flow} objects
+- **Example:**
+  ```yaml
+  - tags: [bug, bugfix, fix]
+    flow: bug_fix_flow
+  ```
+- **Matching:** First match wins (order matters)
+
+**status_progression.{entityType}.emergency_transitions:**
+- **Purpose:** Statuses accessible from any state (bypass flow rules)
+- **Required:** No (can be empty array)
+- **Format:** Array of status names
+- **Example:** `[blocked, on-hold, cancelled, deferred]`
+- **When used:** Unexpected blockers, priority shifts, cancellations
+
+**status_progression.{entityType}.terminal_statuses:**
+- **Purpose:** End states with no further progression
+- **Required:** Yes (can be empty but must exist)
+- **Format:** Array of status names
+- **Example:** `[completed, cancelled, archived]`
+- **Effect:** Cannot transition FROM these statuses
+
+**status_validation.enforce_sequential:**
+- **Purpose:** Require step-by-step progression through flow
+- **When true:** Cannot skip statuses (pending → testing blocked, must go through in-progress)
+- **When false:** Can jump to any status in flow
+- **Recommendation:** true for teams needing process compliance
+
+**status_validation.allow_backward:**
+- **Purpose:** Allow moving backwards in flow for rework
+- **When true:** Can move testing → in-progress for bug fixes
+- **When false:** Can only move forward
+- **Recommendation:** true for iterative development
+
+**status_validation.allow_emergency:**
+- **Purpose:** Allow emergency_transitions from any state
+- **When true:** Can jump to blocked/on-hold/cancelled from anywhere
+- **When false:** Emergency statuses follow normal flow rules
+- **Recommendation:** true to handle unexpected issues
+
+**status_validation.validate_prerequisites:**
+- **Purpose:** Check business rules before transitions
+- **When true:** Feature needs tasks before in-development, tasks need summary before completed
+- **When false:** Skip prerequisite checks
+- **Recommendation:** true to prevent incomplete work from being marked complete
+
+---
+
+## Backward Movement for Review Iterations
+
+**Pattern:** With `allow_backward: true`, you can move backwards in the flow for unlimited review iterations without duplicate statuses.
+
+### Example: with_review Flow
+
+**Flow definition:**
+```yaml
+with_review:
+  - backlog
+  - pending
+  - in-progress
+  - in-review          # Awaiting code review
+  - testing            # Review approved, testing
+  - completed
+```
+
+**Config settings:**
+```yaml
+status_validation:
+  enforce_sequential: true   # Follow flow order
+  allow_backward: true       # Allow backward movement
+```
+
+### Iteration Workflow
+
+**First submission:**
+```javascript
+// Developer finishes work
+in-progress → in-review (forward)
+```
+
+**Changes requested:**
+```javascript
+// Reviewer requests changes
+in-review → in-progress (backward to implement changes)
+```
+
+**Re-submission after changes:**
+```javascript
+// Developer re-submits after fixes
+in-progress → in-review (forward for re-review)
+```
+
+**Multiple rounds:**
+```javascript
+// If more changes needed, repeat:
+in-review → in-progress (backward again)
+in-progress → in-review (forward again)
+
+// Unlimited iterations supported
+```
+
+**Approval:**
+```javascript
+// When approved, move forward
+in-review → testing (forward when review passes)
+testing → completed (forward to complete)
+```
+
+### Why Backward Movement Works Better
+
+**Instead of this (duplicate statuses in flow - DOESN'T WORK with enforce_sequential):**
+```yaml
+# ❌ BROKEN with enforce_sequential: true
+with_review_iterations:
+  - pending
+  - in-progress
+  - in-review
+  - in-progress    # Duplicate status
+  - in-review      # Duplicate status
+  - in-progress    # Duplicate status
+  - testing
+```
+
+**Use this (clean flow + backward movement):**
+```yaml
+# ✅ WORKS with enforce_sequential: true + allow_backward: true
+with_review:
+  - pending
+  - in-progress
+  - in-review
+  - testing
+  - completed
+
+# No duplicates needed - backward movement handles iterations
+```
+
+### Key Benefits
+
+- ✅ **Unlimited iterations** - Move backward as many times as needed
+- ✅ **Clean flow definition** - No duplicate statuses required
+- ✅ **Works with enforce_sequential** - Maintains process compliance
+- ✅ **Clear history** - Status changes show iteration count
+- ✅ **Flexible** - Works for any iterative workflow (reviews, testing, validation)
+
+### changes-requested Status
+
+**Note:** The `changes-requested` status exists in the TASK enum but is NOT used in default flows.
+
+**Why it exists:**
+- Some teams want explicit "changes requested" state
+- Can create custom flows that include it
+
+**Why it's not in default flows:**
+- Backward movement pattern is more flexible
+- No need for separate status - just move backward
+
+**If you want to use it:**
+```yaml
+# Custom flow with changes-requested
+custom_review_flow:
+  - pending
+  - in-progress
+  - in-review
+  - changes-requested  # Explicit state for requested changes
+  - testing
+  - completed
+
+# Workflow:
+# in-review → changes-requested (reviewer requests changes)
+# changes-requested → in-progress (developer starts fixing)
+# in-progress → in-review (developer re-submits)
+```
+
+---
+
+## What to Read from Config
+
+**Read selectively** - only load sections needed to explain user's rules:
+
+### Always Useful: Validation Rules
+
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+
+// Section 1: Validation rules (always useful)
+validationRules = config.status_validation
+// - enforce_sequential: Can skip statuses?
+// - allow_backward: Can move backwards?
+// - allow_emergency: Can jump to blocked/cancelled?
+// - validate_prerequisites: Does StatusValidator check requirements?
+```
+
+### When Explaining Workflows: Entity-Specific Flows
+
+```javascript
+// Section 2: Entity-specific flows (when explaining workflows)
+taskFlows = config.status_progression.tasks
+featureFlows = config.status_progression.features
+projectFlows = config.status_progression.projects
+
+// Get specific flow
+defaultTaskFlow = taskFlows.default_flow
+bugFixFlow = taskFlows.bug_fix_flow  // May not exist - check first
+
+// Get emergency and terminal statuses
+emergencyStatuses = taskFlows.emergency_transitions
+terminalStatuses = taskFlows.terminal_statuses
+```
+
+### When Explaining Tag Routing: Flow Mappings
+
+```javascript
+// Section 3: Flow mappings (when explaining tag-based routing)
+taskMappings = config.status_progression.tasks.flow_mappings
+featureMappings = config.status_progression.features.flow_mappings
+
+// Show user THEIR mappings, not assumed defaults
+"Your task flow mappings:
+- Tags [bug, bugfix, fix] → bug_fix_flow
+- Tags [documentation, docs] → documentation_flow
+- Default: default_flow"
+```
+
+### What NOT to Read
+
+**Don't read these sections** - not implemented or not used by this skill:
+- `parallelism` - Not implemented yet
+- `automation` - Not implemented yet
+- `complexity` - Not loaded by backend (referenced in docs only)
+- `feature_creation` - Not loaded by backend (referenced in docs only)
+- `dependencies` - Not implemented yet
+
+**Only read status_progression and status_validation sections.**
+
+---
+
+## Checking What Exists in User's Config
+
+**Never assume flows exist** - always check user's actual config:
+
+### Check Available Flows
+
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+
+// Get all task flows
+taskFlows = Object.keys(config.status_progression.tasks)
+  .filter(key => key.endsWith('_flow'))
+
+// Tell user what's configured
+"Your config has these task flows:
+- default_flow (always exists)
+- bug_fix_flow
+- documentation_flow
+- hotfix_flow
+- with_review
+
+You can create custom flows by adding them to your config.yaml"
+```
+
+### Check Flow Mappings
+
+```javascript
+// Get user's actual mappings
+taskMappings = config.status_progression.tasks.flow_mappings
+
+// Check if specific mapping exists
+hasBugMapping = taskMappings.some(m => m.tags.includes("bug"))
+
+if (!hasBugMapping) {
+  "No bug flow mapping in your config.
+  Tasks with 'bug' tag will use default_flow.
+
+  To add bug mapping, edit config.yaml:
+  flow_mappings:
+    - tags: [bug, bugfix, fix]
+      flow: bug_fix_flow"
+}
+```
+
+---
+
+## When Config Missing
+
+If `.taskorchestrator/config.yaml` doesn't exist:
+
+```javascript
+// Attempted to read config
+config = Read(".taskorchestrator/config.yaml")
+
+// File not found
+if (error) {
+  "No config found. StatusValidator using fallback mode:
+  - All enum statuses allowed
+  - No transition rules enforced
+  - No prerequisite validation
+
+  To enable config-driven validation:
+  1. Run setup_claude_orchestration tool
+  2. Creates .taskorchestrator/config.yaml
+  3. Customize rules as needed
+
+  Without config, status transitions rely only on enum validation."
+}
+```
+
+**Fallback behavior:**
+- StatusValidator allows any enum status
+- No flow sequences enforced
+- No prerequisite checking
+- Basic enum validation only
+
+---
+
+## Integration with Other Skills
+
+**Status Progression Skill works alongside:**
+
+### Feature Management Skill
+- Feature Management uses config for quality gates
+- Status Progression explains what those gates are
+- Complementary: Feature Management coordinates, Status Progression guides
+
+### Task Management Skill
+- Task Management uses config for execution planning
+- Status Progression explains workflow possibilities
+- Complementary: Task Management executes, Status Progression guides
+
+### Dependency Analysis Skill
+- Dependency Analysis complements prerequisite checking
+- Shows what's blocking tasks
+- Status Progression explains how blockers affect status transitions
+
+**Clear separation:**
+- Feature/Task Management Skills: Coordination and execution
+- Status Progression Skill: Workflow guidance and error interpretation
+- Dependency Analysis Skill: Blocker identification
+
+---
+
+## Customization Examples
+
+### Adding a Custom Flow
+
+**User wants research task flow (no testing needed):**
+
+```yaml
+# Edit .taskorchestrator/config.yaml
+status_progression:
+  tasks:
+    # Add new flow
+    research_task_flow:
+      - pending
+      - in-progress
+      - completed
+
+    # Add mapping
+    flow_mappings:
+      - tags: [research, spike, investigation]
+        flow: research_task_flow
+```
+
+**Result:** Tasks tagged with "research" skip testing and use simplified flow.
+
+### Changing Validation Rules
+
+**User wants flexible workflow (skip statuses allowed):**
+
+```yaml
+# Edit .taskorchestrator/config.yaml
+status_validation:
+  enforce_sequential: false  # Now can skip statuses
+  allow_backward: true       # Keep backward movement
+  allow_emergency: true
+  validate_prerequisites: true
+```
+
+**Result:** Can jump directly from pending → testing without going through in-progress.
+
+### Adding Emergency Transition
+
+**User wants "deferred" status accessible anytime:**
+
+```yaml
+# Edit .taskorchestrator/config.yaml
+status_progression:
+  tasks:
+    emergency_transitions:
+      - blocked
+      - on-hold
+      - cancelled
+      - deferred  # Add this
+```
+
+**Result:** Can move to deferred from any state (low-priority task postponed indefinitely).
+
+---
+
+## Summary
+
+**Progressive Loading Pattern:**
+1. User asks about configuration
+2. You load this file
+3. Show relevant section based on question
+4. Reference user's actual config for examples
+
+**Remember:**
+- Always read user's config.yaml before explaining rules
+- Config sections are user-defined and customizable
+- Only read status_progression and status_validation sections
+- Check what exists before referencing flows
+- Explain rules in terms of user's specific settings

skills/status-progression/examples.md

@@ -0,0 +1,485 @@
+# Status Progression - Flow Examples
+
+This file contains custom flow examples and tag-based selection patterns. Load this when users ask about workflow possibilities or custom flow creation.
+
+## Flows in Default Config (Starter Examples)
+
+**IF the user hasn't customized their config**, these flows exist:
+
+### Task Flows
+
+**default_flow:**
+```yaml
+- backlog            # Task in backlog, needs prioritization
+- pending            # Task ready, waiting to start
+- in-progress        # Actively being worked on
+- testing            # Implementation complete, running tests
+- completed          # Task complete
+```
+
+**bug_fix_flow:**
+```yaml
+- pending            # Bug reported, ready to fix (skip backlog for urgency)
+- in-progress        # Fixing bug
+- testing            # Testing fix
+- completed          # Bug fixed
+```
+
+**documentation_flow:**
+```yaml
+- pending
+- in-progress
+- in-review          # Documentation review (no code testing needed)
+- completed
+```
+
+**hotfix_flow:**
+```yaml
+- pending
+- in-progress
+- completed          # Emergency fixes, skip backlog and review
+```
+
+**with_review:**
+```yaml
+- backlog
+- pending
+- in-progress
+- in-review          # Awaiting code review
+- testing            # Review approved, testing
+- completed
+```
+
+### Feature Flows
+
+**default_flow:**
+```yaml
+- draft              # Initial draft, rough ideas
+- planning           # Define requirements, break into tasks
+- in-development     # Active implementation
+- testing            # All tasks complete, running tests
+- validating         # Tests passed, final validation
+- completed          # Feature complete and validated
+```
+
+**rapid_prototype_flow:**
+```yaml
+- draft
+- in-development     # Skip planning and testing for quick experiments
+- completed
+```
+
+**with_review_flow:**
+```yaml
+- draft
+- planning
+- in-development
+- testing
+- validating
+- pending-review     # Awaiting human approval
+- completed
+```
+
+### Project Flows
+
+**default_flow:**
+```yaml
+- planning           # Define scope and features
+- in-development     # Active development
+- completed          # Project finished
+- archived           # Archive for history
+```
+
+---
+
+## Example Custom Flows (What Users COULD Create)
+
+**These DON'T exist by default** - they show what's possible when users customize their config.
+
+### 1. Research Task Flow
+
+**Use case:** Research tasks, spikes, investigations that don't need testing
+
+```yaml
+research_task_flow:
+  - pending
+  - in-progress
+  - completed         # No testing needed for research
+
+flow_mappings:
+  - tags: [research, spike, investigation]
+    flow: research_task_flow
+```
+
+**Why this works:**
+- Research is exploratory, doesn't produce testable code
+- Skips testing gate entirely
+- Faster completion for non-code work
+
+**Example tasks:**
+- "Research authentication libraries"
+- "Investigate performance bottleneck"
+- "Spike: Feasibility of real-time sync"
+
+### 2. Compliance Review Flow
+
+**Use case:** Regulated features requiring legal/compliance approval
+
+```yaml
+compliance_review_flow:
+  - draft
+  - planning
+  - in-development
+  - testing
+  - validating
+  - pending-review    # Legal/compliance review gate
+  - completed
+
+flow_mappings:
+  - tags: [compliance, regulated, audit, hipaa, gdpr]
+    flow: compliance_review_flow
+```
+
+**Why this works:**
+- Adds formal approval gate before completion
+- Required for regulated industries (healthcare, finance)
+- Ensures compliance sign-off is documented
+
+**Example features:**
+- "HIPAA-compliant patient data storage"
+- "GDPR data export API"
+- "SOC 2 audit logging"
+
+### 3. Experiment Flow
+
+**Use case:** Experiments designed to fail fast without formal process
+
+```yaml
+experiment_flow:
+  - pending
+  - in-progress
+  - cancelled         # Most experiments fail - that's OK!
+  # OR
+  - completed         # Some succeed
+
+# No testing or review required - experiments are exploratory
+
+flow_mappings:
+  - tags: [experiment, try, explore]
+    flow: experiment_flow
+```
+
+**Why this works:**
+- Experiments are meant to fail fast
+- No formal testing/review overhead
+- Terminal states: cancelled (expected) or completed (rare success)
+
+**Example tasks:**
+- "Experiment: Can we use WebAssembly for this?"
+- "Try implementing with GraphQL instead"
+- "Explore alternative caching strategy"
+
+### 4. Staged Rollout Flow
+
+**Use case:** Gradual deployment with validation gates
+
+```yaml
+staged_rollout_flow:
+  - draft
+  - planning
+  - in-development
+  - testing
+  - validating
+  - deployed          # Custom intermediate status (if added to enum)
+  - completed
+
+flow_mappings:
+  - tags: [gradual-rollout, canary, phased-deploy]
+    flow: staged_rollout_flow
+```
+
+**Why this works:**
+- Adds explicit "deployed" state between validating and completed
+- Allows tracking deployment progress separately
+- Useful for canary deployments, feature flags
+
+**Note:** Requires adding "deployed" status to FEATURE enum (not in default)
+
+**Example features:**
+- "New recommendation algorithm (canary rollout)"
+- "Payment provider migration (phased)"
+
+### 5. Multi-Stage Review Flow
+
+**Use case:** Features requiring multiple approval stages (design, security, business)
+
+```yaml
+multi_review_flow:
+  - draft
+  - planning
+  - in-review          # Design review
+  - in-development
+  - testing
+  - validating
+  - pending-review     # Security/business review
+  - completed
+
+flow_mappings:
+  - tags: [high-risk, security-critical, business-critical]
+    flow: multi_review_flow
+```
+
+**Why this works:**
+- Two review gates: after planning (design) and before completion (security/business)
+- Catches issues early with design review
+- Final validation before production
+
+**Example features:**
+- "New authentication method"
+- "Payment processing changes"
+- "Data retention policy implementation"
+
+### 6. Simple Task Flow (Minimal Overhead)
+
+**Use case:** Trivial tasks that don't need backlog or testing
+
+```yaml
+simple_task_flow:
+  - pending
+  - in-progress
+  - completed
+
+flow_mappings:
+  - tags: [trivial, simple, quick-fix]
+    flow: simple_task_flow
+```
+
+**Why this works:**
+- Minimal workflow for tiny changes
+- Skips backlog (not worth prioritizing)
+- Skips testing (too small to warrant formal testing)
+
+**Example tasks:**
+- "Update copyright year"
+- "Fix typo in error message"
+- "Add tooltip to button"
+
+---
+
+## Tag-Based Flow Selection
+
+The `get_next_status` tool automatically selects workflows based on tags **IF** the user has flow_mappings configured.
+
+### How Tag Matching Works
+
+```javascript
+// get_next_status reads user's config and matches tags
+recommendation = get_next_status(
+  containerId="task-uuid",
+  containerType="task"
+)
+
+// Tool checks task tags → matches flow_mappings → returns appropriate flow
+// If tags: [bug, backend] → uses bug_fix_flow (IF that mapping exists in config)
+// If tags: [research] → uses research_task_flow (IF user created that flow)
+// If no match → uses default_flow
+```
+
+### Default Tag Mappings (IF User Hasn't Changed Config)
+
+**Task mappings:**
+```yaml
+flow_mappings:
+  - tags: [bug, bugfix, fix]
+    flow: bug_fix_flow
+  - tags: [documentation, docs]
+    flow: documentation_flow
+  - tags: [hotfix, emergency, critical]
+    flow: hotfix_flow
+  - tags: [needs-review, code-review]
+    flow: with_review
+```
+
+**Feature mappings:**
+```yaml
+flow_mappings:
+  - tags: [prototype, poc, spike]
+    flow: rapid_prototype_flow
+  - tags: [needs-review, stakeholder-approval]
+    flow: with_review_flow
+```
+
+### Custom Tag Mapping Examples
+
+**User's custom config could have:**
+```yaml
+# Tasks
+flow_mappings:
+  - tags: [research, spike]
+    flow: research_task_flow        # Custom flow user created
+  - tags: [compliance]
+    flow: compliance_review_flow    # Another custom flow
+  - tags: [experiment]
+    flow: experiment_flow
+  - tags: [trivial]
+    flow: simple_task_flow
+
+# Features
+flow_mappings:
+  - tags: [gradual-rollout, canary]
+    flow: staged_rollout_flow
+  - tags: [high-risk, security-critical]
+    flow: multi_review_flow
+```
+
+### Checking User's Actual Mappings
+
+**Always verify what the user has configured:**
+
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+
+// Get task flow mappings
+taskMappings = config.status_progression.tasks.flow_mappings
+// Show user THEIR mappings, not assumed defaults
+
+// Get feature flow mappings
+featureMappings = config.status_progression.features.flow_mappings
+
+// Tell user what's configured:
+"Your task flow mappings:
+- Tags [bug, bugfix, fix] → bug_fix_flow
+- Tags [research] → research_task_flow  (custom!)
+- Tags [experiment] → experiment_flow   (custom!)
+- Default: default_flow"
+```
+
+### Tag Matching Priority
+
+When a task/feature has multiple tags, the **first matching mapping** wins:
+
+```yaml
+flow_mappings:
+  - tags: [hotfix, emergency, critical]
+    flow: hotfix_flow               # Priority 1
+  - tags: [bug, bugfix, fix]
+    flow: bug_fix_flow              # Priority 2
+  - tags: [needs-review]
+    flow: with_review               # Priority 3
+```
+
+**Example:** Task with tags `[hotfix, bug]`
+- Matches mapping 1 (hotfix) → uses `hotfix_flow`
+- Does NOT use `bug_fix_flow` (even though "bug" tag is present)
+
+**Best practice:** Order mappings from most specific to least specific.
+
+---
+
+## Creating Custom Flows - Best Practices
+
+### 1. Start with a Use Case
+
+**Ask:**
+- What makes this workflow different from default?
+- What gates can I skip? (backlog, testing, review)
+- What gates do I need to add? (compliance, multi-stage review)
+
+### 2. Keep Flows Linear
+
+**Do:**
+```yaml
+research_task_flow:
+  - pending
+  - in-progress
+  - completed
+```
+
+**Don't:**
+```yaml
+research_task_flow:
+  - pending
+  - in-progress
+  - in-progress    # ❌ Duplicates don't work with enforce_sequential
+  - completed
+```
+
+**Why:** With `enforce_sequential: true`, duplicate statuses break validation. Use backward movement instead.
+
+### 3. Use Backward Movement for Iterations
+
+**Instead of duplicating statuses, enable backward movement:**
+
+```yaml
+status_validation:
+  allow_backward: true  # Enable this
+```
+
+**Then flow becomes:**
+```yaml
+with_review:
+  - pending
+  - in-progress
+  - in-review
+  - testing
+  - completed
+
+# Iteration: in-review → in-progress (backward) → in-review (forward)
+# Unlimited iterations without duplicate statuses
+```
+
+### 4. Tag Conventions
+
+**Use consistent tag patterns:**
+- Workflow type: `research`, `experiment`, `compliance`
+- Urgency: `hotfix`, `emergency`, `critical`
+- Process: `needs-review`, `stakeholder-approval`
+- Domain: `backend`, `frontend`, `database`
+
+**Combine tags for specificity:**
+- Task with `[bug, backend]` → bug fix flow, backend specialist
+- Task with `[research, frontend]` → research flow, frontend context
+
+### 5. Document Your Custom Flows
+
+**Add comments to config.yaml:**
+```yaml
+# Research task flow - for spikes and investigations that don't produce testable code
+# Created: 2024-01-15
+# Use for: Technical research, library evaluations, architecture spikes
+research_task_flow:
+  - pending
+  - in-progress
+  - completed
+```
+
+---
+
+## When to Create a Custom Flow
+
+**Create custom flow when:**
+- ✅ Default flow has unnecessary gates for specific work types (research doesn't need testing)
+- ✅ Need additional approval gates (compliance review, multi-stage approval)
+- ✅ Want faster path for specific scenarios (hotfix skips backlog and review)
+- ✅ Pattern repeats frequently (if you keep skipping same gates, formalize it)
+
+**Don't create custom flow when:**
+- ❌ One-off exception (use emergency transitions instead)
+- ❌ Only difference is number of iterations (use backward movement)
+- ❌ Can be handled by tags alone (tags don't require new flow)
+
+---
+
+## Summary
+
+**Progressive Loading Pattern:**
+1. User asks: "What custom flows can I create?"
+2. You load this file
+3. Show relevant examples based on their context
+4. Guide them to update their config.yaml
+
+**Remember:**
+- All examples here are POSSIBILITIES, not defaults
+- Users must add flows to their config.yaml
+- Always check user's actual config before referencing flows
+- Use tag mappings to automatically route to appropriate flows

skills/status-progression/validation-errors.md

@@ -0,0 +1,579 @@
+# Status Progression - Validation Errors
+
+This file contains common StatusValidator errors, prerequisite failures, and fix patterns. Load this when users encounter validation errors or ask about validation rules.
+
+## Common Validation Rules
+
+**From user's config.yaml:**
+
+```yaml
+status_validation:
+  enforce_sequential: true/false    # Must follow flow order step-by-step?
+  allow_backward: true/false        # Can move backwards in flow?
+  allow_emergency: true/false       # Can jump to blocked/cancelled from any state?
+  validate_prerequisites: true/false # Check business rules before transitions?
+```
+
+**How to check user's settings:**
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+rules = config.status_validation
+
+// Explain their specific configuration
+"Your config validation rules:
+- enforce_sequential: {rules.enforce_sequential}
+- allow_backward: {rules.allow_backward}
+- allow_emergency: {rules.allow_emergency}
+- validate_prerequisites: {rules.validate_prerequisites}"
+```
+
+---
+
+## Flow Validation Errors
+
+### Error: "Cannot skip statuses. Must transition through: in-progress"
+
+**Meaning:** User tried to skip a status in the flow with `enforce_sequential: true`
+
+**Example:**
+```
+Current: pending
+Tried: testing
+Error: Can't skip in-progress
+```
+
+**Cause:** Config has `enforce_sequential: true`
+
+**Fix Options:**
+
+**Option 1: Follow sequential flow**
+```javascript
+// Move step-by-step through the flow
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="in-progress")  // First step
+
+// Later:
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="testing")      // Next step
+```
+
+**Option 2: Change config to allow skipping**
+```yaml
+# Edit .taskorchestrator/config.yaml
+status_validation:
+  enforce_sequential: false  # Now can skip statuses
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because YOUR config has:
+  enforce_sequential: true
+
+You tried: pending → testing (skipped in-progress)
+
+Your options:
+1. Follow sequential flow: pending → in-progress → testing
+2. Change your config: Set enforce_sequential: false in config.yaml
+
+Recommended:
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="in-progress")
+```
+
+### Error: "Backward transitions not allowed. Cannot move from testing to in-progress"
+
+**Meaning:** User tried to move backwards with `allow_backward: false`
+
+**Example:**
+```
+Current: testing
+Tried: in-progress (backward)
+Error: Backward movement disabled
+```
+
+**Cause:** Config has `allow_backward: false`
+
+**Fix Options:**
+
+**Option 1: Move forward only**
+```javascript
+// Can't go back - must progress forward or use emergency transition
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="completed")  // Forward
+
+// OR use emergency transition:
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="cancelled")  // Emergency (if allow_emergency: true)
+```
+
+**Option 2: Enable backward movement**
+```yaml
+# Edit .taskorchestrator/config.yaml
+status_validation:
+  allow_backward: true  # Now can move backwards for rework
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because YOUR config has:
+  allow_backward: false
+
+You tried: testing → in-progress (backward movement)
+
+Your options:
+1. Move forward only: testing → completed
+2. Use emergency transition: testing → cancelled/on-hold
+3. Change your config: Set allow_backward: true in config.yaml
+
+Why backward is useful:
+- Code review requested changes
+- Found bugs during testing
+- Iterative development
+```
+
+### Error: "Status not in defined flow: archived"
+
+**Meaning:** User tried to transition to a status not in their current flow
+
+**Example:**
+```
+Current flow: bug_fix_flow [pending, in-progress, testing, completed]
+Tried: archived
+Error: archived not in bug_fix_flow
+```
+
+**Cause:** The flow being used doesn't include the target status
+
+**Fix Options:**
+
+**Option 1: Use emergency transition (if configured)**
+```javascript
+// Check if status is in emergency_transitions
+config = Read(".taskorchestrator/config.yaml")
+emergencyStatuses = config.status_progression.tasks.emergency_transitions
+
+// If archived is emergency status, it can be used from any state
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="archived")
+```
+
+**Option 2: Use status from current flow**
+```javascript
+// Use terminal status from current flow
+manage_container(operation="setStatus", containerType="task",
+  id="...", status="completed")  // Terminal status in bug_fix_flow
+```
+
+**Option 3: Change task tags to use different flow**
+```javascript
+// Change tags to select flow that includes desired status
+manage_container(operation="update", containerType="task",
+  id="...", tags="backend")  // Uses default_flow which has more statuses
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Your task uses: bug_fix_flow
+- bug_fix_flow doesn't include: archived
+- archived is not in emergency_transitions
+
+Your options:
+1. Use status from bug_fix_flow: completed
+2. Add archived to emergency_transitions in config
+3. Change task tags to use flow that includes archived
+```
+
+---
+
+## Prerequisite Validation Errors
+
+### Error: "Feature must have at least 1 task before IN_DEVELOPMENT"
+
+**Meaning:** StatusValidator checked prerequisites, found 0 tasks when transitioning feature to in-development
+
+**Cause:** Config has `validate_prerequisites: true` and feature transition rules require tasks
+
+**Fix:**
+```javascript
+// Create at least one task for the feature
+manage_container(operation="create", containerType="task",
+  featureId="feature-uuid",
+  title="Implement X",
+  description="...",
+  tags="backend")
+
+// Then retry feature status transition
+manage_container(operation="setStatus", containerType="feature",
+  id="feature-uuid", status="in-development")
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Your config requires features to have tasks before IN_DEVELOPMENT
+- Current task count: 0
+- Required: At least 1
+
+Fix:
+1. Create at least one task for this feature
+2. Then retry the status transition
+
+This prevents empty features from moving to development.
+```
+
+### Error: "Cannot transition to COMPLETED: 1 task(s) not completed"
+
+**Meaning:** Feature has incomplete tasks, can't mark feature complete
+
+**Cause:** Config requires all tasks completed before feature completion
+
+**Check current state:**
+```javascript
+overview = query_container(operation="overview", containerType="feature",
+  id="feature-uuid")
+
+// Returns task counts by status
+overview.taskCounts.byStatus
+// Example: {completed: 8, in-progress: 1, pending: 0}
+```
+
+**Fix Options:**
+
+**Option 1: Complete remaining tasks**
+```javascript
+// Find incomplete tasks
+tasks = query_container(operation="search", containerType="task",
+  featureId="feature-uuid",
+  status="!completed")
+
+// Complete each task
+manage_container(operation="setStatus", containerType="task",
+  id="task-uuid", status="completed")
+```
+
+**Option 2: Cancel unnecessary tasks**
+```javascript
+// Cancel tasks that are no longer needed
+manage_container(operation="setStatus", containerType="task",
+  id="task-uuid", status="cancelled")
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Your config requires ALL tasks completed before feature completion
+- Status breakdown: 8 completed, 1 in-progress, 0 pending
+- Incomplete tasks: 1
+
+Fix options:
+1. Complete remaining task(s)
+2. Cancel tasks that are no longer needed
+
+Task completion ensures feature is fully implemented.
+```
+
+### Error: "Task summary must be 300-500 characters (current: 50)"
+
+**Meaning:** Task summary too short for completion
+
+**Cause:** Prerequisite validation requires summary field populated with 300-500 chars
+
+**Fix:**
+```javascript
+// Update task summary before marking complete
+manage_container(operation="update", containerType="task",
+  id="task-uuid",
+  summary="Implemented authentication API using JWT tokens. Added /login and /refresh endpoints with rate limiting. Created middleware for token validation. Updated user schema to store refresh tokens. All tests passing with 95% coverage. Documentation updated in API reference.")
+
+// Then mark complete
+manage_container(operation="setStatus", containerType="task",
+  id="task-uuid", status="completed")
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Your config requires task summary for completion
+- Current length: 50 characters
+- Required: 300-500 characters
+
+Fix:
+Update task summary with comprehensive description:
+- What was implemented
+- Technical approach
+- Testing results
+- Any important notes
+
+Summary captures work done for future reference.
+```
+
+### Error: "Cannot start task: 2 blocking dependencies not completed"
+
+**Meaning:** Task has incomplete blocking dependencies
+
+**Cause:** Task has BLOCKS dependencies that must complete first
+
+**Check dependencies:**
+```javascript
+deps = query_dependencies(taskId="task-uuid", direction="incoming",
+  type="BLOCKS", includeTaskInfo=true)
+
+// Returns blocking tasks
+deps.incoming.forEach(dep => {
+  console.log(`Blocked by: ${dep.fromTask.title} (${dep.fromTask.status})`)
+})
+```
+
+**Fix:**
+```javascript
+// Complete blocking tasks first
+manage_container(operation="setStatus", containerType="task",
+  id="blocking-task-uuid", status="completed")
+
+// Then start this task
+manage_container(operation="setStatus", containerType="task",
+  id="task-uuid", status="in-progress")
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Task has 2 blocking dependencies
+- Blockers must complete before this task can start
+
+Blocking tasks:
+1. "Database schema migration" (in-progress)
+2. "API authentication design" (pending)
+
+Fix:
+Complete blocking tasks first, then retry this task.
+
+Dependencies ensure correct order of execution.
+```
+
+---
+
+## Emergency Transition Handling
+
+### Using Emergency Transitions
+
+**What are emergency transitions:**
+- Statuses accessible from ANY state
+- Bypass normal flow rules
+- Used for real-world interruptions
+
+**Common emergency statuses:**
+```yaml
+emergency_transitions:
+  - blocked      # External blocker
+  - on-hold      # Paused temporarily
+  - cancelled    # No longer needed
+  - deferred     # Postponed indefinitely
+  - archived     # Archive for history
+```
+
+**Check if status is emergency:**
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+emergencyStatuses = config.status_progression.tasks.emergency_transitions
+
+if (emergencyStatuses.includes("blocked")) {
+  // Can transition to blocked from any state
+  manage_container(operation="setStatus", containerType="task",
+    id="...", status="blocked")
+}
+```
+
+**When to use emergency transitions:**
+
+**blocked:**
+- External API not available
+- Dependency on another team's work
+- Technical blocker preventing progress
+
+**on-hold:**
+- Priority changed, pausing work temporarily
+- Waiting for stakeholder decision
+- Resource constraints
+
+**cancelled:**
+- Requirements changed, task no longer needed
+- Duplicate work discovered
+- Feature cancelled
+
+**deferred:**
+- Nice-to-have, postponing indefinitely
+- Low priority, may revisit later
+
+**Explain to user:**
+```
+Your task is blocked by external API unavailability.
+
+Use emergency transition to: blocked
+in-progress → blocked (emergency - can happen from any state)
+
+Emergency transitions exist for real-world interruptions:
+- blocked: External dependency or technical issue
+- on-hold: Priority shift, paused temporarily
+- cancelled: Task no longer needed
+- deferred: Postponed indefinitely
+
+These bypass normal flow rules because problems don't follow workflows.
+```
+
+---
+
+## Terminal Status Handling
+
+### What are Terminal Statuses
+
+**Terminal statuses:**
+- End states in the workflow
+- No further progression possible
+- Work is finished (successfully or unsuccessfully)
+
+**Common terminal statuses:**
+```yaml
+terminal_statuses:
+  - completed     # Successfully finished
+  - cancelled     # Explicitly cancelled
+  - deferred      # Postponed indefinitely
+  - archived      # Archived for history
+```
+
+### Error: "Cannot transition from terminal status: completed"
+
+**Meaning:** Tried to change status from a terminal state
+
+**Example:**
+```
+Current: completed
+Tried: in-progress
+Error: Cannot progress from terminal status
+```
+
+**Why this happens:**
+- Terminal statuses mark work as finished
+- No valid next status exists
+- Prevents accidental status changes on completed work
+
+**Fix Options:**
+
+**Option 1: Work is actually incomplete - reopen**
+```javascript
+// If work needs to be redone, create new task
+manage_container(operation="create", containerType="task",
+  featureId="...",
+  title="Rework: [original task]",
+  description="Additional work discovered after completion...",
+  tags="backend")
+```
+
+**Option 2: Work is complete - no fix needed**
+```
+Work is correctly marked as completed.
+If you need to make changes, create a new task for the additional work.
+Completed tasks should remain completed for historical accuracy.
+```
+
+**Explain to user:**
+```
+StatusValidator blocked this because:
+- Task is in terminal status: completed
+- Terminal statuses cannot transition further
+- Work is marked as finished
+
+If you need to:
+- Make small changes: Create new task "Update X"
+- Major rework: Create new task "Rework X"
+- Fix bug: Create bug fix task
+
+Preserving completed status maintains accurate history.
+```
+
+---
+
+## Config-Specific Error Patterns
+
+### Checking User's Config for Error Context
+
+**Always read user's actual config when interpreting errors:**
+
+```javascript
+config = Read(".taskorchestrator/config.yaml")
+
+// Get validation rules
+rules = config.status_validation
+
+// Get current flow
+taskFlows = config.status_progression.tasks
+currentFlow = taskFlows.default_flow  // Or bug_fix_flow, etc.
+
+// Get emergency transitions
+emergencyStatuses = config.status_progression.tasks.emergency_transitions
+
+// Explain in context of THEIR config
+"StatusValidator blocked this because YOUR config has:
+  enforce_sequential: {rules.enforce_sequential}
+  allow_backward: {rules.allow_backward}
+
+Your current flow: {currentFlow}
+Emergency transitions available: {emergencyStatuses}"
+```
+
+### Config Customization Impact
+
+**Different configs = different errors:**
+
+**Strict config:**
+```yaml
+status_validation:
+  enforce_sequential: true
+  allow_backward: false
+  allow_emergency: false
+  validate_prerequisites: true
+```
+**Result:** More errors, stricter process
+
+**Lenient config:**
+```yaml
+status_validation:
+  enforce_sequential: false
+  allow_backward: true
+  allow_emergency: true
+  validate_prerequisites: false
+```
+**Result:** Fewer errors, flexible process
+
+**Explain tradeoffs:**
+```
+Your config is strict (enforce_sequential: true, allow_backward: false).
+
+This means:
+✅ Enforces consistent process
+✅ Prevents accidental status skipping
+❌ Less flexibility for iterations
+❌ More validation errors
+
+You can customize this by editing .taskorchestrator/config.yaml
+```
+
+---
+
+## Summary
+
+**Progressive Loading Pattern:**
+1. User encounters StatusValidator error
+2. You load this file
+3. Find matching error pattern
+4. Read user's config for context
+5. Explain error in terms of THEIR settings
+6. Provide fix options specific to their situation
+
+**Remember:**
+- Always read user's config.yaml for context
+- Explain errors in terms of their specific settings
+- Provide multiple fix options when possible
+- Explain WHY the rule exists (prerequisite purpose)
+- Validation errors are FEATURES, not bugs - they prevent problems