<!-- informative -->

# Method rationale

Why each rule in [../method.md](../method.md) exists, and what it cost to learn. This file is
rationale, never instruction: when the two disagree, the rule in `method.md` is what an actor follows.

Each rule states the property on its own terms first and cites its case second. A name from the past
is not an explanation, and a rationale that needs the history in the reader's head has failed at the
one job it has.

## brief

A brief is an actor's only input because an actor cannot ask a question it does not know to ask.
An IMPLEMENTER with a two-line brief and access to the repository will still produce code; it will
simply produce code answering a question nobody asked.

The cost of this rule is that briefs get long — the ones in `research/` run to 250 lines — and that a
brief must restate what the planner knows. Both are cheaper than the alternative, which is an actor
guessing and the finding arriving as a review comment.

The failure mode is a brief that is complete but self-authored: the party that benefits from a weak
acceptance criterion also writes it. So a REVIEWER's brief copies the acceptance criteria verbatim,
and requires the reviewer to read pre-images rather than the implementation's account of them. A
specification that both directs and describes cannot otherwise be told apart from a correct
implementation of a wrong specification.

## inherited

Copying, not retyping, is the load-bearing rule of the method, because every failure it prevents is
silent. A paraphrased trigger matches nothing. A paraphrased obligation loses the part that
mattered. A role body reworded per brief means two sessions obey different rules while both believe
they are following the method.

The reason the report and closeout each emit the block, rather than the planner assembling it, is
that the planner cannot quote a document it has not read. An earlier version said the planner may
never see an intermediate report *and* must quote it into the next brief, which is impossible — and
the only resolutions available to an agent that finds a contradiction like that are paraphrasing or
fabrication. The block is written by whoever held the evidence and copied whole.

## residuals

Residuals are the one item that does not travel down the chain. Obligations and unfixed findings are
chain-bound: the next brief inherits them. A residual is surface-bound — the risk lives in the code —
so a brief with no genealogical link to the work that accepted the risk still needs it if its `IN SCOPE`
can trip the trigger.

Missed selection is the quietest failure the method has, because it is an absence: the brief goes out
looking complete and no reviewer can see what was never written. Which is why the trigger is a glob
over paths rather than a sentence. "If this code is touched" is a comprehension task; a path glob is a
match, and only the second is performed reliably.

Rejected proposals get an entry too. A rejection is a ruling at a time, not a permanent gag: without
re-open semantics, recording it trades infinite re-proposal for permanent silence, and a risk that
later materialises could not be raised because the record forbids it.

The store is a table rather than prose so the count is mechanical. A number recovered by interpreting
four fields of English is the unmeasured claim this repository keeps refusing to accept.

## divergences

Three states because two leave the commonest case homeless: the document was right and the brief was
wrong, so the divergence evaporates with no amendment required and none permitted. With only "amended"
and "deferred", that case gets shut by manufacturing an amendment nothing needed — a bookkeeping line
driving a normative edit.

Naming the artifact is what makes a state checkable. "Document amended" without a commit is a sentence
anyone can write. The amending commit is named but is *not* required to appear in the step's scope
diff: amendment is the OWNER's authority, and requiring it inside the implementer's range would put a
normative change under IMPLEMENTER authority.

## red-evidence

Narrow on purpose. The measured failure in this repository is not a missing test but a test that
passes while asserting the wrong thing, so proof is the named assertion and not the exit status. An
error, a collection failure, or a run that merely happened is not evidence.

Node id and command are what make the counter auditable. A quoted assertion with no way to re-run it
is a claim, not a measurement, and would sit in the one counter with a direction while being
unverifiable.

"No regression test was added" is an honest entry and belongs in the `Fixed` denominator. It is the
counter's whole value: the shortfall should fall toward zero, which is evidence the rule is being
followed and not that the method is improving. A step that fixed only trivial findings can reach
`Red == Fixed` while nothing improves.

## shapes

In one review chain of five residuals — `F2`'s thirteen classes, `R1`'s unhashable identifiers, `R5`'s
`budget_id`, `R7`'s uniqueness, and a `continue` gap the implementer reported against itself — every
residual was found by probing a shape the green suite never built, and not one by a failing test
written afterwards. That is one chain, not the 125-commit corpus, and the corpus-wide claim was an
earlier version of this file asserting more than its source said.

The answer is a list, not a count, because a floor is padable — and a floor would reproduce the class
it targets, which is a check satisfiable without substance. Zero shapes with a stated reason is a
legitimate answer over a small boundary. Zero shapes with no reason is a vacuous report, and it
returns to planning rather than counting as convergence.

## findings

Three states because a binary one loses the third silently. A closeout naming only fixed and dropped
produces a report that reads complete and has discarded every unfixed finding — the cheapest place in
the method to lose one.

Origin is a fixed token rather than prose because grouping later only works if a grep can do it.
Prose origin is an unmeasured claim, which is the defect this repository keeps refusing.

`declined` means *not a defect*, and a defect nobody will fix now is `carried`. The first cycle
declined a real ambiguity in a brief on the grounds that rectifying the wording was the planner's
business; that kept it out of `Carried`, the only column the exit condition reads, and left a brief
defect with no owner. Carried P2 findings do not block convergence, so the distinction costs nothing
and keeps the defect visible.

A defect in a brief is a finding and not `METHOD FRICTION`, for the same reason: friction is read by
the OWNER between steps, findings are counted by the record. The first cycle's only brief defect was
filed as friction, so the record shows no defect originating in a brief.

## files

Actors read their brief and nothing else, so a concern that lives only in a commit message reaches
nobody. The first cycle's planner noted that one brief defect should be attacked by the reviewer and
wrote it in a commit message; the reviewer never saw it and accepted the implementer's reading without
comment. The same holds for the OWNER, who reads files between steps, which is why friction is copied
into `record.md` and not left in the reports it came from.

The same reasoning puts commits in the templates. The commit step was written in `method.md`, which
actors are told not to read, so both sessions delivered uncommitted and the PLANNER committed on their
behalf. That rewrote an actor's evidence (the implementer's `FINAL` named a working tree, the committed
report named a commit) and left the independence rule uncheckable, since one git identity authored
everything. An `Actor:` trailer is the smallest thing that makes authorship a property of the commit.

A report cannot name its own commit, so `FINAL` is the work commit and the report lands in a second
one.

## scope

`IN SCOPE` is a request and nothing enforces it, so the diff is the only evidence about it. Checking
one commit is not enough: closing commits here bundle the specification, the code, and the tests, so
a step of two commits escapes a single-commit check.

The same script matches residual globs against the **diff**, not against declared `IN SCOPE`. These
catch different things and neither subsumes the other: matching the diff catches scope creep into a
risky file the brief never claimed, while matching `IN SCOPE` catches a brief that *should* have
carried an entry for work it admitted to doing and then did not touch. `docs/research/` is allowed
implicitly, because a reviewer's report lands in the diff by design.

The first version of this gate passed six known breach shapes. Every one came from building the test
fixtures out of the parser's own assumptions: `OUT OF SCOPE:` was read as more `IN SCOPE` because the
header pattern could not match a multi-word header, a report directory was exempted that reports are
not written to, renames hid the deleted path, a backtick in the documented table format disabled the
residual check, and a trigger with two globs matched neither. They are now
[tests/test_check_scope.py](../../tests/test_check_scope.py), because an enforcement with no
bypass test is not enforced.
