bootstrap/guides/orchestrator.md

# Autonomous Orchestrator Guide

> Load this guide when orchestrating autonomous task completion across any project.

## Overview

The orchestrator **cold-starts** on any project with just a review report location and minimal kickstart. It autonomously:
1. Parses review reports to extract findings
2. Categorizes findings into phases by severity
3. Estimates token usage per task
4. Creates Gitea issues (phase-level)
5. Bootstraps `docs/tasks.md` from scratch
6. Coordinates completion using worker agents

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

---

## Orchestrator Boundaries (CRITICAL)

**The orchestrator NEVER:**
- Edits source code directly (*.ts, *.tsx, *.js, *.py, etc.)
- Runs quality gates itself (that's the worker's job)
- Makes commits containing code changes
- "Quickly fixes" something to save time — this is how drift starts

**The orchestrator ONLY:**
- Reads/writes `docs/tasks.md`
- Reads/writes `docs/orchestrator-learnings.json`
- Delegates ALL code changes to workers (native subagent tool when available, otherwise Mosaic matrix rail)
- Parses worker JSON results
- Commits task tracking updates (tasks.md, learnings)
- Outputs status reports and handoff messages

**If you find yourself about to edit source code, STOP.**
Spawn a worker instead. No exceptions. No "quick fixes."

**Worker Limits:**
- Maximum **2 parallel workers** at any time
- Wait for at least one worker to complete before spawning more
- This optimizes token usage and reduces context pressure

## Delegation Mode Selection

Choose one delegation mode at session start:

1. **Native subagent mode** (preferred when runtime supports it)
2. **Matrix rail mode** (fallback when native subagents/background tasks are unavailable)

Matrix rail mode commands:

```bash
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply
~/.config/mosaic/bin/mosaic-orchestrator-drain
```

In Matrix rail mode, keep `docs/tasks.md` as canonical project tracking and use
`.mosaic/orchestrator/` for deterministic worker dispatch state.

---

## Bootstrap Templates

Use templates from `jarvis-brain/docs/templates/` to scaffold tracking files:

```bash
# Set environment variables
export PROJECT="project-name"
export MILESTONE="M1-Feature"
export CURRENT_DATETIME=$(date -Iseconds)
export TASK_PREFIX="PR-SEC"
export PHASE_ISSUE="#1"
export PHASE_BRANCH="fix/security"

# Copy templates
TEMPLATES=~/src/jarvis-brain/docs/templates

# Create tasks.md (then populate with findings)
envsubst < $TEMPLATES/orchestrator/tasks.md.template > docs/tasks.md

# Create learnings tracking
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json

# Create review report structure (if doing new review)
$TEMPLATES/reports/review-report-scaffold.sh codebase-review
```

**Available templates:**

| Template | Purpose |
|----------|---------|
| `orchestrator/tasks.md.template` | Task tracking table with schema |
| `orchestrator/orchestrator-learnings.json.template` | Variance tracking |
| `orchestrator/phase-issue-body.md.template` | Gitea issue body |
| `orchestrator/compaction-summary.md.template` | 60% checkpoint format |
| `reports/review-report-scaffold.sh` | Creates report directory |
| `scratchpad.md.template` | Per-task working document |

See `jarvis-brain/docs/templates/README.md` for full documentation.

---

## Phase 1: Bootstrap

### Step 1: Parse Review Reports

Review reports typically follow this structure:
```
docs/reports/{report-name}/
├── 00-executive-summary.md   # Start here - overview and counts
├── 01-security-review.md     # Security findings with IDs like SEC-*
├── 02-code-quality-review.md # Code quality findings like CQ-*
├── 03-qa-test-coverage.md    # Test coverage gaps like TEST-*
└── ...
```

**Extract findings by looking for:**
- Finding IDs (e.g., `SEC-API-1`, `CQ-WEB-3`, `TEST-001`)
- Severity labels: Critical, High, Medium, Low
- Affected files/components (use for `repo` column)
- Specific line numbers or code patterns

