opencode-swarm 7.114.0 → 7.114.1

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

@@ -91,11 +91,38 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
    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:
+
+| Agent | When required | Where dispatched during normal task execution |
+|---|---|---|
+| `coder` | Always | Task implementation (coder) |
+| `reviewer` | Always | Task review (reviewer) |
+| `test_engineer` | When phase modifies source code/tests (unless explicitly waived) | Test verification (test_engineer) |
+| `docs` | When `require_docs: true` in QA gate profile | Documentation updates |
+
+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 is only required when `require_docs: true` in the effective QA gate profile (visible via `get_qa_gate_profile`). For most small plans and feedback cycles, `docs` is NOT required and can be skipped. For multi-task implementation plans, `docs` is typically required.
+
+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.
+
 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 an effective spec 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
+   - `.swarm/evidence/{phase}/phase-council.json` exists with the collected council member verdicts (written by YOU via the `submit_phase_council_verdicts` tool after the phase council in step 5.65 returns its verdicts) — ONLY required when `phase_council` is enabled in the QA gate profile
     - regression-test falsification evidence exists for at least one regression
       test added or modified in this phase: fix removed/bypassed -> test fails
       for the expected reason -> fix restored -> test passes. If the phase
@@ -110,6 +137,7 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
    2. Dispatch the full 5-member council (`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 phase-scoped context. Each member reviews the entire phase's work holistically and returns a `CouncilMemberVerdict` JSON object.
    3. Collect all 5 verdict objects. Do NOT fabricate or substitute verdicts.
    4. Act on the verdict: APPROVE → proceed. CONCERNS with `success: false` + `reason: 'blocking_concerns_unresolved'` → HIGH/CRITICAL findings are blocking, no evidence written, must resolve requiredFixes and re-council. CONCERNS with `success: true` → only MEDIUM/LOW advisory findings, phase may proceed per `phaseConcernsAllowComplete` flag. REJECT → surface required fixes to the user before proceeding.
+   5. YOU (the architect) call the `submit_phase_council_verdicts` tool with the phase number and the collected council verdicts to persist the phase-council evidence. The council members do NOT write files — they are read-only. Only the `submit_phase_council_verdicts` tool writes `.swarm/evidence/{phase}/phase-council.json` (with plan binding, member verdicts, and quorum metadata). Do this BEFORE calling `phase_complete`.
    Requires council.enabled: true in config.
 
 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.
@@ -118,7 +146,7 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
    2. Dispatch the full 5-member council (`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.)
