stack/docs/claude/task-tracking.md

# Autonomous Task Orchestration

> Load this guide when orchestrating autonomous task completion via `docs/tasks.md`.

## Ownership

**The orchestrator is the sole writer of `docs/tasks.md`.** Worker agents execute tasks and report results — they never read or modify the tracking file.

## Schema Reference

| Column         | Format                                   | Purpose                                     |
| -------------- | ---------------------------------------- | ------------------------------------------- |
| `id`           | `MS-{CAT}-{NNN}`                         | Unique task ID                              |
| `status`       | `not-started` \| `in-progress` \| `done` | Current state                               |
| `description`  | Free text                                | What to do (inline, concise)                |
| `issue`        | `#NNN` or empty                          | Gitea issue for requirements context        |
| `repo`         | Workspace name                           | `api`, `web`, `orchestrator`, `coordinator` |
| `branch`       | Branch name                              | Git branch for this work                    |
| `depends_on`   | Comma-separated IDs                      | Must complete before this task starts       |
| `blocks`       | Comma-separated IDs                      | Tasks waiting on this one                   |
| `agent`        | Agent identifier                         | Who is executing                            |
| `started_at`   | ISO 8601                                 | When work began                             |
| `completed_at` | ISO 8601                                 | When work finished                          |
| `estimate`     | `5K`, `40K`                              | Predicted token usage                       |
| `used`         | `4.2K`, `38.5K`                          | Actual token usage (fill on completion)     |

**Category prefixes:** `SEC` (security), `HIGH` (high priority), `CQ` (code quality), `TEST` (test coverage)

## Orchestrator Core Loop

```
1. git pull --rebase
2. Read docs/tasks.md
3. Find next task: status=not-started AND all depends_on are done
4. If no task available:
   - All done? → Report success, STOP
   - Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent, started_at
6. Spawn worker agent (Task tool) with task details from the row
7. Wait for worker completion
8. Parse worker result (JSON)
9. Update tasks.md: status=done/failed, completed_at, used
10. Commit + push: git add docs/tasks.md && git commit && git push
11. Check context usage
12. If >= 60%: Compact (see below), then go to step 1
13. If < 60%: Go to step 1
```

## Worker Prompt Template

The orchestrator constructs this prompt from the task row and passes it to a worker agent via the Task tool:

````markdown
## Task Assignment: {id}

**Description:** {description}
**Repository:** /home/localadmin/src/mosaic-stack/apps/{repo}
**Branch:** {branch}

**Reference Report:** See `docs/reports/codebase-review-2026-02-05/` for detailed findings.

## Workflow

1. Checkout branch: `git checkout {branch} || git checkout -b {branch} develop && git pull`
2. Implement the fix following existing code patterns
3. Run quality gates (ALL must pass):
   ```bash
   pnpm lint
   pnpm typecheck
   pnpm test
   ```
4. If gates fail: Fix and retry. Do NOT report success with failures.
5. Commit: `git commit -m "fix({id}): brief description"`
6. Push: `git push origin {branch}`
7. Report result as JSON (see format below)

## Git Scripts (for issue/PR/milestone operations, NOT raw tea/gh)

~/.claude/scripts/git/issue-view.sh -i {N}
~/.claude/scripts/git/pr-create.sh -t "Title" -b "Desc" -B develop

# Standard git commands (pull, commit, push, checkout) are fine

## Result Format (MANDATORY)

End your response with this JSON block:

```json
{
  "task_id": "{id}",
  "status": "success|failed",
  "used": "5.2K",
  "commit_sha": "abc123",
  "notes": "Brief summary of what was done"
}
```

## Rules

- DO NOT modify docs/tasks.md
- DO NOT claim other tasks
- Complete this single task, report results, done
````

## Compaction Protocol

**Threshold:** 60% context usage

**Why 60%?** System overhead is ~26% (prompts, tools, CLAUDE.md). Real capacity is ~74%. Triggering at 60% means ~81% actual usage — safe margin before the 91-95% emergency wall.

**After completing each task:**

1. Check context usage
2. If < 60%: Continue to next task
3. If >= 60%: Compact before next task

**Compaction steps:**

1. Update docs/tasks.md with all current progress
2. Commit + push tasks.md
3. Summarize: completed tasks, quality status, remaining queue
4. Clear detailed worker outputs and execution history
5. Resume with next unblocked task

**Compaction does NOT require user permission.**

**Template:**

```
Session Summary (Compacting at 60%):

Completed: MS-SEC-001 (12K), MS-SEC-002 (8K), MS-SEC-003 (10K)
Quality: All tests passing, zero regressions
Remaining: MS-SEC-004 (ready), MS-SEC-005 through MS-SEC-010, Phase 2-4 tasks
Next: MS-SEC-004
```

**Expected:** Context drops from 60% → ~25-30%.

## Error Handling

**Quality gates fail:**

1. Update tasks.md: status remains `in-progress`, add failure notes
2. Re-spawn worker with error context, or mark `failed` and move on
3. If failed task blocks others: Report deadlock, STOP

**Worker reports blocker:**

1. Update tasks.md: note the blocker
2. Skip to next unblocked task if possible
3. If all remaining tasks blocked: Report, STOP

**Git push conflict:**

1. `git pull --rebase`
2. If auto-resolves: push again
3. If conflict on tasks.md: Report, STOP (human resolves)

## Stopping Criteria

**ONLY stop if:**

1. All tasks in docs/tasks.md are `done`
2. Critical blocker preventing progress (document and alert)
3. Absolute context limit reached AND cannot compact further

**DO NOT stop to ask "should I continue?"** — the answer is always YES.

## Phase Structure

**Phase 1 - Critical Security (MS-SEC-001 through MS-SEC-010):**

- Authentication, XSS, error handling, OIDC validation
- Must complete before Phase 2

**Phase 2 - High Security (MS-HIGH-001 through MS-HIGH-006):**

- CSRF, mock data removal, rate limiting, container hardening
- Must complete before Phase 3

**Phase 3 - Code Quality (MS-CQ-001 through MS-CQ-007):**

- Memory leaks, stale closures, boolean bugs, atomic operations
- Must complete before Phase 4

**Phase 4 - Test Coverage (MS-TEST-001 through MS-TEST-005):**

- Critical service tests, widget tests, coverage investigation
- Final verification gate