[review] emit = ["REVIEW.md", "AGENTS.md"] is already a list of targets, and
the comment above it is careful that neither is a second source: both are
generated from the catalog under the same --check gate, so a stale one cannot
be committed. This proposes a third kind of target, whose unit is a record
rather than the catalog.
The argument is the ceiling's own argument
max_lines = 900 exists for a stated reason: guidance long enough to be skimmed
is guidance emitted always, and enforcement-needs-a-trigger was amended to say
exactly this and refuses the review tier without the ceiling. scripts/review.py
carries the reasoning in its module doc, and the number sits below an observed
degradation range rather than at the top of it.
Note what that is. The ceiling manages the failure -- it holds the always-read
document short enough to survive being always read. It does not remove the cause.
A per-record target removes the cause. A record whose applies_when does not
describe the change in front of the reviewer is never loaded at all. The
condition that enforcement-needs-a-trigger demands, and that the review tier
currently satisfies only at the granularity of the whole document versus the
whole change, becomes per-record: 19 constraints each with a scope, instead of
one document carrying 19 scopes that a reader applies by hand.
Zero new schema, again
A conditionally-loaded unit needs three things: a name, a description that
decides when it is loaded, and a body.
- the record id is the name
applies_when was written as when it binds and is already the descriptionclaim and review_questions are the body
Which is the same sentence review.py already makes about the compiled entry:
three fields that were written as a prompt, and nothing here was designed for
this.
The one thing the split is not free of
automatable = "yes" records are excluded from the compiled document because a
rule already refuses them, and re-reporting costs a reviewer's attention and
buys a second opinion nobody asked for. That exclusion currently lives in the
preamble -- one block at the top, naming the active rules once.
A record loaded on its own carries no preamble. So a per-record target has to
carry the exclusion inline, in every emitted unit, or the deduplication that the
document tier gets for free is silently lost the moment the tier stops being a
document. That is the design work here; the rest is a second writer.
The limit that argues for measurement
A conditionally-loaded record is loaded because something read its description
and judged it relevant. That is a heuristic, not a trigger, and it is weaker
than the seams uphold usually accepts: a commit-msg hook fires or the commit
does not happen, whereas a record can simply never be selected and the tree looks
identical either way.
enforcement-needs-a-trigger asks what in the system would reveal a rule that
can never fire. For the document tier the answer is at least everything in it
was read. For a per-record tier there is no answer yet, and the same gap
ROADMAP.md already records for installed-but-dead static rules reappears one
layer up, where nothing has ever looked for it.
Deliberately not now
The compiled document is 283 lines against a ceiling of 900. At that size the
split buys nothing a reader is losing today, and it costs the preamble problem
above.
What is worth settling now is the generalization -- that emit names targets
of more than one shape, and where the exclusion lives when a unit is emitted
alone. Adoption belongs at the point the catalog approaches the ceiling, which
is the moment the ceiling starts deciding what a reviewer is allowed to be told.
[review] emit = ["REVIEW.md", "AGENTS.md"]is already a list of targets, andthe comment above it is careful that neither is a second source: both are
generated from the catalog under the same
--checkgate, so a stale one cannotbe committed. This proposes a third kind of target, whose unit is a record
rather than the catalog.
The argument is the ceiling's own argument
max_lines = 900exists for a stated reason: guidance long enough to be skimmedis guidance emitted always, and
enforcement-needs-a-triggerwas amended to sayexactly this and refuses the review tier without the ceiling.
scripts/review.pycarries the reasoning in its module doc, and the number sits below an observed
degradation range rather than at the top of it.
Note what that is. The ceiling manages the failure -- it holds the always-read
document short enough to survive being always read. It does not remove the cause.
A per-record target removes the cause. A record whose
applies_whendoes notdescribe the change in front of the reviewer is never loaded at all. The
condition that
enforcement-needs-a-triggerdemands, and that the review tiercurrently satisfies only at the granularity of the whole document versus the
whole change, becomes per-record: 19 constraints each with a scope, instead of
one document carrying 19 scopes that a reader applies by hand.
Zero new schema, again
A conditionally-loaded unit needs three things: a name, a description that
decides when it is loaded, and a body.
applies_whenwas written as when it binds and is already the descriptionclaimandreview_questionsare the bodyWhich is the same sentence
review.pyalready makes about the compiled entry:three fields that were written as a prompt, and nothing here was designed for
this.
The one thing the split is not free of
automatable = "yes"records are excluded from the compiled document because arule already refuses them, and re-reporting costs a reviewer's attention and
buys a second opinion nobody asked for. That exclusion currently lives in the
preamble -- one block at the top, naming the active rules once.
A record loaded on its own carries no preamble. So a per-record target has to
carry the exclusion inline, in every emitted unit, or the deduplication that the
document tier gets for free is silently lost the moment the tier stops being a
document. That is the design work here; the rest is a second writer.
The limit that argues for measurement
A conditionally-loaded record is loaded because something read its description
and judged it relevant. That is a heuristic, not a trigger, and it is weaker
than the seams uphold usually accepts: a
commit-msghook fires or the commitdoes not happen, whereas a record can simply never be selected and the tree looks
identical either way.
enforcement-needs-a-triggerasks what in the system would reveal a rule thatcan never fire. For the document tier the answer is at least everything in it
was read. For a per-record tier there is no answer yet, and the same gap
ROADMAP.mdalready records for installed-but-dead static rules reappears onelayer up, where nothing has ever looked for it.
Deliberately not now
The compiled document is 283 lines against a ceiling of 900. At that size the
split buys nothing a reader is losing today, and it costs the preamble problem
above.
What is worth settling now is the generalization -- that
emitnames targetsof more than one shape, and where the exclusion lives when a unit is emitted
alone. Adoption belongs at the point the catalog approaches the ceiling, which
is the moment the ceiling starts deciding what a reviewer is allowed to be told.