**Parse each finding into:**
```
{
  id: "SEC-API-1",
  severity: "critical",
  title: "Brief description",
  component: "api",          // For repo column
  file: "path/to/file.ts",   // Reference for worker
  lines: "45-67"             // Specific location
}
```

### Step 2: Categorize into Phases

Map severity to phases:

| Severity | Phase | Focus | Branch Pattern |
|----------|-------|-------|----------------|
| Critical | 1 | Security vulnerabilities, data exposure | `fix/security` |
| High | 2 | Security hardening, auth gaps | `fix/security` |
| Medium | 3 | Code quality, performance, bugs | `fix/code-quality` |
| Low | 4 | Tests, documentation, cleanup | `fix/test-coverage` |

**Within each phase, order tasks by:**
1. Blockers first (tasks that unblock others)
2. Same-file tasks grouped together
3. Simpler fixes before complex ones

### Step 3: Estimate Token Usage

Use these heuristics based on task type:

| Task Type | Estimate | Examples |
|-----------|----------|----------|
| Single-line fix | 3-5K | Typo, wrong operator, missing null check |
| Add guard/validation | 5-8K | Add auth decorator, input validation |
| Fix error handling | 8-12K | Proper try/catch, error propagation |
| Refactor pattern | 10-15K | Replace KEYS with SCAN, fix memory leak |
| Add new functionality | 15-25K | New service method, new component |
| Write tests | 15-25K | Unit tests for untested service |
| Complex refactor | 25-40K | Architectural change, multi-file refactor |

**Adjust estimates based on:**
- Number of files affected (+5K per additional file)
- Test requirements (+5-10K if tests needed)
- Documentation needs (+2-3K if docs needed)

### Step 4: Determine Dependencies

**Automatic dependency rules:**
1. All tasks in Phase N depend on the Phase N-1 verification task
2. Tasks touching the same file should be sequential (earlier blocks later)
3. Auth/security foundation tasks block tasks that rely on them
4. Each phase ends with a verification task that depends on all phase tasks

**Create verification tasks:**
- `{PREFIX}-SEC-{LAST}`: Phase 1 verification (run security tests)
- `{PREFIX}-HIGH-{LAST}`: Phase 2 verification
- `{PREFIX}-CQ-{LAST}`: Phase 3 verification
- `{PREFIX}-TEST-{LAST}`: Phase 4 verification (final quality gates)

### Step 5: Create Gitea Issues (Phase-Level)

Create ONE issue per phase using git scripts:

```bash
~/.config/mosaic/rails/git/issue-create.sh \
  -t "Phase 1: Critical Security Fixes" \
  -b "$(cat <<'EOF'
## Findings

- SEC-API-1: Description
- SEC-WEB-2: Description
- SEC-ORCH-1: Description

## Acceptance Criteria

- [ ] All critical findings remediated
- [ ] Quality gates passing
- [ ] No new regressions
EOF
)" \
  -l "security,critical" \
  -m "{milestone-name}"
```

**Capture issue numbers** — you'll link tasks to these.

### Step 6: Create docs/tasks.md

Create the file with this exact schema:

```markdown
# Tasks

| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {PREFIX}-SEC-001 | not-started | SEC-API-1: Brief description | #{N} | api | fix/security | | {PREFIX}-SEC-002 | | | | 8K | |
```

**Column definitions:**

