docs: changelog, LLM agent guidance, orphaned nav fixes

docs/changelog.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to the GDS ecosystem are documented here. Each release
+lists affected packages, breaking changes, and new capabilities.
+
+---
+
+## 2026-04-03 — Tier 0 + Tier 1 Complete
+
+Driven by external reviews from Zargham and Jamsheed (Shorish) against the
+GDS paper (Zargham & Shorish 2022). The reviews identified foundational gaps
+in notation alignment, formal property statements, ControlAction semantics,
+temporal agnosticism documentation, and execution contract formalization.
+This release closes all Tier 0 and Tier 1 roadmap items.
+
+### gds-framework v0.3.0
+
+**Breaking:** `CanonicalGDS.input_ports` now contains only controlled inputs (U_c);
+disturbance-tagged BoundaryAction ports are in the new `disturbance_ports` field.
+
+New capabilities:
+
+- **ExecutionContract** — DSL-layer time model declaration (`discrete`, `continuous`,
+  `event`, `atemporal`) with Moore/Mealy ordering. Attached as optional field on
+  GDSSpec. A spec without a contract remains valid for structural verification.
+- **ControlAction canonical projection** — `CanonicalGDS` now extracts output ports
+  (Y) and renders the output map `y = C(x, d)` in the formula.
+- **Disturbance input partition** — `disturbance_ports` on `CanonicalGDS` separates
+  policy-bypassing exogenous inputs (W) from controlled inputs (U_c) via
+  `tags={"role": "disturbance"}` on BoundaryAction.
+- **TypeDef.constraint_kind** — optional named constraint pattern (`non_negative`,
+  `positive`, `probability`, `bounded`, `enum`) enabling round-trip export via SHACL.
+
+New verification checks:
+
+- **SC-010** — ControlAction outputs must not feed the g pathway (Policy/BoundaryAction)
+- **SC-011** — ExecutionContract well-formedness
+- **DST-001** — Disturbance-tagged BoundaryAction must not wire to Policy
+
+Documentation:
+
+- Formal property statements for all 15 core checks (G-001..G-006, SC-001..SC-009)
+- Requirement traceability markers on all verification tests
+- Tests for SC-005..SC-009 (previously untested)
+- Controller-plant duality design document
+- Temporal agnosticism invariant with three-layer stack diagram
+- Audit of 30+ docs replacing "timestep" with temporally neutral vocabulary
+- Assurance claims document with verification passport template
+- Execution semantics design document with DSL contract mapping
+- Disturbance formalization design document
+- Notation harmonized with Zargham & Shorish (2022)
+
+### gds-owl v0.2.0
+
+- **SHACL constraint promotion** — `TypeDef.constraint_kind` metadata exports as SHACL
+  property shapes (`sh:minInclusive`, `sh:maxInclusive`, `sh:minExclusive`, `sh:in`).
+  Constraints with a `constraint_kind` are now R2 round-trippable; those without remain
+  R3 lossy. Import reconstructs Python callable constraints from SHACL metadata.
+- New ontology properties: `constraintKind`, `constraintLow`, `constraintHigh`, `constraintValue`
+- New `build_constraint_shapes()` public API
+
+### gds-psuu v0.2.1
+
+- **Parameter schema validation** — `ParameterSpace.from_parameter_schema()` creates
+  sweep dimensions from declared ParameterDef entries. `validate_against_schema()`
+  catches missing params, type mismatches, and out-of-bounds sweeps.
+- **PSUU-001 check** following the GDS Finding pattern
+- Sweep runner validates against schema when `parameter_schema` is provided
+
+### gds-stockflow v0.1.1
+
+- Emit `ExecutionContract(time_domain="discrete")` from `compile_model()`
+
+### gds-control v0.1.1
+
+- Emit `ExecutionContract(time_domain="discrete")` from `compile_model()`
+
+### gds-games v0.3.2
+
+- Emit `ExecutionContract(time_domain="atemporal")` from `compile_pattern_to_spec()`
+
+### gds-software v0.1.1
+
+- Emit `ExecutionContract` from all 6 compilers: `atemporal` for DFD, C4, component,
+  ERD, dependency; `discrete` for state machines
+
+### gds-business v0.1.1
+
+- Emit `ExecutionContract` from all 3 compilers: `discrete` for CLD and supply chain,
+  `atemporal` for value stream maps
+
+### gds-analysis v0.1.1
+
+- Guard `gds-continuous` import in `backward_reachability.py` (previously caused
+  ImportError when gds-continuous wasn't installed)
+
+---
+
+## Earlier Releases
+
+### gds-framework v0.2.3
+
+- Add `StructuralWiring` to public API (compiler intermediate for domain DSL wiring emitters)
+- Switch to dynamic versioning — `__version__` in `__init__.py` is the single source of truth
+- Tighten `gds-framework>=0.2.3` lower bound across all dependent packages
+
+### gds-games v0.2.0
+
+- Add canonical bridge (`compile_pattern_to_spec`) — projects OGS patterns to `GDSSpec`
+- Add view stratification architecture
+- Require `gds-framework>=0.2.3`
+
+### gds-stockflow v0.1.0
+
+- Initial release — declarative stock-flow DSL over GDS semantics
+
+### gds-control v0.1.0
+
+- Initial release — state-space control DSL over GDS semantics
+
+### gds-viz v0.1.2
+
+- Mermaid renderers for structural, canonical, architecture, parameter, and traceability views

docs/index.md

@@ -112,6 +112,27 @@ graph TD
 
 **Legend:** :blue_square: Core | :yellow_square: Domain DSLs | :green_square: Simulation & Analysis | :purple_square: Tooling
 
+## For AI Agents and LLMs
+
+This documentation is available in a machine-readable format for AI coding
+assistants, agents, and LLMs:
+
+| Resource | URL | Use |
+|----------|-----|-----|
+| **llms.txt** | [/llms.txt](https://blockscience.github.io/gds-core/llms.txt) | Compact index of all documentation pages with one-line descriptions |
+| **llms-full.txt** | [/llms-full.txt](https://blockscience.github.io/gds-core/llms-full.txt) | Full concatenated documentation — feed this to an LLM for complete context on the GDS ecosystem |
+
+**If you are an AI agent** working with gds-core, fetch `llms-full.txt` to get
+a comprehensive understanding of the framework's architecture, all 14 packages,
+the composition algebra, verification engine, and domain DSLs. The file follows
+the [llms.txt](https://llmstxt.org) standard and contains every documentation
+page in this site as plain Markdown.
+
+## Changelog
+
+See the [Changelog](changelog.md) for a complete history of releases, breaking
+changes, and new capabilities across all packages.
+
 ## License
 
 Apache-2.0 — [BlockScience](https://block.science)

mkdocs.yml

@@ -132,8 +132,28 @@ plugins:
         Case Studies:
           - {case-studies/index.md: "Real-world projects built on the GDS ecosystem"}
           - {case-studies/axelrod.md: "Axelrod tournament — one model, many views with gds-games, gds-sim, gds-psuu, gds-viz"}
+        Design & Research:
+          - {framework/design/assurance-claims.md: "Verification passport and assurance claims"}
+          - {framework/design/check-specifications.md: "Formal property statements for all verification checks"}
+          - {framework/design/controller-plant-duality.md: "ControlAction as output map y = C(x, d)"}
+          - {framework/design/disturbance-formalization.md: "Disturbance inputs — U_c/W partition"}
+          - {framework/design/temporal-agnosticism.md: "Temporal agnosticism invariant and three-layer stack"}
+          - {framework/design/execution-semantics.md: "ExecutionContract and DSL time model declaration"}
+          - {framework/design/traceability-matrix.md: "Requirement-to-test traceability matrix"}
+          - {framework/design/gds-deepdive.md: "GDS theory deep dive — formalism, MSML, BDP-lib synthesis"}
+          - {framework/design/v0.2-design.md: "v0.2 architecture — parameter typing, canonical projection, tags"}
+          - research/research-boundaries.md
+          - research/paper-implementation-gap.md
+          - research/semantic-web-summary.md
+          - research/formal-representability.md
+          - research/representation-gap.md
+          - research/verification-plan.md
+          - research/verification/*.md
+          - research/journal.md
         Ecosystem:
           - {framework/ecosystem.md: "All packages, their imports, and dependency relationships"}
+        Changelog:
+          - {changelog.md: "Release history — breaking changes, new capabilities, version bumps"}
 
 markdown_extensions:
   - admonition
@@ -378,22 +398,31 @@ nav:
       - case-studies/index.md
       - Axelrod Tournament: case-studies/axelrod.md
   - Design & Research:
-      - Assurance Claims: framework/design/assurance-claims.md
-      - Check Specifications: framework/design/check-specifications.md
-      - Layer 0 Milestone: guides/architecture-milestone-layer0.md
-      - Controller-Plant Duality: framework/design/controller-plant-duality.md
-      - Disturbance Formalization: framework/design/disturbance-formalization.md
-      - DSL Roadmap: guides/dsl-roadmap.md
-      - Research Boundaries: research/research-boundaries.md
-      - Paper Implementation Gap: research/paper-implementation-gap.md
-      - Temporal Agnosticism: framework/design/temporal-agnosticism.md
-      - Execution Semantics: framework/design/execution-semantics.md
-      - View Stratification: guides/view-stratification.md
-      - Ecosystem: framework/ecosystem.md
-      - Semantic Web Integration: research/semantic-web-summary.md
-      - Traceability Matrix: framework/design/traceability-matrix.md
-      - Formal Verification:
-          - Verification Plan: research/verification-plan.md
-          - R3 Non-Representability: research/verification/r3-undecidability.md
-          - R1/R2 Decidability: research/verification/representability-proof.md
+      - Design Documents:
+          - Assurance Claims: framework/design/assurance-claims.md
+          - Check Specifications: framework/design/check-specifications.md
+          - Controller-Plant Duality: framework/design/controller-plant-duality.md
+          - Disturbance Formalization: framework/design/disturbance-formalization.md
+          - Temporal Agnosticism: framework/design/temporal-agnosticism.md
+          - Execution Semantics: framework/design/execution-semantics.md
+          - Traceability Matrix: framework/design/traceability-matrix.md
+          - GDS Deep Dive: framework/design/gds-deepdive.md
+          - v0.2 Architecture: framework/design/v0.2-design.md
+          - Entity Redesign Proposal: framework/design/proposals/entity-redesign.md
+      - Research:
+          - Research Boundaries: research/research-boundaries.md
+          - Paper Implementation Gap: research/paper-implementation-gap.md
+          - Representation Gap: research/representation-gap.md
+          - Semantic Web Integration: research/semantic-web-summary.md
+          - Formal Representability: research/formal-representability.md
+          - Formal Verification:
+              - Verification Plan: research/verification-plan.md
+              - R3 Non-Representability: research/verification/r3-undecidability.md
+              - R1/R2 Decidability: research/verification/representability-proof.md
           - Research Journal: research/journal.md
+      - Roadmaps & Milestones:
+          - Layer 0 Milestone: guides/architecture-milestone-layer0.md
+          - DSL Roadmap: guides/dsl-roadmap.md
+          - View Stratification: guides/view-stratification.md
+      - Ecosystem: framework/ecosystem.md
+  - Changelog: changelog.md