<!-- informative -->

# Residuals

Accepted and rejected risk: what a step decided **not** to fix, and the condition under which that
decision stops holding. Maintained by the PLANNER. An entry is written only on an OWNER ruling, never
on an implementer's judgement and never on a reviewer's.

This store is the single place a residual lives. A specification's residual section or a report's
standing-risk line is evidence an entry cites, not a second copy: a residual held in two places is two
residuals, and nothing would then know which is authoritative.

It is a table rather than prose so that selection and matching are mechanical. Reading and
interpreting four fields of English is a comprehension task, and comprehension is the one thing an
actor does unreliably. `scripts/check-scope` reads the rows directly.

## Two states

- **accepted** — the risk stands and is carried. Re-opening means the risk is live again and must be
  fixed or re-accepted.
- **rejected** — the proposal was declined. Re-opening is a legitimate re-proposal on named evidence:
  the entry records what would make it proposable again.

Both carry a trigger, and the difference is what the trigger means. A rejection is a ruling at a time,
not a permanent gag; recording one without re-open semantics trades infinite re-proposal for permanent
silence, and a risk that later materialises could not be raised because the record forbids it.

The loop's exit condition reads **severity** from the review, not this store, and the record counts
`accepted` rows. Both populations still live here: a round that proposes something the OWNER rejects
has settled it, and the rejection is recorded so it is neither re-proposed every cycle nor lost.

## Entry shape

| Column | Content |
| --- | --- |
| `ID` | short stable key, quoted into briefs as the trigger's name |
| `State` | `accepted` or `rejected` |
| `Trigger` | one or more **globs over paths**; if a path in the diff matches, the brief must carry this entry |
| `Risk` | what was left unfixed, on its own terms |
| `Rationale` | why it was accepted or rejected |
| `Evidence` | the report or review that produced the ruling, linked |

`Trigger` is the column that goes wrong, so it is constrained rather than described. A glob is matched
mechanically by `scripts/check-scope`, which is the only form of this rule an actor performs
reliably. "If this code is touched" is a comprehension task; `src/orchestrator/reducer.py` is a match.
A trigger written as prose is the failure mode, not the fallback. The ID is matched whole-word, so
carrying `R10` does not satisfy `R1`.

## How an entry reaches an actor

Residuals are **selected, not inherited** — obligations and unfixed findings travel down the chain,
while a residual lives in the code and reaches every step whose diff touches a path its glob matches,
including a chain with no link to the work that accepted the risk. The row is copied into that
brief's `INHERITED` field verbatim, because a paraphrased trigger matches nothing.

A tripped trigger is then a finding: fixed with red evidence, or carried into the closeout with its
reason.

## Entries

Migrated under the owner ruling in [record.md](record.md#owner-rulings) (R3): the pilot spec's
residual surface and the five inherited option (e) concerns, each `ID` quoted unchanged from that
ruling's table. `Evidence` links the accepting review per row. The tenth entry is the residual R1
directs be recorded at migration (in-process trusted-code circumvention); its `ID` continues the
ruled series and its evidence is the ruling itself. This first entry arms the residual half of
`scripts/check-scope`.

| ID | State | Trigger | Risk | Rationale | Evidence |
| --- | --- | --- | --- | --- | --- |
| `PILOT-R1` | accepted | `src/orchestrator/planning_pilot.py`, `src/orchestrator/controller.py`, `src/orchestrator/reducer.py` | mutable admitted payload (wiring constraint): the caller holds a mutable reference to the admitted payload, and a post-return mutation of a child's scope survives the reducer's re-validation. Any integration must therefore not mutate a payload between the guard and event admission. | the admitted payload is mutable; the reducer's re-derivation runs at admission and on replay, so the guard's result is only as safe as the wiring keeps it | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md) |
| `PILOT-R2` | accepted | `src/orchestrator/decomposition.py`, `src/orchestrator/planning_pilot.py` | single-layer containment (F1): scope, budget and bounds admit exactly one recursive level; deeper proposals are legitimate work the guard will refuse | the pilot's mandate is deliberately one level deeper than FIXED_ONE_LEVEL and no more | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md) |
| `PILOT-R3` | accepted | `src/orchestrator/model.py`, `src/orchestrator/planning_pilot.py` | `RunState.clone()` is for replay snapshotting, not authority isolation (deepcopy kept): a future model provider must be handed the isolated `provider_state`, never the live state — if a provider is given the live state it can rewrite its own bounds | the pilot spec's threading warning; the live state was handed over exactly once, at the producer seam | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md) |
| `PILOT-R4` | accepted | `src/orchestrator/planning_pilot.py` | `parent_scope` is an assertion, not a restriction: containment is multi-scope and refusal is by comparison with the derived parent, not by trusting the argument. Multi-scope containment reaches only one level — a grandchild of a multi-scope parent may not propose | the contract reads `owned_scope: Sequence[str]` as a plural, and S5.4 in R3 of the option (e) review stands | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md), [option (e) review](research/phase4-option-e-review-report.md) |
| `PILOT-R5` | accepted | `src/orchestrator/planning_pilot.py`, `src/orchestrator/decomposition.py` | all-glob parent refused: `scope_contained` treats a bare `**` or `*` parent as a containment failure and refuses every child | conservative rather than unsafe; the fixed target owns `src/**`, so its proposals are unaffected | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md), [option (e) review](research/phase4-option-e-review-report.md) |
| `PILOT-R6` | accepted | `src/orchestrator/planning_pilot.py` | proposal content is not derivable (shape only): the checks prove shape, budget, bounds and one level of containment — never that a proposal is the right decomposition. If the future model path validates only shape, a well-formed wrong tree is admitted | the independent oracle and the acceptance grading remain the correctness authority; the guard's job is admissibility, not quality | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md) |
| `PILOT-R7` | accepted | `src/orchestrator/derive_obligations.py` | `_nesting_shape` one level (F10) and S7 nested-edge projection: derivation exposes no second level, and nesting deeper than one level is forced through declared `SUBTASK_OF` — if the nesting limit is ever raised, the projection and the containment bound must move together | the one-level stop and the nested-edge projection from the option (e) review both stand | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md), [option (e) review](research/phase4-option-e-review-report.md) |
| `PILOT-R8` | accepted | `src/orchestrator/derive_obligations.py` | `derive_dependencies` projects no nesting: on an obligation set with nesting, nested edges can vanish silently from the projection and only top-level edges remain | the F10 one-level stop | [pilot re-review 3](research/phase4-recursive-planning-pilot-re-review-3.md), [option (e) review](research/phase4-option-e-review-report.md) |
| `PILOT-R9` | accepted | `src/orchestrator/derive_obligations.py` | option (e) concerns 4–7 stand: the candidate-order dependency window, the whole-repository relationship scan, the git-call amplification of a re-derivation per obligation, and the home-grown `derive_dependencies`/`classify_relationship` imports | they are accepted as limitations of the declared path, not defects | [option (e) review](research/phase4-option-e-review-report.md) |
| `PILOT-R10` | accepted | `src/orchestrator/controller.py`, `src/orchestrator/planning_pilot.py` | in-process trusted-code circumvention of the admission capability: the capability is not reconstructible from data, but trusted code running in-process can hold or mint one and admit anything — if untrusted code is ever loaded in-process, the capability boundary does not hold | R1's prevention-shape ruling: the capability's threat model is data-only reconstruction, and trusted-code circumvention is recorded here rather than claimed solved | [owner rulings](record.md#owner-rulings) (R1) |