| Column | Format | Purpose |
|--------|--------|---------|
| `id` | `{PREFIX}-{CAT}-{NNN}` | Unique task ID (e.g., MS-SEC-001) |
| `status` | `not-started` \| `in-progress` \| `done` \| `failed` | Current state |
| `description` | `{FindingID}: Brief summary` | What to fix |
| `issue` | `#NNN` | Gitea issue (phase-level, all tasks in phase share) |
| `repo` | Workspace name | `api`, `web`, `orchestrator`, etc. |
| `branch` | Branch name | `fix/security`, `fix/code-quality`, etc. |
| `depends_on` | Comma-separated IDs | Must complete first |
| `blocks` | Comma-separated IDs | Tasks waiting on this |
| `agent` | Agent identifier | Assigned worker (fill when claiming) |
| `started_at` | ISO 8601 | When work began |
| `completed_at` | ISO 8601 | When work finished |
| `estimate` | `5K`, `15K`, etc. | Predicted token usage |
| `used` | `4.2K`, `12.8K`, etc. | Actual usage (fill on completion) |

**Category prefixes:**
- `SEC` — Security (Phase 1-2)
- `HIGH` — High priority (Phase 2)
- `CQ` — Code quality (Phase 3)
- `TEST` — Test coverage (Phase 4)
- `PERF` — Performance (Phase 3)

### Step 7: Commit Bootstrap

```bash
git add docs/tasks.md
git commit -m "chore(orchestrator): Bootstrap tasks.md from review report

Parsed {N} findings into {M} tasks across {P} phases.
Estimated total: {X}K tokens."
git push
```

---

## Phase 2: Execution 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, run final retrospective, STOP
   - Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent={identifier}, started_at={now}
6. Delegate worker task:
   - native mode: spawn worker agent via runtime subagent/task primitive
   - matrix mode: enqueue/consume task in `.mosaic/orchestrator/tasks.json` and run `mosaic-orchestrator-matrix-cycle`
7. Wait for worker completion
8. Parse worker result (JSON)
9. **Variance check**: Calculate (actual - estimate) / estimate × 100
   - If |variance| > 50%: Capture learning (see Learning & Retrospective)
   - If |variance| > 100%: Flag as CRITICAL — review task classification
10. **Post-Coding Review** (see Phase 2b below)
11. Update tasks.md: status=done/failed/needs-qa, completed_at={now}, used={actual}
12. **Cleanup reports**: Remove processed report files for completed task
    ```bash
    # Find and remove reports matching the finding ID
    find docs/reports/qa-automation/pending/ -name "*{finding_id}*" -delete 2>/dev/null || true
    # If task failed, move reports to escalated/ instead
    ```
13. Commit + push: git add docs/tasks.md .gitignore && git commit && git push
14. If phase verification task: Run phase retrospective, clean up all phase reports
15. Check context usage
16. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
17. If < 55%: Go to step 1
18. After user runs /compact and says "continue": Go to step 1
```

---

## Phase 2b: Post-Coding Review (MANDATORY)

**CRITICAL:** After any worker completes a task that modifies source code, the orchestrator MUST run an independent review before marking the task as done. This catches bugs, security issues, and regressions that the worker missed.

### When to Review

Run review when the worker's result includes code changes (commits). Skip for tasks that only modify docs, config, or tracking files.

### Step 1: Run Codex Review (Primary)

```bash
# Navigate to the project directory
cd {project_path}

# Code quality review
~/.config/mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json

# Security review
~/.config/mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
```

### Step 2: Parse Review Results

```bash
# Check code review
CODE_BLOCKERS=$(jq '.stats.blockers // 0' /tmp/review-{task_id}.json)
CODE_VERDICT=$(jq -r '.verdict // "comment"' /tmp/review-{task_id}.json)

# Check security review
SEC_CRITICAL=$(jq '.stats.critical // 0' /tmp/security-{task_id}.json)
SEC_HIGH=$(jq '.stats.high // 0' /tmp/security-{task_id}.json)
```

### Step 3: Decision Tree

```
IF Codex is unavailable (command not found, auth failure, API error):
  → Use fallback review (Step 4)

