opencode-swarm 7.140.3 → 7.140.5

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

@@ -60,7 +60,7 @@ If `council.general.enabled` is true in the resolved opencode-swarm config AND a
     → REQUIRED: The reviewer Task dispatch MUST contain a literal `ACCEPTANCE:` line. This is a pre-plan spec review (no fr_refs yet), so resolve per ACCEPTANCE FIELD RESOLUTION in your system prompt using a one-line task-derived DONE restatement, e.g. "DONE = reviewer flags HOW-encoded requirements, untestable requirements, missing edge cases, and silent assumptions in the draft spec." A missing line is BLOCKED by ACCEPTANCE_FIELD_REQUIRED.
 - 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`.
+- Resolve the effective spec first via `/swarm sdd status` (issue #2131 finding 9): write `.swarm/spec.md` ONLY when no non-native effective spec (openspec / speckit projection) is active — those sources are read-only inputs (see the status output's `allowed mutations` line); refine them in their own tool instead of shadowing them.
 - Exit when reviewer signs off (or user explicitly accepts remaining disagreements).
 
 **Phase 6: DEFER QA AND EXECUTION PROFILE SELECTION.**

package/.opencode/skills/ci-failure-batching/SKILL.md

@@ -21,7 +21,17 @@ check set is complete and includes all known failed checks in `failedChecks`.
    - For each: `gh run view <run-id> --log-failed`
    - Build a complete failure ledger
 4. **Fix ALL failures in one changeset:** Cluster by root cause, fix each cluster, verify locally
-5. **Push the fixes in one cycle.** Amend the commit and push. NOTE: `git push --force` / `--force-with-lease` is deny-pattern-blocked by the guardrail in guarded sessions (no orchestrator exemption). If force-push is blocked, push a normal new fix commit instead — the batching goal is ONE push cycle (collect all → fix all → push once), not literally one commit. A single new commit containing all batched fixes satisfies the goal.
+5. **Publish through `commit-pr`.** This skill owns diagnosis and fix-planning
+   ONLY (issue #2131 criterion E): before any commit or push, compose the
+   `commit-pr` skill for the commit message, PR body/invariant-audit/test-plan
+   discipline, and the push protocol. The batching goal is ONE push cycle
+   (collect all → fix all → push once), not literally one commit — a single new
+   commit containing all batched fixes satisfies the goal. Guardrail facts (verified in the
+   tool-before push guardrail): bare `git push --force`
+   and `-f` are deny-pattern-blocked; `--force-with-lease` is EXEMPT because it
+   refuses to overwrite remote work gained since your last fetch — commit-pr
+   mandates it for fork/rebase flows. Even so, prefer a normal new fix commit
+   over amending an already-pushed commit.
 6. **Only re-push if NEW failures surface** that were not in the original batch.
 
 ## Why this matters

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

@@ -18,7 +18,7 @@ This skill was originally written for desktop Claude Code (Windows) with `gh`
 CLI. In the **remote execution / GitHub MCP** environment, use the equivalent
 MCP tools instead:
 
-| Desktop / `gh` CLI | Remote MCP equivalent |
+| Capability needed | `gh` CLI | Example remote-MCP shape (resolve the real names via ToolSearch) |
 |---|---|
 | `gh pr checks <number>` | `mcp__github__pull_request_read` method `get_check_runs` |
 | `gh pr view <number> --json checks` | `mcp__github__pull_request_read` method `get_check_runs` |
@@ -26,9 +26,11 @@ MCP tools instead:
 | `gh pr edit --title` | `mcp__github__update_pull_request` with `title` |
 | `gh pr view --json mergeable` | `mcp__github__pull_request_read` method `get` |
 
-> MCP tool names are injected by the runtime harness and not guaranteed to be
-> stable across environments. Use `ToolSearch` to verify availability before
-> calling any `mcp__github__*` tool for the first time in a session.
+> MCP tool names are injected by the runtime harness and are NOT stable across
+> environments. Treat the right-hand column as an example SHAPE only: resolve
+> the actual tools by CAPABILITY (PR read with check-run support, job-log read,
+> PR update) via `ToolSearch` before first use in a session — never assume a
+> specific `mcp__github__*` name exists (issue #2131 finding 9).
 
 ## Step 1 — Fetch current status
 

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

@@ -18,4 +18,4 @@ 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 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.
+- 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 to `.swarm/context.md` under a `## Project Governance` section — append if the section exists, create it if not — PRESERVING PROVENANCE for every rule (issue #2131 finding 9): each entry records (a) its source file, (b) the subtree scope the file declares or implies (repo-wide when undeclared), (c) precedence — `AGENTS.md`/`project-instructions.md` outrank `CONTRIBUTING.md`/`INSTRUCTIONS.md`/`CLAUDE.md` when rules conflict, (d) strength (MUST vs SHOULD), and (e) a conflict flag naming the other file whose rule it contradicts, if any. Never flatten conflicting rules into one; surface the conflict. 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/durable-session-state/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: durable-session-state
+audience: swarm-plugin
+description: >
+  Persist plans, scope decisions, evidence, and reviewer/critic verdicts to
+  durable files during long or multi-phase tasks so work survives context
+  compaction, session resumes, and handoffs. Use for swarm-mode tasks, before
+  context grows large, when recording approval gates, and when resuming after
+  compaction or a session restart.
+---
+
+# Durable Session State
+
+Long swarm-mode sessions outlive their context window. Compaction summarizes
+history, and summaries lose exactly the things the swarm gates depend on:
+which diff a reviewer approved, what evidence was recorded, which decisions
+are settled. Without durable artifacts, a resumed session re-litigates settled
+decisions or — worse — treats a stale approval as current. Persist state to
+files as you go; treat the conversation as cache, not storage.
+
+## Where artifacts live
+
+- Generic swarm tasks: `.claude/session/tasks/<task-slug>/` in the project.
+- Issue-tracer work: `.claude/issue-traces/<issue>/` (that skill's own schema
+  — `08b-implementation-review.md`, `09-final-critic.md` — wins for its work).
+- Never write task artifacts to the repo root, and never under `.swarm/` —
+  that directory is the OpenCode plugin's runtime state, not Claude Code's.
+- These artifacts are working state, not deliverables: do not commit them
+  unless the user asks. Before committing, check `git status` and exclude
+  them explicitly.
+
+## What to persist
+
+Keep it to four small files per task; update in place:
+
+1. `plan.md` — task scope, success criteria, files in scope, what must not
+   break. Update when scope changes; never fork a second plan file.
+2. `decisions.md` — one line per settled decision with a one-line rationale
+   ("chose X over Y because Z"). Settled means: do not reopen without new
+   evidence or a user request.
+3. `evidence.md` — validation commands run and their outcomes (pass/fail plus
+   the load-bearing output lines, not full logs).
+4. `gates.md` — the approval ledger. One entry per reviewer/critic verdict:
+
+   ```
+   ## <gate> — <APPROVE|NEEDS_REVISION|BLOCKED>
+   when: <ISO timestamp or turn marker>
+   head: <git rev-parse HEAD>
+   diff: <git diff --stat summary>
+   items: <blocking items, or none>
+   ```
+
+## When to write
+
+- At phase boundaries (scope settled, plan built, implementation done, each
+  gate verdict received).
+- Before ending a turn while background subagents are running.
+- Whenever you notice the conversation is long — write ahead of compaction,
+  not after it.
+
+## Resume protocol
+
+On resuming (after compaction, a restart, or a handoff), before doing new
+work:
+
+1. Re-read the task's artifacts. They are authoritative over your memory of
+   the conversation.
+2. Do not re-litigate `decisions.md` entries or redo work `evidence.md`
+   already proves, absent new evidence or a user request.
+3. Check gate staleness: if `git rev-parse HEAD` or the working-tree diff no
+   longer matches the latest APPROVE entry in `gates.md`, that approval is
+   invalid — re-run the affected reviewer/critic gate on the current diff.
+4. If artifacts and the summarized conversation disagree, trust the artifacts
+   and say so.
+
+## Relationship to swarm gates
+
+The swarm-mode contract invalidates any approval issued before the latest
+edit. The `gates.md` ledger is what makes that rule *checkable* instead of
+vibes: record the HEAD and diff summary at approval time, compare on resume
+and before final synthesis. If you cannot demonstrate approval-after-last-edit
+from the ledger, the gate is not satisfied.

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

