<!-- normative -->

# Phase 4 design: derived obligations, and a bounded recursive-planning pilot

This is the design brief for self-hosting Phase 4 ("General Decomposition"). The
phase goal in [self-host.md](../self-host.md#phase-4-general-decomposition) is to
decompose a real repository without hand-authored obligations, deriving criterion
coverage and owned scopes from the task and the kernel, and to lift the exclusion
on recursive planning over model outputs for a bounded pilot. Its exit gate is a
multi-component task decomposing into scoped children that reach evidence-bound
acceptance, with no hard-coded `_ROOT_OBLIGATIONS`.

This document is normative for the derivation contract and its invariants. The
pilot's *scope* is informative and is a review decision, not a consequence of the
derivation.

## What is hand-authored today

Obligations are the only hand-authored part of the decomposition. Everything
downstream of them is already derived: `plan_decomposition`
(`trial_driver.py:72`) turns a contract's declared obligations into children with
node ids, scopes, criteria, budgets and dependencies, deterministically and with
no model call. The hand-authored input is the obligation tuple itself:

- `_ROOT_OBLIGATIONS` (`experiment_target.py:170`) for the fixed target, and
- the mandatory `obligations=` argument to `build_target` for any other target.

The cost of that is visible in the Phase 3 self-target, whose obligations are the
crudest possible decomposition — one child per criterion, each owning `"**"`, with
no dependencies (`tests/test_phase3_project_oracle.py:186`). Three children that
all own the whole tree is not a decomposition; it is a relabelling. And it has to
be rewritten by hand for every new target.

## What may be derived, and from what

The derivation has three inputs, all of which the target already freezes, and one
that does not exist yet and must not be invented.

**Criterion coverage** comes from the target's declared `acceptance_criteria`,
which must equal the oracle manifest's criteria. This is already enforced
bidirectionally by `build_target`: every declared criterion is owned by some
obligation, and every obligation references only declared criteria. Derivation
replaces the *first* half being hand-satisfied; the check itself is retained and
strengthened.

**Owned scope** comes from the kernel's `current_scope` and the target's
`components`, which are already per-target rather than constant. `components` is
a `(name, glob)` sequence — the fixed target declares `parser: src/parser/**`,
`render: src/render/**`, `report: src/report/**`. A component is the natural unit
of ownership: it is a named region of the repository with its own tests.

**Dependencies** are the part that cannot be asserted, only observed. The fixed
target's `report` depends on `parse` and `render` because the report component
integrates their outputs — a fact stated in prose in the task statement. A
derivation that simply copied that prose would be hand-authoring with extra steps.
The honest signal is the repository itself: **an integration dependency is an
actual import**. If the files in component `B` import modules belonging to
component `A`, then `B` depends on `A`. That is observable at the base commit, is
stable under the decomposition, and cannot be inflated by prose.

## The derivation contract

1. An obligation exists per declared component, scoped to that component's glob.
   Derivation never invents a component, and never widens a glob.
2. An obligation's `criterion_ids` is the full declared criteria set, so
   coverage is derived and then verified: the union of obligation criterion ids
   must equal the declared criteria exactly, or derivation fails closed.
3. An obligation's `depends_on` is derived from the cross-component import scan at
   the base commit. A derived obligation may declare no dependency; it may never
   declare one the import scan does not support.
4. Budgets are not inferred. They are declared input on **both** paths, keyed by
   component name and threaded into derivation, because a budget is a spend
   decision rather than a fact about the repository. An unknown budget key is an
   error, so a typo cannot silently leave the default in place.
5. Nesting is not derived. The fixed target's `report` → `report-format` →
   `report-emit` chain encodes an authoring choice about granularity. One level
   of derived obligations is the scope of this phase; deeper structure, and
   criterion-level allocation within a component, are what the bounded
   recursive-planning pilot exists to explore.

**Amendment (option (e)).** Points 2–5 above describe what derivation *produces*.
They no longer describe the whole contract, because a declared obligation set is
now a first-class alternative with a mechanical admission test rather than an
override that merely had to be well-formed. Derivation is always recomputed, and
a declared set is admitted only when it is measurably divergent from it, names
only axes that were actually measured, and carries a rationale. The axes, the
projection that measures them, and the predicate are specified in
[the option (e) spec](phase4-option-e-implementation-spec.md), which supersedes
the mechanism half of this document's gate clause. All three axes are diffs against `derive_obligations`' **live output**, and the
predicate requires the named axes to equal the measured set exactly. The
measured-diff design therefore means a declaration resting on an axis that later
becomes derivable starts failing on its own, with no checklist to update. Both
properties were added in response to the adversarial review
([report](phase4-option-e-review-report.md)); see F2 for why `NESTING` and
`ALLOCATION` had to be re-expressed as real diffs, and the predicate ruling for
why subset admission was replaced with exact equality.

## Why criterion-to-component association is not derivable, and is not derived

The obvious place to read criterion-to-scope association is the oracle manifest:
each `OracleCheck` declares the criterion it grades and the paths it reads, so the
association could be derived from the frozen check set. **That is circular, and the
circularity is structural rather than incidental.** Obligations are part of
`TargetSnapshot.snapshot_hash()`, and the manifest's `target_binding` is R12's
binding to exactly that hash. A derivation that read the manifest would need a
target whose obligations are already derived, and the manifest is only built from
a target. Derivation therefore runs strictly before the manifest exists and cannot
consume it.

What remains derivable without the manifest is the component decomposition: the
target already declares `components` as `(name, glob)` pairs, per target rather
than constant, and those globs are the natural units of ownership. So:

- **One derived obligation per component**, scoped to that component's glob.
- Its `criterion_ids` is the **full declared criteria set**. Every criterion is
  therefore owned, and no obligation references an undeclared criterion — which is
  exactly the bidirectional coverage `build_target` already enforces, now
  satisfied by derivation rather than by hand.
- Criterion-level allocation *within* a component is **not** derived. It is
  deferred to the bounded recursive-planning pilot, where a model proposal
  proposes the allocation and the deterministic validator admits or refuses it.

The consequence is worth stating plainly, because it is the honest result rather
than a shortfall: for a single-component target the derivation yields **one**
obligation owning the whole tree, not three fake children. That is a true
statement about the target. The fixed target, with three components and real
cross-component imports, yields three scoped children with derived dependencies —
which is what the exit gate's "multi-component task" clause asks for.

A one-obligation-per-criterion scheme was rejected: it multiplies obligations
without adding information, and for the self-target it reproduces exactly the
crudeness this phase exists to remove (three children that each own `"**"`).

## Invariants

- Derivation is **deterministic**: the same target snapshot yields the same
  obligations, byte-for-byte. It introduces no clock, no model call, and no
  network. This preserves the property `plan_decomposition` already has.
- Derivation is **fail-closed**: criteria that no check grades, components that
  no criterion constrains, and import scans that cannot be completed are errors,
  not empty obligation sets. An empty decomposition must never read as success.
- Derivation is **bounded**: one level, and at most one obligation per
  (criterion, component) pair. Depth limits remain the controller's, per the
  existing depth guard.
- The controller-side write-scope disjointness check (`decomposition.scopes_disjoint`,
  `child_write_scopes`) is retained. Derivation must produce scopes that pass it,
  and a component layout whose globs overlap fails closed rather than being
  silently narrowed.
- Budget feasibility and acyclicity validation (`validate_decomposition`,
  `budget_feasibility_conflict`, `_ensure_acyclic`) are unchanged and remain the
  authority on the derived graph.
- Declared obligations remain available as an explicit override, so a target that
  genuinely needs hand-shaped structure is not blocked. The override is validated
  against the same bidirectional coverage rule, so it cannot quietly narrow
  grading.

## The bounded recursive-planning pilot (scope is a review decision)

The kernel's `current_non_goals` includes "Recursive planning on model outputs
beyond the experiment arms". Lifting it is the second half of the phase goal, and
it is deliberately **not** folded into the derivation: derived obligations are
deterministic, and a model-produced decomposition is not.

The pilot is bounded on three axes, and the bounds are the review's to set:

- **Depth**: two levels below the derived root, not unbounded recursion.
- **Pilot size**: a bounded child count, so a runaway proposal hits the existing
  depth and count guards rather than the model's judgement.
- **Authority**: a model-proposed child is a *proposal* that must pass
  `validate_decomposition` — budget feasibility, acyclicity, scope disjointness —
  before it becomes a node. Model output never becomes structure without the
  deterministic gate, exactly as a model patch never becomes accepted state
  without the oracle.

`PROJECT_KERNEL`'s non-goal list is where the lift is recorded, and it must be
amended as part of the pilot rather than before it, so the non-goal stays true
until the pilot is admitted.

**Forward obligation on the pilot (option (e) re-review).** Nested child ids are
compared verbatim when the `NESTING` shape is measured. That is sound *only*
because derivation produces no nesting today, so any nesting is genuine
divergence. The moment derivation can nest — which is exactly the F2 scenario the
axis self-tracking test simulates — a nested rename will register as a `NESTING`
divergence exactly as a top-level rename did before R1. The pilot must therefore
exclude nested spelling the way top-level spelling is excluded: key the nested
shape by something other than the declared child id, or re-baseline `NESTING`
against derived nested structure when that structure first exists. This is
recorded here so the pilot inherits the obligation rather than rediscovering the
defect.

## What has landed, and what has not

Landed: `derive_obligations` (`src/orchestrator/derive_obligations.py`) and
`build_target(..., obligations=None)`, which derives one obligation per component
with observed cross-component imports. On this repository it recovers real edges —
`project_oracle` depends on `oracle` and `sandbox`, matching its `from . import`
statements. 16 tests in `tests/test_derive_obligations.py` pin determinism,
observed dependencies, relative-import resolution, and the fail-closed paths.

Not landed, and deliberately so:

- **The bounded recursive-planning pilot** is specified above and not
  implemented. It is a separate change with its own review, and its scope
  (depth, child count, authority) is that review's to set.

Superseded by option (e): the statement above that `_ROOT_OBLIGATIONS` "still
exists, for the fixed target only" described the state before the declaration was
made first-class. The constant is now gone, the fixture's obligations live in
`src/orchestrator/data/fixed-target-obligations.yaml`, and
`build_fixed_target` routes through the single validated `build_target`. The
fixed target's contract identity is unchanged — byte-identical `contract_hash`,
preserved ordering, nesting, and calibration devices — and its declaration is
admitted by measurement rather than by assertion. See
[the option (e) spec](phase4-option-e-implementation-spec.md).

| Exit-gate clause | Where it is satisfied |
|---|---|
| multi-component task decomposes into scoped children | one derived obligation per component; scopes are component globs, never a bare `"**"` |
| children reach evidence-bound acceptance | unchanged oracle path; `plan_decomposition` and `validate_decomposition` are untouched |
| declared structure is reproducibility-checked | the option (e) predicate: derivation always recomputed, admission only on measured divergence with named axes and a rationale |
| no hard-coded `_ROOT_OBLIGATIONS` | met: the constant is deleted, the fixture's obligations live in a versioned manifest, and `build_fixed_target` routes through `build_target` |
| lift the recursive-planning exclusion for a bounded pilot | separate, bounded change with its own review; recorded in the kernel's non-goals at admission |
