task-status-sync

<objective> Maintain atomic synchronization between tasks.md checkboxes and NOTES.md completion markers by enforcing task-tracker command usage and preventing manual file edits that cause data inconsistencies. </objective>

<quickstart> <enforcementmodel> 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>

<tasktrackercommands> 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](references/task-tracker-api.md) for complete API reference. </tasktrackercommands> </quick_start>

<workflow> <detection_phase> 1. Monitor Tool Usage

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:

• oldstring: "- [ ] T001" → newstring: "- [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](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](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](references/task-tracker-api.md) - Complete task-tracker command reference with examples
• [references/conversion-logic.md](references/conversion-logic.md) - Manual edit → task-tracker command conversion rules
• [references/validation-rules.md](references/validation-rules.md) - Task status validation and auto-fix logic
• [references/file-formats.md](references/file-formats.md) - tasks.md and NOTES.md structure and patterns

</reference_guides>