IF CODE_BLOCKERS > 0 OR SEC_CRITICAL > 0 OR SEC_HIGH > 0:
  → Mark task as "needs-qa" in tasks.md
  → Create a remediation task:
    - ID: {task_id}-QA
    - Description: Fix findings from review (list specific issues)
    - depends_on: (none — it's a follow-up, not a blocker)
    - Notes: Include finding titles and file locations
  → Continue to next task (remediation task will be picked up in order)

IF CODE_VERDICT == "request-changes" (but no blockers):
  → Log should-fix findings in task notes
  → Mark task as done (non-blocking suggestions)
  → Consider creating a tech-debt issue for significant suggestions

IF CODE_VERDICT == "approve" AND SEC_CRITICAL == 0 AND SEC_HIGH == 0:
  → Mark task as done
  → Log: "Review passed — no issues found"
```

### Step 4: Fallback Review (When Codex is Unavailable)

If the `codex` CLI is not installed or authentication fails, use Claude's built-in review capabilities:

```markdown
## Fallback: Spawn a Review Agent

Use the Task tool to spawn a review subagent:

Prompt:
---
## Independent Code Review

Review the code changes on branch {branch} against {base_branch}.

1. Run: `git diff {base_branch}...HEAD`
2. Review for:
   - Correctness (bugs, logic errors, edge cases)
   - Security (OWASP Top 10, secrets, injection)
   - Testing (coverage, quality)
   - Code quality (complexity, duplication)
3. Reference: ~/.config/mosaic/guides/code-review.md

Report findings as JSON:
```json
{
  "verdict": "approve|request-changes",
  "blockers": 0,
  "critical_security": 0,
  "findings": [
    {"severity": "blocker|should-fix|suggestion", "title": "...", "file": "...", "description": "..."}
  ]
}
```
---
```

### Review Timing Guidelines

| Task Type | Review Required? |
|-----------|-----------------|
| Source code changes (*.ts, *.py, etc.) | **YES — always** |
| Configuration changes (*.yml, *.toml) | YES — security review only |
| Documentation changes (*.md) | No |
| Task tracking updates (tasks.md) | No |
| Test-only changes | YES — code review only |

### Logging Review Results

In the task notes column of tasks.md, append review results:

```
Review: approve (0 blockers, 0 critical) | Codex 0.98.0
```

or:

```
Review: needs-qa (1 blocker, 2 high) → QA task {task_id}-QA created
```

---

## Worker Prompt Template

Construct this from the task row and pass to worker via Task tool:

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

**Description:** {description}
**Repository:** {project_path}/apps/{repo}
**Branch:** {branch}

**Reference:** See `docs/reports/` for detailed finding description. Search for the finding ID.

## Workflow

1. Checkout branch: `git checkout {branch} || git checkout -b {branch} develop && git pull`
2. Read the finding details from the report
3. Implement the fix following existing code patterns
4. Run quality gates (ALL must pass — zero lint errors, zero type errors, all tests green):
   ```bash
   {quality_gates_command}
   ```
   **MANDATORY:** This ALWAYS includes linting. If the project has a linter configured
   (ESLint, Biome, ruff, etc.), you MUST run it and fix ALL violations in files you touched.
   Do NOT leave lint warnings or errors for someone else to clean up.
5. If gates fail: Fix and retry. Do NOT report success with failures.
6. Commit: `git commit -m "fix({finding_id}): brief description"`
7. Push: `git push origin {branch}`
8. Report result as JSON (see format below)

## Git Scripts

For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
- `~/.config/mosaic/rails/git/issue-view.sh -i {N}`
- `~/.config/mosaic/rails/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"
}
```

## Post-Coding Review

After you complete and push your changes, the orchestrator will independently
review your code using Codex (or a fallback review agent). If the review finds
blockers or critical security issues, a follow-up remediation task will be
created. You do NOT need to run the review yourself — the orchestrator handles it.

## Rules

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

---

## Context Threshold Protocol (Orchestrator Replacement)

**Threshold:** 55-60% context usage

**Why replacement, not compaction?**
- Compaction causes **protocol drift** — agent "remembers" gist but loses specifics
- Post-compaction agents may violate core rules (e.g., letting workers modify tasks.md)
- Fresh orchestrator has **100% protocol fidelity**
- All state lives in `docs/tasks.md` — the orchestrator is **stateless and replaceable**

**At threshold (55-60%):**

1. Complete current task
2. Persist all state:
   - Update docs/tasks.md with all progress
   - Update docs/orchestrator-learnings.json with variances
   - Commit and push both files
3. Output **ORCHESTRATOR HANDOFF** message with ready-to-use takeover kickstart
4. **STOP COMPLETELY** — do not continue working

**Handoff message format:**

```
---
⚠️ ORCHESTRATOR HANDOFF REQUIRED

Context: {X}% — Replacement recommended to prevent drift

Progress: {completed}/{total} tasks ({percentage}%)
Current phase: Phase {N} ({phase_name})

State persisted:
- docs/tasks.md ✓
- docs/orchestrator-learnings.json ✓

## Takeover Kickstart

Copy and paste this to spawn a fresh orchestrator:

---
## Continuation Mission

Continue {mission_description} from existing state.

## Setup
- Project: {project_path}
- State: docs/tasks.md (already populated)
- Protocol: docs/claude/orchestrator.md
- Quality gates: {quality_gates_command}

## Resume Point
- Next task: {task_id}
- Phase: {current_phase}
- Progress: {completed}/{total} tasks ({percentage}%)

## Instructions
1. Read docs/claude/orchestrator.md for protocol
2. Read docs/tasks.md to understand current state
3. Continue execution from task {task_id}
4. Follow Two-Phase Completion Protocol
5. You are the SOLE writer of docs/tasks.md
---

STOP: Terminate this session and spawn fresh orchestrator with the kickstart above.
---
```

**Rules:**
- Do NOT attempt to compact yourself — compaction causes drift
- Do NOT continue past 60%
- Do NOT claim you can "just continue" — protocol drift is real
- STOP means STOP — the user (Coordinator) will spawn your replacement
- Include ALL context needed for the replacement in the takeover kickstart

---

## Two-Phase Completion Protocol

Each major phase uses a two-phase approach to maximize completion while managing diminishing returns.

### Bulk Phase (Target: 90%)

- Focus on tractable errors
- Parallelize where possible
- When 90% reached, transition to Polish (do NOT declare success)

### Polish Phase (Target: 100%)

1. **Inventory:** List all remaining errors with file:line
2. **Categorize:**
   | Category | Criteria | Action |
   |----------|----------|--------|
   | Quick-win | <5 min, straightforward | Fix immediately |
   | Medium | 5-30 min, clear path | Fix in order |
   | Hard | >30 min or uncertain | Attempt 15 min, then document |
   | Architectural | Requires design change | Document and defer |

3. **Work priority:** Quick-win → Medium → Hard
4. **Document deferrals** in `docs/deferred-errors.md`:
   ```markdown
   ## {PREFIX}-XXX: [Error description]
   - File: path/to/file.ts:123
   - Error: [exact error message]
   - Category: Hard | Architectural | Framework Limitation
   - Reason: [why this is non-trivial]
   - Suggested approach: [how to fix in future]
   - Risk: Low | Medium | High
   ```

5. **Phase complete when:**
   - All Quick-win/Medium fixed
   - All Hard attempted (fixed or documented)
   - Architectural items documented with justification

### Phase Boundary Rule

Do NOT proceed to the next major phase until the current phase reaches Polish completion:

```
✅ Phase 2 Bulk: 91%
✅ Phase 2 Polish: 118 errors triaged
   - 40 medium → fixed
   - 78 low → EACH documented with rationale
✅ Phase 2 Complete: Created docs/deferred-errors.md
→ NOW proceed to Phase 3

