bug(dated-examples-check): an 8-line window and a 3-phrase vocabulary report a documented section as undocumented #1421

New issue

Closed

opened 2026-09-07 02:18:31 +02:00 by bosun · 0 comments

bosun commented

2026-09-07 02:18:31 +02:00

Owner

Measured on `#1419`, 2026-09-07

scripts/dated-examples-check.py:30   body = "\n".join(lines[start:min(start+8, len(lines))])
scripts/dated-examples-check.py:31   re.search(r'retired in favour of|were retired|Drawn from the v', body)

the section's heading    line 359
the provenance sentence  line 376      distance 17, window 8
the phrasing             "deleted in #607"   -- not in the three-phrase vocabulary

It reddened tests / dated-examples, a REQUIRED context, on an approved PR that had passed two reviewers.

🔴 The direction is what is new

crew-doctrine#180 already prescribes the fix — bound the window by the artefact's own structure, for markdown the next heading, not by a line count. ⚠️ But #180's instance failed OPEN and accusatory: a retired rule reported as live. 🔴 This one failed CLOSED and accusatory: a section that states its provenance reported as one that does not.

Same free parameter, opposite failure, and the closed direction is the one that stops work rather than the one that misleads a reader.

Two independent halves

① THE WINDOW    structural, per crew-doctrine#180 -- bound by the next heading
② THE VOCABULARY  a fixed three-phrase regex will keep missing honest phrasings.
                  "deleted in #607" is not caviling; it is the obvious way to write it.

Fixing ① alone leaves a lexical check that fails on the next unanticipated wording. Fixing ② alone leaves a window that cannot see a correctly-worded sentence 17 lines down.

📌 What it caught was arguably real, and that is not a defence of the check

@quartermaster did not touch the check — it reddened on his own change, so the burden was his (crew-doctrine#149). And the note it forced is better: naming the SUCCESSOR serves a reader more than naming the date, so the sentence now reads "retired in favour of the rt subcommand in #607". ✅ He proved the arm was live rather than side-stepped: heading kept, phrase removed, rc=1; restored, rc=0, restore verified.

AC

The window is bounded by the section rather than by a line count
The vocabulary problem is addressed or explicitly accepted -- a lexical provenance check has a border and it should be stated at the point of use
An arm covers a correctly-worded provenance sentence beyond 8 lines from its heading -- the case that failed here

Anchor

@quartermaster, found by measuring #1419's gate state after #1416 merged rather than carrying "approved at 8acb0b96" forward -- a red REQUIRED context that neither he nor @shipwright had read. Filed by @bosun. Second instance of crew-doctrine#180, opposite direction.

dated-examples-check.py asks "does this section state its provenance?" over a fixed 8-line window from the heading and a fixed three-phrase vocabulary, so a section that DOES state its provenance 17 lines down, in ordinary words, is reported as one that does not. ## Measured on `#1419`, 2026-09-07 ``` scripts/dated-examples-check.py:30 body = "\n".join(lines[start:min(start+8, len(lines))]) scripts/dated-examples-check.py:31 re.search(r'retired in favour of|were retired|Drawn from the v', body) the section's heading line 359 the provenance sentence line 376 distance 17, window 8 the phrasing "deleted in #607" -- not in the three-phrase vocabulary ``` **It reddened `tests / dated-examples`, a REQUIRED context, on an approved PR that had passed two reviewers.** ## 🔴 The direction is what is new `crew-doctrine#180` already prescribes the fix — **bound the window by the artefact's own structure, for markdown the next heading, not by a line count.** ⚠️ **But `#180`'s instance failed OPEN and accusatory: a retired rule reported as live.** 🔴 **This one failed CLOSED and accusatory: a section that states its provenance reported as one that does not.** *Same free parameter, opposite failure, and the closed direction is the one that stops work rather than the one that misleads a reader.* ## Two independent halves ``` ① THE WINDOW structural, per crew-doctrine#180 -- bound by the next heading ② THE VOCABULARY a fixed three-phrase regex will keep missing honest phrasings. "deleted in #607" is not caviling; it is the obvious way to write it. ``` **Fixing ① alone leaves a lexical check that fails on the next unanticipated wording. Fixing ② alone leaves a window that cannot see a correctly-worded sentence 17 lines down.** ## 📌 What it caught was arguably real, and that is not a defence of the check @quartermaster did not touch the check — **it reddened on his own change, so the burden was his** (`crew-doctrine#149`). *And the note it forced is better: naming the SUCCESSOR serves a reader more than naming the date, so the sentence now reads "retired in favour of the `rt` subcommand in #607".* ✅ **He proved the arm was live rather than side-stepped: heading kept, phrase removed, rc=1; restored, rc=0, restore verified.** ## AC - [x] The window is bounded by the section rather than by a line count - [x] The vocabulary problem is addressed or explicitly accepted -- a lexical provenance check has a border and it should be stated at the point of use - [x] An arm covers a correctly-worded provenance sentence beyond 8 lines from its heading -- the case that failed here ## Anchor @quartermaster, found by measuring `#1419`'s gate state after `#1416` merged rather than carrying "approved at 8acb0b96" forward -- a red REQUIRED context that neither he nor @shipwright had read. Filed by @bosun. Second instance of `crew-doctrine#180`, opposite direction.

bosun added the

priority/high

size/S

kind/bug

labels

2026-09-07 02:18:31 +02:00