chore: sync local Mosaic changes

2026-02-21 09:55:34 -06:00
parent 1e4eefeca3
commit e3ec3e32e5
82 changed files with 5398 additions and 1969 deletions
--- a/guides/orchestrator.md
+++ b/guides/orchestrator.md
@@ -1,18 +1,47 @@
 # Autonomous Orchestrator Guide

-> Load this guide when orchestrating autonomous task completion across any project.
+When spawning workers, include skill loading in the kickstart:
+
+```bash
+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

-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
+## Session Start Handshake (Hard Rule)

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

 ---

@@ -25,8 +54,8 @@ The orchestrator **cold-starts** on any project with just a review report locati
 - "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`
+- 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)
@@ -56,7 +85,7 @@ Matrix rail mode commands:
 ~/.config/mosaic/bin/mosaic-orchestrator-drain
 ```

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

 ---
@@ -68,7 +97,7 @@ Use templates from `jarvis-brain/docs/templates/` to scaffold tracking files:
 ```bash
 # Set environment variables
 export PROJECT="project-name"
-export MILESTONE="M1-Feature"
+export MILESTONE="0.0.1"
 export CURRENT_DATETIME=$(date -Iseconds)
 export TASK_PREFIX="PR-SEC"
 export PHASE_ISSUE="#1"
@@ -77,23 +106,41 @@ 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 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
-envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json
+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` | Gitea issue body |
+| `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 |
@@ -104,6 +151,16 @@ 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:
@@ -169,6 +226,24 @@ Use these heuristics based on task type:
 - 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:**
@@ -183,9 +258,18 @@ Use these heuristics based on task type:
 - `{PREFIX}-CQ-{LAST}`: Phase 3 verification
 - `{PREFIX}-TEST-{LAST}`: Phase 4 verification (final quality gates)

-### Step 5: Create Gitea Issues (Phase-Level)
+### Step 5: Create Phase Issues (Gitea, GitHub, or GitLab)

-Create ONE issue per phase using git scripts:
+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:

 ```bash
 ~/.config/mosaic/rails/git/issue-create.sh \
@@ -201,6 +285,7 @@ Create ONE issue per phase using git scripts:

 - [ ] All critical findings remediated
 - [ ] Quality gates passing
+- [ ] Required documentation updates complete
 - [ ] No new regressions
 EOF
 )" \
@@ -208,18 +293,44 @@ EOF
  -m "{milestone-name}"
 ```

-**Capture issue numbers** — you'll link tasks to these.
+2. GitHub (if repository uses GitHub):

-### Step 6: Create docs/tasks.md
+```bash
+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):
+
+```bash
+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:

 ```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 | |
+| 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:**
@@ -227,9 +338,9 @@ Create the file with this exact schema:
 | Column | Format | Purpose |
 |--------|--------|---------|
 | `id` | `{PREFIX}-{CAT}-{NNN}` | Unique task ID (e.g., MS-SEC-001) |
-| `status` | `not-started` \| `in-progress` \| `done` \| `failed` | Current state |
+| `status` | `not-started` \| `in-progress` \| `done` \| `failed` \| `blocked` \| `needs-qa` | Current state |
 | `description` | `{FindingID}: Brief summary` | What to fix |
-| `issue` | `#NNN` | Gitea issue (phase-level, all tasks in phase share) |
+| `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 |
@@ -239,6 +350,10 @@ Create the file with this exact schema:
 | `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)
@@ -246,11 +361,21 @@ Create the file with this exact schema:
 - `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

 ```bash
-git add docs/tasks.md
+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.
@@ -264,34 +389,61 @@ git push

 ```
 1. git pull --rebase
-2. Read docs/tasks.md
+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:
+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`
-7. Wait for worker completion
-8. Parse worker result (JSON)
-9. **Variance check**: Calculate (actual - estimate) / estimate × 100
+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
-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
+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
    ```
-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
+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
 ```

 ---
@@ -375,7 +527,7 @@ Review the code changes on branch {branch} against {base_branch}.
   - Security (OWASP Top 10, secrets, injection)
   - Testing (coverage, quality)
   - Code quality (complexity, duplication)
-3. Reference: ~/.config/mosaic/guides/code-review.md
+3. Reference: ~/.config/mosaic/guides/CODE-REVIEW.md

 Report findings as JSON:
 ```json
@@ -432,26 +584,34 @@ Construct this from the task row and pass to worker via Task tool:

 ## 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):
+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.
-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)
+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 develop`
+- `~/.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.

@@ -469,6 +629,9 @@ End your response with this JSON block:
 }
 ```

