<!-- informative -->

# Reviewer Brief: Phase 4 Option (e) — Evidence-Typed Obligation Source and the Declared-Structure Gate

## Mandate

Independently falsify the decomposition-structure change landed in
**`d78862d`** before the bounded recursive-planning pilot builds on it. The
change is small in surface and load-bearing in consequence: it makes
`build_target` **refuse** inputs it previously accepted, and it introduces a
declaration path whose entire legitimacy rests on a computed diff.

Under review, in one commit:

- **`d78862d` — Phase 4: derive obligations, and make a declaration
  mechanically justified** (`derive_obligations.py`, `data/fixed-target-obligations.yaml`,
  `experiment_target.py`, `experiment.py`, `trial_driver.py`,
  `tests/test_derive_obligations.py`, `tests/test_phase2_general_target.py`,
  `tests/test_phase3_project_oracle.py`, `docs/glossary.md`, `docs/self-host.md`,
  `docs/research/phase4-decomposition-design.md`,
  `docs/research/phase4-option-e-implementation-spec.md`).

The parent `e7534fc` (A2 closed as no change) is unrelated to Phase 4 and out
of scope. Use `git show d78862d^:…` for every pre-image.

**The claim to attack.** Option (e) exists because a hand-authored obligation
set could previously be supplied to `build_target` with no justification: a
declaration was indistinguishable from a derivation, so the Phase 4 exit gate
("no hand-authored obligations") was satisfiable by assertion. The change
replaces assertion with measurement — derivation is always recomputed, and a
declaration is admitted only if it is *measurably divergent* on a named axis. The
design's central claim is the negative one:

> A declaration that stops being necessary starts failing on its own, with no
> checklist to update.

If a declaration can be made to persist after its justification evaporates, the
gate is decorative and Phase 4's exit is not met. That is the primary target.

**Independence:** you must not be the author of `d78862d`,
`derive_obligations.py`, `tests/test_derive_obligations.py`, or of
`phase4-option-e-implementation-spec.md` — the spec that *directs* the
implementation, so a spec bug and an implementation bug are indistinguishable
unless you check the pre-images and the normative documents yourself. Read the
normative documents and the pre-images first; treat the tests, the spec, and
every docstring as claims to verify, not evidence.

## Target

- Repo: `/home/ruben/Projectos/meta-project/orchestrator`
- Revision reviewed: **`d78862d`** (tip). Local, not pushed. Name the tree you
  reviewed (`git worktree add --detach /tmp/kilo/phase4-review d78862d`).
- Normative documents: `docs/experiment.md`, `docs/executors.md`,
  `docs/control-plane.md` (the reducer contract and replay rules the
  decomposition feeds), `docs/glossary.md` (the catalogued
  `EDGES`/`NESTING`/`ALLOCATION` axes and obligation sources),
  `docs/research/phase4-decomposition-design.md` (the derivation contract),
  `docs/research/phase4-option-e-implementation-spec.md` (the directive under
  test), and `docs/self-host.md` (the Phase 4 gate clause being rewritten).
- Baseline (none of these is a verdict): `.venv/bin/python -m pytest -q` (expect
  **770 passed**); `scripts/check-tests --fast` (**740 passed, 30 deselected**);
  `scripts/check-docs` (**229** links OK); `scripts/check` and
  `scripts/check-static` rc 0.
- No source edits, no third-party network, no real credentials, no paid calls.
  Probes and reproducers under `/tmp/kilo/`.

## The guarantees under review

Each is a claim made by `d78862d`. Falsify any of them.

1. **Typed-field discipline.** `DERIVED` carries empty axes and an empty
   reason; `DECLARED` carries a non-empty subset of the catalogued axes and a
   non-empty reason. Both directions are refused, so a `DERIVED` target cannot
   smuggle a stale rationale and a `DECLARED` target cannot carry unexplained
   axes. Supplying `obligations` implies `DECLARED`.
