core-labs/core
core-labs/core
1
0
Fork 0
Code Issues 12 Pull requests Projects Releases Packages Wiki Activity Actions
core/docs/analysis/pr839-lookback-2026-06-20.md
Shay 5cd377b1b8
docs(substrate): add foundational family specification appendices (#839) 
* docs(substrate): add foundational family specification appendices

* docs(substrate): clarify family spec capability wording

* chore: retrigger required checks
2026-06-20 13:49:29 -07:00

2.3 KiB
Raw Permalink Blame History

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.