From a7d91bf15a524f7979371cf29a811d372081c0f4 Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 3 Sep 2026 19:40:05 +0200 Subject: [PATCH] fix(876): sweep session narrative out of hooks, workflows, scripts, tests and code comments; grow the detector to the process corpus MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs.no-session-narrative` reaches every durable artifact, but its detector scanned only `docs/**/*.md` and root markdown, and nothing had ever swept the rest. The issue named four sites from one grep and called them a floor. Deriving the population instead — a whitespace-joined sweep over every tracked file outside the detector, for the detector's own phrasings plus the attribution and review-round class #812 found — gave 453 sites in 108 files at `fb5592971`, and a second pass for phrasings the first list missed (hyphenated `round-N`, "an earlier version", "the reviewer proved") added residuals in the same files. Every site was classified with #812's three dispositions (CUT / SEVER / KEEP with its sub-kind) under the who-benefits test; the per-site manifests are on the PR. The rejected designs, tested-and-rejected fixtures, measurements and traps stay; the attribution of who found them and the round in which they were found go. The detector's population grows to `.claude/`, `.gitea/`, `.husky/` and `scripts/` regardless of extension, minus the detector and its own test (whose fixtures ARE the phrasings) and minus `scripts/tests/fixtures/` (test data, including decision-record copies — the same reasoning as the records' own exemption, and what keeps the record's depth measurement true), and `--all` lists tracked REGULAR files only — a symlink's content is its target and a gitlink has none. The #812 argument for leaving `docs/superpowers/**` in the population runs the other way here: `--diff` sees only ADDED lines, and 287 of the 453 sites were under 30 days old — this corpus is where narrative is being added, so the advisory nudge has reach. Density agrees: 56 line-mode hits over the 113 regular files the predicate admits, against 9 over 66 docs files before #812. `web/` and C# stay out on the same measurement (3 of 74 PATTERNS-matching sites, ~4,600 files). The predicate did not grow: PATTERNS matched 74 of 453 sites, and widening the word list to the attribution class is the treadmill the withdrawn parity test ran on. The population oracle is restated over segments with the new arms, the synthetic cross product gains the process heads and non-markdown extensions, a fixture witnesses that a tracked symlink is neither scanned nor counted, a `.py.bak` axis separates a by-name exemption from a `startswith` over the same tuple, and eight mutants (drop the process arm, drop the by-name exemption, exempt by `startswith`, drop or add a prefix, drop the fixtures exemption, list only markdown, drop the symlink filter, test the mode per row instead of per path) each redden it. A pre-existing silent drop in `--diff` goes with it: git tab-terminates a `+++` filename that contains a space, and the kept tab made `is_scanned_path` refuse the file with no notice — fixed, with a positive control and its own mutant. Code is unchanged by construction, measured per file type against `origin/main`: Python modules are AST-equal with docstrings stripped, except `#` lines inside the embedded fixture programs (string literals) of three test modules; workflows differ only in `#` lines inside `run:` block scalars; shell, C#, TypeScript and jq are equal with comment lines stripped. The stated exceptions: the detector and its test, 26 vitest titles that carried review-round or severity labels or a reviewer attribution (call sites whose title changed — every changed title line walked back to its `it(` / `it.each(...)(` anchor, so a `' + '` concatenation counts once), two registry note strings and the mutation manifest's prose fields. scripts/tests: 1565 passed. Web: lint, typecheck, 1319 tests green. Closes #876. Decisions-Edit: yes Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01PEcBoFw7ctrf3Nb7R7x7wk --- .claude/hooks/pretooluse-agent-model.sh | 6 +- .claude/hooks/pretooluse-merge-consent.sh | 24 +- .gitea/workflows/docker-build.yml | 20 +- .gitea/workflows/pr-checks.yml | 6 +- .gitea/workflows/review-verdict.yml | 153 ++++--- .../Queries/GetSearchFieldValuesHandler.cs | 10 +- .../WatermarkSelectorDecoResolutionTests.cs | 6 +- .../CreateChannelFromLineupHandlerTests.cs | 2 +- .../ScheduleItemResponseRoundTripTests.cs | 6 +- .../GetSearchFieldValuesHandlerTests.cs | 2 +- .../SongIndexerMetadataMutationTests.cs | 2 +- ...2026-07-01-chicorytv-ui-redesign-design.md | 2 +- docs/ci-cd.md | 6 +- .../records/docs/no-session-narrative.md | 26 +- scripts/check-doc-narrative.py | 68 +++- scripts/check-required-contexts.sh | 4 +- scripts/check-review-verdict.sh | 6 +- scripts/ci-prove-ban-detects.sh | 16 +- scripts/ci-step-ran.sh | 18 +- scripts/ci-toolchain-image-resolves.sh | 4 +- scripts/decisions_validate.py | 9 +- scripts/hook-fire-log.sh | 13 +- scripts/jq-preflight.sh | 10 +- scripts/lib/branch-rule-classifier.jq | 14 +- scripts/lib/h10-reviewers.sh | 4 +- scripts/lib/review-verdict-vocabulary.sh | 4 +- scripts/mcp_smoke.py | 16 +- scripts/post-review-verdict.sh | 14 +- scripts/pr-changed-files.sh | 6 +- scripts/prove-fix.sh | 16 +- scripts/tests/conftest.py | 3 +- scripts/tests/hook_fire_isolation.py | 20 +- scripts/tests/mutation_harness_lib.py | 4 +- scripts/tests/mutation_manifest.py | 16 +- .../tests/test_build_catalog_check_path.py | 6 +- scripts/tests/test_check_doc_narrative.py | 208 ++++++++-- scripts/tests/test_check_required_contexts.py | 31 +- scripts/tests/test_check_review_verdict.py | 37 +- scripts/tests/test_ci_dropped_step_guard.py | 49 ++- scripts/tests/test_ci_image_pin_population.py | 14 +- .../tests/test_ci_release_path_scan_job.py | 41 +- .../tests/test_ci_toolchain_image_resolves.py | 2 +- .../test_complete_annotation_dispositions.py | 2 +- scripts/tests/test_decisions_validate.py | 51 ++- .../test_docs_only_detector_clone_depth.py | 12 +- scripts/tests/test_guard_inventory.py | 32 +- .../test_guard_populations_derive_from_git.py | 10 +- scripts/tests/test_hook_fire_log.py | 88 ++-- ...est_image_build_delegates_the_spa_suite.py | 63 ++- scripts/tests/test_jq_preflight.py | 31 +- .../tests/test_merge_consent_base_change.py | 6 +- scripts/tests/test_merge_consent_exemption.py | 17 +- .../tests/test_merge_consent_head_change.py | 4 +- .../test_merge_consent_required_check.py | 67 ++-- scripts/tests/test_migration_equivalence.py | 14 +- scripts/tests/test_mutation_harness.py | 4 +- .../tests/test_optional_request_members.py | 30 +- scripts/tests/test_post_review_verdict.py | 42 +- scripts/tests/test_pr_changed_files.py | 379 +++++++++--------- scripts/tests/test_prepush_unsets_git_env.py | 2 +- scripts/tests/test_prove_fix.py | 23 +- scripts/tests/test_remote_state_inventory.py | 27 +- .../tests/test_review_verdict_vocabulary.py | 10 +- scripts/tests/test_workflow_job_guards.py | 21 +- .../test_workflow_persist_credentials.py | 2 +- .../tests/test_worktree_ownership_guard.py | 14 +- web/src/api/completeAnnotationScan.test.ts | 8 +- web/src/api/completeAnnotationScan.ts | 20 +- web/src/api/completeAnnotations.guard.test.ts | 35 +- web/src/api/completeRequest.guard.test.ts | 10 +- web/src/api/completeRequest.ts | 3 +- web/src/api/libraryBrowse.test.ts | 13 +- web/src/api/pageSizeCallSites.guard.test.ts | 59 ++- web/src/api/pageSizeScan.test.ts | 40 +- web/src/api/pageSizeScan.ts | 12 +- web/src/api/selectionId.test.ts | 6 +- web/src/api/selectionId.ts | 10 +- web/src/builder/ChannelBuilder.test.tsx | 32 +- web/src/builder/libraryBrowse.ts | 14 +- web/src/builder/rules/roundtrip.test.ts | 2 +- web/src/schedules/ScheduleItemInspector.tsx | 6 +- web/src/schedules/pickers.test.tsx | 39 +- web/src/schedules/pickers.tsx | 30 +- web/src/screens/CollectionsScreen.test.tsx | 6 +- web/src/screens/CollectionsScreen.tsx | 29 +- web/src/screens/FillerPresetsScreen.tsx | 6 +- .../PlaybackTroubleshootingScreen.test.tsx | 2 +- .../screens/PlaybackTroubleshootingScreen.tsx | 2 +- web/src/screens/PlaylistsScreen.test.tsx | 12 +- web/src/screens/PlaylistsScreen.tsx | 6 +- .../screens/RerunCollectionsScreen.test.tsx | 64 ++- web/src/screens/RerunCollectionsScreen.tsx | 27 +- web/src/screens/SchedulesScreen.tsx | 6 +- web/vite-plugins/trackedSourceFiles.test.ts | 2 +- web/vite-plugins/trackedSourceFiles.ts | 2 +- 95 files changed, 1275 insertions(+), 1103 deletions(-) diff --git a/.claude/hooks/pretooluse-agent-model.sh b/.claude/hooks/pretooluse-agent-model.sh index e8b28d970..cb71164fc 100755 --- a/.claude/hooks/pretooluse-agent-model.sh +++ b/.claude/hooks/pretooluse-agent-model.sh @@ -12,9 +12,9 @@ # no forcing function was the one that got defaulted. A check that runs beats a rule you must remember # (the same reasoning as pretooluse-bom-guard.sh). # -# SCOPE — gate EVERY dispatch that names no model, not just implementer-looking ones. The first cut -# tried to be clever: it fired only when the prompt text matched implementer signals (`git commit`, -# `worktree`, `fixes #`…). Review of that version (#583) confirmed the heuristic both over- and +# SCOPE — gate EVERY dispatch that names no model, not just implementer-looking ones. A NARROWER +# cut was TRIED AND REJECTED: it fired only when the prompt text matched implementer signals (`git +# commit`, `worktree`, `fixes #`…). Measured (#583), the heuristic both over- and # under-fired — a read-only recon brief mentioning "worktree" nagged, while "author the change and # open a PR", "land this on the branch" and "make the changes and commit them" all sailed through # silently, i.e. it missed the exact case it existed to catch. Prompt prose is not a reliable signal diff --git a/.claude/hooks/pretooluse-merge-consent.sh b/.claude/hooks/pretooluse-merge-consent.sh index 92ed63f08..b96d0fa50 100755 --- a/.claude/hooks/pretooluse-merge-consent.sh +++ b/.claude/hooks/pretooluse-merge-consent.sh @@ -9,8 +9,8 @@ # "re-review the fix commit, not just the initial PR diff"). # # EVERY ONE OF THOSE IS A SNAPSHOT, taken when the merge tool is called. The window is SMALL for an -# immediate merge and UNBOUNDED for a scheduled one. Small is not zero, and this comment used to say -# "sound", which is the overclaim ersatztv#778 removed: this hook returns `allow` and a SEPARATE call +# immediate merge and UNBOUNDED for a scheduled one. Small is not zero, and calling this gate +# "sound" is the overclaim ersatztv#778 removed: this hook returns `allow` and a SEPARATE call # performs the merge, so a push can still land in between. The merge API accepts an optional # `head_commit_id` that would make that call a true compare-and-set; a PreToolUse hook cannot add an # argument, only refuse without one. With merge_when_checks_succeed, Gitea merges @@ -186,11 +186,11 @@ fi # posted before ersatztv#632 and gets NO opinion, rather than denying every in-flight PR the day # this lands. The window closes on its own — verdicts are per-head and short-lived, so every verdict # posted after this carries the field. -# "Could not check" is a THIRD outcome, distinct from both "matches" and "no base recorded". Cold -# review found the first draft collapsing it into the latter: an unreadable status response yielded -# an empty `recorded_base`, which took the graceful-adoption path and skipped validation silently — +# "Could not check" is a THIRD outcome, distinct from both "matches" and "no base recorded". +# Collapsing it into the latter is a false-open: an unreadable status response yields +# an empty `recorded_base`, which takes the graceful-adoption path and skips validation silently — # after which a later, successful status read could still auto-grant. A transient failure would then -# have produced a "merge gate: satisfied" message for a comparison that never happened. Every +# produce a "merge gate: satisfied" message for a comparison that never happened. Every # unreadable input here therefore falls through to a human (`ask`), never to silence. # RE-READ THE BASE HERE, ONCE, FOR EVERY PATH BELOW (ersatztv#778). # @@ -207,8 +207,8 @@ fi # of `process.check-and-use-pins-a-version`, so the guard enforcing that rule must not break it. # # This re-read first landed inside the scheduled-auto-merge branch only, which fixed the branch- -# protection lookup and left the #632 retarget DETECTION below still reading the stale snapshot. Cold -# review demonstrated the consequence with this repo's own fixture: scheduled+retarget denied, while +# protection lookup and left the #632 retarget DETECTION below still reading the stale snapshot. +# Measured on this repo's own fixture: scheduled+retarget denied, while # immediate+retarget auto-GRANTED. That is the twin-missed shape — a fix applied to the path where it # was noticed — so the re-read is hoisted above every consumer rather than duplicated into each. prjson_now=$(gq "repos/$owner/$repo/pulls/$pr") @@ -501,7 +501,7 @@ else # performs no matching and knows nothing about precedence, so a 200 from it means only "a rule # with this NAME exists and lists this context", never "this context is required on this branch". # - # It was used first, with the list consulted only on a 404, and cold review found what that left + # It was used first, with the list consulted only on a 404, and that design left a false-open # behind: the precedence argument below guarded the 404 path while the 200 path — the one this # repo actually takes — granted without it. Given a rule `main` requiring `review-verdict/h10` and # a rule `m*` with better Priority that does not, Gitea applies `m*`, and the by-name hit on @@ -585,8 +585,8 @@ else undecidable) decide ask "H6/H10 merge gate: no branch-protection rule on this repo governs '$base_ref' decidably — a GLOB rule could govern it, or two rule names fold-equal, or a name is non-ASCII. This hook deliberately does not reimplement Gitea's glob matcher, so whether 'review-verdict/h10' is required on this base cannot be derived here (ersatztv#778). Confirm it in the repo's branch-protection settings, or merge immediately instead of scheduling." ;; none) bp_code=nomatch; bp="" ;; # A DECLARED class of the classifier's contract (ersatztv#859), with its OWN sentinel — not - # merely its own arm. The first draft gave it an arm that set `unreadable-rules`, the same value - # the catch-all sets, and that arm was measured to be a no-op: deleting it left the WHOLE suite + # merely its own arm. Giving it an arm that set `unreadable-rules`, the same value + # the catch-all sets, was measured to be a no-op: deleting that arm left the WHOLE suite # green, because nothing downstream could tell the two apart. An arm no observation can # distinguish is not a fix, it is a comment with syntax. (The invariant is "no test reddens", # not a test count — a count goes stale the next time anyone adds one.) @@ -770,7 +770,7 @@ esac # `else` (mwcs = true) and never executes on an immediate merge, which is the common case; hanging # the freshness check off it would fire it only when an auto-merge is armed. This file already # records that exact defect one section up — the base re-read "first landed inside the -# scheduled-auto-merge branch only", and cold review found scheduled+retarget denied while +# scheduled-auto-merge branch only", with scheduled+retarget denied while # immediate+retarget auto-GRANTED. Same shape, so it is not repeated here. # # It reads `main` (the branch the snapshot names), NOT `$base_ref`. That is a DIFFERENT question diff --git a/.gitea/workflows/docker-build.yml b/.gitea/workflows/docker-build.yml index 2e3e79735..ff22cd1a6 100644 --- a/.gitea/workflows/docker-build.yml +++ b/.gitea/workflows/docker-build.yml @@ -128,8 +128,8 @@ env: # serves only its eight `actions/checkout` steps. Note this file needs no `packages:` unit for that # same reason: the `container:` blocks carry explicit `credentials:`. # (Sites above are named by JOB, not by line number: this file is ~1150 lines, so any edit above a -# citation silently invalidates it — which is how the first version of this comment went stale two -# lines after it was written.) +# citation silently invalidates it — a line-number citation here has gone stale within two lines +# of being written.) permissions: code: read @@ -727,9 +727,9 @@ jobs: # runs at all — the image is not built, let alone pushed. Fail-closed by dependency, not by # assertion. # - # WHY IT RUNS THE REAL PYTEST rather than a bespoke scanner. The first cut of #767 hand-parsed the - # workflow YAML in stdlib Python, to avoid provisioning PyYAML on `build`'s bare runner. Two - # independent reviews found ~10 false NEGATIVES in that parser within one round (flow mappings + # WHY IT RUNS THE REAL PYTEST rather than a bespoke scanner. A stdlib hand-parser of the workflow + # YAML was TRIED AND REJECTED in #767 (its appeal: no PyYAML to provision on `build`'s bare + # runner). That parser had ~10 false NEGATIVES, all found at once (flow mappings # `{run: …}`, a quoted `"run":` key, aliases, multiline quoted scalars) — i.e. it was strictly # WEAKER than the check it was meant to backstop, in the one direction that matters for a security # gate. Running the existing PyYAML-based test needs no second implementation of "what is a `run:` @@ -785,16 +785,16 @@ jobs: "${GITHUB_WORKSPACE:-.}/scripts/ci-step-ran.sh" mark ban PYTHONPATH=. python3 -m pytest scripts/tests/test_ci_dropped_step_guard.py scripts/tests/test_ci_release_path_scan_job.py -q # THE POSITIVE CONTROL, and it is deliberately NOT a test (ersatztv#767). The step above proves - # the ban HOLDS; it cannot prove the ban would NOTICE. Review disarmed the entire gate with one - # repo-root `pytest.ini` (`addopts = -k "not delimiter_banned"`) or `conftest.py` - # (`pytest_collection_modifyitems`), which deselects the ban test and every test guarding it, + # the ban HOLDS; it cannot prove the ban would NOTICE. DEMONSTRATED: ONE repo-root `pytest.ini` + # (`addopts = -k "not delimiter_banned"`) or `conftest.py` (`pytest_collection_modifyitems`) + # disarms the entire gate, deselecting the ban test and every test guarding it, # leaving all jobs green with a delimiter sitting in `Smoke`. Nothing inside pytest can be # trusted to catch that, because pytest's own configuration outranks it. # # So this poisons the checked-out workflow, re-runs the SAME command, and fails the job if it # PASSES. It runs in the real checkout — an isolated copy does not inherit the repo-root config - # a disarm would live in, which made the first version of this script report healthy while the - # job's real invocation was deselected. The workflow file is restored by an EXIT trap. + # a disarm would live in, so a check run in a copy reports healthy while the + # job's real invocation is deselected. The workflow file is restored by an EXIT trap. - name: Prove the ban would DETECT a delimiter (ersatztv#767) run: | "${GITHUB_WORKSPACE:-.}/scripts/ci-step-ran.sh" mark selfcheck diff --git a/.gitea/workflows/pr-checks.yml b/.gitea/workflows/pr-checks.yml index f1fbd671b..2e6e6fa76 100644 --- a/.gitea/workflows/pr-checks.yml +++ b/.gitea/workflows/pr-checks.yml @@ -540,9 +540,9 @@ jobs: # is installed, but the one-shot WRITE path `migrate_decisions_split.py` uses PyYAML by # design — and `test_migration_equivalence.py` imports that module, so the suite needs it. # `pytest` and `yaml` are the complete third-party set, established by an AST import scan over - # all of scripts/ rather than by reading the files that seemed relevant: the first cut of this - # job claimed "pure stdlib", passed locally on a machine that happened to have PyYAML, and - # went red in CI on a collection error. + # all of scripts/ rather than by reading the files that seemed relevant — reading only those + # yields "pure stdlib", a claim that passes locally on a machine that happens to have PyYAML + # and goes red in CI on a collection error. - name: Install test dependencies run: python3 -m pip install --disable-pip-version-check --quiet pytest pyyaml # jq gets its OWN step because its VERSION, not merely its presence, is load-bearing diff --git a/.gitea/workflows/review-verdict.yml b/.gitea/workflows/review-verdict.yml index c922c5522..24d85e137 100644 --- a/.gitea/workflows/review-verdict.yml +++ b/.gitea/workflows/review-verdict.yml @@ -89,8 +89,8 @@ name: Review verdict # What IS established on 1.27.1, and stated no wider than it was measured: `pull_request_target` # fires for THIS workflow continuously — 210 such runs across 189 distinct head shas, counting only # runs started strictly after the 2026-08-05 upgrade (measured 2026-09-02). The WINDOW is part of -# the claim, and an earlier draft got it wrong by citing the all-time REPO-WIDE figure: 258 runs / -# 233 shas = 44 before the upgrade date + 4 ON it + 210 after. Citing 258 here would have imported +# the claim, and the all-time REPO-WIDE figure is the WRONG window: 258 runs / +# 233 shas = 44 before the upgrade date + 4 ON it + 210 after. Citing 258 here would import # 1.25.4 evidence into a 1.27.1 sentence. This workflow's own all-time count is 250; the difference # is 8 runs from three since-deleted probe workflows, all pre-upgrade — which is why every one of # the 210 post-upgrade runs is this file. @@ -285,7 +285,7 @@ jobs: # exactly one event — the next run saw a machine-written `pending`, re-derived it, and # posted `success` again, with its own freshly-taken high-water mark now ABOVE the human # row, so the post-write check stayed silent and the rejection went green a second time. - # Found by cold review. Refusing here can only ever withhold an exemption, never grant one. + # Refusing here can only ever withhold an exemption, never grant one. REPAIR_DESC="Human verdict raced this exemption write — re-post the verdict" # THE SECOND SENTINEL, and the two are NOT interchangeable (ersatztv#849). `REPAIR_DESC` # asserts a fact — a human verdict existed and this job's write buried it. Most of the @@ -385,8 +385,8 @@ jobs: # Package Management versions live in `Directory.Packages.props`, so a `.csproj` edit # attributed to Renovate is anomalous by construction. Such a PR is not blocked, it simply # needs a real verdict, which is the correct handling for a PR carrying source changes. - # NOTE the npm manifests are deliberately ABSENT. An earlier draft included - # `web/package.json` / `web/package-lock.json` "so a first SPA bump cannot deadlock". That was + # NOTE the npm manifests are deliberately ABSENT. Including + # `web/package.json` / `web/package-lock.json` "so a first SPA bump cannot deadlock" would be # a self-inflicted code-execution vector for zero benefit: `renovate.json` sets # `enabledManagers: ["nuget", "github-actions", "dockerfile"]`, so Renovate does not manage npm # in this repo at all, while `package.json` carries `scripts` that CI EXECUTES (`npm ci`, @@ -416,7 +416,7 @@ jobs: # not prose about the project — they are the documents that DEFINE the completion protocol, # the merge-consent convention and the H10 rule itself. `.claude/` being protected while the # file that specifies what `.claude/` enforces was docs-only-exempt is the same - # self-exemption the header rules out, one directory over. Found by cold review + # self-exemption the header rules out, one directory over. Measured # (ersatztv#751): driving the real classify body with a lone `CLAUDE.md` change produced # `review-verdict/h10=success`, "Exempt: docs-only change (no code, no protected path)". # @@ -481,9 +481,9 @@ jobs: # every time. Measured 2026-08-29, this repo puts 8 contexts on a `main` head. That case # already stalled before this change — with an ABSENT required check, which reads as "not # reviewed yet" — so what changes is that the stall now says why. - # THE RETURN VALUE IS THE WHOLE POINT, and the first version did not have one: the `else` - # branch ended with a successful `echo`, so the function returned 0 after BOTH POSTs failed - # and its fence caller took the `exit 0` beside it as though the head had been marked. An + # THE RETURN VALUE IS THE WHOLE POINT. Without one the `else` + # branch ends with a successful `echo`, so the function returns 0 after BOTH POSTs failed + # and its fence caller takes the `exit 0` beside it as though the head had been marked. An # explicit `return` per arm, and every caller acts on it. replace_unknown_state() { # $1 = the ::error:: naming what could not be established echo "::error::$1" @@ -508,10 +508,10 @@ jobs: exit 1 } - # DEFINED HERE, BEFORE ANY USE. An earlier round defined these AFTER the classification - # chain that calls them, so `count_matching` was `command not found` on every run, the - # PROTECTED branch silently never fired, and three "protected path" tests still passed — - # they reached `pending` by another route, so the guard being dead was invisible. + # DEFINED HERE, BEFORE ANY USE. Defining them AFTER the classification + # chain that calls them makes `count_matching` `command not found` on every run, the + # PROTECTED branch silently never fires, and three "protected path" tests still pass — + # they reach `pending` by another route, so the guard being dead is invisible. # # HOW THE PATH PREDICATES ARE EVALUATED, and why neither obvious spelling is used. # @@ -559,7 +559,7 @@ jobs: # --- Is there already a verdict for THIS sha? ---------------------------------------- - # NOTE the heading no longer says "never overwrite". It cannot promise that: the read below + # NOTE this heading does NOT say "never overwrite". It cannot promise that: the read below # and the POST at the end of this job are not atomic, so a human verdict posted in between is # still overwritten. The re-read immediately before the POST narrows that window; it does not # close it. Tracked as ersatztv#706 rather than claimed as solved. @@ -582,8 +582,8 @@ jobs: read_existing_verdict() { local json row rv try # `.statuses` IS `null`, NOT `[]`, ON A HEAD WITH NO STATUSES YET — the same nil-slice - # serialization as the timeline terminator, found by cold review of the fix for that one - # (ersatztv#751). Measured on this instance: PR #739's head 5fa672e2 returns + # serialization as the timeline terminator (ersatztv#751). + # Measured on this instance: PR #739's head 5fa672e2 returns # `{"state":"pending","total_count":0,"statuses":null}`. An `array`-only gate read that as # unreadable and took the `exit 1` below, so the job posted NOTHING — fail-closed, but the # user-visible outcome is exactly the one this issue is about: an exempt PR left with no @@ -633,7 +633,7 @@ jobs: st_kind=$(printf '%s' "$json" | jq -r '.statuses | type' 2>/dev/null) || st_kind="" # NUMBER, not `jq -r` text: `jq -r` renders the JSON number 0 and the JSON string "0" # identically, so a schema-corrupted `"total_count": "0"` would satisfy a string compare - # (cold review reproduced this). Requiring the type as well pins the accept path to a real + # (measured, not assumed). Requiring the type as well pins the accept path to a real # numeric zero. st_total=$(printf '%s' "$json" | jq -r 'if (.total_count | type) == "number" then (.total_count | tostring) else "x" end' 2>/dev/null) || st_total="x" st_ok=no @@ -671,7 +671,7 @@ jobs: replace_unknown_and_die "Could not read existing commit statuses for ${SHA:0:7} (.statuses was '${st_kind:-unparseable}', total_count '${st_total}') after a retry, so any ${CONTEXT} already on this head — including one posted by an account this gate does not accept verdicts from — can neither be read nor re-derived." fi # `// []` so the null case cannot hard-error here under `set -e` once it is accepted above. - # TYPE-SAFE, AND A SCHEMA FAILURE REPLACES RATHER THAN DYING (ersatztv#849 round 3). + # TYPE-SAFE, AND A SCHEMA FAILURE REPLACES RATHER THAN DYING (ersatztv#849). # `.statuses` being an array was checked; its ELEMENTS were not. A single scalar in that # array makes `select(.context == ...)` hard-error, jq exits 5, and under `set -e` this # unguarded assignment took the step down — BEFORE any of the replacement paths below, @@ -702,7 +702,7 @@ jobs: # direction for a required check, which must withhold a green rather than grant one. unreadable=$(printf '%s' "$json" | jq -r '[(.statuses // [])[] | select(type != "object" or ((.context | type) != "string"))] | length' 2>/dev/null) || unreadable="" case "$unreadable" in ''|*[!0-9]*) unreadable=1 ;; esac - # ANY UNREADABLE ELEMENT, whether or not a target row was also found. Round 8 scoped this + # ANY UNREADABLE ELEMENT, whether or not a target row was also found. A narrowing scoped it # to "no readable row was found", on the reasoning that a malformed row BESIDE one we did # read is noise. That reasoning does not hold: an element whose `.context` cannot be read # cannot be shown to be a different context, so it may be a mangled rendering of this @@ -758,8 +758,8 @@ jobs: # 736649b3 returned 8 rows keyed id/context/status/creator/description/created_at/ # updated_at/url, ids 14..30 ascending. `// ""` so a server that ever stopped sending it # degrades to the pre-existing text comparison rather than to a false "changed". - # A WRONG TYPE IS NOT AN ABSENT VALUE (ersatztv#849 round 4). Round 3 type-tested these - # four fields and resolved a failure to `""` — which for `.creator` means "no creator", + # A WRONG TYPE IS NOT AN ABSENT VALUE (ersatztv#849). Type-testing these + # four fields and resolving a failure to `""` means, for `.creator`, "no creator", # i.e. unattributable, i.e. RE-DERIVE. That turned a corrupt row into an exemption # `success` where `origin/main` had died before writing anything: measured, a head # carrying `h10=failure` with `"creator": 7` posts `Exempt: docs-only change` here and @@ -784,9 +784,7 @@ jobs: # `.creator.login` HARD-ERRORS on any non-object creator — the same defect #763 fixed in # the post-write filter, still live on this read. `(.creator | type)` short-circuits it, # so the step is not killed; the wrong TYPE then takes the fault route above rather than - # reading as "no creator", which is what made it re-derivable. (An earlier version of - # this comment described that re-derivation as the intended behaviour — it was the - # regression the block above records.) + # reading as "no creator", which is what made it re-derivable. ex_creator=$(printf '%s' "$row" | jq -r --arg f "$SCHEMA_FAULT" 'if (.creator | type) == "object" then (.creator.login // "") elif (.creator | type) == "null" then "" else $f end') ex_desc=$(printf '%s' "$row" | jq -r --arg f "$SCHEMA_FAULT" 'if (.description | type) == "string" then .description elif (.description | type) == "null" then "" else $f end') for _f in "$ex_id" "$ex_state" "$ex_creator" "$ex_desc"; do @@ -797,8 +795,8 @@ jobs: # A `case` prefix test rather than grep: the description is a single short string, and this # removes one more pipeline from a security predicate entirely. The PATTERN is a literal, so # there is no glob-injection concern from $ex_desc. - # A human verdict also has to have been formed against THIS base (ersatztv#698, found in - # round-4 review). `post-review-verdict.sh` records the base it reviewed in the status + # A human verdict also has to have been formed against THIS base (ersatztv#698). + # `post-review-verdict.sh` records the base it reviewed in the status # description — `Review-verdict: MERGEABLE @ abc1234 (base: main)` — precisely because # retargeting changes the effective diff without moving the head sha (ersatztv#632). # Without this check the sha-binding is escapable through the HUMAN path rather than the @@ -1002,8 +1000,7 @@ jobs: # triggered (push -> `pull_request_target` run) pairs on PRs #802, #834 and #761 the # `pull_push` event predates its own run's `started_at` by 26-102s, itself a lower bound # since the job runs a checkout and several steps before counting (69s end to end on run - # 2385). An earlier version of this comment rested the claim on that margin alone and - # called it a deployment property; see `ci.verdict-write-retarget-fence`, which also names + # 2385). See `ci.verdict-write-retarget-fence`, which also names # the one window this does NOT cover — a PR's FIRST push is recorded about a second after # creation and fires no `synchronize`, so an `opened` run landing inside it would abstain # with no successor queued. @@ -1135,12 +1132,11 @@ jobs: # instance; the worst case with the per-page retry below is 40 requests and 20 # one-second sleeps — every page blipping once and recovering — which is 20s of # sleep on top. MEASURED by executing this function against scripted responses, - # not counted by eye: the first draft of this sentence said 19, reasoning that - # the last page could not sleep. It can. + # not counted by eye: 19 would be the count if the last page could not sleep. It can. # - # WALL-CLOCK, which is what the timeout is actually for. An earlier version of this - # comment reasoned that only the last page can pay two timeouts, since a page whose - # BOTH attempts fail ends the walk, and put the bound at ~335s. That bounds TIMEOUTS, + # WALL-CLOCK, which is what the timeout is actually for. A PLAUSIBLE reading is + # that only the last page can pay two timeouts, since a page whose BOTH attempts + # fail ends the walk, which puts the bound at ~335s. That bounds TIMEOUTS, # not elapsed time: attempt 1 can burn its full 15s and attempt 2 still SUCCEED # slowly, so the page costs ~31s and the walk carries on. The pessimum is therefore # 20 x (15 + 1 + 15) = 620s per walk — ~21min on the exempt path's three walks — and @@ -1161,7 +1157,7 @@ jobs: # count with `rt_ok=yes`. Both re-reads share the blind spot, so the counts agree and # the exemption is granted — the SAME construction as before, at the cap instead of at # page 2, at roughly 10x the price. State that price ONCE and in one unit, because - # two earlier drafts of this comment stated it two ways 45 lines apart. The FILTERED + # two statements of it in one file drift into disagreement. The FILTERED # BLOCK is 50 rows in both cases — that is the part which must be inline review # comments. What grew is the timeline the attacker has to build around it: ~100 rows # before (a non-empty page 1, then a 50-row block at a 50-aligned offset) against more @@ -1209,8 +1205,8 @@ jobs: # figure that rots: a real PR's timeline always carries at least one event on page 1 # (the PR is created by a push, which is itself an event). Spot-checked across # #752/#753/#749/#739/#717, all non-empty; the counts themselves are deliberately - # not recorded here because timelines grow and an earlier version of this comment - # cited five numbers of which three were stale within days. Trusting a zero count + # not recorded here because timelines grow and three of five such + # counts went stale within days. Trusting a zero count # from an anomalous first page would mean trusting that no retarget happened on the # strength of a response we cannot explain, so it falls through to `rt_ok=no`, which # withholds the exemption and asks for a human verdict — the safe direction. @@ -1238,8 +1234,8 @@ jobs: # truthiness of its LAST OUTPUT, which is the exit-status subtlety that already bit # this workflow at jq 1.6 (ersatztv#647), and the runner still ships 1.6. A count read # as a VALUE and then range-checked in shell cannot be read two ways, and it matches - # every other tally here. (The first draft of this guard used `jq -e`, safely by - # accident — the array is known non-empty by the check above, so the empty-input + # every other tally here. (Using `jq -e` here would be safe by accident — the + # array is known non-empty by the check above, so the empty-input # divergence could not fire — but "safe because of a property three lines up" is # exactly the reasoning the rule exists to retire.) bad=$(printf '%s' "$raw" | jq -r '[.[] | select(type != "object" or (.type | type) != "string")] | length' 2>/dev/null) || bad="" @@ -1272,8 +1268,8 @@ jobs: # Both callers below want the WHOLE history, and a single `?limit=100` read cannot give it: # `limit` clamps to the server-wide `MAX_RESPONSE_ITEMS`, measured at 50. # - # BE PRECISE ABOUT WHAT THAT COST, because the issue and an earlier version of this comment - # both overstated it. Under the server default (`created_unix DESC`) page 1 holds the NEWEST + # BE PRECISE ABOUT WHAT THAT COST, because the issue overstates it. + # Under the server default (`created_unix DESC`) page 1 holds the NEWEST # rows, and ids are monotonic with `created_at` (measured). So page 1 already carried the # true maximum id, AND every row newer than the mark — which is the only thing the # post-write check selects on. A single-page read therefore missed a raced verdict only if @@ -1323,7 +1319,7 @@ jobs: # EVERY exit publishes what WAS read, not just the complete ones. `ph_ok` alone says # whether the list is whole; a caller that can still use a partial list must be able to # reach it, and the high-water mark below is exactly such a caller — see the fail-open it - # otherwise creates (ersatztv#763, round 2). + # otherwise creates (ersatztv#763). while [ "$page" -le 20 ]; do raw="" kind="" @@ -1417,9 +1413,9 @@ jobs: # combined endpoint is latest-per-context (15 rows on each of the four) and the list # endpoint returns every row ever posted (43-63 across them). # - # THE MECHANISM, so this is re-derivable without a live PR. An earlier draft of this comment - # got it wrong in a way worth recording, because the wrong version is the intuitive one: - # it said `creator: null` means `CreatorID == 0`. It does not. At v1.27.1 an Actions job + # THE MECHANISM, so this is re-derivable without a live PR. The INTUITIVE version is worth + # recording as WRONG, because it is the one a reader will re-derive: + # `creator: null` does NOT mean `CreatorID == 0`. At v1.27.1 an Actions job # authenticates as the SYNTHETIC Actions user, `ActionsUserID = -2` # (`models/user/user_system.go`), which is never a row in the `user` table, and # `NewCommitStatus` stores `CreatorID = opts.Creator.ID` — so an Actions-posted status @@ -1522,7 +1518,7 @@ jobs: pre_state=$ex_state pre_creator=$ex_creator pre_desc=$ex_desc - # THE ID IS PART OF THE SNAPSHOT (ersatztv#849, round 2). The triple cannot see a + # THE ID IS PART OF THE SNAPSHOT (ersatztv#849). The triple cannot see a # REPLACEMENT whose text matches, and the two sentinels are byte-identical by design, so # "another run replaced this row while we classified" was invisible for exactly the rows # where it matters most. Where the server does not send an id both sides are empty and the @@ -1538,7 +1534,7 @@ jobs: # this line — creator, allow-list and description together — is what says so. A separate # `::warning::` annotation was tried and WITHDRAWN: it duplicated all three values from # this line, its only delta was a severity whose rendering could not be probed, and it - # produced three defects across three review rounds (a message that read "from 'timothy', + # produced three successive defects (a message that read "from 'timothy', # which is NOT in H10_REVIEWERS ('timothy')", an unescaped API value interpolated into a # workflow command, and a test that asserted its absence on a path that exits two guards # earlier and so could never fail). One line that is always right beats two where the @@ -1571,7 +1567,7 @@ jobs: if [ "$ex_unverified" = yes ]; then echo "${CONTEXT} on ${SHA:0:7} carries the unverified-write sentinel from an earlier run — reconciling it against the per-POST status history." page_statuses - # THE WITNESS: THE SENTINEL'S OWN ROW MUST BE IN THE HISTORY (ersatztv#849, round 2). + # THE WITNESS: THE SENTINEL'S OWN ROW MUST BE IN THE HISTORY (ersatztv#849). # `ex_unverified=yes` means the COMBINED endpoint just returned the sentinel for this # sha, and `/statuses/{sha}` keeps one row per POST — so a complete history that does # NOT contain it, empty ones included, is a response that cannot be true. The post-write @@ -1586,7 +1582,7 @@ jobs: # PERMANENT sentinel. This asks for a SPECIFIC row already known to exist, and failing it # carries the sentinel forward for THIS run only — the next run retries. # THE WITNESS IS THE CURRENT ROW'S ID, not merely a row with the right text - # (ersatztv#849 round 3). Matching on description alone is satisfied by an OLDER + # (ersatztv#849). Matching on description alone is satisfied by an OLDER # identical sentinel, which is precisely what a fixed point produces: with S1 and a # buried human verdict below the CURRENT S2, a read carrying only S1 satisfies the # witness, `buried` sees nothing, the sentinel clears, and the verdict ends up below the @@ -1596,7 +1592,7 @@ jobs: # `$ex_id` COMES FROM THE COMBINED READ, so it names the row that is current right now. # When the server omits it — not observed on this instance, where every row carries one — # there is nothing to match on and the check degrades to the description, which is the - # pre-round-3 behaviour rather than a new hole. + # description-only behaviour rather than a new hole. if [ -n "$ex_id" ]; then witness=$(printf '%s' "$ph_rows" | jq -r --arg c "$CONTEXT" --argjson wid "$ex_id" \ '[.[] | select(type == "object") @@ -1704,10 +1700,10 @@ jobs: for v in "$n_protected" "$n_not_manifest" "$n_not_docs"; do case "$v" in ''|*[!0-9]*) - # REPLACES, for the reason every other refusal here does (ersatztv#849 round 3): this + # REPLACES, for the reason every other refusal here does (ersatztv#849): this # run has already DECLINED to inherit whatever the head carries, so exiting without - # writing leaves that row authoritative. The old message said no status "will be - # written", which was true and beside the point — the question is what is standing. + # writing leaves that row authoritative. A message saying no status "will be + # written" is true and beside the point — the question is what is standing. replace_unknown_and_die "A path predicate returned '${v}' instead of a count for ${SHA:0:7}, so the classifier is not operating and this run cannot say what belongs on this head." ;; esac done @@ -1779,8 +1775,8 @@ jobs: state=success desc="Exempt: $reason" elif [ "$ex_repair" = yes ]; then - # CARRY THE SENTINEL FORWARD. This branch exists because the first version of it did not, - # and cold review reproduced the consequence: refusing the exemption but posting the + # CARRY THE SENTINEL FORWARD. This branch exists because the consequence of omitting it + # was reproduced: refusing the exemption but posting the # GENERIC pending description overwrote the very sentinel the refusal depends on, so the # next run saw an ordinary machine `pending`, re-derived it, and posted `success` — burying # the human rejection two events after the repair instead of one. The block has to be a @@ -1812,12 +1808,12 @@ jobs: # HIGH-WATER MARK for the post-write verification (ersatztv#706 race 2). Taken FIRST — before # the re-read below, before the fence, before the POST — and the ORDER IS THE POINT. # - # An earlier version captured it just before the POST, "as late as possible". Cold review - # caught that as a High: everything between the re-read and a late mark is a blind gap. A + # Capturing it just before the POST, "as late as possible", is WRONG, and badly so: + # everything between the re-read and a late mark is a blind gap. A # human verdict landing there is invisible to the re-read (which already happened) AND # excluded from the post-write check (its id is BELOW a mark taken afterwards), so it is # silently overwritten with no repair. That gap spans the entire retarget re-count — up to 20 - # timeline round-trips — so it was far wider than the one-round-trip residual being claimed. + # timeline round-trips — far wider than a one-round-trip residual. # # Taking the mark first closes the read side completely: any row newer than the mark is caught # either by the re-read (abstain, post nothing) or by the post-write check (repair). There is @@ -1898,13 +1894,11 @@ jobs: max_id_before=-1 fi - # MARK ANY WRITE NOTHING CAN VERIFY (ersatztv#849 route 1). The heading said "withhold the - # EXEMPTION" while the block downgrades every re-derivable state, which is narrower than - # what it does. + # MARK ANY WRITE NOTHING CAN VERIFY (ersatztv#849 route 1). # - # EVERY RE-DERIVABLE WRITE IS DOWNGRADED, not only `success` (corrected in round 2). An - # earlier version restricted this to the exemption, reasoning that a sticky generic - # `pending` "withholds nothing, since an unreviewed PR is blocked already". That analysed + # EVERY RE-DERIVABLE WRITE IS DOWNGRADED, not only `success`. Restricting + # this to the exemption, on the reasoning that a sticky generic + # `pending` "withholds nothing, since an unreviewed PR is blocked already", analyses # the wrong PR. The damaging case is a PR that IS exemptible and only got the generic # `pending` from a transient enumeration failure: the generic description carries no # marker, the post-write check below does not run without a mark, so a human verdict @@ -1961,17 +1955,17 @@ jobs: exit 0 fi - # A SENTINEL THAT APPEARED MID-RUN (ersatztv#706, round-3 review). The re-read above recomputes + # A SENTINEL THAT APPEARED MID-RUN (ersatztv#706). The re-read above recomputes # `ex_repair`, and until this guard existed nothing downstream read it: the POST writes the # `$state` frozen at classification time, so a STALE OVERLAPPING RUN would post its `success` # straight over a sentinel another run had just written — burying a human rejection, with no # repair (the human row is below this run's mark) and no log. That fails toward SUCCESS, so it # was not covered by the "repair fails toward pending" residual; it is the exact outcome this - # whole change exists to prevent, reached through the run overlap this branch itself measured. + # whole change exists to prevent, reached through a measured run overlap. # # THE RULE IS "NEVER REPLACE A SENTINEL WITH A NON-SENTINEL", not "never overwrite it with a - # success". A first draft of this guard tested `state = success`, which is one branch too - # narrow: a run can reach the POST on `state=pending` carrying the GENERIC description — most + # success". Testing `state = success` here is one branch too narrow: a run can reach + # the POST on `state=pending` carrying the GENERIC description — most # realistically after a transient enumeration failure (`complete != yes`) — and that run # passes a success-only guard, passes the fence, and overwrites the sentinel with ordinary # text. The next run then sees no sentinel, re-derives, and posts `success`: the same buried @@ -2036,7 +2030,7 @@ jobs: # instead of a re-derivable description. Letting `pending` through here is still right — the # alternative strands every PR whenever the timeline is unreadable — but the masking itself # remains a cost, so the trade is "immediate block, one repaired write", not "free". - # ABSTAINING IS A HANDOFF ONLY WHEN THERE IS NOTHING TO HAND OFF (ersatztv#849 round 3). + # ABSTAINING IS A HANDOFF ONLY WHEN THERE IS NOTHING TO HAND OFF (ersatztv#849). # The two arms below are right not to write their CLASSIFICATION — it was computed against # a base or a head the PR may no longer have, and the mutation that invalidated it has # already queued a successor. But when this run DECLINED to inherit a row the head carries, @@ -2106,13 +2100,12 @@ jobs: # in the helper that may be stronger than the reconcilable sentinel. It can only ever # withhold an exemption. mark_desc="$UNVERIFIED_DESC" - # `$desc` ALONE, because the classification has already collected the others. Round 8 - # promoted on `$pre_desc` and `$ex_desc` as well, and both are unreachable as a sole + # `$desc` ALONE, because the classification has already collected the others. Promoting + # on `$pre_desc` and `$ex_desc` as well adds nothing — both are unreachable as a sole # cause: a repair sentinel at the FIRST read sets `ex_repair`, which forces # `desc="$REPAIR_DESC"`; one arriving mid-run is caught by the sentinel guard unless this - # run is itself writing that string, which is the same condition. Keeping them meant two - # clauses no fixture could ever distinguish — the shape this branch has spent several - # rounds either proving or declaring, and here the honest answer is that they are + # run is itself writing that string, which is the same condition. Keeping them means two + # clauses no fixture could ever distinguish, and the honest answer is that they are # redundant rather than unprovable. `$desc` needs no state test: it is this run''s own # decision, and it is `pending` whenever it is that string. if [ "$desc" = "$REPAIR_DESC" ]; then mark_desc="$REPAIR_DESC"; fi @@ -2150,11 +2143,11 @@ jobs: exit 0 fi if { [ "$retargets_before_ok" != yes ] || [ "$rt_ok" != yes ]; } && [ "$state" = "success" ]; then - # ABSTAINING HERE WAS A FAIL-OPEN WHEN THE HEAD ALREADY CARRIED A ROW (ersatztv#849, - # round 2). This branch is reached only after the classification DECLINED to inherit + # ABSTAINING HERE WAS A FAIL-OPEN WHEN THE HEAD ALREADY CARRIED A ROW (ersatztv#849). + # This branch is reached only after the classification DECLINED to inherit # whatever `review-verdict/h10` the head carries — that is why it is re-deriving — so - # posting nothing leaves the declined row current. The old message said the context - # "stays absent", which is true only for a head that had none; on a head carrying a + # posting nothing leaves the declined row current. A message saying the context + # "stays absent" is true only for a head that had none; on a head carrying a # machine or off-list `success` it is the opposite of what happens, and no retarget or # push need have occurred, so no successor run is guaranteed either. # @@ -2312,7 +2305,7 @@ jobs: # over — it carries `creator: null` (an Actions-token POST, measured; see the provenance # note above) and its description is `Exempt: …`, not `Review-verdict:` — so the count is # of human verdicts that did not exist when the mark was taken. - # TWO row shapes count as "something raced this write", not one (round-5 review). + # TWO row shapes count as "something raced this write", not one. # # (a) a HUMAN verdict — non-null creator, `Review-verdict:` description; # (b) a machine SENTINEL — null creator, description exactly `$REPAIR_DESC`. @@ -2534,8 +2527,8 @@ jobs: # a machine-written `success` is re-derived, not inherited, so that successor changes the # answer. A retarget landing before it is caught here. # - # WHAT THAT BUYS IS TRANSIENT INSTEAD OF PERMANENT, not "the green never stands" — which is - # what this comment claimed until round-2 review. The `success` is live between its POST + # WHAT THAT BUYS IS TRANSIENT INSTEAD OF PERMANENT, not "the green never stands". + # The `success` is live between its POST # and the repair below, including the timeline round trips in between, so branch protection # or an already-scheduled auto-merge can observe it. THAT WINDOW GREW WITH #870 and the # sentence is dated accordingly: the walk in between is now 20 requests rather than ~2, diff --git a/ErsatzTV.Application/Search/Queries/GetSearchFieldValuesHandler.cs b/ErsatzTV.Application/Search/Queries/GetSearchFieldValuesHandler.cs index a04adff54..21b762a79 100644 --- a/ErsatzTV.Application/Search/Queries/GetSearchFieldValuesHandler.cs +++ b/ErsatzTV.Application/Search/Queries/GetSearchFieldValuesHandler.cs @@ -18,8 +18,7 @@ public class GetSearchFieldValuesHandler(IDbContextFactory dbContextF /// Rows read per round trip when walking the list-valued (JSON-array) columns on /// SongMetadata, and the ceiling on rows read per request. /// - /// These count ACTUAL ROWS, and arriving at that took four tries — each earlier attempt bounded a - /// quantity that sounded like rows and was not. A fixed LIMIT budget bounded the RESULT, and + /// These count ACTUAL ROWS. A fixed LIMIT budget bounded the RESULT, and /// the pre-filter (allowed to over-match) starved it with rows that could not match. Keyset paging /// with a LIMIT bounded CANDIDATES RETURNED — but a query matching nothing must evaluate /// every eligible row before it can return an empty page, so rows inspected stayed unbounded. A @@ -36,8 +35,7 @@ public class GetSearchFieldValuesHandler(IDbContextFactory dbContextF /// /// /// Be precise about what is bounded: LOGICAL ROWS RETURNED AND MATERIALIZED, and the number of - /// round trips. Not physical work, and not bytes. Two things break the stronger reading, and an - /// earlier version of this comment asserted it anyway: + /// round trips. Not physical work, and not bytes. Two things break the stronger reading: /// /// /// MySQL purge lag. Deleted clustered-index records survive until purge runs, and a range @@ -142,7 +140,7 @@ public class GetSearchFieldValuesHandler(IDbContextFactory dbContextF // over-match, even though the column collation (utf8mb4_0900_ai_ci) is accent-insensitive: the driver // binds the LIKE pattern with a BINARY collation, so the comparison is accent-sensitive in practice. // A hand-typed probe using a LITERAL pattern DOES over-match; that is a different query from the one - // this code runs, and mistaking the two is how an earlier revision of the decision record got it wrong. + // this code runs, and mistaking the two gives a false read on whether this predicate over-matches. if (source is not null && ContainsNonAscii(query) && IsSqlite(dbContext)) { values.AddRange( @@ -472,7 +470,7 @@ public class GetSearchFieldValuesHandler(IDbContextFactory dbContextF /// ordering key, which positions the scan and never discards a row, whereas a residual /// predicate throws away rows the engine already produced. LIMIT only truncates what /// survives a residual predicate, so with one present it bounds the output rather than the row - /// count — which is how every earlier revision scanned past its own bound. With none, LIMIT n + /// count — a gap wide enough to scan straight past a nominal row-count bound. With none, LIMIT n /// yields n logical rows. Null payloads are dropped in memory by /// . /// diff --git a/ErsatzTV.Core.Tests/FFmpeg/WatermarkSelectorDecoResolutionTests.cs b/ErsatzTV.Core.Tests/FFmpeg/WatermarkSelectorDecoResolutionTests.cs index 8ae3e001d..153bde753 100644 --- a/ErsatzTV.Core.Tests/FFmpeg/WatermarkSelectorDecoResolutionTests.cs +++ b/ErsatzTV.Core.Tests/FFmpeg/WatermarkSelectorDecoResolutionTests.cs @@ -359,9 +359,9 @@ public class WatermarkSelectorDecoResolutionTests /// /// /// The channel-level fallback is deliberately an INDEPENDENTLY RESOLVABLE `ChannelLogo` watermark whose - /// cached file exists. An earlier version of this test gave the fallback the same missing custom path as - /// the playout-item watermark, which made it unfalsifiable: a wrongly-widened guard would have fallen - /// through to a fallback that also resolved to None, so the assertion held either way. + /// cached file exists. Giving the fallback the same missing custom path as the playout-item watermark + /// would make the test unfalsifiable: a wrongly-widened guard would fall through to a fallback that also + /// resolves to None, so the assertion would hold either way. /// [Test] public void Missing_But_Named_Custom_Playout_Item_Watermark_Should_Not_Fall_Through() diff --git a/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs b/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs index 706c11ecb..430d15008 100644 --- a/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs +++ b/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs @@ -464,7 +464,7 @@ public class CreateChannelFromLineupHandlerTests [Test] public async Task Should_Reject_WeightedShuffle_For_A_Multi_Item_Lineup() { - // regression (#70, found by adversarial review of PR #402): a 2+ entry lineup is persisted as a + // regression (#70, PR #402): a 2+ entry lineup is persisted as a // Playlist, and PlaylistEnumerator has no default arm -- an order it doesn't know leaves the // enumerator null and the items vanish from the playlist with nothing reported. This handler is the // THIRD writer of PlaylistItem.PlaybackOrder and was missed when the other two were gated. diff --git a/ErsatzTV.Tests/Application/ProgramSchedules/ScheduleItemResponseRoundTripTests.cs b/ErsatzTV.Tests/Application/ProgramSchedules/ScheduleItemResponseRoundTripTests.cs index fc2754f83..dbb04d92b 100644 --- a/ErsatzTV.Tests/Application/ProgramSchedules/ScheduleItemResponseRoundTripTests.cs +++ b/ErsatzTV.Tests/Application/ProgramSchedules/ScheduleItemResponseRoundTripTests.cs @@ -358,9 +358,9 @@ public class ScheduleItemResponseRoundTripTests // that for this fixture's payload: it forwards every Id, takes the id-based reconcile, and // updates rows in place. So Id compares equal, and the exemption was unnecessary. // - // Two mutations of this fixture, both EXECUTED — recorded as results, with no account of why, - // because three earlier drafts of this comment each supplied a confident mechanism for a - // correct observation and two of them were contradicted by the code: + // Two mutations of this fixture, both EXECUTED — recorded as results, with no account of why: + // a confident mechanism for this observation is easy to get wrong, and two independent ones + // were each contradicted by the code: // // ToReplaceCommand passes `null` for EVERY id -> test stays GREEN // ToReplaceCommand passes `null` for index 0 only -> test goes RED, "Id differs" diff --git a/ErsatzTV.Tests/Application/Search/GetSearchFieldValuesHandlerTests.cs b/ErsatzTV.Tests/Application/Search/GetSearchFieldValuesHandlerTests.cs index 1e34d59ac..55aaa2dc8 100644 --- a/ErsatzTV.Tests/Application/Search/GetSearchFieldValuesHandlerTests.cs +++ b/ErsatzTV.Tests/Application/Search/GetSearchFieldValuesHandlerTests.cs @@ -372,7 +372,7 @@ public class GetSearchFieldValuesHandlerTests [Test] public async Task List_Valued_Walk_Reads_Live_Rows_Regardless_Of_Id_Density() { - // THE round-4 killer. That revision bounded the Id KEYSPACE, and keyspace is not rows: with 20,000 + // Bounding the Id KEYSPACE is the killer here: keyspace is not rows — with 20,000 // historical rows deleted and one live song at Id 20001, the walk spent its whole allowance on empty // ranges and returned [] for a table containing exactly one row. Capacity degraded linearly with // deletion ratio, and no ratio was safe -- one placed gap hid the next match. diff --git a/ErsatzTV.Tests/Integration/SongIndexerMetadataMutationTests.cs b/ErsatzTV.Tests/Integration/SongIndexerMetadataMutationTests.cs index b409722d4..58a7abe7a 100644 --- a/ErsatzTV.Tests/Integration/SongIndexerMetadataMutationTests.cs +++ b/ErsatzTV.Tests/Integration/SongIndexerMetadataMutationTests.cs @@ -33,7 +33,7 @@ namespace ErsatzTV.Tests.Integration; /// the decision record media.nullable-primitive-collection-mutation. /// Assigning one on a TRACKED entity flips it to , and the next /// SaveChanges writes [] over what the database held as NULL — the exact -/// mechanism an adversarial review demonstrated in ersatztv#691, which is why that issue's +/// mechanism demonstrated in ersatztv#691, which is why that issue's /// entity-level guard was reverted in favour of guarding at the READ SITE. /// /// diff --git a/design-system/docs/superpowers/specs/2026-07-01-chicorytv-ui-redesign-design.md b/design-system/docs/superpowers/specs/2026-07-01-chicorytv-ui-redesign-design.md index fc49d6e4d..ef4a09714 100644 --- a/design-system/docs/superpowers/specs/2026-07-01-chicorytv-ui-redesign-design.md +++ b/design-system/docs/superpowers/specs/2026-07-01-chicorytv-ui-redesign-design.md @@ -176,7 +176,7 @@ Tracked under epic **#62**; sub-issues #63–#68: ## 7. Out of scope & next steps -**Out of scope now:** the full #59 implementation spec, React app architecture (routing/state/auth/build/deploy), the media-libraries/collections browser (Pass 2), browser-based channel playback (tracked separately in #60), the actual rebuild. (Channel creation was originally deferred to Pass 2 but is now specified in §6.) +**Out of scope now:** the full #59 implementation spec, React app architecture (routing/state/auth/build/deploy), the media-libraries/collections browser (Pass 2), browser-based channel playback (tracked separately in #60), the actual rebuild. (Channel creation is specified in §6, not deferred to Pass 2.) **Next steps (after a look is locked):** 1. Design the §6 Create Channel screen in Claude Design; file the §6 backend-gap issues. diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 8c1dd5182..4e5e0a572 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1148,8 +1148,10 @@ one case that's easy to forget and easy to detect: a PR that touches a SPA scree `::warning::` annotation. **2. The session-narrative reminder** (ersatztv#784) runs `scripts/check-doc-narrative.py --diff` -over the lines this PR **adds** to `docs/**/*.md` (minus `docs/decisions/**`, exempt wholesale) and -root-level `*.md`, flagging text that narrates the document's own revision history — +over the lines this PR **adds** to `docs/**/*.md` (minus `docs/decisions/**`, exempt wholesale), +root-level `*.md`, and — since ersatztv#876 — every tracked file under `.claude/`, `.gitea/`, `.husky/` +and `scripts/` regardless of extension (minus the detector and its own test, whose fixtures are the +phrasings), flagging text that narrates the artifact's own revision history — `docs.no-session-narrative`. It is advisory **by design and permanently**: a narrative detector is a string predicate over prose, the class `docs/defect-shapes-773.md` §4 argues must never be load-bearing, so the script exits 0 on every path including a bad argument or an unresolvable base diff --git a/docs/decisions/records/docs/no-session-narrative.md b/docs/decisions/records/docs/no-session-narrative.md index 005c417ff..182a864ba 100644 --- a/docs/decisions/records/docs/no-session-narrative.md +++ b/docs/decisions/records/docs/no-session-narrative.md @@ -6,8 +6,8 @@ since: '2026-08-21' supersedes: none superseded-by: none rule: 'Every durable artifact — an in-repo `docs/` page, a skill, a README, a code comment, an Obsidian vault page — records the END STATE. The path to that end state goes in the commit message, the Gitea issue, or the issue''s `## Closing record`; it does not go in the artifact. Concretely: **a review finding is answered in the commit message, and only the corrected claim enters the doc.** Naming the destination is load-bearing — "do not write it in the doc" with no home loses the knowledge, and this repo has the inverse failure on record too (#542, where a pruned narrative turned out to be the only copy). THE TEST IS WHO BENEFITS: if only the author''s timeline explains why a sentence is there, it is narrative and belongs in the commit; if a reader who never saw the session would act differently knowing it, it is a finding and stays. Session narrative reads as: first person or session chronology ("I initially thought", "an earlier draft counted", "my first attempt returned 0"), a correction of a belief the reader never held ("this was wrong, actually X" where only X matters), relative time ("earlier today", "currently investigating"), or a blow-by-blow diagnosis standing in place of the conclusion. THE CARVE-OUT, which must be stated or the rule gets over-applied — reader-facing history that must survive: a decision record''s `supersedes`/`superseded-by`; a dated measurement or an explicitly stated snapshot boundary; a TESTED-AND-REJECTED negative result, kept so nobody re-proposes it on plausibility; the *why* behind a non-obvious choice; and a trap together with its consequence. `docs/decisions/records/**` and `docs/decisions/archive/**` are exempt WHOLESALE: a record narrating how a rule was got wrong is carrying the rationale it exists to carry. `docs/superpowers/**` — the dated plans and specs — IS reached by the rule (#812), and is NOT exempt from the detector either. The narrative sites IDENTIFIED there were remediated with the rest of the corpus — identified, not all, since no sweep here claims closure over a phrasing space. The one surviving detector hit is a carve-out on its merits, keeping a rejected design together with the concrete harm that killed it. A wholesale detector exemption for that path was proposed and REJECTED, recorded so it is not re-proposed on plausibility: the argument was that all 35 files are frozen (measured 2026-08-29, before this change: nothing had been edited there since 2026-07-23), so sweeping them yields only false positives. But `--diff`, the mode CI runs, scans ADDED lines, and a frozen file contributes none — so the exemption buys nothing where the check actually runs, and what it WOULD suppress is any plan being written OR REVISED now — 15 of the 35 have more than one commit, so revisions do happen — which is exactly the case where the remedy (move it to the commit message) is still available. It costs the detector''s only reach to buy quiet in a sweep a person runs deliberately. ENFORCEMENT IS ADVISORY ONLY — `scripts/check-doc-narrative.py`, run non-blocking from the `docs-reminder` job over ADDED lines. It is a string predicate over prose and may never become a blocking gate.' -signals: 'no session narrative in docs · the reader never saw the earlier draft · who-benefits test · answer a review finding in the commit message not the doc · end state versus path to it · earlier draft · first version of this table · my first attempt · relative time in a doc · carve-out for dated measurement and snapshot boundary · tested-and-rejected negative result · decision records are exempt on purpose · advisory not blocking · string predicate over prose · does the rule reach docs/superpowers · dated plans and specs · a frozen file contributes no ADDED lines so --diff never sees it · exempting a path costs the detector''s only reach · detector population unchanged by #812 · paths: `scripts/check-doc-narrative.py`, `.gitea/workflows/pr-checks.yml`, `docs/handoffs/chicorytv-issue-queue.md`, `docs/defect-shapes-773.md` · issues: #784, #812, #773, #767, #743, #542' -mechanics: 'The RULE is about every durable artifact; the DETECTOR''s population is narrower and is stated here so a row in it never reads as coverage it does not have. `scripts/check-doc-narrative.py` scans `docs/**/*.md` minus `docs/decisions/**` (exempt wholesale, in both modes), plus root-level `*.md` — a population #812 left UNCHANGED after considering and rejecting a `docs/superpowers/**` exemption. The exemption test carries a hand-written sample path per prefix in `EXEMPT_PREFIXES` and asserts set equality against it, so a prefix added without a case reddens; it also asserts a NON-EXEMPT control HIT in the same invocation, because `hits(out) == set()` alone passes when the scan examined nothing — a scanned-zero run is indistinguishable from a working exemption. What that buys is bounded, and the bound is stated because three rounds of trying to widen it each failed: the test proves the scan EXAMINED something, NOT that a sample''s absence is attributable to the prefix rather than to its shape. A lone depth-1 control fell to a depth-1 population rule; a depth-3 control fell to a `count("/") <= 3` cap; minimal twins differing only in the renamed directory fall to a directory-NAME rule keyed on that rename. Each fix was locally correct and the sequence did not converge — the same shape as the withdrawn `test_review_verdict_vocabulary_parity.py` cited below — so the claim was retracted rather than a fourth finite control added. The residual that remains after all of it is the WIRING: every proof below is about `is_scanned_path`, and nothing in it establishes that the SCAN consults that function — a `continue` added at either call site re-exempts a path with the function untouched, measured to drop `--all` from 66 files to 31 with the oracle still green. A fixture under `docs/superpowers/` is asserted to reach the OUTPUT for exactly that reason, so the one re-exemption this record argues against is witnessed rather than assumed; the general residual is not closed. What closes the SHAPE question is a CLOSED-FORM proof: `is_scanned_path` is compared against an INDEPENDENT restatement of the population rule (written over path segments, not string prefixes) across every tracked `*.md` path AND a cross product of FOUR dimensions a population rule has been OBSERVED to key on here — depth, first segment, second segment, extension — since widened with basename, case and dotted directories. That list ENUMERATES; it is not a universal over the space of rules, and a dimension on neither list has simply not been measured. The real corpus alone is not enough, and that is measured: no scanned path carries more than three slashes today, so a `count("/") <= 3` cap is a no-op against it and would ship latent. The three controls'' defeating mutations (a depth-1 rule, a `count("/") <= 3` cap, a directory-NAME rule) all redden it, as do scan-nothing and a dropped prefix — and so do the basename, case, dotted-directory and extension mutants a later round added the corresponding axes for. Skills under `.claude/`, `web/`, and every other nested markdown file outside `docs/` are OUT of its scope and stay a human judgement. It warns and exits 0 on every path — bad argument, unresolvable ref, unreadable file, unhandled exception — asserted per argument shape in `scripts/tests/test_check_doc_narrative.py`, not only in prose, EXCEPT the unhandled-exception arm, which is a bare `except` no test exercises and is recorded as unproven rather than implied. The invariant is held at the JOB level too (`continue-on-error` on both steps): a script that returns 0 does not keep a job green if a setup action fails. Every knob DEMONSTRATED to break the parse has a row in `FORMAT_KNOBS` in the test file; the user and system config files are removed from the picture entirely so an unnamed one cannot reach it. Three separate review rounds each found ONE more knob turning a real hit into a clean-looking `scanned 0 file(s)`, so the third fix removed the surface rather than naming a fourth knob — a completeness claim over the knob space would be exactly the enumeration that failed three times. COVERAGE BOUNDARY, written once so it is not rediscovered one clause at a time, and naming the clauses rather than a category because a category is where the last mis-sort hid. MUTATION-PROVEN: the parse path (hunk state, the `\` marker, the `diff --git` reset, `splitlines`, the population count, `re.IGNORECASE`, the SCANNED-NOTHING return) and five pins — `core.quotePath=false`, `--find-renames`, `--dst-prefix`, `--no-ext-diff`, `--no-color`. UNPROVEN and defensive, recorded as such rather than implied to be covered: `-U0` (the context arm handles any `-U`, so removing it reddens nothing), the `GIT_CONFIG_GLOBAL`/`SYSTEM`/`NOSYSTEM` overrides (which exist for the UNNAMED knob and therefore cannot be witnessed — the script says so itself), `--src-prefix`, the `+++ /dev/null` deletion arm, the malformed-`@@` arm, the stderr relay, `git()`''s `OSError` return, `run_all`''s failure sentinel, `open(errors=)` and the top-level `except`. Both lists ENUMERATE; neither is a universal over the file, and a clause on neither list has simply not been measured. `--diff` scans only lines ADDED in the PR (with rename detection, so a `git mv` does not re-flag a file''s pre-existing content) and reports `SCANNED NOTHING` rather than a clean-looking line when it cannot resolve the base. `--all` sweeps the tracked corpus from `git ls-files`, never a filesystem walk (#778). Two consequences of added-lines-only are deliberate and stated so they are not mistaken for coverage: a file MOVED into the population (`web/x.md` to `docs/x.md`) is never scanned by any PR, and neither is anything already in the corpus. `--all` is the only thing that sees either, which is why the sweep is a task a person runs rather than a job.' +signals: 'the process corpus is in the detector population since #876 · hooks workflows scripts and their tests are scanned regardless of extension · the predicate did not grow with the population · no session narrative in docs · the reader never saw the earlier draft · who-benefits test · answer a review finding in the commit message not the doc · end state versus path to it · earlier draft · first version of this table · my first attempt · relative time in a doc · carve-out for dated measurement and snapshot boundary · tested-and-rejected negative result · decision records are exempt on purpose · advisory not blocking · string predicate over prose · does the rule reach docs/superpowers · dated plans and specs · a frozen file contributes no ADDED lines so --diff never sees it · exempting a path costs the detector''s only reach · detector population unchanged by #812 · paths: `scripts/check-doc-narrative.py`, `.gitea/workflows/pr-checks.yml`, `docs/handoffs/chicorytv-issue-queue.md`, `docs/defect-shapes-773.md` · issues: #784, #812, #773, #767, #743, #542' +mechanics: 'The RULE is about every durable artifact; the DETECTOR''s population is narrower and is stated here so a row in it never reads as coverage it does not have. `scripts/check-doc-narrative.py` scans `docs/**/*.md` minus `docs/decisions/**` (exempt wholesale, in both modes), plus root-level `*.md` — a population #812 left UNCHANGED after considering and rejecting a `docs/superpowers/**` exemption — and, since #876, EVERY tracked file under `.claude/`, `.gitea/`, `.husky/` and `scripts/` regardless of extension (the PROCESS corpus: hooks, workflows, scripts and their tests), minus the detector and its own test file, whose string fixtures ARE the phrasings and would be permanent hits, and minus `scripts/tests/fixtures/` — test DATA, including copies of decision records, exempt on the same reasoning as the records themselves; `--all` lists tracked REGULAR files only, because a tracked symlink''s content is its target (this repo''s `.claude/skills/jellyfin` is a cross-repo link to a directory), not the artifact. The predicate did NOT grow with the population: PATTERNS matched 74 of the 453 sites the #876 sweep found outside the docs corpus (measured 2026-09-03 at `fb5592971`), because the class that dominates code and hook comments — an attribution of WHO found a finding, or a review-round chronology — is deliberately absent from a list kept narrow enough not to false-positive on carved-out history. So the row buys a nudge on roughly one in six new sites, and the sweep stays a task a person runs. The exemption test carries a hand-written sample path per prefix in `EXEMPT_PREFIXES` and asserts set equality against it, so a prefix added without a case reddens; it also asserts a NON-EXEMPT control HIT in the same invocation, because `hits(out) == set()` alone passes when the scan examined nothing — a scanned-zero run is indistinguishable from a working exemption. What that buys is bounded, and the bound is stated because three rounds of trying to widen it each failed: the test proves the scan EXAMINED something, NOT that a sample''s absence is attributable to the prefix rather than to its shape. A lone depth-1 control fell to a depth-1 population rule; a depth-3 control fell to a `count("/") <= 3` cap; minimal twins differing only in the renamed directory fall to a directory-NAME rule keyed on that rename. Each fix was locally correct and the sequence did not converge — the same shape as the withdrawn `test_review_verdict_vocabulary_parity.py` cited below — so the claim was retracted rather than a fourth finite control added. The residual that remains after all of it is the WIRING: every proof below is about `is_scanned_path`, and nothing in it establishes that the SCAN consults that function — a `continue` added at either call site re-exempts a path with the function untouched, measured 2026-08-29 (#812, when `--all` scanned 66 files) to drop it to 31 with the oracle still green. A fixture under `docs/superpowers/` is asserted to reach the OUTPUT for exactly that reason, so the one re-exemption this record argues against is witnessed rather than assumed; the general residual is not closed. What closes the SHAPE question is a CLOSED-FORM proof: `is_scanned_path` is compared against an INDEPENDENT restatement of the population rule (written over path segments, not string prefixes) across every tracked path (5,160 at 2026-09-03; every tracked `*.md` path before #876) AND a cross product of FOUR dimensions a population rule has been OBSERVED to key on here — depth, first segment, second segment, extension — since widened with basename, case and dotted directories. That list ENUMERATES; it is not a universal over the space of rules, and a dimension on neither list has simply not been measured. The real corpus alone is not enough, and that is measured: no scanned path carries more than three slashes (re-measured 2026-09-03 after #876 grew the population to 179 files — true only because `scripts/tests/fixtures/` is exempt; its record copies sit at four to six), so a `count("/") <= 3` cap is a no-op against it and would ship latent. The three controls'' defeating mutations (a depth-1 rule, a `count("/") <= 3` cap, a directory-NAME rule) all redden it, as do scan-nothing and a dropped prefix — and so do the basename, case, dotted-directory and extension mutants a later round added the corresponding axes for. `web/`, C# source, and every nested markdown file outside `docs/` and the four process directories are OUT of its scope and stay a human judgement — where the line sits is measured, not felt: of those 74 PATTERNS-matching sites, 71 are in the process directories and 3 across the ~4,600 tracked files of `web/` and the C# projects. It warns and exits 0 on every path — bad argument, unresolvable ref, unreadable file, unhandled exception — asserted per argument shape in `scripts/tests/test_check_doc_narrative.py`, not only in prose, EXCEPT the unhandled-exception arm, which is a bare `except` no test exercises and is recorded as unproven rather than implied. The invariant is held at the JOB level too (`continue-on-error` on both steps): a script that returns 0 does not keep a job green if a setup action fails. Every knob DEMONSTRATED to break the parse has a row in `FORMAT_KNOBS` in the test file; the user and system config files are removed from the picture entirely so an unnamed one cannot reach it. Three separate review rounds each found ONE more knob turning a real hit into a clean-looking `scanned 0 file(s)`, so the third fix removed the surface rather than naming a fourth knob — a completeness claim over the knob space would be exactly the enumeration that failed three times. COVERAGE BOUNDARY, written once so it is not rediscovered one clause at a time, and naming the clauses rather than a category because a category is where the last mis-sort hid. MUTATION-PROVEN: the parse path (hunk state, the `\` marker, the `diff --git` reset, the TAB git appends to a `+++` filename containing a space — kept, it drops the file silently (#876), `splitlines`, the population count, `re.IGNORECASE`, the SCANNED-NOTHING return) and five pins — `core.quotePath=false`, `--find-renames`, `--dst-prefix`, `--no-ext-diff`, `--no-color`. UNPROVEN and defensive, recorded as such rather than implied to be covered: `-U0` (the context arm handles any `-U`, so removing it reddens nothing), the `GIT_CONFIG_GLOBAL`/`SYSTEM`/`NOSYSTEM` overrides (which exist for the UNNAMED knob and therefore cannot be witnessed — the script says so itself), `--src-prefix`, the `+++ /dev/null` deletion arm, the malformed-`@@` arm, the stderr relay, `git()`''s `OSError` return, `run_all`''s failure sentinel, `open(errors=)` and the top-level `except`. Both lists ENUMERATE; neither is a universal over the file, and a clause on neither list has simply not been measured. `--diff` scans only lines ADDED in the PR (with rename detection, so a `git mv` does not re-flag a file''s pre-existing content) and reports `SCANNED NOTHING` rather than a clean-looking line when it cannot resolve the base. `--all` sweeps the tracked corpus from `git ls-files`, never a filesystem walk (#778). Two consequences of added-lines-only are deliberate and stated so they are not mistaken for coverage: a file MOVED into the population (`web/x.md` to `docs/x.md`) is never scanned by any PR, and neither is anything already in the corpus. `--all` is the only thing that sees either, which is why the sweep is a task a person runs rather than a job.' --- The rule already existed, correctly stated, and scoped to exactly one file. The kickoff handoff said @@ -71,6 +71,28 @@ sites IDENTIFIED there were remediated with the rest of the corpus — identifie one surviving hit is a genuine carve-out: it keeps a rejected design together with the concrete harm that killed it. +**The population grew to the process corpus in #876, and the argument is the #812 argument run forward.** The +rule reached `.claude/` hooks, workflows, scripts and code comments from the day it was written; nothing had +ever swept them. The sweep found 453 sites outside the docs corpus (measured 2026-09-03 at `fb5592971`, a +whitespace-joined grep for the detector's own phrasings plus the attribution class — a floor, not a +population), and 287 of them had been written within the preceding 30 days. That is the inverse of the +`docs/superpowers/**` case above: there, a frozen path contributes no ADDED lines so `--diff` can never see +it; here, the corpus is where narrative is being written NOW, which is exactly where the remedy — move it to +the commit message being written in the same act — is still available. Density says the same thing: 56 +line-mode PATTERNS hits across the 113 regular files the predicate admits under `.claude/`, `.gitea/`, +`.husky/` and `scripts/` (120 tracked entries, minus the two exempt by name, the fixtures directory and a +symlink), against 9 across the 66 docs files before #812. The population now includes those four directories regardless of +extension, because the artifacts there are shell, YAML, Python and jq, not Markdown. Two files are exempt by +name, not prefix: the detector and its own test, whose fixtures are the phrasings. `scripts/tests/fixtures/` is exempt as test data — it holds copies of decision records, at four to six +slashes, which is also what keeps the depth measurement in `mechanics:` true. `web/` and the C# projects +are left out on the same measurement, stated so the boundary is not read as arbitrary: 3 of the 74 +PATTERNS-matching sites lived there, across roughly 4,600 tracked files. What did NOT change is the predicate. +The class the sweep actually found — "cold review found", "round 3 caught", "found by adversarial review of +PR #N" — matched PATTERNS in one site of six, and extending the word list to it is the treadmill the +withdrawn parity test ran on: every round's list locally correct and the sequence never converging. So the +row buys reach over newly written comments in the corpus that carries them, at advisory cost, and claims no +coverage of the class beyond that. + **If this ever becomes a hook, it belongs at USER scope, not in this repo.** The rule is not ersatztv-specific — it is true of every repo — and an ersatztv-only hook would enforce it exactly where it was first noticed and nowhere else, which is the shape this record exists to close. diff --git a/scripts/check-doc-narrative.py b/scripts/check-doc-narrative.py index 061864f85..fe227fbc1 100755 --- a/scripts/check-doc-narrative.py +++ b/scripts/check-doc-narrative.py @@ -10,8 +10,8 @@ narrative detector is a string predicate over prose, and `docs/defect-shapes-773 withdrawn `test_review_verdict_vocabulary_parity.py` — six review rounds, then deleted — is the empirical case). Do not convert this into a gate; the decision record says no in as many words. -WHY PYTHON AND NOT SHELL. The first implementation hand-parsed `git diff -U0` output in bash by -matching line prefixes, and cold review demonstrated four separate defects in that one parser: the +WHY PYTHON AND NOT SHELL. Hand-parsing `git diff -U0` output in bash by matching line prefixes +produced four separate defects in that one parser: the `\\ No newline at end of file` marker was counted as content, an added line whose own text began `++ ` was eaten by the `+++ ` header arm, `core.quotePath` hid non-ASCII paths, and `read` dropped a final unterminated line. Those are four instances of one mistake — deciding what a diff line IS from @@ -54,7 +54,25 @@ except Exception: # noqa: S110 — a stdout that cannot be reconfigured is not # the 35 have more than one commit, so revisions do happen — which is precisely the case where the # rule's remedy (move it to the commit message) is still available. The exemption costs the only # reach the detector has and buys only quiet in a sweep a person runs deliberately. -EXEMPT_PREFIXES = ("docs/decisions/",) +# +# `scripts/tests/fixtures/` is exempt for the same reason one level down (#876): it holds COPIES of +# decision records and other test DATA, which carry whatever phrasing the test under them needs and +# are not an artifact anyone edits for a reader. Exempting it is also what keeps the depth +# measurement in the record true — its record copies sit at four to six slashes. +EXEMPT_PREFIXES = ("docs/decisions/", "scripts/tests/fixtures/") + +# The PROCESS corpus (#876): hooks, workflows, scripts and their tests, scanned regardless of +# extension because the artifacts there are shell, YAML, Python and jq, not Markdown. It is in the +# population on the #812 argument run forward — `--diff` sees only ADDED lines, and this is where +# narrative is being ADDED: 287 of the 453 sites the #876 sweep found outside the docs corpus were +# under 30 days old (measured 2026-09-03 at `fb5592971`), against a `docs/superpowers/**` that had +# not moved since 2026-07-23. `web/` and the C# projects are left out on the same measurement: 3 of +# the 74 PATTERNS-matching sites lived there, across roughly 4,600 tracked files. +PROCESS_PREFIXES = (".claude/", ".gitea/", ".husky/", "scripts/") + +# Exempt by NAME, not by prefix: this file and its test carry the phrasings as pattern and fixture, +# so they would be permanent hits — the false positive that makes an advisory check stop being read. +EXEMPT_FILES = ("scripts/check-doc-narrative.py", "scripts/tests/test_check_doc_narrative.py") # Session-narrative phrasings. Deliberately narrow: each is first person or names a revision of THIS # artifact. Broad words that also appear in legitimate dated history ("previously", "was wrong") are @@ -84,14 +102,19 @@ WARNING = ( def is_scanned_path(path: str) -> bool: - """The population: `docs/**/*.md` minus `docs/decisions/**`, plus root-level `*.md`. + """The population: `docs/**/*.md` minus `docs/decisions/**`, plus root-level `*.md`, plus every + tracked file under `PROCESS_PREFIXES` regardless of extension, minus `EXEMPT_FILES`. - Stated positively and in one place so the record's `mechanics:` can quote it exactly. Skills, - `web/`, and other nested markdown outside `docs/` are deliberately NOT in scope. + Stated positively and in one place so the record's `mechanics:` can quote it exactly. `web/`, + C# source, and nested markdown outside `docs/` and the process prefixes are deliberately NOT in + scope. This is a PATH predicate; `run_all` additionally restricts the population to tracked + regular files, because a symlink's content is its target, not the artifact. """ - if not path.endswith(".md"): + if path in EXEMPT_FILES or any(path.startswith(p) for p in EXEMPT_PREFIXES): return False - if any(path.startswith(p) for p in EXEMPT_PREFIXES): + if any(path.startswith(p) for p in PROCESS_PREFIXES): + return True + if not path.endswith(".md"): return False return path.startswith("docs/") or "/" not in path @@ -167,6 +190,11 @@ def added_lines(diff: str): # `path` should never name a file the added lines do not belong to. A # `--diff-filter=d` on the git call was removed rather than kept beside it: a second # mechanism nobody can witness failing is how a duplicate guard hides its twin. + # Git terminates the `+++` filename with a TAB when the path contains a space, and a + # path carrying that tab matches nothing in `is_scanned_path` — the file is dropped + # SILENTLY, the same scanned-0 channel the config pins above close. Witnessed by a + # positive control with a space in the name. + p = p.split("\t", 1)[0] path = None if p == "/dev/null" else (p[2:] if p.startswith("b/") else p) elif raw.startswith("+"): lineno += 1 @@ -212,14 +240,30 @@ def run_diff(base: str, out: list[str]) -> int: def run_all(out: list[str]) -> int: # Population from `git ls-files`, never a filesystem walk — an untracked scratch file is not - # part of the corpus (#778). - rc, listing = git("ls-files", "-z", "--", "*.md") + # part of the corpus (#778). The STAGE listing, because the population is tracked REGULAR files + # (mode 100644/100755): a tracked symlink (120000) is a path the predicate admits whose worktree + # content is its TARGET — a directory (`.claude/skills/jellyfin`, a cross-repo skill link) or a + # file that may sit outside the population — and a gitlink (160000) is a submodule pointer with + # no content of its own. `--diff` carries no such filter: a gitlink's diff content is a sha, and + # a symlink's is its target PATH, scanned like any other added line — a phrasing inside a path + # name would draw an advisory warning on the link, which is harmless. The stage listing emits + # one row PER STAGE for an unmerged path, so modes are gathered per path first: a path is opened + # once, and only when EVERY stage is a regular blob — in an add/add conflict between a symlink + # and a regular file, the worktree holds one of them and a per-row test would let the regular + # row authorise opening the other. + rc, listing = git("ls-files", "-s", "-z") if rc != 0: print("doc-narrative: could not list tracked files — SCANNED NOTHING.") return -1 + modes: dict[str, set[str]] = {} + for entry in listing.split("\0"): + if not entry: + continue + meta, _, path = entry.partition("\t") + modes.setdefault(path, set()).add(meta.split(" ", 1)[0]) scanned = 0 - for path in listing.split("\0"): - if not path or not is_scanned_path(path): + for path, path_modes in modes.items(): + if not all(m.startswith("100") for m in path_modes) or not is_scanned_path(path): continue try: with open(path, encoding="utf-8", errors="replace") as fh: diff --git a/scripts/check-required-contexts.sh b/scripts/check-required-contexts.sh index e29b9fdea..0163108e8 100755 --- a/scripts/check-required-contexts.sh +++ b/scripts/check-required-contexts.sh @@ -119,8 +119,8 @@ case $(printf '%s' "$verdict" | jq -r '.verdict // ""' 2>/dev/null || true) in # NOT given separate arms — because this script's contract publishes exactly five class words and # `unreadable` already means precisely "no comparison was made", which is true of both. # - # A separate `unreadable)` arm printing the same word was written first and then deleted: cold - # review measured it as a no-op (removing it left the suite green), and the merge hook's own + # A separate `unreadable)` arm printing the same word is a measured no-op (removing it + # left the suite green), and the merge hook's own # comment condemns exactly that — an arm no observation can distinguish is a comment with syntax. # The hook can afford two arms because it has two distinct REASON STRINGS to hand an operator; # here there is one output word, so a second arm would be decoration. diff --git a/scripts/check-review-verdict.sh b/scripts/check-review-verdict.sh index 1203d961a..ebb17bdad 100755 --- a/scripts/check-review-verdict.sh +++ b/scripts/check-review-verdict.sh @@ -127,8 +127,8 @@ comments=$(cat) # "convention not adopted" and downgrade a hard block into an ask. # # Each body is emitted as a JSON STRING on its own line (newlines escaped by JSON), so comment -# boundaries are carried out-of-band. An earlier version joined bodies with a literal sentinel line; -# a comment containing that sentinel could forge a boundary, reset fence state mid-body, and expose a +# boundaries are carried out-of-band. Joining bodies with a literal sentinel line instead would let +# a comment containing that sentinel forge a boundary, reset fence state mid-body, and expose a # verdict that was still inside an unclosed fence. In-band delimiters are forgeable by whoever writes # the data — and here that is anyone who can comment on the PR. # The shape is asserted IN jq so a payload that isn't an array of comment objects with STRING bodies @@ -189,7 +189,7 @@ verdicts=$(printf '%s\n' "$encoded" | while IFS= read -r encoded_body; do # A shorter or different marker while a fence is open is content, so it neither closes nor prints. outside=$(printf '%s\n' "$body" | awk ' { - # Raw HTML blocks are the third code-block form (#629 round 5): 
,  and HTML
+      # Raw HTML blocks are the third code-block form (#629): 
,  and HTML
       # comments all render their contents literally, so a verdict inside one is an example, not an
       # approval. Tracked as a simple depth/marker count rather than parsed — the direction of error
       # is to strip MORE, which can only ever withhold approval.
diff --git a/scripts/ci-prove-ban-detects.sh b/scripts/ci-prove-ban-detects.sh
index 57b557028..492cf6af1 100755
--- a/scripts/ci-prove-ban-detects.sh
+++ b/scripts/ci-prove-ban-detects.sh
@@ -2,8 +2,8 @@
 # Prove — at runtime, every run — that the delimiter ban actually DETECTS a delimiter (ersatztv#767).
 #
 # WHY THIS EXISTS AS A SHELL STEP RATHER THAN A TEST. The `scan` job's guarantee used to be a pytest
-# that asserted the ban command works. Review then disarmed the whole gate with ONE new file at the
-# repo root — a `pytest.ini` carrying `addopts = -k "not delimiter_banned"`, or a `conftest.py` with
+# that asserted the ban command works. DEMONSTRATED: ONE new file at the repo root disarms the whole gate — a
+# `pytest.ini` carrying `addopts = -k "not delimiter_banned"`, or a `conftest.py` with
 # `pytest_collection_modifyitems` — which deselects the ban test AND the tests guarding it, leaving
 # every job green while a delimiter sits in `build`'s `Smoke` body and the image publishes. That tier
 # sits above every `env:` a test can reconstruct, and above the tests themselves: anything living
@@ -11,8 +11,8 @@
 #
 # IT RUNS IN THE REAL CHECKOUT, NOT A COPY, and that is the whole point. An isolated copy does not
 # inherit the repo-root `pytest.ini`/`conftest.py`/`pyproject.toml` that a disarm would live in, so a
-# copy-based proof reports the ban healthy while the job's actual invocation is deselected — measured,
-# and it is why the first version of this script was wrong. Same cwd, same rootdir, same config and
+# copy-based proof reports the ban healthy while the job's actual invocation is
+# deselected — measured. Same cwd, same rootdir, same config and
 # the same BAN INVOCATION as the run being vouched for — not the same command line, since the
 # workflow step also runs the wiring tests and this runs only the ban file. Only the workflow file
 # differs, and only for a moment.
@@ -34,8 +34,8 @@
 # passing (the ban is not enforcing), pytest failing for a NON-test reason (collection error, nothing
 # collected — cannot prove anything), and pytest failing on some OTHER test while the ban test itself
 # was deselected. Only the ban test's `[build]` parametrisation failing counts as proof. Both weaker
-# readings were live bugs in earlier drafts of this file: "non-zero means it noticed" reported OK on a
-# collection error, and a later draft still fell through to OK when an unrelated test reddened.
+# readings have been live bugs here: "non-zero means it noticed" reported OK on a
+# collection error, and the other still fell through to OK when an unrelated test reddened.
 #
 # NOTE ON THE OPENER: this file must never contain the literal two-character expression opener, both
 # because `scan`'s own run bodies are asserted delimiter-free and because a file containing it is the
@@ -81,8 +81,8 @@ detected=$?
 set -e
 
 # THREE OUTCOMES, EXHAUSTIVELY, and only the last one is a pass. "Non-zero means it noticed" is not
-# good enough — that was this script's own first bug, and an earlier draft of this very block still
-# fell through to OK when pytest exited 1 for a DIFFERENT test's failure while the ban test was
+# good enough, and neither is "exit 1 means the ban test failed": both fall through to
+# OK when pytest exits 1 for a DIFFERENT test's failure while the ban test was
 # deselected. Requiring the exact expected failure is what makes this a proof rather than a liveness
 # check. (`[build]` because the ban is parametrised per job, and `build` is the one whose dropped
 # `Smoke` publishes an unsmoked image.)
diff --git a/scripts/ci-step-ran.sh b/scripts/ci-step-ran.sh
index 65cbaae6d..6a3663480 100755
--- a/scripts/ci-step-ran.sh
+++ b/scripts/ci-step-ran.sh
@@ -48,8 +48,8 @@
 # `review-verdict.yml`, which runs WITHOUT a `container:`. `test` and `migrations` run INSIDE the CI
 # toolchain image, so their `/tmp` is the job container's own and starts empty. That follows from
 # `container:`, NOT from a measurement: the build-lane probe confirmed only that `RUNNER_TEMP` is
-# `/tmp` here (the marker landed at `/tmp/etv-ci-steps-ran-test-1910-1`) — it says nothing about the
-# directory being private or empty, and an earlier draft of this comment cited it as though it did.
+# `/tmp` here (the marker landed at `/tmp/etv-ci-steps-ran-test-1910-1`) — it says nothing about
+# the directory being private or empty.
 # The fresh container is what actually rules out a stale marker here; the keying is defence in depth.
 #
 # It is kept because container-per-job is a property of how the lane is configured today, not a
@@ -74,8 +74,8 @@ EOF
     exit 2
 }
 
-# NO SILENT FALLBACK FOR THE RUN IDENTITY — found by cold review. The first version defaulted to
-# `nojob`/`norunid`/`1`, and those are REUSABLE: with `GITHUB_RUN_ID` unset, every run on the host
+# NO SILENT FALLBACK FOR THE RUN IDENTITY. Defaulting to `nojob`/`norunid`/`1` is
+# REUSABLE: with `GITHUB_RUN_ID` unset, every run on the host
 # would share ONE marker file, so a leftover from any earlier run would satisfy the guard on a run
 # whose step was dropped. A silent PASS — the exact failure the keying exists to remove, reintroduced
 # by the code meant to implement it.
@@ -95,8 +95,8 @@ EOF
 #     then simply read off run 1916: `Marker identity: job=test run=1916 attempt=1 (from the runner)`
 #     and the same for `migrations`. Both required jobs, on the lane that matters.
 #
-# That measurement is what promoted it from warn-and-default to REQUIRED, which is why the residual
-# this comment used to describe — a rerun inheriting attempt 1's markers — no longer exists FOR THE
+# That measurement is what promoted it from warn-and-default to REQUIRED, which is why the rerun
+# residual — a rerun inheriting attempt 1's markers — no longer exists FOR THE
 # CONTAINER JOBS. If a future runner stops exporting any of the three, every job reddens with a
 # message naming the variable; that is loud, instantly diagnosable, and the correct direction for a
 # required check.
@@ -117,8 +117,8 @@ marker_path() {
     if [ -n "$missing" ]; then
         # NOTHING IS PRINTED TO STDOUT HERE, and that is load-bearing rather than style: this
         # function's stdout IS its return value (it is always called inside `$( )`), so a notice
-        # printed here is captured INTO the path. An earlier revision did exactly that and both
-        # sub-commands then failed on a nonexistent directory. Caught by
+        # printed here is captured INTO the path. Printing one makes both
+        # sub-commands fail on a nonexistent directory. Pinned by
         # test_a_degraded_run_IDENTITY_*, which is why that test asserts on the exit status and on
         # the absence of any marker file rather than only on the message.
         echo "::error::ci-step-ran.sh cannot identify this run —${missing} not set. The marker path would fall back to a name other runs also use, and a stale marker would make the dropped-step guard PASS on a run whose step never executed (ersatztv#756). Refusing rather than degrading to a reusable name." >&2
@@ -200,7 +200,7 @@ cmd_assert() {
         echo "Skip gate fired (docs_only='${ETV_DOCS_ONLY:-}', already_validated='${ETV_REVALIDATE_SKIP:-}') — the gated steps were not expected to run."
     fi
 
-    # RE-CHECKED AFTER GATING, not only on argv — found by cold review, which reproduced it:
+    # RE-CHECKED AFTER GATING, not only on argv — reproduced:
     # `ETV_DOCS_ONLY=true … assert --always --gated foo` printed "All 0 expected step(s) executed"
     # and exited 0. The argv check above cannot see that, because the set is emptied by the gate, not
     # by the caller. Unreachable with today's argv (both jobs pass `--always detect revalidate`), but
diff --git a/scripts/ci-toolchain-image-resolves.sh b/scripts/ci-toolchain-image-resolves.sh
index 84b36be45..3b3c3e761 100755
--- a/scripts/ci-toolchain-image-resolves.sh
+++ b/scripts/ci-toolchain-image-resolves.sh
@@ -22,8 +22,8 @@
 # fail fast (1-2s) when the pull fails. This runs in PARALLEL: the diagnosis is present the moment
 # anyone looks, and the happy path pays nothing.
 #
-# UNKNOWN IS NOT A PASS, and this is where the first draft was wrong. It warned and exited 0 on
-# every answer that was not 200 or 404, which makes "curl is missing from this runner", "the
+# UNKNOWN IS NOT A PASS. Warning and exiting 0 on every answer that is not 200 or
+# 404 makes "curl is missing from this runner", "the
 # registry moved", and "DNS changed" all indistinguishable from a healthy pin — a job that is green
 # forever having checked nothing, in a file whose header claims the opposite. Unknown answers are
 # RETRIED (they are usually transient) and then FAIL. The message stays distinct from the deleted
diff --git a/scripts/decisions_validate.py b/scripts/decisions_validate.py
index bf775b679..cef2f16a6 100644
--- a/scripts/decisions_validate.py
+++ b/scripts/decisions_validate.py
@@ -58,7 +58,7 @@ RECORD_CEILING_DEFAULT = 60
 # it is cutting into the bulk rather than marking a tail. See `ceiling_calibration` for why the fine
 # percentile claim is reported instead of asserted.
 #
-# The floor is NOT "at least one record" — that was the first draft and it was nearly unfalsifiable:
+# The floor is NOT "at least one record" — that is nearly unfalsifiable:
 # measured on the live corpus it accepted every ceiling from 39 to 229, including the ceiling of 200
 # this module's own docstring offered as the case it catches (one 230-line record keeps the count
 # nonzero). A 2% floor rejects 200/229/230 and still leaves ~5x headroom below today's 9.8%.
@@ -441,10 +441,9 @@ def record_wing_files(records_dir: Path | None = None, archive_dir: Path | None
     `RECORDS_DIR.rglob` — so such a file IS a corpus source while being exempt from the guard.
 
     So the exemption is by exact RELATIVE PATH, never by basename. The only entry is
-    `archive/README.md`, a hand-written directory README that really does exist — an earlier
-    version of this function excluded any wing-root `README.md` "since no such file exists today",
-    which was simply false and would additionally have exempted a future `records/README.md`, i.e.
-    reintroduced the very hole one directory over.
+    `archive/README.md`, a hand-written directory README that really does exist — excluding any
+    wing-root `README.md` "since no such file exists today" is simply false, and would additionally
+    exempt a future `records/README.md`, i.e. reintroduce the very hole one directory over.
     """
     records_dir = dl.RECORDS_DIR if records_dir is None else records_dir
     archive_dir = dl.ARCHIVE_DIR if archive_dir is None else archive_dir
diff --git a/scripts/hook-fire-log.sh b/scripts/hook-fire-log.sh
index ebf5d36e2..0a649973d 100755
--- a/scripts/hook-fire-log.sh
+++ b/scripts/hook-fire-log.sh
@@ -92,8 +92,8 @@ etv_hook_fire_scrub() {
 # A STRICTER scrub for the one value that becomes a PATH. The record scrub above deliberately keeps
 # `/` and `.` — tool names like `mcp__gitea__x` and event paths read better with them — but those
 # are exactly the two characters that turn a session id into `../../escaped`. Passing a value
-# through a scrub is not the same as passing it through the RIGHT scrub, and the first version of
-# this fix reused the record scrubber and left the traversal wide open while reading as fixed.
+# through a scrub is not the same as passing it through the RIGHT scrub: reusing the record
+# scrubber here leaves the traversal wide open while reading as fixed.
 etv_hook_fire_scrub_component() {
   printf '%s' "${1:-}" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-120
 }
@@ -168,8 +168,8 @@ etv_hook_fire_classify() {
     fi
     [ -z "$d" ] && d=$(printf '%s' "$out" | sed -n 's/.*"decision"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
 
-    # A NON-CANONICAL VALUE IS RECORDED AS SUCH, not normalised into a valid one. An earlier version
-    # lowercased whatever it found, so `"permissionDecision":"Deny"` was filed as a clean `deny` —
+    # A NON-CANONICAL VALUE IS RECORDED AS SUCH, not normalised into a valid one. Lowercasing
+    # whatever is found files `"permissionDecision":"Deny"` as a clean `deny` —
     # manufacturing a decision the harness may never have honoured. The documented values are
     # lowercase; anything else is a hook bug, and the log should say so rather than launder it.
     case "$d" in
@@ -405,9 +405,8 @@ etv_hook_fire_flush() {
     # rescue path delivered 52 bytes where the hook wrote 53, and every JSON parser downstream
     # accepts the short form without complaint. Pinned by `test_stdout_is_replayed_BYTE_EXACT`.
     #
-    # NO `2>/dev/null` ON THE `exec` — see the stdin comment. An earlier version of THIS line had
-    # it, eight lines below the comment forbidding it, which is why the rule is now restated at
-    # every `exec` rather than once.
+    # NO `2>/dev/null` ON THE `exec` — see the stdin comment. The rule is restated at every `exec`
+    # rather than once because it has been violated eight lines below a single statement of it.
     if [ -r "${ETV_HOOK_FIRE_STDOUT_TMP:-}" ]; then
       # Common path: stream the FILE straight through. A shell variable cannot hold a NUL byte, so
       # replaying via `$(...)` silently drops them and warns on stderr; `cat` is byte-exact for any
diff --git a/scripts/jq-preflight.sh b/scripts/jq-preflight.sh
index 5b3751828..ea5e24428 100755
--- a/scripts/jq-preflight.sh
+++ b/scripts/jq-preflight.sh
@@ -109,18 +109,18 @@ fi
 # warning line or a date prefix as the version — `2026.07.26 jq-1.6` parsed as 2026.07, which sails
 # over the floor. Anchoring keeps every legitimate form (`jq-1.6`, `jq version 1.6`, `jq-1.7.1`,
 # `jq-1.6-dirty`, `jq-1.6 (Debian 1.6-2.1)`) and rejects the rest, which then fails closed below.
-# FIRST LINE ONLY, and bounded everywhere. Both bounds are load-bearing; this is the third round on
-# this one predicate and each previous version failed for a variant of the same reason.
+# FIRST LINE ONLY, and bounded everywhere. Both bounds are load-bearing; this is the third narrowing of
+# this one predicate and each earlier narrowing failed for a variant of the same reason.
 #
 #   * First line only. `[[:space:]]` matches NEWLINES, so an "anchored" pattern still scanned the
 #     whole output: `jq\n2.34: cannot load` matched `jq`, crossed the newline as separator, and
-#     parsed 2.34 — fail-open, the round-2 bug narrowed but not closed. `[[:blank:]]` (space/tab
+#     parsed 2.34 — the fail-open narrowed but not closed. `[[:blank:]]` (space/tab
 #     only) plus a first-line slice confines the match to the line that can actually carry a version.
-#   * Bounded digit runs. This is the round-1 mechanism resurrected. The regex guaranteed the
+#   * Bounded digit runs. This is the original fail-open mechanism resurrected. The regex guaranteed the
 #     operands were digits but not that they fit in `test`'s integer range, so a 23-digit major made
 #     `[ "$major" -lt "$min_major" ]` error with "integer expression expected" — and `set -e` exempts
 #     a failing command in an `if` condition, so the conditional read false and THE FLOOR WAS NEVER
-#     ASSERTED, exit 0. Exactly what the empty-string case did in round 1. `{1,9}` keeps every
+#     ASSERTED, exit 0. Exactly what the empty-string case did before the bound. `{1,9}` keeps every
 #     operand inside a 32-bit integer, so the comparison can no longer error.
 #   * Bounded separator runs, so the pattern cannot be walked across arbitrary filler.
 first=${raw%%$'\n'*}
diff --git a/scripts/lib/branch-rule-classifier.jq b/scripts/lib/branch-rule-classifier.jq
index 796194669..d5f5c80fd 100644
--- a/scripts/lib/branch-rule-classifier.jq
+++ b/scripts/lib/branch-rule-classifier.jq
@@ -75,15 +75,15 @@
     # order is right — precedent for a style is not evidence the behaviour is correct, and this chain
     # was wrong about everything else on this line. If a server ever sends two different non-empty
     # names, decide then, with the payload in hand.
-    # THREE outcomes per field, not two, and collapsing the last two is a regression cold review
-    # caught in the first draft of this fix. A field either supplies a NAME, or SKIPs (it is simply
+    # THREE outcomes per field, not two, and collapsing the last two is a REGRESSION.
+    # A field either supplies a NAME, or SKIPs (it is simply
     # not carrying one: absent, null, or the empty string Gitea sends for a glob rule), or POISONs
     # (it is PRESENT holding a type a name cannot have).
     #
-    # The first draft fell through to `rule_name` on anything that was not a usable string, which
-    # made a malformed field indistinguishable from an unsupplied one. Measured: with `branch_name`
+    # Falling through to `rule_name` on anything that was not a usable string
+    # makes a malformed field indistinguishable from an unsupplied one. Measured: with `branch_name`
     # a number, boolean or array beside `rule_name:"main"`, the predecessor THREW and the gate asked,
-    # while that draft answered `exact` and AUTO-GRANTED — and with `rule_name:"develop"` it answered
+    # while that fallback answered `exact` and AUTO-GRANTED — and with `rule_name:"develop"` it answered
     # `none`, denying on "the full rule list was read and none matches" about a field it never read.
     # Both directions of the very defect this file is fixing, reintroduced one shape over.
     #
@@ -94,8 +94,8 @@
                        elif $v == null then {skip: true}
                        else {poison: true} end;
     # POISON IS CHECKED ON BOTH FIELDS BEFORE EITHER NAME IS TAKEN, so the invariant above holds
-    # field-agnostically. The first draft short-circuited on `branch_name` and only consulted
-    # `rule_name` as a fallback, which made the rule order-dependent: `{"branch_name":42,
+    # field-agnostically. Short-circuiting on `branch_name` and only consulting
+    # `rule_name` as a fallback makes the rule order-dependent: `{"branch_name":42,
     # "rule_name":"main"}` poisoned, while `{"branch_name":"main","rule_name":42}` answered `exact`
     # off the good field and never looked at the malformed one. Gitea 1.27.1 does not send that
     # second shape — a plain rule sets both fields equal, a glob rule sets `branch_name` to `""` —
diff --git a/scripts/lib/h10-reviewers.sh b/scripts/lib/h10-reviewers.sh
index d35639d55..683c60b02 100644
--- a/scripts/lib/h10-reviewers.sh
+++ b/scripts/lib/h10-reviewers.sh
@@ -98,8 +98,8 @@ unset _etv_h10_root
 # Reset to 0 HERE, at load time, so that "derived successfully" is a DATA dependency the query
 # function requires rather than a control-flow step a caller is trusted to have taken.
 #
-# ATTRIBUTED CAREFULLY, because the obvious second reason is not this line's. An earlier version
-# claimed the reset defeats an inherited `ETV_H10_REVIEWERS_OK=1` from the environment, and cited a
+# ATTRIBUTED CAREFULLY, because the obvious second reason is not this line's. That reason is that
+# the reset defeats an inherited `ETV_H10_REVIEWERS_OK=1` from the environment, backed by a
 # measurement showing a hostile environment does not get a verdict past the writer. The measurement
 # is real; the conclusion does not follow. Removing this reset produces a byte-identical refusal,
 # because `etv_h10_reviewers_load` runs on that path and overwrites both variables anyway. What the
diff --git a/scripts/lib/review-verdict-vocabulary.sh b/scripts/lib/review-verdict-vocabulary.sh
index dc12aa2d0..a5a081130 100644
--- a/scripts/lib/review-verdict-vocabulary.sh
+++ b/scripts/lib/review-verdict-vocabulary.sh
@@ -12,8 +12,8 @@
 # still denies — an unexplained deny on a gate whose whole job is to be explicable.
 #
 # WHY IT IS NOT A TEST. ersatztv#774 tried to hold the two copies together with a parity test that
-# extracted both vocabularies from their own shell source with regexes and compared them. Six cold
-# review rounds each found another shell construction that either escaped the extractor (`SHIP*)`, a
+# extracted both vocabularies from their own shell source with regexes and compared them. Six
+# successive fixes each met another shell construction that either escaped the extractor (`SHIP*)`, a
 # glob in the arm label; an unquoted `SHIP-IT) state=success`) or reddened it on a correct tree (a
 # `) state=` inside a heredoc; a column-zero `esac` in a string truncating the scoped match).
 # Each fix was locally correct and the sequence converged on nothing, because a regex over shell
diff --git a/scripts/mcp_smoke.py b/scripts/mcp_smoke.py
index 6c4913be8..185ab2d9f 100644
--- a/scripts/mcp_smoke.py
+++ b/scripts/mcp_smoke.py
@@ -3,9 +3,9 @@
 
 Written because the caller's original check only asked `[ -x command ]`, which a
 DIRECTORY satisfies (`[ -x /bin ]` is true), so it could report a pass for a server
-that cannot run. Review then found the first version of THIS file had the same
-weakness one level in: it accepted any response carrying the right id, so a server
-that was not the configured one — or that answered with a malformed body — passed.
+that cannot run. The same weakness recurs one level in: accepting any response
+carrying the right id passes a server that was not the configured one — or that
+answered with a malformed body.
 Hence the shape and identity checks below: "it answered" is not "it answered
 correctly", and a smoke test that cannot tell them apart is decoration.
 
@@ -22,13 +22,13 @@ deliberately share a stage code, so read the message, not the number.
 
 ACCEPTED LIMIT: a server that writes a gigabyte with no newline can still exhaust
 memory before the timeout fires. Guarding that needs the very frame-capping reader
-whose caps were themselves a defect in an earlier round, and the input here is our OWN
+whose caps are themselves the defect described below, and the input here is our OWN
 configured server on a developer machine — not an adversary. Stated rather than
 silently unhandled.
 
-Deliberately NOT bounded by message/line caps. A first attempt added them and
-they were the defect: an over-long line had its suffix re-parsed as a fresh
-message (a false green), and a cap reached before the awaited reply reported
+Deliberately NOT bounded by message/line caps — adding them IS the defect: an
+over-long line has its suffix re-parsed as a fresh message (a false green), and
+a cap reached before the awaited reply reports
 "server did not start". What IS bounded is the set of retained DECODED responses
 — only a reply to the request in flight is kept, notifications are dropped as
 they arrive — and wall-clock, via the caller's timeout. The raw line buffer is
@@ -225,7 +225,7 @@ def main() -> int:
         # `dotnet run` execs a CHILD (csharp-lsp-mcp), so the leader exiting on
         # SIGTERM says nothing about the descendant. Always follow up with SIGKILL to
         # the saved group: a stale server surviving a probe is exactly the litter
-        # this session found at start-up.
+        # observed accumulating at start-up.
         if pgid is not None:
             for sig in (signal.SIGTERM, signal.SIGKILL):
                 try:
diff --git a/scripts/post-review-verdict.sh b/scripts/post-review-verdict.sh
index e2a0a5af5..04b502ee5 100755
--- a/scripts/post-review-verdict.sh
+++ b/scripts/post-review-verdict.sh
@@ -280,8 +280,8 @@ printf 'posted status:  %s = %s on %s\n' "$STATUS_CONTEXT" "$state" "$short"
 # itself on the next PR event. It is not repaired here on purpose: a second corrective write is the
 # sticky-sentinel mechanism ersatztv#849 is separately designing, and inventing a parallel one on
 # this path would be two mechanisms for one invariant.
-# WHY OUR ROW IS ALWAYS IN THIS RESPONSE — measured, and the first version of this comment had it
-# wrong in a way worth recording. This endpoint PAGES, and its `total_count` reports the PAGE rather
+# WHY OUR ROW IS ALWAYS IN THIS RESPONSE — measured, and the INTUITIVE reading is wrong in a way
+# worth recording. This endpoint PAGES, and its `total_count` reports the PAGE rather
 # than the total (`?limit=2` on a 15-context head returns 2 rows and `total_count: 2`), so a
 # truncated body is not detectable from any field in it. That looked like a risk of the verdict row
 # falling off a page. It is not: Gitea selects the MAX id per context, orders those DESCENDING, and
@@ -311,10 +311,10 @@ status_readback=$(api_get "repos/$owner/$repo/commits/$sha/status?limit=100") \
 # the array TYPE is tested rather than assumed; a body that merely lost its array yields no entry
 # and is refused below, exactly like one that carries no verdict.
 # Three outcomes are kept apart below, each with its own message, because they call for different
-# actions and an earlier draft collapsed them into one: a body whose `.statuses` is not an array at
+# actions: a body whose `.statuses` is not an array at
 # all, a well-formed body that does not carry our context, and a body carrying MORE THAN ONE row for
-# it. Collapsing them also made the array-TYPE test unwitnessable — the absent-entry check caught
-# every case on its own, so disarming the type test left the suite green.
+# it. Collapsing them also makes the array-TYPE test unwitnessable — the absent-entry check catches
+# every case on its own, so disarming the type test leaves the suite green.
 readback_matches=$(printf '%s' "$status_readback" | jq -c --arg c "$STATUS_CONTEXT" \
   'if (.statuses | type) == "array" then (.statuses | map(select(.context == $c))) else null end') \
   || die "the '$STATUS_CONTEXT' status was posted on $short, but the read-back body could not be parsed — no comment was written."
@@ -340,8 +340,8 @@ esac
 if [ "$readback_count" = 0 ]; then
   # Does NOT assert a single cause. Reaching here means the row this run just POSTed is absent from
   # a response that, by the ordering measured above, should have it FIRST — so the honest statement
-  # is that something removed or replaced it, not a guess at which. Paging is deliberately not named:
-  # an earlier version named it, and it is not a live candidate for THIS row.
+  # is that something removed or replaced it, not a guess at which. Paging is deliberately not
+  # named: it is not a live candidate for THIS row.
   #
   # `.statuses` is known to be an array here (the branch above refused otherwise), so `length` cannot
   # fail and needs no fallback. The `|| readback_rows=...` guard that used to be here was dead for a
diff --git a/scripts/pr-changed-files.sh b/scripts/pr-changed-files.sh
index 0dc612d97..f984ff152 100755
--- a/scripts/pr-changed-files.sh
+++ b/scripts/pr-changed-files.sh
@@ -213,9 +213,9 @@ while [ "$page" -le "$MAX_PAGES" ]; do
   #   is rejecting rows whose vocabulary we do not recognise — where a source path may be absent, or
   #   carried in some other field we are not reading. Without it, `"Renamed"` with a capital R, or an
   #   absent status, silently takes the `else true` branch of the clause below and skips the
-  #   "renamed rows MUST carry previous_filename" requirement entirely. (An earlier version of this
-  #   comment claimed the source path would be "dropped", which is not the mechanism; a maintainer
-  #   who tested that claim would find it false and might conclude the check is redundant.)
+  #   "renamed rows MUST carry previous_filename" requirement entirely. The source path is NOT
+  #   "dropped" — that is not the mechanism, and a maintainer who tested that claim would find it
+  #   false and might conclude the check is redundant.
   #   `modified` is accepted alongside `changed` deliberately. Live Gitea emits `changed`; a re-derivation
   #   on 1.27.1 (2026-08-28, ersatztv#747) over the file rows of the 200 most recently updated PRs saw
   #   `changed`, `added`, `renamed` and `deleted` — all four already in the list below. `copied` and
diff --git a/scripts/prove-fix.sh b/scripts/prove-fix.sh
index 5106e2a24..9acd22da9 100755
--- a/scripts/prove-fix.sh
+++ b/scripts/prove-fix.sh
@@ -3,8 +3,8 @@
 #
 # THE RULE THIS ENFORCES. `testing.guard-ships-with-mutation-proof` says a guard is not
 # tested because a test involving it passes; it ships with a proof it can fail. The same
-# argument applies to every bug fix, and nothing enforced it. #776 and #793 each took six
-# review rounds, and in both the recurring mechanism was one thing: a fix's test was
+# argument applies to every bug fix, and nothing enforced it. In #776 and #793 the
+# recurring mechanism was one thing: a fix's test was
 # written to confirm the fix, not to discriminate against its absence.
 #
 # HOW. Run the named tests at the commit (CONTROL — must be GREEN), then again in a
@@ -14,8 +14,8 @@
 #
 # ONLY pytest exit 1 COUNTS AS RED, and that is the whole safety argument. "Non-zero" is
 # not "the test failed": 2 is an interrupted collection, 3 an internal error, 4 a usage
-# error, 5 nothing collected, and a killed run gives 143. Cold review measured a SIGTERM
-# being read as red in an early DRAFT — cancellation masquerading as evidence. On the first
+# error, 5 nothing collected, and a killed run gives 143. A SIGTERM read as red was
+# measured in an early DRAFT — cancellation masquerading as evidence. On the first
 # COMMITTED version the reproducible false PROVEN is the marker case (a failed `cd` giving
 # the subshell status 1), not the signal one; see the decision record.
 # `--continue-on-collection-errors` is passed so a genuine collection failure
@@ -56,9 +56,9 @@ SELECTOR="${2:-}"
 
 TMP=""
 TMP_ENUM=""
-# ONE cleanup, ONE EXIT trap. An earlier version installed a SECOND `trap ... EXIT` later in
-# the script to remove TMP_ENUM; `on_signal` then ran `trap - EXIT`, disarming it, so a
-# signalled run leaked that directory. Folding both removals in here removes the ordering
+# ONE cleanup, ONE EXIT trap. A SECOND `trap ... EXIT` installed later in
+# the script to remove TMP_ENUM does not survive: `on_signal` runs `trap - EXIT`, disarming it,
+# so a signalled run leaks that directory. Folding both removals in here removes the ordering
 # subtlety rather than adding a third trap to compensate for it.
 cleanup() {
   if [ -n "$TMP" ]; then
@@ -199,7 +199,7 @@ mkdir -p "$TMP/tmp-control" "$TMP/tmp-reverted" || die "could not create phase t
 # PYTEST_RC IS READ FROM A MARKER, NOT FROM THE SUBSHELL. `( cd X && pytest ) ; rc=$?`
 # returns the SUBSHELL's status, and a failed `cd` or a failed redirection also yields 1 —
 # which the "only exit 1 is red" rule would then accept as a witnessed test failure with
-# pytest never having run. Cold review found exactly that. The marker file is written only
+# pytest never having run. The marker file is written only
 # after pytest RETURNS, so its absence means "pytest did not complete" and can never be
 # mistaken for a verdict.
 PYTEST_RC=""
diff --git a/scripts/tests/conftest.py b/scripts/tests/conftest.py
index 2c58ef3e2..00d95fd1b 100644
--- a/scripts/tests/conftest.py
+++ b/scripts/tests/conftest.py
@@ -88,8 +88,7 @@ def pytest_configure(config):
     the group this layer cannot help with and the reason there is a second one.
 
     INSTRUMENT `Popen` ONLY. `subprocess.run`, `call` and `check_output` all reach `Popen`, so
-    wrapping `run` as well counts every launch twice and doubles every figure — which is how the
-    first version of this measurement was wrong.
+    wrapping `run` as well counts every launch twice and doubles every figure.
     """
     global _SESSION_LOG_DIR
     _SESSION_LOG_DIR = tempfile.mkdtemp(prefix="etv-hook-fire-session-")
diff --git a/scripts/tests/hook_fire_isolation.py b/scripts/tests/hook_fire_isolation.py
index 536b9bc99..b98711924 100644
--- a/scripts/tests/hook_fire_isolation.py
+++ b/scripts/tests/hook_fire_isolation.py
@@ -69,19 +69,19 @@ def _anchored(path: Path, cwd) -> str:
     """Absolute realpath, resolving a RELATIVE value against the CHILD's working directory.
 
     `Popen(cwd=...)` changes the directory the child resolves a relative `ETV_HOOK_FIRE_LOG_DIR`
-    against, so anchoring at the parent's cwd models the wrong process. Cross-family review found
-    that as a live bypass: `ETV_HOOK_FIRE_LOG_DIR=.cache/ersatztv/hook-fire` with `cwd=$HOME` lands
+    against, so anchoring at the parent's cwd models the wrong process. That is a LIVE BYPASS:
+    `ETV_HOOK_FIRE_LOG_DIR=.cache/ersatztv/hook-fire` with `cwd=$HOME` lands
     exactly on the shared log while a parent-anchored check sees an unrelated path under the repo
     and clears it.
 
     THREE cwd shapes, not four. `Popen` accepts str, bytes and `PathLike`; it calls `os.fsencode`,
     which rejects an int, so a file DESCRIPTOR is not a launch shape and needs no handling here —
     measured on CPython 3.9 and 3.13, and pinned by
-    `test_the_guard_JUDGES_every_cwd_SHAPE_that_Popen_ACCEPTS`. A previous version of this added a
-    branch for the int case; the branch was DEAD, because `os.fspath` already raises `TypeError` on
+    `test_the_guard_JUDGES_every_cwd_SHAPE_that_Popen_ACCEPTS`. A branch for the int case is DEAD
+    code, because `os.fspath` already raises `TypeError` on
     an int, and deleting it left that branch's own test green. `os.fsdecode(os.fspath(...))`
-    normalises the three shapes that do exist, which is what the FIRST version got wrong — it called
-    `os.fspath` alone, and `os.path.join` then raised on mixing str with bytes.
+    normalises the three shapes that do exist; `os.fspath` alone leaves
+    `os.path.join` raising on mixing str with bytes.
 
     realpath, not `==`: `/tmp` is `/private/tmp` on macOS and `$HOME` may itself be a symlink.
     """
@@ -100,7 +100,7 @@ def _decoded(env: Mapping) -> dict[str, str]:
     launch is rejected as carrying no isolated dir — a false positive on a correctly isolated
     child — while a bytes VALUE makes `Path(...)` raise `TypeError`. Both are the "red on a
     legitimate launch" failure ersatztv#809 explicitly forbids, and they are the same shape as the
-    bytes-`cwd` regression an earlier round shipped.
+    bytes-`cwd` regression `_anchored` records.
 
     Done here rather than at each lookup so there is one place that knows about the two encodings,
     and no later reader has to remember which call sites handle which.
@@ -196,9 +196,9 @@ class ProductionLogGuard:
     volumes are case-insensitive, so `$HOME/.cache/ErsatzTV/hook-fire` is the same directory as
     `$HOME/.cache/ersatztv/hook-fire` and is cleared. Left as a note rather than fixed with an
     inode comparison, deliberately: nothing spells it that way, the likeliest wrong value — the
-    sink's own default transliterated — matches case exactly, and this change has already had two
-    consecutive review rounds whose finding was created by the previous round's fix, which is this
-    corpus's stated trigger for subtracting a layer rather than adding one.
+    sink's own default transliterated — matches case exactly, and two consecutive fixes here have
+    each created the next finding, which is this corpus's stated trigger for subtracting a layer
+    rather than adding one.
     """
 
     def __init__(self) -> None:
diff --git a/scripts/tests/mutation_harness_lib.py b/scripts/tests/mutation_harness_lib.py
index 94d842225..4b6c06f66 100644
--- a/scripts/tests/mutation_harness_lib.py
+++ b/scripts/tests/mutation_harness_lib.py
@@ -128,8 +128,8 @@ def _clean_env(**extra: str) -> dict[str, str]:
     stay out of. A git hook exports several of them, and this suite runs from one.
 
     So this is a DENY-BY-DEFAULT boundary rather than a list of the variables anyone has thought of:
-    every `GIT_*` is dropped and only the identity this module sets itself is put back. Enumerating
-    the dangerous ones is how the first version of this function shipped covering three of them.
+    every `GIT_*` is dropped and only the identity this module sets itself is put back. An enumeration
+    of the dangerous ones shipped here once, covering three of them — a list is what this replaces.
     """
     env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
     env.update(extra)
diff --git a/scripts/tests/mutation_manifest.py b/scripts/tests/mutation_manifest.py
index ddca1a457..29c3a80c6 100644
--- a/scripts/tests/mutation_manifest.py
+++ b/scripts/tests/mutation_manifest.py
@@ -135,8 +135,8 @@ MUTATIONS: tuple[Mutation, ...] = (
         "`drift` on an added context, the mutant reports `match` — a permanent no-op that would "
         "confirm the snapshot fresh forever. The proof asserts the mutant's EXACT verdict "
         "`(0, 'match')` rather than merely 'not drift', and ships a positive control for its own "
-        "tmp layout: an earlier draft copied the script without the classifier it loads beside "
-        "itself, so the mutant exited 2 with empty stdout and 'not drift' was satisfied by a copy "
+        "tmp layout: a copy of the script without the classifier it loads beside "
+        "itself exits 2 with empty stdout, and 'not drift' is then satisfied by a copy "
         "that never ran. The clause string is the one the proof test asserts on before mutating.",
     ),
     Mutation(
@@ -205,7 +205,7 @@ MUTATIONS: tuple[Mutation, ...] = (
         "The clause is the exact defect this guard was written after: `derived_guard_files` read "
         "its CALLERS from the index and then admitted the paths they name on `Path.exists()`, so a "
         "tracked workflow naming a script that exists on one machine only entered the population "
-        "there, red on that checkout and green in CI (#778's third shape, found by cold review "
+        "there, red on that checkout and green in CI (#778's third shape, "
         "inside #806 itself). Note what this mutation does NOT do: on a clean tree the mutated set "
         "is identical, so `test_guard_inventory.py`'s own assertions stay green — only narrowing "
         "the index, which is what the proof does, separates them. That is why the proof has to "
@@ -382,7 +382,7 @@ MUTATIONS: tuple[Mutation, ...] = (
         "be disarmed in it directly (`testing.verification-code-needs-its-own-proof`). The clause is "
         "the unguessable request id, which AT THE `initialize` STAGE is the only thing refusing a "
         "server that answers before it is asked: the pending-registration cannot help there, because "
-        "that id is already in flight when the pre-answer arrives, which is why #793 round 5 replaced "
+        "that id is already in flight when the pre-answer arrives, which is why #793 replaced "
         "the lock rather than tightening it. Disarmed, the stub's pre-answer is "
         "accepted at `initialize` and the run dies one stage later at `tools/list`, so the proof "
         "asserts the STAGE (rc 9 and the initialize diagnostic) rather than mere failure: the mutant "
@@ -406,7 +406,7 @@ MUTATIONS: tuple[Mutation, ...] = (
         expect="this file says COVERED, the SPA guard says CREATE",
         why="This guard IS a test, so disarming it makes it absent rather than red — the checker-guard "
         "exception applies and the mutation goes into the guarded ARTIFACT, the SPA guard's disposition "
-        "table. The VALUE is the clause: cold review demonstrated that flipping this row from ANNOTATED "
+        "table. The VALUE is the clause: flipping this row from ANNOTATED "
         "to CREATE retires the requirement that MultiCollectionItemRequest be annotated, so deleting the "
         "Complete<...> from MultiCollectionsScreen.toItemRequest then leaves every suite green with "
         "#807's silent weight reset live again. The row is named in full rather than by the bare "
@@ -442,7 +442,7 @@ MUTATIONS: tuple[Mutation, ...] = (
         "the defect itself rather than a caricature of it — ersatztv#883 put a vitest run back into "
         "a gitless stage, and every image build failed from that commit until #887. WHAT THIS PROVES "
         "IS NARROWER THAN IT LOOKS, and saying so is the point: the guard no longer decides whether "
-        "a command RUNS the suite (that predicate was wrong nine times across three review rounds), "
+        "a command RUNS the suite (that predicate was wrong nine times), "
         "it compares the stage's commands against a pin. So this mutation proves the pin is "
         "compared and reported — not that any particular spelling is recognised, because none needs "
         "to be. The mutant is deliberately the UNFILTERED spelling: the filtered one is what broke, "
@@ -472,8 +472,8 @@ MUTATIONS: tuple[Mutation, ...] = (
 # test is THE proof, which is #775's scope; this file can only verify one afterwards.
 
 UNDECLARED: dict[str, str] = {
-    # NO GROUPING. An earlier version sorted these into "driven through their deciding path" and
-    # "not driven at all", and the sort was wrong twice in successive review rounds — in both
+    # NO GROUPING. Sorting these into "driven through their deciding path" and
+    # "not driven at all" was wrong twice — in both
     # directions, over entries whose own text said the opposite. A category above a list is a second
     # classification of the same facts, and it drifts the moment one entry's situation changes. Each
     # entry states its own case instead.
diff --git a/scripts/tests/test_build_catalog_check_path.py b/scripts/tests/test_build_catalog_check_path.py
index 8a0ae5fde..8c803f599 100644
--- a/scripts/tests/test_build_catalog_check_path.py
+++ b/scripts/tests/test_build_catalog_check_path.py
@@ -147,10 +147,10 @@ def _active_runs(workflow: Path | None = None) -> list[str]:
     Parsed with `yaml.safe_load`, and returned WHOLE — not split into lines. Both choices are
     scar tissue.
 
-    Text-scanning for `run:` was round one, and cold review broke it three ways: a `run: |` block
+    Text-scanning for `run:` was round one, and it broke three ways: a `run: |` block
     scalar was invisible; a job or step switched off still read as wired; and `run:` inside
     block-scalar *text* was extracted and executed. Round two parsed the YAML and matched a LINE
-    beginning with `PYTHONPATH=.` — and review broke that too, with a heredoc:
+    beginning with `PYTHONPATH=.` — and that broke too, with a heredoc:
 
         run: |
           cat <<'EOF' > /dev/null
@@ -381,7 +381,7 @@ _STEP = (
 def test_a_guard_that_stopped_RUNNING_is_DETECTED(tmp_path, label, mutate):
     """Eight ways the catalog guard can stop gating, each of which must be caught.
 
-    Commenting out is one of them and was the only one the first version detected. The last two
+    Commenting out is one of them, and the only one a text scan detects. The last two
     leave the command in the file, parseable and even matchable — as `echo` argument and as heredoc
     data — which is why the proof executes the step's whole script instead of a line lifted out of it.
     """
diff --git a/scripts/tests/test_check_doc_narrative.py b/scripts/tests/test_check_doc_narrative.py
index 03b23a1e6..2ffb73748 100644
--- a/scripts/tests/test_check_doc_narrative.py
+++ b/scripts/tests/test_check_doc_narrative.py
@@ -1,6 +1,6 @@
 """Proofs for `scripts/check-doc-narrative.py` (ersatztv#784).
 
-Every case below is a defect a cold review DEMONSTRATED in the first, shell implementation. They are
+Every case below is a defect DEMONSTRATED in the first, shell implementation. They are
 here because the never-fails invariant and the reported line numbers are both asserted in prose in
 four places (the script header, the workflow comment, `docs/guard-inventory.md` and
 `docs/remote-state-inventory.md`), and an invariant asserted only in prose is the shape this repo
@@ -266,6 +266,8 @@ def test_a_RENAME_does_not_re_flag_the_whole_pre_existing_file(repo: Path) -> No
 # what stops a new prefix from shipping without a case here.
 EXEMPT_SAMPLES = {
     "docs/decisions/": ("docs/decisions/records/x/y.md", "docs/decisions/archive/x/y.md"),
+    # test DATA under a process prefix (#876): a decision-record copy and a shell fixture
+    "scripts/tests/fixtures/": ("scripts/tests/fixtures/premigration/decisions.md", "scripts/tests/fixtures/x/y.sh"),
 }
 
 
@@ -281,7 +283,7 @@ def test_every_exempt_genre_is_exempt_in_BOTH_modes(repo: Path, mode: str) -> No
     Each exempt sample is also paired with a MINIMAL TWIN — the same path with the exempt directory
     renamed — which raises the cost of a structural bypass but does NOT close it. Stated as a limit
     rather than a guarantee, because three successive attempts to close it were each defeated by the
-    next round: a lone depth-1 control fell to a depth-1 population rule; a depth-3 control fell to a
+    next: a lone depth-1 control fell to a depth-1 population rule; a depth-3 control fell to a
     `count("/") <= 3` cap; the twins themselves fell to a directory-NAME rule keyed on the renamed
     SECOND segment (`path.count("/") > 1 and "-" not in path.split("/", 2)[1]`), which skipped both
     samples and kept both twins. It reddens here now, but only because the `docs/superpowers/`
@@ -325,27 +327,36 @@ def test_the_population_agrees_with_an_INDEPENDENT_RESTATEMENT_over_the_REAL_cor
     "unprovable".
 
     The rule as the record states it — `docs/**/*.md` minus `docs/decisions/**`, plus root-level
-    `*.md` — is restated below over path SEGMENTS rather than string prefixes, so the two are not
-    one expression copy-pasted, then compared against `is_scanned_path` on every tracked Markdown
-    path in this repo. A finite fixture can only witness the shapes someone thought to write down;
+    `*.md`, plus every file under the four process directories minus the detector and its test
+    (#876) — is restated below over path SEGMENTS rather than string prefixes, so the two are not
+    one expression copy-pasted, then compared against `is_scanned_path` on every tracked path in
+    this repo. A finite fixture can only witness the shapes someone thought to write down;
     this witnesses every real path, so any population change that alters a verdict on one of them
     reddens — the depth-1 rule and the directory-NAME rule among them.
 
     It is NOT sufficient on its own, and the arm below says why with the measurement: a
-    `count("/") <= 3` cap changes no real path's verdict today, so within this test only the
-    synthetic arm catches it. Do not trim that arm as belt-and-braces; it is the half that sees a
+    `count("/") <= 3` cap changes no real path's verdict (re-measured 2026-09-03 after #876 grew the
+    population: 179 files, none deeper than three slashes — and only because `scripts/tests/fixtures/`
+    is exempt, whose record copies sit at four to six), so within this test only the synthetic arm
+    catches it. Do not trim that arm as belt-and-braces; it is the half that sees a
     rule the corpus has no instance of yet. (The exemption test above happens to redden on that cap
     too — its two minimal twins sit at four slashes — but that is incidental, not the arm carrying the claim.)
     """
 
     def restated(path: str) -> bool:
         parts = path.split("/")
+        if parts in (["scripts", "check-doc-narrative.py"], ["scripts", "tests", "test_check_doc_narrative.py"]):
+            return False  # the detector and its test: exempt by NAME, their fixtures ARE the phrasings
+        if parts[:3] == ["scripts", "tests", "fixtures"] and len(parts) > 3:
+            return False  # test DATA, including decision-record copies (#876)
+        if len(parts) > 1 and parts[0] in {".claude", ".gitea", ".husky", "scripts"}:
+            return True  # the process corpus, any extension (#876)
         if not parts[-1].endswith(".md"):
             return False
         if len(parts) == 1:
             return True  # root-level *.md
         if parts[0] != "docs":
-            return False  # nested markdown outside docs/ is out of scope
+            return False  # nested markdown outside docs/ and the process corpus is out of scope
         return parts[1] != "decisions"  # docs/** minus docs/decisions/**
 
     spec = importlib.util.spec_from_file_location("_cdn_pop", SCRIPT)
@@ -353,29 +364,64 @@ def test_the_population_agrees_with_an_INDEPENDENT_RESTATEMENT_over_the_REAL_cor
     mod = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(mod)
 
-    rc = subprocess.run(["git", "ls-files", "-z", "--", "*.md"], cwd=REPO, capture_output=True, text=True, check=True)
-    paths = [p for p in rc.stdout.split("\0") if p]
-    assert len(paths) > 100, f"corpus looks wrong: {len(paths)} paths"
+    rc = subprocess.run(["git", "ls-files", "-s", "-z"], cwd=REPO, capture_output=True, text=True, check=True)
+    entries = [e.partition("\t") for e in rc.stdout.split("\0") if e]
+    paths = sorted({path for _meta, _, path in entries})
+    # "regular" as `run_all` defines it: EVERY stage of the path a regular blob, not any one of them.
+    stage_modes: dict[str, set[str]] = {}
+    for meta, _, path in entries:
+        stage_modes.setdefault(path, set()).add(meta.split(" ", 1)[0])
+    regular = {path for path, ms in stage_modes.items() if all(m.startswith("100") for m in ms)}
+    assert len(paths) > 1000, f"corpus looks wrong: {len(paths)} paths"
 
     disagree = [p for p in paths if mod.is_scanned_path(p) != restated(p)]
     assert not disagree, f"population disagrees with the restated rule on {len(disagree)}: {disagree[:8]}"
 
     # Anti-vacuity: an oracle that says False everywhere would agree with a scan-nothing mutant.
-    scanned = [p for p in paths if restated(p)]
+    # `scanned` is what `--all` opens: the predicate over REGULAR blobs only, because a symlink or
+    # gitlink the predicate admits is excluded by mode, and a claim about the scanned corpus's shape
+    # must be measured over the corpus that is scanned.
+    scanned = [p for p in paths if restated(p) and p in regular]
     exempt = [p for p in paths if p.startswith("docs/decisions/")]
+    process = [p for p in scanned if not p.endswith(".md")]
     assert len(scanned) > 50 and len(exempt) > 50, f"{len(scanned)} scanned / {len(exempt)} exempt"
+    assert len(process) > 50, f"{len(process)} non-markdown process files — the #876 arm saw nothing"
+    # The record states a MEASUREMENT about this corpus — no scanned path deeper than three slashes,
+    # so a `count("/") <= 3` cap is a no-op against it — and nothing else couples the claim to the
+    # corpus. A red here is the claim going stale, not a defect in the path that broke it. Re-measure,
+    # then re-state every site that carries the claim: the record's `mechanics:`
+    # (`docs.no-session-narrative`, `mechanics:` AND the #876 paragraph of its body), this function's
+    # docstring, the comment on the cross product below, and the fixtures paragraph of the exemption
+    # comment in `check-doc-narrative.py`; then move this bound.
+    assert max(p.count("/") for p in scanned) <= 3, "the record's depth measurement is stale — re-state it"
+    assert not any(mod.is_scanned_path(p) for p in mod.EXEMPT_FILES)
+    assert all(p in paths for p in mod.EXEMPT_FILES), "an EXEMPT_FILES entry names nothing tracked"
 
     # The real corpus alone cannot see a rule that differs only on a shape it does not currently
-    # contain — no scanned path carries more than three slashes today, so a `count("/") <= 3` cap is
-    # a no-op against it and would ship latent. So the same oracle is also compared over a cross
-    # product of FOUR dimensions a population rule has been observed to key on here — depth, first
+    # contain — no scanned path carries more than three slashes (re-measured 2026-09-03, #876), so a
+    # `count("/") <= 3` cap is a no-op against it and would ship latent. So the same oracle is also
+    # compared over a cross product of FOUR dimensions a population rule has been observed to key on here — depth, first
     # segment, second segment, extension — widened with basename, case and dotted directories after
-    # a review round found a mutant keyed on each. This ENUMERATES; it is not a universal over the
+    # a mutant keyed on each was found. This ENUMERATES; it is not a universal over the
     # space of rules, and a dimension on neither list has simply not been measured.
-    heads = ["docs", "Docs", "web", "scripts", ".github", ""]
-    seconds = ["decisions", "superpowers", "other", "decisions-not", "Decisions", ".hidden", ""]
-    leaves = ["f", "index", "README"]
-    exts = [".md", ".markdown", ".MD", ".txt", ""]
+    heads = ["docs", "Docs", "web", "scripts", "Scripts", ".github", ".gitea", ".claude", ".husky", "scripts-not", ""]
+    seconds = [
+        "decisions",
+        "superpowers",
+        "other",
+        "decisions-not",
+        "Decisions",
+        ".hidden",
+        "tests",
+        "hooks",
+        "tests/fixtures",
+        "tests/fixtures-not",
+        "",
+    ]
+    leaves = ["f", "index", "README", "check-doc-narrative", "test_check_doc_narrative"]
+    # `.py.bak` is the strict extension of an exempt NAME: it separates `path in EXEMPT_FILES` from
+    # a `startswith` over the same tuple, which the real corpus cannot (nothing tracked extends it).
+    exts = [".md", ".markdown", ".MD", ".txt", ".py", ".py.bak", ".sh", ".yml", ""]
     synthetic = set()
     for ext in exts:
         for leaf in leaves:
@@ -401,14 +447,122 @@ def test_every_exempt_prefix_has_a_case_above() -> None:
 
 
 def test_markdown_outside_the_stated_population_is_not_scanned(repo: Path) -> None:
-    """The population is `docs/**/*.md` minus `EXEMPT_PREFIXES`, plus root-level `*.md`. A skill
-    under `.claude/` is out of scope, and the record's `mechanics:` says so — out of the DETECTOR,
-    still bound by the RULE."""
-    (repo / ".claude" / "skills" / "s").mkdir(parents=True)
-    (repo / ".claude" / "skills" / "s" / "SKILL.md").write_text(f"{NARRATIVE}\n", encoding="utf-8")
-    (repo / "README.md").write_text(f"{NARRATIVE}\n", encoding="utf-8")
+    """The population is `docs/**/*.md` minus `EXEMPT_PREFIXES`, plus root-level `*.md`, plus the
+    PROCESS corpus (#876) regardless of extension, minus `EXEMPT_FILES`. Nested markdown under
+    `web/` is out of scope, and the record's `mechanics:` says so — out of the DETECTOR, still bound
+    by the RULE. A skill under `.claude/`, a shell hook and a Python test are IN, and the detector's
+    own test file — which carries these phrasings as fixtures — is out BY NAME, so its twin one
+    directory over is still scanned."""
+    for rel in (
+        "web/docs/x.md",
+        ".claude/skills/s/SKILL.md",
+        ".claude/hooks/h.sh",
+        "scripts/tests/test_x.py",
+        "scripts/tests/test_check_doc_narrative.py",
+        "scripts/tests/x/test_check_doc_narrative.py",
+        "README.md",
+    ):
+        (repo / rel).parent.mkdir(parents=True, exist_ok=True)
+        (repo / rel).write_text(f"# {NARRATIVE}\n", encoding="utf-8")
     commit(repo)
-    assert hits(run(repo, "--all").stdout) == {("README.md", 1)}
+    assert hits(run(repo, "--all").stdout) == {
+        ("README.md", 1),
+        (".claude/skills/s/SKILL.md", 1),
+        (".claude/hooks/h.sh", 1),
+        ("scripts/tests/test_x.py", 1),
+        ("scripts/tests/x/test_check_doc_narrative.py", 1),
+    }
+
+
+def test_a_tracked_SYMLINK_is_not_scanned_and_not_counted(repo: Path) -> None:
+    """The population is tracked REGULAR files. A tracked symlink under a process prefix is a path
+    the predicate admits whose worktree content is its TARGET: a directory (this repo's
+    `.claude/skills/jellyfin`) would be skipped with a notice, and a file outside the population
+    would be scanned under the link's name — the target's narrative attributed to a path the rule
+    does not reach. Both are excluded by mode, and the count says so."""
+    (repo / "web").mkdir()
+    (repo / "web" / "target.md").write_text(f"{NARRATIVE}\n", encoding="utf-8")
+    (repo / ".claude" / "skills").mkdir(parents=True)
+    (repo / ".claude" / "skills" / "linked.md").symlink_to("../../web/target.md")
+    (repo / ".claude" / "skills" / "dir").symlink_to("../../web")
+    (repo / ".claude" / "hooks").mkdir()
+    (repo / ".claude" / "hooks" / "h.sh").write_text(f"# {NARRATIVE}\n", encoding="utf-8")
+    commit(repo)
+    out = run(repo, "--all").stdout
+    assert hits(out) == {(".claude/hooks/h.sh", 1)}
+    assert "skipped" not in out
+    # the fixture's `docs/seed.md` plus the hook: neither symlink is counted, and neither is skipped
+    assert "scanned 2 file(s)" in out
+
+
+def test_an_UNMERGED_path_is_scanned_once_and_counted_once(repo: Path) -> None:
+    """`git ls-files -s` emits one row per index STAGE, so a path in conflict appears up to three
+    times. Without de-duplication `--all` opens the worktree file once per row: the same warning
+    three times over, and a population count that is not a count of files."""
+    git(repo, "checkout", "-qb", "side")
+    (repo / "docs" / "seed.md").write_text(f"side\n{NARRATIVE}\n", encoding="utf-8")
+    commit(repo)
+    git(repo, "checkout", "-q", "-")
+    (repo / "docs" / "seed.md").write_text(f"main\n{NARRATIVE}\n", encoding="utf-8")
+    commit(repo)
+    merge = subprocess.run(["git", "merge", "side"], cwd=repo, capture_output=True, text=True)
+    assert merge.returncode != 0, "the fixture must be in conflict"
+    stages = subprocess.run(["git", "ls-files", "-s", "--", "docs/seed.md"], cwd=repo, capture_output=True, text=True)
+    assert stages.stdout.count("\n") == 3, stages.stdout
+    out = run(repo, "--all").stdout
+    assert out.count("::warning") == 1
+    assert "scanned 1 file(s)" in out
+
+
+def test_a_MIXED_MODE_conflict_is_not_opened(repo: Path) -> None:
+    """Two stages of DIFFERENT mode under one path — a symlink beside a regular blob — with the
+    worktree holding one of them. A per-row mode test lets the regular row authorise opening the
+    path, which may be the symlink; a path is opened only when EVERY stage is a regular blob.
+
+    Built with `update-index --index-info` rather than a merge: git resolves a symlink/file add/add
+    conflict by RENAMING one side (`h.sh~HEAD`), so a merge never yields this index shape — an
+    older git, a tool, or a hand-edited index can, and `ls-files -s` reports it exactly like this."""
+    (repo / ".claude" / "hooks").mkdir(parents=True)
+    (repo / ".claude" / "hooks" / "h.sh").write_text(f"# {NARRATIVE}\n", encoding="utf-8")
+    commit(repo)
+    blob = subprocess.run(
+        ["git", "rev-parse", "HEAD:.claude/hooks/h.sh"], cwd=repo, capture_output=True, text=True
+    ).stdout.strip()
+    link = subprocess.run(
+        ["git", "hash-object", "-w", "--stdin"], cwd=repo, input="../../web/t.sh", capture_output=True, text=True
+    ).stdout.strip()
+    subprocess.run(
+        ["git", "update-index", "--index-info"],
+        cwd=repo,
+        input=(
+            "0 0000000000000000000000000000000000000000\t.claude/hooks/h.sh\n"
+            f"100644 {blob} 2\t.claude/hooks/h.sh\n"
+            f"120000 {link} 3\t.claude/hooks/h.sh\n"
+        ),
+        text=True,
+        check=True,
+    )
+    stages = subprocess.run(
+        ["git", "ls-files", "-s", "--", ".claude/hooks/h.sh"], cwd=repo, capture_output=True, text=True
+    )
+    assert {line.split(" ", 1)[0] for line in stages.stdout.splitlines()} == {"100644", "120000"}, stages.stdout
+    out = run(repo, "--all").stdout
+    assert hits(out) == set()
+    assert "skipped" not in out
+    assert "scanned 1 file(s)" in out  # the fixture's docs/seed.md only
+
+
+def test_a_path_with_a_SPACE_is_scanned_in_diff_mode(repo: Path) -> None:
+    """Git terminates the `+++` filename field with a TAB when the path contains a space. A parser
+    that keeps the tab asks `is_scanned_path("docs/my notes.md\\t")`, which is False, and the file is
+    dropped with no notice — the scanned-0 channel one level below the config pins. The positive
+    control is the same content at a space-free path in the same diff."""
+    (repo / "docs" / "my notes.md").write_text(f"{NARRATIVE}\n", encoding="utf-8")
+    (repo / "docs" / "mynotes.md").write_text(f"{NARRATIVE}\n", encoding="utf-8")
+    commit(repo)
+    out = run(repo, "--diff", "HEAD~1").stdout
+    assert hits(out) == {("docs/my notes.md", 1), ("docs/mynotes.md", 1)}
+    assert "scanned 2 file(s)" in out
 
 
 # --- the detector actually detects ---------------------------------------------------------------
diff --git a/scripts/tests/test_check_required_contexts.py b/scripts/tests/test_check_required_contexts.py
index e7a6c0c84..527dfdf89 100644
--- a/scripts/tests/test_check_required_contexts.py
+++ b/scripts/tests/test_check_required_contexts.py
@@ -243,10 +243,10 @@ SENTINEL_CLASSIFIER = (
 def test_ONE_classifier_TWO_callers_BEHAVIOURALLY():
     """The structural property #787 relies on, PROVEN by swapping the file — not by reading source.
 
-    A string-presence check was the seventh test in this change to pass for the wrong reason: cold
-    review re-inlined a BYTE-IDENTICAL copy of the classifier into the merge hook, left a comment
-    naming `scripts/lib/branch-rule-classifier.jq` above it, and the whole suite stayed green at
-    exactly 1062 passed. A comment satisfies a substring assertion. And the byte-identical inline is
+    A string-presence check passes for the wrong reason here: re-inlining a BYTE-IDENTICAL copy of
+    the classifier into the merge hook, with a comment naming
+    `scripts/lib/branch-rule-classifier.jq` above it, left the whole suite green at exactly 1062
+    passed. A comment satisfies a substring assertion, and the byte-identical inline is
     precisely the drift-creating refactor that matters, because it AGREES on day one — a weakened
     copy would have been caught behaviourally.
 
@@ -281,10 +281,10 @@ def _mutant_tree(tmp_path, source_text):
     """The script in a RUNNABLE layout: it resolves `lib/branch-rule-classifier.jq` relative to its
     own directory, so a bare copy exits 2 before reaching any of its logic.
 
-    This is not incidental plumbing. The first version of the mutation proof below copied only the
-    script, so the mutant died on `classifier not readable` with EMPTY stdout — and an assertion that
-    stdout merely differed from `drift` was satisfied by that empty string. The proof passed for the
-    wrong reason and the `MUTATION` grade it justified was unsupported.
+    This is not incidental plumbing. A mutation proof that copies only the script kills the mutant
+    on `classifier not readable` with EMPTY stdout — and an assertion that stdout merely differs
+    from `drift` is satisfied by that empty string, so the proof passes for the wrong reason and
+    the `MUTATION` grade it justifies is unsupported.
     """
     victim = tmp_path / "mutant.sh"
     victim.write_text(source_text)
@@ -454,9 +454,9 @@ CLASSIFIER = REPO_ROOT / "scripts" / "lib" / "branch-rule-classifier.jq"
 def classify(payload: str, branch: str = "main") -> tuple[int, str]:
     """The classifier ALONE, with no script wrapping it. `check-required-contexts.sh` maps both a
     declared `unreadable` verdict and a jq CRASH onto the same output word, so a test that only reads
-    that word cannot tell the two apart — cold review demonstrated exactly that by mutating the
-    classifier's structural guard to `if false`, making jq exit 5, and watching the wrapper still
-    print `unreadable`. Asserting the raw verdict is what pins the mechanism."""
+    that word cannot tell the two apart — measured: mutating the classifier's structural guard to
+    `if false` makes jq exit 5 and the wrapper still prints `unreadable`. Asserting the raw verdict
+    is what pins the mechanism."""
     proc = subprocess.run(
         ["jq", "--arg", "b", branch, "-c", "-f", str(CLASSIFIER)],
         input=payload,
@@ -538,11 +538,12 @@ def test_an_EMPTY_array_is_still_a_real_finding():
 
 
 def test_a_MALFORMED_rule_name_poisons_even_beside_a_GOOD_branch_name():
-    """Poison is field-agnostic, which the first draft of the fix got wrong in one direction.
+    """Poison is field-agnostic, and a short-circuit on `branch_name` gets that wrong in one
+    direction.
 
-    It short-circuited on `branch_name`, so `{"branch_name":42,"rule_name":"main"}` poisoned while
-    `{"branch_name":"main","rule_name":42}` answered `exact` off the good field and never looked at
-    the malformed one — an invariant the comment claimed and the code did not hold. Gitea 1.27.1 does
+    A short-circuiting implementation poisons on `{"branch_name":42,"rule_name":"main"}` while
+    `{"branch_name":"main","rule_name":42}` answers `exact` off the good field and never looks at
+    the malformed one — contradicting the field-agnostic invariant its own comment states. Gitea 1.27.1 does
     not send that second shape, so this pins a property rather than a bug: "a malformed field poisons
     the list" has to be true of BOTH fields or it is not the rule that is written down.
     """
diff --git a/scripts/tests/test_check_review_verdict.py b/scripts/tests/test_check_review_verdict.py
index 077ccd5d1..535287422 100644
--- a/scripts/tests/test_check_review_verdict.py
+++ b/scripts/tests/test_check_review_verdict.py
@@ -78,7 +78,7 @@ def test_fence_state_does_not_leak_between_comments():
     assert classify(["Example:\n```\nnot a verdict", verdict("MERGEABLE", HEAD)]) == ("positive", 0)
 
 