@@ -201,7 +201,7 @@ When a sandbox executor (`src/sandbox/{linux,macos,win32}/*.ts`) interpolates en
 
 - **Keys must match POSIX env-var name syntax.** Every env key must be validated against the regex `/^[A-Za-z_][A-Za-z0-9_]*$/` (a leading letter or underscore, then letters/digits/underscores) before being interpolated. Define or reuse a single `isValidEnvKey(key: string): boolean` helper colocated with the `SandboxExecutor` interface in `src/sandbox/executor.ts` (around line 24+); do not duplicate the regex inline at every call site. Keys that fail validation must be silently dropped (not raised) so that one bad caller cannot wedge the sandbox path — but the drop must be observable in the advisory/observability layer (`pendingAdvisoryMessages` or structured log), never silent.
 - **Values must be shell-quoted or treated as opaque single tokens.** On POSIX, prepend a leading single quote, escape any embedded single quotes by replacing `'` with `'\''`, and append a trailing single quote. On Windows PowerShell, **prefer single-quoted literal contexts (e.g. `'$env:NAME'`) and run values through a `psStringEscape`-style helper that escapes backtick, `$`, `"`, and `` ` ``** (the special characters in double-quoted PowerShell strings). Single-quoted PowerShell strings are literal — only `'` needs escaping, doubling it to `''`. If a context requires double-quoted PS values, escape embedded `"` as `` ` ``, backtick as `` `` ``, and `$` as `` ` `` (backtick is the PS escape character in double-quoted strings; `$` must be escaped to prevent variable expansion). On bwrap, always pass values as separate argv tokens after the `--setenv` flag (`--setenv KEY VALUE`, two tokens), never as a single concatenated `KEY=VALUE` token that an intermediate shell would interpret.
-- **Use the array-form argv for every sandbox subprocess.** Never `shell:`-interpolate. The same invariant-3 rules (`array-form spawn`, `stdin: 'ignore'`, `cwd`, `timeout`, `proc.kill()` in `finally`) apply to sandbox spawns as to any other subprocess — see the `subprocess-safety` cross-link.
+- **Use the array-form argv for every sandbox subprocess.** Never `shell:`-interpolate. The same invariant-3 rules (`array-form spawn`, `stdin: 'ignore'`, `cwd`, `timeout`, `proc.kill()` in `finally`) apply to sandbox spawns as to any other subprocess; opencode-swarm repository contributors can also consult the repo's subprocess-safety developer skill.
 
 ## Sandbox fallback parity (Windows and Linux)
 

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

@@ -84,17 +84,23 @@ its receipt gates ARE the mechanical implementation for the parts it owns):
 - **Plan-critic gate before EXECUTE** — the reducer will not advance to EXECUTE until the
   plan-critic approval is observed.
 - **Authoritative plan state** — read through the ledger-aware loader, never the projection.
+- **Independent implementation review before commit-pr handoff** — fresh-context reviewer
+  AND critic passes must both approve the diff; record them with
+  `record_implementation_review` (else the engine emits a one-shot review directive). The
+  receipt is an agent self-attestation of the fresh-context discipline; under
+  PR-review/feedback modes the mechanically authenticated reviewer gates remain the
+  PR-workflow machinery.
+- **Recurrence sweep before commit-pr handoff** — the defect class must be characterized,
+  searched with explicit predicates, every hit dispositioned, and a guardrail installed
+  with proof it catches the original defect (or the "no defect class" fast path recorded);
+  record it with `record_recurrence_sweep` (else the engine emits a one-shot sweep directive).
 - **Honest completion** — `publication_handoff` is NOT "resolved"; terminal `published` needs
   an issue-bound publication receipt.
 - **Durable delivery** — a transition persists only after its directive is delivered.
 
-The following Contract obligations are NOT mechanically enforced by the trace engine and
-remain the responsibility of the agent / owning skills (tracked as residual criterion-B
-work on issue #2131, not yet composed into this path): the **independent implementation
-review** (separate reviewer/critic contexts on the diff — when run under PR-review/feedback
-modes those are enforced by the PR-workflow gates, not by this trace engine) and the
-**recurrence sweep** (checking for related prior fixes of the same root cause). Surface
-both honestly in the trace's evidence; do not claim the Contract is fully composed here.
+With these receipts the Full-Resolution Contract is mechanically composed into this trace
+path end to end; the receipts are issue-bound and survive until the next `/swarm issue` or
+`/swarm reset`.
 
 RULES:
 - One question per message in INTAKE dialogue (max 6 questions)

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

@@ -74,7 +74,7 @@ Use these sources in this order.
 Before meaningful work, discover the repository's own contract in this order. Do not assume one project's conventions apply to another.
 
 1. Read the repo-root agent instruction files (`AGENTS.md` and any runtime-specific root instruction file your agent loads).
-2. Read the repo's contributing/commit/test skills or docs if present (e.g. a `contributing` guide, a `writing-tests` skill, a `commit-pr` skill).
+2. Read the repo's contributing/commit/test skills or docs if present (e.g. a contributing guide, a `writing-tests` skill, a `commit-pr` skill).
 3. Inspect manifests (package/build metadata), test configs, and CI configs to learn the verification commands — from files, not memory.
 4. Only if an invariants/architecture-contract doc exists, perform the invariant audit against it and record touched-invariant evidence in the PR body. If none exists, state "no invariant doc found" in the PR body — never fabricate an audit.
 

package/.opencode/skills/orchestrating-subagents/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: orchestrating-subagents
+audience: swarm-plugin
+description: >
+  Tiering and economics for delegating to subagents: which agent type, model,
+  and effort to use per role (explorer, implementer, reviewer, critic), how many
+  agents to launch in parallel, how to write scoped subagent prompts with
+  bounded structured returns, and how to keep the main context clean. Use when
+  launching subagents, parallel explorers, independent reviewers, or critic
+  passes — especially for swarm-mode, qa-sweep, or issue-tracer work.
+---
+
+# Orchestrating Subagents
+
+Swarm-mode work in this repo delegates heavily (explorer → reviewer → critic).
+This skill defines HOW to delegate so validation gates stay strong while
+breadth stays fast and cheap. It complements — never replaces — the gates in
+`.claude/session/swarm-mode.md`, qa-sweep, and swarm-implement.
+
+## Role → tier mapping
+
+| Role | Agent type | Model / effort | Rationale |
+|---|---|---|---|
+| Explorer (mapping, candidate findings) | `Explore` when read-only suffices | Cheaper/faster tier acceptable; low–medium effort | Recall-bound, not reasoning-bound; the reviewer gate catches misses |
+| Implementer (scoped edits) | general-purpose | Session model; medium–high effort | Edits need project conventions (CLAUDE.md context) |
+| Reviewer (independent validation) | general-purpose, **fresh context** | Session (strongest) model; high effort | Precision-bound; false approvals are the expensive failure |
+| Critic (final challenge) | general-purpose, **fresh context** | Session (strongest) model; high effort | Same — this is the last line of defense |
+
+Hard rule: economize on explorers, never on reviewers or critics. If the
+harness exposes model or effort overrides for subagents, tier explorers down;
+do not tier the reviewer or critic below the session model or below high
+effort. If no override is available, tier by agent type (`Explore` is
+lightweight: read-only tools, skips CLAUDE.md) and by prompt scope.
+
+## Fan-out discipline
+
+- Launch parallel agents only for **disjoint scopes**. Before launching, write
+  one line per agent stating its scope; if two overlap, merge them.
+- 2–4 explorers per wave is a heuristic only when the active workflow does
+  not define its own fan-out contract. A workflow-specific contract overrides
+  this heuristic: PR review, for example, requires all six base dimensions and
+  all eleven risk families to be covered on every PR — its capability profiles
+  and depth tiers (see swarm-pr-review) govern how many lanes carry that
+  coverage, and under the plugin's mechanical controller the tier is computed
+  from the bound diff and the matching lane floors are enforced outright. No
+  time, cost, repository-size, or simplicity
+  rationale may reduce the coverage a workflow mandates.
+  Outside fixed-fan-out workflows, more agents than distinct scopes adds token
+  cost and synthesis burden without adding recall.
+- Launch independent agents **in a single message** so they run concurrently.
+- Do not re-run a search an agent is already doing; wait for its report.
+- Scale waves, not width: if the first wave surfaces new territory, launch a
+  second targeted wave rather than one giant speculative first wave.
+
+## Subagent prompt contract
+
+Every delegation prompt must state:
+
+1. **Scope** — exact directories, files, or question. Name what is out of scope.
+2. **Deliverable** — the structure of the report (per-item findings, then a
+   ranked summary). The agent's final message is the only thing you receive.
+3. **Evidence bar** — exact `file:line` references; no invented paths; verify a
+   path exists before citing it.
+4. **Status labels** — explorers return CANDIDATE findings only; reviewers
+   classify CONFIRMED / DISPROVED / UNVERIFIED / PRE_EXISTING; reviewer and
+   critic verdicts are APPROVE / NEEDS_REVISION / BLOCKED.
+5. **Output bound** — compact structured returns; no full-file dumps.
+
+For reviewers and critics additionally:
+- Give the **claims and locations**, not the author's justification — the
+  reviewer must re-derive, not confirm, the reasoning.
+- State the adversarial default explicitly: "default to DISPROVED/UNVERIFIED
+  unless the code evidence supports the finding."
+- A reviewer or critic must be a **fresh agent**, never a continued
+  conversation with the agent whose work it judges.
+
+## Independence and staleness
+
+- Reviewer and critic review the **latest diff**, not a description of it. Give
+  them the branch state and the validation evidence, and require them to run
+  `git diff`/`git log` themselves.
+- Any edit after an approval invalidates it. Record what was approved (e.g.
+  `git rev-parse HEAD`, `git diff --stat`) so staleness is checkable — see the
+  durable-session-state skill.
+
+## Nesting limitation
+
+Whether a subagent can spawn further subagents depends on the harness and
+agent type — check whether a subagent tool (`Agent` or `Task`) is actually
+available in your context before assuming either way. If a skill mandating
+fresh-subagent review (qa-sweep, swarm-implement) executes in a context
+**without** a subagent tool:
+- perform the same review checklist yourself as a clearly labeled
+  **fallback self-review**, and
+- disclose in your report that independent review was unavailable in this
+  context, so the orchestrator can re-run the gate with a real fresh agent.
+Never silently present self-review as independent review.
+
+## Main-context hygiene
+
+- Push reading-heavy work into subagents; keep the main thread for scoping,
+  synthesis, and decisions.
+- Do not paste subagent transcripts or large tool outputs back into the main
+  thread; carry forward only validated findings and verdicts.
+- When a subagent report arrives, extract the load-bearing facts into your
+  durable task artifacts (see durable-session-state) before moving on.
+
+## When not to delegate
+
+Answer directly, without a subagent, when the task is a single-fact lookup you
+can resolve with one or two targeted Grep/Read calls, or when you already know
+the file and symbol. Delegation overhead should buy breadth, isolation, or
+independence — if it buys none of those, skip it.

package/.opencode/skills/parallel-work-check/SKILL.md

@@ -122,7 +122,7 @@ The parallel-work-check skill is referenced by other skills that start work on a
 | Skill | Usage |
 |-------|-------|
 | `file:.swarm/bundled-skills/swarm-pr-feedback/SKILL.md` | Checks before starting PR feedback fixes — ensures no parallel work has already addressed the same findings |
-| Legacy `pr-review-fix` alias | Compatibility entry that delegates to the bundled `swarm-pr-feedback` protocol |
+| Legacy pr-review-fix alias | Compatibility entry that delegates to the bundled `swarm-pr-feedback` protocol |
 | `file:.swarm/bundled-skills/swarm-implement/SKILL.md` | Checks before implementation Phase 1 — ensures the branch is up-to-date before planning |
 | Any skill that starts work on an existing branch | Run the parallel-work-check protocol before beginning fixes or implementation |
 

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

@@ -11,16 +11,41 @@ This protocol is loaded on demand by the architect runtime. The architect prompt
 
 ### MODE: PLAN
 
-SPEC GATE (soft — check before planning):
+PLANNING PROFILE (authoritative): obey the runtime-injected `[PLANNING PROFILE
+— AUTHORITATIVE]` directive, which is produced by the same resolver used by
+`save_plan`. Select exactly one path:
+
+- `balanced`: use durable QA/execution defaults and do not pause for the full
+  questionnaire, spec ceremony, or complete clarification funnel. Ask only for
+  unresolved material ambiguity, destructive/high-risk authorization, or a
+  decision only the user can make. `save_plan` exact-binds the default QA
+  profile. Persist `planning_profile: "balanced"`.
+- `strict` (including locked legacy profiles with no stored field): require an
+  effective spec, run the complete clarification funnel, present the unified
+  QA/execution questionnaire, and wait for the user's answers before saving.
+  Persist `planning_profile: "strict"` only when the field is already explicit
+  or this is a new/unlocked plan; do not materialize it into a locked legacy
+  profile.
+
+A locked profile may ratchet `balanced` to `strict`; it never moves `strict` to
+`balanced`.
+
+SPEC POLICY (profile-dependent — check before planning):
 
 An effective spec exists iff `/swarm sdd status` reports a resolved spec (it reflects `readEffectiveSpecSync`, which returns null for no sources, multiple competing sources, multi-feature Spec-Kit without a selected feature, or any unresolvable state). Do NOT enumerate these cases — defer to `/swarm sdd status`.
 
 - If NO effective spec exists (confirmed via `/swarm sdd status`):
+  - `strict`: stop and enter MODE: SPECIFY (or materialize a selected SDD source
+    with explicit consent). Strict planning cannot save without an effective
+    spec.
+  - `balanced`: a spec is optional. Offer the choices below only when a spec
+    would materially resolve ambiguity; otherwise proceed directly.
+  - The remaining no-spec choices in this section apply only to `balanced`.
   - PLAN INGESTION DETECTION: Check if the user is providing an external plan (indicators: markdown content with Phase/Task structure, or phrases like "ingest this plan", "implement this plan", "prepare for implementation", "here is a plan", "here's the plan"):
     - If plan ingestion is detected AND no effective spec exists: offer this choice FIRST before any planning:
       1. "Generate spec from this plan first" → enter EXTERNAL PLAN IMPORT PATH in MODE: SPECIFY to reverse-engineer a spec.md from the provided plan, then return to planning
       2. "Skip spec and proceed with the provided plan" → proceed directly to plan ingestion and planning without creating a spec
-    - This is a SOFT gate — option 2 always lets the user proceed without a spec
+    - In `balanced`, this is a SOFT gate — option 2 lets the user proceed without a spec.
   - If no plan ingestion detected: Warn: "No effective spec found. A spec helps ensure the plan covers all requirements and gives the critic something to verify against. Would you like to create one first?"
     - Offer two options:
       1. "Create a spec first" → transition to MODE: SPECIFY
@@ -28,20 +53,21 @@ An effective spec exists iff `/swarm sdd status` reports a resolved spec (it ref
 - If an effective spec EXISTS:
   - NOTE: Stale detection is intentionally heuristic (compare headings) — false positives are acceptable because this is a SOFT gate. When in doubt, ask the user.
   - Read the spec (using the effective spec path reported by `/swarm sdd status`) and compare its first heading (or feature description) against the current planning context (the user's request and any existing plan.md title/phase names)
-  - STALE SPEC DETECTION: If the spec heading or feature description does NOT match the current work being planned (e.g., spec describes "user authentication" but user is asking to plan "payment integration"), treat the spec as potentially stale and offer three options:
+  - STALE SPEC DETECTION: If the spec heading or feature description does NOT match the current work being planned (e.g., spec describes "user authentication" but user is asking to plan "payment integration"), treat the spec as potentially stale. In `strict`, offer options 1 and 2 only. In `balanced`, offer all three options:
     1. **Archive and create new spec** → attempt to rename .swarm/spec.md to .swarm/spec-archive/spec-{YYYY-MM-DD}.md (create the directory if needed); if archival succeeds: enter MODE: SPECIFY and skip the "spec already exists" prompt; if archival fails: inform user of the failure and offer: retry archival, or proceed with option 2, or proceed with option 3
     2. **Keep existing spec** → use the effective spec as-is and proceed with planning below
-    3. **Skip spec entirely** → proceed to planning below ignoring the existing spec
+    3. **Skip spec entirely** (`balanced` only) → proceed to planning below ignoring the existing spec
   - If the spec appears current (heading matches the work being planned) OR user chose option 2 above, proceed with spec:
     - Read it and use it as the primary input for planning
     - Cross-reference requirements (FR-###) when decomposing tasks
     - Ensure every FR-### maps to at least one task
     - If a task has no corresponding FR-###, flag it as a potential gold-plating risk
-  - If user chose option 3 above, proceed without spec: skip all spec-based steps and proceed directly to planning
+  - If a `balanced` user chose option 3 above, proceed without spec: skip all spec-based steps and proceed directly to planning
 
-This is a SOFT gate. When the user chooses "Skip and plan directly", proceed to the steps below exactly as before — do NOT modify any planning behavior.
+This is a soft gate only in `balanced`. In `strict`, a missing effective spec is
+a hard prerequisite and `save_plan` will return `SPEC_REQUIRED`.
 
-**SAVE_PLAN SPEC_REQUIRED RECOVERY:**
+**STRICT-ONLY SAVE_PLAN SPEC_REQUIRED RECOVERY:**
 When `save_plan` returns a SPEC_REQUIRED rejection (no effective spec found), the architect MUST:
 1. DIAGNOSE: run `/swarm sdd status` to determine why no effective spec resolved.
    - (a) If `/swarm sdd status` shows NO sources → transition to MODE: SPECIFY.
@@ -54,7 +80,7 @@ Run CODEBASE REALITY CHECK scoped to codebase elements referenced in the effecti
 
 ### GENERAL COUNCIL ADVISORY OPTION (pre-save_plan)
 
-Before drafting or saving the plan, the architect MUST offer General Council advisory input when `council.general.enabled` is true in the resolved opencode-swarm config and a search API key is configured.
+In `strict`, before drafting or saving the plan, the architect MUST offer General Council advisory input when `council.general.enabled` is true in the resolved opencode-swarm config and a search API key is configured. In `balanced`, offer it only when current external facts could materially change the plan; do not introduce a pause merely because the feature is configured.
 
 - Ask the user: "Use General Council advisory input before I write the plan? The 3-agent council (generalist, skeptic, domain expert) will gather current external context and provide perspectives that I will fold into the plan before critic review. (default: no)"
 - If the user declines, proceed to the clarification funnel and planning normally.
@@ -70,7 +96,7 @@ General Council is advisory and distinct from `council_mode`, `phase_council`, a
 
 ### CLARIFICATION FUNNEL (pre-save_plan)
 
-Before calling `save_plan` — whether creating a new plan or finalizing an external plan ingestion — the architect MUST run this four-stage clarification funnel. The goal is to limit unnecessary user interruption, not planning completeness.
+In `strict`, before calling `save_plan` — whether creating a new plan or finalizing an external plan ingestion — the architect MUST run this four-stage clarification funnel. In `balanced`, use the same classification concepts internally but surface only unresolved material ambiguity, destructive/high-risk authorization, or decisions only the user can make; do not run the full funnel as ceremony.
 
 #### Stage 1: Inventory All Material Uncertainties
 
@@ -113,6 +139,8 @@ For each item classified as `research_needed` or `user_decision` in Stage 2, sen
 
 **Hard constraint:** Items in the Always-Surface Categories list (below) MUST NOT receive `UNNECESSARY`/`DROP` from the critic — only `REPHRASE` or `APPROVED`/`ASK_USER` are allowed. If the critic attempts to `UNNECESSARY`/`DROP` an always-surface item, override to `APPROVED`/`ASK_USER`.
 
+This always-surface protection remains mandatory in every planning profile.
+
 **Overconfidence guard:** If the critic attempts to self-resolve an item by supplying an answer (verdict `RESOLVE`) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as `user_decision` rather than `self_resolved`. Unsupported defaults must not be silently accepted.
 
 Update classifications based on critic response:
@@ -124,7 +152,7 @@ Update classifications based on critic response:
 
 The architect MUST update the plan's assumptions with all resolved items before proceeding to Stage 4.
 
-Exception: QA gate selection questions are already mandatory user decisions (enforced by the save_plan tool itself) and do NOT need to go through the funnel. QA gate selection is always a direct user dialogue.
+Strict-only exception: QA gate selection questions are direct user decisions and do NOT need to go through the funnel. Balanced uses the durable default profile and does not present this dialogue.
 
 #### Stage 4: Surface User Decision Packet
 
@@ -182,7 +210,7 @@ Draft the complete implementation plan in memory first. Required parameters:
 
 1. Finish drafting the title, swarm identifier, phases, tasks, dependencies, and `files_touched` scopes. Freeze the exact raw plan identity as `swarm_id` plus `plan_title` (the same title passed to `save_plan`). Do not normalize, shorten, or rename either value between profile creation and plan save. An intentional identity replacement must use `confirm_identity_change: true`; never silently create a second profile because wording changed.
 2. Inspect dependency-ready tasks and their file scopes before recommending parallelism. File-disjoint task groups may run concurrently in isolated worktrees; overlapping or unknown scopes require serial execution.
-3. Present the following unified four-choice dialogue in one message and wait for one complete answer. Silence is not consent.
+3. `strict`: present the following unified four-choice dialogue in one message and wait for one complete answer. Silence is not consent. `balanced`: skip this dialogue and continue with the durable defaults.
 
 <!-- BEGIN QA_GATE_BODY -->
 
@@ -208,7 +236,7 @@ Additionally, present these three sub-items as part of the same exchange:
 <!-- END QA_GATE_BODY -->
 
 4. MODE: LOOP exception: when `autonomy=auto`, do not pause. Use the loop skill's balanced-speed defaults: reviewer, test_engineer, sme_enabled, critic_pre_plan, sast_enabled, and drift_check ON; council_mode, hallucination_guard, mutation_test, phase_council, and final_council OFF. Choose the largest safe parallel count from the drafted scopes (1 when overlap or uncertainty exists), keep phase-level commits (`commit_after_each_completed_task: false`), and set `auto_proceed: true`.
-5. Before the first `save_plan`, persist all eleven gate booleans with `set_qa_gates({ swarm_id: <exact swarm_id>, plan_title: <exact title>, ...gates })`. If it fails, stop and resolve the profile error; do not save a plan without the matching profile.
+5. `strict`: before the first `save_plan`, persist all eleven gate booleans with `set_qa_gates({ swarm_id: <exact swarm_id>, plan_title: <exact title>, ...gates })`. If it fails, stop and resolve the profile error. `balanced`: do not call `set_qa_gates` merely to reproduce defaults; `save_plan` creates and exact-binds them.
    Recovery for upgraded legacy plans: if `get_qa_gate_profile`, `save_plan`, or an execution gate reports that the QA profile is not exact-bound, run `set_qa_gates({ swarm_id: <exact swarm_id>, plan_title: <exact title>, adopt_legacy_binding_only: true })`. This exact-binds the existing profile without changing gates or its lock, then you retry the blocked read/save/enforcement step.
 6. Immediately call `save_plan` with the same exact identity, the full drafted phases, and the complete locked profile:
 

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

@@ -55,14 +55,16 @@ ci-fix-monitor; do not re-derive it here.
 The canonical uses the `gh` CLI. In remote/MCP environments, use the equivalent
 MCP tools and verify availability first:
 
-| `gh` CLI | Remote MCP equivalent |
+| Capability needed | `gh` CLI | Example remote-MCP shape (resolve the real names via ToolSearch) |
 |---|---|
 | `gh pr checks <N>` | `mcp__github__pull_request_read` method `get_check_runs` |
 | `gh pr view <N> --json mergeable,mergeStateStatus,reviewDecision` | `mcp__github__pull_request_read` method `get` |
 | `gh run view <run> --log` | `mcp__github__get_job_logs` with `job_id`, `return_content: true` |
 
-> MCP tool names are injected by the harness and not stable across
-> environments. Use `ToolSearch` to verify before first use in a session.
+> MCP tool names are injected by the harness and are NOT stable across
+> environments. The right-hand column is an example SHAPE only: resolve tools
+> by CAPABILITY (PR read, job-log read) via `ToolSearch` before first use —
+> never assume a specific `mcp__github__*` name exists (issue #2131 finding 9).
 
 ## Step 1 — Pre-flight gates (run ONCE, before entering the loop)
 

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

@@ -619,10 +619,32 @@ settle on the Stage-A digest. After they settle, only one standalone `git commit
 command may create the reviewed commit; push and remote publication remain
 blocked until that exact commit is armed. The first completion requires a clean
 index/worktree and a non-merge direct child commit whose sole parent is the
-immutable intake head, so zero commits, multiple commits, merge commits,
+immutable intake head, so multiple commits, merge commits,
 amend/non-descendant histories,
 `--allow-empty`, and partially committed reviewed content fail closed. There is no speed, efficiency, token, or time exception.
 
+**Verified no-change terminal (issue #2131 C1).** When the ENTIRE immutable
+inventory is verified as a no-change outcome — every `FB-###` item classified
+`DISPROVED`, `PRE_EXISTING`, `NEEDS_MORE_EVIDENCE`, or `NEEDS_USER_DECISION`
+in the settled verification lanes — a correct workflow needs NO content commit.
+After every ordered gate settles, call `complete_pr_workflow` with the intake
+`pr_head_sha` while HEAD still equals that intake head and the tree is clean:
+it returns `verified-no-change` and clears the gate terminally (nothing to
+publish; an empty or `--allow-empty` commit is still forbidden). Any item
+classified `CONFIRMED`/`PARTIAL` requires the ordinary exactly-one-reviewed-
+commit path above.
+
+**Base-sync/rebind (issue #2131 C2).** When base drift or merge conflicts force
+a merge/rebase, the repaired history is no longer a direct child of the intake
+head and the ordinary publication path can never be satisfied. Do NOT abort
+ad-hoc: finish the repair, fetch the new authoritative PR head, check it out,
+then call `rebind_pr_feedback_head` with the new full PR head SHA. It moves the
+immutable intake head to the new head, preserves the immutable inventory, and
+invalidates every ancestry-bound receipt (Stage A, verification, ordered
+gates) — re-run the entire mechanical ladder on the new ancestry. It refuses a
+no-op rebind, refuses while publication is armed, and refuses while lanes are
+in flight.
+
 **Without the controller (Profiles B/C).** The same gates run in the same
 order with the same one-row-per-feedback-ID verdict contracts; what changes is
 the executor. Stage A: run the repository's discovered build, typecheck, and
@@ -691,9 +713,13 @@ because a name such as `test` or `build` can hide a no-op. A
 reproduction must also return non-empty machine-observable runner output.
 The reproduction check also supplies one `feedback_targets` row per immutable
 feedback ID, in inventory order: exact `feedback_item_id`, one executed `target`,
-and concrete `expected_behavior`. Missing, duplicate, invented, or target-less
-mappings block Stage B; the controller persists that exact per-item mapping
-rather than stamping an unrelated test onto the whole inventory.
+concrete `expected_behavior`, and a typed `proof_kind` (`defect`, `metadata`,
+`source-proof`, `conflict`, `ci`, or `user-decision`). Missing, duplicate,
+invented, target-less, or kind-less mappings block Stage B; the controller
+persists that exact per-item mapping. This is a STRUCTURAL mapping with a typed
+proof kind — it proves each item maps to a target the executed command actually
+selects, not that the target is causally decisive for that item; the Stage B
+reviewer lane owns that judgement (issue #2131 C4).
 No-op/help/list/dry-run,
 fix/update, package publication/deployment, Git mutation, remote client,
 shell/eval/wrapper, and credentialed publication surfaces fail closed. The

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

@@ -143,7 +143,7 @@ When test files pass individually but fail when run together, follow this protoc
 5. **Specific symptom — closure capture failure**: `vi.mock()` captures closures at **hoist time** (before `beforeEach` runs). Reassigning `mockFn.mockImplementation(newFn)` in the test body does **NOT** update the hoisted closure — the mock still calls the original function.
    - Symptom: `expect(mockFn).toHaveBeenCalledTimes(N)` fails with an unexpected count
    - Symptom: `expect(mockFn).not.toHaveBeenCalled()` fails because the real function was called
-6. **Fix path**: Migrate the affected test file to `_internals` DI seam pattern per the `mock-to-internals-migration` skill. This eliminates both the `vi.mock()` call and the closure capture surface area. **Exception — reference-captured functions**: if the source code passes a function as a direct argument or captures it in a closure at module scope (e.g., `transactFile(path, readKnowledge, ...)`), the reference bypasses `_internals` entirely — mutating `_internals.readKnowledge` changes only the object property, not the module-scope binding the source already holds. Migrating to `_internals` does not help. In that case, test via observable outcomes (e.g., run concurrent callers and assert on final persisted state).
+6. **Fix path**: Migrate the affected test file to the `_internals` DI seam pattern documented above (opencode-swarm repository contributors also have a dedicated mock-to-internals-migration skill that walks the recipe in depth). This eliminates both the `vi.mock()` call and the closure capture surface area. **Exception — reference-captured functions**: if the source code passes a function as a direct argument or captures it in a closure at module scope (e.g., `transactFile(path, readKnowledge, ...)`), the reference bypasses `_internals` entirely — mutating `_internals.readKnowledge` changes only the object property, not the module-scope binding the source already holds. Migrating to `_internals` does not help. In that case, test via observable outcomes (e.g., run concurrent callers and assert on final persisted state).
 
 ## Two-Tier Mock Convention
 

package/dist/agents/architect.d.ts

@@ -1,5 +1,6 @@
 import type { AgentConfig } from '@opencode-ai/sdk';
 export type { AgentConfig };
+import { type ResolvedPlanningProfile } from '../plan/planning-profile';
 export interface AgentDefinition {
     name: string;
     description?: string;
@@ -72,4 +73,4 @@ export declare function buildCouncilWorkflow(council?: CouncilWorkflowConfig): s
  * helper remains as a compatibility oracle for direct prompt-contract tests.
  */
 export declare function buildQaGateSelectionDialogue(modeLabel: 'BRAINSTORM' | 'SPECIFY' | 'PLAN'): string;
-export declare function createArchitectAgent(model: string, customPrompt?: string, customAppendPrompt?: string, adversarialTesting?: AdversarialTestingConfig, council?: CouncilWorkflowConfig, uiReview?: UIReviewConfig, memoryEnabled?: boolean, architecturalSupervision?: ArchitectureSupervisionWorkflowConfig, designDocsEnabled?: boolean, externalSkillsEnabled?: boolean, turboEnabled?: boolean, skillsEnabled?: boolean): AgentDefinition;
+export declare function createArchitectAgent(model: string, customPrompt?: string, customAppendPrompt?: string, adversarialTesting?: AdversarialTestingConfig, council?: CouncilWorkflowConfig, uiReview?: UIReviewConfig, memoryEnabled?: boolean, architecturalSupervision?: ArchitectureSupervisionWorkflowConfig, designDocsEnabled?: boolean, externalSkillsEnabled?: boolean, turboEnabled?: boolean, skillsEnabled?: boolean, planningProfileResolution?: ResolvedPlanningProfile): AgentDefinition;

package/dist/agents/reviewer-directive-compliance.d.ts

@@ -2,11 +2,12 @@
  * Reviewer DIRECTIVE_COMPLIANCE support (Swarm Learning System, Change 2 /
  * Task 2.1).
  *
- * The reviewer must emit a per-ID verdict for every knowledge directive shown
+ * The reviewer must emit a per-membership verdict for every knowledge directive shown
  * during the phase. This module owns:
  *   - DIRECTIVE_COMPLIANCE_OUTPUT_SPEC: the static format documentation embedded
  *     in the reviewer system prompt (always present).
- *   - buildDirectiveComplianceBlock: the dynamic, per-phase list of directive IDs
+ *   - buildDirectiveComplianceBlock: the dynamic, per-phase list of exact
+ *     trace + entry memberships
  *     to verify (with priorities + any verification_predicate), injected into the
  *     reviewer's delegation prompt at runtime.
  *
@@ -18,7 +19,15 @@ import type { DirectivePriority } from '../hooks/knowledge-types.js';
 export declare const DIRECTIVES_TO_VERIFY_TAG = "<directives_to_verify>";
 /** A directive the reviewer must produce a verdict for. */
 export interface DirectiveToVerify {
-    id: string;
+    /** Exact retrieval membership this verdict must close. */
+    trace_id: string;
+    entry_id: string;
+    /** Session recorded with the originating retrieval membership. */
+    session_id: string;
+    cohort_id?: string;
+    source_link_id?: string;
+    prior_terminal_outcome?: 'violated';
+    prior_terminal_event_id?: string;
     priority: DirectivePriority;
     lesson?: string;
     verification_predicate?: string;
@@ -27,10 +36,15 @@ export interface DirectiveToVerify {
  * Static spec embedded in the reviewer system prompt. Documents the mandatory
  * DIRECTIVE_COMPLIANCE output section and its verdict grammar.
  */
-export declare const DIRECTIVE_COMPLIANCE_OUTPUT_SPEC = "DIRECTIVE_COMPLIANCE: one line per knowledge directive shown during this phase (the IDs are listed in the DIRECTIVES TO VERIFY block of your prompt). Use exactly one of:\n  VERIFIED:<id> evidence=<file:line | predicate_passed>\n  VIOLATED:<id> evidence=<file:line | failing_predicate>\n  N/A:<id> reason=<why it does not apply to this change>\nEvery listed directive ID MUST appear exactly once. If a directive carries a verification_predicate, you MUST run it and report predicate_passed / failing_predicate as the evidence. Omitting a listed directive ID is itself a VIOLATED verdict.";
+export declare const DIRECTIVE_COMPLIANCE_OUTPUT_SPEC = "DIRECTIVE_COMPLIANCE: one line per retrieval membership shown during this phase. Copy the encoded trace_id and entry_id tokens exactly from the DIRECTIVES TO VERIFY block. Use exactly one of:\n  VERIFIED:<trace_id>:<entry_id> evidence=<file:line | predicate_passed>\n  VIOLATED:<trace_id>:<entry_id> evidence=<file:line | failing_predicate>\n  N/A:<trace_id>:<entry_id> reason=<why it does not apply to this change>\nEvery listed trace_id + entry_id pair MUST appear exactly once. The same entry_id may appear under more than one trace_id and requires one verdict per pair. If a directive carries a verification_predicate, you MUST run it and report predicate_passed / failing_predicate as the evidence. Omitting a listed CRITICAL pair is itself a VIOLATED verdict.";
+/** Encode arbitrary correlation identifiers into one delimiter-safe token. */
+export declare function encodeDirectiveCorrelationId(value: string): string;
+/** Decode one correlation token, rejecting malformed or unbounded values. */
+export declare function decodeDirectiveCorrelationId(token: string): string | null;
 /**
  * Render the per-phase "DIRECTIVES TO VERIFY" block injected into the reviewer's
- * delegation prompt. Deterministic (sorted by priority then ID). Returns null
+ * delegation prompt. Deterministic (sorted by priority then entry + trace).
+ * Returns null
  * when there is nothing to verify (no block emitted).
  */
 export declare function buildDirectiveComplianceBlock(directives: DirectiveToVerify[]): string | null;