Phase Wrap

Phase Wrap Protocol

This protocol is loaded on demand by the architect runtime. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

Graph-first evidence contract

Before final phase judgment, use repo_map diff_context, impact_cone, and test_pack to audit the changed surface and likely tests. Graph evidence is advisory only. If freshness is stale or inconclusive, confidence is low, source is missing, the language is unsupported/dynamic, the graph is absent, or an action fails, inspect the direct source, Git diff, and executable test evidence.

⛔ 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)
• `verdict`: Explicit phase outcome, either `pass` or `fail`
• `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 the exact caller-supplied `"verdict"`.

Required field rules:

• `verdict` must be explicit on every write. Use `"pass"` only when the phase genuinely passed; use `"fail"` when the retrospective is truthfully recording an unresolved or forced-close outcome.
• `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 an EFFECTIVE spec existing (determined via /swarm sdd status or readEffectiveSpecSync — native .swarm/spec.md, OpenSpec openspec/, or Spec-Kit .specify/). If NO effective spec exists at all, skip silently. If an effective spec exists (even openspec-only or specify-only), 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. Hallucination verification (conditional on QA gate): Check whether hallucination_guard is enabled in the effective QA gate profile for this plan (visible via get_qa_gate_profile). If disabled, skip silently and proceed to step 5.6. If hallucination_guard is enabled, delegate to the active swarm's critic_hallucination_verifier agent with HALLUCINATION-CHECK context:
   • Provide: phase number being completed, completed task IDs, every file touched this phase
   • Include evidence path (.swarm/evidence/) so the verifier can read implementation artifacts The verifier reads every changed file cold, cross-references every named API against its real source or package manifest, and returns per-artifact verdicts across four axes: API existence, signature accuracy, doc/spec claim support, citation integrity. If the verifier returns NEEDS_REVISION: STOP — do NOT call phase_complete. Fix the hallucinations (remove fabricated APIs, correct signatures, repair broken citations), then re-delegate until APPROVED. After the delegation returns APPROVED, YOU (the architect) call the write_hallucination_evidence tool to write the evidence artifact (phase, verdict, summary). The critic does NOT write files — it is read-only. NOTE: This step is enforced by the plugin. If hallucination_guard is enabled and .swarm/evidence/{phase}/hallucination-guard.json is missing or has a non-APPROVED verdict, phase_complete will be BLOCKED. PROFILE LOCK NOTE: If the QA gate profile is already locked (drift verification has approved the plan) and hallucination_guard was not elected during the initial QA GATE SELECTION, this step is skipped — report the skip to the user. A new plan cycle is required to enable the gate. 5.56. Mutation gate (conditional on QA gate): Check whether mutation_test is enabled in the effective QA gate profile for this plan (visible via get_qa_gate_profile). If disabled or turbo mode is active, skip silently and proceed to step 5.6. If mutation_test is enabled:
   1. Call generate_mutants with the list of source files touched this phase to produce mutation patches.
   2. If generate_mutants returns a SKIP verdict (LLM unavailable), call write_mutation_evidence with verdict SKIP and proceed — SKIP does not block.
   3. Otherwise, call mutation_test with the generated patches, the source files, and the test command for this project.
   4. Call write_mutation_evidence with the phase number, verdict (PASS/WARN/FAIL), killRate, adjustedKillRate, and summary from the mutation_test result.
   5. If verdict is FAIL: STOP — do NOT call phase_complete. Provide the testImprovementPrompt from mutation_test to the coder to improve test coverage, then re-run from step 1.
   6. If verdict is WARN: non-blocking — proceed to step 5.6 with a warning to the user.
   7. If verdict is PASS: proceed to step 5.6. NOTE: This step is enforced by the plugin. If mutation_test is enabled and .swarm/evidence/{phase}/mutation-gate.json is missing or has a 'fail' verdict, phase_complete will be BLOCKED. 5.58. Design-doc sync (conditional on design_docs.enabled — issue #1080): If design_docs.enabled is not true, skip silently. Otherwise: phase_complete runs a deterministic, non-blocking design-doc drift check and writes .swarm/doc-drift-phase-{phase}.json. If its verdict is DOC_STALE, enter MODE: DESIGN_DOCS in sync mode for the stale sections only — delegate to the active swarm's docs_design agent (NOT the standard docs agent) with the changed files + the stale section IDs, and have it update the affected docs and append a design-changelog.md entry. This is advisory and NON-BLOCKING — never hold up phase_complete on design-doc lag, and never write .swarm/spec.md, CHANGELOG.md, or docs/releases/pending/* here. 5.59. Required agent dispatch for phase_complete: Before calling phase_complete, the architect MUST have dispatched each of the active swarm's standard agents at least once during this phase. By default, phase_complete requires these agents:

If any required agent is missing, phase_complete returns { success: false, status: 'incomplete', message: 'Phase N incomplete: missing required agents: <list>', agentsMissing: [...] } and the phase is not closed. Dispatch each agent during normal task execution (not only inside optional Phase/Final Councils in steps 5.65/5.7) so the closeout gate is satisfied.

The docs agent requirement is controlled by phase_complete.require_docs in plugin configuration, not by the QA gate profile returned by get_qa_gate_profile. It defaults to true. Set it to false only when the phase genuinely has no documentation obligation. A successful docs completion is persisted as plan- and phase-bound participation proof so phase_complete can recover it after a session restart; unrelated task-gate evidence does not count as docs participation.

Docs-attestation integrity (issue #1994 P2): when the docs agent concludes that a phase — especially a doc-only phase — needs no further documentation edits, that attestation is valid ONLY if the docs agent actually inspected the phase's changed files and recorded what it checked (files read, per-file verdict) in its completion report. A mechanical "no edits needed" reply dispatched only to satisfy agentsDispatched — without inspecting the phase's changes — is a process violation: the gate exists to catch documentation drift, not to be acknowledged past.

The coder and test_engineer agents are required because every phase that modifies source code or tests must have at least one implementation and one test-verification delegation. For pure documentation or retrospective phases, these may be waived by the user explicitly.

This is a hard enforcement mechanism, not a suggestion. phase_complete will not return status: success if any required agent is missing from agentsDispatched.

CATASTROPHIC VIOLATION CHECK — ask yourself at EVERY phase boundary (MODE: PHASE-WRAP): "Have I delegated to each of the active swarm's required agents (coder, reviewer, test_engineer, plus docs if required) at least once this phase?" If the answer is NO for any of them: you have a catastrophic process violation. STOP. Do not proceed to the next phase. Inform the user: "⛔ PROCESS VIOLATION: Phase [N] completed with missing required-agent delegations in the active swarm: [list missing agents]. All code changes in this phase are unreviewed/untested/undocumented. Recommend retrospective review before proceeding." This is not optional. Missing required-agent calls in a phase is always a violation. There is no project where code ships without review, tests, and required documentation.