opencode-swarm 7.114.0 → 7.114.1

package/.opencode/skills/brainstorm/SKILL.md

@@ -54,10 +54,11 @@ If `council.general.enabled` is true in the resolved opencode-swarm config AND a
 
 **Phase 5: SPEC WRITE + SELF-REVIEW (architect + reviewer).**
     - Generate `.swarm/spec.md` following the same SPEC CONTENT RULES that MODE: SPECIFY uses: WHAT/WHY only, no tech stack, no implementation details, FR-### / SC-### numbering, Given/When/Then scenarios, `[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).
-    - **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.
 - Cross-reference design sections by name where relevant context helps (but keep HOW out of the spec).
 - Delegate to `the active swarm's reviewer agent` for an independent review of the draft spec. Reviewer must flag: requirements that encode HOW, untestable requirements, missing edge cases, silent assumptions.
 - Apply reviewer feedback. If reviewer rejects, iterate once and re-review. After two rounds, surface remaining disagreements to the user.
+- Before writing `.swarm/spec.md`, apply the FR-002 non-shadowing check: if a non-native spec already exists, do not shadow it (see MODE: SPECIFY step 1b).
 - Write the final spec to `.swarm/spec.md`.
 - Exit when reviewer signs off (or user explicitly accepts remaining disagreements).
 
@@ -70,9 +71,9 @@ hallucination_guard, mutation_test, phase_council, final_council OFF). Do not
 write `## Pending Parallelization Config` here because task scopes are not known
 until PLAN; MODE: PLAN will choose safe parallelism automatically. Keep commit
 frequency at phase-level only.
-Now ask the user which QA gates to enable for this plan, how many parallel coders to use, and the commit frequency -- do not select on their behalf. Present all three items together as one unified exchange.
+Now 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.
 
-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:
+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
@@ -85,7 +86,7 @@ Present the eleven gates with their defaults (DEFAULT_QA_GATES), parallel coder
 - drift_check (default: ON) -- when enabled, mandatory per-phase drift verification via critic_drift_verifier at PHASE-WRAP; compares implemented changes against spec.md intent; hard-blocks phase_complete when spec.md exists and drift evidence is missing or REJECTED; advisory-only when no spec.md exists (recommended for all projects with a specification)
 - 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 file scopes do NOT overlap. The per-task file scopes that determine a safe parallel count are not known until the plan is finalized, so default to 1 (serial) here; the precise recommendation is made at plan time once the tasks and their scopes exist.
   > 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.
@@ -126,13 +127,13 @@ GATE SELECTION IS MANDATORY — these thoughts are WRONG and must be ignored:
   ✗ "I already know which gates are right for this project"
     → WRONG: the architect does not configure gates. The user configures gates. Always ask.
 
-MANDATORY PAUSE: Do NOT write the spec summary (step 7). Do NOT suggest next steps.
+MANDATORY PAUSE: Do NOT write the spec summary (Phase 7 transition). Do NOT suggest next steps.
 Exception: MODE: LOOP with `autonomy=auto` uses the balanced-speed defaults
 above and does not pause for this preference exchange.
 You are BLOCKED until ALL THREE of these conditions are met:
-  (1) The unified gate/coders/commit selection section has been presented to the user in a single message
-  (2) The user has responded (accept defaults OR customized list for all three items)
-  (3) The elected gates, parallel coder config, and commit policy have been written to .swarm/context.md under "## Pending QA Gate Selection" (and related sections as applicable)
+  (1) The unified gate/coders/commit/auto_proceed selection section has been presented to the user in a single message
+  (2) The user has responded (accept defaults OR customized list for all four items)
+  (3) The elected gates, parallel coder config, commit policy, and auto_proceed selection have been written to .swarm/context.md under "## Pending QA Gate Selection" (and related sections as applicable)
 <!-- BEHAVIORAL_GUIDANCE_END -->
 
 Do NOT call `set_qa_gates` yet — `plan.json` does not exist at this point. Once the user answers, write the elected gates to `.swarm/context.md` under a new section:
@@ -149,6 +150,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 applies these after `save_plan` succeeds via `set_qa_gates`.

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

@@ -73,7 +73,7 @@ readCuratorSummary reads file back successfully`), while the same tests pass
 on `ubuntu-latest` and `windows-latest`.
 
 **Canonical patterns:** See
-`file:.swarm/bundled-skills/writing-tests/SKILL.md`
+`file:.opencode/skills/writing-tests/SKILL.md`
 § Cross-Platform Requirements → "macOS rename-visibility race" for the
 full three-layer fix pattern (bunWrite + ENOENT retry + Node FileHandle.sync()
 not fsync()). This skill is a triage pointer; the canonical technical
@@ -85,7 +85,7 @@ or path, the security test `ADVERSARIAL: Command Services Attack Vectors >
 Attack Vector 1: Malformed Arguments > EVIDENCE: extremely long task ID
 (buffer overflow) - ACCEPTED by regex but no crash` requires a path length
 guard BEFORE `validateSwarmPath` in `src/evidence/manager.ts:loadEvidence`.
-See `file:.swarm/bundled-skills/engineering-conventions/SKILL.md`
+See `file:.opencode/skills/engineering-conventions/SKILL.md`
 for the evidence file flow that this gate check triggers on macOS CI.
 
 ## Step 3 — Diagnose with logs

package/.opencode/skills/clarify/SKILL.md

@@ -39,7 +39,7 @@ There is NO hard cap on the internal inventory. Record every material uncertaint
 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.
 
@@ -107,4 +107,4 @@ All items resolved in Stages 2-3 (self_resolved, critic_resolved, deferred_nonbl
 
 **Implementation Note:** The hard constraint against `DROP` on always-surface items (defined in 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.

package/.opencode/skills/clarify-spec/SKILL.md

@@ -10,7 +10,7 @@ description: >
 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: CLARIFY-SPEC
-Activates when: `/swarm sdd status` reports a **single resolved EFFECTIVE spec** (non-null) AND it contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY with open markers.
+Activates when: `/swarm sdd status` reports a **single resolved EFFECTIVE spec** (non-null) AND it contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY or MODE: BRAINSTORM with open markers.
 
 `/swarm sdd status` reflects `readEffectiveSpecSync`, which returns **null** (NO effective spec) for: no sources at all, multiple competing sources (e.g. `openspec/` AND `.specify/`), multi-feature Spec-Kit without a selected feature, or any other unresolvable state. CLARIFY-SPEC does NOT activate in these null cases — tell the user: "No resolved effective spec exists. Disambiguate with `/swarm sdd project --source <source>` or `--feature <feature>`, or run `/swarm specify` to generate one first." and stop.
 
@@ -31,7 +31,7 @@ CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. Always consult `/swarm sdd st
    - Offer 2–4 multiple-choice options for each question
    - Mark the recommended option with reasoning (e.g., "Recommended: Option 2 because…")
    - Allow free-form input as an alternative to the options
-5. After each accepted answer, write the resolution to the **resolved effective source** (source-aware write-back):
+6. After each accepted answer, write the resolution to the **resolved effective source** (source-aware write-back):
     - **NATIVE effective spec** (`.swarm/spec.md` exists): update `.swarm/spec.md` with the resolution directly.
     - **NON-NATIVE effective spec** (openspec/specify-only, NO native `.swarm/spec.md`): do NOT write `.swarm/spec.md` — this would silently shadow the non-native source. Instead:
       - (a) If the resolved source supports in-place edits (e.g., OpenSpec sections), update the source artifacts directly.
