okstra 0.143.0 → 0.144.0

package/docs/project-structure-overview.md

@@ -243,7 +243,8 @@ Important modules:
 | `incremental_carry.py` | carry merge for an incremental re-run — merges the previous run's plan-item verdicts that this run does not re-verify into the current data.json with a `carriedForwardFromSeq` tag. On `schemaVersion` drift it exits non-zero with `CarryError` to force a full fallback. CLI: `okstra incremental-carry` |
 | `build_tools.py` | allowlist SSOT for deciding whether a plan's command cell invokes the project build toolchain (`npm`/`pytest`/`cargo`/`gradle`/… behind transparent leaders like `sudo`/`env`). The planning worktree has no dependencies installed, so `validators/validate-run.py` uses this to warn (advisory) when a toolchain stage declares no install precondition. Intentionally an allowlist, not a denylist, so unknown tokens go undetected rather than firing on `grep`/`sed` in every plan |
 | `stage_citations.py` | shared grammar SSOT for reading the Stage Map stage numbers a prose cell cites (`Stages 1, 2, and 3`, ranges, etc.). One definition serves two readers that must not drift — the coverage check in `validators/validate-run.py` proving every stage traces to a requirement, and `incremental_scope.py`'s back-trace resolving which stages an answered clarification touches |
-| `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and `selfmock_path_key` (the one path-normalization the coverage check and the waiver matcher both share). The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). Both the static detector `validators/detect_self_mock.py` and the drift guard MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate |
+| `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
+| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
@@ -379,7 +380,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 | `validate-schedule.py` | Schedule section/order/code validation |
 | `validate-implementation-plan-stages.py` | enforces the Stage Map structure — checks the S1–S8 rules (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` sections, ≤ 8 steps per stage, etc.) |
 | `validate_improvement_report.py` | enforces the 11-item contract of the improvement-discovery final-report. Automatically invoked by `validate-run.py` when `task_type == "improvement-discovery"` |
-| `detect_self_mock.py` | static self-mock detector — scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
+| `detect_self_mock.py` | self-mock detector — runs BOTH gates and writes the run's sidecar. Gate A (static) scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Gate B (mutation) runs in the same call: `--changed-file` takes the stage's WHOLE changed set (each adapter selects its own production sources out of it), `--diff` and `--worktree` scope it, and `scripts/okstra_ctl/mutation_probe.py` writes the result into the sidecar's `mutation` block; the received set is recorded as `changedFiles` so the gate can prove gate B was not handed an empty input. `overall` and the exit code follow BOTH gates — a mutation FAIL with a clean static scan still exits 1. The same `--waivers` file feeds both (gate A reads its `signal` entries, gate B its `mutant` ones). Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.143.0",
+  "version": "0.144.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.143.0",
-  "builtAt": "2026-08-02T11:16:25.811Z",
+  "package": "0.144.0",
+  "builtAt": "2026-08-02T12:01:26.299Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/coding-preflight/overview.md

@@ -63,7 +63,7 @@ Per-file checks miss cross-cutting issues; each commit can be individually clean
 
 - [ ] **Domain-literal sweep:** `grep -rn` every domain enum value / predicate you added or touched in WHERE clauses, filters, or branches. The same literal at 2+ I/O sites is a *candidate* scattered decision — ask: would these sites change together when the business rule changes? Same decision → consolidate into one named constant or query builder in the domain layer and make every site reference it. Different decisions that merely share a value → leave them separate; coupling incidental duplication is worse than the repetition. (The identifier grep above does NOT catch this — sweep *values*, not just names.)
 - [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
-- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it.
+- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static); absent `qa/self-mock-*.json` sidecar BLOCKS at `validate-run.py`.
 - [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
 
 ## Boundaries

package/runtime/prompts/profiles/_coding-conventions-preflight.md

@@ -18,5 +18,5 @@ Load the applicable coding conventions for every language the diff will touch, t
 - **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework from its extension or project manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`), then read that pack's resources via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
 - **Declared architecture style — an authoritative Stage 3 input, and it binds.** Before selecting resources, read `<PROJECT_ROOT>/.okstra/project.json` and take `architecture.style`. A declared `hexagonal` selects `architectures/hexagonal.md` even when none of Stage 3's layout signals matched, so the declaration — not the directory shape — decides. A declared `layered` has no pack resource; its invariant applies from this line: dependencies run one direction only — an upper layer may import a lower one, never the reverse — and a variation point is extracted onto a layer boundary. A declared style makes this overlay binding rather than advisory, and which rule binds follows the style: under `hexagonal` the overlay's otherwise-advisory concrete-adapter item is blocking, so a service dependency you add or modify goes through a port instead of a concrete implementation and that placement violation is fixed before the write rather than recorded as a note; under `layered` what binds is the direction invariant just stated — your own judgement over the import list of every file the diff touches, plus extracting a variation point onto a layer boundary — while the concrete-adapter item stays advisory, since `layered` has no ports to route it through. An absent field, a `none` style, or an unreadable `project.json` changes nothing — Stage 3 stays detection-driven and its overlay stays advisory, leaving the language-agnostic principles below as the only always-binding layer. The verifier re-grades the same diff under the same declaration (`_implementation-verifier.md` → Static design & test-quality review), so a placement violation missed here returns as a verdict `FAIL`.
 - **Project review rule packs:** also look for project-local review skills in `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`. Read the relevant `SKILL.md` plus referenced `references/*.md` files and apply their rules during implementation. This is a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
