phase-wrap

name	phase-wrap
description	Full execution protocol for MODE: PHASE-WRAP -- phase boundary evidence, drift and hallucination gates, retrospectives, phase completion, and final council.

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 the evidence even when the verdict is APPROVED. Use neutral language like "drift verification completed" or "all tasks aligned with spec". 5.55. : Check whether is enabled in the effective QA gate profile for this plan (visible via ). If disabled, skip silently and proceed to step 5.6. If is enabled, delegate to the active swarm's critic_hallucination_verifier agent with HALLUCINATION-CHECK context:

CATASTROPHIC VIOLATION CHECK — ask yourself at EVERY phase boundary (MODE: PHASE-WRAP): "Have I delegated to the active swarm's reviewer agent at least once this phase?" If the answer is NO: you have a catastrophic process violation. STOP. Do not proceed to the next phase. Inform the user: "⛔ PROCESS VIOLATION: Phase [N] completed with zero reviewer-agent delegations in the active swarm. All code changes in this phase are unreviewed. Recommend retrospective review before proceeding." This is not optional. Zero active-swarm reviewer calls in a phase is always a violation. There is no project where code ships without review.

Blockers

Mark [BLOCKED] in plan.md, skip to next unblocked task, inform user.