core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs(substrate): add foundational family specification appendices (#839)

Browse source 
* docs(substrate): add foundational family specification appendices

* docs(substrate): clarify family spec capability wording

* chore: retrigger required checks
This commit is contained in:
Shay 2026-06-20 13:49:29 -07:00 committed by GitHub
parent f4a2a2925b
commit 5cd377b1b8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 393 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
HANDOFF-gpt55-2026-06-20.md
View file

@ -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.

31
docs/analysis/pr839-lookback-2026-06-20.md Normal file
View file

@ -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.

25
docs/specs/foundational-families/README.md Normal file
View file

@ -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.

19
docs/specs/foundational-families/TEMPLATE.md Normal file
View file

@ -0,0 +1,19 @@
# Foundational Family Specification: <family>
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:

128
docs/specs/foundational-families/quantity-entity-binding.md Normal file
View file

@ -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:
- `<number> <noun>` (e.g., "5 apples", "12 grams")
- `<number> of the <noun>` (e.g., "three of the boxes")
- `<noun>: <number>` (e.g., "Population: 50,000", "Red group: 12")
- `<number> <unit> of <material>` (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.

164
docs/specs/foundational-families/state-change.md Normal file
View file

@ -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:
- `<verb-change> to <value>` (e.g., "decreased to 3/4", "heated to 100 degrees")
- `<verb-change> by <value>` (e.g., "increased by 5", "grew by 2 inches")
- "originally <value>, now <value>" (e.g., "was 12, now is 8")
- "after <event>, <actor> has <value>" (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.