Initial commit

2025-11-30 08:29:28 +08:00
commit 87c03319a3
50 changed files with 21409 additions and 0 deletions
--- a/skills/status-progression/validation-errors.md
+++ b/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