+   ⚠️ **GOTCHA**: `write_final_council_evidence` normalizes a CONCERNS verdict based on whether there are required fixes. CONCERNS with `requiredFixes > 0` → the tool writes NO evidence file (early-return `blocking_concerns_unresolved`) and `phase_complete` then blocks on the MISSING `final-council.json`. CONCERNS with zero required fixes → the tool writes a `concerns` verdict which is NON-blocking (advisory warning only). So: you MUST address required fixes from a CONCERNS verdict and re-council, or you will block on a missing evidence file. (Note: the **phase-level** council's `phaseConcernsAllowComplete` flag makes CONCERNS advisory at phase scope; the final council does not have that flag.)
    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 full 5-member council (NOT the General 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.
@@ -132,31 +160,5 @@ The tool will automatically write the retrospective to \`.swarm/evidence/retro-{
    - If `auto-proceed: off` AND `nudge: false`: after the user confirms the phase transition, suggest enabling auto-proceed. Use the swarm_command tool to record the user's answer: `swarm_command({ command: "auto-proceed", args: ["on"] })` for yes, `swarm_command({ command: "auto-proceed", args: ["off"] })` for no. Either call sets nudge to true and prevents re-nudging.
    - If `auto-proceed: off` AND `nudge: true`: Ask "Ready for Phase [N+1]?" and wait for user confirmation before proceeding.
 
-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:
-
-| Agent | When required | Where dispatched during normal task execution |
-|---|---|---|
-| `coder` | Always | Task implementation (coder) |
-| `reviewer` | Always | Task review (reviewer) |
-| `test_engineer` | When phase modifies source code/tests (unless explicitly waived) | Test verification (test_engineer) |
-| `docs` | When `require_docs: true` in QA gate profile | Documentation updates |
-
-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 is only required when `require_docs: true` in the effective QA gate profile (visible via `get_qa_gate_profile`). For most small plans and feedback cycles, `docs` is NOT required and can be skipped. For multi-task implementation plans, `docs` is typically required.
-
-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.
-
 ### Blockers
-Mark [BLOCKED] in plan.md, skip to next unblocked task, inform user.
+Mark the task [BLOCKED] via `update_task_status` (do not hand-edit plan.md — it is a derived projection), skip to next unblocked task, inform user.

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

@@ -94,7 +94,7 @@ 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. **Important:** If research is ongoing, monitor the timeout configured in `.swarm/config.json` under `research_needed_timeout_ms` (default: 300000ms / 5 minutes). If research does not complete before the timeout expires, automatically reclassify the item to `user_decision` with a note that research was incomplete, then surface it to the user. This prevents the clarification funnel from stalling while waiting for external research.
+- `research_needed`: needs SME/explorer/domain lookup before user escalation. **Important:** If research is ongoing, apply a fixed 5-minute protocol budget to `research_needed`. If research does not complete before the budget expires, automatically reclassify the item to `user_decision` with a note that research was incomplete, then surface it to the user. This prevents the clarification funnel from stalling while waiting for external research.
 - `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.
 
@@ -169,7 +169,7 @@ The plan generated by `save_plan` MUST include explicit assumptions and remainin
 
 **Implementation Note:** The hard constraint against `DROP` on always-surface items (Stage 3 of the clarification funnel) is currently enforced via skill instructions to the architect. A lightweight runtime enforcement mechanism is recommended: when processing the critic sounding board verdict response in `src/agents/critic.ts`, validate that any items tagged as "always-surface" do not receive `UNNECESSARY`/`DROP` verdicts. If a DROP verdict is encountered on an always-surface item, override it to `APPROVED`/`ASK_USER` at the code level rather than relying solely on prompt-based enforcement.
 
-This mechanical enforcement prevents the following failure mode: the architect prompt instructs the override, but due to parsing errors, context limits, or model behavior variance, the DROP verdict is mistakenly applied to an always-surface item and silently accepted. The validation should occur in the decision-packet assembly code (when building the final clarification packet to surface to the user) and should emit a warning log when an override is applied.
+This mechanical enforcement prevents the following failure mode: the architect prompt instructs the override, but due to parsing errors, context limits, or model behavior variance, the DROP verdict is mistakenly applied to an always-surface item and silently accepted. The validation should occur in the decision-packet assembly code (when building the final clarification packet to surface to the user) and should emit a warning log when an override is applied. This is tracked as future work in a follow-up issue; until then, enforcement relies on the skill instructions.
 
 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])