-- **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability.
+- **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static); absent `qa/self-mock-*.json` sidecar BLOCKS at `validate-run.py`.
 - **Graceful degradation (codex / antigravity executor runtimes, or any runtime where the resolved coding-preflight pack files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a resource read that did not happen.

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -40,7 +40,7 @@ Verifier obtains the QA command set from exactly two declared sources, in order
 
 ### Execution rule
 
-Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Then the Tier 3 stage conformance script (below) runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Verifier-specific forbidden actions below).
+Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Then the Tier 3 stage conformance script (below) runs once. Then the self-mock detector (below) runs once whenever the diff changed a test file. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Verifier-specific forbidden actions below).
 
 ### Tier 3 — stage conformance scripts
 
@@ -84,6 +84,52 @@ also remain contract violations.
 - **Read-only command log.** Record the `runCommand` exact line + its exit code in the Read-only command log. Tier 3 external non-PASS evidence MUST remain visible with status `ADVISORY`. Unlike Tiers 1·2, a conformance script MAY mutate the **replica datastore** (exercising integrated state is its whole purpose) — but only the `qaEnv` replica target, never a shared/staging/prod store. The `runCommand` itself is still subject to the same source/lockfile mutation deny-list as Tier 2 (`--fix`, `npm install` without `ci`, etc.); a denied token aborts with `contract-violated`.
 - **No manifest / no entry for this stage.** If the manifest file is absent, or it has no entry whose `stageKey` matches this run's stageKey, the verifier records `conformance: no manifest entry for <stageKey>` and proceeds (forcing the *declaration* of conformance entries is the job of planning Step 11 + the `validate-run.py` diff-surface cross-check, not the verifier).
 