❌ WRONG: Phase 2 at 91%, "low priority acceptable", starting Phase 3
```

### Reporting

When transitioning from Bulk to Polish:
```
Phase X Bulk Complete: {N}% ({fixed}/{total})
Entering Polish Phase: {remaining} errors to triage
```

When Polish Phase complete:
```
Phase X Complete: {final_pct}% ({fixed}/{total})
- Quick-wins: {n} fixed
- Medium: {n} fixed
- Hard: {n} fixed, {n} documented
- Framework limitations: {n} documented
```

---

## Learning & Retrospective

Orchestrators capture learnings to improve future estimation accuracy.

### Variance Thresholds

| Variance | Action |
|----------|--------|
| 0-30% | Log only (acceptable) |
| 30-50% | Flag for review |
| 50-100% | Capture learning to `docs/orchestrator-learnings.json` |
| >100% | CRITICAL — review task classification, possible mismatch |

### Task Type Classification

Classify tasks by description keywords for pattern analysis:

| Type | Keywords | Base Estimate |
|------|----------|---------------|
| STYLE_FIX | "formatting", "prettier", "lint" | 3-5K |
| BULK_CLEANUP | "unused", "warnings", "~N files" | file_count × 550 |
| GUARD_ADD | "add guard", "decorator", "validation" | 5-8K |
| SECURITY_FIX | "sanitize", "injection", "XSS" | 8-12K × 2.5 |
| AUTH_ADD | "authentication", "auth" | 15-25K |
| REFACTOR | "refactor", "replace", "migrate" | 10-15K |
| TEST_ADD | "add tests", "coverage" | 15-25K |

### Capture Learning

When |variance| > 50%, append to `docs/orchestrator-learnings.json`:

```json
{
  "task_id": "UC-CLEAN-003",
  "task_type": "BULK_CLEANUP",
  "estimate_k": 30,
  "actual_k": 112.8,
  "variance_pct": 276,
  "characteristics": {
    "file_count": 200,
    "keywords": ["object injection", "type guards"]
  },
  "analysis": "Multi-file type guards severely underestimated",
  "captured_at": "2026-02-05T19:45:00Z"
}
```

### Retrospective Triggers

| Trigger | Action |
|---------|--------|
| Phase verification task | Analyze phase variance, summarize patterns |
| 60% compaction | Persist learnings buffer, include in summary |
| Milestone complete | Full retrospective, generate heuristic proposals |

### Enhanced Compaction Summary

Include learnings in compaction output:

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

Completed: MS-SEC-001 (15K→0.3K, -98%), MS-SEC-002 (8K→12K, +50%)
Quality: All gates passing

Learnings Captured:
- MS-SEC-001: -98% variance — AUTH_ADD may need SKIP_IF_EXISTS category
- MS-SEC-002: +50% variance — XSS sanitization more complex than expected

Remaining: MS-SEC-004 (ready), MS-SEC-005 through MS-SEC-010
Next: MS-SEC-004
```

### Cross-Project Learnings

Universal heuristics are maintained in `~/.config/mosaic/guides/orchestrator-learnings.md`.
After completing a milestone, review variance patterns and propose updates to the universal guide.

---

## Report Cleanup

QA automation generates report files in `docs/reports/qa-automation/pending/`. These must be cleaned up to prevent accumulation.

**Directory structure:**
```
docs/reports/qa-automation/
├── pending/      # Reports awaiting processing
└── escalated/    # Reports for failed tasks (manual review needed)
```

**Gitignore:** Add this to project `.gitignore`:
```
# Orchestrator reports (generated by QA automation, cleaned up after processing)
docs/reports/qa-automation/
```

**Cleanup timing:**
| Event | Action |
|-------|--------|
| Task success | Delete matching reports from `pending/` |
| Task failed | Move reports to `escalated/` for investigation |
| Phase verification | Clean up all `pending/` reports for that phase |
| Milestone complete | Archive or delete entire `escalated/` directory |

**Cleanup commands:**
```bash
# After successful task (finding ID pattern, e.g., SEC-API-1)
find docs/reports/qa-automation/pending/ -name "*relevant-file-pattern*" -delete

# After phase verification - clean all pending
rm -rf docs/reports/qa-automation/pending/*

# Move failed task reports to escalated
mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/escalated/
```