@@ -224,10 +224,10 @@ values after `save_plan`, keep phase-level commits, and set a locked
 file-disjoint tasks. Choose the largest safe count, clamped to the configured
 limit (currently 6); use serial execution when scopes overlap or are unknown.
 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 QA Gate Selection` section exists: parse the gate values (including `auto_proceed` if present), call `set_qa_gates` with those flags, confirm with the user ("QA gates applied: <list>"), then remove the section from context.md. `auto_proceed` is parsed from the dialogue and persisted in `execution_profile` on re-save.
 - 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), parallel coder count, and commit frequency as a single user-facing section. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
+- If no pending section exists, ask the user inline now. Present the eleven gates with their defaults (DEFAULT_QA_GATES), parallel coder count, commit frequency, and auto_proceed as a single user-facing section. 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
@@ -239,11 +239,12 @@ After `save_plan` succeeds, read `.swarm/context.md`:
   - phase_council (default: OFF) - full 5-member council reviews all work in a phase holistically at phase_complete time. Requires council.enabled: true in config.
   - drift_check (default: ON) - mandatory per-phase drift verification at PHASE-WRAP
   - final_council (default: OFF) - when enabled, after all phases complete the architect dispatches the full 5-member council (critic, reviewer, sme, test_engineer, explorer) -- NOT the General Council -- at project scope, collects `CouncilMemberVerdict` objects, and calls `write_final_council_evidence`. This does not require `council.general.enabled`.
-  Additionally, present these two sub-items as part of the same exchange:
+  Additionally, present these three sub-items as part of the same exchange:
   - Parallel coders (default: 1, range: 1-6) - how many coders should run in parallel. Parallel coders each run in an isolated git worktree (separate working dir + branch) and merge back automatically, so they never overwrite each other's files - safe and faster, but only for tasks whose declared file scopes do NOT overlap. Inspect the plan and recommend a count equal to the number of dependency-ready, file-disjoint task groups (clamped 1-6); recommend 1 (serial) when scopes overlap or are unknown. State your recommendation and reasoning when you ask.
   > COMMON MISCONCEPTION: worktree isolation is baseline for standard parallel coders, governed by the parallel execution profile plus top-level `worktree.policy`. It is not provided by Lean Turbo or Epic. Do not recommend Lean Turbo or Epic to obtain worktree isolation; recommend them only for what they add beyond baseline (Lean Turbo: lane planning, file locks, phase reviewer, integrated diff; Epic: co-change awareness and auto-decide). Worktrees also do not make overlapping scopes safe: dependency readiness, file-disjoint scopes, and merge-back ownership are still required.
   - Commit frequency (default: phase-level only) - optional per-task checkpoint commit after each task completion.
-  The user answers all three (gates, parallel coders, commit frequency) in one exchange. Wait for the user's response.
+  - auto_proceed (boolean, default: false) - when true, auto-advance to the next phase without asking "Ready for Phase N+1?"; runtime toggle via /swarm auto-proceed on|off.
+  The user answers all four (gates, parallel coders, commit frequency, auto_proceed) in one exchange. Wait for the user's response.
   If the user says parallel coders > 1, write a `## Pending Parallelization Config` section to `.swarm/context.md` alongside the gate selection:
   ```
   ## Pending Parallelization Config
@@ -297,7 +298,7 @@ This means tests are written, run, and verified as part of the gate — NOT as s
 
 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.
+Research and in-repo experience show that large shifts in test-writing volume yield little resolution change while consuming substantially 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

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

@@ -13,15 +13,15 @@ This protocol is loaded on demand by the architect stub in src/agents/architect.
 If .swarm/plan.md exists:
   1. Read plan.md header for "Swarm:" field
   2. If Swarm field missing or matches the active swarm id:
-     - Reconcile stale worktree state before resuming: prune/adopt stale `.swarm-worktrees/` lane directories and `swarm-lane/*` git branches left from the prior session. Use the existing `cleanupOrphanedBranches` / `startupOrphanRecovery` helpers (or `/swarm reset-session` recovery) as the mechanism so the resumed run starts from a clean provisioning state.
+     - Reconcile stale worktree state before resuming: prune/adopt stale `.swarm-worktrees/` lane directories and `swarm-lane/*` git branches left from the prior session. Drive this via the `/swarm reset-session` recovery command (internal: `cleanupOrphanedBranches`) so the resumed run starts from a clean provisioning state.
      - 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
+     - Update the plan's Swarm field to the active swarm id via `save_plan` (do not hand-edit plan.md — it is a derived projection).
      - 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."
-     - Reconcile stale worktree state before resuming: prune/adopt stale `.swarm-worktrees/` lane directories and `swarm-lane/*` git branches left from the prior session. Use the existing `cleanupOrphanedBranches` / `startupOrphanRecovery` helpers (or `/swarm reset-session` recovery) as the mechanism so the resumed run starts from a clean provisioning state.
+     - Reconcile stale worktree state before resuming: prune/adopt stale `.swarm-worktrees/` lane directories and `swarm-lane/*` git branches left from the prior session. Drive this via the `/swarm reset-session` recovery command (internal: `cleanupOrphanedBranches`) so the resumed run starts from a clean provisioning state.
      - 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/).
+If .swarm/plan.md does not exist → New project, proceed to MODE: SPECIFY
+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 QA gate selection (stricter gates). 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/).

package/.opencode/skills/running-tests/SKILL.md

@@ -78,8 +78,7 @@ Do you need to run tests?
 | `'convention'` | ✅ Safe | ❌ Rejected (`scope_exceeded`) | Guard fires before fan-out; direct test file paths exempt |
 | `'graph'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |
 | `'impact'` | ✅ Safe (capped at 50 via budget) | ❌ Rejected (`scope_exceeded`) | Two-layer guard: source-file count + fan-out estimate |
-| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |
-| `'all'` | ❌ Never | ❌ Never | Requires `allow_full_suite: true`; CI mirror only |
+| `'all'` | ❌ Never | ❌ Never | Env-gated (`SWARM_ALLOW_FULL_SUITE=1`); CI mirror only |
 
 **Rule of thumb:** Pass exactly one source file to `test_runner`. For multiple files, use a shell loop.
 
@@ -234,7 +233,7 @@ Not all failures are equal. Before deciding what to do, classify the failure:
 |-------|-----------|---------|------------|
 | **Stale assertion** | Test checks for text/value that was deliberately removed | `expect(prompt).toContain('CONSTRAINT: [what NOT to do]')` — template removed in refactor | Update the assertion to match current state |
 | **Soft regression indicator** | Test checks a threshold the codebase has since exceeded | `expect(tokenCount).toBeLessThan(35000)` — prompt grew past limit | Fix the threshold or reduce the prompt; do not just document and ignore |
-| **Genuine pre-existing** | Failure exists on `main` unrelated to any recent change | `full-auto-intercept.test.ts` logger gating issue | Document in PR body; do not fix unless scoped |
+| **Genuine pre-existing** | Failure exists on `main` unrelated to any recent change | See the quarantine ledgers (`scripts/ci/quarantined-tests*.txt`) | Document in PR body; do not fix unless scoped |
 | **New regression** | Failure introduced by your changes | Tests for prompt text you removed without updating tests | Fix before pushing |
 
 **Stale assertions and soft regression indicators are actionable** — they signal drift between
@@ -281,7 +280,7 @@ bun --smol test tests/unit/agents/some-file.test.ts --timeout 30000
 | `Select-String -Last N` error | Invalid PowerShell parameter | Use `Select-Object -Last N` |
 | Token budget test failure | Prompt grew past hardcoded threshold | Treat as soft regression; update threshold |
 | CONSTRAINT assertion fails after refactor | Test checks for removed format template | Update assertion to match current prompt |
-| `package-check` CI failure | `package-check` validates the npm tarball (`npm pack` + tarball contents) — a source/build/package-manifest problem, not generated-file drift. `dist/` is generated and NOT committed — do not stage it; run `bun run build` locally only when you need the bundle. There is no longer a committed-dist drift check. |
+| `package-check` CI failure | `package-check` validates the npm tarball (`npm pack` + tarball contents) — a source/build/package-manifest problem, not generated-file drift | `dist/` is generated and NOT committed — do not stage it; run `bun run build` locally only when you need the bundle. There is no longer a committed-dist drift check. |
 
 ## Tree-sitter / WASM test timeouts
 

package/.opencode/skills/specify/SKILL.md

@@ -48,7 +48,7 @@ Activates when: user asks to "specify", "define requirements", "write a spec", o
    - Key entities if data is involved (no schema or field definitions — entity names only)
    - Edge cases and known failure modes
     - `[NEEDS CLARIFICATION]` markers for items where uncertainty could change scope, security, or core behavior, BUT ONLY after running the clarification funnel: (1) inventory all material uncertainties without numeric cap, (2) classify each as 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`, (3) consult critic_sounding_board with candidate items — 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, (4) record all resolved items as explicit assumptions in the spec, (5) use markers only for items that survive the funnel (ASK_USER or unresolved after critic consultation). Decision packet format: grouped by category, recommended defaults, blocking vs optional markers, impact of accepting default. Prefer informed defaults over asking
-     - **Important:** If research is ongoing, monitor the timeout configured in `.swarm/config.json` under `research_needed_timeout_ms` (default: 300000ms / 5 minutes). If research does not complete before the timeout expires, automatically reclassify the item to `user_decision` with a note that research was incomplete, then surface it to the user. This prevents the clarification funnel from stalling while waiting for external research.
+     - **Important:** If research is ongoing, apply a fixed 5-minute protocol budget to `research_needed`. If research does not complete before the budget expires, automatically reclassify the item to `user_decision` with a note that research was incomplete, then surface it to the user. This prevents the clarification funnel from stalling while waiting for external research.
  5. Write the spec to `.swarm/spec.md`.
 5b. **QA GATE SELECTION, PARALLEL CODERS, COMMIT FREQUENCY, AND AUTO_PROCEED (dialogue only).**
 Ask the user which QA gates to enable for this plan, how many parallel coders to use, the commit frequency, and auto_proceed -- do not select on their behalf. Present all four items together as one unified exchange. Exception: when SPECIFY is running inside MODE: LOOP with `autonomy=auto`, write the balanced-speed default `## Pending QA Gate Selection` instead (reviewer, test_engineer, sme_enabled, critic_pre_plan, sast_enabled, drift_check ON; council_mode, hallucination_guard, mutation_test, phase_council, final_council OFF), keep phase-level commits, and let MODE: PLAN choose safe parallelism after task scopes exist.
@@ -130,6 +130,7 @@ Do NOT call `set_qa_gates` yet — `plan.json` does not exist at this point. Onc
 - phase_council: <true|false>
 - drift_check: <true|false>
 - final_council: <true|false>
+- auto_proceed: <true|false>
 - recorded_at: <ISO timestamp>
 ```
 MODE: PLAN will read this section after `save_plan` succeeds and persist via `set_qa_gates`.

package/.opencode/skills/swarm/SKILL.md

@@ -78,6 +78,14 @@ Any edit after reviewer or critic approval invalidates that approval. Re-run the
 3. Confirm that swarm mode is now enabled for this session.
 4. For the user's next complex task, follow the swarm-mode contract automatically unless the user disables it.
 
+The session contract file is written to a runtime-specific session dir. Use the path that matches the host runtime:
+
+| Runtime | Session contract path |
+|---|---|
+| OpenCode | `.zcode/session/swarm-mode.md` |
+| Claude Code | `.claude/session/swarm-mode.md` |
+| Codex | `.codex/session/swarm-mode.md` |
+
 Write this exact file:
 
 ```md

package/.opencode/skills/swarm-ci-monitor/SKILL.md

@@ -130,9 +130,9 @@ job/step — pick the one matching where the flake actually failed:
 
 | Quarantine file | Consumed by |
 |---|---|
-| `scripts/ci/quarantined-tests.txt` | unit + coverage jobs, all OSes |
-| `scripts/ci/quarantined-tests-macos.txt` | unit + coverage jobs, macOS runner only |
-| `scripts/ci/quarantined-tests-windows.txt` | unit + coverage jobs, Windows runner only |
+| `scripts/ci/quarantined-tests.txt` | unit (all OSes) + coverage (ubuntu) |
+| `scripts/ci/quarantined-tests-macos.txt` | unit on macOS runner only |
+| `scripts/ci/quarantined-tests-windows.txt` | unit on Windows runner only |
 | `scripts/ci/quarantined-integration-tests.txt` | the `merge_group`-only integration step — **never** reads the base file above |
 
 Using the wrong file is a real failure mode, not a formality: appending an
@@ -254,7 +254,7 @@ gh pr merge <N>
   a merge queue, no merge strategy is required" — this skill must work
   correctly whether or not the base branch requires a merge queue, so let
   branch protection determine the method rather than assuming squash.
-  `contributing.md`'s squash-merge guidance may describe a different (or
+  `contributing.md`'s merge-queue/merge-commit guidance may describe a different (or
   stale) configuration for a given deployment of this repo; do not assume it
   applies without checking the actual outcome below.
 - **No `--admin`.** Never bypass required checks, review, or a merge queue.

package/.opencode/skills/swarm-pr-feedback/SKILL.md

@@ -6,8 +6,9 @@ description: >
   Use when addressing pasted PR feedback, GitHub review comments or threads,
   requested changes, CI/check failures, merge conflicts, stale PR branches, or
   PR follow-up work that must close all known issues without dropping findings.
-  Supports multi-round bot reviews (the repository's bot posts a new review
-  after every push) via the iterative pattern documented in the body. Stage A
+  Supports multi-round bot reviews — when the repo uses an auto-review bot that
+  posts a new review after every push (in opencode-swarm, `hermes-pr-review`) —
+  via the iterative pattern documented in the body. Stage A
   (structural pre-checks) and Stage B (reviewer + test_engineer) gates and the
   reviewer + critic closeout gate are MANDATORY for any change made as part of
   this process.
@@ -42,9 +43,10 @@ fixes.
 
 ## Multi-Round Bot Reviews (Iterative Pattern)
 
-The repository's bot reviewer (`hermes-pr-review` / Qwen3.6 + Gemma-4 dual-model)
-posts a new review comment after **every push** to the PR branch, not just the
-final state. Expect N rounds of review for N pushes, and budget for it.
+When the repo uses an auto-review bot — in opencode-swarm, `hermes-pr-review`
+(Qwen3.6 + Gemma-4 dual-model) — it posts a new review comment after **every
+push** to the PR branch, not just the final state. Expect N rounds of review for
+N pushes, and budget for it.
 
 **Round N+1 deltas vs Round N:**
 - Fresh `FB-###` ledger IDs for new findings (do not reuse IDs from earlier rounds)
@@ -66,14 +68,15 @@ final state. Expect N rounds of review for N pushes, and budget for it.
    defense-in-depth rationale comment rather than continue to debate. One extra
    condition is cheap; per-round debate is expensive. Document the parent-vs-inner
    relationship inline so future readers see the rationale.
-   **When not to apply 3-strikes:** If the suggested fix would add incorrect,
-   misleading, or redundant code — e.g., an outer guard that already exists at an
+   **When not to apply 3-strikes:** If the suggested fix would add incorrect or
+   misleading code about existing guards — e.g., an outer guard that already exists at an
    inner scope and whose addition would imply the inner guard is absent, a type
    narrowing that masks a real error class, or a check whose presence asserts a
    false invariant — do not add the change. A wrong fix embedded in the code is
-   harder to remove than a repeated rebuttal in a comment thread. Apply item 6's
-   "surface to user" path instead, with the cumulative evidence that the fix
-   direction is incorrect.
+   harder to remove than a repeated rebuttal in a comment thread. When the
+   repeated finding is misleading about existing guards, apply item 6's
+   "surface to user" path instead of 3-strikes; otherwise the 3-strikes rule
+   applies.
 4. **Verify bot fix-direction suggestions against actual file structure.** Bots
    read files linearly and can miss parent-block guards. For any "add an X check"
    suggestion, read the surrounding function/block to confirm the check is genuinely
@@ -244,10 +247,10 @@ one push + one CI run.
 **The fix:** Collect all failures and their logs in one batch operation before
 proposing any fix.
 
-1. `gh pr checks --json checkName,conclusion,detailsUrl` — get every check,
-   its conclusion, and the URL to its run details.
-2. Filter to failing checks (`conclusion: "failure"` | `"cancelled"` | `"timed_out"`).
-3. For each failing check, extract the run ID from `detailsUrl` and run
+1. `gh pr checks <n> --json name,bucket,state,link` — get every check,
+   its bucket/state, and the URL to its run details.
+2. Filter to failing checks (`bucket == "fail"` | `bucket == "cancel"`).
+3. For each failing check, extract the run ID from `link` and run
    `gh run view <run-id> --log-failed` to fetch the full log output.
 4. Build a complete failure ledger: all checks + all failure logs collected.
 5. Triage the full ledger to identify root causes.
@@ -264,7 +267,7 @@ for the Fix Planning step.
 
 **When to use `declare_scope` (preferred):** any feedback round that touches 2+ files, OR any feedback round where the file scope is not 100% obvious from the prompt. Before delegating, save a minimal plan via `save_plan` with a single phase containing the feedback-closure tasks, then call `declare_scope` per task with the exact file list.
 
-**Carve-out for direct Task delegation:** 1-file, single-function changes where the file path appears verbatim in the coder's prompt may use direct `Task(subagent_type="paid_coder", ...)` delegation without `declare_scope`. This is a narrow exception; the orchestrator is responsible for verifying the scope is unambiguous.
+**Carve-out for direct Task delegation:** 1-file, single-function changes where the file path appears verbatim in the coder's prompt may use direct `Task(subagent_type="<coder>", ...)` delegation without `declare_scope`, where `<coder>` is the active swarm's coder agent (e.g. `coder`, or `paid_coder` when the swarm id is `paid`). This is a narrow exception; the orchestrator is responsible for verifying the scope is unambiguous.
 
 **Anti-pattern:** do not use `Task` delegation for multi-file feedback fixes just to skip `save_plan` — the loss of scope discipline is not worth the saved ceremony.
 
@@ -303,15 +306,17 @@ architect work: normalize feedback IDs, gather deterministic PR metadata, prepar
 reproduction commands, and plan likely fix groups. Do not edit, close items, or
 mark feedback resolved from running lanes.
 
-Before the Verification step can mark any item `RESOLVED`, `DISPROVED`,
-`PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`, every open
-verification batch must be fully settled. Poll with `collect_lane_results` (wait
-omitted or `false`) to process settled lanes incrementally — clustering confirmed
-items and pre-reading files for settled findings while ledger-safe work remains —
-then issue a final `collect_lane_results` with `wait: true` per batch once
-independent work is exhausted, to confirm every lane is settled.
+Before the Verification step can mark any item `CONFIRMED`, `PARTIAL`,
+`DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`,
+every open verification batch must be fully settled. Poll with
+`collect_lane_results` (wait omitted or `false`) to process settled lanes
+incrementally — clustering confirmed items and pre-reading files for settled
+findings while ledger-safe work remains — then issue a final
+`collect_lane_results` with `wait: true` per batch once independent work is
+exhausted, to confirm every lane is settled.
 Missing, stale, cancelled, or failed lanes are coverage gaps that must be closed
-before marking any item RESOLVED/DISPROVED/PRE_EXISTING. Apply the COVERAGE GATE:
+before marking any item CONFIRMED/PARTIAL/DISPROVED/PRE_EXISTING. Apply the
+COVERAGE GATE:
 retry failed lanes (max 2), deploy a verified equivalent alternative (same agent
 type, same prompt, same scope, same isolation, with Task-tool dispatch as the
 final fallback when lane tools do not work), or stop and surface the lane failure
@@ -345,8 +350,9 @@ entire pipeline. Before triaging, check:
 ### PR body claim verification
 
 PR body text like "PHASE 2 council APPROVED (5/5, round 2)" or "Final council
-APPROVED" must be backed by an evidence file in `.swarm/evidence/`
-(typically `phase-council.json` or `final-council.json`). Bot-generated PR
+APPROVED" must be backed by an evidence file under `.swarm/evidence/` — phase
+councils write `.swarm/evidence/{phaseNumber}/phase-council.json`; the final
+council writes the flat `.swarm/evidence/final-council.json`. Bot-generated PR
 bodies commonly auto-fill these claims without real review. Before accepting
 such a claim as part of triage:
 
@@ -381,9 +387,9 @@ Rules:
   `CONFLICT-001` for merge/base drift and `CI-001` for check failures, so PR
   bodies can show exactly how operational blockers were closed.
 
-### Mandatory: integrate all PR comments with feedback or findings before validation
+### Mandatory: integrate all PR comments with feedback or findings before branch validation (Stage A)
 
-**Before the Verification step begins, every PR comment that contains feedback
+**Before branch validation (Stage A) can begin, every PR comment that contains feedback
 or findings MUST be integrated into the total feedback ledger as a
 `FB-###` item.** This is a hard requirement, not a best-effort step.
 
@@ -408,13 +414,13 @@ Rules:
   reviewer mentioned, the corresponding `FB-###` item MUST be in the ledger
   before the fix. If you skip the fix, the `FB-###` item MUST be in the
   ledger with a `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or
-  `NEEDS_USER_DECISION` status before validation can begin.
+  `NEEDS_USER_DECISION` status before branch validation (Stage A) can begin.
 - **Status semantics for unaddressed items:**
   - `CONFIRMED` and `PARTIAL` items must be addressed (fixed or
-    disproved) before validation can begin. A `CONFIRMED` item that is
+    disproved) before branch validation (Stage A) can begin. A `CONFIRMED` item that is
     left unaddressed is a regression against the review.
   - `DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, and
-    `NEEDS_USER_DECISION` items may remain open at validation time, but
+    `NEEDS_USER_DECISION` items may remain open at branch-validation (Stage A) time, but
     each must be explicitly justified in the closure ledger.
 - **The closure ledger at the end of the run must account for every `FB-###`
   item** with a final status (fixed / disproved / pre-existing / needs user
@@ -515,7 +521,7 @@ or compatibility policy, mark the item `NEEDS_USER_DECISION` and ask.
   and let the merge queue perform final current-base validation. Still resolve real
    merge conflicts and SHA-dependent review threads before queuing.
 
- ### Operational Gotchas
+### Operational Gotchas
 
  - **Plan identity change:** When switching from a review plan to a feedback-closure
    plan, `save_plan` rejects with `PLAN_IDENTITY_MISMATCH`. Pass
@@ -535,7 +541,7 @@ or compatibility policy, mark the item `NEEDS_USER_DECISION` and ask.
    targeting the same file. The "ONE task per coder" rule is about distinct
    objectives, not about N edits to one file.
 
- ## Mandatory Gates
+## Mandatory Gates
 
 **Stage A and Stage B gates and the reviewer + critic closeout gate are
 MANDATORY for any change made as part of the PR-feedback process.** No fix
@@ -566,7 +572,10 @@ than skipping silently.
 
 ### Stage B — reviewer + test_engineer (mandatory after Stage A passes)
 
-Two independent agents on the Stage-A-green diff:
+Two independent agents on the Stage-A-green diff, run in order: **reviewer
+first**, then **test_engineer**. The reviewer validates the fixes before the
+test_engineer writes falsification probes against them; running them in parallel
+risks the test_engineer pinning a not-yet-approved fix shape.
 
 - **reviewer** — independent (fresh context, not the implementer, not a continued
   conversation). Validates each fix on the current diff against the feedback
@@ -576,7 +585,10 @@ Two independent agents on the Stage-A-green diff:
   newly covered gaps). Verdict per item: PASS / FAIL / BLOCKED.
 
 Address every NEEDS_REVISION / BLOCKED / FAIL, then re-run the affected agent on
-the current diff.
+the current diff. When the test_engineer authors or modifies test files during
+Stage B, re-run the Stage A structural pre-checks (build / typecheck / lint)
+over those test files before the Stage B verdict is considered final — Stage A
+must be green over the full Stage-B-inclusive diff.
 
 ### Closeout gate — reviewer + critic (mandatory after Stage B)
 
@@ -598,9 +610,11 @@ critic surfaces correctness issues, then re-critic. **Any edit after the
 reviewer's or critic's approval invalidates that approval** — re-run the
 affected gate on the current diff before publishing.
 
-Record both closeout verdicts (reviewer + critic, with HEAD/diff) in
-`.claude/session/tasks/<slug>/gates.md` per the `durable-session-state` skill
-(`.swarm/` is the plugin's runtime state — never write task artifacts there).
+Record both closeout verdicts (reviewer + critic, with HEAD/diff) in the
+runtime's session task-gates artifact (e.g. `.claude/session/tasks/<slug>/gates.md`
+under Claude Code, or the OpenCode/Codex equivalent) per the
+`durable-session-state` skill (`.swarm/` is the plugin's runtime state — never
+write task artifacts there).
 
 ### Post-publish verification (mandatory after the PR is pushed)
 
@@ -616,6 +630,9 @@ pre-checks and must not be folded into Stage A.
 
 ## Publishing And Communication
 
+Commits and pushes follow `file:.swarm/bundled-skills/commit-pr/SKILL.md` (the
+repository's commit/PR workflow) — do not push ad-hoc.
+
 After fixes, update the PR body or comment with a closure ledger:
 
 ```text
@@ -623,7 +640,7 @@ FB-001 | fixed | commit/test evidence
 FB-002 | disproved | code evidence
 FB-003 | pre-existing | base-branch evidence
 FB-004 | needs user decision | decision required
-FB-005 | needs more evidence | .swarm/evidence/phase-council.json missing
+FB-005 | needs more evidence | .swarm/evidence/{phase}/phase-council.json missing
 CONFLICT-001 | fixed | remote mergeability is MERGEABLE/CLEAN
 CI-001 | fixed | current-head check/run evidence
 ```

package/.opencode/skills/swarm-pr-subscribe/SKILL.md

@@ -26,6 +26,8 @@ This is the final hop of the PR lifecycle:
 watching the PR — routing fresh events back through the feedback discipline —
 until the PR is merged or closed.
 
+> **Cross-reference**: For ongoing CI-status tracking across multiple PRs (not just one PR's feedback), use the `swarm-ci-monitor` skill instead.
+
 ## When To Subscribe
 
 - **Automatically after PR creation.** When `pr_monitor.enabled` and

package/.opencode/skills/test-file-split/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: test-file-split
 audience: swarm-plugin
-description: Protocol for splitting test files that exceed the FR-006 500-line hard limit. Covers describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, and cascading-split detection. Load when a test file approaches or exceeds 500 lines.
+description: Protocol for splitting test files that approach or exceed the FR-006 500-line limit (enforced in CI by scripts/check-test-file-cap.sh as a diff-scoped ratchet). Covers describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, and cascading-split detection. Load when a test file approaches or exceeds 500 lines.
 ---
 
 # Test File Split Protocol (FR-006)
@@ -88,9 +88,7 @@ After splitting, evaluate whether internal utility functions in the source modul
 
 If a previously split file exceeds 500 lines **again**, the test suite is structurally too large for a single module. Do not split a third time — reorganize the tests by source module boundaries instead. Repeated splitting produces fragmented test suites that are hard to navigate and maintain.
 
-## Real-world example (PR #1762 — pending merge)
-
-> **Note:** This example references functions and files from PR #1762's branch. These do not exist on `main` until the PR is merged. The pattern is still valid as an illustration of the splitting protocol.
+## Real-world example (PR #1762)
 
 `tests/unit/scripts/release-notes-fragments.test.ts` exceeded 500 lines. It was split into: