bootstrap/guides/orchestrator.md

Autonomous Orchestrator Guide

When spawning workers, include skill loading in the kickstart:

claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."

MANDATORY

• You MUST establish the requirements for a task, or series of tasks, before coding begins.
• You MUST ensure docs/PRD.md or docs/PRD.json exists before worker coding starts.
• You MUST use sequential-thinking to properly plan out tasks, milestones, epics, and PRD requirements prior to orchestrating agents.
• You MUST track tasks at the project level in docs/TASKS.md.
• You MUST keep the TASKS.md file updated with agent and tasks statuses.
• You MUST keep docs/ root clean. Reports and working artifacts MUST be stored in scoped folders (docs/reports/, docs/tasks/, docs/releases/, docs/scratchpads/).
• You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
• You MUST enforce trunk workflow: workers branch from main, PR target is main, direct push to main is forbidden, and PR merges to main are squash-only.
• You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
• You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
• Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
• Do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow after gates pass.

Overview

Session Start Handshake (Hard Rule)

Before any orchestration actions, the first response MUST be:

Now initiating Orchestrator mode...

Then proceed with orchestration bootstrap steps.

The orchestrator cold-starts on any project with just a review report location and minimal kickstart. It autonomously:

1. Prepares/updates project PRD (docs/PRD.md or docs/PRD.json) from user input and available project context
2. Parses review reports to extract findings
3. Categorizes findings into phases by severity
4. Estimates token usage per task
5. Creates phase issues in the configured git provider (Gitea/GitHub/GitLab)
6. Bootstraps docs/TASKS.md from scratch
7. Coordinates completion using worker agents
8. Enforces documentation completion gates for code/API/auth/infra changes

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/tasks/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:

~/.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:

# Set environment variables
export PROJECT="project-name"
export MILESTONE="0.0.1"
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 PRD if missing (before coding begins)
[[ -f docs/PRD.md || -f docs/PRD.json ]] || cp ~/.config/mosaic/templates/docs/PRD.md.template docs/PRD.md

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

# Create learnings tracking
mkdir -p docs/tasks docs/reports/deferred
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/tasks/orchestrator-learnings.json

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

Milestone versioning (HARD RULE):

• Pre-MVP milestones MUST start at 0.0.1.
• Pre-MVP progression MUST remain in 0.0.x (0.0.2, 0.0.3, ...).
• 0.1.0 is reserved for MVP release.
• You MUST NOT start pre-MVP planning at 0.1.0.

Branch and merge strategy (HARD RULE):

• Workers use short-lived task branches from origin/main.
• Worker task branches merge back via PR to main only.
• Direct pushes to main are prohibited.
• PR merges to main MUST use squash merge.

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	Git provider 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 0: Prepare PRD (Required Before Coding)

Before creating tasks or spawning workers:

1. Ensure docs/PRD.md or docs/PRD.json exists.
2. Build/update PRD from user input and available project context.
3. If requirements are missing, proceed with best-guess assumptions by default and mark each guessed requirement with ASSUMPTION: in PRD.
4. Escalate only when uncertainty is high-impact and cannot be safely bounded with rollback-ready defaults.
5. Do NOT start worker coding tasks until this step is complete.

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 3b: Budget Guardrail (HARD RULE)

Before creating dependencies or dispatching workers:

1. Determine budget cap:
   • Use explicit user plan/token cap if provided.
   • If no cap is provided, derive a soft cap from estimates and runtime constraints, then continue autonomously.
2. Calculate projected total from estimate column and record cap in task notes/scratchpad.
3. Apply dispatch mode by budget pressure:
   • <70% of cap projected: normal orchestration (up to 2 workers).
   • 70-90% of cap projected: conservative mode (1 worker, tighter scope, no exploratory tasks).
   • >90% of cap projected: freeze new worker starts; triage remaining work with user.