---

## Error Handling

**Quality gates fail:**
1. Worker should retry up to 2 times
2. If still failing, worker reports `failed` with error details
3. Orchestrator updates tasks.md: keep `in-progress`, add notes
4. Orchestrator may re-spawn with error context, or mark `failed` and continue
5. If failed task blocks others: Report deadlock, STOP

**Worker reports blocker:**
1. Update tasks.md with blocker notes
2. Skip to next unblocked task if possible
3. If all remaining tasks blocked: Report blockers, 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. Context usage >= 55% — output COMPACTION REQUIRED checkpoint and wait
4. Absolute context limit reached AND cannot compact further

**DO NOT stop to ask "should I continue?"** — the answer is always YES.
**DO stop at 55-60%** — output the compaction checkpoint and wait for user to run `/compact`.

---

## Sprint Completion Protocol

When all tasks in `docs/tasks.md` are `done` (or triaged as `deferred`), archive the sprint artifacts before stopping. This preserves them for post-mortems, variance calibration, and historical reference.

### Archive Steps

1. **Create archive directory** (if it doesn't exist):
   ```bash
   mkdir -p docs/tasks/
   ```

2. **Move tasks.md to archive:**
   ```bash
   mv docs/tasks.md docs/tasks/{milestone-name}-tasks.md
   ```
   Example: `docs/tasks/M6-AgentOrchestration-Fixes-tasks.md`

3. **Move learnings to archive:**
   ```bash
   mv docs/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
   ```

4. **Commit the archive:**
   ```bash
   git add docs/tasks/
   git rm docs/tasks.md docs/orchestrator-learnings.json 2>/dev/null || true
   git commit -m "chore(orchestrator): Archive {milestone-name} sprint artifacts

   {completed}/{total} tasks completed, {deferred} deferred.
   Archived to docs/tasks/ for post-mortem reference."
   git push
   ```

5. **Run final retrospective** — review variance patterns and propose updates to estimation heuristics.

### Recovery

If an orchestrator starts and `docs/tasks.md` does not exist, check `docs/tasks/` for the most recent archive:

```bash
ls -t docs/tasks/*-tasks.md 2>/dev/null | head -1
```

If found, this may indicate another session archived the file. The orchestrator should:
1. Report what it found in `docs/tasks/`
2. Ask whether to resume from the archived file or bootstrap fresh
3. If resuming: copy the archive back to `docs/tasks.md` and continue

### Retention Policy

Keep all archived sprints indefinitely. They are small text files and valuable for:
- Post-mortem analysis
- Estimation variance calibration across milestones
- Understanding what was deferred and why
- Onboarding new orchestrators to project history

---

## Kickstart Message Format

The kickstart should be **minimal** — the orchestrator figures out the rest:

```markdown
## Mission
Remediate findings from the codebase review.

## Setup
- Project: /path/to/project
- Review: docs/reports/{report-name}/
- Quality gates: {command}
- Milestone: {milestone-name} (for issue creation)
- Task prefix: {PREFIX} (e.g., MS, UC)

## Protocol
Read ~/.config/mosaic/guides/orchestrator.md for full instructions.

## Start
Bootstrap from the review report, then execute until complete.
```

**The orchestrator will:**
1. Read this guide
2. Parse the review reports
3. Determine phases, estimates, dependencies
4. Create issues and tasks.md
5. Execute until done or blocked

---

## Quick Reference

| Phase | Action |
|-------|--------|
| Bootstrap | Parse reports → Categorize → Estimate → Create issues → Create tasks.md |
| Execute | Loop: claim → spawn worker → update → commit |
| Compact | At 60%: summarize, clear history, continue |
| Stop | Queue empty, blocker, or context limit |

**Orchestrator owns tasks.md. Workers execute and report. Single writer eliminates conflicts.**