+### Self-mock detection (changed test files)
+
+A green suite does not prove a test exercises the unit it names — a test that stubs its own SUT passes forever, including after the real implementation is deleted. The static detector is the machine half of the **Self-mocking** blocking check below, and running it is the verifier's own duty: it is never delegated to the executor and never inferred from the executor's evidence.
+
+- **Trigger.** This run's diff changed at least one **test** file. Enumerate the changed files with `git diff --name-only <base>...HEAD` from the worktree cwd — the same enumeration the static review's Scope rule uses — then keep only the paths the gate itself treats as tests: `*.spec.*`, `*.test.*`, a `test_`-prefixed basename, a `_test.` suffixed basename, or any path segment `test/` or `tests/`. Pass nothing else; non-test files are excluded. Exclude `tests/fixtures/self_mock/**` as well — those are the detector's own deliberately self-mocked fixtures, which `validate-run.py` also excludes from the trigger, so feeding them in would manufacture a `FAIL` the gate then blocks on. No changed test file → no run and no sidecar; the gate is vacuous by design.
+- **Run the detector once, in the worktree cwd**, one `--test-file` per changed test file:
+  ```bash
+  python3 ~/.okstra/lib/validators/detect_self_mock.py \
+    --test-file <changed test file> [--test-file <changed test file> ...] \
+    --changed-file <changed file> [--changed-file <changed file> ...] \
+    --sidecar <task_root>/qa/self-mock-<stage-name>.json \
+    --stage-name <stage-name> \
+    --waivers <task_root>/qa/self-mock-waivers.json \
+    --diff <task_root>/qa/self-mock-<stage-name>.diff \
+    --worktree <this stage's worktree root>
+  ```
+  `--changed-file` / `--diff` / `--worktree` feed **gate B** (the mutation probe) and are separate from `--test-file`, which feeds gate A. `--changed-file` takes **every** path in the stage's diff — production sources included, not only the test files — because each mutation adapter selects its own production sources out of that set; hand it only the test files and every adapter finds nothing to mutate, which records a vacuous PASS while gate B is silently dead. Write `--diff` first with `git diff <base>...HEAD > <task_root>/qa/self-mock-<stage-name>.diff` — the same `<base>` and the same range every other `git diff` in this file uses: it is what scopes surviving mutants to the lines this stage added or modified, and without it gate B reports `unsupported(diff-unavailable)` rather than guessing.
+  `<stage-name>` is literally `stage-<N>` for this run's injected Stage number (`stage-3` — not the bare number, not the stageKey), and `<task_root>/qa` is the `TASK_QA_PATH` token, the same directory Tier 3's manifest and `result-*.json` live in. A whole-task run with no stage writes `<task_root>/qa/self-mock.json` and omits `--stage-name`. Any other filename or directory is invisible to the gate and reads exactly like "the detector never ran". Pass `--waivers` **unconditionally**: an absent waiver file is the normal case and the detector treats it as "no waivers", so there is no branch to decide and no file for you to create.
+- **Write the result sidecar (BLOCKING deliverable).** The detector writes `<task_root>/qa/self-mock-<stage-name>.json` itself:
+  ```json
+  {
+    "stageName": "stage-<N>",
+    "overall": "PASS",
+    "ranAt": "<UTC ISO8601>",
+    "scannedFiles": ["<test file the detector read>"],
+    "skippedFiles": ["<test file it received but could not read>"],
+    "changedFiles": ["<every --changed-file path you passed>"],
+    "staticDetect": { "status": "PASS", "hits": [], "waived": [], "waiverSource": "<the --waivers path, or null>" },
+    "mutation": { "status": "unsupported(stryker:tool-not-declared)", "tool": "stryker", "survived": [], "survivedTotal": 0, "waived": [], "waiverSource": "<the --waivers path, or null>" }
+  }
+  ```
+  `overall` is exactly one of `PASS` / `FAIL`. `scannedFiles` + `skippedFiles` together are the detector's own record of **every** `--test-file` path it received: it read the first list, and could not read the second (extension with no signal set, or no file on disk). Which list a path lands in is the **detector's** decision, never yours — a Go/Ruby/C# test, a JSON fixture under `tests/`, and a test file this stage deleted are all legitimate `skippedFiles` entries and none of them is a defect. The verifier MUST NOT hand-write, edit, or "correct" this file — the detector's own output is the evidence, and a hand-authored sidecar is a `contract-violated` outcome. Its absence is not a passive skip: **Enforced:** `validators/validate-run.py` `_validate_selfmock` fails any report whose §5.7.3 diff summary lists a changed test file while this sidecar is absent, unreadable, malformed, or carries `overall != PASS`.
+  **Enforced (coverage, gate B):** the same gate fails the report when a file from §5.7.3 is missing from `changedFiles`, or when that field is absent — that is how "gate B saw this stage" stays distinguishable from "gate B was handed nothing". Pass **every** path in the diff summary to `--changed-file`, production sources included.
+  **Enforced (coverage, gate A):** the same gate fails the report when a changed test file from §5.7.3 appears in **neither** `scannedFiles` nor `skippedFiles` — that means you never passed it, and a PASS over a narrower input says nothing about the file left out. So pass **every** file the trigger enumeration kept, in the same repo-relative spelling the diff summary uses, and let the detector sort them. Pre-filtering by language, or dropping a path because the stage deleted the file, is the one way to trip this check.
+- **Suspected false positive → report it, never waive it (self-check safety).** The signal set is regex-based, so it will occasionally accuse a test that is not self-mocked. The escape hatch is `<task_root>/qa/self-mock-waivers.json`, a JSON array of `{"file": "<repo-relative path, as in --test-file>", "line": <hit line>, "signal": "<signal name>", "reason": "<why this hit is not a self-mock>", "acknowledgedBy": "<the user who accepted it>"}`. A waived hit moves out of `staticDetect.hits` into `staticDetect.waived` and stops counting toward the verdict, so it is the one input that can talk the gate out of a finding — and the finding is about **the code this run is verifying**, which is why the acknowledgement must come from outside the run.
+  **The verifier MUST NOT create, edit, extend, or re-order that file.** It is the user's acknowledgement channel, not yours; writing an entry into it is self-certification of your own finding and is a `contract-violated` outcome exactly like hand-editing the sidecar. You also MUST NOT point `--waivers` at any other file, and MUST NOT copy a waiver entry into the sidecar by hand. **Enforced (source):** the detector records the `--waivers` argument verbatim as `staticDetect.waiverSource`, and `_validate_selfmock` fails any report whose sidecar carries a non-empty `waived` read from anywhere other than this task's `<task_root>/qa/self-mock-waivers.json` — so redirecting the flag at a file you wrote yourself blocks the run instead of clearing it, and every applied waiver is left in the task bundle to review.
+  What you do instead: keep the verdict `FAIL`, and record the suspected false positive in your worker result under the hit's citation — the `path:line`, the signal name, why you believe it is not a self-mock, and the exact JSON object the user would add. The user reviews it, adds the entry with their own `acknowledgedBy`, and the next detector run picks it up through `--waivers`. **Enforced:** `validators/validate-run.py` `_validate_selfmock` fails the report when any `staticDetect.waived` entry is missing a non-empty `reason` or a non-empty `acknowledgedBy` — so an unacknowledged or unexplained waiver blocks the run instead of clearing it, and a matching-but-unacknowledged waiver reaches that gate rather than being silently dropped by the detector.
+- **Read-only command log.** Record the exact command line, its exit code (`0` = PASS, `1` = FAIL), and the detector's last stdout line `QA-RESULT: PASS|FAIL`, together with every `SELF-MOCK <file>:<line> <signal>` line it printed. When the sidecar's `staticDetect.waived` is non-empty, list each waived hit with its `reason` and `acknowledgedBy` so the report shows what the run was excused from and on whose authority. A `FAIL` sets the verifier verdict to `FAIL` with each hit cited `path:line` + signal name and the recommended fix recorded (delete the stub and exercise the real method, or stub injected collaborators only) — the same verdict machinery as the **Self-mocking** blocking check below, which the detector cites for but does not replace: a self-mock the detector's signal set does not cover is still the verifier's finding to make by reading the diff.
+- **Gate B (mutation) runs inside the same detector call.** The detector invokes the mutation probe itself over `--changed-file` and writes the `mutation` block (`status` / `tool` / `survived` / `waived`); your duty is to pass the three flags above, never to author or edit that block by hand. Gate B is a **real gate now** — the `mutation` block is no longer a `pending-phase-2` placeholder, and running the probe over the supported languages in this diff is MANDATORY, which is what the `--changed-file` / `--diff` / `--worktree` flags above accomplish. `status` is `PASS`, `FAIL`, or `unsupported(<reason>)`, and the reason's **class** decides what happens:
+  - **Capability gap** (`no-adapter:<lang>`, `tool-not-declared`, `diff-scope-unavailable`, `no-production-sources`, `no-changed-sources`) or **nothing to verify** (`no-mutants-generated`, `diff-adds-no-line`) — gate B legitimately had no tool or nothing to check. Non-blocking; this is the normal case in a repo without mutation tooling.
+  - **Integrity / inspection failure** (`diff-incomplete`, `diff-unavailable`, `report-unavailable`, `report-unparsed`, `adapter-malformed-status`, `no-conclusive-mutants`, or any reason not listed above) — **this BLOCKS the run.** It means the stage was never actually inspected: most often a `--diff` you built from a different `<base>` than the `--changed-file` list, or one written before your last edit, so the diff does not cover the changed sources. Rebuild the diff from the same `<base>` and re-run the detector; do not treat it as a skip.
+  **Enforced:** `validators/validate-run.py` `_validate_selfmock` blocks on `mutation.status == "FAIL"`, on a missing or malformed `mutation` block, and on any `unsupported(...)` in the integrity/inspection class; the other classes stay excluded from the verdict and are kept in the sidecar for audit.
+- **Suspected false-positive MUTANT → report it, never waive it (self-check safety).** A surviving mutant can be a false accusation too — an unreachable branch, a mutation with no observable behaviour. The escape hatch is the SAME `<task_root>/qa/self-mock-waivers.json` gate A uses, so the user manages one file: a static entry is keyed `{"file", "line", "signal", ...}` and a mutation entry `{"file": "<repo-relative path>", "line": <survivor line>, "mutant": "<mutator name as the detector printed it>", "reason": "<why this mutant is not a real gap>", "acknowledgedBy": "<the user who accepted it>"}`. The `mutant` field is what marks it as gate B's; entries without it are gate A's and never clear a mutant. A waived mutant moves out of `mutation.survived` into `mutation.waived`, and once every survivor on a changed line is waived the mutation verdict is `PASS`.
+  **The verifier MUST NOT create, edit, extend, or re-order that file** — the same rule as gate A, for the same reason: it is the user's acknowledgement channel, and writing an entry into it is self-certification of your own finding, a `contract-violated` outcome exactly like hand-editing the sidecar. You also MUST NOT point `--waivers` anywhere else. **Enforced (fields + source):** the probe only MATCHES waivers and carries an unacknowledged one straight through, so `_validate_selfmock` fails any report whose `mutation.waived` entry is missing a non-empty `reason` or `acknowledgedBy`, or whose `mutation.waiverSource` is not this task's own `qa/self-mock-waivers.json`.
+  What you do instead: keep the verdict `FAIL`, and record the suspected false positive in your worker result under the mutant's citation — the `path:line`, the mutator name, its `Survived`/`NoCoverage` status, why you believe it is not a real coverage gap, and the exact JSON object the user would add. The user reviews it, adds the entry with their own `acknowledgedBy`, and the next detector run picks it up through the same `--waivers` flag. When it is `FAIL`, cite each `MUTANT-SURVIVED <file>:<line> <mutator> (<status>)` line the detector printed: `Survived` means the test ran that line and asserted nothing about it, `NoCoverage` means no test reached it at all — which is what a stubbed subject looks like from the outside.
+
 ### Missing-tier handling
 
 If a tier is empty or absent, verifier records the single line `qa-command not configured: <category>` per missing category (`lint` / `format` / `typecheck` / `test`; and `db-test` **only when the diff touches DB/IO/SQL**, where a missing `db-test` is escalated to a blocking finding per the DB real-execution gate below) in the worker result and proceeds — silent omission is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_missing_qa_categories_recorded` for the four unconditional categories; `db-test` is left to the DB gate below because its requirement depends on whether the diff touches DB/IO/SQL. Without the note, "the category passed" and "the category never ran" read identically in the report. Verifier MUST NOT auto-detect or invent a command in this case; the user/operator must declare it in `project.json.qaCommands` or in the plan.
@@ -98,7 +144,7 @@ Tier 3 external-advisory discrepancies are excluded from this promotion: preserv
 
 ### Read-only command log (per verifier)
 
-The worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order — including the Tier 3 conformance `runCommand` (or the exemption/waiver skip note when no script ran). No source-mutating command may appear in this block; the only permitted mutation is a Tier 3 conformance script writing to its `qaEnv` replica datastore, which is logged like any other command. This log is copied into the final report's verifier result section verbatim.
+The worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order — including the Tier 3 conformance `runCommand` (or the exemption/waiver skip note when no script ran). No source-mutating command may appear in this block; the only permitted mutations are a Tier 3 conformance script writing to its `qaEnv` replica datastore and the self-mock detector writing its own `<task_root>/qa/self-mock-*.json` sidecar — both are artifact-directory writes, both are logged like any other command, and neither touches the worktree source, so the verifier runs them without hesitation. This log is copied into the final report's verifier result section verbatim.
 
 ### Verifier evidence is independent of executor evidence