2. **Derivation is always recomputed**, on both paths. A raising derivation is
   fatal with `ExperimentError` whatever the caller supplied. There is no
   `obligations=` bypass — no argument, flag, or call ordering that reaches the
   snapshot without a re-derivation.
3. **Admissibility requires measured divergence.** A `DECLARED` set identical to
   the derived set is refused. The named axes must be a subset of the axes
   actually measured. A non-empty rationale is required.
4. **The diff is measured against live policy**, not a hard-coded checklist: a
   declaration resting on an axis that later becomes derivable starts failing
   without any code or checklist change.
5. **Projection is a bijection onto components.** Each top-level declared scope
   is expanded against the tracked Python files at the base commit; every matched
   file must be owned by exactly one component; zero matched files, multi-
   component scope, a doubly-claimed component, and an unclaimed component all
   fail closed.
6. **Validation order is normative**: shape → coverage → projection →
   predicate. A scopeless obligation fails at the boundary rather than with a
   `KeyError` at `plan_decomposition`; coverage precedes projection because the
   allocation comparison consumes coverage-validated criterion sets.
7. **Nested validation** applies the top-level shape rules recursively, plus
   non-vacuity: a nested `criterion_ids` is a non-empty subset of both the
   parent's criteria and the declared criteria, and nested budgets are finite
   and non-negative.
8. **The fixture's contract is byte-identical.** Moving the declaration from a
   Python constant into a versioned manifest does not change the fixed target's
   `contract_hash` (`sha256:157bbd15b2d3e6cf86cd13f44f2ac6a4d94ee79561dd76c9173c95fdf40cf848`),
   its `report → (parse, render)` ordering, its two-level nesting, its
   calibration devices (`trial_scripts`), or the absoluteness of `repository`.
9. **Budgets are declared input on both paths**, keyed by component name, with
   unknown keys refused so a typo cannot silently leave the default in place.
10. **Identity**: the typed fields are in `snapshot_hash` and out of
    `contract_hash`, so a post-build mutation of either changes target identity
    (the F10 rule) while the fixture's contract identity is untouched.

## In scope

- `derive_obligations.py` in full: the import scan, the projection, the axis
  measurement, the predicate, and the budget resolution.
- `build_target`'s validation pipeline, and the ordering of its four stages.
- `TargetSnapshot`'s typed fields and their presence in `snapshot_hash`.
- The fixture manifest `data/fixed-target-obligations.yaml`, its loader, and the
  claim that it is fixture-owned, versioned data rather than scheduler code.
- Every `obligations=` call site and its migration (spec S11's disposition
  table is the checklist; verify each row was migrated as specified and that no
  row was left half-done).
- The rewritten Phase 4 gate clause in `docs/self-host.md`: does it now state
  only what is enforced?
- The `NESTING`/`ALLOCATION` declarations in existence today (the fixture
  manifest, the greet target) — are they the *minimum* claim, and would they
  survive a change that made their axis derivable?

## Out of scope

- `_commands_for` and `_SOLUTION_FILES`. The gate clause names them out of
  scope on two grounds: they are candidate production rather than
  decomposition, and they are transitional machinery retired when the patch
  path replaces the scripted path. Attack that *reasoning* only if you think the
  exclusion hides a decomposition defect, not the command map itself.
- The bounded recursive-planning pilot (not implemented; specified only).
- The A2 closure in `e7534fc`, and Phase 3's oracle, both reviewed separately.
- Performance, except where a defect is a denial-of-service on a real target
  (see the disclosed git-call amplification below).

## Known residuals and disclosed concerns — acknowledge, do not re-report as novel

The implementer volunteers these. They are judgement calls, not oversights, and
several are consequences the spec accepted on purpose.

1. **The predicate is permissive about unnamed axes (deliberate, spec S5).** A
   declaration must name axes that were *measured*, and at least one, but it may
   diverge on axes it does not name. So a declaration can carry more divergence
   than it claims. Requiring exact equality would force declarations to name
   axes that do not apply to them. **Attack this**: can a declaration be admitted
   on a token axis while resting almost entirely on undeclared divergence? If
   yes, is that a gate defect or the intended cost of not forcing spurious
   claims?
