feat: add anchor configuration system for upstream/satellite governance

.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 <recipe>` (local) or `must <transition>` (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."))))))

.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"))))

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

.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)")))))