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:

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

with a constructional, substrate-mediated relationship:

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:

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

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

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:

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:

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:

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

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

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:

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

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

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

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:

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

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

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.