2. **`EDGES` is measured only for pairs the projection can express.** A declared
   edge to a *nested* child id, or one expressed by path rather than child id,
   may project to nothing and read as "no edge" rather than as divergence.
3. **File-backed projection is asymmetric (accepted, spec S4).** A `DECLARED`
   set cannot describe a file-less greenfield component, because its scope
   expands to zero files, while the derived path emits an obligation per
   component regardless. Accepted fail-closed; pattern-containment resolution is
   the named extension.
4. **Module resolution is order-sensitive.** `_module_candidates` prefers
   `pkg/sub.py` over `pkg/sub/__init__.py`. If both exist, the choice is
   arbitrary, and the two can belong to different components.
5. **The import scan trusts the whole tracked tree.** An edge can be created by a
   file outside the target's `owned_scope`, because the scan reads `git ls-tree`
   rather than filtering by scope. Whether that is right is a judgement about
   what an integration dependency *is*.
6. **git-call amplification.** `_python_files` (an `ls-tree`) runs at least
   three times per build — `derive_dependencies`, `project_declared_obligations`,
   and via `measure_divergent_axes`. Each is O(tree) plus a subprocess. Not a
   correctness defect; a real per-target cost.
7. **Relative-import resolution is home-grown.** `from . import a` /
   `from ..pkg import m` are resolved against the file's own package with a
   level-count heuristic. Try to make it wrong: a package whose `__init__` is
   absent, a module shadowed by a same-named file at a different depth, a `*`
   import, a `try: import x except ImportError: x = None` guard.
8. **Validation was written before its tests, in one pass.** The implementer
   introduced and fixed three real defects during the change (a docstring
   terminator deleted during an edit, a scope bug from a mis-indexed deletion, a
   coverage/predicate ordering mistake in a test that then asserted the wrong
   rule). Treat that as evidence the seams are under-tested, not as a list of
   known bugs.

## Attacks to attempt (minimum)

Each is a falsification attempt with a defined success condition. A defence
that holds is a result, not a failure.

**A. Make a declaration outlive its justification (the primary attack).**
Construct a repository where the fixture's declared divergence genuinely
evaporates — for example by making the declared `report → (parse, render)`
ordering real in the tree so derivation observes it — and confirm
`build_fixed_target` then *refuses*. Success condition: the build still
succeeds, or fails for some reason other than inadmissibility. This is the
claim that the gate is self-enforcing.

**B. Reach a snapshot without re-deriving.** Try every route:
`obligations_source="DERIVED"` with obligations supplied; omitting
`non_derivable_reason`; an empty-string reason; an axis list containing an
uncatalogued name; whitespace-only axes or reason; `obligations` passed as a
generator or other non-`Sequence`; `budgets` naming no component; a budget key
that is a near-miss of a real component. Success condition: any accepted target
whose structure was not measured.

**C. Break the bijection.** Components claimed zero times, twice, or by an
obligation whose glob matches files in two components; a scope that matches only
non-Python files; a declared obligation whose scope is a superset of its
component's. Success condition: a projection that maps two obligations onto one
component, or silently drops one.

**D. Make coverage and projection disagree.** Find an input where the
allocation axis is measured against an unvalidated criterion set, i.e. where
reordering S6's stages changes an outcome. Try coverage-passing-but-
shape-failing and shape-passing-but-projection-failing inputs.

**E. Nested escapes.** A nested obligation whose `criterion_ids` is empty,
names a criterion the parent does not own, names a declared criterion the parent
does not own, has a non-finite or negative budget, is not a mapping, or recurses
into a non-sequence. Success condition: any nested structure that reaches
`plan_decomposition` unvalidated.

