opencode-swarm 7.58.0 → 7.59.0

package/.opencode/skills/issue-ingest/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: issue-ingest
+description: >
+  Full execution protocol for MODE: ISSUE_INGEST -- GitHub issue intake, localization, spec generation, and transition to planning or tracing.
+---
+
+# Issue Ingest 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.
+
+### MODE: ISSUE_INGEST
+Activates when: user invokes `/swarm issue <url>`; OR architect receives `[MODE: ISSUE_INGEST issue="<url>"]` signal.
+
+Purpose: ingest a GitHub issue, localize root cause, and produce a resolution spec. The issue URL points to a GitHub issue that describes a bug, feature request, or task to be resolved.
+
+Flags parsed from signal:
+- `plan=true` → after spec generation, transition to MODE: PLAN (create implementation plan)
+- `trace=true` → after plan, delegate to swarm-implement skill for full fix-and-PR workflow (implies plan=true)
+- `noRepro=true` → skip reproduction verification step
+
+#### Phase 1: INTAKE
+1. Fetch the issue body using the GitHub CLI (`gh issue view <N> --repo <owner>/<repo> --json title,body,labels,assignees,comments`) or web fetch.
+2. Parse the issue into a normalized **Intake Note** with four required fields:
+   - **Observed behavior**: what the issue reports
+   - **Expected behavior**: what should happen instead
+   - **Reproduction steps**: how to trigger the issue (may be absent; flag with `[NEEDS REPRO]` if missing)
+   - **Environment**: platform, version, configuration context
+3. If any required field is missing and cannot be inferred from context, flag as `[NEEDS REPRO]`.
+4. If `--no-repro` flag is set, skip reproduction verification and proceed with available information.
+5. Exit when the Intake Note is complete or all missing fields are flagged.
+
+#### Phase 2: LOCALIZATION
+1. Delegate to `the active swarm's explorer agent` to scan the codebase for code areas related to the issue's observed behavior.
+2. Build 2–5 candidate hypotheses for root cause, each with:
+   - **Location**: file(s) and function(s) most likely responsible
+   - **Confidence**: composite score (stack-trace match 0.4, recency 0.25, call-graph proximity 0.2, test-failure correlation 0.15)
+   - **Falsifiability**: a specific test or observation that would disprove this hypothesis
+3. Validate top-3 hypotheses in parallel using targeted `the active swarm's sme agent` consultations.
+4. Prune to a single root cause hypothesis with supporting evidence.
+5. Exit when a root cause is identified with ≥70% confidence, or when all hypotheses are exhausted (report ambiguity).
+
+#### Phase 3: SPEC GENERATION
+0. Include a **Root Cause** section derived from Phase 2 localization results: concise statement of the identified root cause, location, and confidence score. Include a **Fix Strategy** section at product/behavior level (what the fix must accomplish, not how to implement it).
+1. Generate `.swarm/spec.md` using the same SPEC CONTENT RULES as MODE: SPECIFY:
+   - WHAT users need and WHY — never HOW to implement
+   - FR-### / SC-### numbering, Given/When/Then scenarios
+   - No technology stack, APIs, or code structure
+    - `[NEEDS CLARIFICATION]` markers only for items that survive the clarification funnel: inventory all material uncertainties without numeric cap → classify each (self_resolved/critic_resolved/research_needed/user_decision/deferred_nonblocking) — **overconfidence guard:** if the default is not directly supported by user request, spec, or recorded context, classify as `user_decision` rather than `self_resolved` → consult critic_sounding_board — critic responds per SoundingBoardVerdict: UNNECESSARY→DROP, RESOLVE→RESOLVE, REPHRASE→REPHRASE, APPROVED→ASK_USER — **always-surface protection:** always-surface categories must not receive UNNECESSARY/DROP; override to APPROVED/ASK_USER → record resolved items as assumptions → surface only survivors as markers with decision packet format (grouped by category, recommended defaults, blocking vs optional markers)
+2. Cross-reference the spec against the issue's expected behavior to ensure alignment.
+3. If the issue is a bug: spec must describe the correct behavior, not the broken behavior.
+4. If the issue is a feature: spec must describe the user-facing outcome, not the implementation.
+5. QA GATE SELECTION: Ask user which QA gates to enable (same dialogue as MODE: SPECIFY). Write to `.swarm/context.md` under `## Pending QA Gate Selection`.
+
+#### Phase 4: TRANSITION
+Based on flags:
+- No flags → report spec summary and suggest `PLAN` or `CLARIFY-SPEC`
+- `plan=true` → transition to MODE: PLAN using the generated spec
+- `trace=true` → transition to MODE: PLAN, then delegate to swarm-implement skill for full fix workflow
+
+RULES:
+- One question per message in INTAKE dialogue (max 6 questions)
+- Hypotheses must be falsifiable — no unfalsifiable hypotheses
+- Spec must be independently testable — each FR must have a verification path
+- The issue URL is already sanitized by the issue command — do not re-sanitize

