opencode-swarm 7.124.0 → 7.125.1

package/.opencode/skills/swarm-pr-review/references/parser-dry-run.md

@@ -0,0 +1,235 @@
+# Dry-Run: Parser-Based Candidate Extraction
+
+This section demonstrates the new parser-based extraction path end-to-end
+using synthetic data. It is concrete enough to implement the same pattern in
+another skill.
+
+### Scenario
+
+A PR review has dispatched six base explorer lanes via `dispatch_lanes_async`.
+The batch completed and `collect_lane_results` returned:
+
+```json
+{
+  "batch_id": "batch-a1b2c3",
+  "lane_results": [
+    {
+      "lane_id": "pr_review_lane1_correctness",
+      "status": "completed",
+      "output_ref": "L1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+      "output_degraded": false
+    },
+    {
+      "lane_id": "pr_review_lane2_security",
+      "status": "completed",
+      "output_ref": "L1:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+      "output_degraded": false
+    }
+  ]
+}
+```
+
+### Step 1 — Call the parser
+
+The orchestrator calls `parse_lane_candidates` for each `output_ref`:
+
+```json
+{
+  "tool": "parse_lane_candidates",
+  "arguments": {
+    "output_ref": "L1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "producer": "swarm-pr-review",
+    "expected_family": "base_explorer"
+  }
+}
+```
+
+### Step 2 — Structured response
+
+The parser returns a `ParseResultWithSidecar`. On success, `error` and `error_code` are absent:
+
+```json
+{
+  "candidates": [
+    {
+      "record_type": "candidate",
+      "row_format_family": "base_explorer",
+      "row_format_version": 1,
+      "record_version": { "major": 1, "minor": 1 },
+      "source_output_ref": "L1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+      "source_batch_id": "B-2025-06-22-001",
+      "source_lane_id": "explorer-1",
+      "source_agent": "paid_explorer",
+      "source_digest": "sha256:abc123def456...",
+      "extracted_from_partial_source": false,
+      "sessionId": "ses_01HXYZ...",
+      "parentSessionId": "ses_01HABC...",
+      "producer": "swarm-pr-review",
+      "candidate_id": "C-001",
+      "lane": "Lane 1: Correctness and edge cases",
+      "micro_lane": null,
+      "severity": "HIGH",
+      "category": "null-safety",
+      "file_line": "src/utils/cache.ts:142",
+      "claim": "Uncached getter may return undefined on cold start",
+      "evidence_summary": "The `getCached` function returns `cache[key]` without a fallback when the cache is empty.",
+      "impact_context": "Downstream callers in `src/handlers/*.ts` expect a defined value and call `.toString()` directly.",
+      "invariant_violated": null,
+      "confidence": "HIGH"
+    },
+    {
+      "record_type": "candidate",
+      "row_format_family": "base_explorer",
+      "row_format_version": 1,
+      "record_version": { "major": 1, "minor": 1 },
+      "source_output_ref": "L1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+      "source_batch_id": "B-2025-06-22-001",
+      "source_lane_id": "explorer-1",
+      "source_agent": "paid_explorer",
+      "source_digest": "sha256:abc123def456...",
+      "extracted_from_partial_source": false,
+      "sessionId": "ses_01HXYZ...",
+      "parentSessionId": "ses_01HABC...",
+      "producer": "swarm-pr-review",
+      "candidate_id": "C-002",
+      "lane": "Lane 1: Correctness and edge cases",
+      "micro_lane": null,
+      "severity": "MEDIUM",
+      "category": "async-ordering",
+      "file_line": "src/services/queue.ts:88",
+      "claim": "Race between `drain` and `processNext` may drop items",
+      "evidence_summary": "`drain` sets `active = false` before awaiting `processNext`, which also checks `active`.",
+      "impact_context": "Items submitted during the drain window are silently dropped.",
+      "invariant_violated": null,
+      "confidence": "MEDIUM"
+    }
+  ],
+  "invocation_envelope": {
+    "record_type": "invocation",
+    "source_output_ref": "L1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "source_batch_id": "B-2025-06-22-001",
+    "source_lane_id": "explorer-1",
+    "source_agent": "paid_explorer",
+    "source_digest": "sha256:abc123def456...",
+    "row_format_version": 1,
+    "record_version": { "major": 1, "minor": 1 },
+    "sessionId": "ses_01HXYZ...",
+    "parentSessionId": "ses_01HABC...",
+    "producer": "swarm-pr-review",
+    "produced_at": "2025-06-22T14:30:00.000Z",
+     "format_families_detected": ["base_explorer"],
+     "candidate_count": 2,
+     "parse_errors": 0,
+     "malformed_rows": 0,
+     "clean_attestation_count": 0
+  },
+  "diagnostics": {
+    "candidate_count": 2,
+    "parse_errors": 0,
+    "parse_error_details": [],
+    "malformed_rows": 0,
+    "duplicate_id_count": 0,
+    "duplicate_id_warnings": [],
+    "degraded_source_count": 0,
+    "incomplete_source_count": 0,
+     "format_families_detected": ["base_explorer"],
+     "clean_attestation_count": 0
+   }
+}
+```
+> **Note**: callers pass `expected_family` for each dispatch batch. A recognizable
+> conflicting header fails closed with `expected-family-mismatch`; when the flag
+> is absent, the recognized header controls the mapping and positional detection
+> is only a legacy unknown-header fallback. Marker-prefixed data rows remain
+> accepted for compatibility. Valid canonical rows produce `parse_errors: 0`.
+
+On refusal (e.g. `output_ref` does not exist), `error` and `error_code` are present; `candidates` is `[]`; `invocation_envelope` and `diagnostics` are populated with empty fields for traceability:
+
+```json
+{
+  "error": "Artifact reference not found in store",
+  "error_code": "ref-not-found",
+  "candidates": [],
+  "invocation_envelope": {
+    "record_type": "invocation",
+    "source_output_ref": "L1:1111111111111111111111111111111111111111111111111111111111111111:2222222222222222222222222222222222222222222222222222222222222222:3333333333333333333333333333333333333333333333333333333333333333",
+    "source_batch_id": "",
+    "source_lane_id": "",
+    "source_agent": "",
+    "source_digest": "",
+    "row_format_version": 1,
+    "record_version": { "major": 1, "minor": 1 },
+    "produced_at": "2025-06-22T14:30:00.000Z",
+    "format_families_detected": [],
+    "candidate_count": 0,
+    "parse_errors": 0,
+    "malformed_rows": 0,
+    "clean_attestation_count": 0
+  },
+  "diagnostics": {
+    "candidate_count": 0,
+    "parse_errors": 0,
+    "parse_error_details": [],
+    "malformed_rows": 0,
+    "duplicate_id_count": 0,
+    "duplicate_id_warnings": [],
+    "degraded_source_count": 0,
+    "incomplete_source_count": 0,
+    "format_families_detected": [],
+    "clean_attestation_count": 0
+   }
+}
+```
+
+### Step 3 — Filter and group
+
+The orchestrator filters the returned `candidates[]` array by `producer: "swarm-pr-review"` and the exact allowed `source_batch_id` / `source_lane_id` tuples, then groups
+the candidates. In this synthetic example, the two candidates above are grouped
+by file area:
+
+- **Chunk A — `src/utils/`** (1 candidate): C-001
+- **Chunk B — `src/services/`** (1 candidate): C-002
+
+If there were more candidates, the orchestrator would also group by category
+(e.g., `null-safety`, `async-ordering`) and cap each chunk at 50 candidates.
+
+### Step 4 — Dispatch reviewer lanes
+
+The orchestrator dispatches one reviewer lane per chunk:
+
+```text
+You are the independent reviewer. Validate only the candidates assigned below.
+Do not search for new issues except where needed to validate reachability or
+mitigation. Do not trust explorer severity.
+
+Context pack summary:
+- scope: ...
+- obligations: ...
+- impact cone: ...
+- deterministic signals: ...
+- relevant Swarm artifacts / knowledge: ...
+- base_ref: <commit SHA of base branch>
+- head_ref: <commit SHA of PR head branch>
+
+Candidates (Chunk A — src/utils/):
+- C-001 | HIGH | null-safety | src/utils/cache.ts:142 | Uncached getter may return undefined on cold start
+
+For each candidate, return:
+[REVIEWED] | candidate_id | CONFIRMED/DISPROVED/UNVERIFIED/PRE_EXISTING | evidence_type | final_severity | introduced_by_pr | file:line | rationale | falsification_probe | reviewer_id
+
+You must check caller context, reachability, schema/middleware/framework mitigations, state-machine constraints, test coverage, PR-introducedness, and severity.
+
+IMPORTANT: If a finding claims behavior is "new" or "introduced by the PR", you MUST read the equivalent code on the base branch (git show <base_ref>:<file>) to verify it was not present before. A reviewer claim of "this is new" is invalid without base-branch evidence. Do not compare the new code to an idealized baseline — compare it to what actually existed on the base branch at the time of the PR.
+```
+
+### Key invariants
+
+- The parser reads the **full artifact**, not a preview. Truncation in the
+  `dispatch_lanes` preview does not affect candidate extraction.
+- The orchestrator never classifies candidates — it only filters, groups, and
+  routes them.
+- Each reviewer receives a bounded chunk. A chunk with more than 50 candidates
+  is split before dispatch.
+- The `invocation_envelope` in the parser response provides audit provenance
+  for every extracted candidate.
+

package/.opencode/skills/swarm-pr-review/references/prompt-templates.md

@@ -0,0 +1,103 @@
+# Reviewer Prompt Template
+
+Use this template when dispatching reviewer subagents:
+
+```text
+You are the independent reviewer. Validate only the candidates assigned below.
+Do not search for new issues except where needed to validate reachability or mitigation.
+Do not trust explorer severity.
+
+Context pack summary:
+- scope: ...
+- obligations: ...
+- impact cone: ...
+- deterministic signals: ...
+- relevant Swarm artifacts / knowledge: ...
+- base_ref: <commit SHA of base branch>
+- head_ref: <commit SHA of PR head branch>
+
+Candidates:
+- ...
+
+For each candidate, return:
+[REVIEWED] | candidate_id | CONFIRMED/DISPROVED/UNVERIFIED/PRE_EXISTING | evidence_type | final_severity | introduced_by_pr | file:line | rationale | falsification_probe | reviewer_id
+
+You must check caller context, reachability, schema/middleware/framework mitigations, state-machine constraints, test coverage, PR-introducedness, and severity.
+
+IMPORTANT: If a finding claims behavior is "new" or "introduced by the PR", you MUST read the equivalent code on the base branch (git show <base_ref>:<file>) to verify it was not present before. A reviewer claim of "this is new" is invalid without base-branch evidence. Do not compare the new code to an idealized baseline — compare it to what actually existed on the base branch at the time of the PR.
+```
+
+---
+
+# Critic Prompt Template
+
+Use this template when dispatching critic subagents:
+
+```text
+You are the adversarial critic. Challenge only reviewer-confirmed findings assigned below.
+Your goal is to reduce false positives, severity inflation, and non-actionable reports.
+
+For each finding, challenge:
+- whether evidence proves the claim,
+- whether the path is reachable,
+- whether mitigations apply,
+- whether severity is inflated,
+- whether it is PR-introduced,
+- whether suggested fixes are safe/actionable,
+- whether related files were missed,
+- whether multiple findings should be grouped.
+
+Return:
+[CRITIC] | finding_id | UPHELD/DOWNGRADED/DISPROVED/NEEDS_MORE_EVIDENCE | final_severity | reason | required_report_change
+
+REQUIRED FINAL LINE — your final line MUST be exactly the row above (no variations, no labeled fields, no placeholders):
+[CRITIC] | finding_id | UPHELD/DOWNGRADED/DISPROVED/NEEDS_MORE_EVIDENCE | final_severity | reason | required_report_change
+
+A response without this exact row is treated as a planning preamble and re-dispatched. Do not output only a planning or investigation message.
+```
+
+---
+
+# Explorer Prompt Template
+
+Use this template when dispatching base explorer or micro-lane agents:
+
+```text
+You are an explorer. Optimize for recall, not final judgment.
+Return candidates only. Do not use CONFIRMED, DISPROVED, or PRE_EXISTING.
+
+Lane:
+Scope:
+base_ref:
+head_ref:
+Obligations:
+Changed files/hunks:
+Impact cone:
+Relevant deterministic signals:
+Relevant Swarm artifacts / knowledge:
+Checklist:
+
+You must inspect or mark unavailable:
+1. changed hunk,
+2. caller/consumer,
+3. callee/dependency,
+4. sibling implementation or prior pattern,
+5. nearest test or missing-test location,
+6. deterministic signals,
+7. Swarm artifacts/knowledge,
+8. the exact `base_sha...pr_head_sha` merge-base range and both endpoint revisions.
+
+Return:
+[CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence
+Emit the marker-bearing header once, then unprefixed data rows.
+For a clean micro-lane, emit `[CLEAN] | micro_lane | coverage_scope | evidence`.
+For a clean base lane, emit `[CLEAN] | workflow_lane | coverage_scope | evidence`.
+```
+
+The orchestrator extracts candidates from the full lane artifact via
+`parse_lane_candidates` as the primary mechanism. The `[CANDIDATE]` row
+format above is a fallback convention for environments where the parser is
+unavailable. Explorers should still emit structured records regardless of
+whether the parser is present.
+
+Do not let speed degrade validation quality.

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

@@ -619,44 +619,6 @@ authority checks:
 
 For the full splitting protocol (describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, cascading-split detection), read `file:.swarm/bundled-skills/test-file-split/SKILL.md`.
 
-### Checking file length
-
-```bash
-# Check a single file
-wc -l tests/unit/scripts/my-test.test.ts
-
-# Find all test files exceeding 400 lines (early warning threshold)
-find tests/ -name "*.test.ts" -exec wc -l {} \; | sort -rn | awk '$1 > 400'
-```
-
-### Splitting pattern
-
-When a test file approaches or exceeds 500 lines, split it by extracting cohesive `describe()` blocks into a new file with a descriptive suffix:
-
-1. **Identify natural boundaries.** Group `describe()` blocks by functional area (e.g., SHA resolution, validation, merge logic).
-2. **Create the new file** with a descriptive suffix: `<module>-<area>.test.ts` (e.g., `release-notes-fragments-sha.test.ts`, `release-notes-fragments-validation.test.ts`).
-3. **Move shared imports and helpers.** Either:
-   - Duplicate shared imports in both files (simple, for small overlap), OR
-   - Extract shared test helpers to a utility module (e.g., `tests/helpers/<module>-shared.ts`) and import from both files (preferred for complex shared setup).
-4. **Extract testable pure functions.** If the source module has inline validation logic (e.g., `isValidPrNumber`), extract it as an exported pure function so both test files can target it independently.
-5. **Verify both files are under 500 lines.**
-6. **Run both files independently AND co-run** to verify no mock isolation breakage:
-   ```bash
-   bun --smol test tests/unit/scripts/release-notes-fragments.test.ts --timeout 60000
-   bun --smol test tests/unit/scripts/release-notes-fragments-sha.test.ts --timeout 60000
-   bun --smol test tests/unit/scripts/release-notes-fragments*.test.ts --timeout 60000
-   ```
-
-### When to split vs refactor
-
-- **Split** when there are natural `describe()` boundaries (e.g., one file per functional area).
-- **Refactor** when the file is a single monolithic test with no clear boundaries — consolidate test logic instead.
-- **Warning:** If a previously split file exceeds 500 lines again, the test suite is structurally too large. Reorganize by module rather than continuing to split.
-
-### Reference
-
-See PR #1762 for a real-world example: `release-notes-fragments.test.ts` was split into `release-notes-fragments.test.ts` (379 lines) + `release-notes-fragments-sha.test.ts` (261 lines).
-
 ## Cross-Entry Invariants (config maps)
 
 When you modify any entry of a "map of agents/tools/roles" in `src/config/constants.ts` (`AGENT_TOOL_MAP`, `DEFAULT_MODELS`, `QA_AGENTS`, `PIPELINE_AGENTS`, etc.) or tool-name registration in `src/tools/tool-names.ts`, there are tests that assert **parity across sibling entries**, not just shape of one entry.
@@ -847,50 +809,7 @@ try {
 
 ## Running Tests
 
-### bash (Linux / macOS)
-
-```bash
-# Single file
-bun test src/hooks/scope-guard.test.ts
-
-# Batch directory (safe for dirs without mock conflicts)
-bun --smol test tests/unit/hooks --timeout 30000
-
-# Per-file loop (required for tools/services/agents — prevents mock poisoning)
-for f in tests/unit/tools/*.test.ts; do bun --smol test "$f" --timeout 30000; done
-
-# CI-equivalent run for batch steps (step 2: cli; step 3: commands + config)
-bun --smol test tests/unit/cli --timeout 120000
-bun --smol test tests/unit/commands tests/unit/config --timeout 120000
-```
-
-### PowerShell (Windows)
-
-```powershell
-# Single file
-bun test src/hooks/scope-guard.test.ts
-
-# Batch directory (safe for dirs without mock conflicts)
-bun --smol test tests/unit/hooks --timeout 30000
-
-# Per-file loop (required for tools/services/agents — prevents mock poisoning)
-Get-ChildItem tests/unit/tools/*.test.ts | ForEach-Object { bun --smol test $_.FullName --timeout 30000 }
-
-# CI-equivalent run for batch steps (step 2: cli; step 3: commands + config)
-bun --smol test tests/unit/cli --timeout 120000
-bun --smol test tests/unit/commands tests/unit/config --timeout 120000
-
-# Capture output to file (avoids truncation when output is large)
-bun --smol test tests/unit/agents --timeout 60000 | Out-File "$env:TEMP\test_out.txt"; Get-Content "$env:TEMP\test_out.txt" | Select-Object -Last 50
-```
-
-**Note:** `for f in ...; do` bash syntax is invalid in PowerShell. Use `Get-ChildItem | ForEach-Object` instead. `Select-String -Last N` is also invalid — use `Select-Object -Last N`.
-
-**Warning:** Running `bun --smol test tests/unit/tools` as a single batch will cause mock poisoning failures. Always use the per-file loop for the per-file-isolation steps (1a, 1b, 4-6: tools, services, agents, etc.).
-
-The `--smol` flag reduces Bun's memory footprint. Use it when running large directories (50+ files).
-
-The `--timeout 120000` flag sets per-test timeout to 120 seconds. Individual tests should complete in under 5 seconds. If a test needs more than 10 seconds, it's doing too much — split it or mock the slow dependency.
+For the full test execution commands (bash and PowerShell per-file isolation loops, CI integration), read `file:.swarm/bundled-skills/running-tests/SKILL.md`. The key principle: always run one test file per process (`bun --smol test <file> --timeout 30000`) to prevent `mock.module` cross-contamination.
 
 ## Before Submitting
 
@@ -905,44 +824,6 @@ The `--timeout 120000` flag sets per-test timeout to 120 seconds. Individual tes
 
 Pre-existing and flaky failures are tracked in the per-platform quarantine ledgers (`scripts/ci/quarantined-tests.txt`, `quarantined-tests-macos.txt`, `quarantined-tests-windows.txt`), not in this skill. To confirm a failure is pre-existing, reproduce it in a clean worktree on `origin/main` (see the worktree verify protocol in `running-tests`).
 
-## Known Cross-module mock.module Locations
-
-The following directories contain test files that use cross-module `mock.module` (permitted under two-tier convention):
-
-- `tests/unit/commands/` — mocks tools, hooks, services, state
-- `tests/unit/hooks/` — mocks knowledge-store, knowledge-validator, knowledge-reader, telemetry, utils
-- `tests/unit/tools/` — mocks Node built-ins (fs, child_process), sast-baseline, build/discovery
-- `tests/unit/services/` — mocks path-security
-- `tests/unit/config/` — mocks node:fs/promises
-- `tests/unit/background/` — mocks utils, event-bus, evidence-summary-service
-- `tests/unit/council/` — mocks node:fs
-- `tests/unit/plan/` — mocks spec-hash
-- `tests/unit/mutation/` — mocks node:child_process
-- `tests/unit/git/` — mocks node:child_process
-- `tests/integration/` — mocks co-change-analyzer, knowledge-store
-- `src/__tests__/` — mocks plan/manager, preflight-service, telemetry
-- `src/hooks/` — mocks logger, event-bus
-- `src/tools/__tests__/` — mocks test-impact/analyzer, build/discovery, path-security
-- `src/mutation/__tests__/` — mocks state
-- `src/agents/` — mocks node:fs/promises
-- `src/background/` — mocks vulnerability trigger
-
-## Dead-code _internals Seams
-
-The following source modules export `_internals` but have no test consumers (as of this writing). They are harmless but may be removed in future cleanup:
-
-- `src/tools/secretscan.ts`
-- `src/tools/knowledge-recall.ts`
-- `src/tools/lint.ts`
-- `src/tools/sast-scan.ts`
-- `src/tools/sast-baseline.ts`
-- `src/mutation/gate.ts`
-- `src/mutation/equivalence.ts`
-- `src/mutation/engine.ts`
-- `src/db/qa-gate-profile.ts`
-- `src/config/schema.ts`
-- `src/config/index.ts`
-- `src/commands/registry.ts`
-- `src/background/manager.ts`
-- `src/background/event-bus.ts`
-- `src/agents/critic.ts`
+## Mock and Seam Inventories
+
+For the current cross-module `mock.module` location inventory and dead-code `_internals` seam inventory, read `references/mock-and-seam-inventory.md`.

package/.opencode/skills/writing-tests/references/mock-and-seam-inventory.md

@@ -0,0 +1,43 @@
+# Mock and Seam Inventory
+
+## Known Cross-module mock.module Locations
+
+The following directories contain test files that use cross-module `mock.module` (permitted under two-tier convention):
+
+- `tests/unit/commands/` — mocks tools, hooks, services, state
+- `tests/unit/hooks/` — mocks knowledge-store, knowledge-validator, knowledge-reader, telemetry, utils
+- `tests/unit/tools/` — mocks Node built-ins (fs, child_process), sast-baseline, build/discovery
+- `tests/unit/services/` — mocks path-security
+- `tests/unit/config/` — mocks node:fs/promises
+- `tests/unit/background/` — mocks utils, event-bus, evidence-summary-service
+- `tests/unit/council/` — mocks node:fs
+- `tests/unit/plan/` — mocks spec-hash
+- `tests/unit/mutation/` — mocks node:child_process
+- `tests/unit/git/` — mocks node:child_process
+- `tests/integration/` — mocks co-change-analyzer, knowledge-store
+- `src/__tests__/` — mocks plan/manager, preflight-service, telemetry
+- `src/hooks/` — mocks logger, event-bus
+- `src/tools/__tests__/` — mocks test-impact/analyzer, build/discovery, path-security
+- `src/mutation/__tests__/` — mocks state
+- `src/agents/` — mocks node:fs/promises
+- `src/background/` — mocks vulnerability trigger
+
+## Dead-code _internals Seams
+
+The following source modules export `_internals` but have no test consumers (as of this writing). They are harmless but may be removed in future cleanup:
+
+- `src/tools/secretscan.ts`
+- `src/tools/knowledge-recall.ts`
+- `src/tools/lint.ts`
+- `src/tools/sast-scan.ts`
+- `src/tools/sast-baseline.ts`
+- `src/mutation/gate.ts`
+- `src/mutation/equivalence.ts`
+- `src/mutation/engine.ts`
+- `src/db/qa-gate-profile.ts`
+- `src/config/schema.ts`
+- `src/config/index.ts`
+- `src/commands/registry.ts`
+- `src/background/manager.ts`
+- `src/background/event-bus.ts`
+- `src/agents/critic.ts`

package/README.md

@@ -810,7 +810,9 @@ Every candidate passes a 3-gate pipeline before entering quarantine:
 | generate_mutants | Architect-only: generates LLM-based mutation patches (5–10 per function across 6 types: off-by-one, null substitution, operator swap, guard removal, branch swap, side-effect deletion) for direct consumption by the mutation_test tool; returns SKIP verdict on LLM failure rather than throwing |
 | write_mutation_evidence | Architect-only: writes mutation gate results atomically to `.swarm/evidence/{phase}/mutation-gate.json`; accepts verdict (PASS/WARN/FAIL/SKIP), kill rate metrics, and optional survived mutant details; normalizes uppercase-to-lowercase before persisting |
 | parse_lane_candidates | Architect-only: parses `[CANDIDATE]` rows and micro-lane `[CLEAN]` attestations from a lane `output_ref`; supports asserted batch families, preserves dispatch provenance, and persists sidecar JSONL records |
-| write_pr_review_trigger_eval | Architect-only: validates the exact PR-review trigger-map ID set, requires provenance for every matched micro-lane, and atomically persists `.swarm/pr-review/<run_id>/trigger-eval.json` |
+| write_pr_review_trigger_eval | Architect-only: validates the exact mandatory PR-review micro-lane ID set, requires completed provenance for all 11 repository-agnostic lanes, verifies the claimed merge base against an exact live base ref, rejects every `NO-MATCH` waiver, and atomically persists `.swarm/pr-review/<run_id>/trigger-eval.json` |
+| complete_pr_workflow | Architect-only: validates terminal PR-review or PR-feedback coverage; feedback uses a two-call arm/publish protocol and clears only after the approved content is observed on both the bound remote-tracking ref and the actual remote branch |
+| run_pr_feedback_stage_a | Architect-only: executes targeted reproduction/regression and exact `git diff --check` plus every mechanically applicable workspace/category/source build, typecheck, and lint obligation, then persists content-bound Stage A receipts before ordered feedback review gates |
 | git_blame | Per-line git blame metadata (sha, author, date, summary) via `git blame --porcelain`; supports optional line range filtering |
 | diff | Structured git diff with contract change detection; supports `summaryOnly` mode returning file list with additions/deletions counts |
 | suggest_patch | Reviewer-safe structured patch suggestion; supports `format` parameter ('json' or 'unified') where unified outputs valid unified diff with `diff --git` headers, hunks, and context |

package/dist/background/lane-output-store.d.ts

@@ -11,6 +11,11 @@ declare const LaneOutputArtifactSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodString>;
     parentSessionId: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodString>;
+    workflowLane: z.ZodOptional<z.ZodString>;
+    prHeadSha: z.ZodOptional<z.ZodString>;
+    gitHead: z.ZodOptional<z.ZodString>;
+    revisionDigest: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
     source: z.ZodEnum<{
         dispatch_lanes: "dispatch_lanes";
         collect_lane_results: "collect_lane_results";
@@ -34,6 +39,11 @@ export interface StoreLaneOutputInput {
     sessionId?: string;
     parentSessionId?: string;
     mode?: string;
+    workflowLane?: string;
+    prHeadSha?: string;
+    gitHead?: string;
+    revisionDigest?: string;
+    scope?: string;
     source: LaneOutputSource;
     text: string;
     messageCount?: number;

package/dist/background/pending-delegations.d.ts

@@ -52,6 +52,8 @@ export interface BackgroundDelegationRecord {
     laneId?: string;
     /** Advisory workflow/mode that launched the lane. */
     mode?: string;