**F. Fixture identity.** Mutate the manifest's obligations, budgets, axes, or
reason and confirm `contract_hash` is unchanged while `snapshot_hash` changes.
Then confirm the *unmutated* fixture still matches the pinned literal, keeps
`trial_scripts` (a dropped `trial_scripts` silently turns seeds 1003/1004 into
default kinds, destroying the calibration devices), and keeps an absolute
`repository`.

**G. The import scan, adversarially.** A cycle (recorded, not ordered — confirm
`_ensure_acyclic` still owns that). A file importing a module that does not
exist. Two components whose globs both match a file. A `DECLARED` set whose
edges are *narrower* than derived (should read as `EDGES` divergence) and one
whose edges are *wider* (should read as divergence too — or should it?).

**H. False equivalence.** Construct a `DECLARED` set that differs from derived
only in `description`, `budget`, or child-id spelling, and confirm it is refused
(budgets and spelling are excluded from the comparison by S4 rule 4, so these
alone must not manufacture admissibility).

**I. Bypass the predicate through the derived path.** Confirm a `DERIVED` target
cannot be given a scope narrower than its component, and that
`derive_obligations` cannot be called in a way that returns a narrowed set.

## Method

- Read the normative documents and the pre-images (`git show d78862d^:…`) of
  every changed function first; list the semantic deltas before testing any of
  them. In particular diff `build_target`'s validation pipeline against its
  pre-image and account for every stage that moved.
- Drive the real entry points — `build_target`, `build_fixed_target`,
  `load_fixed_target_obligations`, `derive_obligations`,
  `measure_divergent_axes`, `is_admissible` — with throwaway git repositories
  under `/tmp/kilo/`. Use the project's `GIT_ENVIRONMENT` fixture identity when
  committing: a bare `git commit` fails where no ambient identity exists.
- Prefer whole-build reproducers (`build_target` over a real tree) over unit
  pokes, and use unit calls only for the projection and predicate questions.
- For each attack: exact commands, the probe (not a source edit), observed vs
  expected, and the guarantee violated. Prefer a failing reproducer. Do not
  weaken or edit tests. If a guarantee holds, say "attacked, not falsified" and
  state the method — that is a valid and useful result.
- When you claim the gate self-enforces (attack A), demonstrate it by making the
  divergence evaporate in a *real* tree, not by asserting the predicate's
  behaviour in isolation.

## Deliverable

1. **Verdict:** GO / NO-GO for the bounded recursive-planning pilot to build on
   this base.
2. **A ruling on the predicate's permissiveness** (disclosed concern 1): is
   "named axes must be measured, at least one, extras unnamed" the right
   admission rule, or does it let a declaration carry unclaimed divergence? If
   it is wrong, state the rule you would substitute and the failure it closes.
3. **Findings** with severity (P0/P1/P2), the guarantee violated, a minimal
   reproducer, observed vs expected, and the proposed permanent regression test.
4. **Claims verified:** each of the ten guarantees with its falsification attempt
   and outcome.
5. **A table of every `DECLARED` target in the tree** (the fixture manifest, the
   greet target) with its measured axes, its named axes, and whether the named
   set is minimal — i.e. could a smaller honest claim be admitted? Any row whose
   declaration could be replaced by derivation without loss is a finding.
6. **Residual unknowns:** what you could not test and why.

## Exit criteria

- Every guarantee is either falsified with a reproducer or explicitly
  "attacked, not falsified" with the method.
- Attack A is resolved with a real-tree demonstration in one direction or the
  other, not by unit assertion.
- The gate-clause rewrite in `docs/self-host.md` is checked against what the
  code enforces: every "is" in the clause has a corresponding check, and the
  clause's explicit non-claims (edge necessity, `_commands_for`) are honest.
- The S11 disposition table is verified row by row, including that no migrated
  call site silently kept a declaration that no longer needs one.
- No source edits, no real credentials, no paid calls; host state left clean.
- Findings are reproducible from the report alone against `d78862d`.
- The review states what it did not cover.

## Reproduce everything

List every probe command, tree-mutation script, manifest variant, and worktree
revision here so the verdict can be re-run against a corrective revision.