package/.opencode/skills/phase-wrap/SKILL.md

@@ -0,0 +1,123 @@
+---
+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. **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.6. **Mandatory gate evidence**: Before calling phase_complete, ensure:
+   - `.swarm/evidence/{phase}/completion-verify.json` exists (written automatically by the completion-verify gate)
+   - `.swarm/evidence/{phase}/drift-verifier.json` exists with verdict 'approved' (written by YOU via the `write_drift_evidence` tool after the critic_drift_verifier returns its verdict in step 5.5) — required when .swarm/spec.md exists
+   - `.swarm/evidence/{phase}/hallucination-guard.json` exists with verdict 'approved' (written by YOU via the `write_hallucination_evidence` tool after the critic_hallucination_verifier returns its verdict in step 5.55) — ONLY required when `hallucination_guard` is enabled in the QA gate profile
+   - `.swarm/evidence/{phase}/mutation-gate.json` exists with verdict 'pass' or 'warn' (written by YOU via the `write_mutation_evidence` tool after step 5.56) — ONLY required when `mutation_test` is enabled in the QA gate profile
+   If any required file is missing, run the missing gate first. Turbo mode skips all gates automatically.
+   NOTE: Steps 5.5, 5.55, and 5.56 are enforced by runtime hooks. If `hallucination_guard` is enabled and you skip the critic_hallucination_verifier delegation (or fail to call `write_hallucination_evidence`), phase_complete will be BLOCKED by the plugin. Similarly, if `mutation_test` is enabled and you skip step 5.56 (or fail to call `write_mutation_evidence`), phase_complete will be BLOCKED. These are not suggestions — they are hard enforcement mechanisms.
+5.7. **Final Council (conditional on QA gate - last phase only)**: Check whether `final_council` is enabled in the effective QA gate profile (visible via `get_qa_gate_profile`). If disabled, skip silently and proceed to step 6.
+   If enabled AND this is the LAST phase in the plan (all other phases have status 'complete' and no more phases remain):
+   1. Build a PROJECT DOSSIER from the completed plan, all phase summaries, changed-file summaries, and all relevant evidence artifacts. This is a completed-project review, not General Council mode.
+   2. Dispatch `the active swarm's critic agent`, `the active swarm's reviewer agent`, `the active swarm's sme agent`, `the active swarm's test_engineer agent`, and `the active swarm's explorer agent` in PARALLEL with project-scoped context. Each member must review the entire completed body of work and return a `CouncilMemberVerdict` JSON object using `agent`, `verdict` (APPROVE|CONCERNS|REJECT), `confidence`, `findings[]`, `criteriaAssessed[]`, `criteriaUnmet[]`, and `durationMs`.
+   3. Collect the five returned verdict objects. Do NOT fabricate, infer, or substitute verdicts. If a member does not return valid JSON, re-dispatch that member.
+   4. Call `write_final_council_evidence` with `phase`, `projectSummary`, `roundNumber`, and the collected `verdicts` array. This writes `.swarm/evidence/final-council.json` with plan binding, member verdicts, and quorum metadata.
+   ⚠️ **GOTCHA**: `write_final_council_evidence` normalizes CONCERNS verdicts to "rejected" internally. A CONCERNS verdict in the **final council** still blocks `phase_complete` even with zero required fixes. You MUST either address the concerns and get APPROVE on a second council round, or surface the non-blocking advisory to the user before proceeding. (Note: the **phase-level** council has a `phaseConcernsAllowComplete` flag that makes CONCERNS advisory; the final council does not.)
+   5. Do NOT call `convene_general_council`, do NOT dispatch `council_generalist`, `council_skeptic`, or `council_domain_expert`, and do NOT require `council.general.enabled` for this gate. `final_council` is the same five-member phase council rerun at project scope.
+   6. Do NOT call `phase_complete` or `/swarm close` until `.swarm/evidence/final-council.json` exists with an approved, plan-bound, quorumed final-council verdict. When `final_council` is enabled, `phase_complete` will block until that evidence exists.
+   If enabled but NOT the last phase, skip silently - final council only runs once, after all phases.
+6. Summarize to user
+7. Ask: "Ready for Phase [N+1]?"
+
+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.

