feat(784): a doc records the end state — generalize the no-session-narrative rule #811
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d938493d5d |
style(784): clear ruff check on both new python files
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 12s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 20s
PR Gates / Docs update reminder (pull_request) Successful in 30s
PR Gates / decisions lifecycle (pull_request) Successful in 33s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 27s
Review verdict / Set review-verdict status (pull_request_target) Successful in 17s
PR Gates / Script tests (pytest) (pull_request) Successful in 5m10s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m48s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m24s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 6m38s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 10s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
review-verdict/h10 Review-verdict: MERGEABLE @ d938493 (base: main)
Round 7 verdict was MERGEABLE with one nit — an over-long comment line. Ruff found two more while I was there: UP031 (percent format) and S110 (a bare try/except/pass). The S110 is deliberate and stays: it guards the stdio reconfigure, which IS the never-fails invariant's own setup and so is the one place that must not raise. It is now noqa'd with that reason rather than left looking like an oversight. `ruff format` is deliberately NOT applied. This repo checks in no ruff config and 21 of its 35 tracked python files fail `ruff format --check`, so reformatting these two alone would diverge from every file around them — the deviation policy says match the established style. `ruff check` is clean, which is the half that finds defects. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
19e9d9e29c |
docs(784): the mnemonicPrefix note explained the right observation with the wrong cause
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 8s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 17s
PR Gates / Docs update reminder (pull_request) Successful in 15s
PR Gates / decisions lifecycle (pull_request) Successful in 16s
review-verdict/h10 Awaiting review verdict for 19e9d9e
Review verdict / Set review-verdict status (pull_request_target) Successful in 19s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 22s
PR Gates / Script tests (pytest) (pull_request) Successful in 4m34s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 9m14s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m15s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 6m3s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 9s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
Round 6 verdict was MERGEABLE with two follow-ups; both are one clause and
both are exactly this PR's subject, so they land here rather than in a
follow-up issue.
F1 I wrote that `diff.mnemonicPrefix` is "harmless only because --dst-prefix
beats it". The pin does beat it, but that is not why it is inert here.
Measured: git only uses mnemonic prefixes when a diff side is the worktree
or the index, and run_diff issues the three-dot `base...HEAD` form, where
git emits plain a/…b/ either way — with or without the pin.
git -c diff.mnemonicPrefix=true diff -U0 HEAD~1 -> +++ w/docs/f.md
git -c diff.mnemonicPrefix=true diff -U0 HEAD~1...HEAD -> +++ b/docs/f.md
A right observation attracting a wrong "because" is a shape this repo has
on record, and it is worse in a comment whose whole job is to stop a future
reader re-deriving something.
F2 the UNPROVEN list read as exhaustive while three clauses sat on neither
side. Each is now listed and each was disarmed to confirm the sort — the
`+++ /dev/null` arm, the malformed-`@@` arm and the stderr relay all
survive, matching the UNPROVEN claim. Both lists now say they ENUMERATE,
so a clause on neither has simply not been measured, rather than being
implied covered.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
||
|
|
ff03812814 |
docs(784): the coverage boundary mis-sorted two pins — sort by measurement, not category
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 9s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 21s
PR Gates / Docs update reminder (pull_request) Successful in 20s
PR Gates / decisions lifecycle (pull_request) Successful in 26s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 26s
review-verdict/h10 Awaiting review verdict for ff03812
Review verdict / Set review-verdict status (pull_request_target) Successful in 31s
PR Gates / Script tests (pytest) (pull_request) Successful in 4m25s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 9m0s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m26s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 6m2s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 7s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 5s
The boundary sentence I wrote last round said "the PARSE path and the FORMAT PINS carry mutation proofs". Two format pins do not: `-U0` (the context arm handles any -U, so removing it reddens nothing) and the GIT_CONFIG_GLOBAL/ SYSTEM/NOSYSTEM overrides — which the script's own comment already disclaims in as many words, so the record asserted a proof the file it describes denies, two files apart. My own round-3 mutation run had shown both surviving; I wrote the category anyway. `--src-prefix` is a third. Fixed by naming clauses instead of a category, because the category is where the mis-sort hid. Then verified the sort rather than asserting it: all 19 clauses the sentence sorts were disarmed individually — the 12 it calls proven were witnessed red, the 7 it calls unproven were witnessed green. The sentence now matches a measurement. Two stale universals removed with it. `docs/ci-cd.md` said "one honest gap" where the boundary names seven; it now points at the boundary rather than carrying its own count. And the FORMAT_KNOBS header comment still said "every knob that reshapes the output this script parses" — the exact universal that was blocked in `mechanics:` last round and simply moved one file over. `diff.mnemonicPrefix` is named there as a live counter-example: it reshapes the header, has no row, and is harmless only because --dst-prefix beats it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
b60c0b4c14 |
docs(784): three false prose claims, and the coverage boundary written down once
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 8s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 20s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 24s
PR Gates / Docs update reminder (pull_request) Successful in 35s
PR Gates / decisions lifecycle (pull_request) Successful in 28s
Review verdict / Set review-verdict status (pull_request_target) Failing after 2s
PR Gates / Script tests (pytest) (pull_request) Successful in 4m59s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Canceled after 4m34s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Canceled after 0s
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Canceled after 0s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Canceled after 0s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Canceled after 0s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Canceled after 0s
Round 4 confirmed the git-format channel is genuinely closed — an independent
46-configuration matrix across two modes found zero false cleans, and all
eight claimed mutant kills reproduced. What it blocked on was three sentences,
in a PR whose whole subject is that a doc asserting a proof it lacks is what a
later reader trusts instead of re-checking. Mine did it three times.
M-C the workflow comment named "a checkout hiccup" as the motivating failure
and then left Checkout unguarded, so its closing claim was false of the
code it annotated. Checkout is now stated as deliberately OUT of scope: a
job that cannot run is a different failure from an advisory one that ran
and disagreed. The comment also records what I measured on the real
runner (PR#811, run 2179) rather than what I assumed — both steps green
under continue-on-error, job success, commit status success.
M-F `# -U0 is what the line arithmetic assumes` is false: removing -U0
reddens nothing, because the context arm handles any -U. The row pins
that a configured diff.context cannot beat the CLI, and now says so.
N-E `mechanics:` claimed EVERY knob that can reshape the output has a row.
Six knobs do not — they are harmless, which is why. Worse, the claim is
unprovable in principle, which is the exact argument this fix used to
close the channel instead of enumerating it.
And the reviewer's larger point, taken: rounds 3 and 4 each converted "N
load-bearing clauses have no mutant" into "N kills", and round 4 produced six
more from the same well. That is two rounds of one mechanism, so the answer is
to stop enumerating clauses, not to add five more tests. The record now
carries the COVERAGE BOUNDARY in one sentence — the parse path and the format
pins are mutation-proven; the error and degradation arms are defensive and
unproven — and the two inventories point at it instead of repeating a flat
"exits 0 on every path".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
||
|
|
995b900a00 |
fix(784): close the git-format channel, and kill eight mutants that had survived
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 8s
PR Gates / Docs update reminder (pull_request) Successful in 10s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 16s
PR Gates / decisions lifecycle (pull_request) Successful in 15s
review-verdict/h10 Awaiting review verdict for 995b900
Review verdict / Set review-verdict status (pull_request_target) Successful in 13s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 22s
PR Gates / Script tests (pytest) (pull_request) Successful in 4m22s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m44s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Canceled after 5m35s
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Canceled after 0s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Canceled after 0s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Canceled after 0s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Canceled after 0s
Round 3. Both the reviewer and I independently found the SAME defect — `color.diff=always` / `color.ui=always` injects ANSI escapes and every parse arm misses, so a real hit reports `scanned 0 file(s)`. That is the THIRD gitconfig knob in three rounds to turn a hit into a clean-looking run (core.quotePath, then diff.dstPrefix, now color.*). Three instances of one mechanism is the point where naming a fourth knob is the wrong move, so the channel is closed rather than the variant: the user's and system's config files are removed from the picture via GIT_CONFIG_GLOBAL/ SYSTEM/NOSYSTEM, which also covers knobs nobody has named; every knob that IS named is pinned on the command line where it beats a repo-local config too; and each has a row in FORMAT_KNOBS in the test file so the next one found gets a row instead of a fourth round. The now-redundant `color.ui=never` -c pin was dropped — a second mechanism on a condition another mechanism already proves is the duplicate-guard shape. H-2 was a docstring of mine asserting a proof the script's own comment says does not exist, and the reviewer showed it is false: removing the `+++ /dev/null` arm reddens nothing. The arm is defensive; both places now say so. A docstring claiming a proof it lacks is what a later reader trusts instead of re-checking. Eight clauses were load-bearing and unwitnessed. Each is now disarmed and witnessed red: --no-color, --no-ext-diff, subprocess errors="replace" (a UTF-8 doc under an ascii locale silently emptied the whole scan while exiting 0), the `diff --git` in_hunk reset (every file after the first dropped from a multi-file diff — which is every real CI run), the SCANNED-NOTHING return, the population count, re.IGNORECASE, and the core.quotePath pin. Two of my own assertions were vacuous and are fixed rather than kept: `assert "nothing to flag" not in stdout` named a string that occurs nowhere in this script, so it could never fail; and the LC_ALL=C stdio case passed against the pre-fix script too (PEP 540), reading as a second witness where there was one. M-6: the setup-python step added last round could itself redden the advisory job. `continue-on-error` on both steps — a script returning 0 does not keep a JOB green. The record now records the unhandled-exception arm as UNPROVEN rather than implying the whole invariant is tested. Proves: scripts/tests/test_check_doc_narrative.py Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
c635a4d54d |
fix(784): close the three re-review blockers, and drop two clauses I could not prove
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 9s
PR Gates / decisions lifecycle (pull_request) Successful in 17s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 21s
PR Gates / Docs update reminder (pull_request) Successful in 20s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 17s
review-verdict/h10 Awaiting review verdict for c635a4d
Review verdict / Set review-verdict status (pull_request_target) Successful in 16s
PR Gates / Script tests (pytest) (pull_request) Successful in 4m17s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m37s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m15s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Canceled after 2m13s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Canceled after 0s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Canceled after 0s
Re-review confirmed all seven earlier findings fixed and blocked on three new ones. Each reproduced before acting. H3 the never-fails invariant exited 1 on a clean ASCII repo: the summary line and the bare-except fallback both carry U+2014, so under ascii/latin-1 stdio the code guaranteeing exit 0 was itself what raised. stdout/stderr are reconfigured with errors="replace" at import. Not reachable on the CI image (PEP 540), but the invariant is asserted without qualification in four places, and the earlier B1 was upheld on exactly that standard. H2 four shipped references to the deleted .sh remained — including the record's own ENFORCEMENT clause and the generated catalog a lookup resolves to. A record naming a path that does not exist at its own head is worse than no record. M5 a stray `diff.dstPrefix` produced `scanned 0 file(s)` on a file that plainly contained a hit. Pinned --src-prefix/--dst-prefix/--no-ext-diff: closing the channel, not the one variant that was demonstrated. M4 python3 is not guaranteed on the bare `small` lane — docs/ci-cd.md says so 36 lines below the section this PR rewrote, and every other python-using job there declares setup-python. A missing interpreter is exit 127, a RED advisory job, which is the one thing this step must never be. Then I mutation-checked my own new tests, and two of them were vacuous: - `--diff-filter=d` was a SECOND mechanism for excluding deletions, and neither it nor the `+++ /dev/null` arm can be witnessed failing, because a deletion contributes no added lines either way. Removed the duplicate and labelled the survivor defensive rather than load-bearing. - the rename test restated a git default. `diff.renames` is true by default, so it passed with or without --find-renames. It now sets the config to false, which is what makes that flag load-bearing and the test a proof. Every remaining load-bearing clause was disarmed individually and witnessed red: core.quotePath, the hunk-state parse, the no-newline arm, splitlines, the SCANNED-NOTHING branch, the stdio reconfigure, the prefix pin and --find-renames. The previous commit's `Proves:` trailer sat in its own paragraph, so git parsed no such trailer and prove-fix reported that nothing was verified. It belongs in the same block as the other trailers. Proves: scripts/tests/test_check_doc_narrative.py Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
779f1b2cb3 |
fix(784): replace the shell diff parser after cold review demonstrated four defects in it
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 10s
PR Gates / Docs update reminder (pull_request) Successful in 15s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 21s
PR Gates / decisions lifecycle (pull_request) Successful in 18s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 14s
review-verdict/h10 Awaiting review verdict for 779f1b2
Review verdict / Set review-verdict status (pull_request_target) Successful in 13s
PR Gates / Script tests (pytest) (pull_request) Successful in 5m16s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m28s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m15s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 6m1s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 8s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 5s
Cold review (BLOCKED) falsified three of the four things the PR asked it to
attack. Reproduced each before acting:
B1 the script could exit NON-ZERO on two reachable paths, against an
invariant asserted absolutely in four places
H1 an unresolvable base ref printed "nothing to flag" and exited 0, having
scanned zero files — indistinguishable from a clean run
M1 `'\\ No newline'*` never matched (two literal backslashes inside single
quotes; git emits one), so the marker counted as content
M2 an added line whose own text began `++ ` was eaten by the `+++ ` header
arm. Verified against the real predecessor: it reported line 2 where the
truth is 3.
M3 core.quotePath hid non-ASCII paths from BOTH modes, silently
M4 --all dropped a final unterminated line
Those are one mistake at six sites: deciding what a diff line IS from its
prefix, with no hunk state. Patching them individually is the shape that does
not converge here, so the mechanism is replaced — check-doc-narrative.py
parses with hunk state, uses core.quotePath=false, keeps rename detection, and
returns 0 from a bare `except` as the last line of defence.
H2 said TOOLING/NONE is the classification under which no proof is ever owed,
and that a 99-line parser shipped with four demonstrated defects a fixture
directory would have caught. Correct: scripts/tests/test_check_doc_narrative.py
now asserts exit 0 per argument shape, compares every reported line number
against truth read back off disk (never a hand-written number), covers each
defect above, and carries a mutation proof that disarms PATTERNS so the suite
cannot pass on a detector that finds nothing.
M5/M6: docs/ci-cd.md now describes both steps of the job, and the record's
mechanics: states the detector's population instead of implying it matches the
rule's — skills and nested markdown outside docs/ are out of scope.
Proves: scripts/tests/test_check_doc_narrative.py
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
||
|
|
d0637a0ec2 |
fix(784): inventory rows for the new advisory script, and a robust diff-header parse
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 8s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 19s
PR Gates / Docs update reminder (pull_request) Successful in 13s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 12s
PR Gates / decisions lifecycle (pull_request) Successful in 24s
review-verdict/h10 Awaiting review verdict for d0637a0
Review verdict / Set review-verdict status (pull_request_target) Successful in 11s
PR Gates / Script tests (pytest) (pull_request) Successful in 5m19s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m16s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m3s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 5m57s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 9s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
Both inventory guards were witnessed RED before these rows existed: test_the_inventory_covers_exactly_the_guards_that_exist and test_every_in_scope_file_has_a_row_and_every_row_names_a_real_file each named scripts/check-doc-narrative.sh as unclassified. The `tail -n +5` on `git diff` assumed a four-line file header, which is wrong for a rename or a mode change; the extra header lines would then be counted as content until the first `@@` reset the counter. Match the header lines explicitly instead, `+++`/`---` before the `+*`/`-*` arms. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
be2f85b79b |
feat(784): generalize the no-session-narrative rule beyond the kickoff file
The rule existed, correctly stated, scoped to one file: a paragraph of narrative in the kickoff handoff is a tax paid by every session that pastes it. That reason is file-specific. The general one is broader and applies to every doc: a reader coming cold never saw the earlier draft, so "we previously got this wrong" carries nothing they can act on. - docs/decisions/records/docs/no-session-narrative.md — the rule, the who-benefits test, the named destination (the commit message), and the carve-out that keeps it from over-applying. - The kickoff file now cites the general rule and keeps only its extra, file-specific cost on top. - scripts/check-doc-narrative.sh + a docs-reminder step — ADVISORY. It exits 0 on every path. A narrative detector is a string predicate over prose, and defect-shapes-773 §4 argues that class must never be load-bearing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |