diff --git a/HANDOFF-gpt55-2026-06-20.md b/HANDOFF-gpt55-2026-06-20.md index 746bc4b2..2a438707 100644 --- a/HANDOFF-gpt55-2026-06-20.md +++ b/HANDOFF-gpt55-2026-06-20.md @@ -253,3 +253,29 @@ The substantive result of this session is not just “0005 runnable.” It is th - **Smoke suite**: `core.cli test --suite smoke -q` -> Running in background. +--- + +## PR #839 Addendum — docs(substrate): add foundational family specification appendices + +### Agent and Session + +- **Agent:** Antigravity (Gemini 3.5 Flash) +- **Date:** 2026-06-20 +- **Task:** Create the foundational family specification appendix structure required by ADR-0224 +- **Branch:** `docs/foundational-family-spec-appendices` + +### Modules Touched / Created + +| File | Change type | Summary | +|---|---|---| +| `docs/specs/foundational-families/README.md` | NEW | README file explaining post-ADR-0224 gating rules, extension of ADR-0223's closeness/bindings/contracts rule, and diagnostic role of benchmarks. | +| `docs/specs/foundational-families/TEMPLATE.md` | NEW | Mandatory template section structure for foundational family specifications. | +| `docs/specs/foundational-families/quantity-entity-binding.md` | NEW | Constitutional specification for the quantity-entity binding family, featuring cross-domain use cases, required/optional roles, hazards, and refusal conditions. | +| `docs/specs/foundational-families/state-change.md` | NEW | Constitutional specification for the state-change family, featuring cross-domain use cases, required/optional roles, hazards, and refusal conditions. | +| `docs/analysis/pr839-lookback-2026-06-20.md` | NEW | Lookback documenting design choices, verification details, and alignment with ADR-0224. | +| `HANDOFF-gpt55-2026-06-20.md` | modified | Updated with this PR #839 addendum. | + +### Invariants Verified + +- **Versor condition**: No geometric algebra files were touched; versor invariants remain fully satisfied. +- **Docs-Only Scope**: Verified that all changes are purely documentation additions or comments, with no runtime code or test suite modifications. diff --git a/docs/analysis/pr839-lookback-2026-06-20.md b/docs/analysis/pr839-lookback-2026-06-20.md new file mode 100644 index 00000000..d4016baa --- /dev/null +++ b/docs/analysis/pr839-lookback-2026-06-20.md @@ -0,0 +1,31 @@ +# Lookback: PR #839 Foundational Family Specification Appendices + +**Date:** 2026-06-20 +**PR:** #839 +**Status:** Completed (Docs-only) + +## Objectives & Context + +Following the merge of **ADR-0224**, this PR establishes the controlled, constitutional location for foundational substrate family specifications. ADR-0224 mandates that: +1. No family may receive implementation slices before its complete specification is written and approved in the designated location. +2. The substrate must not become benchmark-shaped (e.g., GSM8K-only); it must support minimal reusable constructional affordances across at least 8 foundational elementary/middle-school domains. + +This PR executes the first post-ADR-0224 step: +- Created the controlled specification directory `docs/specs/foundational-families/`. +- Established `README.md` and `TEMPLATE.md` to define the gating rules and mandatory specification fields. +- Drafted the initial specification files for two high-leverage families: `quantity-entity-binding.md` and `state-change.md`. + +## Architectural Alignment & Verification + +This work strictly adheres to the semantic-substrate affordance audit charter (**ADR-0223**) and readiness mapping rules (**ADR-0224**). + +- **Docs-Only Scope:** No codebase changes or executable files were created or modified. All changes reside strictly under `docs/` and `HANDOFF-gpt55-2026-06-20.md`. +- **Benchmark Autonomy:** The specifications explicitly decouple the substrate definitions from GSM8K, detailing cross-domain examples in physical sciences, reading comprehension, life sciences, and social studies. +- **Typed ProblemFrame Focus:** The specifications present the ProblemFrame/domain-frame representations in typed relation/binding language (using Python-like class syntax for `MentionBinding`, `BoundRelation`, `RelationRole`, etc.), rather than prose-only descriptions. +- **No Implementation Authorization:** Both specifications carry explicit serving status notes and clear warnings that implementation is unauthorized by this PR and must come via separate, evidence-backed PRs. + +## Invariant Review + +- **Versor Condition:** `||F * reverse(F) - 1||_F < 1e-6` is trivially preserved as no algebra, field, or solver code was touched. +- **No New Legacy:** No local parsing logic or regex was added, satisfying the deprecation rules. +- **Wrong-Zero Discipline:** Retained. diff --git a/docs/specs/foundational-families/README.md b/docs/specs/foundational-families/README.md new file mode 100644 index 00000000..3aac9aaf --- /dev/null +++ b/docs/specs/foundational-families/README.md @@ -0,0 +1,25 @@ +# Foundational Substrate Family Specifications + +This directory contains the controlled foundational family specifications for the K–8 cognitive substrate, as mandated by **ADR-0224**. + +## Core Principles + +1. **Gate for Implementation Slices** + A complete and approved family specification document in this directory is a strict constitutional requirement *before* any implementation slice for that family is authorized. These specifications act as architectural gating artifacts, not runtime behavior. + +2. **Extension of ADR-0223 Doctrine** + All future family design and implementation must strictly adhere to the canonical rule defined in **ADR-0223**: + > Closeness proposes; bindings ground; contracts determine. + + - **Semantic closeness proposes:** Lexical cues and, where implemented, exact substrate/CGA neighborhood retrieval may identify candidate affordances. + - **Exact bindings ground:** Span-grounded bindings map values to roles. + - **Organ-specific contracts determine:** Contract assessments verify completeness, topology, and absence of hazards before admitting a candidate. + +3. **Benchmarks as Diagnostic Lanes Only** + Benchmarks, such as GSM8K, are valuable diagnostic pressure lanes to identify gaps, verify behavior, and test morphology. They **never** define the substrate. The substrate is defined by minimal, reusable constructional affordances across elementary and middle school subjects. + +## Directory Structure + +- [TEMPLATE.md](TEMPLATE.md): The mandatory section structure every family specification must populate. +- [quantity-entity-binding.md](quantity-entity-binding.md): Specification for the quantity-entity binding family. +- [state-change.md](state-change.md): Specification for the state-change family. diff --git a/docs/specs/foundational-families/TEMPLATE.md b/docs/specs/foundational-families/TEMPLATE.md new file mode 100644 index 00000000..b69231c1 --- /dev/null +++ b/docs/specs/foundational-families/TEMPLATE.md @@ -0,0 +1,19 @@ +# Foundational Family Specification: + +Status: +Related ADRs: +Domains: +Summary: +Surface / chunk patterns: +Semantic neighborhood: +Construction signatures: +Required roles: +Optional roles: +Hazards / confusers: +ProblemFrame / domain-frame representation: +ContractAssessment readiness criteria: +Verification style: +Refusal conditions: +Cross-domain evidence: +Serving status: +Implementation authorization: diff --git a/docs/specs/foundational-families/quantity-entity-binding.md b/docs/specs/foundational-families/quantity-entity-binding.md new file mode 100644 index 00000000..9b472626 --- /dev/null +++ b/docs/specs/foundational-families/quantity-entity-binding.md @@ -0,0 +1,128 @@ +# Foundational Family Specification: Quantity-Entity Binding + +Status: Proposed (gating specification) +Related ADRs: ADR-0223, ADR-0224 +Domains: Arithmetic/Quantitative, Physical Science, Charts/Tables/Data, Social Studies +Summary: +This family defines the structural binding of a quantified scalar value to the semantic entity, object, or category it measures. Quantity-entity binding is the foundational prerequisite for all relational reasoning: before a rate, partition, comparison, or state change can be computed, the quantities themselves must be unambiguously anchored to their semantic referents. + +Surface / chunk patterns: +- ` ` (e.g., "5 apples", "12 grams") +- ` of the ` (e.g., "three of the boxes") +- `: ` (e.g., "Population: 50,000", "Red group: 12") +- ` of ` (e.g., "5 kg of iron") + +Semantic neighborhood: +- `quantified_group` +- `measured_property` +- `category_cardinality` +- `resource_population` + +Construction signatures: +```text +Signature: quantity_entity_binding +Future adapter: quantity_entity_adapter +Relation Type: quantity_entity +``` + +Required roles: +- `quantity`: The GroundedMention pointing to a ScalarCandidate representing the numerical value (including fractions, percents, or integers). +- `entity`: The GroundedMention pointing to the noun, noun phrase, or category that the quantity measures. + +Optional roles: +- `unit`: The GroundedMention pointing to the measurement unit (e.g., "meters", "dollars"), if the quantity is dimensional. + +Hazards / confusers: +- `PF-EN-002 quantity_entity_unbound`: A quantity appears adjacent to another quantity modifier rather than a noun (e.g., "3 more"). +- `PF-LX-004 span_collision`: Numeric homophones or compound words leading to overlapping/competing scalar candidate spans (e.g., "one half-hour" -> "one", "one half", "half-hour"). +- `PF-EN-005 role_alias_collision`: Same surface denotes different subgroups or objects (e.g., "5 red apples and 3 green ones" where "ones" is an alias for "apples"). +- `PF-HZ-005 conflict_auto_resolved`: Confused reference mapping when multiple entities of the same category are mentioned in close proximity. + +ProblemFrame / domain-frame representation: +```python +# Typed bindings and relations representing quantity-entity alignment +from dataclasses import dataclass + +@dataclass(frozen=True) +class GroundedMention: + mention_id: str + surface: str + start: int + end: int + fact_id: str | None = None # Links to GroundedScalar, GroundedUnit, etc. + +@dataclass(frozen=True) +class MentionBinding: + binding_id: str + binding_type: str # "quantity_entity" | "quantity_unit" + source_mention_id: str # GroundedMention.mention_id of quantity + target_mention_id: str # GroundedMention.mention_id of entity/unit +``` + +ContractAssessment readiness criteria: +A candidate quantity-entity binding reaches `RUNNABLE` status if and only if: +1. The quantity mention is successfully grounded to a parsed `GroundedScalar` with exact numeric fraction values (`PF-LX-001` resolved). +2. The entity mention is successfully resolved to a valid noun phrase or category within the sentence span (`PF-EN-001` resolved). +3. No active overlap or span collisions exist (`PF-LX-004` resolved). +4. No unresolved hazard category is active (e.g., `quantity_entity_unbound` checks pass). + +Verification style: +- Invariance under lexical substitution (e.g., substituting "apples" with "oranges" must result in identical binding topology, modulo spans). +- Confuser rejection (e.g., "3 more than 5" must bind "5" to its entity and flag "3" as comparative, refusing generic binding for "3"). + +Refusal conditions: +- Presence of unresolved ambiguous referents (e.g., "them" or "ones" in "there are 5 apples and 3 of them" when multiple candidate entities are active and ungrounded). +- Multi-scalar overlap collisions that cannot be deterministically ordered. + +Cross-domain evidence: +1. **Physical Science (Measurement):** + - *Example:* "A block of iron has a mass of 12 grams." + - *Bindings:* + ```python + GroundedMention(mention_id="m-qty", surface="12", start=34, end=36, fact_id="scalar-0001") + GroundedMention(mention_id="m-unit", surface="grams", start=37, end=42, fact_id="unit-0001") + GroundedMention(mention_id="m-entity", surface="iron", start=10, end=14, fact_id="entity-0001") + + MentionBinding(binding_id="b-qty-ent", binding_type="quantity_entity", source_mention_id="m-qty", target_mention_id="m-entity") + MentionBinding(binding_id="b-qty-unit", binding_type="quantity_unit", source_mention_id="m-qty", target_mention_id="m-unit") + ``` +2. **Charts/Tables (Category Counts):** + - *Example:* "The bar graph shows: Apples: 15, Bananas: 8." + - *Bindings:* + ```python + GroundedMention(mention_id="m-qty-1", surface="15", start=32, end=34, fact_id="scalar-0001") + GroundedMention(mention_id="m-ent-1", surface="Apples", start=24, end=30, fact_id="entity-0001") + GroundedMention(mention_id="m-qty-2", surface="8", start=46, end=47, fact_id="scalar-0002") + GroundedMention(mention_id="m-ent-2", surface="Bananas", start=36, end=43, fact_id="entity-0002") + + MentionBinding(binding_id="b-qty-ent-1", binding_type="quantity_entity", source_mention_id="m-qty-1", target_mention_id="m-ent-1") + MentionBinding(binding_id="b-qty-ent-2", binding_type="quantity_entity", source_mention_id="m-qty-2", target_mention_id="m-ent-2") + ``` +3. **Social Studies (Demographics):** + - *Example:* "The town of Shelbyville has a population of 50,000 residents." + - *Bindings:* + ```python + GroundedMention(mention_id="m-qty", surface="50,000", start=47, end=53, fact_id="scalar-0001") + GroundedMention(mention_id="m-ent-town", surface="Shelbyville", start=12, end=23, fact_id="entity-0001") + GroundedMention(mention_id="m-ent-pop", surface="residents", start=54, end=63, fact_id="entity-0002") + + MentionBinding(binding_id="b-qty-ent", binding_type="quantity_entity", source_mention_id="m-qty", target_mention_id="m-ent-pop") + ``` +4. **Arithmetic / GSM-style Pressure Lane:** + - *Example:* "Joan has 5 marbles. She gives 3 marbles to Todd." + - *Bindings:* + ```python + GroundedMention(mention_id="m-qty-1", surface="5", start=9, end=10, fact_id="scalar-0001") + GroundedMention(mention_id="m-ent-1", surface="marbles", start=11, end=18, fact_id="entity-0001") + GroundedMention(mention_id="m-qty-2", surface="3", start=31, end=32, fact_id="scalar-0002") + GroundedMention(mention_id="m-ent-2", surface="marbles", start=33, end=40, fact_id="entity-0001") + + MentionBinding(binding_id="b-qty-ent-1", binding_type="quantity_entity", source_mention_id="m-qty-1", target_mention_id="m-ent-1") + MentionBinding(binding_id="b-qty-ent-2", binding_type="quantity_entity", source_mention_id="m-qty-2", target_mention_id="m-ent-2") + ``` + +Serving status: Not implemented / not serving. +Current state relies on ad-hoc regex heuristic extraction within local parsers. Assessment-backed proposal traces for selected math constructions exist in diagnostics, but general CGA/substrate retrieval does not yet support this family. + +Implementation authorization: +**NOT AUTHORIZED.** This is a constitutional specification file only. Implementation requires a separate, evidence-backed implementation plan and PR. diff --git a/docs/specs/foundational-families/state-change.md b/docs/specs/foundational-families/state-change.md new file mode 100644 index 00000000..1abd8bde --- /dev/null +++ b/docs/specs/foundational-families/state-change.md @@ -0,0 +1,164 @@ +# Foundational Family Specification: State Change + +Status: Proposed (gating specification) +Related ADRs: ADR-0223, ADR-0224 +Domains: Mathematics (Arithmetic/Proportional), Physical Science, Life Science, Reading Comprehension, Procedural Reasoning +Summary: +This family represents the transition of an entity or system from an initial state to a final state, triggered by an event, action, or process. It captures the initial value/condition, the mechanism or scale of change, and the resulting final value/condition. State change reasoning is vital for modeling deltas, proportional scaling, temporal sequences, and physical/biological processes. + +Surface / chunk patterns: +- ` to ` (e.g., "decreased to 3/4", "heated to 100 degrees") +- ` by ` (e.g., "increased by 5", "grew by 2 inches") +- "originally , now " (e.g., "was 12, now is 8") +- "after , has " (e.g., "after giving away 3, she had 5") + +Semantic neighborhood: +- `possession_change` +- `proportional_scaling` +- `temperature_transition` +- `growth_stage` +- `procedural_step` + +Construction signatures: +```text +Signature: state_change +Future adapter: state_change_adapter +Relation Type: state_change +``` + +Required roles: +- `entity`: The actor, object, or system undergoing the change. +- `initial_state`: The condition or quantity before the transition event. +- `transition_event`: The trigger or action causing the transition (e.g., "gives", "heats", "loses"). +- `final_state`: The condition or quantity after the transition event. + +Optional roles: +- `scale`: The ratio or scale factor of change (e.g., "3/4 of"). +- `delta`: The absolute difference/change quantity (e.g., "by 5"). + +Hazards / confusers: +- `PF-BD-004 positional_binding`: Selecting the wrong quantity as the base/initial state due to sentence ordering (e.g., "Shelly now has 8 apples. She started with some and lost 2" -> incorrectly binding 8 as initial). +- `PF-TG-004 target_direction_unknown`: Confusing a request for the final value with a request for the difference/delta, or vice versa (e.g., "How much did it decrease by?" vs "What is the new temperature?"). +- `PF-TP-006 state_transition_open`: The transition lacks clear initial, delta, or final state constraints, leading to under-constrained mathematical systems. +- `PF-HZ-003 hazard_ignored_by_contract`: Failing to block on "decreased by" vs "decreased to", which completely changes the arithmetic operator and target mapping. + +ProblemFrame / domain-frame representation: +```python +# Typed representation of state transition relations +from dataclasses import dataclass + +@dataclass(frozen=True) +class RelationRole: + role: str # "entity" | "initial_state" | "final_state" | "delta" | "scale" | "transition" + target_id: str # Mentions ID of the bound GroundedMention + +@dataclass(frozen=True) +class BoundRelation: + relation_id: str + relation_type: str # "state_change" | "decrease_to_fraction" + roles: tuple[RelationRole, ...] + evidence_spans: tuple[SourceSpan, ...] +``` + +ContractAssessment readiness criteria: +A state change candidate reaches `RUNNABLE` status if and only if: +1. The `entity` undergoing the transition is bound and verified to have entity continuity across the event span (`PF-EN-004` resolved). +2. The transition direction (increase vs decrease) is explicitly resolved from the trigger verb/surface (`PF-BD-007` resolved). +3. The target question asks for a mathematically valid and closed variable (e.g., if initial and final are known, target must be delta; if initial and delta are known, target must be final) (`PF-TG-004` resolved). +4. No unresolved directional ambiguity (such as "decreased by" vs "decreased to") is present in the active hazard categories (`PF-HZ-003` resolved). + +Verification style: +- State equation validation: `final_state = initial_state +/- delta` or `final_state = scale * initial_state`. +- Adverse confuser checks: Changing the trigger from "decreased to 3/4" to "decreased by 3/4" must fail the contract unless the delta role is re-bound and re-verified. + +Refusal conditions: +- Missing event order or temporal ambiguity (e.g., "she lost 3 apples and bought 5, ending with 8" without temporal indicators to order the events). +- Incomplete/open state transitions where neither initial, delta, nor final values can be grounded to spans. + +Cross-domain evidence: +1. **Physical Science (Temperature Change):** + - *Example:* "Water originally at 20 degrees Celsius is heated to 80 degrees Celsius." + - *Bindings:* + ```python + BoundRelation( + relation_id="rel-0001", + relation_type="state_change", + roles=( + RelationRole(role="entity", target_id="m-water"), + RelationRole(role="initial_state", target_id="m-temp-init"), + RelationRole(role="transition", target_id="m-heated"), + RelationRole(role="final_state", target_id="m-temp-final") + ), + evidence_spans=(...) + ) + ``` +2. **Life Science (Growth Change):** + - *Example:* "The plant grew from 5 inches tall to 9 inches tall over the summer." + - *Bindings:* + ```python + BoundRelation( + relation_id="rel-0001", + relation_type="state_change", + roles=( + RelationRole(role="entity", target_id="m-plant"), + RelationRole(role="initial_state", target_id="m-height-init"), + RelationRole(role="transition", target_id="m-grew"), + RelationRole(role="final_state", target_id="m-height-final") + ), + evidence_spans=(...) + ) + ``` +3. **Reading Comprehension (Event Transition):** + - *Example:* "Before the storm, the streets were dry. After the storm, the streets were flooded." + - *Bindings:* + ```python + BoundRelation( + relation_id="rel-0001", + relation_type="state_change", + roles=( + RelationRole(role="entity", target_id="m-streets"), + RelationRole(role="initial_state", target_id="m-dry"), + RelationRole(role="transition", target_id="m-storm"), + RelationRole(role="final_state", target_id="m-flooded") + ), + evidence_spans=(...) + ) + ``` +4. **Procedural Reasoning (Step Changes):** + - *Example:* "Step 1: Set X to 10. Step 2: Decrement X by 2." + - *Bindings:* + ```python + BoundRelation( + relation_id="rel-0002", + relation_type="state_change", + roles=( + RelationRole(role="entity", target_id="m-x"), + RelationRole(role="initial_state", target_id="m-x-val1"), + RelationRole(role="transition", target_id="m-decrement"), + RelationRole(role="delta", target_id="m-two") + ), + evidence_spans=(...) + ) + ``` +5. **Arithmetic / GSM-style Proportional Decrease Pressure Lane:** + - *Example:* "A group of 84 students decreases to 3/4 of its size." + - *Bindings:* + ```python + BoundRelation( + relation_id="rel-0001", + relation_type="decrease_to_fraction", + roles=( + RelationRole(role="entity", target_id="m-students"), + RelationRole(role="initial_state", target_id="m-init-count"), + RelationRole(role="transition", target_id="m-decreases"), + RelationRole(role="scale", target_id="m-fraction") + ), + evidence_spans=(...) + ) + ``` + +Serving status: Not implemented / not serving. +Current state features assessment-backed proposal traces for selected math constructions (`proportional_change.decrease_to_fraction` in diagnostics). General state-change adapter and non-math domain frames are absent from live serving pathways. + +Implementation authorization: +**NOT AUTHORIZED.** This is a constitutional specification file only. Implementation requires a separate, evidence-backed implementation plan and PR.