From cb94049679d8d98a90b20d8b7d31146adecf44ce Mon Sep 17 00:00:00 2001 From: Shay Date: Wed, 27 May 2026 09:48:51 -0700 Subject: [PATCH] docs(ADR-0168): scope FrameClaim ratification doctrine after compatibility audit (#364) * docs(ADR-0168): scope FrameClaim ratification doctrine * docs(ADR-0168): add prior ADR compatibility audit --- .../ADR-0168-frameclaim-ratification.md | 482 ++++++++++++++++++ 1 file changed, 482 insertions(+) create mode 100644 docs/decisions/ADR-0168-frameclaim-ratification.md diff --git a/docs/decisions/ADR-0168-frameclaim-ratification.md b/docs/decisions/ADR-0168-frameclaim-ratification.md new file mode 100644 index 00000000..44d7cf3f --- /dev/null +++ b/docs/decisions/ADR-0168-frameclaim-ratification.md @@ -0,0 +1,482 @@ +# ADR-0168 — FrameClaim Ratification Doctrine + +**Status:** Proposed (doctrine/scoping ADR; no runtime mutation in this PR) +**Date:** 2026-05-27 +**Author:** Shay +**Parent:** [ADR-0167](./ADR-0167-audit-as-teaching-evidence.md) +**Related:** ADR-0114a, ADR-0164, ADR-0165, ADR-0166, ADR-0056/0057, ADR-0167 FOLLOWUPS §1/§5 + +--- + +## Context + +ADR-0167 intentionally scoped the first math-teaching corridor implementation +to `LexicalClaim` only. + +That choice was structural, not opportunistic: + +- lexical ratification is local +- lexical ratification is additive +- lexical ratification does not alter graph-opening semantics +- lexical ratification cannot create new multi-step admissibility paths + unless graph completeness is already satisfied + +`FrameClaim` is different. + +A `FrameClaim` does not merely say: + +> "surface form X belongs to category Y" + +It says: + +> "surface form X opens (or does not open) a semantic frame of class K" + +That is an admissibility decision. + +Frame-openers determine: + +- whether decomposition occurs +- whether slot extraction occurs +- whether quantities compose +- whether references bind +- whether downstream graph construction is attempted at all + +A mistaken lexical entry can create noise. +A mistaken frame opener can create false reasoning structure. + +This is the first ADR-0167 sub-type where the system risks moving from: + +> refusal-first deterministic omission + +into: + +> incorrect graph admission + +which directly threatens the `wrong == 0` invariant. + +--- + +## Prior ADR compatibility audit + +This ADR is not final until it remains compatible with prior ADR doctrine. +The following audit was performed before opening implementation work. + +| Prior ADR | Load-bearing rule | ADR-0168 compatibility result | +|---|---|---| +| ADR-0056 | Contemplation is cognitive only; no corpus mutation; reviewed evidence boundaries matter | Compatible. ADR-0168 remains evidence/proposal-only and does not mutate during contemplation. | +| ADR-0057 | Replay-equivalence is a precondition, not permission; operator accept is required; proposal logs are append-only | Compatible with constraint. FrameClaim implementation must use a math-specific proposal/ratification adapter or subtype that preserves the same replay/review discipline without weakening ADR-0057's corpus-evidence eligibility gate. | +| ADR-0114a | Zero wrong, typed refusal, adversarial misparse=0, determinism, operation provenance | Compatible. ADR-0168 inherits these obligations and elevates case 0050 and recognized-but-uninjectable hazards as mandatory pins. | +| ADR-0164 | Incremental reader over semantic categories; no hidden best guess; new categories/rules require ADR | Compatible. FrameClaim ratifies reviewed category membership only; no dynamic category synthesis or runtime guessing. | +| ADR-0165 | Regex only at lexeme level; never grammar templates | Compatible. ADR-0168 introduces no regex and no sentence-template path. | +| ADR-0166 | Capability before measurement; no new eval lanes ahead of operators | Compatible. ADR-0168 is doctrine/capability scoping only and explicitly forbids new eval lanes in the implementation PR. | +| ADR-0167 | Audit rows become teaching evidence; LexicalClaim first; harder sub-types require their own ADR | Compatible. ADR-0168 is exactly the next sub-type ADR and keeps audit rows evidence-only. | + +### Resolved tension: ADR-0057 evidence floor + +ADR-0057's ordinary `TeachingChainProposal` eligibility requires at least +one `source="corpus"` evidence pointer. Math-domain FrameClaims originate +from audit/refusal artifacts, not from the cognition teaching corpus. + +ADR-0168 therefore does **not** weaken ADR-0057. + +A future implementation must choose one of two compatible paths: + +1. Define a math-specific proposal/ratification type whose evidence floor is + `MathReaderRefusalEvidence` plus replay-admissibility evidence, while + preserving ADR-0057's append-only/replay/operator-review discipline; or +2. Define a reviewed math corpus artifact that can supply the required + corpus-style evidence pointer without borrowing cognition corpus evidence. + +What is forbidden: + +- treating audit evidence as cognition corpus evidence +- bypassing the reviewed-evidence floor +- auto-accepting because replay passed +- mutating runtime frame behavior outside the proposal/review boundary + +This section is the compatibility trip-wire for any implementation PR. + +--- + +## Decision + +`FrameClaim` ratification is permitted only as a deterministic, +replay-equivalent, operator-reviewed proposal surface with explicit +hazard pins and category allowlists. + +This ADR does **not** approve runtime implementation. + +This ADR defines: + +- what a `FrameClaim` is +- what it is allowed to mutate +- what it is forbidden to mutate +- the replay obligations required before implementation +- the initial safe category surface +- the explicit non-goals + +Implementation is deferred until a follow-on PR proves the acceptance +gates below. + +--- + +## Definition of a FrameClaim + +A `FrameClaim` is a reviewed assertion that a surface form participates +in a specific frame-opening category. + +Canonical shape: + +```text +(surface_form, frame_category, polarity) +``` + +Examples: + +| Surface | Category | Meaning | +|---|---|---| +| `gave` | `transfer_frame` | opens giver/receiver/object slots | +| `spent` | `decrement_frame` | reduces quantity ownership | +| `earned` | `increment_frame` | increases quantity ownership | +| `left` | `remainder_frame` | produces residual quantity | + +The claim concerns: + +- frame admissibility +- slot topology +- decomposition eligibility + +It does NOT assert: + +- arithmetic truth +- entity identity +- quantity correctness +- reference resolution +- solver validity + +Those remain separate sub-types. + +--- + +## Why FrameClaim is dangerous + +Frame-openers sit upstream of nearly every later reasoning stage. + +A lexical error may fail to ground. +A frame error may create an entirely fabricated graph. + +The principal hazard is: + +```text +recognized-but-wrongly-opened graph construction +``` + +This is exactly the class of issue exposed by: + +- GSM8K train-sample case 0050 +- recognized-but-uninjectable skip-only fallback +- partial-graph greed + +The system must therefore prefer: + +```text +refusal > incomplete graph > speculative frame opening +``` + +at all times. + +--- + +## Initial safe category scope + +Initial implementation scope MUST be allowlist-only. + +No freeform frame invention. +No dynamic category synthesis. +No embedding-nearest-category fallback. + +Initial safe categories: + +| Category | Scope | +|---|---| +| `increment_frame` | additive ownership gain | +| `decrement_frame` | subtractive ownership loss | +| `transfer_frame` | giver/receiver transfer | +| `remainder_frame` | residual quantity after removal | + +Explicitly excluded initially: + +| Deferred category | Reason | +|---|---| +| comparison frames | ambiguity amplification | +| temporal frames | multi-anchor semantics | +| pronoun-dependent frames | requires ReferenceClaim | +| implicit-unit frames | requires SlotClaim | +| nested composition frames | requires CompositionClaim | +| metaphorical/idiomatic frames | non-deterministic semantics | + +--- + +## Mutation boundary + +A `FrameClaim` ratification MAY mutate only: + +- reviewed frame-category registries +- reviewed verb→frame mappings +- proposal-layer artifacts + +A `FrameClaim` ratification MUST NOT directly mutate: + +- solver logic +- parser traversal order +- decomposition recursion policy +- runtime graph execution +- arithmetic operators +- refusal logic +- graph verifier semantics + +The runtime consumes ratified frame data only through existing reviewed +pack-loading mechanisms. + +No direct hot-path mutation. + +--- + +## Replay obligations + +Before implementation, the following replay obligations must be proven. + +### 1. Deterministic claim signature + +Equivalent refusals MUST produce identical normalized claim signatures. + +Canonical identity must include: + +- surface form +- normalized frame category +- polarity +- audit-row digest +- refusal category + +Equivalent evidence MUST deduplicate. + +--- + +### 2. Replay equivalence + +Ratified `FrameClaim`s MUST replay identically across: + +- in-process runs +- cross-process runs +- reordered candidate queues +- repeated ingestion of the same audit evidence + +No queue-order dependence. + +--- + +### 3. wrong==0 preservation + +The implementation must prove: + +```text +new frame admission cannot silently convert a prior refusal +into an incorrect graph acceptance +``` + +This specifically requires hazard pins for: + +- case 0050 +- recognized-but-uninjectable fallback +- partial graph acceptance +- decomposition-without-slot-completeness + +--- + +### 4. Refusal stability + +Previously refusing cases MAY become: + +- correctly admitted +- still refused + +They MUST NOT become: + +- partially admitted +- ambiguously admitted +- non-deterministically admitted + +--- + +## Partition guarantees + +FrameClaims inherit the ADR-0167 domain partition. + +Math-domain frame claims: + +- use math-domain replay gates +- use math-domain contemplation routing +- do not borrow cognition corpus evidence +- do not reuse cognition semantic-domain classifiers + +Cross-domain leakage is prohibited. + +--- + +## Refusal-first doctrine + +The system must continue preferring: + +```text +refuse > speculate +``` + +throughout FrameClaim processing. + +Specifically forbidden: + +- nearest-frame guessing +- probabilistic fallback frame selection +- majority-vote frame admission +- confidence-threshold semantic coercion +- dynamic graph completion + +A missing frame remains a refusal event. + +The teaching corridor exists precisely so the engine does not need to +invent structure at runtime. + +--- + +## Non-goals + +This ADR does NOT approve: + +- CompositionClaim +- ReferenceClaim +- SlotClaim +- dynamic frame synthesis +- graph-schema replacement +- automatic frame learning +- runtime self-modification +- autonomous pack mutation +- embedding-derived semantic repair + +This ADR also does NOT attempt to solve: + +- generalized natural language understanding +- open-ended semantic parsing +- unrestricted text interpretation + +The target is bounded deterministic graph admission for audited +GSM8K-style reasoning surfaces. + +--- + +## Sequencing + +Per ADR-0166: + +### Q1 — Capability + +Adds one new operator-ratifiable admissibility surface: + +```text +surface form -> reviewed frame category +``` + +using the existing audit → contemplation → replay → HITL corridor. + +### Q2 — Lane + +No new eval lane. + +Existing: + +- GSM8K audit lane +- contemplation replay lane +- wrong==0 gates +- determinism checks + +remain the proof surface. + +### Q3 — Invariant + +Must preserve: + +- wrong==0 +- replay equivalence +- deterministic claim hashing +- refusal-first semantics +- explicit operator ratification +- reviewed mutation only + +The implementation PR passes only when all six are mechanically proven. + +--- + +## Acceptance gates for implementation PR + +A future implementation PR must provide: + +- deterministic claim canonicalization tests +- replay-equivalence tests +- queue-order independence tests +- duplicate ratification idempotency tests +- case 0050 hazard pins +- recognized-but-uninjectable regression pins +- refusal-stability regression suite +- cross-domain partition tests +- no-corpus-mutation proof +- no-runtime-hotpatch proof + +without introducing: + +- new eval lanes +- stochastic routing +- runtime graph guessing + +--- + +## Relationship to ADR-0167 + +ADR-0167 established: + +```text +audit rows become teaching evidence +``` + +ADR-0168 establishes: + +```text +frame-opening semantics may become reviewed teaching evidence, +but only under deterministic replay-constrained doctrine +``` + +The distinction matters. + +LexicalClaim teaches vocabulary. +FrameClaim teaches admissibility structure. + +That is a materially more dangerous surface and therefore requires +explicit doctrine before implementation. + +--- + +## Decision + +> CORE may extend the ADR-0167 teaching corridor from lexical +> ratification into bounded frame-opening ratification, provided: +> +> - replay equivalence remains deterministic +> - wrong==0 hazard pins hold +> - frame categories remain explicitly allowlisted +> - runtime speculation remains prohibited +> - all mutation remains proposal-reviewed and replay-auditable +> +> Refusal remains preferable to speculative graph construction. + +Reopening this ADR requires evidence that: + +1. the replay obligations cannot be satisfied mechanically, or +2. a graph-schema approach supersedes sub-type ratification entirely.