Stacked on #543 (this branch is rebased onto that PR's head, so it needs no further rebase once #543 lands).
The premise inverted
Timothy asked why the kickoff handoff doc stores historical narrative when it should be instructions. It shouldn't — its own lore section is chartered as "STANDING workflow/orchestration rules only" with the why belonging in docs/decisions.md.
I assumed that meant the narrative was duplicated and could be deleted in favour of pointers. An inventory of every bullet against the whole decision corpus said otherwise:
Coverage
Count
Fully covered by an existing record
~8
PARTIAL — cause recorded, actionable rule missing
11
NONE — substance nowhere in the corpus
19
That one file was the only copy of the mandatory independent-review rubric, the entire CI-triage vocabulary (killed job vs cancelled vs infra-shaped red), the build-concurrency/RAM policy, the H12 session-end audit, the plumbing-merge recipe, and more. Pruning first would have destroyed them — the doc was load-bearing, not bloat.
So: records first, prune second
1. New topic file docs/decisions/workflow-process.md — 32 records (ci.*, process.*, testing.*) covering every NONE and PARTIAL the inventory found. Includes ci.gitea-milestone-filter-noop, whose only copy was the archived selector section this PR deletes: GET /issues?milestones=<name> silently returns the whole open-issue list when the milestone title contains : or +, which every milestone title here does.
2. Then the prune. HARD CONSTRAINTS and the lore section become one/two-line rules, each citing the decision key: that holds its evidence; the 40-line "Archived — do not follow" section is gone. 636 → 354 lines.
3. Corpus budget re-baselined 4800 → 5600, with the reason in the code: the corpus grew ~525 lines because knowledge moved into it, which is the system working, not drift. The comment explicitly forbids raising it again for genuinely new records. Flagging plainly that this is me moving a guard I was subject to — the reviewer was asked to judge whether that is honest or papering over bloat, and concluded the arithmetic matches the claim with ~430 lines of slack left.
Verification
Independent cold adversarial review, tasked with the single question "was any actionable knowledge destroyed?" — verdict MERGEABLE, no Blocker/High: "I found no deleted actionable fact without a surviving home."
It extracted the full 636-line predecessor, walked every removed bullet against the new records, the pre-existing corpus and the scripts, confirmed all 38 cited keys resolve, and spot-checked 10+ records verbatim against the source (the BOM xxd loop and bash -c/mapfile recipe, the RAM thresholds, the Gitea cancel 404s, the codex exec flags, the plumbing-merge sequence, the vitest run-686 timeout, the e2e READY_LINE, the milestone-filter recipe, the shared-tree incident timestamps).
Findings folded in: two dangling "see the archived section below" pointers — a real defect in a file pasted verbatim into every kickoff — and the explicit "file a tracked issue for a deferral" instruction, restored. One record's closing sentence about the dependencies API had no source in the deleted text; I traced it to an earlier revision of the handoff doc (f93458c7) where it was dropped by a later prune rather than disproved, and cited that provenance in the record rather than leaving an unsourced claim.
decisions_validate.py OK, catalog regenerated, no duplicate keys.
fixes #542
Stacked on #543 (this branch is rebased onto that PR's head, so it needs no further rebase once #543 lands).
## The premise inverted
Timothy asked why the kickoff handoff doc stores historical narrative when it should be instructions. It shouldn't — its own lore section is chartered as "STANDING workflow/orchestration rules only" with the why belonging in `docs/decisions.md`.
I assumed that meant the narrative was *duplicated* and could be deleted in favour of pointers. An inventory of every bullet against the whole decision corpus said otherwise:
| Coverage | Count |
|---|---|
| Fully covered by an existing record | ~8 |
| **PARTIAL** — cause recorded, actionable rule missing | 11 |
| **NONE** — substance nowhere in the corpus | 19 |
That one file was the **only** copy of the mandatory independent-review rubric, the entire CI-triage vocabulary (killed job vs cancelled vs infra-shaped red), the build-concurrency/RAM policy, the H12 session-end audit, the plumbing-merge recipe, and more. Pruning first would have destroyed them — the doc was load-bearing, not bloat.
## So: records first, prune second
**1.** New topic file `docs/decisions/workflow-process.md` — **32 records** (`ci.*`, `process.*`, `testing.*`) covering every NONE and PARTIAL the inventory found. Includes `ci.gitea-milestone-filter-noop`, whose only copy was the archived selector section this PR deletes: `GET /issues?milestones=<name>` silently returns the **whole** open-issue list when the milestone title contains `:` or `+`, which every milestone title here does.
**2.** Then the prune. HARD CONSTRAINTS and the lore section become one/two-line rules, each citing the decision `key:` that holds its evidence; the 40-line "Archived — do not follow" section is gone. **636 → 354 lines.**
**3.** Corpus budget re-baselined 4800 → 5600, with the reason in the code: the corpus grew ~525 lines because knowledge **moved** into it, which is the system working, not drift. The comment explicitly forbids raising it again for genuinely new records. Flagging plainly that this is me moving a guard I was subject to — the reviewer was asked to judge whether that is honest or papering over bloat, and concluded the arithmetic matches the claim with ~430 lines of slack left.
## Verification
Independent cold adversarial review, tasked with the single question "was any actionable knowledge destroyed?" — verdict **MERGEABLE**, no Blocker/High: *"I found no deleted actionable fact without a surviving home."*
It extracted the full 636-line predecessor, walked every removed bullet against the new records, the pre-existing corpus and the scripts, confirmed all 38 cited keys resolve, and spot-checked 10+ records verbatim against the source (the BOM `xxd` loop and `bash -c`/`mapfile` recipe, the RAM thresholds, the Gitea cancel 404s, the `codex exec` flags, the plumbing-merge sequence, the vitest run-686 timeout, the e2e `READY_LINE`, the milestone-filter recipe, the shared-tree incident timestamps).
Findings folded in: two dangling "see the archived section below" pointers — a real defect in a file pasted verbatim into every kickoff — and the explicit "file a tracked issue for a deferral" instruction, restored. One record's closing sentence about the dependencies API had no source in the deleted text; I traced it to an earlier revision of the handoff doc (`f93458c7`) where it was dropped by a later prune rather than disproved, and cited that provenance in the record rather than leaving an unsourced claim.
`decisions_validate.py` OK, catalog regenerated, no duplicate keys.
A session was handed docs/handoffs/chicorytv-issue-queue.md pasted out of
/Users/timothy/ersatztv while that tree was 81 commits behind, so it still
described the queue protocol #520 retired the day before (read tracker
command was ever run against that tree, so every existing "never read its
HEAD" guard was irrelevant: a stale checkout serves stale FILES, and docs
are what a kickoff depends on. Nothing broke only because selection went
through scripts/select-queue.sh.
The lore bullet on that tree already prescribed the shape of the fix for
its earlier failure modes — "a design flaw, not a discipline failure; a
check does not stay true" — so this removes the stale condition instead of
adding another check.
scripts/refresh-shared-checkout.sh fast-forwards the tree to origin/main
and reinstalls web/node_modules when the lockfile moved. It is deliberately
timid: it refuses and changes nothing when the tree is not on main, is
dirty, is ahead, or is mid-rebase/merge, and it never switches branches,
stashes or discards. A NO-OP is a normal outcome.
Uses npm ci rather than npm install — the first version used install,
which rewrote package-lock.json and left the tree dirty, i.e. the exact
state the next run refuses on, so it would have disabled itself after one
use. Asserts the tree is clean at exit.
refs #541
Timothy asked why the kickoff handoff doc stores historical narrative when
it should be instructions. It shouldn't — its own lore section is chartered
as "STANDING workflow/orchestration rules only" with the why belonging in
docs/decisions.md. But an inventory of every bullet against the decision
corpus inverted the premise: only ~8 of ~38 were actually covered. 19 had
no record anywhere and 11 more were half-covered, so that single file was
the ONLY copy of the mandatory review rubric, the whole CI-triage
vocabulary, the build-concurrency policy, the H12 session-end audit, and
the plumbing-merge recipe. Pruning first would have destroyed them.
So the records come first. New topic file docs/decisions/workflow-process.md
carries 32 records (ci.*, process.*, testing.*) covering every NONE and
PARTIAL the inventory found, including the Gitea `?milestones=` no-op bug
whose only copy was the archived selector section this prune deletes.
Only then the prune: HARD CONSTRAINTS and the lore section become one- or
two-line rules, each citing the decision key that holds its evidence, and
the 40-line "Archived — do not follow" section is gone. 636 -> 353 lines,
with every cited key verified to resolve against the corpus.
The aggregate corpus budget is re-baselined 4800 -> 5600 with the reason in
the code: the corpus grew because knowledge MOVED into it, which is the
system working, not drift.
refs #542
Independent cold adversarial review, scoped to the one question that could make this change harmful — was any actionable knowledge destroyed? Verdict MERGEABLE, no Blocker/High.
Method it executed (not eyeballed): extracted the full 636-line predecessor via git show, walked every removed bullet and constraint fact-by-fact against docs/decisions/workflow-process.md, the pre-existing corpus and the scripts, and reported anything without a surviving home. Its conclusion: "I found no deleted actionable fact without a surviving home."
Key resolution: all 38 cited keys resolve to live records; validator exit 0; no duplicate keys across the corpus.
Accuracy, 10+ records spot-checked against the source, verbatim where it matters: the BOM xxd loop and the bash -c/mapfile recipe (byte-identical, including the corrected "--include DOES work" framing and the od false-clean warning); codex exec flags plus the gpt-5.1-codex-mini HTTP 400 and the models_cache.json rollover step; build concurrency (3–4 builds, memory_pressure -Q <20%/<10%, M4/10-core/16GB, the 8–9-way crash); the Gitea cancel 404s including the dispatch_workflow exception and the slot-drain correction; the plumbing-merge sequence; vitest run 686 / 5s / 15s; the e2e READY_LINE pair; killed-job triage including UTC-vs-UTC+2 and the refs/heads/v4 noise; the shared-tree incident timestamps.
Deleted facts whose home is elsewhere (correctly not duplicated into the new file): the #231/#250 stress-loop and negative-control recipe lives in ffmpeg.work-ahead-slot-atomic; the lazy Map lesson in release.live-e2e-required; ETV_SKIP_REBASE_CHECK and regenerate-don't-hand-resolve in release.format-as-you-touch-rebase; re-review-the-fix-commit in release.review-verdict-gate. It also confirmed the old doc's "not yet in decisions.md" note on ResponseHeadersRead was itself stale.
Budget: judged honest — pre-commit ≈4642, post-commit 5167, growth ≈525 matching the "~530 moved" claim, ~430 slack left, and the in-code comment forbids re-raising for new records.
Standalone kickoff: still functions; nothing under-specified to unusability.
Fixed from its findings: two dangling "see the archived section below" pointers (Medium — a real defect in a file pasted verbatim into every kickoff), and the explicit file-a-tracked-issue-for-a-deferral instruction, restored. Its one provenance query — a dependencies-API sentence with no source in the deleted text — I traced to commit f93458c7, an earlier revision of this same doc where it was dropped by a later prune rather than disproved; the record now cites that provenance instead of asserting it bare.
Independent cold adversarial review, scoped to the one question that could make this change harmful — **was any actionable knowledge destroyed?** Verdict **MERGEABLE**, no Blocker/High.
Method it executed (not eyeballed): extracted the full 636-line predecessor via `git show`, walked every removed bullet and constraint fact-by-fact against `docs/decisions/workflow-process.md`, the pre-existing corpus and the scripts, and reported anything without a surviving home. Its conclusion: *"I found no deleted actionable fact without a surviving home."*
- **Key resolution:** all 38 cited keys resolve to live records; validator exit 0; no duplicate keys across the corpus.
- **Accuracy, 10+ records spot-checked against the source, verbatim where it matters:** the BOM `xxd` loop and the `bash -c`/`mapfile` recipe (byte-identical, including the corrected "`--include` DOES work" framing and the `od` false-clean warning); `codex exec` flags plus the `gpt-5.1-codex-mini` HTTP 400 and the `models_cache.json` rollover step; build concurrency (3–4 builds, `memory_pressure -Q` <20%/<10%, M4/10-core/16GB, the 8–9-way crash); the Gitea cancel 404s including the `dispatch_workflow` exception and the slot-drain correction; the plumbing-merge sequence; vitest run 686 / 5s / 15s; the e2e `READY_LINE` pair; killed-job triage including UTC-vs-UTC+2 and the `refs/heads/v4` noise; the shared-tree incident timestamps.
- **Deleted facts whose home is elsewhere** (correctly not duplicated into the new file): the #231/#250 stress-loop and negative-control recipe lives in `ffmpeg.work-ahead-slot-atomic`; the lazy `Map` lesson in `release.live-e2e-required`; `ETV_SKIP_REBASE_CHECK` and regenerate-don't-hand-resolve in `release.format-as-you-touch-rebase`; re-review-the-fix-commit in `release.review-verdict-gate`. It also confirmed the old doc's "not yet in decisions.md" note on `ResponseHeadersRead` was itself stale.
- **Budget:** judged honest — pre-commit ≈4642, post-commit 5167, growth ≈525 matching the "~530 moved" claim, ~430 slack left, and the in-code comment forbids re-raising for new records.
- **Standalone kickoff:** still functions; nothing under-specified to unusability.
Fixed from its findings: two dangling "see the archived section below" pointers (Medium — a real defect in a file pasted verbatim into every kickoff), and the explicit file-a-tracked-issue-for-a-deferral instruction, restored. Its one provenance query — a dependencies-API sentence with no source in the deleted text — I traced to commit `f93458c7`, an earlier revision of this same doc where it was dropped by a later prune rather than disproved; the record now cites that provenance instead of asserting it bare.
Review-verdict: MERGEABLE @ 12e5c3d26f60f0df2711ea8deac9804bbb51fb30
timothy
merged commit 9713bae498 into main2026-07-21 20:43:06 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
fixes #542
Stacked on #543 (this branch is rebased onto that PR's head, so it needs no further rebase once #543 lands).
The premise inverted
Timothy asked why the kickoff handoff doc stores historical narrative when it should be instructions. It shouldn't — its own lore section is chartered as "STANDING workflow/orchestration rules only" with the why belonging in
docs/decisions.md.I assumed that meant the narrative was duplicated and could be deleted in favour of pointers. An inventory of every bullet against the whole decision corpus said otherwise:
That one file was the only copy of the mandatory independent-review rubric, the entire CI-triage vocabulary (killed job vs cancelled vs infra-shaped red), the build-concurrency/RAM policy, the H12 session-end audit, the plumbing-merge recipe, and more. Pruning first would have destroyed them — the doc was load-bearing, not bloat.
So: records first, prune second
1. New topic file
docs/decisions/workflow-process.md— 32 records (ci.*,process.*,testing.*) covering every NONE and PARTIAL the inventory found. Includesci.gitea-milestone-filter-noop, whose only copy was the archived selector section this PR deletes:GET /issues?milestones=<name>silently returns the whole open-issue list when the milestone title contains:or+, which every milestone title here does.2. Then the prune. HARD CONSTRAINTS and the lore section become one/two-line rules, each citing the decision
key:that holds its evidence; the 40-line "Archived — do not follow" section is gone. 636 → 354 lines.3. Corpus budget re-baselined 4800 → 5600, with the reason in the code: the corpus grew ~525 lines because knowledge moved into it, which is the system working, not drift. The comment explicitly forbids raising it again for genuinely new records. Flagging plainly that this is me moving a guard I was subject to — the reviewer was asked to judge whether that is honest or papering over bloat, and concluded the arithmetic matches the claim with ~430 lines of slack left.
Verification
Independent cold adversarial review, tasked with the single question "was any actionable knowledge destroyed?" — verdict MERGEABLE, no Blocker/High: "I found no deleted actionable fact without a surviving home."
It extracted the full 636-line predecessor, walked every removed bullet against the new records, the pre-existing corpus and the scripts, confirmed all 38 cited keys resolve, and spot-checked 10+ records verbatim against the source (the BOM
xxdloop andbash -c/mapfilerecipe, the RAM thresholds, the Gitea cancel 404s, thecodex execflags, the plumbing-merge sequence, the vitest run-686 timeout, the e2eREADY_LINE, the milestone-filter recipe, the shared-tree incident timestamps).Findings folded in: two dangling "see the archived section below" pointers — a real defect in a file pasted verbatim into every kickoff — and the explicit "file a tracked issue for a deferral" instruction, restored. One record's closing sentence about the dependencies API had no source in the deleted text; I traced it to an earlier revision of the handoff doc (
f93458c7) where it was dropped by a later prune rather than disproved, and cited that provenance in the record rather than leaving an unsourced claim.decisions_validate.pyOK, catalog regenerated, no duplicate keys.Independent cold adversarial review, scoped to the one question that could make this change harmful — was any actionable knowledge destroyed? Verdict MERGEABLE, no Blocker/High.
Method it executed (not eyeballed): extracted the full 636-line predecessor via
git show, walked every removed bullet and constraint fact-by-fact againstdocs/decisions/workflow-process.md, the pre-existing corpus and the scripts, and reported anything without a surviving home. Its conclusion: "I found no deleted actionable fact without a surviving home."xxdloop and thebash -c/mapfilerecipe (byte-identical, including the corrected "--includeDOES work" framing and theodfalse-clean warning);codex execflags plus thegpt-5.1-codex-miniHTTP 400 and themodels_cache.jsonrollover step; build concurrency (3–4 builds,memory_pressure -Q<20%/<10%, M4/10-core/16GB, the 8–9-way crash); the Gitea cancel 404s including thedispatch_workflowexception and the slot-drain correction; the plumbing-merge sequence; vitest run 686 / 5s / 15s; the e2eREADY_LINEpair; killed-job triage including UTC-vs-UTC+2 and therefs/heads/v4noise; the shared-tree incident timestamps.ffmpeg.work-ahead-slot-atomic; the lazyMaplesson inrelease.live-e2e-required;ETV_SKIP_REBASE_CHECKand regenerate-don't-hand-resolve inrelease.format-as-you-touch-rebase; re-review-the-fix-commit inrelease.review-verdict-gate. It also confirmed the old doc's "not yet in decisions.md" note onResponseHeadersReadwas itself stale.Fixed from its findings: two dangling "see the archived section below" pointers (Medium — a real defect in a file pasted verbatim into every kickoff), and the explicit file-a-tracked-issue-for-a-deferral instruction, restored. Its one provenance query — a dependencies-API sentence with no source in the deleted text — I traced to commit
f93458c7, an earlier revision of this same doc where it was dropped by a later prune rather than disproved; the record now cites that provenance instead of asserting it bare.Review-verdict: MERGEABLE @
12e5c3d26f