-# --- found by cross-family review of the first fix (all three reproduced before fixing) ----------
+# --- three more false-opens, all reproduced before fixing ----------------------------------------
 
 
 def test_falseopen_tilde_fence_is_also_stripped():
@@ -106,8 +106,8 @@ def test_falseopen_sha_field_needs_a_right_boundary(suffix):
 def test_falseopen_a_body_cannot_forge_a_comment_boundary():
     """The separator between comments must be out-of-band.
 
-    An earlier version joined bodies with a literal `\\x01BODY-BOUNDARY\\x01` line. A comment
-    containing that line could reset fence state mid-body and expose a verdict still inside an
+    Joining bodies with a literal `\\x01BODY-BOUNDARY\\x01` line is forgeable: a comment
+    containing that line resets fence state mid-body and exposes a verdict still inside an
     unclosed fence — an in-band delimiter is forgeable by whoever writes the data, and here that is
     anyone who can comment on the PR.
     """
@@ -121,7 +121,7 @@ def test_a_valid_verdict_may_carry_trailing_prose():
     assert classify([f"{verdict('MERGEABLE', HEAD)} (all findings resolved)"]) == ("positive", 0)
 
 
-# --- found by a third review round: fence LENGTH, and masked reader failures ---------------------
+# --- fence LENGTH, and masked reader failures ----------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -180,7 +180,7 @@ def test_a_fenced_example_alongside_a_real_blocked_verdict_still_blocks():
     assert classify([fenced, verdict("BLOCKED", HEAD)]) == ("negative", 0)
 
 
-# --- found by a fifth review round: raw HTML is the third code-block form ------------------------
+# --- raw HTML is the third code-block form -------------------------------------------------------
 
 
 @pytest.mark.parametrize(
@@ -361,7 +361,7 @@ def test_missing_head_argument_is_an_input_error():
     assert p.returncode == 2
 
 
-# --- found by re-review of the fix commit: the READ path must fail closed too ------------------
+# --- the READ path must fail closed too --------------------------------------------------------
 
 
 def test_a_hostile_tmpdir_does_not_hide_a_verdict():
@@ -443,29 +443,26 @@ NEGATIVE_WORDS = ["BLOCKED", "NOT-MERGEABLE"]
 def test_each_verdict_word_retains_its_established_polarity(word, expected):
     """The five established tokens still classify the way reviewers rely on. READ side only.
 
-    NAMED FOR WHAT IT IS. An earlier version called itself a disjointness test and its docstring
-    said "no word may be in both vocabularies". Cold review was right that this is an overclaim:
-    pinning the observable classification of five hardcoded tokens cannot establish a universal
-    property over every token the scripts accept, and for THAT property an omitted token is not a
-    vacuous pass — it is precisely the untested member. This is a polarity regression, and the
-    honest scope is the five words listed. Universal disjointness needs one shared vocabulary both
-    scripts read (ersatztv#788).
+    NAMED FOR WHAT IT IS. Calling this a disjointness test — "no word may be in both vocabularies"
+    — is an overclaim: pinning the observable classification of five hardcoded tokens cannot
+    establish a universal property over every token the scripts accept, and for THAT property an
+    omitted token is not a vacuous pass — it is precisely the untested member. This is a polarity
+    regression, and the honest scope is the five words listed. Universal disjointness needs one
+    shared vocabulary both scripts read (ersatztv#788).
 
     WHY IT SURVIVED ITS PARENT. That test asserted set equality between the write side's `case` arms
-    and the read side's `POS_RE`/`NEG_RE` by parsing shell with regexes, and six review rounds each
-    found another construction it mis-read; it was deleted rather than patched a seventh time. But
+    and the read side's `POS_RE`/`NEG_RE` by parsing shell with regexes, and six successive fixes each
+    met another construction it mis-read; it was deleted rather than patched a seventh time. But
     it carried a SECOND, separable invariant that had nothing to do with parsing, and deleting the
-    file silently took that with it — caught by cold review of the deletion, which is exactly the
-    "enumerate what a workaround provided before removing it" rule
-    (`process.enumerate-workaround-behaviors-before-deleting`).
+    file silently took that with it — exactly the "enumerate what a workaround provided before
+    removing it" rule (`process.enumerate-workaround-behaviors-before-deleting`).
 
     WHY THIS VERSION IS SOUND WHERE ITS PARENT WAS NOT. It EXECUTES the real classifier instead of
     reading its source, so no shell construction can fool it. `check-review-verdict.sh` sets
     `is_pos` and `is_neg` from two INDEPENDENT `grep -iqE` calls, so a word in both patterns sets
     both flags and precedence decides.
 
-    WHICH DIRECTION THIS CATCHES, MEASURED RATHER THAN REASONED — the first draft of this docstring
-    asserted it and was checked afterwards, which is the wrong order. `check-review-verdict.sh:284`
+    WHICH DIRECTION THIS CATCHES, MEASURED RATHER THAN REASONED. `check-review-verdict.sh:284`
     reads `if [ "$is_pos" = 1 ]; then head_pos=1; else head_neg=1; fi`, so `is_pos` wins per line
     and an overlapping word resolves POSITIVE. Both mutations were run against this test:
 
diff --git a/scripts/tests/test_ci_dropped_step_guard.py b/scripts/tests/test_ci_dropped_step_guard.py
index 59e3d9001..08377b971 100644
--- a/scripts/tests/test_ci_dropped_step_guard.py
+++ b/scripts/tests/test_ci_dropped_step_guard.py
@@ -84,8 +84,7 @@ def _workflow_job_contexts() -> dict[str, str]:
     job runs `test_ci_release_path_scan_job.py`, whose harness executes THIS file inside a poisoned
     COPY of the tree that is not a git repository, where `git ls-files` exits 128. (The scan job
     itself runs in a real checkout — the non-git tree is the harness's, which is why the constraint
-    is real but the shorthand "the scan job runs this in a non-git copy" is imprecise.) An earlier
-    draft of this change walked straight into it.
+    is real but the shorthand "the scan job runs this in a non-git copy" is imprecise.)
 
     SYNTHESIZED and matched by equality, never parsed. Gitea names an Actions context
     ` /  ()`, and both names are already in the YAML — so building
@@ -224,9 +223,9 @@ MARKED_JOBS = _derive_marked_jobs()
 # `build`'s "Smoke + IPTV E2E" step runs AFTER `Build and push`, so on a `v*` tag the image is
 # already in the registry as the release candidate and this step is what decides whether it was ever
 # booted. A drop there publishes an unsmoked candidate and goes green, and `DeployStack jazz-media`
-# promotes exactly that image — not a "smaller cost than a required context", which is what an
-# earlier draft of the decision record claimed. Its two payloads moved into the step's `env:`, which
-# is the free half of the escape hatch, so the ban costs nothing there.
+# promotes exactly that image — not a "smaller cost than a required context". Its two payloads
+# moved into the step's `env:`, which is the free half of the escape hatch, so the ban costs nothing
+# there.
 #
 # `functional-e2e` is deliberately NOT here even though it is delimiter-free today: it is advisory by
 # declaration (not a required check, not a `needs:` of `build`), so the rule stays "ban where a drop
@@ -249,7 +248,7 @@ assert set(MARKED_JOBS) <= set(DELIMITER_BAN_JOBS), (
     "still carry the delimiter that makes the runner drop the step in the first place (ersatztv#756)."
 )
 
-# THE RAW OPENER, not a closed `${{ … }}` pair — found by cold review. The runner's rewrite is
+# THE RAW OPENER, not a closed `${{ … }}` pair. The runner's rewrite is
 # triggered by the OPENER; a closed-pair regex therefore misses `# ${{` with no closer, which would
 # sail through an "absolute" ban and still drop the step. Nothing in these jobs may contain the
 # opener at all, so matching it directly is both simpler and strictly stronger. `_EXPR` is kept for
@@ -334,7 +333,7 @@ def test_the_delimiter_banned_jobs_have_NO_expression_delimiter_in_any_run_body(
 
     The scope is `DELIMITER_BAN_JOBS` — see the comment there for why `build` is in
     and `functional-e2e` is not. Do NOT restate this docstring as "scoped to the required pair":
-    round 2 moved `build`'s two payloads into `env:` and brought it into the ban, and this docstring
+    `build`'s two payloads moved into `env:`, which brought it into the ban, and this docstring
     sits directly above the decorator that parametrises over the wider set.
 
     The escape hatch when a value really is needed is the step's `env:` block, which is interpolated
@@ -444,7 +443,7 @@ def test_the_guard_expects_EXACTLY_the_set_of_marked_keys_in_the_right_bucket(jo
         f"{sorted(keys)}. Keys marked-but-unexpected are unguarded drops; keys "
         "expected-but-unmarked redden every run."
     )
-    # AN UNRECOGNISED `if:` IS REJECTED, never silently bucketed — found by both reviewers. The
+    # AN UNRECOGNISED `if:` IS REJECTED, never silently bucketed. The
     # protocol only knows two conditions: absent (always runs) and exactly the skip gate. A marked
     # step carrying a third condition (`if: github.event_name == 'push'`, or the `always() && `
     # spelling the peak-anon steps already use) would fall through to "always", the suite would go
@@ -534,13 +533,13 @@ def test_the_guards_OWN_body_cannot_be_dropped_by_the_mechanism_it_guards_agains
         f"the '{job}' guard is no longer a bare invocation: {guard['run']!r}. Keeping it to one "
         "command is what makes a delimiter impossible rather than merely absent."
     )
-    # THE VALUES, not just the names — found by cold review. Asserting the keys alone accepts
+    # THE VALUES, not just the names. Asserting the keys alone accepts
     # `ETV_DOCS_ONLY: ${{ steps.detect.outputs.doc_only }}` (note the typo), which names a real
     # context so the repo-wide expression check passes it too. The guard would then read an EMPTY
     # value on a docs-only run, demand the gated steps that were correctly skipped, and redden a
     # REQUIRED context on every docs-only PR.
     # THE TWO MAPPINGS MUST BE PRESENT AND CORRECT — but this deliberately does NOT demand that the
-    # `env:` block contain ONLY them. An earlier version compared the whole dict, which false-redded
+    # `env:` block contain ONLY them. Comparing the whole dict false-reds
     # on adding an unrelated variable (an `LC_ALL`, say) and on the equally-valid `${{x}}` spacing;
     # a red here blocks every merge through the combined status, so brittleness is a real cost and
     # not a free strictness win. Whitespace inside the delimiters is normalised for the same reason.
@@ -576,7 +575,7 @@ def _mark_line(step) -> str:
 
 
 # THE GATE VALUES DEFAULT TO `"false"`, WHICH IS WHAT THE RUNNER ACTUALLY SENDS — and getting this
-# wrong made the whole suite blind. Found by cold review, which demonstrated it: every behavioural
+# wrong made the whole suite blind. DEMONSTRATED: every behavioural
 # test used to leave these UNSET, so the guard was never once driven at its production values. Change
 # the gate in `ci-step-ran.sh` from `= "true"` to `-n` — a one-token regression — and all 30 tests
 # stayed GREEN while the guard, run with the real environment, reported
@@ -596,8 +595,8 @@ def _mark_line(step) -> str:
 # CATCH, which is exactly why the gate must treat anything that is not `true` as "widen what is
 # required". `None` (unset) is the same case reached a different way.
 #
-# A test double is an assertion about what the real system sends, and the earlier version of this one
-# was wrong about the only field the guard branches on.
+# A test double is an assertion about what the real system sends, and this one has already been
+# wrong about the only field the guard branches on.
 GATE_VALUES_IN_THE_WILD = ("false", "", None)
 
 
@@ -810,10 +809,10 @@ def test_a_key_is_matched_WHOLE_not_as_a_substring(tmp_path):
 def test_a_degraded_run_IDENTITY_refuses_rather_than_sharing_a_marker_path(tmp_path):
     """`GITHUB_RUN_ID` absent must REFUSE, not fall back to a name every run shares.
 
-    The first version of `marker_path` defaulted to `nojob`/`norunid`/`1`. Those are reusable, so a
+    A `marker_path` defaulting to `nojob`/`norunid`/`1` uses names every run shares, so a
     leftover marker from any earlier run on the host would satisfy the guard on a run whose step was
     dropped — a silent PASS, which is the precise failure the run-keying exists to remove,
-    reintroduced by the code implementing it. Found by cold review.
+    reintroduced by the code implementing it.
 
     Asserted on BOTH sub-commands: a refusal that only `assert` honoured would let `mark` write to a
     shared path and leave the two disagreeing about where the file is.
@@ -849,8 +848,8 @@ def test_the_marker_identity_is_REPORTED_on_stdout_every_run(tmp_path):
     and the same for `migrations`. That is what promoted the variable from warn-and-default to
     required.
 
-    Asserted because cold review demonstrated three mutations of this reporting — deleting the echo,
-    mis-deriving the attempt, inverting the provenance — all surviving a 50-green suite. It is a
+    Asserted because three mutations of this reporting — deleting the echo,
+    mis-deriving the attempt, inverting the provenance — all survived a 50-green suite. It is a
     documented contract (the record's `mechanics:`), and a future reader is told to trust it.
     """
     marks = [_mark_line(s) for s, _ in _marked("test")]
@@ -866,8 +865,7 @@ def test_the_marker_identity_is_REPORTED_on_stdout_every_run(tmp_path):
 
 
 def test_a_skip_gate_that_empties_the_expected_set_REFUSES(tmp_path):
-    """The anti-vacuity check has to run AFTER the gate, not only on argv. Cold review reproduced
-    this exactly:
+    """The anti-vacuity check has to run AFTER the gate, not only on argv. REPRODUCED exactly:
 
         ETV_DOCS_ONLY=true … assert --always --gated foo
         -> "All 0 expected step(s) executed", exit 0
@@ -888,14 +886,13 @@ def test_a_skip_gate_that_empties_the_expected_set_REFUSES(tmp_path):
     "docs_only", ["true", "false", "", None], ids=lambda v: f"docs-{v if v is not None else 'unset'}"
 )
 def test_the_skip_gate_over_the_WHOLE_value_matrix(docs_only, revalidate, tmp_path):
-    """Every combination of the two gate values, not just the diagonal — cold review's last finding.
+    """Every combination of the two gate values, not just the diagonal.
 
-    Round 3 fixed the suite's blindness to the production value `false`, but still only exercised
-    matched pairs and single-`true` cases. `(true, true)` is REACHABLE — a docs-only PR merged to
-    `main` whose tree was already validated sets both — and an exclusive-or regression would pass
-    every other test here while demanding all the gated markers on a run that legitimately skipped
-    those steps. That reddens BOTH required contexts, which is the false-red direction: it deadlocks
-    every merge rather than letting one through.
+    Matched pairs and single-`true` cases are not enough on their own. `(true, true)` is REACHABLE
+    — a docs-only PR merged to `main` whose tree was already validated sets both — and an
+    exclusive-or regression would pass every other test here while demanding all the gated markers
+    on a run that legitimately skipped those steps. That reddens BOTH required contexts, which is
+    the false-red direction: it deadlocks every merge rather than letting one through.
 
     The property asserted is the whole contract in one line: with only the `--always` keys marked,
     the guard passes exactly when the gate says the gated steps were skipped — `true` in EITHER
diff --git a/scripts/tests/test_ci_image_pin_population.py b/scripts/tests/test_ci_image_pin_population.py
index 1a2cc69cd..21d163893 100644
--- a/scripts/tests/test_ci_image_pin_population.py
+++ b/scripts/tests/test_ci_image_pin_population.py
@@ -69,8 +69,8 @@ _DOC = yaml.safe_load(WORKFLOW.read_text())
 # `BARE_RUNNER_JOBS` — two hand-written literals enumerating jobs by name.
 #
 # WHY A LITERAL WAS THERE AT ALL, because the reason is real and the replacement has to answer it.
-# The first version of this file compared `container_jobs(doc)` against `pinned_jobs(doc)` and
-# nothing else. That is blind to the mutation that matters most: delete a `container:` block and the
+# Comparing `container_jobs(doc)` against `pinned_jobs(doc)` and
+# nothing else is blind to the mutation that matters most: delete a `container:` block and the
 # job leaves BOTH sets together, so the comparison stays balanced and reports green — the very
 # fail-open this file exists to close, reproduced one level up. A guard whose expected set shrinks
 # in step with the thing it guards is not a guard. So the population needs an ANCHOR that does not
@@ -82,7 +82,7 @@ _DOC = yaml.safe_load(WORKFLOW.read_text())
 # instead of in a Python file three directories away — so it is reachable by anyone reading that job,
 # and it moves with the job when the job is renamed or removed.
 #
-# NOT "in the same diff hunk", which an earlier version of this note claimed. MEASURED distance from
+# NOT "in the same diff hunk". MEASURED distance from
 # each `container:` block to its marker: test 6 lines, functional-e2e 6, api-docs 7, format 7 —
 # and migrations 58, because the whole `services:` block sits between them. A container-only edit to
 # `migrations` shows no marker in its hunk at all. Adjacency is a convenience that mostly holds; the
@@ -269,8 +269,8 @@ def jobs_whose_steps_need_the_toolchain(doc) -> dict[str, set[str]]:
 
     ONE-DIRECTIONAL ON PURPOSE, and this is the limit to state rather than let review find. Step
     text is a NECESSARY condition, never a sufficient one: a job whose ONLY toolchain use sat behind
-    a script would be invisible here. MEASURED, because the first version of this note asserted the
-    blind spot was live and it is not — all five declared toolchain jobs are detected directly,
+    a script would be invisible here. MEASURED: that blind spot is NOT live —
+    all five declared toolchain jobs are detected directly,
     `functional-e2e` included, which runs `dotnet restore` and `npm ci` in its own steps before
     handing off to `scripts/e2e-local.sh`. The blind-spot set is EMPTY today. The converse —
     'declared toolchain, so some step must name a tool' — is still not asserted, because a future
@@ -499,8 +499,8 @@ def test_docker_build_is_the_ONLY_workflow_pinning_the_toolchain_image():
     guard, no single-tag check and no partition, silently, while `pin_population_faults`'s own error
     text claims "All container jobs must run the same toolchain image".
 
-    Found by cold review, which correctly noted this file criticises `MARKED_JOBS` for exactly this
-    and then shipped the same shape without even the dated comment `MARKED_JOBS` then carried.
+    This file criticised `MARKED_JOBS` for exactly this and then shipped the same shape, without
+    even the dated comment `MARKED_JOBS` then carried.
     `MARKED_JOBS` has since been derived (#787), and `TOOLCHAIN_JOBS`/`BARE_RUNNER_JOBS` — the
     literals this file once carried — were replaced by the per-job `env.CI_EXECUTION_CLASS` marker
     in #789. This scope check is what still keeps `WORKFLOW` honest: the marker says which class a
diff --git a/scripts/tests/test_ci_release_path_scan_job.py b/scripts/tests/test_ci_release_path_scan_job.py
index 22723f202..80d072901 100644
--- a/scripts/tests/test_ci_release_path_scan_job.py
+++ b/scripts/tests/test_ci_release_path_scan_job.py
@@ -6,8 +6,8 @@ But the ban was enforced ONLY by `test_the_delimiter_banned_jobs_have_NO_express
 in `script-tests` — `on: pull_request`, not a required context. Nothing re-checked it on a `v*` tag
 push, which is exactly when the candidate is published.
 
-WHY A JOB AND NOT A STEP IN `build`, and why this file is structural. The first cut of #767 put a
-bespoke stdlib scanner in `build` itself. Two independent reviews killed it on two counts, and both
+WHY A JOB AND NOT A STEP IN `build`, and why this file is structural. A bespoke stdlib scanner in
+`build` itself is wrong on two counts, and both
 are worth keeping written down because both are easy to re-invent:
 
   * A guard step inside `build` cannot protect `build`. If the runner drops it, the job carries on
@@ -15,9 +15,9 @@ are worth keeping written down because both are easy to re-invent:
     cannot be dropped", but the only thing enforcing THAT was the same PR-only test being
     backstopped. Circular. As a `needs:` of `build`, a red here means `build` never runs at all.
   * The bespoke scanner hand-parsed YAML (to avoid provisioning PyYAML on `build`'s bare runner) and
-    had ~10 false NEGATIVES within one review round — flow mappings, a quoted `"run":` key, aliases,
+    had ~10 false NEGATIVES — flow mappings, a quoted `"run":` key, aliases,
     multiline quoted scalars. It was strictly WEAKER than the check it backstopped, in the only
-    direction that matters. The fix was to delete it and run the real PyYAML-based test, which needs
+    direction that matters. This job runs the real PyYAML-based test instead, which needs
     no second definition of "what is a `run:` body" and so has no drift surface.
 
 The detection ALGORITHM is not reimplemented here — it lives in `test_ci_dropped_step_guard.py`, and
@@ -26,9 +26,9 @@ exists, `build` depends on it, nothing can skip it, its own steps cannot be sile
 ONE end-to-end probe that executes the scan step's real command against a poisoned copy of the repo
 and requires it to fail.
 
-THAT PROBE IS THE LOAD-BEARING TEST, and it exists because shape assertions lost twice. Round 2
-replaced a substring check with checks ABOUT the command — bare-token argument, no `-k`, no `||` —
-and round 3 then disarmed the gate seven more ways that all left the suite green: `echo`ing the
+THAT PROBE IS THE LOAD-BEARING TEST, and it exists because shape assertions lost twice. Checks
+ABOUT the command — bare-token argument, no `-k`, no `||` — replaced a substring check,
+and the gate was then disarmed seven more ways that all left the suite green: `echo`ing the
 command instead of running it, flags moved past a `\` continuation, a trailing `exit 0`,
 `if false; then … fi`, `set +e`, and `PYTEST_ADDOPTS` in the step's `env:`. Two further disarms lived
 in the sibling module where no shape check could ever reach — the ban test's parametrize list swapped
@@ -36,10 +36,10 @@ to `MARKED_JOBS`, and its opener regex neutered. Running the command settles eve
 because it asks the only question that matters: with a delimiter in `build`'s `Smoke` body, does this
 command fail? The shape checks are kept as a faster, more specific signal, not as the guarantee.
 
-ROUND 4 THEN FOUND THE TWIN OF THE ROUND-3 FIX, which is the reusable lesson here: fixing the STEP
+THE TWIN OF THAT FIX IS THE REUSABLE LESSON HERE: fixing the STEP
 `env:` tier did not generalise, and the same `PYTEST_ADDOPTS` disarm placed one tier up — on the JOB
 — defeated the probe, because the probe reconstructed only the step's env. It now layers all three
-tiers (workflow, job, step). The same round found that `needs:` is not by itself a gate: an
+tiers (workflow, job, step). Nor is `needs:` by itself a gate: an
 `always()` in `build`'s `if:` downgrades the edge to mere ordering, and the delimiter ban does not
 cover `if:` expressions, so nothing else would have objected.
 
@@ -51,7 +51,7 @@ poisoned tree while the probe reports healthy. That one is BANNED rather than mo
 be a second implementation of precisely the kind #767 already deleted once. The rule after any fix
 here: enumerate the tiers and the twin, and where a tier cannot be observed, forbid it.
 
-(Two disarms review reported were checked and are NOT real: `--ignore=` and a `conftest.py`
+(Two proposed disarms were checked and are NOT real: `--ignore=` and a `conftest.py`
 `collect_ignore` do not suppress a file pytest was given explicitly as an argument — measured, the
 ban test still ran and still failed. Recorded so they are not re-litigated. But note what refuting
 them did NOT establish: the WORKING attacks through that same configuration channel — a repo-root
@@ -403,14 +403,14 @@ def test_the_scan_step_REALLY_FAILS_on_a_poisoned_workflow(tmp_path):
     It executes the ban step's actual `run:` body — with its actual `env:` — against a copy of the
     repo whose `build`/`Smoke` body carries an injected delimiter, and requires a non-zero exit.
 
-    This exists because shape checks lost. An earlier round asserted things ABOUT the command
-    (the ban test's path is a bare token, no `-k`/`--deselect`, no `||`) and review then disarmed the
-    gate anyway, every time leaving the suite green: `echo`ing the command instead of running it,
+    This exists because shape checks lost. With things asserted ABOUT the command
+    (the ban test's path is a bare token, no `-k`/`--deselect`, no `||`), the gate was disarmed
+    anyway, every time leaving the suite green: `echo`ing the command instead of running it,
     flags moved past a `\\` continuation, a trailing `exit 0`, `if false; then … fi`, `set +e`, and
     `PYTEST_ADDOPTS` in the step's `env:`. Enumerating shapes of a command cannot win; running the
     command settles them together, including the two in the sibling module that no shape check could
     reach (a parametrize list swapped to `MARKED_JOBS`, and a neutered opener regex). No count is
-    given on purpose — an earlier draft's tally disagreed with its own list, and the number was never
+    given on purpose — a tally here has already disagreed with its own list, and the number was never
     the point.
 
     The negative control below is what stops this passing for the wrong reason. And note the limit of
@@ -457,7 +457,7 @@ def test_the_PROOF_SCRIPT_itself_refuses_when_the_ban_is_deselected(tmp_path):
 
     The disarm reproduced here is the real one: a repo-root `conftest.py` that deselects the ban test
     entirely, which makes pytest exit 5 (nothing collected) rather than fail — the exact reading that
-    made an earlier draft of the script report the gate healthy while an unsmoked candidate would
+    reports the gate healthy while an unsmoked candidate would
     publish.
     """
     repo = _repo_copy(tmp_path)
@@ -479,8 +479,8 @@ def test_the_PROOF_SCRIPT_itself_refuses_when_the_ban_is_deselected(tmp_path):
     # NON-ZERO IS NOT ENOUGH — the script could exit non-zero because its own harness broke (a moved
     # anchor, an unwritable tree, no python3), which would make this test pass while proving nothing.
     # Require one of its real verdicts. Measured, this path yields "pytest exited 5" (nothing
-    # collected), which is precisely the deselection disarm and precisely the reading an earlier draft
-    # mistook for success.
+    # collected), which is precisely the deselection disarm and precisely the reading that looks like
+    # success.
     combined = res.stdout + res.stderr
     # THE SPECIFIC branch, not a disjunction over the script's verdicts. Measured: a total deselect
     # makes pytest exit 5, so this lands on "cannot prove anything". Accepting any verdict would let
@@ -498,8 +498,8 @@ def test_the_PROOF_SCRIPT_refuses_when_the_WRONG_test_fails(tmp_path):
     """The third branch, which the aggregate 'deselect ⇒ non-zero' control does not reach.
 
     Deselecting only the `[build]` parametrisation while some unrelated test fails gives pytest exit
-    1 — a real test failure, just not the one that proves anything. An earlier draft read that as
-    success. Reproduced here because that branch was added to fix a live bug and was otherwise
+    1 — a real test failure, just not the one that proves anything.
+    Reproduced here because that branch was added to fix a live bug and was otherwise
     exercised by nothing: making it unreachable left both guard files green.
     """
     repo = _repo_copy(tmp_path)
@@ -509,8 +509,7 @@ def test_the_PROOF_SCRIPT_refuses_when_the_WRONG_test_fails(tmp_path):
     )
     # The unrelated failure has to live INSIDE the ban file: the script runs that file and nothing
     # else, so a failing test in a sibling module is never collected and the run would exit 0 —
-    # landing on the "not enforcing" branch instead of the one under test. (First draft of this test
-    # did exactly that and was red for the wrong reason.)
+    # landing on the "not enforcing" branch instead of the one under test.
     ban = repo / BAN_TEST_FILE
     ban.write_text(ban.read_text() + "\n\ndef test_an_unrelated_failure_for_this_probe():\n    assert False\n")
     res = subprocess.run(
diff --git a/scripts/tests/test_ci_toolchain_image_resolves.py b/scripts/tests/test_ci_toolchain_image_resolves.py
index 6333e9566..afa5aeb4c 100644
--- a/scripts/tests/test_ci_toolchain_image_resolves.py
+++ b/scripts/tests/test_ci_toolchain_image_resolves.py
@@ -152,7 +152,7 @@ def test_MUTATION_a_deleted_tag_is_reported_as_a_failure(preflight):
 
 @pytest.mark.parametrize("code", ["TRANSPORT", "503"])
 def test_an_unknown_answer_FAILS_and_is_not_reported_as_gone(preflight, code):
-    """The first draft warned and exited 0 here, which is how a preflight becomes a no-op.
+    """Warning and exiting 0 here is how a preflight becomes a no-op.
 
     A missing `curl`, a moved registry or a DNS change all land in this arm, and each would have
     been green forever. It fails — but with its own wording, because "could not verify" and "IS
diff --git a/scripts/tests/test_complete_annotation_dispositions.py b/scripts/tests/test_complete_annotation_dispositions.py
index cc6370020..fe6a25d65 100644
--- a/scripts/tests/test_complete_annotation_dispositions.py
+++ b/scripts/tests/test_complete_annotation_dispositions.py
@@ -5,7 +5,7 @@ saying, per schema, whether the SPA must annotate it `Complete`, must not, or
 its POPULATION (which schemas can drop a member) from the generated types and asserts set equality
 against those keys — so a new optional member cannot ship undispositioned.
 
-It did not check the VALUE, and cold review demonstrated that the value is a kill switch: flip
+It did not check the VALUE, and the value is a kill switch, measured: flip
 `MultiCollectionItemRequest` from `ANNOTATED` to `CREATE` and delete the `Complete<…>` from
 `MultiCollectionsScreen.toItemRequest`, and the whole suite stays green while the defect #807 exists
 to prevent — every weight silently reset to 1 on save — is live again. The row's own note still said
diff --git a/scripts/tests/test_decisions_validate.py b/scripts/tests/test_decisions_validate.py
index 1310db8d8..62067e715 100644
--- a/scripts/tests/test_decisions_validate.py
+++ b/scripts/tests/test_decisions_validate.py
@@ -915,10 +915,9 @@ def test_a_wing_root_README_is_exempt_by_PATH_not_by_basename(tmp_path):
     """`docs/decisions/archive/README.md` really exists (a hand-written directory README), so it
     must be exempt — but by exact relative path, not by basename.
 
-    An earlier version excluded ANY wing-root `README.md` on the stated grounds that no such file
-    existed. That was false, and it would additionally have exempted a future
-    `records/README.md` — reintroducing the basename hole one directory over, in the wing that
-    matters most."""
+    Excluding ANY wing-root `README.md` on the grounds that no such file exists is false, and it
+    would additionally exempt a future `records/README.md` — reintroducing the basename hole one
+    directory over, in the wing that matters most."""
     records, archive = _wing(tmp_path)
     (records / "ci" / "good.md").write_text(_GOOD)
     (archive / "README.md").write_text("# archive\n\nHand-written directory README.\n")
@@ -1067,7 +1066,7 @@ def test_ceiling_calibration_detects_drift_in_BOTH_directions():
     assert not dv.ceiling_calibration(recs, 10).marks_tail, "below p90 it cuts into the bulk"
     assert not dv.ceiling_calibration(recs, 999).marks_tail, "above p95 it is parked among outliers"
 
-    # BOTH ends of `marks_tail` are inclusive. Review found the upper one unpinned — `ceiling <= p95`
+    # BOTH ends of `marks_tail` are inclusive. The upper one was unpinned — `ceiling <= p95`
     # mutated to `<` survived the whole suite. It is notice-only rather than blocking, but an
     # unpinned boundary is how a documented claim quietly stops being true.
     assert dv.ceiling_calibration(recs, 20).marks_tail, "p90 itself must satisfy the lower bound"
@@ -1083,10 +1082,10 @@ def test_ceiling_calibration_detects_drift_in_BOTH_directions():
 def test_the_coarse_bound_REJECTS_a_badly_placed_ceiling():
     """The blocking property must have teeth.
 
-    Review's strongest finding on the first draft: a floor of `fraction_over > 0` was nearly
-    unfalsifiable — measured on the live corpus it accepted every ceiling from 39 to 229, including
-    the ceiling of 200 the docstring itself offered as the case it catches, because one 230-line
-    record keeps the count nonzero. A FRACTION floor is what restores the teeth.
+    A floor of `fraction_over > 0` is nearly unfalsifiable — measured on the live corpus it
+    accepted every ceiling from 39 to 229, including the ceiling of 200 the docstring itself
+    offered as the case it catches, because one 230-line record keeps the count nonzero. A
+    FRACTION floor is what restores the teeth.
 
     The rejections are pinned on a SYNTHETIC distribution: asserting that a specific absurd ceiling
     stays rejected by the live corpus is itself growth-coupled (three new 200+ line records flip the
@@ -1094,9 +1093,9 @@ def test_the_coarse_bound_REJECTS_a_badly_placed_ceiling():
     """
     # The TEETH are demonstrated on an owned distribution, for the reason in
     # `test_v4_would_have_reddened_where_v5_holds`: an assertion that a specific absurd ceiling is
-    # rejected by the LIVE corpus is itself growth-coupled (review found that three new 200+ line
-    # records would flip the 200 arm). 100 records of 30 lines and one of 230 — an outlier-only
-    # tail, which is precisely the shape a badly-placed ceiling fails to distinguish.
+    # rejected by the LIVE corpus is itself growth-coupled (three new 200+ line records would flip
+    # the 200 arm). 100 records of 30 lines and one of 230 — an outlier-only tail, which is
+    # precisely the shape a badly-placed ceiling fails to distinguish.
     synthetic = [_rec_body(f"a.s{i}", 30) for i in range(100)] + [_rec_body("a.outlier", 230)]
 
     for bad in (200, 229, 230):
@@ -1121,7 +1120,7 @@ def test_ceiling_calibration_is_empty_safe():
 
 
 def test_the_minority_band_BOUNDARIES_are_exactly_where_documented():
-    """Pins both constants AND both inclusivities, which review found entirely unmutated.
+    """Pins both constants AND both inclusivities, which were entirely unmutated.
 
     Mutating `0.02 -> 0.03`, `0.25 -> 0.30`, or either `<=` to `<` passed all eight calibration
     tests. These are not free parameters — they ARE the documented CI-red thresholds, so a silent
@@ -1164,7 +1163,7 @@ def test_the_minority_band_BOUNDARIES_are_exactly_where_documented():
 
 
 def test_ceiling_calibration_IGNORES_keyless_records_and_counts_the_rest():
-    """`n` and the `if r.key` filter, both of which review found unpinned.
+    """`n` and the `if r.key` filter, both of which were unpinned.
 
     `main()` passes the UNFILTERED record list, so the filter is load-bearing in production while
     every live-corpus test hands this function a pre-filtered list — the oracle and production's
@@ -1175,9 +1174,9 @@ def test_ceiling_calibration_IGNORES_keyless_records_and_counts_the_rest():
     `n` itself lost its only pin when the over-tight live test was deleted: a mutation returning
     `n=1` passed everything, which would print a wrong denominator in the drift notice.
 
-    The oracle is DYNAMIC and runs at two distinct cardinalities on purpose. The first attempt
-    asserted `n == 10` against a ten-record fixture, and review killed it: a mutation returning a
-    constant 10 for every input satisfied it while changing the live denominator from 183 to 10 —
+    The oracle is DYNAMIC and runs at two distinct cardinalities on purpose. Asserting `n == 10`
+    against a ten-record fixture does not hold it: a mutation returning a constant 10 for every
+    input satisfies it while changing the live denominator from 183 to 10 —
     preserving the exact production defect the test claims to close. A single hardcoded count
     cannot distinguish "counts the input" from "returns this number".
     """
@@ -1219,7 +1218,7 @@ def test_v4_would_have_reddened_where_v5_holds():
     """The v4-vs-v5 contrast, on a distribution the test OWNS rather than the live corpus.
 
     THIRD TIME for this defect class in one change, which is why the fix is to remove the coupling
-    rather than patch the instance. Round 1 of review caught it in the drift test; round 2 caught it
+    rather than patch the instance. The same coupling turned up in the drift test and again
     here, in what looked like a safe `if before.marks_tail:` guard — the GUARD was conditional but
     the CONCLUSION was still an assertion about live order statistics, and appending 16 ordinary
     30-line records (nothing long, nothing unusual) makes `after.marks_tail` true again and fires it:
@@ -1445,9 +1444,9 @@ def test_main_reports_ceiling_drift_as_a_NOTICE_and_still_exits_0(capsys):
     red — the entire point of the v5 split.
 
     The ceiling is DERIVED as one line above the longest record, so it is off the tail boundary by
-    definition. A hardcoded 999 looked safe and was not: review showed ten valid 1000-line records
-    would put p95 at 1000, making 999 calibrated — so the notice would stop firing and this test
-    would go RED, for a corpus change that is nobody's defect.
+    definition. A hardcoded 999 looked safe and was not: ten valid 1000-line records would put p95
+    at 1000, making 999 calibrated — so the notice would stop firing and this test would go RED,
+    for a corpus change that is nobody's defect.
     """
     longest = max(dv.record_prose_lines(r) for r in dl.all_active_records() if r.key)
     assert dv.main(["--record-ceiling", str(longest + 1)]) == 0
@@ -1460,8 +1459,8 @@ def test_main_reports_ceiling_drift_as_a_NOTICE_and_still_exits_0(capsys):
 def test_main_reports_drift_IFF_the_ceiling_is_off_the_tail_boundary(capsys):
     """The complement of the test above — asserting the WIRING, not the corpus's current state.
 
-    The obvious way to write this is `dv.main([]); assert "drifted" not in err`, and that is a trap
-    review caught: `main()` emits the notice exactly when `p90 <= 60 <= p95` is false over the LIVE
+    The obvious way to write this is `dv.main([]); assert "drifted" not in err`, and that is a
+    trap: `main()` emits the notice exactly when `p90 <= 60 <= p95` is false over the LIVE
     corpus, so such a test fails under precisely the condition #688 exists to stop failing — it
     would move v4's assertion three functions down and leave it in the same blocking job. Today p90
     sits exactly ON the ceiling, so ONE new over-ceiling record would have reddened it.
@@ -1475,9 +1474,9 @@ def test_main_reports_drift_IFF_the_ceiling_is_off_the_tail_boundary(capsys):
     assert recs, "corpus is empty — the derived ceilings need at least one record"
     lengths = sorted(dv.record_prose_lines(r) for r in recs)
 
-    # Both ceilings are DERIVED so each branch is guaranteed by construction, not by luck. Review
-    # caught the earlier version relying on the live 60/999 pair: once one 61-line record lands,
-    # BOTH of those drift, and an UNCONDITIONAL notice would have passed the test.
+    # Both ceilings are DERIVED so each branch is guaranteed by construction, not by luck. Relying
+    # on the live 60/999 pair does not: once one 61-line record lands,
+    # BOTH of those drift, and an UNCONDITIONAL notice would pass the test.
     #   * p90 itself is always calibrated — `p90 <= p90 <= p95` holds for any distribution.
     #   * one line above the longest record is always off the tail — it exceeds p95 by definition.
     quiet_ceiling = lengths[min(int(len(lengths) * 0.90), len(lengths) - 1)]
diff --git a/scripts/tests/test_docs_only_detector_clone_depth.py b/scripts/tests/test_docs_only_detector_clone_depth.py
index 5c6053d83..e7a472bc0 100644
--- a/scripts/tests/test_docs_only_detector_clone_depth.py
+++ b/scripts/tests/test_docs_only_detector_clone_depth.py
@@ -56,7 +56,7 @@ def _env(**extra: str) -> dict[str, str]:
     THE MACHINE'S GIT CONFIG IS NEUTRALISED TOO, and that is not belt-and-braces — it is what keeps
     this file from passing here and failing in CI. A developer checkout has a global `user.email`;
     the CI container has none, and git refuses to commit without one ("Author identity unknown").
-    The fixtures below commit, so the first version of this file was green locally and red in CI on
+    The fixtures below commit, so without this the file is green locally and red in CI on
     exactly that. Pointing the global and system config at `os.devnull` makes the ambient
     configuration UNAVAILABLE rather than merely overridden, so a missing `-c` flag in `_git` fails
     everywhere instead of only where the machine is unhelpful — the local run reproduces CI by
@@ -216,9 +216,9 @@ def test_the_fixture_can_actually_graft(request, fixture_name, depth, tmp_path):
     """The raw `--depth=N` fetch the detector must not perform DOES graft this fixture.
 
     Parametrised over BOTH fixtures and BOTH depths, because a control that covers only one of
-    them leaves the other free to go vacuous unreported — which is what happened: the PR arm was
-    first written against the 31-commit origin, where a depth of 200 has nothing to cut, and it
-    passed against the unfixed script. One control per (fixture, depth) pair the file relies on.
+    them leaves the other free to go vacuous unreported — and that is MEASURED: the PR arm against
+    the 31-commit origin, where a depth of 200 has nothing to cut, passed against the unfixed
+    script. One control per (fixture, depth) pair the file relies on.
     """
     origin = request.getfixturevalue(fixture_name)
     repo = _clone(origin, tmp_path / f"control-{depth}")
@@ -279,8 +279,8 @@ def test_the_push_arm_leaves_a_COMPLETE_clone_complete(origin_url, tmp_path):
 def test_the_pull_request_arm_leaves_a_COMPLETE_clone_complete(deep_origin_url, tmp_path):
     """A complete checkout on the PR arm, N=200. NO PRODUCTION CONSUMER TODAY — deliberately.
 
-    Said plainly because the first version of this docstring got it wrong: on `pull_request` the only
-    jobs running this script are the three `fetch-depth: 2` ones, so the PR arm's `--depth=200` was
+    MEASURED: on `pull_request` the only
+    jobs running this script are the three `fetch-depth: 2` ones, so the PR arm's `--depth=200` is
     inert rather than latently firing. What this pins is the SHARED CLAUSE — the next `fetch-depth: 0`
     consumer added to this arm must not silently inherit the graft that cost #836. It is a guard
     against a future shape, not a reproduction of a shipped one, and grading it as the latter would
diff --git a/scripts/tests/test_guard_inventory.py b/scripts/tests/test_guard_inventory.py
index a8886e610..003c9c926 100644
--- a/scripts/tests/test_guard_inventory.py
+++ b/scripts/tests/test_guard_inventory.py
@@ -57,18 +57,18 @@ GUARD_TESTS = ("scripts/tests", ("test_*.py",))
 KINDS = {"GUARD", "TOOLING", "PROOF"}
 PROOFS = {"MUTATION", "BEHAVIOUR-ONLY", "NONE"}
 
-# `scripts/x.sh` AND `scripts/tests/x.py`. The first version omitted the `/`, and the consequence was
-# not theoretical: the three guard files this inventory shipped with were themselves outside the
-# population it checked for completeness, so they acquired no rows and the guard stayed green. Cold
-# review found it. A completeness guard blind to its own author's new guards is the defect this
-# whole change is about, so the miss is recorded here rather than quietly corrected.
+# `scripts/x.sh` AND `scripts/tests/x.py`. Omitting the `/` had a consequence that was not
+# theoretical: the three guard files this inventory shipped with were themselves outside the
+# population it checked for completeness, so they acquired no rows and the guard stayed green.
+# A completeness guard blind to its own author's new guards is the defect this whole change is
+# about, so the miss is recorded here rather than quietly corrected.
 _SCRIPT_REF = re.compile(r"scripts/(?:[a-z0-9_.-]+/)?[a-z0-9_.-]+\.(?:sh|py)")
 _ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|([^|]*)\|\s*([A-Z-]+)\s*\|\s*([A-Z-]+)\s*\|([^|]*)\|\s*$", re.M)
 
 # The prose summary, parsed so it cannot drift from the table it summarises. It already had:
 # shipped as "28 guards, 4 tooling … 6 … 3 … 19" against a table holding 27/5/6/3/18, because it was
 # a hand-maintained mirror with no equality check — #773's Family C inside the deliverable arguing
-# against it. Both reviewers caught it independently.
+# against it.
 _SUMMARY = re.compile(
     r"(\d+)\s+guards?,\s+(\d+)\s+tooling\s+scripts?,\s+(\d+)\s+proof\s+files?\.\s+"
     r"\*\*(\d+)\s+guards?\s+carry\s+a\s+mutation\s+proof;\s+(\d+)\s+(?:are|is)\s+behaviour-only;\s+"
@@ -132,18 +132,17 @@ def wired_hook_files() -> set[str]:
 
     Directory membership is not execution. A hook whose settings.json registration is deleted keeps
     its file, keeps its inventory row, and stops running — and the table would go on describing a
-    working guard. That is #631 and #719's shape ("wired is not running") one level down, and it was
-    the derivation's blind spot until cold review named it.
+    working guard. That is #631 and #719's shape ("wired is not running") one level down.
 
-    COMMENT LINES ARE STRIPPED from the husky hooks first, and that is not a refinement — the first
-    version of this function counted a mention anywhere, and `.husky/pre-commit:7` reads
+    COMMENT LINES ARE STRIPPED from the husky hooks first, and that is not a refinement — counting
+    a mention anywhere counts `.husky/pre-commit:7`, which reads
 
         # CI where a base ref exists). Fail-open shim — see .claude/hooks/decisions-guard.sh.
 
-    one line above the real invocation. Delete line 8 and keep line 7 and the hook would still have
-    read as wired, which is the exact substitution of mention for invocation this function exists to
-    stop, reproduced inside the fix for it. `.claude/settings.json` needs no stripping: JSON has no
-    comments, so every occurrence there is in a real command string.
+    one line above the real invocation. Delete line 8 and keep line 7 and the hook would still read
+    as wired, which is the exact substitution of mention for invocation this function exists to
+    stop. `.claude/settings.json` needs no stripping: JSON has no comments, so every occurrence
+    there is in a real command string.
     """
     text = (REPO_ROOT / ".claude" / "settings.json").read_text()
     for husky in tracked_paths(*HUSKY):
@@ -308,9 +307,8 @@ def test_every_proof_ref_points_at_a_row_marked_PROOF():
 def test_the_summary_counts_match_the_table():
     """The prose is DERIVED-checked, not hand-maintained.
 
-    It shipped wrong the first time — "28 guards, 4 tooling … 19 have none" against a table holding
-    27/5/…/18 — because it was a mirror with no equality check. Both cold reviewers found it
-    independently, which is the clearest possible evidence that a summary nobody checks is a summary
+    A mirror with no equality check shipped "28 guards, 4 tooling … 19 have none" against a table
+    holding 27/5/…/18. A summary nobody checks is a summary
     nobody can trust.
     """
     rows = inventory_rows()
diff --git a/scripts/tests/test_guard_populations_derive_from_git.py b/scripts/tests/test_guard_populations_derive_from_git.py
index 001ac4c2c..f85c88188 100644
--- a/scripts/tests/test_guard_populations_derive_from_git.py
+++ b/scripts/tests/test_guard_populations_derive_from_git.py
@@ -345,7 +345,7 @@ def test_no_derivation_admits_an_untracked_file(label, derive):
 
 # The directory-listing APIs a Python file population is realistically written with. NOT every way a
 # process can list a directory — `subprocess.run(["ls"])`, a module-level alias captured before the
-# patch, and any C-level call all walk straight past this, all three verified by cold review. That
+# patch, and any C-level call all walk straight past this, all three verified. That
 # bounds what the check below can claim, and the docstring says so rather than implying a sandbox.
 # Reading a file stays allowed: `derived_guard_files` must read workflow bodies.
 _ENUMERATORS = (
@@ -394,10 +394,10 @@ def test_no_derivation_ENUMERATES_the_filesystem(label, derive):
     returned. Reading is untouched, so a derivation may still parse the workflow bodies it scrapes
     for referenced scripts.
 
-    WHAT IT DOES NOT COVER. The boundary is not "synchronous", which is what two earlier drafts
-    said and what measurement disproved — a thread that outlives the `derive()` call but finishes
-    while its result is being drained IS caught, as is a `__del__` firing during that drain. The
-    boundary is mechanical rather than temporal: a call to one of the SPIES is observed, wherever and
+    WHAT IT DOES NOT COVER. The boundary is not "synchronous", which measurement disproves — a
+    thread that outlives the `derive()` call but finishes while its result is being drained IS
+    caught, as is a `__del__` firing during that drain. The boundary is mechanical rather than
+    temporal: a call to one of the SPIES is observed, wherever and
     whenever it happens in this process before the assertion below. "While the patch is active"
     under-claims it — the spy appends to a list that outlives the patch, so a reference captured
     during the window and invoked after it still records. What decides observation is whether the
diff --git a/scripts/tests/test_hook_fire_log.py b/scripts/tests/test_hook_fire_log.py
index 59676ab22..87b976333 100644
--- a/scripts/tests/test_hook_fire_log.py
+++ b/scripts/tests/test_hook_fire_log.py
@@ -60,9 +60,10 @@ SINK = REPO_ROOT / "scripts" / "hook-fire-log.sh"
 #
 # `{**os.environ}` at module level is the shape #785 shipped: a suite that snapshots the environment
 # once, at collection, and hands that stale mapping to every subprocess it launches. Because the
-# autouse isolation fixture runs at test SETUP, such a snapshot used to predate it and every hook
-# driven from it wrote to `$HOME/.cache/ersatztv/hook-fire/` — 58 records per run, with every
-# assertion green, since the fire-log library is fail-open by design.
+# autouse isolation fixture runs at test SETUP, such a snapshot PREDATES it. Before isolation was
+# installed at `pytest_configure` (pre-collection), every hook driven from that snapshot wrote to
+# `$HOME/.cache/ersatztv/hook-fire/` — 58 records per run, measured, with every assertion green,
+# since the fire-log library is fail-open by design.
 #
 # `test_the_suite_does_not_write_to_the_PRODUCTION_log` asserts this specimen is now SAFE, which is
 # the cross-suite claim that test has always made in its docstring and never checked in its body.
@@ -92,7 +93,7 @@ def hook_scripts() -> list[Path]:
     """THE POPULATION, from the GIT INDEX. Never a list, and never the filesystem (ersatztv#806).
 
     The filesystem is not an authoritative source: an untracked `.sh` dropped in `.claude/hooks/` —
-    a scratch copy, a half-written hook — used to enter this population and be demanded to carry
+    a scratch copy, a half-written hook — would enter this population and be demanded to carry
     instrumentation, reddening the suite on that checkout while CI, which never sees the file, stayed
     green. That is #778's third shape, and a guard that fails everywhere except where it runs trains
     its readers to ignore it.
@@ -130,14 +131,14 @@ def instrumentation_faults(text: str, name: str) -> list[str]:
     # the `[ -r ] && .` line untouched and disables all reporting silently — a mutation the first
     # version of this checker passed clean.
     #
-    # EVERY assignment, and EXACTLY ONE of them. Reading only the first is a hole cold review found
-    # and measured: a hook carrying the canonical self-located line and then a SECOND
+    # EVERY assignment, and EXACTLY ONE of them. Reading only the first is a hole, and it is
+    # MEASURED: a hook carrying the canonical self-located line and then a SECOND
     # `ETV_HOOK_FIRE_LIB=${SOME_OTHER_VAR:-…}/scripts/hook-fire-log.sh` passed this checker clean on
     # all 13 hooks, and the shell would source the LAST value. The sourcing line reads the variable's
     # final value, so the checker must judge every writer of it — checking the first is checking the
     # one the defect does not use.
     # THE AUTHORITY IS BYTE-IDENTITY, not a pattern — and that is a withdrawal, recorded rather than
-    # quietly performed. Three review rounds attacked a lexical rule over this line: `${VAR:-}`
+    # quietly performed. Three successive lexical rules over this line each fell: `${VAR:-}`
     # satisfied a containment test; then backticks and `$((…))`; then `$(printenv VAR)`, `$1`, `$?`,
     # an INDENTED or `export`ed reassignment further down, and `$'…'` quoting that makes the required
     # token literal rather than expanded. Every fix admitted the next shape, which is this repo's own
@@ -180,7 +181,7 @@ def instrumentation_faults(text: str, name: str) -> list[str]:
     # answering). Disarm an arm here with `pass`. `if False:` is safe on an arm with no `elif` after
     # it — `mutation_manifest.py` disarms byte-identity that way every run — but on the two begin-call
     # arms below it falls through to a `.group(1)` on None and reds with an AttributeError: a red for
-    # the wrong reason that reads like a proof, and cost this branch two review rounds. A
+    # the wrong reason that reads like a proof. A
     # hook carrying both canonical lines plus `ETV_HOOK_FIRE_DISABLE=1` trips exactly one fault, and
     # it is not byte-identity's, so a reader who sorts those into "already covered" deletes a live
     # detector.
@@ -221,8 +222,8 @@ def instrumentation_faults(text: str, name: str) -> list[str]:
         if "${BASH_SOURCE[0]}" not in value:
             faults.append(f"{name}: the sink path is not self-located from ${{BASH_SOURCE[0]}}: {value}")
 
-        # ...and MENTIONING `${BASH_SOURCE[0]}` is not the same as being DECIDED by it. Cold review
-        # measured the gap: `${ETV_HOOKS_ROOT:-$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../..")}`
+        # ...and MENTIONING `${BASH_SOURCE[0]}` is not the same as being DECIDED by it. The gap is
+        # MEASURED: `${ETV_HOOKS_ROOT:-$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../..")}`
         # — literally "the next `${SOME_OTHER_DIR:-…}`" the comment above says it stops — passed on
         # all 13 hooks, because the self-location sitting in the `:-` FALLBACK satisfied a
         # containment test while the environment still won whenever the variable was set. A
@@ -231,8 +232,8 @@ def instrumentation_faults(text: str, name: str) -> list[str]:
         # So the value must contain NO expansion at all beyond `${BASH_SOURCE[0]}` itself and the
         # `$(…)` command substitution the canonical line is MADE of. Four spellings can let something
         # outside this file choose the tree, and all four fail: `${…}`, a bare `$NAME`, an arithmetic
-        # `$((…))`, and a BACKTICK substitution — the last two found by self-audit rather than by a
-        # reviewer, and both slip past a `${…}`/`$NAME` test when `${BASH_SOURCE[0]}` also appears
+        # `$((…))`, and a BACKTICK substitution — the last two
+        # slip past a `${…}`/`$NAME` test when `${BASH_SOURCE[0]}` also appears
         # (`` `cat /tmp/root` `` names a tree while containing no `$` at all). Neither has any use in
         # this line, so refusing them costs nothing and "could not tell where this resolves from"
         # fails rather than passing quietly.
@@ -322,9 +323,9 @@ def test_the_population_is_not_empty():
 def test_the_stripper_removes_EXACTLY_the_preamble_and_nothing_else():
     """The A/B control must be the hook minus the instrumentation — no more, no less.
 
-    This compared `strip_instrumentation(hook)` against the hook at the merge base, which asserted
-    two unrelated things at once: that the stripper is exact, AND that no hook was edited in this PR
-    for any other reason. The second is not a property worth pinning — it went red the moment
+    Comparing `strip_instrumentation(hook)` against the hook at the merge base asserts
+    two unrelated things at once: that the stripper is exact, AND that no hook was edited on the
+    branch for any other reason. The second is not a property worth pinning — it went red the moment
     `pretooluse-bom-guard.sh` had a real defect fixed (`xxd`, absent on the CI runner, made it
     fail open) — and coupling them means a legitimate change reads as a broken control.
 
@@ -619,8 +620,8 @@ def test_the_husky_launched_population_is_not_empty():
 def _pushed_tree(tmp_path: Path, hook: Path, sink_body: str) -> Path:
     """A repo-SHAPED scratch tree holding this hook and a `scripts/hook-fire-log.sh` of `sink_body`.
 
-    The pair below used to make its relative launch from REPO_ROOT itself, which was wrong twice
-    over and cold review measured both: `prepush-rebase-check.sh` reaches `git fetch origin main` on
+    A relative launch from REPO_ROOT itself is wrong twice
+    over, and both were measured: `prepush-rebase-check.sh` reaches `git fetch origin main` on
     an empty ref list, so every suite run made a NETWORK CALL and rewrote `FETCH_HEAD` in the very
     checkout under test — the one ref this repo's process treats as the baseline — and
     `decisions-guard.sh` ran the full decisions validator over the live tree. A unit test must not
@@ -741,7 +742,7 @@ def test_a_LATER_reassignment_the_regex_cannot_see_is_DETECTED(hook):
 
     The diagnostic arms below it read `^ETV_HOOK_FIRE_LIB=(.*)$`, anchored at column zero, so an
     INDENTED reassignment inside an `if`, or an `export`ed one, is invisible to them while bash
-    executes it and the `. `-source line takes the LAST value. Cold review measured both passing a
+    executes it and the `. `-source line takes the LAST value. Both were MEASURED passing a
     checker that had just been "fixed" to read every assignment — which is what retired the pattern
     approach in favour of pinning the two canonical lines.
 
@@ -768,7 +769,7 @@ def test_the_NEXT_env_var_to_be_invented_is_DETECTED(hook):
     """THE MUTATION PROOF for the no-other-expansion arm, and the reason that arm exists.
 
     Banning `CLAUDE_PROJECT_DIR` by name only moves the defect to the next name. This is that shape,
-    and cold review measured it passing on all 13 hooks against the arm that merely required
+    and it was MEASURED passing on all 13 hooks against the arm that merely required
     `${BASH_SOURCE[0]}` to APPEAR: the self-location sits in the `:-` fallback, so the containment
     test is satisfied while the environment still decides whenever `$ETV_HOOKS_ROOT` is set.
 
@@ -807,7 +808,7 @@ def test_the_NEXT_env_var_to_be_invented_is_DETECTED(hook):
 # reach with a bare payload get a constructed positive case in `positive_cases()` below, and
 # `test_the_AB_is_not_VACUOUS_for_any_hook` refuses to let any hook rely on this matrix alone.
 #
-# Stated because the first version of this file claimed the opposite in three places: this matrix
+# MEASURED, not assumed: this matrix
 # alone produced empty-vs-empty comparisons for 8 of 13 hooks and a zero exit status for all 13, so
 # deleting the entire stdout replay left the differential test green for four hooks — two of which
 # issue `deny`. An A/B over silent allows proves transparency on the one path where there is nothing
@@ -1121,7 +1122,7 @@ def _normalise_stderr(err: bytes) -> bytes:
     """
     # The two fields are normalised TOGETHER, as one anchored prefix, not independently. A global
     # `line \d+:` substitution also rewrites application text that happens to contain that phrase,
-    # and cold review demonstrated it collapsing two genuinely different diagnostics ("highest
+    # and was DEMONSTRATED collapsing two genuinely different diagnostics ("highest
     # private fd line 0" vs "line 4") into one — hiding exactly the kind of fd-state difference this
     # comparison exists to catch.
     return re.sub(rb"(?m)^[^\s:]*/[^\s:]*\.sh: line \d+:", b"