phase-wrap

# Phase Wrap Protocol

This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

## ⛔ RETROSPECTIVE GATE

**MANDATORY before calling phase_complete.** You MUST write a retrospective evidence bundle BEFORE calling \`phase_complete\`. The tool will return \`{status: 'blocked', reason: 'RETROSPECTIVE_MISSING'}\` if you skip this step.

**How to write the retrospective:**

Call the \`write_retro\` tool with the required fields:
- \`phase\`: The phase number being completed (e.g., 1, 2, 3)
- \`summary\`: Human-readable summary of the phase
- \`task_count\`: Count of tasks completed in this phase
- \`task_complexity\`: One of \`trivial\` | \`simple\` | \`moderate\` | \`complex\`
- \`total_tool_calls\`: Total number of tool calls in this phase
- \`coder_revisions\`: Number of coder revisions made
- \`reviewer_rejections\`: Number of reviewer rejections received
- \`test_failures\`: Number of test failures encountered
- \`security_findings\`: Number of security findings
- \`integration_issues\`: Number of integration issues
- \`lessons_learned\` ("lessons_learned"): (optional) Key lessons learned from this phase (max 5)
- \`top_rejection_reasons\`: (optional) Top reasons for reviewer rejections
- \`metadata\`: (optional) Additional metadata, e.g., \`{ "plan_id": "<current plan title from .swarm/plan.json>" }\`

The tool will automatically write the retrospective to \`.swarm/evidence/retro-{phase}/evidence.json\` with the correct schema wrapper. The resulting JSON entry will include: \`"type": "retrospective"\`, \`"phase_number"\` (matching the phase argument), and \`"verdict": "pass"\` (auto-set by the tool).

**Required field rules:**
- \`verdict\` is auto-generated by write_retro with value \`"pass"\`. The resulting retrospective entry will have verdict \`"pass"\`; this is required for phase_complete to succeed.
- \`phase\` MUST match the phase number you are completing
- \`lessons_learned\` should be 3-5 concrete, actionable items from this phase
- Write the bundle as task_id \`retro-{N}\` (e.g., \`retro-1\` for Phase 1, \`retro-2\` for Phase 2)
- \`metadata.plan_id\` should be set to the current project's plan title (from \`.swarm/plan.json\` header). This enables cross-project filtering in the retrospective injection system.

### Additional retrospective fields (capture when applicable):
- \`user_directives\`: Any corrections or preferences the user expressed during this phase
  - \`directive\`: what the user said (non-empty string)
  - \`category\`: \`tooling\` | \`code_style\` | \`architecture\` | \`process\` | \`other\`
  - \`scope\`: \`session\` (one-time, do not carry forward) | \`project\` (persist to context.md) | \`global\` (user preference)
- \`approaches_tried\`: Approaches attempted during this phase (max 10)
  - \`approach\`: what was tried (non-empty string)
  - \`result\`: \`success\` | \`failure\` | \`partial\`
  - \`abandoned_reason\`: why it was abandoned (required when result is \`failure\` or \`partial\`)

**⚠️ WARNING:** Calling \`phase_complete(N)\` without a valid \`retro-N\` bundle will be BLOCKED. The error response will be:
\`{ "status": "blocked", "reason": "RETROSPECTIVE_MISSING" }\`

### MODE: PHASE-WRAP
1. the active swarm's explorer agent - Rescan
2. the active swarm's docs agent (the standard `docs` agent — NOT `docs_design`) - Update documentation for all changes in this phase. Provide:
   - Complete list of files changed during this phase
   - Summary of what was added/modified/removed
   - List of doc files that may need updating (README.md, CONTRIBUTING.md, docs/)
   Do NOT dispatch `docs_design` here. The structured design docs are synced separately and conditionally in step 5.58.
3. Update context.md
4. Write retrospective evidence: use the evidence manager (write_retro) to record phase, total_tool_calls, coder_revisions, reviewer_rejections, test_failures, security_findings, integration_issues, task_count, task_complexity, top_rejection_reasons, lessons_learned to .swarm/evidence/. Reset Phase Metrics in context.md to 0.
4.5. Run `evidence_check` to verify all completed tasks have required evidence (review + test). If gaps found, note in retrospective lessons_learned. Optionally run `pkg_audit` if dependencies were modified during this phase. Optionally run `schema_drift` if API routes were modified during this phase.
5. Run `sbom_generate` with scope='changed' to capture post-implementation dependency snapshot (saved to `.swarm/evidence/sbom/`). This is a non-blocking step - always proceeds to summary.
5.5. **Drift verification**: Conditional on .swarm/spec.md existence — if spec.md does not exist, skip silently and proceed to step 5.55. If spec.md exists, delegate to the active swarm's critic_drift_verifier agent with DRIFT-CHECK context:
   - Provide: phase number being completed, completed task IDs and their descriptions
   - Include evidence path (.swarm/evidence/) for the critic to read implementation artifacts
   The critic reads every target file, verifies described changes exist against the spec, and returns per-task verdicts: ALIGNED, MINOR_DRIFT, MAJOR_DRIFT, or OFF_SPEC.
   If the critic returns anything other than ALIGNED on any task, surface the drift results as a warning to the user before proceeding.
   After the delegation returns, YOU (the architect) call the `write_drift_evidence` tool to write the drift evidence artifact (phase, verdict from critic, summary). The critic does NOT write files — it is read-only. Only then proceed to step 5.55. phase_complete will also run its own deterministic pre-check (completion-verify) and block if tasks are obviously incomplete.
   ⚠️ **GOTCHA**: The drift evidence `summary` field is scanned by gates for verdict keywords. NEVER include the string "NEEDS_REVISION" or any other verdict word in the summary text — the gate will match it and falsely reject th