<!-- mixed: the Specification and Tests sections are normative; Provenance, Bounds rationale, and Residual sections are informative. -->

# Phase 4 bounded recursive-planning pilot: implementation spec

Status: **implementation spec**, reached after the option (e) review chain closed
(NO-GO → remediation → conditional GO → GO for this pilot, recorded in
[phase4-option-e-review-report.md](phase4-option-e-review-report.md)). This lifts
the kernel's exclusion on recursive planning over model outputs for a **bounded**
pilot, as the second half of
[Phase 4](phase4-decomposition-design.md#the-bounded-recursive-planning-pilot-scope-is-a-review-decision).

## Provenance (informative)

Option (e) made a declared obligation set first-class and mechanically justified,
and the gate now enforces that a declaration is *exactly* as divergent as it
claims. Two axes are only ever non-empty because **derivation cannot express
them**: `NESTING` (one-level derivation produces no nesting) and, for a
multi-component target, `ALLOCATION` (derivation stamps every criterion on every
child). Those declarations are the pilot's motivation — they are standing
substitutes for structure the harness cannot yet derive.

The pilot replaces the standing substitutes with a mechanism: a model proposes
the child structure, and a deterministic validator admits or refuses it. A
proposal never becomes a node without passing the validator, exactly as a model
patch never becomes accepted state without the oracle.

## The one forward obligation inherited from the option (e) chain (normative)

The re-review recorded a forward note that this pilot **must** discharge:

> Nested child ids remain compared verbatim, which is sound today only because
> derivation produces no nesting. Once derivation can nest (the F2 scenario),
> nested spelling must be excluded like top-level spelling or a nested rename will
> manufacture `NESTING`.

This is the first requirement below, because the pilot is the change that makes
derived nesting possible.

## Specification (normative)

### P1. Exclude nested spelling from the `NESTING` shape

The `NESTING` shape is keyed by projected component at the top level. Nested
children have no projection, so they are compared by raw child id, which makes a
nested rename indistinguishable from a structural difference.

A nested obligation's *identity* for shape purposes must be its position under
its owning component, not its declared name: the shape is
`(component, tuple_of_child_positions_or_count)` — or, more usefully,
`(component, frozenset_of_nested_criterion_sets)` — so that renaming a nested
child produces no divergence, while adding, removing, or re-parenting one does.
The chosen form must be stable under a nested rename and sensitive to a nested
structural change; that property is the requirement, not the particular encoding.

This lands **before** any derived nesting exists, so it cannot regress today's
fixture: the fixed target's `report → (report-format, report-emit)` shape must
still measure as `NESTING`-divergent.

### P2. Model proposals enter only as proposals

A model-produced decomposition is data, never structure. The admission path is:

1. The model emits a **proposal**: children for an admitted parent, each in the
   reducer's child shape — `node_id`, `mandatory`, `criterion_ids`,
   `contract.owned_scope`, `contract.acceptance_criteria`, `contract.budget_id`,
   and `budget_allocation` (a per-dimension mapping). It is the shape
   `validate_decomposition` consumes, not a parallel obligation shape, and the
   guard reads the same fields, so there is one interface to settle before the
   producer is written.
2. The proposal is validated by the *existing* deterministic gate, unchanged:
   `decomposition.validate_decomposition` for budget feasibility, acyclicity, and
   scope disjointness; the Phase 4 shape/coverage/projection/predicate stages for
   structure.
3. Only a proposal that passes becomes the parent's nested structure, and only
   then does it reach `plan_decomposition`.

No stage may be skipped because the input came from a model, and no model output
may be used to relax a validator. A refusal is a refusal, not a fallback to a
partial structure.

### P3. The three bounds

These are the bounds the earlier docs left to this review, set explicitly:

- **Depth**: two levels below the derived root. A parent admitted at the root may
  propose children, and a child may propose grandchildren. A grandchild may not
  propose. The existing controller depth guard remains the backstop; the pilot's
  bound is not a substitute for it and must not raise it.
- **Pilot size**: the existing per-node fan-out limit applies unchanged —
  `maximum_children_per_node` is 6 (`docs/tables/limits.yaml`) and the pilot must
  not raise it. A pilot-specific per-trial ceiling of 32 proposed children is
  added, checked *before* validation so a runaway proposal hits a cheap guard
  rather than the validator's cost. (This section originally specified 8 children
  per parent, which would have *raised* the existing limit of 6. The table is the
  authority and the pilot is bounded by it.)
- **Derivation is mandatory.** `admit_proposal` requires the replayable `state`
  and the `parent_node_id`; depth, the trial's admitted count, the parent scope
  and the parent budget are all derived from state. The corresponding keyword
  arguments exist only so a caller can *assert* what it believes, and a mismatch
  is refused with the derived value authoritative. Opting out is what re-opened
  the first review's caller-trust findings, so the pilot path does not offer it.
- **Authority**: a proposal is admitted only by the deterministic validator. The
  model has no vote on admission, no ability to widen its own scope beyond its
  parent's, and no ability to introduce a criterion the parent does not own.

### P4. Scope containment for proposals

A proposed child's scope must be contained in its parent's scope, reusing the
same glob-free prefix rule the shape validator already enforces. A proposal may
therefore subdivide its parent's territory but never reach outside it. This is
what stops a proposal from silently widening the write-scope surface.

### P5. Budget authority

A proposed child's budget must come from the parent's budget, not exceed it, and
the sum of a parent's proposed child budgets must not exceed the parent total.
Budgets are a spend decision; a model may subdivide an allocation but not inflate
one. The validator's existing budget-feasibility conflict check remains the
authority, and the pilot must not weaken it.

### P6. The declared-structure gate still governs the result

A pilot-admitted nested structure is a *derived* structure for gate purposes: it
does not become a `DECLARED` target, and it must not be admitted by naming
`NESTING` or `ALLOCATION`. If a pilot structure turns out to be expressible by
derivation, the derived path must win — which is the self-clearing property the
option (e) chain was built to deliver, and the reason the pilot is a mechanism
rather than another declaration.

### P7. Kernel amendment timing

`PROJECT_KERNEL`'s `current_non_goals` includes "Recursive planning on model
outputs beyond the experiment arms". The lift is recorded as part of admitting
the pilot, and must name the pilot's bounds, so the non-goal stays true until the
pilot is actually admitted and its limits are legible in the kernel.

### P7a. The producer's shape

The producer is `planning_pilot.propose_decomposition`. It takes a **provider** — a
callable `(state, parent_node_id) -> children` — which is the seam a model adapter
plugs into. The harness has no model call for recursive planning today, so the
provider is injected and the tests use deterministic doubles; no pilot test makes a
model call.

**The `state` the provider receives is an isolated deep copy, never the live
`RunState`.** Every bound the guard enforces is derived from that object, so a
provider handed the live one could clear its own depth, inflate its own budget, and
be admitted against the constraints it had just edited — which is exactly what the
adversarial review demonstrated. A state that cannot be isolated is a refusal, not a
fallback to live state.

Every identifier the reducer will *key* is validated at the guard: a child's
`node_id`, its criterion ids, its `contract.budget_id` (which becomes a ledger key),
and the `contract.acceptance_criteria` entries' ids. Being *well-formed* is not
enough — a `budget_id` must also be **unused** in the ledger and unique within the
proposal, because `Ledger.register_budget` raises `LedgerStateError` on a present id
and `reduce` wraps the handler with nothing, so a collision escaped as neither a
`DecompositionError` nor a `ReducerError`. And a child that declares no
`criterion_ids` is still contract-checked: an early `continue` once skipped those
checks, reaching the same gaps through a different door. The promise is that what the
guard admits is something the reducer can evaluate, and a key it cannot hash is not
that — an unhashable value reached `register_budget` as a bare `TypeError` the
reducer's `DecompositionError` handler did not catch. Caller-supplied `dependencies`
entries are shape-checked for the same reason: `_ensure_acyclic` reads both
endpoints unchecked, so a missing key reached the authority as a bare `KeyError`.

The provider's output is deep-copied, run through `admit_proposal`, and only an
admitted structure becomes a `DECOMPOSITION_ADMITTED` payload. The whole sequence —
provider call, normalisation, admission, coverage derivation, payload assembly —
is inside one net: a provider that raises, returns a non-iterable, or returns an
element that is not a mapping is **refused and recorded**, not raised. "Every
proposal produces a record" is the stronger property, so the stages are `PROVIDER`
(a provider fault), `GUARD` (a pre-check refusal), the three named checks, and
`ASSEMBLY` (payload assembly). `depth_reached` is the depth the proposal *reaches*:
the admitted children's depth, one below their parent. Criterion coverage is
derived from the admitted children rather than taken from the provider, so the
matrix the reducer checks is a mechanical consequence of what was admitted; whether
that coverage is *sufficient* remains the reducer's call.

### P8. Instrumentation

The pilot must record, per proposal: whether it was admitted or refused, the
stage that refused it, the proposed and admitted child counts, and the depth
reached. A pilot that cannot be measured cannot be bounded in practice, and the
projection already exists as the place to put this.

## Tests (normative)

1. **Nested spelling excluded (P1).** A derived-equivalent structure with nested
   children renamed measures no `NESTING`; adding, removing, or re-parenting a
   nested child does measure it. The fixed target's manifest still measures
   `NESTING`.
2. **Proposal admission (P2).** A well-formed proposal is admitted and reaches
   `plan_decomposition` as nested structure; a proposal failing budget
   feasibility, acyclicity, or scope disjointness is refused and leaves the
   parent's structure unchanged.
3. **Model output is never structure (P2).** A proposal is refused — not partially
   applied — when any stage fails; there is no path where a refused child is
   retained.
4. **Depth bound (P3).** A third-level proposal is refused; the controller's
   existing depth guard is not raised by the pilot.
5. **Size bound (P3).** A proposal exceeding `maximum_children_per_node` (6) is
   refused by the existing validator and the pilot does not raise it; the
   per-trial ceiling is enforced independently of the per-parent one.
6. **Scope containment (P4).** A proposed child whose scope escapes its parent is
   refused, including the sibling-reach case.
7. **Budget authority (P5).** A proposed child budget exceeding the parent's, and
   a set of children summing beyond the parent total, are both refused.
8. **Gate still governs (P6).** A pilot-admitted structure is `DERIVED`; there is
   no path by which admitting one marks a target `DECLARED` or admits it by
   naming an axis.
9. **Kernel amendment (P7).** `PROJECT_KERNEL`'s non-goal list names the pilot and
   its bounds once admitted; the recorded bounds match P3.
10. **Instrumentation (P8).** Every proposal produces a record naming its outcome
    and the refusing stage, and the counts and depth agree with the admitted
    structure.
11. **Docs gates.** `scripts/check-docs`, `scripts/check-static`, and
    `scripts/check-tests` pass.

## Bounds rationale (informative)

**Why two levels.** The fixed target's two-level structure is the only multi-level
surface the experiment has ever exercised, so one level of proposal reproduces
exactly the known case and two levels test the boundary without reaching
unbounded recursion. A third level would be new surface with no reference
behaviour to calibrate against.

**Why the table's 6 and a per-trial 32.** The per-node limit is not the pilot's to
set: `maximum_children_per_node` is 6 and a component needing more than six
children is a signal the component split is wrong, not that the pilot should
accommodate it. The per-trial ceiling exists so the bound is enforceable at a
second site — a parent-level check alone would let many parents each contribute
their maximum.

**Why the model has no authority.** The option (e) chain established that a
structure claim is only worth what its measured divergence is worth. A model
proposal admitted by the model would reintroduce exactly that problem one level
down. The validator is the whole safety argument; the model only chooses what to
propose.

## Residual and inherited surface (informative)

Unchanged and still accepted as bounded, per the option (e) re-review ruling:
concerns 2 (nested-child edge projection — now with a named re-open trigger in S7
of the option (e) spec), 4 (module-candidate order), 5 (the scan reads the whole
tracked tree rather than `owned_scope`), 6 (git-call amplification), and 7
(home-grown relative-import resolution).

This pilot adds two of its own, to be reviewed with it rather than inherited
silently:

- A proposal's *content* is model-generated and is not itself derivable, so its
  divergence cannot be measured — only its shape can be. The gate admits the
  shape, and the content is bounded by P3–P5 rather than justified.
- The nesting bound interacts with `derive_dependencies`, which projects no nested
  structure. A pilot-admitted nested edge is therefore unmeasured by construction,
  which is the S7 asymmetry the pilot inherits rather than resolves.
- **A parent must own a scope the containment rule can anchor on.**
  `scope_contained` refuses an all-glob parent prefix, so a run whose root owns a
  bare `**` cannot use the pilot: there is no subtree to reason about. The fixed
  target owns `src/**`, which is fine, and a whole-tree parent is better expressed
  as an explicit region. Recorded rather than changed, because widening the rule to
  admit `**` would undo the deliberate choice that a parent owning nothing cannot
  authorise a child
  ([re-review 2](phase4-recursive-planning-pilot-re-review-2.md), R2).
- A parent may own **several** scopes; containment is "inside any of them", so a
  child in the parent's second declared region is admitted. The `parent_scope`
  argument to `admit_proposal` is an **assertion, not a restriction**: it lets a
  caller state which region it believes it is subdividing and is refused if the
  contract disagrees, but containment always uses the contract's full scope set.
  A producer may therefore omit it entirely.
- **The admitted payload is mutable and the reducer does not re-check scope
  containment.** The guard deep-copies so a provider's own objects are safe, but
  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, or the
  reducer must gain the scope check — a change to the harness contract that the
  single-layer decision above forbids. Recorded by the producer review (F4) and the
  re-review that accepted it (R3); not a producer-logic defect, a wiring constraint.
- **`RunState.clone()` is deliberately not used for provider isolation.** It is
  cheaper and its purity contract is enforced by `tests/test_state_purity.py`, but
  that contract is scoped to "every container *the reducer can mutate*" — nested
  values the reducer never touches are shared on purpose. A model provider is not
  the reducer, so the cheaper primitive optimises against the wrong threat model and
  would reopen the P0. `copy.deepcopy` is retained
  ([producer re-review](phase4-recursive-planning-pilot-producer-re-review.md), R4).
- **Scope containment has one layer.** `validate_decomposition` does not enforce
  it, so the pilot guard is the only enforcement
  ([review report](phase4-recursive-planning-pilot-review-report.md), F1). Adding
  it to the validator is a change to the harness's decomposition contract, not a
  defence-in-depth addition: existing admitted proposals have children whose
  scopes escape their parent's declared scope, so enforcing it rewrites semantics
  the committed milestone evidence was measured under. Pinned as a recorded gap
  by `TestContainmentIsSingleLayer`. The guard deep-copies, so a post-admission
  mutation cannot bypass the single check.
- `_nesting_shape` is one level deep (F10), so a grandchild-level change is
  invisible to the `NESTING` axis. Named for the S7/S12 residual surface rather
  than fixed here, and it becomes load-bearing if the pilot admits depth-2
  structures whose divergence must be measured.