+    /** Mechanical PR workflow obligation identifier, distinct from retry-safe laneId. */
+    workflowLane?: string;
     /** Canonical hash of prompt/provenance inputs captured at dispatch time. */
     promptHash?: string;
     /** Project/root provenance captured at dispatch time. */
@@ -119,6 +121,7 @@ export interface RecordPendingInput {
     batchId?: string;
     laneId?: string;
     mode?: string;
+    workflowLane?: string;
     promptHash?: string;
     workspace?: BackgroundWorkspaceSnapshot;
     taskChangeContext?: BackgroundTaskChangeContext;

package/dist/background/workspace-snapshot.d.ts

@@ -11,8 +11,65 @@ interface CaptureWorkspaceSnapshotOptions {
      */
     resolveCurrentPrHeadSha?: boolean;
 }
+/**
+ * Read one bounded repository file from an immutable commit without consulting
+ * the mutable checkout. Callers compare this text with the checkout copy before
+ * treating a PR-provided contract as authority.
+ */
+export declare function readGitTextAtRevision(directory: string, revision: string, relativePath: string): string | null;
+/** Resolve the exact checked-out commit through the bounded Git snapshot path. */
+export declare function resolveCurrentGitHead(directory: string): string | null;
+/** Resolve one exact PR merge base without shell interpolation or unbounded I/O. */
+export declare function resolveExactMergeBase(directory: string, baseRef: string, prHeadSha: string): string | null;
+/** Resolve the current branch's exact remote-tracking publication target. */
+export declare function resolveCurrentUpstreamRemoteRef(directory: string): string | null;
+export interface PrUpstreamPushTarget {
+    remoteName: string;
+    remoteBranchRef: string;
+    remoteTrackingRef: string;
+}
+/** Resolve a branch's upstream without guessing where a remote name ends. */
+export declare function resolveCurrentUpstreamPushTarget(directory: string): PrUpstreamPushTarget | null;
+/** Query the actual remote ref; local tracking refs are not publication proof. */
+export declare function resolveExactRemoteBranchHead(directory: string, remoteName: string, remoteBranchRef: string): string | null;
+/** Bind Stage-A execution to Git refs, config, HEAD, and index metadata. */
+export declare function resolveGitControlStateDigest(directory: string): string | null;
+/** Require all independently reviewed content to be captured by the commit. */
+export declare function resolveIsWorkingTreeClean(directory: string): boolean | null;
+/** Count commits on the ancestry path from the immutable intake head to HEAD. */
+export declare function resolveCommitCountSince(directory: string, baseHeadSha: string, currentHeadSha: string): number | null;
+/** Prove the publication commit is a non-merge direct child of intake HEAD. */
+export declare function resolveIsExactSingleChildCommit(directory: string, baseHeadSha: string, currentHeadSha: string): boolean | null;
+/**
+ * Return remote-tracking refs whose tip equals the exact checked-out commit.
+ * Publication closeout uses this bounded local observation after a successful
+ * push; an empty list is not proof that the approved revision was published.
+ */
+export declare function resolveRemoteRefsContainingHead(directory: string, headSha: string): string[] | null;
+/**
+ * Bind a mutable working tree to its actual content, not merely porcelain status.
+ * This lets PR-feedback approvals fail closed when a same-path edit occurs after a
+ * gate. Paths come from Git, are containment-checked, and are hashed without
+ * following symlinks outside the project.
+ */
+export declare function resolvePrWorkflowRevisionDigest(directory: string, baseHeadSha: string): string | null;
+/**
+ * Asynchronously bind a mutable working tree to its actual content. File
+ * reads are chunked with bounded cooperative yields so a large, permitted
+ * revision cannot stall the synchronous plugin gate path.
+ */
+export declare function resolvePrWorkflowRevisionDigestAsync(directory: string, baseHeadSha: string): Promise<string | null>;
 /** Parse `git status --porcelain=v1 -z`, including both sides of renames. */
 export declare function parsePorcelainPaths(output: string): string[] | null;
+interface PorcelainV2Snapshot {
+    gitHead: string | null;
+    changedFiles: string[];
+}
+/**
+ * Parse the one-command `git status --porcelain=v2 --branch -z` snapshot used
+ * by background evidence capture. A malformed or unknown record fails closed.
+ */
+declare function parsePorcelainV2Snapshot(output: string): PorcelainV2Snapshot | null;
 export declare function captureWorkspaceSnapshot(directory: string, optionsOrScope?: string | null | CaptureWorkspaceSnapshotOptions, prHeadShaArg?: string | null): BackgroundWorkspaceSnapshot;
 /**
  * Conservatively derive final paths changed since a pre-task snapshot.
@@ -34,5 +91,7 @@ export declare function compareWorkspaceSnapshots(expected: BackgroundWorkspaceS
 export declare function digest(text: string): string;
 export declare const _internals: {
     spawnSync: SpawnSync;
+    yieldControl: () => Promise<void>;
+    parsePorcelainV2Snapshot: typeof parsePorcelainV2Snapshot;
 };
 export {};