Skip to content

feat(gate): a design artifact must name its consumer, prior art and twins - #1288

Merged
dc0sk merged 1 commit into
mainfrom
feat/proposal-fields-enforced
Sep 6, 2026
Merged

feat(gate): a design artifact must name its consumer, prior art and twins#1288
dc0sk merged 1 commit into
mainfrom
feat/proposal-fields-enforced

Conversation

@dc0sk

@dc0sk dc0sk commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Maintainer decision, from a lessons review of a ten-PR session.

Why

Every design proposal I sent to review in that session was overturned, and each was missing exactly
one cheap check that would have killed it
— each one command away:

proposal the missing check
#1271 the consumer: GetConfig runs on a task holding no engine, so the design would have paid none of the debt it claimed
#1268 the prior art: the ratchet I proposed building already existed (NOT-GRANDFATHERED, trace.py)
#1252 the twin: the responder path was pinned, the initiator left open
#1258 the census: three builders reported, four exist; seven backends, eight exist

So the reviewer was doing the proposer's falsification. That works only while the error is in
something a reviewer re-derives. A census presented as a fact is the shape that gets confirmed
instead — which is how #1252's false "every QSY frame is Ed25519-signed" claim survived a dedicated
code review for months.

The tempting fix was falsified first, and that is the more useful half

My diagnosis was that the rules already exist — measurement-integrity bans grep-censuses and
reading an absence out of a filter; second-opinion says read the consumer before proposing — and
that the fix was their trigger, since those skills had not loaded.

Tested against the session transcript: since 2026-09-02 there are 92 GATE: lines, 81 cargo
verdicts and 20 gh pr create, with zero loads of measurement-integrity.
A wrong-trigger
hypothesis predicts loads during the activities the trigger does name; they did not happen. Three
rules were also violated the same day they were written — the "grep the skill before adding a
rule" line went into global CLAUDE.md at 09:06 and #1268 broke it at 12:29.

Adding or re-scoping text was the one intervention the evidence ruled out. Hence a mechanical
check rather than another paragraph.

What this does

scripts/check-review.sh now requires a design artifact to carry ## Consumer, ## Prior art and
## Twins, each non-empty, each either an answer with the command that produced it or the
literal UNCHECKED.

UNCHECKED is legal on purpose. The goal is to turn an omission into a written claim, exactly as
tier 1's Review: none — <reason> already does. A field that may not be empty but may say
UNCHECKED bans a construct
; "consider the consumer" would be an exhortation that cannot fail and
is indistinguishable from compliance.

Tests

Five new probes, and the third is the one that matters:

  • each of the three fields missing is rejected by name (not just by exit code);
  • an empty section is rejected — a checker that only greps for the heading turns the requirement
    into a formatting rule the omission can wear;
  • UNCHECKED is accepted, so the escape hatch is real rather than nominal.

The positive-control fixture now carries the three fields, which means "fixing" that fixture by
deleting them would silently un-require them for everyone. The fixture is part of the check.

REVIEW-LINT-SELF-TEST: PASS   (13 probes, two of them positive controls)
GATE: PASS 187af96da64b8101581cc21fde3c9ad1ced7060f clean 20260906T185034Z
        suites=325 tests_passed=2464 tests_failed=0

This PR classifies as ordinary (it touches scripts/, not a decision-recording site), so its own
trailer is Review: none — the maintainer specified this shape, which is the honest answer.

Already earning it

The first design proposal after this landed (#1263, PTT nesting) was written with the three fields
filled. The Consumer field is what surfaced that the manual PttAssert path holds no ownership
token at all; the Prior art sweep still missed an existing marker (ARDOP's manual_keyed) because
I grepped for the words I expected the mechanism to be called rather than reading the struct — so the
field is not a cure, but the omission is now written down where the next reader can see it.

Review: none — the maintainer specified this shape

🤖 Generated with Claude Code

https://claude.ai/code/session_0188ATCj6DZ9aRVQ2vSirua6

…wins

Maintainer decision, from a lessons review of a ten-PR session in which every design proposal sent
to review was overturned. Each was missing exactly one cheap check that would have killed it, each
one command away — so the reviewer was doing the proposer's falsification. That works only while
the error is in something a reviewer re-derives; a census presented as fact gets CONFIRMED instead,
which is how #1252's false "every QSY frame is signed" claim survived a dedicated review for months.

The tempting fix was falsified first, and that is the more useful half. My diagnosis was that the
rules already exist (measurement-integrity bans grep-censuses and reading an absence from a filter;
second-opinion says read the consumer before proposing) and that the fix was their TRIGGER, since
the skills had not loaded. Tested against the transcript: 92 GATE: lines, 81 cargo verdicts and 20
gh pr create since 2026-09-02, with ZERO loads of measurement-integrity. A wrong-trigger hypothesis
predicts loads during the activities the trigger does name; they did not happen. Three rules were
also violated the same day they were written. Adding or re-scoping text was the one intervention
the evidence ruled out.

So: check-review.sh now requires ## Consumer, ## Prior art and ## Twins in a design artifact, each
non-empty, each either an answer with its command or the literal UNCHECKED. UNCHECKED is legal
deliberately — the goal is to convert an omission into a written claim, as `Review: none` already
does at tier 1. A field that may say UNCHECKED bans a construct; "consider the consumer" is an
exhortation that cannot fail.

Five new self-test probes: each field missing is rejected by name, an EMPTY section is rejected
(a checker that only greps the heading turns the requirement into a formatting rule the omission
can wear), and UNCHECKED is accepted. The positive-control fixture now carries the fields, so
"fixing" it by deleting them would silently un-require them — the fixture is part of the check.

Results: REVIEW-LINT-SELF-TEST: PASS, 13 probes including two positive controls.

Review: none — the maintainer specified this shape

Verification-objective: a design proposal must not be able to omit its consumer, prior art or twins
without writing down that it did.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188ATCj6DZ9aRVQ2vSirua6
@dc0sk
dc0sk merged commit ce4bd3c into main Sep 6, 2026
6 of 7 checks passed
@dc0sk
dc0sk deleted the feat/proposal-fields-enforced branch September 6, 2026 19:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant