task-status-sync

<quick_start> <enforcement_model> Intercept and convert manual edits to task-tracker commands:

1. •Detect attempt: Monitor for Edit/Write tool usage on NOTES.md or tasks.md
2. •Extract intent: Parse what change the user/Claude wants to make
3. •Convert to command: Generate equivalent task-tracker command
4. •Execute atomically: Run task-tracker to update both files simultaneously
5. •Provide feedback: Explain the conversion and show the result

Example workflow:

User: "Mark T001 as completed"

❌ BLOCKED: Direct edit to tasks.md
✅ AUTO-CONVERTED: .spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes -TaskId T001

Result:
- tasks.md: - [X] T001 Create database schema
- NOTES.md: ✅ T001: Create database schema - est (2025-11-19 10:30)

</enforcement_model>

<allowed_operations> ✅ Permitted (read-only):

• •Read NOTES.md to understand progress
• •Read tasks.md to see task list
• •Read error-log.md to diagnose failures

✅ Permitted (through task-tracker):

• •Mark tasks complete: mark-done-with-notes
• •Mark tasks in progress: mark-in-progress
• •Mark tasks failed: mark-failed
• •Sync status: sync-status
• •Get next task: next
• •Get summary: summary
• •Validate: validate

❌ Blocked (auto-converted):

• •Direct Edit/Write to tasks.md
• •Direct Edit/Write to NOTES.md
• •Manual checkbox changes ([ ] → [X])
• •Manual completion markers (✅ T001) </allowed_operations>

<task_tracker_commands> Available task-tracker.sh / task-tracker.ps1 actions:

# Get current status
.spec-flow/scripts/bash/task-tracker.sh status -Json

# Mark task completed with full details
.spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes \
  -TaskId T001 \
  -Notes "Created Message model with validation" \
  -Evidence "pytest: 25/25 passing" \
  -Coverage "92% (+8%)" \
  -CommitHash "abc123" \
  -Duration "15min"

# Mark task in progress
.spec-flow/scripts/bash/task-tracker.sh mark-in-progress -TaskId T002

# Mark task failed
.spec-flow/scripts/bash/task-tracker.sh mark-failed \
  -TaskId T003 \
  -ErrorMessage "Tests failing: ImportError on MessageService"

# Sync tasks.md to NOTES.md (migration utility)
.spec-flow/scripts/bash/task-tracker.sh sync-status

# Get next available task
.spec-flow/scripts/bash/task-tracker.sh next -Json

# Get phase-wise summary
.spec-flow/scripts/bash/task-tracker.sh summary -Json

# Validate task file structure
.spec-flow/scripts/bash/task-tracker.sh validate -Json

See references/task-tracker-api.md for complete API reference. </task_tracker_commands> </quick_start>

Watch for these patterns that indicate task status updates:

Direct file edits:

• •Edit(file_path: "*/tasks.md", ...)
• •Edit(file_path: "*/NOTES.md", ...)
• •Write(file_path: "*/tasks.md", ...)
• •Write(file_path: "*/NOTES.md", ...)

Verbal indicators:

• •"Mark T001 as complete"
• •"Update task status for T002"
• •"Task T003 is done"
• •"Completed T004"
• •"T005 failed"

Checkbox change patterns:

• •old_string: "- [ ] T001" → new_string: "- [X] T001"
• •Adding ✅ markers to NOTES.md manually </detection_phase>

<interception_phase> 2. Intercept and Block Manual Edits

When Edit/Write detected on tasks.md or NOTES.md:

⛔ MANUAL EDIT BLOCKED

File: specs/001-feature/tasks.md
Attempted change: Mark T001 as [X] completed

❌ Reason: Manual edits break atomic sync between tasks.md and NOTES.md

✅ Solution: Use task-tracker command instead

Auto-converting to:
  .spec-flow/scripts/bash/task-tracker.sh mark-done-with-notes -TaskId T001

This atomically updates:
  - tasks.md checkbox: - [X] T001
  - NOTES.md marker: ✅ T001: ... - est (2025-11-19 10:30)
  - Progress summary in tasks.md (if update-tasks-summary.ps1 exists)

Do NOT execute the manual edit. Instead, proceed to conversion phase. </interception_phase>

<conversion_phase> 3. Convert Manual Edit to Task-Tracker Command

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. </conversion_phase>

<execution_phase> 4. Execute Task-Tracker Command

# 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`)

Parse JSON output:

{
  "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]"
}

Provide feedback:

✅ 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

</execution_phase>

<validation_phase> 5. Validate Task-Tracker Usage

Common mistakes to auto-fix:

TDD validation:

Check if test task completed before implementation:

• •If marking T002 (implement) complete but T001 (test) is pending → warn
• •Recommendation: "Complete T001 (test) before T002 (implement) for TDD"

Parallel safety:

• •If more than 2 tasks in-progress → warn: "Exceeds parallel limit (2)"
• •If file path conflicts detected → block: "T002 and T003 both modify app.py"

See references/validation-rules.md for complete validation logic. </validation_phase> </workflow>

<anti_patterns> Avoid these mistakes that break sync:

1. Manual checkbox edits

❌ 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"

2. Adding NOTES.md markers manually

❌ 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

3. Inconsistent states

❌ 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

4. Skipping in-progress marker

❌ 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

5. Missing task completion evidence

❌ 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

</anti_patterns>

<success_criteria> Task status sync is working correctly when:

• •✓ All task completions use task-tracker commands
• •✓ tasks.md checkboxes and NOTES.md markers are always synchronized
• •✓ No manual edits to tasks.md or NOTES.md occur
• •✓ Attempted manual edits are auto-converted to task-tracker commands
• •✓ Task-tracker validation catches and fixes common mistakes
• •✓ TDD flow is enforced (tests before implementation)
• •✓ Parallel task limit (2) is respected
• •✓ File path conflicts are detected and prevented
• •✓ Error log entries are created for failed tasks
• •✓ Progress summary stays updated with velocity metrics

Detection working when:

• •Edit/Write attempts to tasks.md are intercepted
• •Verbal task completion mentions are recognized
• •Checkbox change patterns are detected
• •Auto-conversion generates correct task-tracker commands

Validation working when:

• •Invalid task IDs are caught and corrected
• •Invalid status transitions are prevented or guided
• •TDD violations are warned
• •Parallel safety limits are enforced </success_criteria>

<reference_guides> For detailed implementation and troubleshooting:

• •references/task-tracker-api.md - Complete task-tracker command reference with examples
• •references/conversion-logic.md - Manual edit → task-tracker command conversion rules
• •references/validation-rules.md - Task status validation and auto-fix logic
• •references/file-formats.md - tasks.md and NOTES.md structure and patterns </reference_guides>