4. If projected usage exceeds cap, first reduce scope/parallelism automatically. If cap still cannot be met, STOP and ask user to:
   • reduce scope, or
   • split into phases, or
   • approve a higher budget.

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 Phase Issues (Gitea, GitHub, or GitLab)

You MUST create ONE issue per phase in the configured external git provider.

Milestone binding rule:

• When the project is pre-MVP, issue milestones MUST use a 0.0.x milestone.
• 0.1.0 MUST be used only for the MVP release milestone.

Provider options:

1. Gitea (preferred when available) via Mosaic helper:

~/.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
- [ ] Required documentation updates complete
- [ ] No new regressions
EOF
)" \
  -l "security,critical" \
  -m "{milestone-name}"

2. GitHub (if repository uses GitHub):

gh issue create \
  --title "Phase 1: Critical Security Fixes" \
  --body-file /tmp/phase-1-body.md \
  --label "security,critical" \
  --milestone "{milestone-name}"

3. GitLab (if repository uses GitLab):

glab issue create \
  --title "Phase 1: Critical Security Fixes" \
  --description-file /tmp/phase-1-body.md \
  --label "security,critical" \
  --milestone "{milestone-name}"

No external provider fallback (HARD RULE):

• If Gitea/GitHub/GitLab is unavailable, you MUST track phase-level milestones and issue equivalents directly in docs/TASKS.md.
• In this mode, the issue column MUST use internal refs (example: TASKS:P1, TASKS:P2).
• You MUST keep docs/TASKS.md as the complete system of record for tasks, milestones, and issue status.

Capture issue references — you'll link tasks to these.

Step 6: Create docs/TASKS.md

Create the file with this exact schema:

# Tasks

| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {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 | blocked | needs-qa	Current state
description	{FindingID}: Brief summary	What to fix
issue	#NNN or TASKS:Pn	Provider issue ref (phase-level) or internal TASKS milestone ref
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)
notes	free text	Review results, PR/CI/issue closure evidence, blocker commands

Status rule:

• done is allowed only after PR merge + green CI + issue/ref closure for source-code tasks.

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)
• DOC — Documentation updates/gates

Step 6b: Add Documentation Tasks (MANDATORY)

For each phase containing code/API/auth/infra work:

1. Add explicit documentation tasks in docs/TASKS.md (or include docs in phase verification tasks).
2. Require completion of ~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md.
3. Ensure phase acceptance criteria includes documentation completion.
4. Do not mark phase complete until documentation tasks are done.

Step 7: Commit Bootstrap

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. Budget gate (before dispatch):
   - Compute cumulative used + remaining estimate
   - If projected total > budget cap: STOP and request user decision (reduce scope/phase/increase cap)
   - If projected total is 70-90% of cap: run conservative mode (single worker)
7. 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`
8. Wait for worker completion
9. Parse worker result (JSON)
10. **Variance check**: Calculate (actual - estimate) / estimate × 100
   - If |variance| > 50%: Capture learning (see Learning & Retrospective)
   - If |variance| > 100%: Flag as CRITICAL — review task classification
11. **Post-Coding Review** (see Phase 2b below)
12. **Documentation Gate**: Verify required docs were updated per `~/.config/mosaic/guides/DOCUMENTATION.md`
    and checklist completed (`~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`) when applicable.
13. **PR + CI + Issue Closure Gate** (HARD RULE for source-code tasks):
    - Before merging, run queue guard:
      `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`
    - Ensure PR exists for the task branch (create/update via wrappers if needed):
      `~/.config/mosaic/rails/git/pr-create.sh ... -B main`
    - Merge via wrapper:
      `~/.config/mosaic/rails/git/pr-merge.sh -n {PR_NUMBER} -m squash`
    - Wait for terminal CI status:
      `~/.config/mosaic/rails/git/pr-ci-wait.sh -n {PR_NUMBER}`
    - Close linked issue after merge + green CI:
      `~/.config/mosaic/rails/git/issue-close.sh -i {ISSUE_NUMBER}`
    - If any wrapper command fails, mark task `blocked`, record the exact failed wrapper command, report blocker, and STOP.
    - Do NOT stop at "PR created" or "PR merged pending CI".
    - Do NOT claim completion before CI is green and issue/internal ref is closed.
14. Update tasks.md: status=done/failed/needs-qa/blocked, completed_at={now}, used={actual}
15. Recalculate budget position:
    - cumulative used
    - projected remaining from estimates
    - total projected at completion
16. **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
    ```
