core/docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md

# Semantic-Substrate Problem-Solving Master Plan — 2026-06-20

**Status:** proposed implementation plan for architect ratification

**Scope:** math/problem-solving comprehension from substrate proposal through verified derivation

**Governing evidence:** ADR-0223 and its 2026-06-20 audit pack

**Behavioral effect of this document:** none; this is architecture and sequencing only

This plan assumes the merged baseline at `main@60df4fc0` (#833). It does not
authorize serving changes, report mutation, benchmark-case mutation, sealed-artifact
access, pack mutation, or parser deletion. Each material step below remains a separate,
reviewable PR with its own evidence.

## 1. Executive thesis

CORE must replace the current relationship between comprehension and solving:

```text
raw problem text
  -> ordered list of organ-local recognizers
  -> organ-local extraction and arithmetic
  -> answer admission
```

with a constructional, substrate-mediated relationship:

```text
surface chunk
  -> exact semantic-neighborhood proposal
  -> constructional affordance candidate
  -> role-obligation template
  -> exact span grounding
  -> ProblemFrame relation and target
  -> obligation-complete ContractAssessment
  -> typed organ input
  -> independently verified derivation
  -> existing answer admission and articulation
```

The intrinsic space is not a sequence of words and not a bag of numbers. It is a
typed relational field over source spans, entities, quantities, units, events,
states, target operators, temporal order, hazards, and proof obligations. Surface
language is a probe into that field. A probe may resonate with several construction
families, but it cannot determine one by proximity alone.

The governing law is:

```text
semantic closeness proposes;
exact bindings ground;
organ-specific contracts determine;
verification admits;
otherwise CORE refuses.
```

Local raw-text organs are the wrong long-term foundation because each one privately
reconstructs the same semantic facts—entities, quantities, state changes, target
direction, units, and hazards—with different regexes and different failure modes.
That duplicates meaning, makes confuser coverage non-compositional, and prevents a
single correction from improving more than one capability. It also creates a false
choice between broadening a parser and refusing: the missing third door is a reusable
construction layer that can propose broadly while proving narrowly.

The semantic substrate should therefore become the source of *candidate
constructions*, not answers or operators. Reviewed pack entries and exact CGA
neighborhood scans should make `buy`, `purchase`, `acquire`, `gain`, and `receive`
available as related probes. A declarative construction signature should then ask
whether a particular chunk closes roles such as buyer, acquired quantity, acquired
entity, prior state, and target. Hazards provide the conjugate correction: negation,
money targets, entity discontinuity, comparison readings, and incompatible units can
block closure even when the lexical neighborhood is strong.

This transformation is deliberately incremental. The current serving organs remain
the precision reference while `ProblemFrame` builds richer diagnostic evidence.
Only a contract that is runnable from `ProblemFrame` alone, stable under morphology,
blocked by near confusers, deterministic on replay, and parity-checked against the
existing organ may be considered for serving migration. Migration is complete only
when the legacy raw-text parser and its allowlist entry are deleted. Adding a second
path without retiring the first is not migration.

The program optimizes for truthful reusable comprehension, not short-term GSM8K
score. A reduction in runnable count is progress when it removes a false runnable.
The hard safety floor remains `wrong_ids == []`.

## 2. Current-state map

### 2.1 What exists and is sound

| Capability | Evidence | Architectural status |
|---|---|---|
| Geometric field transitions | `algebra/versor.py`, `field/propagate.py` | Live and load-bearing; preserve `versor_condition(F) < 1e-6`. |
| Exact CGA neighborhood/recall | `algebra/cga.py`, `algebra/backend.py`, `vocab/manifold.py`, `vault/store.py` | Exact deterministic scan exists; no ANN, cosine substitution, or stochastic ranking is needed. |
| Checksummed language-pack compilation | `language_packs/compiler.py`, manifests, immutable pack bytes | Correct reviewed source boundary for lexical state. |
| Exact scalar normalization | `language_packs/scalar_equivalence.py`, `language_packs/numerics_loader.py` | Produces exact `Fraction` values and source spans. |
| Unit and dimension facts | `language_packs/unit_dimensions.py` | Useful typed lexical facts; coverage is narrow but the boundary is sound. |
| Central ambiguity vocabulary | `language_packs/ambiguity_hazards.py` | Correct place for reusable corrective conditions. |
| Provenance-bearing kernel facts | `generate/kernel_facts.py` | Immutable facts, exact spans, and provenance distinctions are sound. |
| Purpose-specific graph separation | `ProblemFrame`, `EpistemicGraph`, math state, `PropositionGraph` | Healthy separation; preserve it. |
| Existing math verifier/admission discipline | derivation verification and GSM8K runner | The `wrong == 0` safety posture is the reference constraint. |
| Reviewed learning/promotion boundaries | `teaching/*`, ADR-0218, Vault invariants | Construction/catalog changes must use the same proposal/review discipline. |

### 2.2 What exists but is diagnostic only

`build_problem_frame()` extracts scalars, units, hazards, process candidates,
mentions, bindings, relations, and a bound question target. The adequacy and
morphology scripts expose candidate and runnable contract counts. None of this
changes serving. That is correct at the current maturity level.

`ContractAssessment` is the correct kind of gate but currently carries a coarse
`runnable: bool` and incomplete obligations. The material percent-partition
assessment can report closure without proving numeric-whole provenance, partition
topology, subgroup distinctness/coverage, or target direction.

### 2.3 What bypasses the intended design

- `generate/math_candidate_graph.py::parse_and_solve` invokes a sequence of
  `resolve_promotable_*` functions with raw problem text.
- `generate/derivation/fraction_decrease.py` and
  `generate/derivation/percent_partition.py` independently parse prose, bind values,
  reject confusers, derive answers, and self-verify.
- `ProblemFrame` is imported by diagnostics and tests, not by the serving organs.
- The no-new-legacy test contains the spread but does not shrink it until a migrated
  parser is removed from its allowlist.

### 2.4 What is named like substrate but is still local parsing

- `generate/process_frames.py` declares useful family/role vocabulary, but family
  discovery is a hard-coded `trigger_surfaces` string scan.
- `_ENTITY_AFTER_QUANTITY_RE`, `_FRACTION_ENTITY_RE`, `_ACTOR_VERB_RE`, and
  `_TRANSFER_RE` in `problem_frame_builder.py` are bounded diagnostic scaffolds, not
  semantic-substrate retrieval.
- Percent/fraction relations currently use local surface patterns and a positional
  first-whole heuristic.
- Question binding recognizes a small `how many/how much` surface and under-models
  operator, state, scope, and direction.
- `en_core_math_v1/frames.jsonl` is zero bytes. The manifest pins the SHA-256 of empty
  bytes, so the math pack does not yet carry reviewed construction semantics.

Renaming any of these mechanisms to “affordance retrieval” without changing its
authority, evidence, and tests would be relabeling, not architectural progress.

### 2.5 What must not be touched yet

- Do not wire `ProblemFrame` into `math_candidate_graph.py` during diagnostic
  construction work.
- Do not edit derivation organs in the proportional-closure PR.
- Do not change serving thresholds, report files, case files, sealed artifacts, or
  answer labels.
- Do not add normalization to `generate/`, propagation, Vault, or telemetry paths.
- Do not alter `determine()` or introduce `FrameVerdict`; ADR-0222 remains proposed
  and closed-world semantics are unrelated to math contract readiness.
- Do not turn `PropositionGraph` or `EpistemicGraph` into the math comprehension IR.
- Do not delete a legacy parser before a typed, verified replacement has passed
  shadow parity and confuser evidence.

## 3. Target architecture

### 3.1 End-to-end flow

```text
reviewed pack bytes
  -> compiled lexical manifold + compiled construction catalog
  -> chunk probes
  -> exact semantic-neighborhood proposals
  -> construction candidates and role-obligation templates
  -> exact span/fact binding + competing-binding record
  -> ProblemFrame relations, states, dimensions, hazards, and question target
  -> organ-specific ContractAssessment
  -> immutable typed organ projection
  -> verified derivation / proof
  -> existing admission and articulation
  -> deterministic replay evidence
  -> reviewed proposal gate for durable learning
```

### 3.2 Layer contracts

| Layer | Allowed input | Required output | Must never do |
|---|---|---|---|
| Surface chunking | Original problem text and deterministic token/span boundaries | Ordered chunks with exact character spans | Normalize field state, infer answers, use labels/case IDs, or erase original spans. |
| Semantic-neighborhood proposal | Chunk probes, compiled manifold, reviewed candidate subset | Deterministically ranked candidate construction IDs plus lexical evidence and exact CGA scores | Treat score as proof; choose an operator; use ANN/HNSW/cosine/randomness; mutate packs. |
| Construction catalog | Reviewed, checksummed data-only pack records | Immutable construction signature, role obligations, hazards, candidate relation/operator families | Execute code from pack data; contain organ logic; encode benchmark case IDs; become a universal grammar. |
| Construction binder | Candidate signature, chunk spans, `KernelFacts`, local discourse evidence | Zero or more explicit role bindings, competing bindings, and blocker evidence | Reparse in a derivation organ; invent missing roles; silently resolve ambiguity; compute the answer. |
| `ProblemFrame` | Kernel facts and bound construction evidence | Purpose-specific math facts: entities, quantities, units, state/event relations, target semantics, hazards, provenance | Own epistemic standing, articulation policy, solver steps, or an answer. |
| `ContractAssessment` | One `ProblemFrame` and one organ contract | Candidate/blocked/runnable state, closed obligations, blockers, hazards, and evidence spans | Parse raw text, perform arithmetic, fall back to a legacy parser, or grant generic readiness. |
| Typed organ adapter | A runnable, contract-specific assessment and frame | Minimal immutable organ input with exact values, units, target, and provenance | Pass raw prose, drop target direction/provenance, or project fields for unrelated organs. |
| Derivation organ | Typed closed input | Derivation steps and proof/verification material | Recover missing semantics from raw text; mutate memory; bypass verification. |
| Admission/articulation | Verified derivation and existing runtime policy | Existing answer/surface record with trace evidence | Promote an unverified candidate; collapse walk/articulation/surface contracts. |
| Replay/learning gate | Canonical construction, binding, contract, derivation, and verdict evidence | Stable digest and, when reviewed, a proposal | Directly mutate catalog, packs, identity, policy, or Vault standing. |

### 3.3 State machine

```text
UNSEEN
  -> PROPOSED       semantic or exact construction evidence exists
  -> PARTIAL        at least one required role is grounded
  -> AMBIGUOUS      competing bindings or a blocking hazard remains
  -> CLOSED         all construction roles and corrections are proven
  -> RUNNABLE       a named organ contract accepts a typed projection
  -> VERIFIED       the organ derives and the independent verifier accepts
  -> MIGRATED       serving consumes the typed path
  -> RETIRED        the legacy parser and allowlist entry are deleted

PROPOSED | PARTIAL | AMBIGUOUS | CLOSED -> REFUSED when no licensed transition exists
```

`CLOSED` is construction closure, not answer correctness. `RUNNABLE` is specific to
one organ. `VERIFIED` does not grant epistemic promotion or durable learning.

## 4. Constructional affordance catalog plan

### 4.1 Minimal catalog shape

Use the existing checksummed pack compilation boundary, but version the current
frame artifact into a safe data-only construction catalog. A record needs only:

```text
construction_id
family
semantic_domain anchors
declarative chunk signature
required role declarations
optional role declarations
candidate relation families
candidate operator families
blocking/advisory hazard IDs
negative licenses
provenance/evidence hashes
schema version
```

The signature format must be closed and non-executable: ordered anchor sets, typed
slots, span adjacency/scope constraints, and reference requirements. No Python,
dynamic import, arbitrary regex, template code, or answer expression belongs in
pack data. Exact arithmetic and organ-specific obligations remain outside the
catalog.

Start with one or two reviewed signatures per family. Expand only when morphology
and confuser tests prove the same geometry across surface variants.

### 4.2 Initial families

#### Proportional change

| Axis | Initial design |
|---|---|
| Semantic neighborhood | decrease, reduce, lower, increase, raise, grow; to/by/of; fraction/percent scales |
| Signatures | `state decreases to scale of base`; later `state decreases by scale of base` and `state increases to/by scale` as distinct constructions |
| Required roles | state/entity, prior/base quantity, scale, transition kind (`to` vs `by`), question target operator and direction |
| Optional roles | unit, actor/causer, duration/time anchor, explicit final state |
| Hazards/confusers | final-value vs delta target, affine “fraction more than,” percent-change vs percent-of, multiple scales, ambiguous base, negation, unit mismatch |
| Candidate operators | `scale_final_state`, `difference_from_base`; candidates only |
| Tests | lexical invariance; `0005` positive; final-value, affine, multiple-fraction, unit/entity mismatch, and ambiguous-base refusals |
| Readiness | exactly one base/scale/state transition; `0 < scale < 1` for decrease; entity/unit continuity; explicit delta target for `fraction_decrease`; no blocker |

#### Acquisition / transaction

| Axis | Initial design |
|---|---|
| Semantic neighborhood | buy, purchase, acquire, get, receive, gain, collect; sell/pay/cost as related but distinct transaction probes |
| Signatures | `actor acquires quantity of entity`; `buyer purchases quantity at price`; money-target constructions remain separate |
| Required roles | acquirer/buyer, acquired quantity, acquired entity, event direction, target state |
| Optional roles | seller, unit price, total cost, money delta, prior possession state, time |
| Hazards/confusers | “more” comparison, target asks cost/change, entity mismatch, sale direction, negation, division/fraction subproblem |
| Candidate operators | positive possession delta, total cost, remaining money; contract chooses at most one |
| Tests | `buy/purchase/acquire/receive` topology invariance; money-target and comparison confusers; same-entity continuation; passive voice later |
| Readiness | acquisition event and target refer to the same possession entity; quantity is grounded; target chooses final possession or a separately licensed money contract |

#### Transfer

| Axis | Initial design |
|---|---|
| Semantic neighborhood | give, hand, pass, send, donate, lend, receive, sell, trade |
| Signatures | `source transfers quantity/entity to recipient`; inverse voice is a distinct surface signature over the same relation |
| Required roles | source actor, recipient actor, quantity, transferred entity, direction |
| Optional roles | price/value, unit, prior/final state for either participant, time |
| Hazards/confusers | pronoun ambiguity, passive voice, sell-vs-give value topology, omitted recipient, negation, source/target reversal |
| Candidate operators | paired negative/positive possession deltas; optional value exchange |
| Tests | active variants; source/recipient reversal; missing recipient; pronoun collision; sale with money target |
| Readiness | distinct source/recipient, one grounded quantity/entity, explicit direction, target participant/state, and no unresolved reference hazard |

#### Loss / consumption

| Axis | Initial design |
|---|---|
| Semantic neighborhood | use, spend, eat, consume, lose, remove, discard, give away |
| Signatures | `owner consumes quantity of entity`; `owner loses quantity from prior state` |
| Required roles | owner/affected entity, consumed/lost quantity, resource entity, negative direction, target state |
| Optional roles | prior state, final state, rate, recipient for give-away, time |
| Hazards/confusers | spending money vs consuming objects, “lose weight” goal, gain verb currently mixed into consumption, target asks consumed amount vs remainder, negation |
| Candidate operators | negative possession delta, remainder/final state |
| Tests | use/spend/eat variants; money dimension; goal-language refusal; consumed-vs-remaining target pairs |
| Readiness | resource dimension and entity continuity proven; event ordered after prior state; target explicitly requests loss or final remainder |

#### Rate / per / each

| Axis | Initial design |
|---|---|
| Semantic neighborhood | per, each, every, hourly, daily, rate, for each |
| Signatures | `numerator quantity per denominator unit/entity`; `count repeated for each member/interval` |
| Required roles | numerator quantity/dimension, denominator quantity/dimension, participant/event, requested output dimension |
| Optional roles | duration, count of instances, schedule window, currency, conversion fact |
| Hazards/confusers | occurrence “times,” every-other schedule, unit inversion, per-total ambiguity, incompatible dimensions |
| Candidate operators | dimensional product/quotient, repeated propagation |
| Tests | rate-axis swaps; each/per paraphrases; incompatible units; occurrence-times confusers; exact unit conversion |
| Readiness | numerator/denominator axes are explicit, dimensions compose to target dimension, repetition count/window is grounded, no inferred conversion |

#### Comparison

| Axis | Initial design |
|---|---|
| Semantic neighborhood | more than, fewer than, less than, difference, twice/as many, greater/smaller |
| Signatures | `subject is additive delta from reference`; `subject is multiplicative scale of reference`; `question requests directed difference` |
| Required roles | subject entity/quantity, reference entity/quantity, comparator kind, amount/scale, direction, target |
| Optional roles | unit, time/state scope, equality anchor |
| Hazards/confusers | “more” in acquisition, reversed reference, additive vs multiplicative reading, occurrence “times,” missing subject |
| Candidate operators | directed difference, affine projection, scale relation |
| Tests | role-reversal pairs; additive/multiplicative pairs; acquisition confuser; question-direction pairs |
| Readiness | comparator family and reference direction are explicit; both entities/quantities share a compatible dimension; target scope is grounded |

#### Remainder / final state

| Axis | Initial design |
|---|---|
| Semantic neighborhood | left, remain, remaining, after, still has, final, originally |
| Signatures | `initial state followed by ordered deltas yields final state`; `known final plus licensed deltas reconstructs initial` is a distinct inverse construction |
| Required roles | state entity, state direction, ordered event/delta set, known state, requested state |
| Optional roles | actor, unit, intermediate states, time anchors |
| Hazards/confusers | adjectival/directional “left,” inverse topology, omitted initial state, unordered events, entity discontinuity |
| Candidate operators | forward state fold, inverse reconstruction; never interchangeable |
| Tests | forward/inverse pairs; `0393` remains blocked for forward percent partition; lexical “left” confusers; event-order permutations |
| Readiness | target state/direction explicit; every delta is bound and ordered; entity/unit continuity holds; organ explicitly licenses forward or inverse topology |

#### Container / part-whole

| Axis | Initial design |
|---|---|
| Semantic neighborhood | box, bag, crate, pack, group, part, half, percent of, portion, whole |
| Signatures | `N containers each contain M entities`; `whole partitioned into distinct subgroups`; `scale of subgroup has property` |
| Required roles | container/content/count-per/container-count, or whole/part/scale/subgroup identity/coverage; target aggregation |
| Optional roles | remainder, capacity, loose items, nested container, actor |
| Hazards/confusers | subgroup alias collision, incomplete coverage, final remainder mistaken for whole, nested partition, count-vs-capacity |
| Candidate operators | cardinality product, partition allocation, subgroup aggregation |
| Tests | `0046` positive; subgroup identity/coverage negatives; `0393` inverse blocker; nested container and loose-item confusers |
| Readiness | numeric whole precedes and scopes the partition; required subgroups are distinct and covered; scales bind to the correct subgroup; target is forward aggregate |

#### Temporal / schedule

| Axis | Initial design |
|---|---|
| Semantic neighborhood | before, after, during, hour/day/week, every other, schedule, starts/ends, for N hours |
| Signatures | `event lasts duration`; `event recurs over interval`; `ordered events/states anchored in time` |
| Required roles | event, duration/interval, temporal order or recurrence rule, target temporal quantity |
| Optional roles | start/end, participant, rate, calendar fact, exception window |
| Hazards/confusers | clock time vs duration, every-other parity, inclusive endpoints, unrelated forecast duration, calendar/world-fact provenance |
| Candidate operators | duration sum/difference, recurrence count, schedule projection |
| Tests | clock-vs-duration; inclusive/exclusive boundary; forecast-duration confuser for `0005`; calendar provenance refusal |
| Readiness | time quantities have correct dimension and scope; order/recurrence is explicit; any calendar fact has kernel provenance; target is temporal |

#### Unit / currency relations

| Axis | Initial design |
|---|---|
| Semantic neighborhood | dollars/cents, degrees, miles, hours, items; cost, worth, change; pack-backed unit aliases |
| Signatures | `quantity bears unit`; `exact compatible conversion`; `currency amount per item/time`; `money remainder/change` |
| Required roles | scalar, unit, dimension, target dimension; both endpoints for conversion |
| Optional roles | currency denomination, rate denominator, entity counted, exact conversion fact |
| Hazards/confusers | count noun classified as unit, money vs item quantity, temperature change vs final temperature, unsupported conversion, mixed currencies |
| Candidate operators | identity/unit binding, exact conversion, dimension composition; no approximate conversion |
| Tests | compatible/incompatible dimensions; exact ratio replay; money/item target pairs; unit continuity across state change |
| Readiness | every arithmetic operand has a compatible role dimension; conversions come from exact reviewed facts; target unit/dimension is proven |

## 5. Immediate PR sequence

The sequence separates obligation soundness, catalog authority, proposal geometry,
role binding, organ adaptation, and serving migration. Later PRs may split further;
they must not collapse gates to chase score.

### PR 1 — proportional closure and readiness correction

| Field | Plan |
|---|---|
| Title | `feat(kernel): close proportional-decrease contracts and make readiness obligation-sound` |
| Branch | `codex/problemframe-proportional-change-closure` |
| Purpose | Make train `0005` diagnostically runnable from `ProblemFrame`; keep `0046` runnable under explicit obligations; make holdout `0393` non-runnable. |
| Likely files | `generate/kernel_facts.py`, `generate/problem_frame.py`, `generate/problem_frame_builder.py`, `generate/problem_frame_contracts.py`, `generate/process_frames.py`, `scripts/gsm8k_problem_frame_adequacy.py`, `scripts/gsm8k_substrate_morphology.py`, focused tests listed in §6. |
| Non-goals | No derivation-organ edits, `math_candidate_graph.py`, serving wire, catalog compilation, pack bytes, report/case/sealed files, answer derivation, or score lift. |
| Tests | Builder/contract positives, target-direction and topology confusers, deterministic replay, adequacy metrics, no-new-legacy, serving reports in memory. |
| Expected movement | Train runnable `1 -> 2` (`0005`, `0046`); holdout runnable `1 -> 0`; serving remains train `30/20/0`, holdout `5/495/0`, `wrong_ids=[]`. |
| Safety gates | Contract reads only `ProblemFrame`; no raw-text fallback; exact spans; false-runnable removal required; no serving diff. |
| Agent | Codex/Opus at high reasoning for implementation; XHIGH performs merge-blocker review. Grok is not appropriate for the semantic design. |

### PR 2 — explicit readiness stages and evidence accounting

| Field | Plan |
|---|---|
| Title | `feat(kernel): type contract readiness stages and blockers` |
| Branch | `codex/problemframe-readiness-stages` |
| Purpose | Replace headline dependence on a boolean with candidate/blocked/runnable/verified/migrated diagnostic stages while retaining organ-specific assessments. |
| Likely files | `generate/problem_frame_contracts.py`, adequacy/morphology scripts, focused tests, runtime-contract documentation if a public diagnostic schema changes. |
| Non-goals | No new constructions, organ adapters, serving, or generic solver state. |
| Tests | Serialization/order, illegal stage combinations, blocker preservation, false-runnable accounting, report schema determinism. |
| Expected movement | Counts become more honest; numerical runnable count need not rise. `0393` appears as blocked with stable gap codes. |
| Safety gates | A stage is derived, never user asserted; `verified`/`migrated` cannot be constructed without their evidence; no answer labels enter assessment. |
| Agent | Codex/Opus; cheaper agent may verify report diffs mechanically after design is frozen. |

### PR 3 — reviewed construction catalog foundation

| Field | Plan |
|---|---|
| Title | `feat(packs): compile reviewed math construction catalog` |
| Branch | `codex/math-construction-catalog` |
| Purpose | Give construction signatures, roles, hazards, and negative licenses a checksummed source of truth in reviewed pack bytes. Seed proportional decrease and a minimal cross-family set. |
| Likely files | `language_packs/compile_frames.py`, a typed frame/construction loader, `language_packs/schema.py` or manifest validation, `language_packs/data/en_core_math_v1/frames/*.jsonl`, compiled `frames.jsonl`, manifest checksum, pack/compiler tests. |
| Non-goals | No runtime proposal retrieval, no organ logic in data, no broad grammar, no dynamic regex/code, no serving. |
| Tests | Canonical bytes, checksum-from-written-bytes, schema rejection, deterministic ordering, unknown field/version failure, source/compiled parity. |
| Expected movement | No serving or runnable change. Empty math-frame checksum becomes a reviewed non-empty artifact. |
| Safety gates | Data-only closed schema; pack mutation reviewed; no executable fields; provenance/evidence hashes mandatory. |
| Agent | XHIGH defines the schema; Codex/Opus implements. Grok may perform only exact manifest/fixture updates after schema approval. |

### PR 4 — exact semantic-neighborhood proposal seam

| Field | Plan |
|---|---|
| Title | `feat(kernel): propose constructions through exact substrate neighborhoods` |
| Branch | `codex/exact-construction-proposals` |
| Purpose | Map chunk probes to catalog construction candidates using mounted pack manifold points and exact CGA inner-product scans over a reviewed candidate set. |
| Likely files | new narrow `generate/construction_proposals.py`, catalog loader, `vocab/manifold.py` only if an exact top-k evidence API is unavoidable, `problem_frame_builder.py` integration for diagnostic candidates, tests. |
| Non-goals | No readiness authority, operator selection, approximate retrieval, learned threshold, mutable cache, or serving. |
| Tests | Exact replay/order/tie behavior, lexical-neighborhood invariance, unrelated-neighbor rejection, proposal-with-missing-roles never runnable, backend parity if manifold API changes. |
| Expected movement | Candidate recall may rise; runnable must not rise solely from proximity. |
| Safety gates | Exact O(N) CGA scan; bounded reviewed candidate indices; scores retained as proposal evidence only; existing field closure unchanged. |
| Agent | XHIGH architecture plus Codex/Opus implementation and review. Do not assign geometric threshold semantics to a cheap agent. |

### PR 5 — acquisition, transfer, and loss state-change bindings

| Field | Plan |
|---|---|
| Title | `feat(kernel): bind possession-change constructions` |
| Branch | `codex/problemframe-possession-change-bindings` |
| Purpose | Close reusable event/state roles for acquisition, transfer, and consumption/loss without solving. Replace the fixed transfer regex for migrated diagnostic signatures. |
| Likely files | construction catalog records, binder module, `problem_frame_builder.py`, `kernel_facts.py`/`problem_frame.py` only for reusable typed state/event roles, hazards, tests. |
| Non-goals | No generic event parser, no money solver, no serving migration, no raw-text organ fallback. |
| Tests | Morphology invariance, actor/recipient reversal, money-vs-object target, negation, entity continuity, competing interpretations, deterministic spans. |
| Expected movement | More `PARTIAL` and `CLOSED` possession constructions; runnable may remain unchanged until named contracts exist. |
| Safety gates | Competing candidates preserved; event direction explicit; no candidate implies addition/subtraction by itself. |
| Agent | Codex/Opus with XHIGH review of role topology. Grok may add pre-specified fixture variants only. |

### PR 6 — dimensional, temporal, comparison, and part-whole closure

| Field | Plan |
|---|---|
| Title | `feat(kernel): close dimensional and relational construction topologies` |
| Branch | `codex/problemframe-relational-topology` |
| Purpose | Bind rate axes, unit/currency dimensions, comparison direction, temporal scope, container/part-whole coverage, and forward/inverse state targets. Split if review size exceeds one coherent topology. |
| Likely files | catalog records, binder and target modules, unit/hazard facades where coverage is genuinely lexical, `problem_frame*`, diagnostics, tests. |
| Non-goals | No universal IR, inferred conversions, calendar guessing, serving, or generic parser. |
| Tests | Axis swaps, incompatible dimensions, target-direction pairs, subgroup distinctness/coverage, remainder inverse/forward pairs, event order. |
| Expected movement | Blocker taxonomy becomes more specific; legitimate closed contracts rise only per family; false-runnable count remains zero. |
| Safety gates | Exact units/conversions only; topology-specific contracts; no structure is shared by expanding `EpistemicGraph` or `PropositionGraph`. |
| Agent | XHIGH should split/ratify topology; Codex/Opus implements bounded slices. Mechanical agents only after exact contracts are written. |

### PR 7 — ProblemFrame-only fraction-decrease adapter and shadow parity

| Field | Plan |
|---|---|
| Title | `feat(math): derive fraction decrease from a closed ProblemFrame contract` |
| Branch | `codex/fraction-decrease-problemframe-shadow` |
| Purpose | Add the first immutable typed projection and a ProblemFrame-fed derivation entry point; run it in diagnostics/shadow evidence only. |
| Likely files | new contract-specific adapter/input type, `generate/derivation/fraction_decrease.py` refactored so arithmetic consumes typed input, shadow/parity harness, tests; no serving branch yet. |
| Non-goals | No fallback from typed input to raw text; no serving selection; no parser deletion until parity passes. |
| Tests | Typed input construction, exact arithmetic, verifier parity, positive morphology, confusers, legacy-vs-frame shadow comparison, deterministic proof evidence. |
| Expected movement | One `ProblemFrame-only verified contract`; serving metrics unchanged. |
| Safety gates | The typed entry point accepts no problem text; adapter accepts only runnable assessment; discrepancies refuse and block migration. |
| Agent | Codex/Opus high reasoning; XHIGH reviews the adapter boundary and parity evidence. |

### PR 8 — migrate fraction decrease and retire its parser

| Field | Plan |
|---|---|
| Title | `refactor(math): serve fraction decrease from ProblemFrame and retire raw parser` |
| Branch | `codex/fraction-decrease-parser-retirement` |
| Purpose | Wire the verified typed path into existing admission, remove raw-prose parsing from the organ, and shrink the legacy allowlist. |
| Likely files | `generate/math_candidate_graph.py`, `generate/derivation/fraction_decrease.py`, typed adapter, no-new-legacy allowlist/test, serving/confuser tests, runtime contract docs only if externally visible behavior changes. |
| Non-goals | No second organ migration, score-chasing broadening, fallback parser, or report mutation. |
| Tests | Full shadow parity, serving train/holdout/confusers, verifier evidence, no-new-legacy shrink, architectural invariants, smoke/full relevant lanes. |
| Expected movement | Serving should remain at least `30/20/0` train and `5/495/0` holdout with `wrong_ids=[]`; capability lift is optional. Parser-retirement count improves by one. |
| Safety gates | Any legacy/frame disagreement refuses; raw parser and allowlist entry removed in the same PR; no hidden fallback. |
| Agent | Codex/Opus implements; XHIGH performs mandatory merge-blocker review. Grok should not own the migration. |

### PR 9 — readiness/replay inspection projection

| Field | Plan |
|---|---|
| Title | `feat(workbench): expose substrate construction evidence` |
| Branch | `codex/workbench-construction-evidence` |
| Purpose | Project already-persisted or explicitly journaled construction candidates, bindings, blockers, and readiness stages into Workbench without claiming live capability. |
| Likely files | curated runtime/workbench schemas and readers, API projection, UI trace components, tests; exact files chosen only after persistence review. |
| Non-goals | No UI-driven mutation, replay in browser, raw field arrays, synthetic green stages, or capability claims. |
| Tests | Missing-evidence honesty, deterministic projection, no raw field persistence, accessibility/UI tests, replay divergence. |
| Expected movement | Operator inspectability only; no serving/readiness movement. |
| Safety gates | UI labels diagnostic vs migrated explicitly; absent evidence stays absent; work waits until the core evidence schema is stable. |
| Agent | Codex/Opus for schema; cheaper agent may implement frozen UI mechanics. XHIGH reviews claims and persistence boundaries. |

## 6. Proportional-decrease implementation plan

PR 1 remains the correct next implementation PR. The repository evidence does not
justify migrating `percent_partition`, broadening process triggers, or touching
serving first.

### 6.1 Bind `decrease_to_fraction`

Add a diagnostic proportional-change construction that consumes existing scalar,
unit, mention, and span facts at the `ProblemFrame` construction boundary.

For `0005`, emit one bound relation:

```text
relation_type = decrease_to_fraction
roles:
  base_quantity -> grounded scalar 84
  scale -> grounded scalar 3/4
  state_entity -> exact “temperature” mention
  unit -> exact “degrees” mention/fact
  transition -> exact “decrease to” span
```

The relation must preserve the original double-space source text and exact character
spans. `scale` and `base_quantity` bind by fact identity, not by numeric position.
The relation may be proposed only when the construction distinguishes `decrease to`
from `decrease by` and from affine `fraction more than` surfaces.

This PR is an obligation-closing diagnostic bridge, not the final semantic-neighborhood
implementation. Any temporary signature declaration must live at the construction
boundary, be explicitly marked for catalog migration in PR 3, and must not be called
geometric substrate retrieval.

### 6.2 Represent delta question targets

Extend target semantics so the bound target carries at least:

```text
target_operator = difference
target_state = delta
target_direction = decrease
target_entity = same state entity as the relation
unknown_slot = delta_quantity
```

Do not encode this as a free-form `unknown` string alone. Illegal combinations such as
`target_state=final` with `target_operator=difference` should be rejected by typed
construction or explicit validation. Preserve the exact question span
`what will the temperature decrease by?`.

### 6.3 Make `fraction_decrease` runnable for train `0005`

Add `assess_fraction_decrease(frame)` and emit it only when a
`decrease_to_fraction` relation exists. Its positive obligations are:

1. exactly one base quantity and one scale are bound by fact identity;
2. `0 < scale < 1` for this organ;
3. state entity continuity is proven between transition and target;
4. unit/dimension continuity is proven when a unit is present;
5. target explicitly requests the decrease delta, not the final state;
6. all relation and target spans are provenance-bearing;
7. no blocking hazard or competing construction remains.

`runnable=True` means only that a future typed adapter could construct every input the
existing organ requires. It must not calculate 21, call the organ, or affect serving.

### 6.4 Keep confusers blocked

Required negative fixtures:

- `decrease to 3/4 ... what is the final temperature?` — closed proportional
  construction, not runnable for the delta organ;
- `3/4 more than 84` — affine comparison, not proportional decrease;
- `decrease by 3/4 of 84` — distinct transition semantics, not silently treated as
  `decrease to`;
- multiple fraction scales or multiple candidate bases — ambiguous/refuse;
- forecast duration (`one hour`) — never chosen as the base;
- entity discontinuity (`temperature ... decrease in pressure`) — block;
- incompatible units across state/target — block;
- negated or hypothetical decrease — block unless explicitly supported later.

### 6.5 Remove false percent-partition runnable holdout `0393`

Tighten `assess_percent_partition` to require the organ's actual forward topology:

1. a numeric original whole bound to the whole entity before partition events;
2. explicit subgroup identities, distinctness, and required coverage;
3. each scale linked to the correct subgroup by mention/fact identity rather than
   lowercase surface equality;
4. a forward aggregation target over subgroup results;
5. no final-state/remainder quantity used as the original whole;
6. no inverse-reconstruction target.

For `0393`, the grounded `28 chocolates left` is a final state and the question asks
for the original state. The current forward `percent_partition` organ does not license
that inverse topology. The assessment must therefore be blocked with stable reasons
such as `inverse_topology_unlicensed` and `original_whole_unbound`; it must not infer
80 or route to another organ.

Train `0046` remains runnable only if the frame proves the numeric whole `100 students`,
the girls/boys half partition, distinct subgroup bindings, both percentages linked to
their respective subgroup, and the forward aggregate target `students own dogs`.

### 6.6 Files and tests

Expected production edits are limited to the diagnostic substrate path:

- `generate/kernel_facts.py`
- `generate/problem_frame.py`
- `generate/problem_frame_builder.py`
- `generate/problem_frame_contracts.py`
- `generate/process_frames.py` only if a proportional-change candidate declaration is
  required
- `scripts/gsm8k_problem_frame_adequacy.py`
- `scripts/gsm8k_substrate_morphology.py`

Focused tests:

- `tests/test_problem_frame_skeleton.py`
- `tests/test_problem_frame_builder.py`
- `tests/test_problem_frame_contracts.py`
- `tests/test_gsm8k_problem_frame_adequacy.py`
- `tests/test_gsm8k_morphology_missing_kernel_labels.py`
- a new narrow proportional-change/confuser test file if keeping the existing files
  readable
- `tests/test_kernel_no_new_legacy_derivation_surfaces.py`

Forbidden edits in PR 1:

- `generate/derivation/*`
- `generate/math_candidate_graph.py`
- `evals/**/report.json`
- any `cases.jsonl` or sealed `.age` file
- language-pack compiled bytes/manifests

## 7. Readiness metric evolution

Readiness must express authority and evidence, not merely coverage.

| Stage | Meaning | Required evidence | Allowed effect |
|---|---|---|---|
| Candidate contract | A construction family and organ may be relevant | Proposal evidence and at least one supported role | Diagnostic count only |
| Blocked contract | Candidate exists but roles, target, topology, dimension, or hazards do not close | Stable blocker codes and evidence spans | Refusal/diagnostic only |
| Runnable diagnostic contract | Every organ input can be projected from `ProblemFrame` alone | Closed obligations, no blocking hazard, deterministic typed projection schema | Diagnostic count only; no organ call |
| ProblemFrame-only verified contract | Typed input was derived without raw prose and the organ/verifier accepted it | Derivation proof, independent verifier, morphology/confuser evidence, replay digest | Shadow evidence only |
| Migrated serving contract | Existing admission consumes the typed path | Serving parity, wrong-zero gates, explicit ratification | May answer through existing surface policy |
| Retired legacy parser | No raw-text fallback/call site remains for the migrated organ | Parser deletion, call-site deletion, no-new-legacy allowlist shrink | Architectural debt reduced |

Headline metrics should include:

- candidate count and candidate precision;
- blocked count by stable gap code;
- binding closure rate by construction;
- diagnostic runnable count and per-case obligation proof;
- false-runnable count, which must be zero before promotion;
- ProblemFrame-only verified count;
- migrated serving contract count;
- retired parser/allowlist count;
- serving `correct/refused/wrong` and exact `wrong_ids`.

Progress is not monotonic in runnable count. PR 1's expected train movement `1 -> 2`
and holdout movement `1 -> 0` are both improvements: one closes a legitimate contract,
the other removes a lie. Candidate recall without stable precision is not progress.

## 8. Parser retirement strategy

1. **Inventory.** Keep a mechanically checked list of raw-text organs, parsing
   helpers, raw-prose call sites, and allowlisted legacy files. Classify shared lexical
   extraction separately from sentence-structure parsing.
2. **Shadow diagnostics.** Build `ProblemFrame` and assessments beside serving without
   changing answers. Record candidate, blockers, and false-runnable cases.
3. **Parity checks.** For one organ, compare the typed `ProblemFrame` projection with
   the legacy organ's accepted/rejected domain across positives, morphology variants,
   and near confusers. Disagreement blocks migration and must default to refusal.
4. **ProblemFrame-only readiness.** Add a typed organ entry point that accepts no raw
   text. Prove the derivation and verifier from that input. No fallback is allowed.
5. **Migration.** Wire the typed path through the existing admission boundary only
   after architect ratification and serving evidence.
6. **Legacy fallback removal.** Remove raw-text parsing and any compatibility call in
   the same migration PR. Do not retain it “temporarily” behind the typed consumer.
7. **Final deletion.** Shrink the no-new-legacy allowlist and delete dead helpers only
   after call-site scans and the full relevant lanes prove equivalence or stricter
   refusal.

The unit of retirement is one organ. A broad rewrite that deletes several parsers
before independently proving each contract is not reviewable.

## 9. Governance and ADR implications

### 9.1 ADR-0223

ADR-0223 supplies the binding doctrine for this program: words/chunks probe; semantic
closeness proposes; bindings ground; contracts determine. Future substrate PRs must
show which audit gap codes they close and must not claim substrate use merely because
they execute inside `problem_frame_builder.py`.

There is status drift: ADR-0223 still says **Proposed for architect ratification**
while its required audit is merged in #833 and this plan depends on its conclusions.
Before PR 1 merges, the architect should ratify ADR-0223 and update its status to
Accepted, recording that the audit requirement was fulfilled by #833. This can be a
docs-only amendment in the plan review; it must not be silently inferred from merge
history.

### 9.2 ADR-0144 graph separation

- `ProblemFrame` owns problem comprehension state.
- Math-specific derivation state remains in math structures/organs.
- `EpistemicGraph` may carry recognition/provenance evidence through a typed adapter,
  but never solver operands or target arithmetic.
- `PropositionGraph` receives claims for articulation after derivation; it does not
  become the construction or solver graph.

### 9.3 ADR-0207 anti-universal-IR posture

The construction catalog is not a universal parser, and `ProblemFrame` is not a
universal cognition graph. Every consumer receives a narrow immutable projection.
Shared concepts are represented by typed facts and adapters, not by adding all fields
to one object.

ADR-0207 also freezes bespoke regex positive serving capability. The temporary
diagnostic construction in PR 1 cannot become a new positive serving branch. Positive
serving capability ultimately flows through the verified typed path.

### 9.4 ADR-0218 promotion discipline

A verified derivation does not promote catalog data or memory. Durable construction,
pack, or epistemic changes remain reviewed. Runtime observations may produce replayable
proposals, but they cannot rewrite the catalog, activate new signatures, or promote
standing. Existing Vault mutation ownership and INV-29 remain unchanged.

### 9.5 ADR-0222 / FrameVerdict contamination

`ContractAssessment` is a readiness decision, not an epistemic verdict. A blocked
contract means “this organ is not licensed from these facts,” not “the proposition is
false.” Do not import, construct, emulate, or rename `FrameVerdict` here. Do not add an
`answer=False` path or use absence of a binding as proof of negation.

## 10. Agent allocation strategy

| Work | Primary agent | Review | Constraint |
|---|---|---|---|
| Architecture, catalog schema, graph boundaries, promotion criteria | XHIGH | Architect | Owns doctrine and merge-blocker analysis; no bulk implementation. |
| Bounded builder/contract/adapter implementation | Codex or Opus | XHIGH for semantic boundaries | Must implement the written obligations, not reinterpret them. |
| Mechanical fixtures, manifest/checksum updates, allowlist edits | Grok only when instructions and expected bytes are exact | Codex/Opus | No authority to widen signatures, relax blockers, or change topology. |
| Preflight, inventory, docs-only consistency, branch/diff verification | Gemini/Flash or equivalent cheaper agent | Implementer | May report evidence; may not approve capability or doctrine. |
| Serving migration | Codex/Opus | Mandatory XHIGH + architect review | Requires ProblemFrame-only verification and wrong-zero evidence first. |

Every implementation handoff must state exact files, positive obligations, negative
fixtures, non-goals, and expected metrics. No agent may substitute score movement for
contract evidence or reinterpret “semantic neighborhood” as permission to select an
operator.

## 11. Validation matrix

Run the smallest lanes first. Use the repository CLI when available; the module
entrypoint is an equivalent fallback when `core` is not on `PATH`.

### 11.1 Focused ProblemFrame and contract tests

```bash
uv run python -m pytest -q \
  tests/test_problem_frame_skeleton.py \
  tests/test_problem_frame_builder.py \
  tests/test_problem_frame_contracts.py \
  tests/test_gsm8k_problem_frame_adequacy.py \
  tests/test_gsm8k_morphology_missing_kernel_labels.py \
  tests/test_process_frames.py \
  tests/test_language_packs_scalar_equivalence.py \
  tests/test_language_packs_unit_dimensions.py \
  tests/test_ambiguity_hazards.py
```

Acceptance: all pass; repeated frame/assessment construction is byte/structure equal;
`0005` has a runnable `fraction_decrease`; `0046` has a runnable
`percent_partition`; `0393` has no runnable contract and exposes stable blockers.

### 11.2 Adequacy diagnostics

```bash
uv run python scripts/gsm8k_problem_frame_adequacy.py \
  --cases evals/gsm8k_math/train_sample/v1/cases.jsonl

uv run python scripts/gsm8k_problem_frame_adequacy.py \
  --cases evals/gsm8k_math/holdout_dev/v1/cases.jsonl
```

Acceptance after PR 1:

```text
train contract_runnable_count = 2, exactly 0005 and 0046
holdout contract_runnable_count = 0
false_runnable_count = 0
```

Do not write these outputs into committed report artifacts.

### 11.3 Serving reports in memory

```bash
uv run python - <<'PY'
from evals.gsm8k_math.train_sample.v1.runner import _CASES_PATH, _load_cases, build_report
r = build_report(_load_cases(_CASES_PATH))
wrong = [row["case_id"] for row in r["per_case"] if row["verdict"] == "wrong"]
print(r["counts"], wrong)
PY

uv run python - <<'PY'
from evals.gsm8k_math.holdout_dev.v1.runner import build_report
r = build_report()
wrong = [row["case_id"] for row in r["per_case"] if row["verdict"] == "wrong"]
print(r["counts"], wrong)
PY
```

Acceptance for PR 1: train `30 correct / 20 refused / 0 wrong`; holdout
`5 correct / 495 refused / 0 wrong`; both wrong-ID lists empty. PR 1 must not alter
serving output at all.

### 11.4 Legacy and architectural invariants

```bash
uv run python -m pytest -q \
  tests/test_kernel_no_new_legacy_derivation_surfaces.py \
  tests/test_architectural_invariants.py \
  tests/test_epistemic_invariants.py

core test --suite smoke -q
# fallback when core is not on PATH:
uv run python -m core.cli test --suite smoke -q
```

Acceptance: all pass; no new derivation raw-parser surface; INV-21/24/29/30 remain
unchanged; no field/runtime path was modified in diagnostic PRs.

### 11.5 Diff and artifact gates

```bash
git diff --check
git status --short
git diff --name-only origin/main...HEAD
test -z "$(git diff --name-only origin/main...HEAD | \
  rg '(^|/)(report\.json|cases\.jsonl|[^/]+\.age)$')"
```

Acceptance for PR 1:

- no `generate/derivation/` diff;
- no `generate/math_candidate_graph.py` diff;
- no report, case, or sealed diff;
- no pack/manifest diff;
- no case-ID logic;
- only intended source/tests/docs changed.

Before a serving migration, additionally run the relevant CLI runtime/algebra/full
lanes and `core eval cognition`; the exact migration PR must record why each lane is
proportionate to its risk.

## 12. Workbench/UI implications

Workbench should eventually make the middle layer inspectable:

```text
original chunk and source span
  -> exact semantic neighbors and scores
  -> candidate construction IDs
  -> required/optional roles
  -> grounded role targets and provenance
  -> competing bindings/hazards
  -> ContractAssessment blockers and stage
  -> typed projection / derivation / verification evidence, when present
```

The UI must label `candidate`, `blocked`, `diagnostic runnable`, `verified shadow`,
and `migrated serving` distinctly. It must never render a candidate as a live
capability, synthesize missing stages, replay raw runtime state in the browser, or
persist field arrays merely for visualization.

This is PR 9, not immediate work. The evidence schema must stabilize first; otherwise
the UI will freeze diagnostic accidents into a public contract.

## 13. Risks and failure modes

| Risk | Failure signature | Required correction |
|---|---|---|
| Local parser relabeled as substrate | A new regex/trigger is added and described as affordance retrieval | Classify it honestly as bounded scaffold; move authority to reviewed catalog plus exact proposal seam. |
| False runnable inflation | Runnable count rises while topology/target obligations remain implicit | Audit every runnable case; add explicit obligations and confusers; count removal as progress. |
| Raw-text fallback behind a `ProblemFrame` consumer | Typed adapter fails and consumer reparses `problem_text` | Prohibit text on typed entry point; failure returns refusal; scan call sites. |
| Universal-IR drift | Solver, recognition, and articulation fields accumulate on one graph | Keep purpose-specific structures and narrow projections per ADR-0144/0207. |
| Score chasing | A GSM8K case or phrase causes a special branch | Ban case IDs/labels; require heterogeneous morphology and near-confuser evidence; preserve wrong-zero. |
| Premature serving migration | Diagnostic runnable is wired before typed derivation/verifier parity | Require ProblemFrame-only verified stage and architect ratification first. |
| Benchmark overfitting | Only `0005`/`0046` exact prose passes | Test same geometry across reviewed lexical variants and different entities/units; hold target/topology confusers. |
| Hidden normalization | New binder repairs field/versor state or coerces units silently | Keep normalization at approved boundaries; bind facts without modifying geometric state. |
| Semantic closeness mistaken for proof | High CGA score directly chooses organ/operator | Proposal record only; contract cannot read score as an obligation; exact bindings and hazards decide. |
| Catalog becomes executable grammar | Pack records contain regex/code/answer expressions | Closed data schema; no dynamic import or arbitrary regex; schema rejects unknown executable fields. |
| Mutable/stochastic proposal | Learned threshold/cache changes candidate order across runs | Exact scan, immutable reviewed subset, deterministic tie order, replay tests. |
| Target semantics collapse | “How many” grounds an entity but not state/operator/direction | Typed target axes and illegal-combination checks. |
| Readiness conflates truth | Blocked contract is interpreted as false proposition | Keep `ContractAssessment` separate from `Determined` and proposed `FrameVerdict`. |
| Duplicate semantic authority | Python process frames and pack catalog drift | Establish pack bytes as authority, parity-test compatibility views, then retire duplicate declarations. |
| Parser accumulation | Typed path lands but old parser remains as fallback | Migration PR must delete parser and shrink allowlist in the same change. |

## 14. Final recommendation

### Exact next PR

```text
branch: codex/problemframe-proportional-change-closure
title:  feat(kernel): close proportional-decrease contracts and make readiness obligation-sound
```

Keep it diagnostic-only. It must bind `decrease_to_fraction`, type the delta target,
make train `0005` runnable, retain train `0046` under stronger obligations, and block
holdout `0393`. It must not edit derivation organs, `math_candidate_graph.py`, pack
bytes, serving, reports, cases, or sealed artifacts.

### Exact next agent

Use Codex or Opus for the bounded implementation, with high reasoning and a mandatory
XHIGH merge-blocker review. The implementation is narrow enough for a code-focused
agent, but target/topology semantics are too consequential for an unguided mechanical
agent.

### Exact handoff prompt

```text
Implement PR: feat(kernel): close proportional-decrease contracts and make readiness
obligation-sound on branch codex/problemframe-proportional-change-closure.

Read GPT55.md/your agent supplement, AGENTS.md, docs/runtime_contracts.md,
docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md,
the ADR-0223 audit pack, and HANDOFF-gpt55-2026-06-20.md. Complete the repository
bootstrap and pre-edit sweep before editing.

Scope:
1. In the diagnostic ProblemFrame path, bind a provenance-bearing
   decrease_to_fraction relation for train case 0005 with roles for base quantity 84,
   scale 3/4, state entity temperature, unit degrees, and the exact transition span.
2. Represent the question as an explicit decrease-delta target: operator=difference,
   state=delta, direction=decrease, same target entity, exact source span.
3. Add an obligation-complete assess_fraction_decrease(frame) that is runnable only
   when base, scale, entity/unit continuity, delta target, provenance, and hazards close.
4. Tighten assess_percent_partition(frame): require a pre-partition numeric whole,
   distinct/covered subgroups, identity-linked scales, and a forward aggregate target.
   Keep train 0046 runnable. Make holdout 0393 non-runnable with stable blockers for
   missing original whole / inverse topology; do not solve or reroute it.
5. Add positive, final-value, affine, decrease-by, multiple-scale/base, forecast-time,
   entity/unit mismatch, inverse-target, subgroup, and deterministic replay tests.
6. Update adequacy/morphology diagnostics only as required for stable blocker evidence.

Hard stops:
- Do not edit generate/derivation/* or generate/math_candidate_graph.py.
- Do not change serving, reports, cases, sealed artifacts, pack bytes/manifests, or
  answer labels.
- Do not add raw-text fallback, case-ID behavior, generic parsing, hidden normalization,
  approximate retrieval, or a second semantic authority.
- Do not call local signature matching “semantic substrate retrieval”; exact CGA
  proposal is a later PR.

Required evidence:
- focused ProblemFrame/contracts/process/scalar/unit/hazard tests green;
- no-new-legacy and architectural invariants green;
- adequacy: train runnable 1->2 (0005, 0046), holdout 1->0;
- serving in memory unchanged: train 30/20/0, holdout 5/495/0, wrong_ids=[];
- git diff --check; no derivation/candidate-graph/report/case/sealed/pack diff.

Before coding, state the exact files and explain why the relation and target types make
false readiness unrepresentable. At handoff, list every obligation and confuser proven.
```

### What not to do next

Do not migrate `percent_partition`, wire `ProblemFrame` into serving, build a generic
parser, add embeddings/ANN/cosine retrieval, broaden trigger lists for score, or start
Workbench UI. First make diagnostic readiness truthful. Then establish the reviewed
construction catalog and exact proposal seam. Serving comes only after one
ProblemFrame-only contract is independently verified.