From bb41357322b063d4df6f0fee7f6db5f1776e66c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Jan 2026 15:14:11 +0000 Subject: [PATCH] feat: add anchor configuration system for upstream/satellite governance Establishes hyperpolymath anchor system for managing semantic authority between the canonical eclexia repo and downstream satellites. This prevents agentic drift and toolchain creep by defining clear boundaries. - ANCHOR.scm: Defines eclexia as upstream-canonical with semantic authority - .machine_read/LLM_SUPERINTENDENT.scm: Machine-readable AI guidance - .machine_read/ROADMAP.f0.scm: Phase F0 development roadmap - .machine_read/AUTHORITY_STACK.scm: Task routing via just/must/nickel - .machine_read/SATELLITE_ANCHOR_TEMPLATE.scm: Template for downstream repos - ECOSYSTEM.scm: Updated with anchor system references and satellite links --- .machine_read/AUTHORITY_STACK.scm | 48 +++++++ .machine_read/LLM_SUPERINTENDENT.scm | 81 +++++++++++ .machine_read/ROADMAP.f0.scm | 67 +++++++++ .machine_read/SATELLITE_ANCHOR_TEMPLATE.scm | 142 ++++++++++++++++++++ ANCHOR.scm | 105 +++++++++++++++ ECOSYSTEM.scm | 34 ++++- 6 files changed, 470 insertions(+), 7 deletions(-) create mode 100644 .machine_read/AUTHORITY_STACK.scm create mode 100644 .machine_read/LLM_SUPERINTENDENT.scm create mode 100644 .machine_read/ROADMAP.f0.scm create mode 100644 .machine_read/SATELLITE_ANCHOR_TEMPLATE.scm create mode 100644 ANCHOR.scm diff --git a/.machine_read/AUTHORITY_STACK.scm b/.machine_read/AUTHORITY_STACK.scm new file mode 100644 index 0000000..10e1ac1 --- /dev/null +++ b/.machine_read/AUTHORITY_STACK.scm @@ -0,0 +1,48 @@ +;; SPDX-License-Identifier: AGPL-3.0-or-later +;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +;;; AUTHORITY_STACK.scm — Task routing + config authority for hyperpolymath repos + +(define-module (eclexia machine-read authority-stack) + #:export (authority-stack)) + +(define authority-stack + '((schema . "hyperpolymath.authority-stack/1") + (intent + . ("Stop agentic drift and toolchain creep." + "Make the repo executable via a single blessed interface." + "Prevent the LLM from inventing commands, tools, or files.")) + + (operational-authority + . ((local-tasks . "just") + (deployment-transitions . "must") + (config-manifests . "nickel") + (container-engine . "podman-first"))) + + (hard-rules + . ("Makefiles are forbidden." + "All operations must be invoked via `just ` (local) or `must ` (deployment)." + "If a recipe/transition does not exist, the correct action is to ADD it (and document it), not to run ad-hoc commands." + "Nickel manifests are the single source of truth for config; do not hand-edit generated outputs." + "No network-required runtime paths for demos/tests unless explicitly permitted in ANCHOR.")) + + (workflow + . ((first-run + . ("Read ANCHOR*.scm" + "Read STATE.scm" + "Run: just --list" + "Run: just test" + "Run: just demo (if defined)")) + (adding-new-capability + . ("Update SPEC/ROADMAP first" + "Add a `just` recipe (and tests) that implements the capability" + "Only then edit code")))) + + (tooling-contract + . ((mustfile-notes + . ("Mustfile is the deployment contract (physical state transitions)." + "must is the supervisor/enforcer for must-spec; it routes through just where appropriate.")) + (nickel-notes + . ("Nickel provides validated, type-safe manifests." + "Prefer .ncl for machine-truth; render docs from it via your conversion pipeline.")) + (shell-entrypoints + . ("Shell wrappers may exist; all must route to just/must without inventing extra logic.")))))) diff --git a/.machine_read/LLM_SUPERINTENDENT.scm b/.machine_read/LLM_SUPERINTENDENT.scm new file mode 100644 index 0000000..20bc8f5 --- /dev/null +++ b/.machine_read/LLM_SUPERINTENDENT.scm @@ -0,0 +1,81 @@ +;; SPDX-License-Identifier: AGPL-3.0-or-later +;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +;;; LLM_SUPERINTENDENT.scm — Machine-readable guidance for AI assistants + +(define-module (eclexia machine-read llm-superintendent) + #:export (superintendent-policy repo-identity constraints directives)) + +(define superintendent-policy + '((schema . "hyperpolymath.superintendent/1") + (repo . "hyperpolymath/eclexia") + (role . "upstream-canonical") + (last-updated . "2026-01-01"))) + +(define repo-identity + '((name . "Eclexia") + (type . "programming-language") + (domain . "sustainable-computing") + (one-liner . "Energy-aware language with dimensional types and shadow price optimization") + + (core-concepts + . ((dimensional-types . "Types carry physical units (joules, watts, seconds)") + (shadow-prices . "Runtime cost model: energy + latency + carbon") + (adaptive-execution . "Select implementation based on current shadow prices") + (energy-accounting . "Track and report energy consumption at language level"))) + + (this-repo-owns + . ("Language semantics and specification" + "Compiler implementation (Rust)" + "Formal proofs and type theory" + "Reference interpreter" + "CLI and REPL")) + + (this-repo-does-not-own + . ("Playground demos (see eclexia-playground)" + "IDE extensions" + "User tutorials beyond GETTING_STARTED.md")))) + +(define constraints + '((language-policy + . ((allowed . ("Rust" "OCaml" "Scheme" "Shell" "Just" "Deno" "ReScript" "Markdown" "AsciiDoc")) + (forbidden . ("TypeScript" "Node.js" "npm" "Go" "Python")) + (compiler-only . ("Rust" "OCaml")))) + + (semantic-policy + . ((authority . "This repo is the ONLY authoritative source for Eclexia semantics") + (no-forks-defining-semantics . #t) + (satellites-must-pin . #t))) + + (security-policy + . ((no-md5-sha1 . #t) + (https-only . #t) + (no-hardcoded-secrets . #t) + (spdx-headers-required . #t))) + + (rsr-compliance + . ((target . "gold") + (sha-pinned-actions . #t) + (multi-platform-ci . #t))))) + +(define directives + '((when-modifying-compiler + . ("Ensure all existing tests pass" + "Add tests for new functionality" + "Update SPECIFICATION.md if semantics change" + "Update STATE.scm completion percentages")) + + (when-adding-features + . ("Check alignment with energy-aware computing mission" + "Consider shadow price implications" + "Document in appropriate .md file" + "Add examples in examples/ directory")) + + (when-working-on-satellites + . ("Satellites CANNOT define or change language semantics" + "Always pin to specific upstream commit" + "Reference upstream ANCHOR.scm for policy")) + + (golden-path-verification + . ("cargo test — must pass" + "cargo run -- check examples/ — must succeed" + "cargo run -- run examples/fibonacci.ecl — must execute")))) diff --git a/.machine_read/ROADMAP.f0.scm b/.machine_read/ROADMAP.f0.scm new file mode 100644 index 0000000..c81208e --- /dev/null +++ b/.machine_read/ROADMAP.f0.scm @@ -0,0 +1,67 @@ +;; SPDX-License-Identifier: AGPL-3.0-or-later +;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +;;; ROADMAP.f0.scm — Machine-readable development roadmap (Phase F0) + +(define-module (eclexia machine-read roadmap) + #:export (roadmap current-phase milestones dependencies)) + +(define roadmap + '((schema . "hyperpolymath.roadmap/1") + (repo . "hyperpolymath/eclexia") + (phase . "f0") + (phase-name . "Foundation") + (last-updated . "2026-01-01"))) + +(define current-phase + '((id . "f0") + (name . "Foundation Phase") + (status . "in-progress") + (completion . 55) + (objectives + . ("Complete core compiler pipeline" + "Establish type checking with dimensional analysis" + "Implement shadow price runtime selection" + "Create reference interpreter")))) + +(define milestones + '((m0-lexer + . ((status . "complete") + (deliverables . ("Token types" "Dimensional literals" "Position tracking")))) + + (m1-parser + . ((status . "complete") + (deliverables . ("Recursive descent parser" "AST construction" "Error recovery")))) + + (m2-ast + . ((status . "complete") + (deliverables . ("Expression types" "Type annotations" "Dimensional type nodes")))) + + (m3-typeck + . ((status . "in-progress") + (completion . 60) + (deliverables . ("Hindley-Milner inference" "Dimensional type checking" "Error messages")) + (remaining . ("Full dimensional unification" "Constraint solving" "Energy bound inference")))) + + (m4-hir + . ((status . "not-started") + (deliverables . ("High-level IR" "Desugaring" "Name resolution")))) + + (m5-mir + . ((status . "not-started") + (deliverables . ("Mid-level IR" "Optimization passes" "Shadow price analysis")))) + + (m6-codegen + . ((status . "not-started") + (deliverables . ("LLVM backend" "WebAssembly target" "Energy instrumentation")))) + + (m7-runtime + . ((status . "not-started") + (completion . 5) + (deliverables . ("Shadow price runtime" "Energy metering" "Adaptive dispatch")))))) + +(define dependencies + '((m3-typeck . (m0-lexer m1-parser m2-ast)) + (m4-hir . (m3-typeck)) + (m5-mir . (m4-hir)) + (m6-codegen . (m5-mir)) + (m7-runtime . (m6-codegen)))) diff --git a/.machine_read/SATELLITE_ANCHOR_TEMPLATE.scm b/.machine_read/SATELLITE_ANCHOR_TEMPLATE.scm new file mode 100644 index 0000000..8046fbc --- /dev/null +++ b/.machine_read/SATELLITE_ANCHOR_TEMPLATE.scm @@ -0,0 +1,142 @@ +;; SPDX-License-Identifier: AGPL-3.0-or-later +;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +;;; SATELLITE_ANCHOR_TEMPLATE.scm — Template for downstream/satellite repositories +;;; +;;; USAGE: Copy this file to your satellite repo as ANCHOR.scm and customize +;;; the fields marked with TODO comments. + +(define-module (eclexia-satellite anchor) + #:export (anchor)) + +(define anchor + '((schema . "hyperpolymath.anchor/1") + ;; TODO: Set your satellite repo name + (repo . "hyperpolymath/eclexia-SATELLITE_NAME") + ;; TODO: Set current date + (date . "YYYY-MM-DD") + (authority . "repo-superintendent") + ;; TODO: Define your satellite's purpose (scope arrest) + (purpose + . ("Scope arrest: [DESCRIBE BOUNDARIES]" + "Keep one reproducible, offline golden path." + "Ensure satellite stays aligned with upstream Eclexia language identity/spec.")) + + (identity + . ((project . "Eclexia [SATELLITE_NAME]") + ;; TODO: Set kind (playground, tooling, bindings, docs, etc.) + (kind . "[playground|tooling|bindings|docs]") + ;; TODO: One-sentence description + (one-sentence . "[DESCRIBE YOUR SATELLITE]") + (upstream . "hyperpolymath/eclexia"))) + + (semantic-anchor + . ((policy . "downstream") + (upstream-authority + . ("Language semantics/spec live in hyperpolymath/eclexia." + "This repo may illustrate, prototype, benchmark, or visualize—but not define semantics.")))) + + ;; TODO: Customize allowed/quarantined/forbidden based on satellite purpose + (implementation-policy + . ((allowed + . ("Scheme" "Shell" "Just" + "Deno" "ReScript" + ;; Add other languages appropriate for your satellite + "Markdown" "AsciiDoc")) + (quarantined + . ("Any 'compiler' work (must live upstream unless explicitly delegated by upstream ANCHOR)" + "Any new runtime/backends beyond demo stubs")) + (forbidden + . ("Second authoritative compiler" + "Changing Eclexia's mission statement in this repo" + "Network-required execution for demos")))) + + ;; TODO: Define your golden path smoke tests + (golden-path + . ((smoke-test-command + . ("just --list" + "just test ;; must exist" + "just demo ;; must exist; runs one canonical example offline")) + (success-criteria + . ("A clean checkout can run `just demo` offline." + "[ADD SATELLITE-SPECIFIC SUCCESS CRITERIA]" + "README/STATE do not contradict upstream identity.")))) + + ;; TODO: List mandatory machine-readable files for your satellite + (mandatory-files + . ("./.machine_read/LLM_SUPERINTENDENT.scm" + "./.machine_read/ROADMAP.f0.scm")) + + ;; TODO: Define first-pass setup directives + (first-pass-directives + . ("[ADD SETUP DIRECTIVES]" + "Pin upstream commits if importing artifacts; document the pin.")) + + ;; RSR compliance tier + (rsr . ((target-tier . "bronze-now") + (upgrade-path . "silver-after-f1 (CI + pinned artifacts + e2e demo)"))))) + + +;;; ============================================================================ +;;; EXAMPLE: eclexia-playground ANCHOR +;;; ============================================================================ +;;; Below is a complete example for the eclexia-playground satellite. +;;; Delete this section after customizing the template above. + +(define example-playground-anchor + '((schema . "hyperpolymath.anchor/1") + (repo . "hyperpolymath/eclexia-playground") + (date . "2026-01-01") + (authority . "repo-superintendent") + (purpose + . ("Scope arrest: sandbox + demos only. No second authoritative implementation." + "Keep one reproducible, offline golden path." + "Ensure satellite stays aligned with upstream Eclexia language identity/spec.")) + + (identity + . ((project . "Eclexia Playground") + (kind . "playground") + (one-sentence . "Experimentation sandbox for Eclexia (sustainable computing / energy-aware language ideas).") + (upstream . "hyperpolymath/eclexia"))) + + (semantic-anchor + . ((policy . "downstream") + (upstream-authority + . ("Language semantics/spec live in hyperpolymath/eclexia." + "This repo may illustrate, prototype, benchmark, or visualize—but not define semantics.")))) + + (implementation-policy + . ((allowed + . ("Scheme" "Shell" "Just" + "Deno" "ReScript" + "Zig" "V" + "Markdown" "AsciiDoc")) + (quarantined + . ("Any 'compiler' work (must live upstream unless explicitly delegated by upstream ANCHOR)" + "Any new runtime/backends beyond demo stubs")) + (forbidden + . ("Second authoritative compiler" + "Changing Eclexia's mission statement in this repo" + "Network-required execution for demos")))) + + (golden-path + . ((smoke-test-command + . ("just --list" + "just test ;; must exist; may call deno test or scheme harness" + "just demo ;; must exist; runs one canonical example offline")) + (success-criteria + . ("A clean checkout can run `just demo` offline." + "At least 1 example demonstrates the *intended* Eclexia concept (energy/cost annotations) in a testable way." + "README/STATE do not contradict upstream identity.")))) + + (mandatory-files + . ("./.machine_read/LLM_SUPERINTENDENT.scm" + "./.machine_read/ROADMAP.f0.scm" + "./.machine_read/SPEC.playground.scm")) + + (first-pass-directives + . ("Add SPEC.playground.scm that defines: demo contract, artifact contract, and upstream pin." + "If README claims a tech split (e.g., Zig/V), make it explicitly 'demo scaffolding', not semantics." + "Pin upstream commits if importing artifacts; document the pin.")) + + (rsr . ((target-tier . "bronze-now") + (upgrade-path . "silver-after-f1 (CI + pinned artifacts + e2e demo)"))))) diff --git a/ANCHOR.scm b/ANCHOR.scm new file mode 100644 index 0000000..239ec45 --- /dev/null +++ b/ANCHOR.scm @@ -0,0 +1,105 @@ +;; SPDX-License-Identifier: AGPL-3.0-or-later +;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +;;; ANCHOR.scm — eclexia (authoritative upstream) + +(define-module (eclexia anchor) + #:export (anchor satellite-policy semantic-authority)) + +(define anchor + '((schema . "hyperpolymath.anchor/1") + (repo . "hyperpolymath/eclexia") + (date . "2026-01-01") + (authority . "upstream-canonical") + (purpose + . ("Define authoritative Eclexia language semantics and specification." + "Maintain canonical compiler implementation." + "Govern satellite repositories through anchor policy.")) + + (identity + . ((project . "Eclexia") + (kind . "language") + (one-sentence . "Energy-aware programming language with dimensional types and shadow price optimization.") + (domain . "sustainable-computing"))) + + (semantic-authority + . ((policy . "canonical") + (owns + . ("Language semantics and formal specification" + "Type system and dimensional analysis rules" + "Shadow price model and optimization algorithms" + "Compiler implementation (lexer, parser, AST, type-checker, codegen)" + "Runtime semantics and energy accounting")) + (delegates + . ((playgrounds . "Demos, benchmarks, visualization—not semantics") + (bindings . "FFI wrappers for specific platforms") + (tooling . "IDE plugins, formatters, linters"))))) + + (implementation-policy + . ((allowed + . ("Rust" "OCaml" + "Scheme" "Guile" + "Shell" "Just" + "Deno" "ReScript" + "Markdown" "AsciiDoc")) + (compiler-languages + . ("Rust" "OCaml")) + (forbidden + . ("TypeScript" "Node.js" "npm" "Go" + "Python (except SaltStack)" + "Network-required compilation")))) + + (golden-path + . ((smoke-test-command + . ("cargo test" + "cargo run -- check examples/" + "cargo run -- run examples/fibonacci.ecl")) + (success-criteria + . ("All tests pass." + "Compiler can parse and type-check example programs." + "Interpreter executes with shadow price selection.")))) + + (satellite-repos + . ((eclexia-playground + . ((purpose . "Experimentation sandbox, demos, benchmarks") + (authority . "downstream") + (semantic-policy . "illustrate-not-define") + (anchor-ref . "hyperpolymath/eclexia-playground"))) + (eclexia-vscode + . ((purpose . "VS Code language extension") + (authority . "downstream") + (semantic-policy . "consume-only") + (anchor-ref . "hyperpolymath/eclexia-vscode"))) + (eclexia-docs + . ((purpose . "User documentation and tutorials") + (authority . "downstream") + (semantic-policy . "document-not-define") + (anchor-ref . "hyperpolymath/eclexia-docs"))))) + + (mandatory-files + . ("./ANCHOR.scm" + "./META.scm" + "./STATE.scm" + "./ECOSYSTEM.scm" + "./.machine_read/LLM_SUPERINTENDENT.scm")) + + (rsr . ((target-tier . "gold") + (current-tier . "silver") + (upgrade-path . "CI hardening + full coverage + release automation"))))) + +(define satellite-policy + '((requirements + . ((must-pin-upstream . #t) + (must-declare-authority . #t) + (must-have-anchor . #t) + (must-have-golden-path . #t))) + (semantic-policies + . ((downstream . "May implement, must not redefine semantics") + (illustrate-not-define . "May demo/visualize, cannot change meaning") + (consume-only . "Read-only access to language spec") + (document-not-define . "Explain, do not alter"))))) + +(define semantic-authority + '((language-spec . "SPECIFICATION.md") + (formal-proofs . "PROOFS.md") + (type-theory . "THEORY.md") + (algorithms . "ALGORITHMS.md"))) diff --git a/ECOSYSTEM.scm b/ECOSYSTEM.scm index 7657d1e..3222673 100644 --- a/ECOSYSTEM.scm +++ b/ECOSYSTEM.scm @@ -3,18 +3,38 @@ ;; ECOSYSTEM.scm — eclexia (ecosystem - (version "1.0.0") + (version "1.1.0") (name "eclexia") - (type "project") - (purpose "Project in the hyperpolymath ecosystem") + (type "language") + (purpose "Energy-aware programming language with dimensional types and shadow price optimization") (position-in-ecosystem - "Part of hyperpolymath ecosystem. Follows RSR guidelines.") + "Canonical upstream for Eclexia language. Part of hyperpolymath ecosystem. Follows RSR guidelines.") + + (anchor-system + (authority "upstream-canonical") + (anchor-file "./ANCHOR.scm") + (machine-read-dir "./.machine_read/") + (satellite-policy "Downstream repos must pin to this upstream and cannot redefine semantics.")) (related-projects (project (name "rhodium-standard-repositories") (url "https://github.com/hyperpolymath/rhodium-standard-repositories") - (relationship "standard"))) + (relationship "standard")) + (project (name "eclexia-playground") + (url "https://github.com/hyperpolymath/eclexia-playground") + (relationship "downstream-satellite")) + (project (name "eclexia-vscode") + (url "https://github.com/hyperpolymath/eclexia-vscode") + (relationship "downstream-tooling")) + (project (name "eclexia-docs") + (url "https://github.com/hyperpolymath/eclexia-docs") + (relationship "downstream-documentation"))) + + (what-this-is + "Authoritative source for Eclexia language semantics, specification, and compiler implementation.") - (what-this-is "Project in the hyperpolymath ecosystem") - (what-this-is-not "- NOT exempt from RSR compliance")) + (what-this-is-not + "- NOT exempt from RSR compliance" + "- NOT a playground or demo repository (see eclexia-playground)" + "- NOT where IDE plugins live (see eclexia-vscode)"))