opencode-swarm 7.140.2 → 7.140.4

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/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/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;

package/dist/cli/{config-doctor-shc0n4q1.js → config-doctor-qqe6172n.js}

@@ -12,11 +12,11 @@ import {
   shouldRunOnStartup,
   writeBackupArtifact,
   writeDoctorArtifact
-} from "./index-chx92bes.js";
+} from "./index-arza4m4j.js";
 import"./index-ee3x66a5.js";
 import"./index-zgwm4ryv.js";
-import"./index-bmmzfrc7.js";
-import"./index-n408rw7n.js";
+import"./index-tj04dj06.js";
+import"./index-hxvkfx6t.js";
 import"./index-zjygnfay.js";
 import"./index-bk5tah7q.js";
 import"./index-bpmtbmy9.js";

package/dist/cli/{core-p5cyej3r.js → core-52k057mf.js}

@@ -14,12 +14,12 @@ import {
   resolveWorktreeBaseDir,
   shortenWorktreePath,
   writeLaneProfileToDiskReal
-} from "./index-898f16j9.js";
+} from "./index-v3x7j9ey.js";
 import"./index-ee3x66a5.js";
 import"./index-4nt52yr9.js";
 import"./index-4rhhvd1a.js";
 import"./index-zgwm4ryv.js";
-import"./index-n408rw7n.js";
+import"./index-hxvkfx6t.js";
 import"./index-zjygnfay.js";
 import"./index-a76rekgs.js";
 export {

package/dist/cli/{curation-policy-7n6t8he4.js → curation-policy-9291bdat.js}

@@ -4,18 +4,16 @@ import {
   authorizeCuration,
   buildConfigFingerprintInput,
   readCohortConfigFingerprint
-} from "./index-t59cdg48.js";
+} from "./index-dtam929z.js";
 import"./index-rtry5xyf.js";
-import"./index-jfp1bgt1.js";
-import"./index-ae75rja9.js";
-import"./index-rs1f1bh0.js";
-import"./index-h2waehqq.js";
+import"./index-mrpfd1jx.js";
+import"./index-4hp8nvwb.js";
 import"./index-ed5ykebp.js";
-import"./index-hfvxhk4z.js";
+import"./index-35qep0v7.js";
 import"./index-7g4c7s5r.js";
 import"./index-4nt52yr9.js";
 import"./index-zgwm4ryv.js";
-import"./index-ry0hgg3m.js";
+import"./index-bfhwtdsw.js";
 import"./index-bpmtbmy9.js";
 import"./index-a76rekgs.js";
 export {

package/dist/cli/{curator-zp5qq24c.js → curator-04xqq68e.js}

@@ -14,59 +14,59 @@ import {
   runCuratorInit,
   runCuratorPhase,
   writeCuratorSummary
-} from "./index-n831qq2v.js";
+} from "./index-a1fjhx4w.js";
 import"./index-41hkt36g.js";
-import"./index-1m1ksyqt.js";
-import"./index-x6mtyj6q.js";
-import"./index-chx92bes.js";
-import"./index-brh827g0.js";
-import"./index-yyyk63kk.js";
+import"./index-c5kr20nz.js";
+import"./index-ysa38bnr.js";
+import"./index-arza4m4j.js";
+import"./index-hz0refz4.js";
+import"./index-w4etfamq.js";
 import"./index-y8552snf.js";
 import"./index-4905hd2m.js";
 import"./index-134d35c1.js";
-import"./index-9txca231.js";
-import"./index-z6md3t8m.js";
-import"./index-yt3vz0e1.js";
+import"./index-hfjvepk2.js";
+import"./index-v1an91bq.js";
+import"./index-mpytsq6k.js";
 import"./index-v2xrer41.js";
 import"./index-c8s9a3zh.js";
 import"./index-9ss2m4rs.js";
-import"./index-jfjnn408.js";
-import"./index-adyxbmt5.js";
+import"./index-bn17ycxn.js";
+import"./index-ryq97w1x.js";
 import"./index-556ja8an.js";
-import"./index-kbfsp07d.js";
+import"./index-wk8s1m7b.js";
 import"./index-1kyex7z2.js";
 import"./index-b8zgtz81.js";
-import"./index-898f16j9.js";
-import"./index-b9rd29ge.js";
-import"./index-k46me75h.js";
-import"./index-ee3x66a5.js";
+import"./index-v3x7j9ey.js";
+import"./index-rrb6cz2f.js";
 import"./index-74hpm6sh.js";
-import"./index-n0pja0qs.js";
+import"./index-dtyeabmj.js";
 import"./index-8fwhhayc.js";
 import"./index-q1exe2b3.js";
-import"./index-1j5my2qy.js";
-import"./index-t59cdg48.js";
+import"./index-2rb3x0fk.js";
+import"./index-k46me75h.js";
+import"./index-ee3x66a5.js";
+import"./index-7begd9aq.js";
+import"./index-dtam929z.js";
 import"./index-rtry5xyf.js";
-import"./index-325zmfyj.js";
-import"./index-jfp1bgt1.js";
+import"./index-vrmkg8fm.js";
 import"./index-ae75rja9.js";
-import"./index-rs1f1bh0.js";
-import"./index-h2waehqq.js";
+import"./index-mrpfd1jx.js";
+import"./index-4hp8nvwb.js";
 import"./index-ed5ykebp.js";
-import"./index-hfvxhk4z.js";
+import"./index-35qep0v7.js";
 import"./index-7g4c7s5r.js";
 import"./index-4nt52yr9.js";
-import"./index-0tevsq1a.js";
+import"./index-pp5m7xga.js";
 import"./index-gprxjmm7.js";
 import"./index-n832052r.js";
 import"./index-d181x9zr.js";
 import"./index-4rhhvd1a.js";
 import"./index-zgwm4ryv.js";
-import"./index-bmmzfrc7.js";
-import"./index-n408rw7n.js";
+import"./index-tj04dj06.js";
+import"./index-hxvkfx6t.js";
 import"./index-zjygnfay.js";
 import"./index-bk5tah7q.js";
-import"./index-ry0hgg3m.js";
+import"./index-bfhwtdsw.js";
 import"./index-bpmtbmy9.js";
 import"./index-a76rekgs.js";
 export {