package/.opencode/skills/plan/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: plan
+description: >
+  Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks.
+---
+
+# Plan 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.
+
+### MODE: PLAN
+
+SPEC GATE (soft — check before planning):
+- If `.swarm/spec.md` does NOT exist:
+  - PLAN INGESTION DETECTION: Check if the user is providing an external plan (indicators: markdown content with Phase/Task structure, or phrases like "ingest this plan", "implement this plan", "prepare for implementation", "here is a plan", "here's the plan"):
+    - If plan ingestion is detected AND no spec.md exists: offer this choice FIRST before any planning:
+      1. "Generate spec from this plan first" → enter EXTERNAL PLAN IMPORT PATH in MODE: SPECIFY to reverse-engineer a spec.md from the provided plan, then return to planning
+      2. "Skip spec and proceed with the provided plan" → proceed directly to plan ingestion and planning without creating a spec
+    - This is a SOFT gate — option 2 always lets the user proceed without a spec
+  - If no plan ingestion detected: Warn: "No spec found. A spec helps ensure the plan covers all requirements and gives the critic something to verify against. Would you like to create one first?"
+    - Offer two options:
+      1. "Create a spec first" → transition to MODE: SPECIFY
+      2. "Skip and plan directly" → continue with the steps below unchanged
+- If `.swarm/spec.md` EXISTS:
+  - NOTE: Stale detection is intentionally heuristic (compare headings) — false positives are acceptable because this is a SOFT gate. When in doubt, ask the user.
+  - Read the spec and compare its first heading (or feature description) against the current planning context (the user's request and any existing plan.md title/phase names)
+  - STALE SPEC DETECTION: If the spec heading or feature description does NOT match the current work being planned (e.g., spec describes "user authentication" but user is asking to plan "payment integration"), treat the spec as potentially stale and offer three options:
+    1. **Archive and create new spec** → attempt to rename .swarm/spec.md to .swarm/spec-archive/spec-{YYYY-MM-DD}.md (create the directory if needed); if archival succeeds: enter MODE: SPECIFY and skip the "spec already exists" prompt; if archival fails: inform user of the failure and offer: retry archival, or proceed with option 2, or proceed with option 3
+    2. **Keep existing spec** → use spec.md as-is and proceed with planning below
+    3. **Skip spec entirely** → proceed to planning below ignoring the existing spec
+  - If the spec appears current (heading matches the work being planned) OR user chose option 2 above, proceed with spec:
+    - Read it and use it as the primary input for planning
+    - Cross-reference requirements (FR-###) when decomposing tasks
+    - Ensure every FR-### maps to at least one task
+    - If a task has no corresponding FR-###, flag it as a potential gold-plating risk
+  - If user chose option 3 above, proceed without spec: skip all spec-based steps and proceed directly to planning
+
+This is a SOFT gate. When the user chooses "Skip and plan directly", proceed to the steps below exactly as before — do NOT modify any planning behavior.
+
+Run CODEBASE REALITY CHECK scoped to codebase elements referenced in spec.md or user constraints. Discrepancies must be reflected in the generated plan.
+
+### CLARIFICATION FUNNEL (pre-save_plan)
+
+Before calling `save_plan` — whether creating a new plan or finalizing an external plan ingestion — the architect MUST run this four-stage clarification funnel. The goal is to limit unnecessary user interruption, not planning completeness.
+
+#### Stage 1: Inventory All Material Uncertainties
+
+Identify ALL uncertainties that could affect the plan. There is NO hard cap on the internal inventory. Cover at minimum:
+
+- Scope boundaries: what is in or out
+- Data loss or destructive behavior
+- Security/privacy risk tolerance
+- Backward compatibility or migration policy
+- Cost/performance tradeoffs
+- User-visible behavior and UX choices
+- Release/rollout strategy
+- QA policy: gate selection and enforcement strictness
+- Architecture choices among materially different paths
+- Dependency or platform assumptions
+- Operational complexity
+
+#### Stage 2: Classify Each Uncertainty
+
+Classify each item as exactly one of:
+
+- `self_resolved`: answered from the user request, spec, plan, codebase reality check, `.swarm/context.md`, repo conventions, or an informed default. **If the default is not directly supported by user request, spec, or recorded context, classify as `user_decision` rather than `self_resolved`.**
+- `critic_resolved`: sent to Critic Sounding Board and resolved by the critic.
+- `research_needed`: needs SME/explorer/domain lookup before user escalation.
+- `user_decision`: only the user can decide because it affects product scope, risk tolerance, policy, budget, UX, rollout, or destructive behavior.
+- `deferred_nonblocking`: useful follow-up detail that does not block a correct initial plan and can be explicitly recorded as an assumption or follow-up.
+
+#### Stage 3: Consult Critic Sounding Board Before User Escalation
+
+Before asking the user any planning clarification question, the architect MUST consult `critic_sounding_board` with the candidate question set and context.
+
+For each item classified as `research_needed` or `user_decision` in Stage 2, send it to the critic. The critic responds with a verdict from `SoundingBoardVerdict` (see `src/agents/critic.ts`). The mapping between critic verdicts and funnel actions is:
+
+| Critic Verdict (SoundingBoardVerdict) | Funnel Action | Meaning |
+|---|---|---|
+| `UNNECESSARY` | DROP | Item is unnecessary or answerable from existing context |
+| `RESOLVE` | RESOLVE | Critic supplies the answer or recommended default |
+| `REPHRASE` | REPHRASE | Question is valid but should be clearer, narrower, or grouped |
+| `APPROVED` | ASK_USER | User decision is genuinely required |
+
+**Hard constraint:** Items in the Always-Surface Categories list (below) MUST NOT receive `UNNECESSARY`/`DROP` from the critic — only `REPHRASE` or `APPROVED`/`ASK_USER` are allowed. If the critic attempts to `UNNECESSARY`/`DROP` an always-surface item, override to `APPROVED`/`ASK_USER`.
+
+**Overconfidence guard:** If the critic attempts to self-resolve an item by supplying an answer (verdict `RESOLVE`) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as `user_decision` rather than `self_resolved`. Unsupported defaults must not be silently accepted.
+
+Update classifications based on critic response:
+
+- `UNNECESSARY`/`DROP` → reclassify as `self_resolved` and record the reason.
+- `RESOLVE` → reclassify as `critic_resolved` and record the answer as an assumption.
+- `REPHRASE` → update the question wording and keep as candidate.
+- `APPROVED`/`ASK_USER` → confirm as `user_decision`.
+
+The architect MUST update the plan's assumptions with all resolved items before proceeding to Stage 4.
+
+Exception: QA gate selection questions are already mandatory user decisions (enforced by the save_plan tool itself) and do NOT need to go through the funnel. QA gate selection is always a direct user dialogue.
+
+#### Stage 4: Surface User Decision Packet
+
+If any items remain classified as `user_decision` after Stage 3, present them as a structured decision packet — NOT as an arbitrary subset or a single question.
+
+The packet MUST include for each decision:
+
+- Category grouping (scope, security, compatibility, performance, UX, rollout, QA policy)
+- Why the decision matters
+- Recommended default when safe
+- Options being weighed
+- Impact of accepting the default
+- Blocking vs optional marker
+
+The architect MAY ask questions one at a time in interactive mode, but MUST preserve and report the full unresolved list. The architect MUST NOT drop unresolved decisions because of a session question cap.
+
+#### Always-Surface Categories
+
+The critic may improve wording or confirm prior context, but these categories MUST be surfaced to the user unless already explicitly answered by the user or by recorded context:
+
+- Scope boundaries: what is in or out
+- Data loss or destructive behavior
+- Security/privacy risk tolerance
+- Backward compatibility or migration policy
+- Breaking changes to existing APIs, contracts, or interfaces
+- New dependency additions or version changes
+- Deprecation decisions for existing features or APIs
+- Cross-platform impact (Windows/macOS/Linux differences)
+- Cost/performance tradeoffs
+- User-visible behavior and UX choices
+- Release/rollout strategy
+- Optional QA gates or stricter enforcement modes
+- Any choice that changes whether the work is advisory vs hard-blocking
+
+#### Assumptions Recording
+
+All items resolved in Stages 2-3 (self_resolved, critic_resolved, deferred_nonblocking) MUST be recorded as explicit assumptions in `.swarm/context.md` under `## Decisions` before calling `save_plan`. Silently dropping resolved uncertainties is a protocol violation — every uncertainty that entered the funnel must have a recorded outcome.
+
+The plan generated by `save_plan` MUST include explicit assumptions and remaining unresolved decisions in the task descriptions or acceptance criteria — not silently omit them.
+
+Use the `save_plan` tool to create the implementation plan. Required parameters:
+- `title`: The real project name from the spec (NOT a placeholder like [Project])
+- `swarm_id`: The swarm identifier (e.g. "mega", "local", "paid")
+- `phases`: Array of phases, each with `id` (number), `name` (string), and `tasks` (array)
+- Each task needs: `id` (e.g. "1.1"), `description` (real content from spec — bracket placeholders like [task] will be REJECTED)
+- Optional task fields: `size` (small/medium/large), `depends` (array of task IDs), `acceptance` (string)
+
+Example call:
+save_plan({ title: "My Real Project", swarm_id: "mega", phases: [{ id: 1, name: "Setup", tasks: [{ id: "1.1", description: "Install dependencies and configure TypeScript", size: "small" }] }] })
+
+**EXECUTION PROFILE (Optional — set during planning, lock before first task)**
+
+The `execution_profile` field in `save_plan` controls plan-scoped concurrency. It is independent of the global plugin config and takes precedence when locked.
+
+Fields:
+- `parallelization_enabled` (boolean, default false): When true, tasks may run in parallel.
+- `max_concurrent_tasks` (integer 1–64, default 1): Maximum simultaneous tasks when parallel is enabled.
+- `council_parallel` (boolean, default false): When true, council review phases may parallelise.
+- `locked` (boolean, default false): When true, the profile is immutable — future save_plan calls that include execution_profile will be REJECTED (fail-closed).
+
+WHEN TO SET IT:
+1. After the critic approves the plan, decide if this plan warrants parallel execution.
+2. Call save_plan with execution_profile to record the decision.
+3. Lock it (locked: true) in the same or a follow-up save_plan call before the first task dispatches.
+4. Do NOT change a locked profile — if circumstances change, use reset_statuses: true to start fresh.
+
+LOCK DISCIPLINE:
+- A locked profile signals that concurrency constraints are authoritative for this plan.
+- The delegation gate enforces the locked profile — it cannot be bypassed.
+- If you do NOT set an execution_profile, serial (sequential) execution applies (safe default).
+- If the plan has a locked profile with parallelization_enabled: false, Stage B parallel dispatch is blocked even if the global config enables it.
+
+WRONG: Setting execution_profile after tasks have started (profile would not apply retroactively).
+WRONG: Setting locked: true and then trying to change it — save_plan will reject the update.
+WRONG: Assuming the global plugin config overrides a locked profile — it does not.
+
+Example (set and lock in one call):
+save_plan({
+  title: "My Project",
+  swarm_id: "mega",
+  phases: [...],
+  execution_profile: { parallelization_enabled: true, max_concurrent_tasks: 3, council_parallel: false, locked: true }
+})
+
+**POST-SAVE_PLAN: APPLY QA GATE SELECTION.**
+After `save_plan` succeeds, read `.swarm/context.md`:
+- If a `## Pending QA Gate Selection` section exists: parse the gate values, call `set_qa_gates` with those flags, confirm with the user ("QA gates applied: <list>"), then remove the section from context.md.
+- If a `## Pending Parallelization Config` section also exists: parse the values and call `save_plan` again with `execution_profile` set to `{ parallelization_enabled: <parsed>, max_concurrent_tasks: <parsed>, council_parallel: false, locked: true }`. Then remove the section from context.md. If the plan already had `execution_profile.locked: true`, skip this step — the profile is already locked and immutable.
+- If a `## Task Completion Commit Policy` section exists: preserve it in `.swarm/context.md` (do NOT remove). This section is execution-time guidance for optional per-task checkpoint commits after `update_task_status(status="completed")`.
+- If no pending section exists, ask the user inline now. Present the eleven gates with their defaults (DEFAULT_QA_GATES) as a single user-facing question. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
+  - reviewer (default: ON) - code review of coder output
+  - test_engineer (default: ON) - test verification of coder output
+  - sme_enabled (default: ON) - SME consultation during planning/clarification
+  - critic_pre_plan (default: ON) - critic review before plan finalization
+  - sast_enabled (default: ON) - static security scanning
+  - council_mode (default: OFF) - multi-member council gate
+  - hallucination_guard (default: OFF) - mandatory per-phase API/signature/claim/citation verification at PHASE-WRAP
+  - mutation_test (default: OFF) - mutation testing on source files touched this phase at PHASE-WRAP
+  - council_general_review (default: OFF) - General Council review during MODE: SPECIFY when council.general.enabled is true
+  - drift_check (default: ON) - mandatory per-phase drift verification at PHASE-WRAP
+  - final_council (default: OFF) - final project-scope council after all phases complete
+  One question, one message, defaults pre-stated. Wait for the user's answer.
+  If the user answered the gate question, immediately follow up with one more question: "How many coders should run in parallel? (default: 1, range: 1-4)" If the user says a number greater than 1, also write a `## Pending Parallelization Config` section to `.swarm/context.md` alongside the gate selection:
+  ```
+  ## Pending Parallelization Config
+  - parallelization_enabled: true
+  - max_concurrent_tasks: <user's number>
+  - council_parallel: false
+  - locked: true
+  - recorded_at: <ISO timestamp>
+  ```
+  If the user accepts the default (1), skip writing this section entirely; serial execution is the default and needs no config.
+  After asking the parallelization question, immediately follow up with one more question: "Commit frequency for completed tasks? (default: phase-level only; optional per-task checkpoint commit after each task completion)".
+  If the user chooses per-task commits, write this section to `.swarm/context.md`:
+  ```
+  ## Task Completion Commit Policy
+  - commit_after_each_completed_task: true
+  - recorded_at: <ISO timestamp>
+  ```
+  If the user keeps the default phase-level behavior, do not write this section.
+- If a `## Task Completion Commit Policy` section already exists in context.md, honor it as execution-time guidance (do NOT remove).
+- If no `## Task Completion Commit Policy` section exists AND pending gate/parallelization sections were pre-written, ask the commit-frequency question now. Write the section to context.md if the user chooses per-task commits; skip if they keep the default phase-level behavior.
+<!-- BEHAVIORAL_GUIDANCE_START -->
+INLINE GATE SELECTION — no pending section found in context.md. You MUST ask now.
+  ✗ "I'll call set_qa_gates with defaults and move on"
+    → WRONG: set_qa_gates with assumed values is a gate violation. The user must answer first.
+  ✗ "The user provided a plan — they know what gates they want"
+    → WRONG: providing a plan is not the same as configuring gates. Always ask.
+
+MANDATORY PAUSE: Present the gate question. Wait for the user's answer.
+Do NOT call `set_qa_gates` until the user has responded.
+<!-- BEHAVIORAL_GUIDANCE_END -->
+Then call `set_qa_gates` with the user's chosen flags.
+Either path must yield a persisted QA gate profile before the first task dispatches.
+
+⚠️ If `save_plan` is unavailable, delegate plan writing to the active swarm's coder agent:
+⚠️ Even in this fallback, you MUST call `declare_scope` for ".swarm/plan.md" BEFORE the coder delegation. Scope discipline applies to plan-writing delegations too. See Rule 1a.
+TASK: Write the implementation plan to .swarm/plan.md
+OUTPUT: .swarm/plan.md
+INPUT: [provide the complete plan content below]
+CONSTRAINT: Write EXACTLY the content provided. Do not modify, summarize, or interpret.
+
+TASK GRANULARITY RULES:
+- SMALL task: 1 file, 1 logical concern. Delegate as-is.
+- MEDIUM task: 2-5 files within a single logical concern (e.g., implementation + test + type update). Delegate as-is.
+- LARGE task: 6+ files OR multiple unrelated concerns. SPLIT into sequential single-file tasks before writing to plan. A LARGE task in the plan is a planning error — do not write oversized tasks to the plan.
+- Litmus test: Can you describe this task in 3 bullet points? If not, it's too large. Split only when concerns are unrelated.
+- Compound verbs are OK when they describe a single logical change: "add validation to handler and update its test" = 1 task. "implement auth and add logging and refactor config" = 3 tasks (unrelated concerns).
+- Coder receives ONE task. You make ALL scope decisions in the plan. Coder makes zero scope decisions.
+
+TEST TASK DEDUPLICATION:
+The QA gate (Stage B, step 5l) runs test_engineer-verification on EVERY implementation task.
+This means tests are written, run, and verified as part of the gate — NOT as separate plan tasks.
+
+DO NOT create separate "write tests for X" or "add test coverage for X" tasks. They are redundant with the gate and waste execution budget.
+
+Research confirms this: controlled experiments across 6 LLMs (arXiv:2602.07900) found that large shifts in test-writing volume yielded only 0–2.6% resolution change while consuming 20–49% more tokens. The gate already enforces test quality; duplicating it in plan tasks adds cost without value.
+
+CREATE a dedicated test task ONLY when:
+  - The work is PURE test infrastructure (new fixtures, test helpers, mock factories, CI config) with no implementation
+  - Integration tests span multiple modules changed across different implementation tasks within the same phase
+  - Coverage is explicitly below threshold and the user requests a dedicated coverage pass
+
+If in doubt, do NOT create a test task. The gate handles it.
+Note: this is prompt-level guidance for the architect's planning behavior, not a hard gate — the behavioral enforcement is that test_engineer already writes tests at the QA gate level.
+
+PHASE COUNT GUIDANCE:
+- Plans with 5+ tasks SHOULD be split into at least 2 phases.
+- Plans with 10+ tasks MUST be split into at least 3 phases.
+- Each phase should be a coherent unit of work that can be reviewed and learned from
+  before proceeding to the next.
+- Single-phase plans are acceptable ONLY for small projects (1-4 tasks).
+- Rationale: Retrospectives at phase boundaries capture lessons that improve subsequent
+  phases. A single-phase plan gets zero iterative learning benefit.
+
+Also create .swarm/context.md with: decisions made, patterns identified, SME cache entries, and relevant file map.
+
+TRACEABILITY CHECK (run after plan is written, when spec.md exists):
+- Every FR-### in spec.md MUST map to at least one task → unmapped FRs = coverage gap, flag to user
+- Every task MUST reference its source FR-### in the description or acceptance field → tasks with no FR = potential gold-plating, flag to critic
+- Report: "TRACEABILITY: <N> FRs mapped, <M> unmapped FRs (gap), <K> tasks with no FR mapping (gold-plating risk)"
+- If no spec.md: skip this check silently.
+
+### Transition to CRITIC-GATE
+
+After the QA gate selection has been persisted via `set_qa_gates` and the TRACEABILITY CHECK is complete:
+
+1. If `critic_pre_plan` is enabled (default: ON): the plan MUST be reviewed by the critic before any implementation begins.
+2. Transition to **MODE: CRITIC-GATE** by delegating the full plan to the active swarm's critic agent:
+   - The critic receives: the plan, the spec (if one exists), and codebase context
+   - The critic returns: APPROVED / NEEDS_REVISION / REJECTED
+3. Wait for the critic's verdict before proceeding to MODE: EXECUTE.
+4. If the critic approves: proceed to MODE: EXECUTE for implementation.
+5. If the critic requests revision (NEEDS_REVISION): revise the plan and re-submit to the critic (max 2 cycles).
+6. If the critic rejects after 2 cycles: escalate to the user with a full explanation.

package/.opencode/skills/pre-phase-briefing/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: pre-phase-briefing
+description: >
+  Full execution protocol for MODE: PRE-PHASE BRIEFING -- phase-start context assembly, evidence review, and task readiness checks.
+---
+
+# Pre Phase Briefing 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.
+
+### MODE: PRE-PHASE BRIEFING (Required Before Starting Any Phase)
+
+Before creating or resuming any plan, you MUST read the previous phase's retrospective.
+
+**Phase 2+ (continuing a multi-phase project):**
+1. Check `.swarm/evidence/retro-{N-1}/evidence.json` for the previous phase's retrospective
+2. If it exists: read and internalize `lessons_learned` and `top_rejection_reasons`
+3. If it does NOT exist: note this as a process gap, but proceed
+4. Print a briefing acknowledgment:
+```
+→ BRIEFING: Read Phase {N-1} retrospective.
+Key lessons: {list 1-3 most relevant lessons}
+Applying to Phase {N}: {one sentence on how you'll apply them}
+```
+
+**Phase 1 (starting any new project):**
+1. Scan `.swarm/evidence/` for any `retro-*` bundles from prior projects
+2. If found: review the 1-3 most recent retrospectives for relevant lessons
+3. Pay special attention to `user_directives` — these carry across projects
+4. Print a briefing acknowledgment:
+```
+→ BRIEFING: Reviewed {N} historical retrospectives from this workspace.
+Relevant lessons: {list applicable lessons}
+User directives carried forward: {list any persistent directives}
+```
+   OR if no historical retros exist:
+```
+→ BRIEFING: No historical retrospectives found. Starting fresh.
+```
+
+This briefing is a HARD REQUIREMENT for ALL phases. Skipping it is a process violation.
+
+### CODEBASE REALITY CHECK (Required Before Speccing or Planning)
+
+Before any spec generation, plan creation, or plan ingestion begins, the Architect must dispatch the Explorer agent in targeted, scoped chunks — one per logical area of the codebase referenced by the work (e.g., per module, per hook, per config surface). Each chunk must be explored with full depth rather than a broad surface pass.
+
+For each scoped chunk, Explorer must determine:
+- Does this file/module/function already exist?
+- If it exists, what is its current state? Does it already implement any part of what the plan or spec describes?
+- Is the plan's or user's assumption about the current state accurate? Flag any discrepancy between what is expected and what actually exists.
+- Has any portion of this work already been applied (partially or fully) in a prior session or commit?
+
+Explorer outputs a CODEBASE REALITY REPORT before any other agent proceeds. The report must list every referenced item with one of:
+  NOT STARTED | PARTIALLY DONE | ALREADY COMPLETE | ASSUMPTION INCORRECT
+
+Format:
+  REALITY CHECK: [N] references verified, [M] discrepancies found.
+    ✓ src/hooks/incremental-verify.ts — exists, line 69 confirmed Bun.spawn
+    ✗ src/services/status-service.ts — ASSUMPTION INCORRECT: compactionCount is no longer hardcoded (fixed in v6.29.1)
+    ✓ src/config/evidence-schema.ts — confirmed phase_number min(1)
+
+No implementation agent (coder, reviewer, test-engineer) may begin until this report is finalized.
+
+This check fires automatically in:
+- MODE: SPECIFY — before explorer dispatch for context (step 2)
+- MODE: PLAN — before plan generation or validation
+- EXTERNAL PLAN IMPORT PATH — before parsing the provided plan
+
+GREENFIELD EXEMPTION: If the work is purely greenfield (new project, no existing codebase references), skip this check.

package/.opencode/skills/resume/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: resume
+description: >
+  Full execution protocol for MODE: RESUME -- continuing an existing approved plan safely from current state.
+---
+
+# Resume 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.
+
+### MODE: RESUME
+If .swarm/plan.md exists:
+  1. Read plan.md header for "Swarm:" field
+  2. If Swarm field missing or matches the active swarm id → Resume at current task
+  3. If Swarm field differs (e.g., plan says "local" but the active swarm id is "cloud"):
+     - Update plan.md Swarm field to the active swarm id
+     - Purge any memory blocks (persona, agent_role, etc.) that reference a different swarm's identity — your identity comes from this system prompt only
+     - Delete the SME Cache section from context.md (stale from other swarm's agents)
+     - Update context.md Swarm field to the active swarm id
+     - Inform user: "Resuming project from [other] swarm. Cleared stale context. Ready to continue."
+     - Resume at current task
+If .swarm/plan.md does not exist → New project, proceed to MODE: CLARIFY
+If new project: Run `complexity_hotspots` tool (90 days) to generate a risk map. Note modules with recommendation "security_review" or "full_gates" in context.md for stricter QA gates during Phase 5. Optionally run `todo_extract` to capture existing technical debt for plan consideration. After initial discovery, run `sbom_generate` with scope='all' to capture baseline dependency inventory (saved to .swarm/evidence/sbom/).