<!-- informative -->

# Development method

Four actors, one brief at a time, one rule about what may be carried. Every rule here is held by a
reviewer or the OWNER; the one exception is the scope check, which is automated. Reasoning per rule
lives in [research/method-rationale.md](research/method-rationale.md) and is linked from each rule.

**Nothing here is proven.** Every mechanism was added against a hypothesised failure rather than an
observed one. What the method got wrong is recorded in each report's `METHOD FRICTION` section, and
a rule is added only against a failure with a body count.

## Actors

| Actor | May | May not |
| --- | --- | --- |
| PLANNER | read anything; write briefs and review briefs; assemble closeouts; maintain the ledger and the residual store | amend a normative document; assign a finding's origin; rule on a design question; edit or commit an actor's work or report |
| IMPLEMENTER | change files named in `IN SCOPE`; run the gates; commit its own work and report | widen scope; fix anything outside `IN SCOPE`; plan |
| REVIEWER | read; create new test files; write its report; commit both | modify any project file other than a new test or its report; fix anything |
| OWNER | rule on design questions; amend normative documents; accept or reject a residual | — |

A finding's `ORIGIN` is assigned by the REVIEWER. The PLANNER assembles a closeout by copying it and
adds no judgement, so nobody records a verdict on their own work.

**OWNER notes, not planner tasks:** allow at most one detection brief per three feature briefs while
a ledger row has no test; choose model capability — the PLANNER's reconciliation work is heavier than
an actor's execution of a brief, so escalate planning before escalating the model. Run each role on
its own model; dispatch stays with the OWNER. Keep `method.md` near 220 lines: when a rule would
cross it, the OWNER folds or retires one — rules duplicating a template line first, then rules
untriggered through the Record's rows. Rulings waiting to be consumed live in
[record.md](record.md#owner-rulings).

## Cycle

1. PLANNER writes the brief.
2. IMPLEMENTER commits the work, then writes the report and commits that separately. The work
   commit's sha is `FINAL`.
3. PLANNER writes one review brief per planned review.
4. REVIEWER reviews — one session per brief, independent of the others: no reviewer reads another's
   report — and may add test files and its report only, committed together.
5. PLANNER decides: next brief, return to planning, refer to OWNER, or close out.

A **step** is one IMPLEMENTER brief plus every review of it, ending at that decision. `CLOSE OUT`, the
record row, and the exit condition attach to that boundary. The PLANNER declares the step's review
plan in the brief's `REVIEW:` field before the work exists — one entry per planned review session,
each its focus — and may add reviews after the report but never remove one. A skipped review rests
on an OWNER ruling, never on the planner's judgement.

Every actor commits its own work with an `Actor: IMPLEMENTER` or `Actor: REVIEWER` trailer, because
every commit shares one git identity and the trailer is the only thing that makes "you must not be the
author of the commits under review" checkable. The PLANNER never commits on an actor's behalf and never
edits an actor's report: an actor that delivered uncommitted work is sent back to commit it. The
PLANNER commits only its own artifacts — briefs, review briefs, the closeout and `record.md`. Between
`REV` and `FINAL` the only PLANNER commits are brief files — the brief and any re-cut, each its own
file — and any other planner write (`record.md`, rulings) waits until after `FINAL`, so
`scripts/check-scope <rev> <final> <brief>` sees no path outside `IN SCOPE` but the brief itself. A
committed report is never edited by anyone: corrections travel as rulings and later briefs. A
committed brief is never modified either: a re-cut is a new file (`…-brief-2.md`) under
`docs/research/`, which `check-scope` admits by its added-file exemption and without any self-claim,
while an edit to an older brief path stays a scope failure. A brief never claims its own path in
`IN SCOPE`. An aborted dispatch is discarded, not inherited: the PLANNER moves the uncommitted edits
aside (`git stash`, or a branch named `aborted/<subject>`), leaves the tree clean at the brief's
commit, and a fresh implementer session gets the unchanged brief — partial work of unknown origin is
never raw material.

### Starting procedure

1. `git log --oneline -5` and `git status --short`.
2. The last [Record](record.md#record) row, and the `INHERITED` block of every artifact it names;
   then reconcile with `git log`: a committed brief whose step has no Record row is an open step —
   finish it at whichever point it stands (awaiting dispatch, its `REVIEW:` briefs, or its decision
   under cycle step 5) before step 4.
3. The current phase in [self-host.md](self-host.md).
4. **Select.** Take the first that applies: an OWNER ruling in
   [record.md](record.md#owner-rulings) naming the next brief; the next unblocked item in the
   current phase of `self-host.md`; a ledger row whose Detection reads `partial`, within the
   detection-brief ratio. If none applies, refer to the OWNER. Do not
   dispatch a review brief by searching `research/` for a brief with no report: the corpus predates
   the naming convention, so that search mostly returns work already reviewed.
5. Measure the gates, then decide: next brief, return to planning, refer to OWNER, or close out.

A ruling is removed by the PLANNER when the Record row that consumes it is appended. Appending the
row does not remove the ruling by itself.

Expect the fast suite to be **red** when the previous step's reviewer left a failing test: the test
lands before the registration that keeps it honest — the open-defect registry owns `test_bug_*` pins
only, and a review's `test_review_*` probe rides red until the next brief absorbs it. That red is the
next implementer's red evidence and starting procedure step 5 measures it.

## Rules

1. **A brief is the actor's only input.** If you were handed a brief, follow only the brief; do not
   read this document. One exception: a REVIEWER may read
   [research/report-recurring-failures.md](research/report-recurring-failures.md).
   [why](research/method-rationale.md#brief)
2. **`INHERITED` is copied, never retyped.** Take the source text and move it. Each report's
   `INHERITED` block is written by whoever held the evidence; when a step has several reports, the
   next brief copies **every** block, in report order.
   [why](research/method-rationale.md#inherited)
3. **Residuals are selected, not inherited.** Every brief whose `IN SCOPE` matches a trigger's path
   glob carries that entry in its `RESIDUALS` block, even from an unrelated chain; `INHERITED` never
   carries residual rows. [why](research/method-rationale.md#residuals)
4. **A tripped trigger is a finding**, and is fixed with red evidence or carried with its reason.
   [why](research/method-rationale.md#residuals)
5. **`DIVERGENCES` closes in exactly three states:** brief corrected (name the rev), document amended
   (name the OWNER's commit), or deferred (quoted ledger entry). Never silently. The amending commit
   need not appear in the step's scope diff — amendment is the OWNER's authority. A clause misworded
   on the actor is a finding (`ORIGIN: BRIEF`, rule 8), not a divergence.
   [why](research/method-rationale.md#divergences)
6. **Red evidence** is the test **node id**, the **exact command**, and the **named failing assertion**
   at `REV`. An error or a collect failure is not evidence. Every `Red` unit is replayable or uncounted.
   [why](research/method-rationale.md#red-evidence)
7. **Shapes are a list, not a count.** Zero with a stated reason is legitimate; zero without one is
   vacuous, and a vacuous report returns to planning. No threshold is set.
   [why](research/method-rationale.md#shapes)
8. **A finding has one of three states:** `fixed` (with red evidence, or the honest
   `fixed: no regression test`), `declined` (not a defect, with the reason), or `carried` (a real
   defect left unfixed, passed into the next brief). A defect you will not fix now is `carried`,
   never `declined`. A defect in a brief is a finding with `ORIGIN: BRIEF`, not `METHOD FRICTION`.
   Carried means a future actor has something to do with the finding; nothing is carried that no one
   can act on. The close forms are in `report.txt`'s `STATE` note. At every step decision the PLANNER
   closes findings no one can act on, and moves an authoring lesson into
   [record.md](record.md#observations).
   [why](research/method-rationale.md#findings)
9. **An empty section reads `none`.** A silent blank is indistinguishable from skipped work.
10. **Scope is a command, not a judgement:** `scripts/check-scope <rev> <final> <brief>`. It fails
    when a path in the diff is not claimed, and when check-scope's `tripped:` ids go uncarried.
    [why](research/method-rationale.md#scope)
11. **Anything an actor or the OWNER must act on lives in a file, never only in a commit message.**
    Actors do not read commit messages. A concern the PLANNER wants a REVIEWER to attack goes into the
    review brief's `QUESTIONS TO ATTACK`; a concern for the OWNER goes into
    [record.md](record.md#pending-for-the-owner). [why](research/method-rationale.md#files)
12. **An invariant over the event log names its measure:** final-log membership, or order at a named event.
13. **When a review falsifies an absolute claim,** the next brief either makes it structurally true —
    one seam over the whole surface, pinned by a test over generated inputs — or the OWNER narrows
    the claim by ruling, separately from any remedy. A brief may not answer a falsified absolute
    with another enumerated list of cases.
14. **A count figure is the gate's printed line (or the artifact's own list), never a recomputed or
    remembered number.** Copy the line; never subtract.
15. **A brief asks; it does not predict.** If it states an expected outcome, the outcome is marked
    as expected and names its basis. A predicted outcome is never written as fact.

## Templates

An IMPLEMENTER and a REVIEWER read their brief and nothing else, so the brief carries their whole
role. The templates are the actors' contract and this document is the planner's:

- [templates/implementer-brief.txt](templates/implementer-brief.txt)
- [templates/review-brief.txt](templates/review-brief.txt)
- [templates/report.txt](templates/report.txt)

The closeout is the PLANNER's alone and has its own template,
[templates/closeout.txt](templates/closeout.txt), appended to the step's last report when
`CLOSE OUT` is yes, copying and adding no judgement.

Any rule an IMPLEMENTER or REVIEWER must follow lives in their template; the rules above bind the
PLANNER. A brief is the actor's template **followed by `report.txt`**, so the instruction to append
the report template finds it. Copy the files; do not retype them, and do not re-derive a template per
brief — that is how two sessions end up obeying different rules while both believe they are
following the method.

The PLANNER writes the brief to `docs/research/<phase>-<subject>-brief.md` and commits it before
dispatching, because the review brief's acceptance names that path and a path nothing created is a
path the gate cannot check.

## State

The ledger, one row per completed step, and the OWNER rulings waiting to be consumed live in
[record.md](record.md). [residuals.md](residuals.md) holds accepted and rejected risk on OWNER
rulings. Nothing in this document changes while a step runs: only `record.md` does.

## Exit

A step returns to planning when the brief was wrong rather than the code, a finding is suspected and
its fix is not obvious, a fix needs a file outside `IN SCOPE`, or acceptance passes without the goal
being observable. The same goal failing twice goes to the OWNER, because two failures are evidence
about the brief.

It converges when **every accepted review of it raises no P0 and no P1** — a review returned as
vacuous under rule 7 is not accepted and does not count — and its `REVIEW ACCEPTANCE` is green, or
the same verdict is obtained another way and recorded. A finding that answers a
`QUESTIONS TO ATTACK` item about a seam the brief's `OUT OF SCOPE` names explicitly does not block:
it leaves as `carried` whatever its severity, and a `P1` among them goes into
[record.md](record.md#pending-for-the-owner) at closeout — the next brief is its fix unless the
OWNER rules otherwise. Every other P0/P1 blocks. P2 findings may leave the step as `carried`, and
the Record's `Carried` column counts them — a reviewer fixes nothing, so demanding zero carried
findings would demand zero findings.

A chain of steps on one goal ends when its last step converges and that step's `INHERITED` carries
no finding. A chain whose only remaining items are brief-text defects ends at its last closeout,
closing them as actionless; it does not open a step to close them. A status refresh is never a
step's goal: it rides a real step's `IN SCOPE`, or it is an OWNER commit. A brief never restates an
exit bar in prose; a stricter bar for a chain is an OWNER ruling. Programme-level "done" has its
home in [self-host.md](self-host.md)'s phase exit gates.

When the step closes out, the PLANNER appends the closeout to the step's **last report only**, and
copies every `METHOD FRICTION` entry from every report of the step, verbatim (a `none` section has
no entries and copies nothing), into
[record.md](record.md#pending-for-the-owner). A step that converges closes out and counts its own
findings (`CLOSE OUT: no` predicts a return to planning, waives nothing); a non-closeout step
appends no `CLOSEOUT` block.

## Gates

| Gate | Command |
| --- | --- |
| Fast suite | `scripts/check-tests --fast --parallel` is the primary dev-loop gate (~33s, under the 100s bar); `--fast` alone is the serial reference |
| Documentation | `scripts/check-docs` |
| Static | `scripts/check-static` |
| Full suite | `scripts/check-tests` |
| Scope | `scripts/check-scope <rev> <final> <brief>` |

Figures are not recorded here. Step 5 of the starting procedure measures them on every run, and each
report's `VERIFIED` line records them against that report's own revision, so a third copy here would
only go stale.

Never put a full run in `ACCEPTANCE`: thirty slow tests are three percent of the suite and most of
its wall clock. A brief that adds a file under `tests/` or `scripts/` also names
`pytest tests/test_phase3_project_oracle.py`, because the fast suite and the commit hook both
deselect the oracle and a new module in those directories breaks it. Name every load-bearing command under 100s on the development host — the 120s session ceiling kills longer ones silently.