@@ -39,8 +39,8 @@ CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. Always consult `/swarm sdd st
       - (c) If neither (a) nor (b) applies, stop and tell the user the clarification cannot be auto-written to a non-native source without a projection step.
     - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer.
     - If the answer invalidates an earlier requirement, update it to remove the contradiction.
-6. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
-7. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).
+7. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
+8. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).
 
 CLARIFY-SPEC RULES:
 - FR-ID increment rule: When adding new requirements, find the highest existing FR-ID and increment from there (FR-001 → FR-002). Never reuse or skip FR-IDs.

package/.opencode/skills/commit-pr/SKILL.md

@@ -72,6 +72,8 @@ Run before publication work:
 ```bash
 git fetch origin main
 rm -f .swarm/evidence/*.json
+rm -f .swarm/evidence/pr_body.md
+rm -f .swarm/evidence/commit-pr-validation.md
 git status --short
 ```
 
@@ -112,6 +114,8 @@ The fragment should cover:
 - breaking changes, if any
 - known caveats
 
+Bot authors (e.g. `[bot]`, Copilot) and docs/workflow/meta-only changes (no `src/`, `tests/`, `scripts/`, `package.json`, etc.) are exempt from this requirement by CI; all other PRs that touch code must include a fragment.
+
 Do not manually edit:
 
 - `package.json` version
@@ -147,24 +151,26 @@ node --input-type=module -e "await import('./dist/index.js'); console.log('dist
 
 ### Tier 1 - quality
 
-Run both linter AND formatter — e.g., `bunx @biomejs/biome@<version> check --write .` or equivalent — because CI quality gates reject code that passes tests but fails style validation. **Pin the tool version** to match the version in `package.json` (`@biomejs/biome`); unversioned `bunx biome` resolves to a different version than the CI gate uses.
+Run both linter AND formatter — e.g., `bunx @biomejs/biome@<version> check --write .` or equivalent — because CI quality gates reject code that passes tests but fails style validation. **Pin the tool version** to match the version in `package.json` (`@biomejs/biome`); unversioned `bunx biome` resolves to a different version than the CI gate uses. (the repo script `bun run lint:ci` runs the pinned Biome version; prefer it over invoking `bunx biome` directly).
 
 ```bash
 bun run typecheck
-bunx @biomejs/biome@<version> ci .
+bun run lint:ci
+bun run scripts/check-tool-registration.ts
+bash scripts/check-mock-cleanup.sh
+bash scripts/check-invariants.sh
+bash scripts/check-cross-contamination.sh
+bash scripts/check-test-clock.sh
 ```
 
 ### Tier 2 - unit tests
 
 ```bash
-for f in tests/unit/tools/*.test.ts; do bun --smol test "$f" --timeout 30000; done
-for f in tests/unit/services/*.test.ts; do bun --smol test "$f" --timeout 30000; done
-for f in tests/unit/agents/*.test.ts; do bun --smol test "$f" --timeout 30000; done
-for f in tests/unit/hooks/*.test.ts; do bun --smol test "$f" --timeout 30000; done
-bun --smol test tests/unit/cli tests/unit/commands tests/unit/config --timeout 120000
+bun run test:unit:ci               # CI-equivalent unit gate (quarantine ledgers + retry budget)
+bun run test:unit:ci <file>...     # scoped mode: run only the listed repo-relative test files
 ```
 
-If agent prompt text changed, grep for the changed text in tests and rerun every matching file individually.
+`bun run test:unit:ci` runs `scripts/ci/run-unit-tests-local.ts`, the CI-equivalent unit gate with per-platform quarantine ledgers (`scripts/ci/quarantined-tests.txt`, `quarantined-tests-macos.txt`, `quarantined-tests-windows.txt`) and the retry budget. The full serial run is 45–90 min, so use the scoped mode (`bun run test:unit:ci <file>...`) when the evidence justifies narrowing (e.g. you only touched one module). This closes the gap the hand-rolled loops left (~40% of CI's colocated `src/**` tests were uncovered).
 
 ### Tier 3 - integration
 
@@ -191,7 +197,11 @@ If a failure looks unrelated, prove it on clean `origin/main` before carrying it
 
 ```bash
 git worktree add /tmp/repro-check origin/main
-bun --smol test /tmp/repro-check/<path-to-failing-test> --timeout 30000
+cd /tmp/repro-check
+bun install --frozen-lockfile
+bun run build
+bun --smol test <repo-relative-path-to-failing-test> --timeout 120000
+cd ..
 git worktree remove /tmp/repro-check
 ```
 
@@ -221,14 +231,14 @@ Before opening a PR, verify no local-only files are staged:
 git diff --name-only HEAD origin/main | grep -E '\.(local\.json|vscode|idea)' || true
 ```
 
-Prefer a single clean commit for the branch before initial PR publication:
+Prefer a single clean commit for the branch before initial PR publication. Resolve the canonical remote first (see "Canonical remote resolution" below), then squash/push:
 
 ```bash
-git fetch origin main
-git log --oneline origin/main..HEAD
-git reset --soft origin/main
+git fetch <canonical-remote> <base-branch>
+git log --oneline <canonical-remote>/<base-branch>..HEAD
+git reset --soft <canonical-remote>/<base-branch>
 git commit -m "type(scope): description"
-git push --force-with-lease -u origin <branch-name>
+git push --force-with-lease -u <canonical-remote> <branch-name>
 ```
 
 If a review cycle is already active and inline comments depend on current SHAs, avoid resquashing until threads are resolved.
@@ -237,8 +247,8 @@ If pushing to a PR branch owned by another agent or bot, push to the PR's actual
 
 ```powershell
 $prBranch = gh pr view <number> --json headRefName --jq '.headRefName'
-git fetch origin $prBranch
-git push origin "<your-local-branch>:$prBranch" --force-with-lease
+git fetch <canonical-remote> $prBranch
+git push <canonical-remote> "<your-local-branch>:$prBranch" --force-with-lease
 ```
 
 ### Fork PR workflow approval
@@ -268,13 +278,13 @@ pattern was pushed before the string-concatenation workaround was applied.
 **The primary check (pre-push, after commit exists):**
 
 ```bash
-git log origin/main..HEAD -p | grep -E "$(printf '%s' "${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza")" || true
+git log origin/main..HEAD -p | grep -E 'sk_live|ghp_|xox[abprs]-|AKIA|eyJ|AIza' || true
 ```
 
 **The optional pre-commit add-on (staged changes only):**
 
 ```bash
-git diff --cached | grep -E "$(printf '%s' "${PREFIX:-sk_live}|ghp_|xox[abprs]-|AKIA|eyJ|AIza")" || true
+git diff --cached | grep -E 'sk_live|ghp_|xox[abprs]-|AKIA|eyJ|AIza' || true
 ```
 
 Forbidden patterns: Stripe (`sk_live_*`), GitHub (`ghp_*`), Slack (`xox[abprs]-*`),
@@ -325,6 +335,8 @@ PR body requirements:
 - `## Invariant audit`
 - `## Test plan`
 
+CI enforces both the section ORDER (Summary, then Invariant audit, then Test plan) and that each heading is on its own line with nothing trailing but whitespace (see `.github/workflows/pr-standards.yml`).
+
 ### Publication-gate evidence
 
 A repository publication gate (`.github/hooks/pr-publication-gate.json` ->
@@ -415,6 +427,8 @@ $issueCommentPath = Join-Path ([System.IO.Path]::GetTempPath()) "issue-comment.t
 gh issue comment <issue-number> --body-file $issueCommentPath
 ````
 
+If the PR merged before this was done, post the missing issue comment immediately.
+
 ## Commit messages
 
 `git commit -m "..."` with parens, brackets, backticks, or dollar-signs in the message fails on PowerShell because the shell parses them as expressions. Write the commit message to a UTF-8 (no BOM) file first and use `git commit -F <file>`.
@@ -435,8 +449,6 @@ git commit -F $commitMsgPath
 
 Apply this pattern for any commit message containing special characters, multi-paragraph bodies, or code blocks. The plain `git commit -m "..."` form remains fine for short single-line messages with no special characters.
 
-If the PR merged before this was done, post the missing issue comment immediately.
-
 ## Step 7 - Existing PR follow-up and closeout
 
 If a PR already exists for the branch:

package/.opencode/skills/council/SKILL.md

@@ -15,7 +15,7 @@ the full execution details live here.
 ### MODE: COUNCIL
 
 Activates when: user invokes `/swarm council <question>` (optionally with
-`--preset <name>` and/or `--spec-review`).
+`--spec-review`).
 
 Purpose: convene a fixed three-agent multi-model General Council
 (generalist / skeptic / domain expert) for an advisory deliberation. The

package/.opencode/skills/deep-dive/SKILL.md

@@ -97,12 +97,12 @@ Explorers generate CANDIDATE FINDINGS only — they do NOT make verdicts. All fi
 1. Collect all candidate findings from all explorer missions.
 2. Deduplicate: merge findings that reference the same location and issue.
 3. Assign DD-C001 through DD-CNNN identifiers to unique findings.
-4. Cap at 10 findings per shard (see Step 5 for sharding).
-5. Sort by severity (CRITICAL → HIGH → MEDIUM → LOW → INFO).
+4. Sort candidates by severity (CRITICAL → HIGH → MEDIUM → LOW → INFO).
+5. Shard into ≤10-candidate shards until all candidates are assigned to a shard.
 
 ## Step 5 — Always 2 Parallel Reviewers
 
-Split the verified candidates into 2 shards of ≤10 candidates each. Dispatch 2 parallel `the active swarm's reviewer agent` calls.
+Split the candidates into shards of ≤10 each and dispatch 2 parallel `the active swarm's reviewer agent` calls.
 
 Each reviewer receives:
 - Their shard of candidates (up to 10)

package/.opencode/skills/design-docs/SKILL.md

@@ -28,8 +28,9 @@ If the header is malformed, report the error and stop.
 ## Step 1 — Preconditions
 
 1. Confirm `design_docs.enabled` is true (the `docs_design` agent only exists when enabled). If it is not, tell the user to set `design_docs.enabled: true` in `opencode-swarm.json` and stop.
-2. If a spec-staleness block is active (`.swarm/spec-staleness.json` present), resolve/acknowledge spec staleness FIRST — otherwise design-doc writes may be blocked by the guardrail. Do not blindly retry on `SPEC_STALENESS_BLOCK`.
+2. If a spec-staleness block is active (`.swarm/spec-staleness.json` present), resolve/acknowledge spec staleness FIRST — otherwise design-doc writes may be blocked by the guardrail, which emits `SPEC_DRIFT_BLOCK`. Do not blindly retry on `SPEC_DRIFT_BLOCK`.
 3. Read `.swarm/spec.md` if present — it is the authoritative requirements source (FR-### IDs). The design docs must be consistent with it.
+   Run `/swarm sdd status` to resolve the effective spec before reading.
 
 ## Step 2 — Index Existing State (always)
 

package/.opencode/skills/discover/SKILL.md

@@ -17,5 +17,5 @@ For complex tasks, make a second explorer call focused on risk/gap analysis:
 After explorer returns:
 - Run `symbols` tool on key files identified by explorer to understand public API surfaces
 - For multi-file module surveys: prefer `batch_symbols` over sequential single-file symbols calls
-- Run `complexity_hotspots` if not already run in Phase 0 (check context.md for existing analysis). Note modules with recommendation "security_review" or "full_gates" in context.md.
-- Check for project governance files using the `glob` tool with patterns `project-instructions.md`, `docs/project-instructions.md`, `CONTRIBUTING.md`, and `INSTRUCTIONS.md` (checked in that priority order — first match wins). If a file is found: read it and extract all MUST (mandatory constraints) and SHOULD (recommended practices) rules. Write the extracted rules as a summary to `.swarm/context.md` under a `## Project Governance` section — append if the section already exists, create it if not. If no MUST or SHOULD rules are found in the file, skip writing. If no governance file is found: skip silently. Existing DISCOVER steps are unchanged.
+- Run `complexity_hotspots` if not already run during project discovery (check context.md for existing analysis). Note modules with recommendation "security_review" or "full_gates" in context.md.
+- Check for project governance files using the `glob` tool with patterns `project-instructions.md`, `docs/project-instructions.md`, `CONTRIBUTING.md`, `INSTRUCTIONS.md`, `AGENTS.md`, and `CLAUDE.md` (process all matches found). For each file found: read it and extract all MUST (mandatory constraints) and SHOULD (recommended practices) rules. Write the extracted rules as a summary to `.swarm/context.md` under a `## Project Governance` section — append if the section already exists, create it if not. If no MUST or SHOULD rules are found in the file, skip writing. If no governance file is found: skip silently. Existing DISCOVER steps are unchanged.

package/.opencode/skills/engineering-conventions/SKILL.md

@@ -35,6 +35,7 @@ If you are not sure whether you are touching one of these, you are touching one
 The full list of 12 invariants is in `AGENTS.md`. The four that have caused the most recent production regressions:
 
 1. **Plugin initialization is bounded and fail-open.** Every awaited operation on the plugin-init path must be wrapped in `withTimeout(...)` and degrade non-fatally on timeout. Issue #704 (v7.0.3) and the v7.3.3 git-hygiene regression both stem from violating this. The OpenCode plugin host silently drops a plugin whose entry never resolves; users see "no agents in TUI / GUI" with no error.
+   - **Bounded is not free:** `withTimeout` only prevents an *unbounded* hang — the awaited work's latency still counts toward the ~400 ms repro-704 init deadline. Defer non-trivial init I/O via `queueMicrotask` when nothing downstream needs it before `server()` resolves.
 2. **Subprocesses are bounded, non-interactive, and killable.** Every `bunSpawn(['<bin>', ...])` call must pass `cwd`, `stdin: 'ignore'` (unless intentionally interactive), `timeout: <ms>`, bounded stdio, and call `proc.kill()` in a `finally`. An outer `withTimeout` is not enough — it lets the awaiter proceed but does not abort the child.
 3. **Runtime portability — Node-ESM-loadable + v1 plugin shape.** No top-level `bun:` imports in `dist/index.js`. Default export is `{ id, server }`. All `Bun.*` calls go through `src/utils/bun-compat.ts`. v6.86.8 / v6.86.9 are the cautionary tales.
 4. **Test mock isolation.** `mock.module(...)` leaks across files in Bun's shared test-runner process. Prefer, in order: (a) `_test_exports` for pure function testing with zero mocks, (b) `_internals` dependency-injection seam for within-module mocking (see `src/utils/gitignore-warning.ts:_internals` and `src/hooks/diff-scope.ts:_internals`), (c) `mock.module` only when unavoidable. Restore in `afterEach`. The writing-tests skill covers all three tiers in detail; load it before modifying tests.
@@ -49,7 +50,7 @@ The OpenCode `test_runner` tool is for **targeted agent validation** with explic
 
 - `MAX_SAFE_TEST_FILES = 50` (`src/tools/test-runner.ts`). Resolutions exceeding this return `outcome: 'scope_exceeded'` with a SKIP. Do not lean on this — broad scopes can stall or kill OpenCode before that guard fires.
 - For repo validation, run the shell commands in `contributing.md` / `TESTING.md` directly (per-file isolation loops + tier orchestration).
-- `scope: 'all'` requires `allow_full_suite: true` and is intended for opt-in CI mirrors only. Default to `files: [...]` instead.
+- `scope: 'all'` is gated behind the `SWARM_ALLOW_FULL_SUITE=1` env var (intended for opt-in CI mirrors only); there is no `allow_full_suite` arg. Default to `files: [...]` instead.
 
 ## The invariant-audit gate (PR-time)
 
@@ -57,6 +58,58 @@ Every PR that touches a relevant area must include an `## Invariant audit` secti
 
 If you cannot prove a touched invariant from source and test output, **do not push**.
 
+## Evidence file flow (`.swarm/evidence/{taskId}.json`)
+
+**Agents NEVER write these files directly.** The `delegation-gate` hook
+writes them automatically after each reviewer/test_engineer Task
+delegation returns. The schema is defined in `src/gate-evidence.ts`:
+
+```typescript
+export interface GateEvidence {
+  sessionId: string;  // actual session ID from the Task delegation
+  timestamp: string;  // ISO 8601
+  agent: string;     // 'reviewer' | 'test_engineer' | 'sme' | etc.
+}
+
+export interface TaskEvidence {
+  taskId: string;
+  required_gates: string[];
+  gates: Record<string, GateEvidence>;
+  turbo?: boolean;
+}
+```
+
+**How to verify the flow is working:**
+
+1. After dispatching a reviewer/test_engineer Task, the `delegation-gate`
+   toolAfter hook should automatically write/update
+   `.swarm/evidence/{taskId}.json`.
+2. When you call `update_task_status(completed)`, the tool reads the
+   evidence file and verifies the `required_gates` are all present.
+3. If `update_task_status` fails with "required QA gates not yet satisfied"
+   or "Evidence file is corrupt or unreadable," inspect the evidence
+   file with `cat .swarm/evidence/{taskId}.json` to diagnose.
+
+**Do NOT manually write or fabricate evidence files.** This bypasses the
+gate enforcement and can cause downstream tool failures when the real
+session IDs are looked up.
+
+**When to suspect the flow is broken:**
+
+- The evidence file doesn't exist after a reviewer/test_engineer Task
+  delegation returns
+- The evidence file exists but has wrong `agent` or `sessionId` values
+- The plan has newly-added task IDs that the hook may not recognize
+
+**Workaround for broken flow:** If the hook consistently fails to write
+the evidence file, escalate to the user — do NOT silently fabricate
+evidence with placeholder session IDs. The gate check exists to enforce
+that a real review/test run happened.
+
+See [`.opencode/skills/writing-tests/SKILL.md`](../writing-tests/SKILL.md)
+§ Cross-Platform Requirements → "macOS rename-visibility race" for the
+ENOENT retry pattern that this gate flow triggers on macOS CI.
+
 ## Init-path-safe imports (invariant 1 deep-dive)
 
 The most expensive invariant-1 violations come from **transitive import chains** that silently load heavy modules (WASM, tree-sitter) at plugin init time. A single `import { X } from '../../lang'` in a tool-time module can transitively load `runtime.ts` → `web-tree-sitter` (heavy WASM), spiking init latency well past the repro-704 T1 deadline (observed during issue #1471 development).

package/.opencode/skills/gate-attribution/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gate-attribution
 audience: swarm-plugin
-description: Per-task gate dispatch protocol. Documents single-task attribution plus parseable set-dispatch reviewer/test_engineer rows.
+description: Per-task gate dispatch protocol for reviewer/test_engineer set-dispatch attribution. Activates when dispatch_lanes returns set-dispatch verdict rows that must be attributed to plan tasks. Documents single-task attribution plus parseable set-dispatch reviewer/test_engineer rows.
 ---
 
 # Gate Attribution
@@ -14,17 +14,20 @@ output includes parseable per-task rows:
 
 ```
 [REVIEWED] | task-2.1 | APPROVED | ...
-[REVIEWED] | 2.2 | PASS | ...
+[TESTED] | 2.1 | PASS | ...
 ```
 
-Rows with `task-X.Y` are normalized to `X.Y`; unsafe or non-plan IDs are ignored.
-Only passing verdicts (`APPROVED`, `PASS`, or `PASSED`) create gate evidence.
-Rows such as `NEEDS_REVISION` are reviewed rows but do not satisfy the gate. If
-no reviewed rows are parseable, attribution falls back to the single-task rule.
+`[REVIEWED]` verdicts are `APPROVED | REJECTED | CONCERNS`; `[TESTED]` verdicts
+are `PASS | FAIL | SKIPPED`. Rows with `task-X.Y` are normalized to `X.Y`;
+unsafe or non-plan IDs are ignored.
+Each parseable per-task verdict row creates gate evidence (regardless of verdict
+value); the gate's pass/fail decision is made elsewhere from the accumulated
+evidence. If no rows are parseable, attribution falls back to the single-task
+rule.
 
 ## Protocol
 1. **For unrelated or high-risk tasks:** Dispatch separate reviewer and/or test_engineer lanes with exactly ONE taskId.
-2. **For a true set-dispatch:** Require one `[REVIEWED] | task-id | verdict | ...` row per task in the returned output. Only passing verdict rows count.
+2. **For a true set-dispatch:** Require one `[REVIEWED] | task-id | verdict | ...` (or `[TESTED] | ...`) row per task in the returned output. Each parseable row creates gate evidence; the gate decision is made from the accumulated evidence.
 3. **Minimize overhead via parallel dispatch when set-dispatch is not appropriate:**
    ```
    dispatch_lanes_async with:
@@ -35,7 +38,7 @@ no reviewed rows are parseable, attribution falls back to the single-task rule.
 4. **Collect + attribute:** Single-task lanes auto-attribute to their taskId; set-dispatch rows auto-attribute per parsed row.
 5. **Do NOT rely on prose summaries:** A batched dispatch without parseable rows is ambiguous and does not count per-task.
 
-Gate evidence is persisted independently as `.swarm/evidence/{taskId}.json` for each task. Passing set-dispatch rows cause the hook to write one task-scoped file per task; a single multi-task evidence file cannot satisfy any task.
+Gate evidence is persisted independently as `.swarm/evidence/{taskId}.json` for each task. Each parseable set-dispatch row causes the hook to write one task-scoped evidence file for that task (regardless of verdict value); a single multi-task evidence file cannot satisfy any task.
 
 ## Optimization for trivial tasks
 For pure ceremony gates (1-line doc fix):

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

@@ -2,7 +2,7 @@
 name: issue-ingest
 audience: swarm-plugin
 description: >
-  Full execution protocol for MODE: ISSUE_INGEST -- GitHub issue intake, localization, spec generation, and transition to planning or tracing.
+  Full execution protocol for MODE: ISSUE_INGEST -- GitHub issue intake, localization, spec generation, and transition to the full fix workflow.
 ---
 
 # Issue Ingest Protocol
@@ -16,19 +16,21 @@ Purpose: ingest a GitHub issue, localize root cause, and produce a resolution sp
 
 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
+- `trace=true` → after plan, delegate to swarm-implement skill for the fix workflow; the user invokes commit-pr to publish (implies plan=true)
+- `noRepro=true` → skip the reproduction step below
 
 #### 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.
+   - If the issue cannot be fetched (404, private repo, no `gh` auth, or the argument resolves to a PR not an issue), report the blocked operation explicitly and do not proceed on empty intake; fall back to any pasted issue text the user provided. Closed-issue cases proceed but note the closed state.
 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.
+4. Attempt a minimal reproduction of the reported issue: record the exact commands and their output. Skip this step when `noRepro=true` (set via `--no-repro`); in that case, note that reproduction was skipped and proceed on the issue text alone.
+5. Ask the user clarifying questions one at a time, max 6 per intake, when the issue text is ambiguous; otherwise flag the item with markers like `[NEEDS REPRO]` or `[NEEDS CLARIFICATION]` and proceed.
+6. 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.
@@ -41,23 +43,25 @@ Flags parsed from signal:
 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:
+0. Include a **Root Cause** section derived from Phase 2 localization results: concise statement of the identified root cause, location, and confidence score; the `location` field (file/function from Phase 2 localization) is the sole exception to the no-implementation-detail rule. Include a **Fix Strategy** section at product/behavior level (what the fix must accomplish, not how to implement it).
+1. If `.swarm/spec.md` already exists, route through MODE: SPECIFY step 1's classification (overwrite / refine / archive / non-shadowing check) before writing — do not clobber an existing spec. (This protects the drift-gate which consumes spec.md.)
+2. 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)
-     - **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.
- 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`.
+   - `[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)
+   - **Important:** Apply a fixed 5-minute protocol budget to `research_needed`. If research does not complete within 5 minutes, automatically reclassify the item to `user_decision` with a note that research was incomplete, then surface it to the user.
+3. Cross-reference the spec against the issue's expected behavior to ensure alignment.
+4. If the issue is a bug: spec must describe the correct behavior, not the broken behavior.
+5. If the issue is a feature: spec must describe the user-facing outcome, not the implementation.
+6. Carry forward any `[NEEDS REPRO]` / `[NEEDS CLARIFICATION]` flags from Phase 1 into the spec as open questions; do not silently drop them.
+7. 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
+- `trace=true` → transition to MODE: PLAN, then delegate to swarm-implement skill for the fix workflow; the user invokes commit-pr to publish
 
 RULES:
 - One question per message in INTAKE dialogue (max 6 questions)

package/.opencode/skills/loop/SKILL.md

@@ -256,8 +256,7 @@ When a stop condition fires:
    - Learnings captured this run and where they live.
    - Suggested next steps (e.g., open a PR via `/swarm pr-review` or the
      commit-pr flow — do NOT open a PR unless the user asks).
-3. Emit a machine-detectable completion marker on its own line so callers /
-   automation can detect terminal state:
+3. Emit a completion marker on its own line to summarize terminal state for human readers:
 
    `<loop-complete reason="objective-met|budget-exhausted|plateau|oscillation|unrecoverable-error|user-stop" cycles="N"/>`
 
@@ -293,8 +292,8 @@ A minimal, append-friendly shape — extend as needed but keep these fields:
 
 | Behavior | `auto` (default) | `checkpoint` |
 | --- | --- | --- |
-| Pause at phase gates | Yes — wait for user approval | No |
-| Confirm before next cycle | Yes | No |
+| Pause at phase gates | No | Yes — wait for user approval |
+| Confirm before next cycle | No | Yes |
 | Mandatory review + critic gates | Enforced | Enforced |
 | Hard stop conditions (budget, plateau, oscillation, errors) | Enforced | Enforced |
 | Weaken/mock/skip a failing test | Never | Never |

package/.opencode/skills/merge-queue-readiness/SKILL.md

@@ -13,20 +13,13 @@ Before adding the PR to the merge queue (or before the final push if the repo us
 1. **Fetch latest main:** `git fetch origin main`
 2. **Run the simulation command (preferred):**
    ```
-   /swarm ci-simulate --base origin/main --head <pr-branch>
+   /swarm ci-simulate [<pr-ref>]
    ```
-   By default this runs fixed local CI gates: `bun run typecheck`,
-   `bun run lint:ci`, `bun run build`, `bun run test:unit:ci`,
-   integration/security/smoke tests, and `bun run drift:check`.
-   `test:unit:ci` runs unit tests per file with the repo's quarantine filters
-   and retry budget, matching CI's mock-isolation semantics. The command creates
-   a temporary detached worktree under `.swarm/ci-simulate`, merges the PR branch
-   or current worktree commit, runs the gate sequence, removes the worktree, and
-   prunes metadata. It does not accept arbitrary shell commands.
-3. **Manual fallback:** If the command is unavailable, create a temporary simulation worktree (do NOT mutate the PR branch). Use a project-relative path UNDER the swarm worktree base so the path is portable across OSes and its later removal is permitted by the worktree guardrail (paths outside `.swarm-worktrees/` are blocked). Do NOT hardcode `/tmp` — it does not exist on Windows.
+   The optional positional `<pr-ref>` is the PR branch/ref to simulate (defaults to the current branch). It does NOT accept `--base`/`--head` flags. The command runs fixed local gates: `bun run typecheck`, `bun run lint`, `bun run build`, then a full-batch `bun test`. It creates a temporary detached worktree under `os.tmpdir()/swarm-ci-simulate` (a SIBLING of the project root, not project-relative), merges the PR ref, runs the gate sequence, removes the worktree, and prunes metadata. It does not accept arbitrary shell commands and does NOT replicate CI's quarantine/retry semantics — it is a fast pre-merge signal, not a CI parity check.
+3. **Manual fallback:** If the command is unavailable, create a temporary simulation worktree (do NOT mutate the PR branch). The default worktree base is a SIBLING of the project root (`<parent>/.swarm-worktrees/`), overridable via the `worktree_dir` config; on Windows, very long paths may be shortened to `os.tmpdir()/swwt/...`. Place the worktree under that base. Do NOT hardcode `/tmp` — it does not exist on Windows.
    ```
-   git worktree add .swarm-worktrees/merge-sim origin/main
-   cd .swarm-worktrees/merge-sim
+   git worktree add ../.swarm-worktrees/merge-sim origin/main
+   cd ../.swarm-worktrees/merge-sim
    git merge <pr-branch> --no-edit
    ```
 4. **Run integration + unit tests against the merged result:**
@@ -36,7 +29,7 @@ Before adding the PR to the merge queue (or before the final push if the repo us
    ```
    (Use per-file loops for hot modules per AGENTS.md invariant 6)
 5. **If failures:** Fix on the PR branch, re-push, re-simulate. Always run the cleanup step (6) before re-simulating or on any exit path — do not leave the simulation worktree behind.
-6. **Cleanup for manual fallback (run on EVERY exit path, including failure):** `git worktree remove --force .swarm-worktrees/merge-sim`. If the remove is guardrail-blocked or fails, delete the directory directly and run `git worktree prune`.
+6. **Cleanup for manual fallback (run on EVERY exit path, including failure):** Prefer non-force `git worktree remove ../.swarm-worktrees/merge-sim`. If the removal is blocked or fails, surface the block to the user (the worktree guard fails closed for safety) and run `git worktree prune`.
 7. **Only after simulation passes,** add PR to the merge queue.
 
 ## Why this matters