diff --git a/HANDOFF-gpt55-2026-06-20.md b/HANDOFF-gpt55-2026-06-20.md index 279eda07..4763c6d5 100644 --- a/HANDOFF-gpt55-2026-06-20.md +++ b/HANDOFF-gpt55-2026-06-20.md @@ -1,136 +1,136 @@ # HANDOFF — GPT-5.5 — 2026-06-20 -## Session objective +## Agent and session -Produce the ADR-0223 semantic-substrate affordance audit without changing serving, derivation, benchmark, sealed, or runtime behavior. +- **Agent:** GPT-5.5 / Codex +- **Reasoning effort:** high architecture review +- **Session entry point:** produce the master implementation plan for moving math + comprehension from local raw-text organs to substrate-mediated constructional + cognition; do not implement runtime code. +- **Baseline:** `origin/main@60df4fc0`, merged audit PR #833. +- **Branch:** `codex/semantic-substrate-problem-solving-plan` -## Baseline +## Bootstrap and smoke -- Repository: `/Users/kaizenpro/.codex/worktrees/1737/core` -- Git state at start: clean, detached HEAD -- Commit: `564e360e docs(adr): require semantic substrate affordance audit` -- Required bootstrap read: `GPT55.md`, `AGENTS.md`, `docs/runtime_contracts.md`, recent `HANDOFF-gpt55-2026-06-18.md`, ADR-0223 and governing ADRs, substrate briefs/audits, relevant source and tests. +Read before editing: -## Map +- `GPT55.md` +- `AGENTS.md` +- `docs/runtime_contracts.md` +- the ADR-0223 audit/session pack and previous handoff +- current `ProblemFrame`, contracts, derivation boundaries, pack/compiler, + graph-carrier boundaries, governing ADRs, diagnostics, and focused tests -Four directions were evaluated: - -1. continue organ-local parsers — rejected as forward architecture; -2. universal parser/mega-IR — rejected because it collapses graph invariants; -3. pack-backed constructional affordances with exact proposal and deterministic proof — selected; -4. learned/stochastic parsing — deferred because it undermines replay and inspectability at the current stage. - -The intrinsic space is a typed relational field over source spans, entities, quantities, events, target operators, hazards, and contract obligations. Semantic proximity can propose a construction but cannot prove it. - -## Build - -Documentation-only artifacts added: - -- `docs/analysis/semantic-substrate-affordance-audit-2026-06-20.md` -- `docs/analysis/semantic-substrate-affordance-map-2026-06-20.md` -- `docs/analysis/problemframe-contract-gap-taxonomy-2026-06-20.md` -- this handoff - -No Python, runtime, pack, benchmark, report, case, sealed artifact, manifest, or test file was changed. - -## Principal findings - -- CORE's geometric substrate is real in pack manifold compilation, exact CGA recall, vault recall, and versor propagation. -- The math `ProblemFrame` path does not consume that geometry. It uses hard-coded process triggers and local regex binding. -- `en_core_math_v1/frames.jsonl` is empty; its frame checksum is the SHA-256 of empty bytes. Process construction semantics live in `generate/process_frames.py`, separately from the pack lexicon. -- `ProblemFrame` is diagnostic only. Serving calls raw-text `resolve_promotable_*` organs through `parse_and_solve`. -- The no-new-legacy test contains parser expansion but does not retire the existing allowlist. -- Current percent-partition contract readiness is obligation-incomplete. -- Train case `0046` is the intended forward percent-partition slice. -- Holdout case `0393` is a false diagnostic runnable: a final remainder is selected as the whole and an inverse reconstruction is accepted by a forward contract. -- Train case `0005` has sufficient scalar/unit substrate to motivate proportional decrease, but no construction, state-transition relation, target direction, or contract. -- Graph boundaries are currently healthy: `ProblemFrame`, `EpistemicGraph`, `MathProblemGraph`, and `PropositionGraph` remain purpose-specific. - -## Diagnostic evidence - -Serving reports, run in memory without writes: - -| Split | Correct | Refused | Wrong | Wrong IDs | -|---|---:|---:|---:|---| -| Train sample | 30 | 20 | 0 | `[]` | -| Holdout | 5 | 495 | 0 | `[]` | - -ProblemFrame adequacy: - -| Split | Contract candidates | Runnable | -|---|---:|---:| -| Train sample | 42 | 1 | -| Holdout | 423 | 1 (false runnable `0393`) | - -## Validation - -- `core test --suite smoke -q` — unavailable because `core` was not on `PATH`. -- Fallback: `uv run python -m core.cli test --suite smoke -q` — `108 passed in 136.89s`. -- Focused substrate/contract suite — `69 passed in 1.00s`: - - ProblemFrame builder and contracts - - adequacy and morphology labels - - no-new-legacy guard - - process frames - - scalar equivalence and unit dimensions - - ambiguity hazards - - epistemic carrier - -No versor code or runtime field path changed, so the hard field invariant was not mechanically perturbed. - -## Justification - -The recommended architecture separates candidate resonance from constructive proof: +Direct CLI result: ```text -exact semantic neighborhood - -> construction proposal - -> deterministic span/role binding - -> obligations and corrective hazards - -> ProblemFrame - -> organ-specific closed contract +core test --suite smoke -q +zsh: command not found: core ``` -This preserves duality: proposal is paired with correction, and positive evidence is paired with hazards/confusers. It also makes illegal readiness states structurally distinguishable: a candidate is not a binding, and a partial binding is not runnable. +Repository-supported fallback: -## Recommended next PR +```text +uv run python -m core.cli test --suite smoke -q +108 passed, 1 warning in 129.78s +``` -Branch: `codex/problemframe-proportional-change-closure` +The warning reports a stale `engine_state` revision. This docs-only task did not clear +or mutate engine state. -Title: `feat(kernel): close proportional-decrease contracts and make readiness obligation-sound` +## Modules touched -Scope: +| File | Change | Summary | +|---|---|---| +| `docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md` | added | 14-section master architecture, catalog, PR sequence, immediate PR specification, metrics, retirement, governance, validation, risk, and exact handoff prompt | +| `HANDOFF-gpt55-2026-06-20.md` | updated | this bounded implementation handoff, superseding the audit-session handoff now captured by the merged audit artifacts | -- close proportional-decrease roles for train `0005` from existing substrate facts; -- represent base/final state, fractional scale, entity/unit continuity, and delta target with exact provenance; -- add an obligation-complete contract; -- tighten percent-partition readiness so holdout `0393` is not runnable; -- retain train `0046` with explicit topology and target obligations; -- add positive/confuser/determinism tests; -- do not change serving. +No Python, runtime, pack, manifest, benchmark, report, case, sealed, test, or UI file +was modified. -Expected diagnostic movement to verify: +## Decisions -- train runnable `1 -> 2` (`0005`, `0046`); -- holdout runnable `1 -> 0`; -- serving `wrong_ids == []` remains unchanged. +1. The transformation boundary is: -## Subsequent sequence + ```text + chunk -> exact substrate proposal -> construction candidate -> role obligations + -> exact bindings -> ProblemFrame -> ContractAssessment -> typed organ input + -> verified derivation -> existing admission/articulation + ``` -1. compile a reviewed, checksummed math construction catalog from pack data; -2. add exact CGA semantic-neighborhood proposal with evidence, never readiness authority; -3. bind acquisition/loss/transfer state changes constructionally; -4. close rate/comparison/container/partition topology; -5. migrate one organ to a typed closed contract and delete its local parser. +2. Semantic closeness proposes; exact bindings ground; contracts determine; + verification admits. CGA score never proves a relation or selects an operator. +3. The next implementation PR remains proportional-decrease/readiness closure. +4. Serving migration is deferred until a contract runs from `ProblemFrame` alone and + passes typed derivation, verifier, morphology, confuser, replay, and parity evidence. +5. Parser retirement is one organ at a time. Migration is incomplete until the raw + parser and no-new-legacy allowlist entry are deleted. +6. `ProblemFrame`, math state, `EpistemicGraph`, and `PropositionGraph` remain + purpose-specific. Typed adapters connect them; no universal graph is introduced. +7. ADR-0223 status is stale (`Proposed`) despite the merged audit. Architect + ratification/status reconciliation is required before the next implementation PR + merges. -## Hard stops for the next session +## Invariants reviewed -- Do not turn CGA similarity into semantic assertion or organ selection. -- Do not add raw-text parsing to a new derivation organ. -- Do not promote `ProblemFrame` until false runnable `0393` is removed and obligations are explicit. -- Do not use `EpistemicGraph` or `PropositionGraph` as a mathematical mega-IR. -- Do not mutate packs without reviewed bytes, regenerated checksums, and replay evidence. -- Do not accept coverage growth if serving wrong IDs cease to be empty. +| Invariant | Result | +|---|---| +| `versor_condition(F) < 1e-6` | Not mechanically perturbed; no field/algebra/runtime code changed. | +| Exact CGA only | Plan requires exact O(N) candidate scans and forbids ANN/HNSW/cosine substitution. | +| Normalization boundaries | No normalization proposed outside approved construction/algebra boundaries. | +| Wrong-zero serving | Every promotion gate retains `wrong_ids == []`; false-runnable removal counts as progress. | +| Reviewed mutation | Catalog/pack changes remain checksummed, reviewed, data-only; runtime learning is proposal-only. | +| INV-21/24/29/30 | No mutation or open-/closed-world determination path touched or widened. | +| Graph separation | ADR-0144 and ADR-0207 boundaries are explicit in the plan. | -## Workspace note +No subagents were used. -At handoff creation, only the four documentation files listed above were intended changes. Recheck `git status`, `git diff --check`, and the final diff before committing. +## Exact next PR + +```text +branch: codex/problemframe-proportional-change-closure +title: feat(kernel): close proportional-decrease contracts and make readiness obligation-sound +agent: Codex or Opus, high reasoning; mandatory XHIGH merge-blocker review +``` + +Required outcome: + +- bind `decrease_to_fraction` for train `0005` from exact facts/spans; +- represent a typed decrease-delta question target; +- make `fraction_decrease` diagnostically runnable for `0005`; +- retain `percent_partition` runnable for `0046` only under explicit topology; +- make holdout `0393` non-runnable for forward percent partition; +- keep serving unchanged and `wrong_ids=[]`. + +Forbidden scope: + +- `generate/derivation/*` +- `generate/math_candidate_graph.py` +- serving changes or raw-text fallback +- report, case, sealed, pack, or manifest changes +- case-ID behavior, generic parsing, hidden normalization, or approximate retrieval + +Expected diagnostics: + +```text +train runnable: 1 -> 2 (0005, 0046) +holdout runnable: 1 -> 0 +train serving: 30 correct / 20 refused / 0 wrong +holdout serving: 5 correct / 495 refused / 0 wrong +wrong_ids: [] +``` + +## Implementation entry prompt + +Use the full exact prompt in §14 of +`docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md`. +Before editing, the implementer must state the exact files and explain how the new +relation/target/contract types make false readiness unrepresentable. At handoff, list +every positive obligation, confuser, metric, and forbidden-diff check proven. + +## Do not forget + +The immediate PR closes diagnostic obligations; it does not complete semantic +substrate retrieval. Do not call bounded local construction matching “geometric” or +“substrate-mediated.” The reviewed construction catalog and exact CGA proposal seam +are later, separate PRs. diff --git a/docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md b/docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md new file mode 100644 index 00000000..ed55614d --- /dev/null +++ b/docs/analysis/semantic-substrate-problem-solving-master-plan-2026-06-20.md @@ -0,0 +1,981 @@ +# 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.