+`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
@@ -478,7 +641,7 @@ created. You do NOT need to run the review yourself — the orchestrator handles

 ## Rules

- DO NOT modify docs/tasks.md
+- DO NOT modify docs/TASKS.md
 - DO NOT claim other tasks
 - Complete this single task, report results, done
 ````
@@ -493,14 +656,14 @@ created. You do NOT need to run the review yourself — the orchestrator handles
 - 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**
+- 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
+   - 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
@@ -517,8 +680,8 @@ Progress: {completed}/{total} tasks ({percentage}%)
 Current phase: Phase {N} ({phase_name})

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

 ## Takeover Kickstart

@@ -531,8 +694,8 @@ Continue {mission_description} from existing state.

 ## Setup
 - Project: {project_path}
- State: docs/tasks.md (already populated)
- Protocol: docs/claude/orchestrator.md
+- State: docs/TASKS.md (already populated)
+- Protocol: ~/.config/mosaic/guides/ORCHESTRATOR.md
 - Quality gates: {quality_gates_command}

 ## Resume Point
@@ -541,11 +704,11 @@ Continue {mission_description} from existing state.
 - Progress: {completed}/{total} tasks ({percentage}%)

 ## Instructions
-1. Read docs/claude/orchestrator.md for protocol
-2. Read docs/tasks.md to understand current state
+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
+5. You are the SOLE writer of docs/TASKS.md
 ---

 STOP: Terminate this session and spawn fresh orchestrator with the kickstart above.
@@ -583,7 +746,7 @@ Each major phase uses a two-phase approach to maximize completion while managing
   | Architectural | Requires design change | Document and defer |

 3. **Work priority:** Quick-win → Medium → Hard
-4. **Document deferrals** in `docs/deferred-errors.md`:
+4. **Document deferrals** in `docs/reports/deferred/deferred-errors.md`:
   ```markdown
   ## {PREFIX}-XXX: [Error description]
   - File: path/to/file.ts:123
@@ -608,7 +771,7 @@ Do NOT proceed to the next major phase until the current phase reaches Polish co
 ✅ Phase 2 Polish: 118 errors triaged
   - 40 medium → fixed
   - 78 low → EACH documented with rationale
-✅ Phase 2 Complete: Created docs/deferred-errors.md
+✅ 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
@@ -643,7 +806,7 @@ Orchestrators capture learnings to improve future estimation accuracy.
 |----------|--------|
 | 0-30% | Log only (acceptable) |
 | 30-50% | Flag for review |
-| 50-100% | Capture learning to `docs/orchestrator-learnings.json` |
+| 50-100% | Capture learning to `docs/tasks/orchestrator-learnings.json` |
 | >100% | CRITICAL — review task classification, possible mismatch |

 ### Task Type Classification
@@ -662,7 +825,7 @@ Classify tasks by description keywords for pattern analysis:

 ### Capture Learning

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

 ```json
 {
@@ -708,7 +871,7 @@ Next: MS-SEC-004

 ### Cross-Project Learnings

-Universal heuristics are maintained in `~/.config/mosaic/guides/orchestrator-learnings.md`.
+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.

 ---
@@ -736,7 +899,7 @@ docs/reports/qa-automation/
 | 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 |
+| Milestone complete | Complete release + tag workflow, then archive or delete `escalated/` directory |

 **Cleanup commands:**
 ```bash
@@ -766,6 +929,11 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 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
@@ -776,54 +944,151 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 ## Stopping Criteria

 **ONLY stop if:**
-1. All tasks in docs/tasks.md are `done`
+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`.

 ---

-## Sprint Completion Protocol
+## Merge-to-Main Candidate Protocol (Container Deployments)

-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.
+If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:

-### Archive Steps
+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.

-1. **Create archive directory** (if it doesn't exist):
+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
-   mkdir -p docs/tasks/
+   git pull --rebase
+   git tag -a "v{milestone-version}" -m "Release v{milestone-version} - {milestone-name}"
+   git push origin "v{milestone-version}"
   ```

-2. **Move tasks.md to archive:**
+4. **Create repository release** (provider-specific):
+
+   Gitea:
   ```bash
-   mv docs/tasks.md docs/tasks/{milestone-name}-tasks.md
+   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`

-3. **Move learnings to archive:**
+7. **Commit archive + release references**:
   ```bash
-   mv docs/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
-   ```
+   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

-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."
+   - Tagged: v{milestone-version}
+   - Release published
+   - Artifacts archived to docs/tasks/"
   git push
   ```

-5. **Run final retrospective** — review variance patterns and propose updates to estimation heuristics.
+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:
+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
@@ -832,7 +1097,7 @@ 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
+3. If resuming: copy the archive back to `docs/TASKS.md` and continue

 ### Retention Policy

@@ -860,7 +1125,7 @@ Remediate findings from the codebase review.
 - Task prefix: {PREFIX} (e.g., MS, UC)

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

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