task-status-sync

Parse the intended change:

Extract from Edit/Write tool parameters:

• TaskId: T### from checkbox pattern or ✅ marker
• NewStatus: Infer from checkbox ([X] = completed, [~] = in-progress, [ ] = pending)
• Notes: Extract from NOTES.md addition or Edit context
• ErrorMessage: Extract if marking failed

Generate equivalent command:

// Pseudo-logic
if (newStatus === 'X' || intent === 'mark complete') {
  command = 'mark-done-with-notes'
  params = {
    TaskId: extractedTaskId,
    Notes: extractedNotes || "",
    Duration: "est"  // Default if not specified
  }
}
else if (newStatus === '~' || intent === 'mark in progress') {
  command = 'mark-in-progress'
  params = { TaskId: extractedTaskId }
}
else if (intent === 'mark failed' || errorMessage present) {
  command = 'mark-failed'
  params = {
    TaskId: extractedTaskId,
    ErrorMessage: extractedErrorMessage
  }
}

Validation before execution:

Check that:

• TaskId exists in tasks.md
• Status transition is valid (pending → in-progress → completed)
• Required fields present (e.g., ErrorMessage for mark-failed)

If validation fails, auto-fix where possible:

• Missing TaskId → Extract from context or ask user
• Invalid transition → Warn and suggest correct flow
• Missing ErrorMessage → Prompt for details

See references/conversion-logic.md for detailed conversion rules.

# Platform detection
if (platform === 'win32') {
  script = '.spec-flow/scripts/bash/task-tracker.sh'  # Uses WSL or delegates to PS
} else if (platform === 'linux' || platform === 'darwin') {
  script = '.spec-flow/scripts/bash/task-tracker.sh'
}

# Execute with Bash tool
Bash(`${script} ${command} -TaskId ${TaskId} [additional params] -Json`)

{
  "Success": true,
  "TaskId": "T001",
  "Message": "Task T001 marked complete in both tasks.md and NOTES.md",
  "TasksFile": "specs/001-feature/tasks.md",
  "NotesFile": "specs/001-feature/NOTES.md",
  "PhaseMarker": "[RED]"
}

✅ TASK STATUS UPDATED ATOMICALLY

Task T001 marked complete:
  - tasks.md: Updated checkbox to [X]
  - NOTES.md: Added completion marker
  - Phase: [RED] (TDD red phase)

Files synchronized:
  - specs/001-feature/tasks.md
  - specs/001-feature/NOTES.md

Next steps:
  - Run: task-tracker.sh next
  - Continue with T002

❌ BAD (manual edit to tasks.md):
- [X] T001 Create database schema

✅ GOOD (task-tracker command):
task-tracker.sh mark-done-with-notes -TaskId T001 -Notes "Created schema"

❌ BAD (manual edit to NOTES.md):
✅ T001: Created database schema

✅ GOOD (task-tracker handles NOTES.md):
task-tracker.sh mark-done-with-notes -TaskId T001
# Atomically updates both files

❌ BAD (tasks.md says pending, NOTES.md says complete):
tasks.md: - [ ] T001 Create schema
NOTES.md: ✅ T001: Created schema

✅ GOOD (atomic update ensures consistency):
Both files updated simultaneously via task-tracker

❌ BAD (pending → completed without in-progress):
Can lose tracking of what's actively being worked on

✅ GOOD (mark in-progress first):
1. task-tracker.sh mark-in-progress -TaskId T001
2. [implement task]
3. task-tracker.sh mark-done-with-notes -TaskId T001

❌ BAD (no evidence of completion):
✅ T001 - est (timestamp)

✅ GOOD (include evidence, coverage, commit):
✅ T001: Created Message model - 15min (2025-11-19 10:30)
  - Evidence: pytest: 25/25 passing
  - Coverage: 92% (+8%)
  - Committed: abc123