17. Commit + push: git add docs/TASKS.md .gitignore && git commit && git push
18. If phase verification task: Run phase retrospective, clean up all phase reports
19. Check context usage
20. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
21. Check budget usage:
    - If projected total > cap: STOP and request user decision before new tasks
    - If projected total is 70-90% of cap: continue in conservative mode
22. If < 55% context and within budget: Go to step 1
23. 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)

# 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

# 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:

## 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 fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
3. Read the finding details from the report
4. Implement the fix following existing code patterns
5. 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. 6. Run REQUIRED situational tests based on changed surfaces (see ~/.config/mosaic/guides/E2E-DELIVERY.md and ~/.config/mosaic/guides/QA-TESTING.md). 7. If task is bug fix/security/auth/critical business logic, apply REQUIRED TDD discipline per ~/.config/mosaic/guides/QA-TESTING.md. 8. If gates or required situational tests fail: Fix and retry. Do NOT report success with failures. 9. Commit: git commit -m "fix({finding_id}): brief description" 10. Before push, run queue guard: ~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main 11. Push: git push origin {branch} 12. 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 main
• ~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main
• ~/.config/mosaic/rails/git/pr-merge.sh -n {PR_NUMBER} -m squash
• ~/.config/mosaic/rails/git/pr-ci-wait.sh -n {PR_NUMBER}
• ~/.config/mosaic/rails/git/issue-close.sh -i {N}

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

Result Format (MANDATORY)

End your response with this JSON block:

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

status=success means "code pushed and ready for orchestrator integration gates"; it does NOT mean PR merged/CI green/issue closed.

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/tasks/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/tasks/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: ~/.config/mosaic/guides/ORCHESTRATOR.md
- Quality gates: {quality_gates_command}

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

## Instructions
1. Read ~/.config/mosaic/guides/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/reports/deferred/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/reports/deferred/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/tasks/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/tasks/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 | Complete release + tag workflow, then archive or delete `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

**PR/CI/Issue wrapper failure:**
1. Record task status as `blocked` in `docs/TASKS.md`.
2. Record the exact failed wrapper command (full command line) in task notes and user report.
3. STOP orchestration for that task; do not mark complete and do not silently fall back to raw provider commands.

**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
5. PRD is current and reflects delivered requirements (`docs/PRD.md` or `docs/PRD.json`)
6. Required documentation checklist is complete for applicable changes
7. For milestone completion, release + git tag steps are complete
8. For source-code tasks with external provider, merged PR evidence exists
9. For source-code tasks with external provider, CI/pipeline is terminal green
10. For linked external issues, closure is complete (or internal TASKS ref closure if no provider)

**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`.

---

## Merge-to-Main Candidate Protocol (Container Deployments)

If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:

1. Build and push immutable candidate image tags:
   - `sha-<shortsha>` (always)
   - `v{base-version}-rc.{build}` (for `main` merges)
   - `testing` mutable pointer to the same digest
2. Resolve and record the image digest for each service.
3. Deploy by digest to testing environment (never deploy by mutable tag alone).
4. Run full situational testing against images pulled from the registry.
5. If tests pass, promote the SAME digest (no rebuild) to environment pointers (`staging`/`prod` as applicable).
6. If tests fail, rollback to last known-good digest and create remediation tasks immediately.

Hard rules:
- `latest` MUST NOT be used as a deployment reference.
- Final semantic release tags (`vX.Y.Z`) are milestone-level only.
- Intermediate checkpoints use RC image tags (`vX.Y.Z-rc.N`) and digest promotion.

---

## Milestone Completion Protocol (Release + Tag Required)

When all tasks in `docs/TASKS.md` are `done` (or triaged as `deferred`), you MUST complete release/tag operations before declaring the milestone complete.

### Required Completion Steps

1. **Prepare release metadata**:
   - `milestone-name` (human-readable)
   - `milestone-version` (semantic version, e.g., `0.0.3`, `0.1.0`)
   - `tag` = `v{milestone-version}` (e.g., `v0.0.3`)

2. **Verify documentation gate**:
   - Confirm required docs were updated per `~/.config/mosaic/guides/DOCUMENTATION.md`.
   - Confirm checklist completion: `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`.
   - If docs are incomplete, STOP and create remediation task(s) before release/tag.

3. **Create and push annotated git tag**:
   ```bash
   git pull --rebase
   git tag -a "v{milestone-version}" -m "Release v{milestone-version} - {milestone-name}"
   git push origin "v{milestone-version}"
   ```

4. **Create repository release** (provider-specific):

   Gitea:
   ```bash
   tea releases create \
     --tag "v{milestone-version}" \
     --title "v{milestone-version}" \
     --note "Milestone {milestone-name} completed."
   ```

   GitHub:
   ```bash
   gh release create "v{milestone-version}" \
     --title "v{milestone-version}" \
     --notes "Milestone {milestone-name} completed."
   ```

   GitLab:
   ```bash
   glab release create "v{milestone-version}" \
     --name "v{milestone-version}" \
     --notes "Milestone {milestone-name} completed."
   ```

   No external provider fallback:
   - Create and push annotated tag as above.
   - Create `docs/releases/v{milestone-version}.md` with release notes and include milestone completion summary.

5. **Close milestone in provider**:
   - Gitea/GitHub:
   ```bash
   ~/.config/mosaic/rails/git/milestone-close.sh -t "{milestone-name}"
   ```
   - GitLab: close milestone via provider workflow (CLI or web UI).
   If provider tooling is unavailable, record milestone closure status in `docs/TASKS.md` notes.

6. **Archive sprint artifacts**:
   ```bash
   mkdir -p docs/tasks/
   mv docs/TASKS.md docs/tasks/{milestone-name}-tasks.md
   mv docs/tasks/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
   ```
   Example: `docs/tasks/M6-AgentOrchestration-Fixes-tasks.md`

7. **Commit archive + release references**:
   ```bash
   git add docs/tasks/ docs/releases/ 2>/dev/null || true
   git rm docs/TASKS.md docs/tasks/orchestrator-learnings.json 2>/dev/null || true
   git commit -m "chore(orchestrator): Complete {milestone-name} milestone release

   - Tagged: v{milestone-version}
   - Release published
   - Artifacts archived to docs/tasks/"
   git push
   ```

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

### Deployment Protocol (When In Scope)

If the milestone includes deployment, orchestrator MUST complete deployment before final completion status:

1. Determine deployment target from PRD, project config, or environment:
   - `Portainer`
   - `Coolify`
   - `Vercel`
   - other configured SaaS provider
2. Trigger deployment using provider API/CLI/webhook.
3. Deployment method MUST be digest-first:
   - Resolve digest from candidate image (`sha-*` or `vX.Y.Z-rc.N`),
   - deploy that digest,
   - promote tags (`testing`/`staging`/`prod`) only after validation.
4. Run post-deploy verification:
   - health endpoint checks,
   - critical smoke tests,
   - release/version verification,
   - digest verification (running digest equals promoted digest).
5. Default strategy is blue-green. Canary is allowed only if automated metrics, thresholds, and rollback triggers are configured.
6. If verification fails, execute rollback/redeploy-safe path and mark milestone `blocked` until stable.
7. Record deployment evidence in milestone release notes and `docs/TASKS.md` notes, including digest and promoted tags.
8. Ensure registry cleanup is scheduled/enforced (retain release tags + active digests, purge stale RC/sha tags).

### 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.**