feat: add machine-readable anchor and spec files

.machine_read/ANCHOR.wokelang.scm

@@ -0,0 +1,77 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; SPDX-FileCopyrightText: 2026 Hyperpolymath
+;;
+;; Machine-readable anchor for WokeLang
+;; Schema: hyperpolymath.anchor/1
+
+(define anchor
+  '((schema . "hyperpolymath.anchor/1")
+    (repo . "hyperpolymath/wokelang")
+    (date . "2026-01-01")
+    (authority . "repo-superintendent")
+    (purpose
+      . ("Authoritative source for WokeLang language specification."
+         "Human-centered programming language: empathy, consent, and gratitude as first-class concepts."
+         "All downstream implementations defer to this repo for semantics and grammar."))
+
+    (identity
+      . ((project . "WokeLang")
+         (kind . "language-core")
+         (one-sentence . "A human-centered programming language with empathy, consent, and gratitude.")
+         (upstream . #f)))  ; This IS the upstream
+
+    (semantic-anchor
+      . ((policy . "authoritative")
+         (downstream-repos
+           . ("hyperpolymath/wokelang-playground"
+              "hyperpolymath/wokelang-vscode"
+              "hyperpolymath/wokelang-lsp"))
+         (authority-scope
+           . ("EBNF grammar specification (docs/grammar.ebnf)"
+              "Language semantics and type system"
+              "Compiler implementation (src/)"
+              "Standard library definitions"
+              "Consent system semantics"
+              "Gratitude block semantics"
+              "Emote tag semantics"))))
+
+    (implementation-policy
+      . ((allowed . ("Rust" "OCaml" "Scheme" "Shell" "Just" "Markdown" "AsciiDoc" "Lean" "Coq"))
+         (primary . ("Rust" "OCaml"))
+         (quarantined . ("JavaScript without ReScript" "TypeScript"))
+         (forbidden
+           . ("Competing language specification"
+              "Breaking semantic changes without RFC"
+              "Removal of consent gates"
+              "Removal of gratitude blocks"))))
+
+    (golden-path
+      . ((smoke-test-command
+           . ("cargo test"
+              "cargo run -- examples/hello.woke"
+              "cargo run -- repl"))
+         (success-criteria
+           . ("All core tests pass."
+              "REPL evaluates basic expressions."
+              "Example programs run without error."
+              "WASM compilation produces valid modules."))))
+
+    (mandatory-files
+      . ("./.machine_read/LLM_SUPERINTENDENT.scm"
+         "./.machine_read/ROADMAP.f0.scm"
+         "./.machine_read/SPEC.core.scm"
+         "./.machine_read/AUTHORITY_STACK.mustfile-nickel.scm"))
+
+    (first-pass-directives
+      . ("Ensure grammar.ebnf is canonical."
+         "Verify all semantic constructs documented in proofs/."
+         "Validate consent/gratitude/emote semantics are formally specified."))
+
+    (rsr . ((target-tier . "silver-now")
+            (current-achievements
+              . ("EBNF grammar specification"
+                 "Tree-walking interpreter"
+                 "WASM compilation"
+                 "Formal proofs (Lean, Coq)"
+                 "Security validation hooks"))
+            (upgrade-path . "gold-after-v0.3 (full type system + native compilation)")))))

.machine_read/AUTHORITY_STACK.mustfile-nickel.scm

@@ -0,0 +1,47 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; SPDX-FileCopyrightText: 2026 Hyperpolymath
+;;
+;; AUTHORITY_STACK.mustfile-nickel.scm
+;; Shared drop for hyperpolymath repos: defines task routing + config authority.
+
+(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,95 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; SPDX-FileCopyrightText: 2026 Hyperpolymath
+;;
+;; LLM Superintendent Instructions for WokeLang
+;; This file provides guidance for AI assistants working on this codebase.
+
+(define llm-superintendent
+  '((schema . "hyperpolymath.llm-superintendent/1")
+    (repo . "hyperpolymath/wokelang")
+    (last-updated . "2026-01-01")
+
+    (identity
+      . ((project . "WokeLang")
+         (role . "authoritative-upstream")
+         (description
+           . "WokeLang is a human-centered programming language emphasizing empathy, consent, and gratitude. This is the authoritative implementation.")))
+
+    (scope-boundaries
+      . ((in-scope
+           . ("Language grammar and parsing (src/lexer/, src/parser/)"
+              "Abstract syntax tree definitions"
+              "Type system implementation"
+              "Interpreter and evaluation"
+              "WASM compilation target"
+              "Standard library (lib/)"
+              "FFI bindings (include/, zig/)"
+              "Formal proofs and verification (docs/proofs/)"
+              "Documentation and wiki (docs/)"
+              "Examples (examples/)"
+              "CI/CD and security workflows (.github/)"))
+         (out-of-scope
+           . ("Playground UX (belongs in wokelang-playground)"
+              "Editor extensions (separate repos)"
+              "Package registry infrastructure"
+              "Third-party integrations not covered by FFI"))))
+
+    (language-policy
+      . ((primary-languages . ("Rust" "OCaml"))
+         (documentation . ("Markdown" "AsciiDoc"))
+         (proofs . ("Lean" "Coq"))
+         (config . ("TOML" "Scheme"))
+         (forbidden . ("TypeScript" "Go" "Python-outside-SaltStack"))))
+
+    (semantic-invariants
+      . ((consent-gates
+           . "All operations that are 'sensitive' (file I/O, network, env) MUST use consent gates. The 'only if okay' construct is not optional sugar.")
+         (gratitude-blocks
+           . "'thanks to' blocks are semantically meaningful and preserved in AST. They are not comments.")
+         (emote-tags
+           . "@feeling annotations are part of the type system and affect compilation.")
+         (units
+           . "'measured in' provides compile-time unit checking. Unit mismatches are errors, not warnings.")))
+
+    (contribution-rules
+      . ((before-changes
+           . ("Read docs/grammar.ebnf for syntax decisions"
+              "Check docs/proofs/ for semantic guarantees"
+              "Run 'cargo test' to verify baseline"))
+         (when-changing-grammar
+           . ("Update docs/grammar.ebnf first"
+              "Update parser to match"
+              "Add test cases for new syntax"
+              "Update formal semantics if applicable"))
+         (when-adding-features
+           . ("Consider consent implications"
+              "Preserve human-centered design philosophy"
+              "Add documentation alongside code"
+              "Add example programs demonstrating feature"))))
+
+    (critical-files
+      . (("docs/grammar.ebnf" . "Canonical EBNF grammar - all parsing decisions derive from this")
+         ("src/parser/" . "Parser implementation - must match grammar.ebnf")
+         ("src/vm.rs" . "Virtual machine - core execution semantics")
+         ("docs/proofs/formal-semantics/" . "Formal specifications - semantic truth source")
+         ("docs/proofs/type-theory/" . "Type system proofs")
+         ("examples/" . "Reference programs - used for testing and documentation")))
+
+    (testing-requirements
+      . ((unit-tests . "cargo test")
+         (examples . "Run all .woke files in examples/")
+         (proofs . "Lean/Coq proofs in docs/proofs/verification/")))
+
+    (security-notes
+      . ((pre-commit-hooks . "hooks/ contains validation scripts")
+         (spdx-required . "All source files need SPDX headers")
+         (sha-pins . "Dependencies must be SHA-pinned")
+         (no-secrets . "Never commit credentials or API keys")))
+
+    (communication-style
+      . ((error-messages
+           . "WokeLang error messages are kind and constructive. They explain what went wrong, why it matters, and suggest fixes.")
+         (documentation
+           . "Documentation uses welcoming, accessible language. Technical accuracy does not require hostility.")
+         (code-comments
+           . "Comments explain intent, not mechanics. 'This ensures user consent before file deletion' not 'deletes file'.")))))

.machine_read/ROADMAP.f0.scm

@@ -0,0 +1,123 @@
+;; SPDX-License-Identifier: AGPL-3.0-or-later
+;; SPDX-FileCopyrightText: 2026 Hyperpolymath
+;;
+;; Machine-readable roadmap for WokeLang
+;; f0 = foundation milestone (initial machine-readable spec)
+
+(define roadmap
+  '((schema . "hyperpolymath.roadmap/1")
+    (repo . "hyperpolymath/wokelang")
+    (version . "f0")
+    (last-updated . "2026-01-01")
+
+    (current-milestone
+      . ((name . "foundation")
+         (version . "0.1.x")
+         (status . "complete")
+         (features
+           . ((grammar . "complete")
+              (lexer . "complete")
+              (parser . "complete")
+              (ast . "complete")
+              (interpreter . "complete")
+              (cli . "complete")
+              (repl . "complete")
+              (wasm-basic . "complete")
+              (c-ffi . "complete")
+              (zig-ffi . "complete")))))
+
+    (milestones
+      . (((id . "m1")
+          (name . "language-completeness")
+          (target . "0.2.0")
+          (dependencies . ())
+          (features
+            . ((static-type-inference . "planned")
+               (generic-types . "planned")
+               (union-types . "planned")
+               (pattern-matching . "planned")
+               (module-system . "planned")
+               (result-types . "planned")
+               (error-propagation . "planned"))))
+
+         ((id . "m2")
+          (name . "concurrency-safety")
+          (target . "0.3.0")
+          (dependencies . ("m1"))
+          (features
+            . ((async-workers . "planned")
+               (message-passing . "planned")
+               (worker-pools . "planned")
+               (side-quests . "planned")
+               (capability-security . "planned")
+               (consent-persistence . "planned"))))
+
+         ((id . "m3")
+          (name . "standard-library")
+          (target . "0.4.0")
+          (dependencies . ("m2"))
+          (features
+            . ((std-io . "planned")
+               (std-net . "planned")
+               (std-json . "planned")
+               (std-time . "planned")
+               (std-math . "planned")
+               (std-units . "planned")
+               (consent-aware-modules . "planned"))))
+
+         ((id . "m4")
+          (name . "optimizing-compiler")
+          (target . "0.5.0")
+          (dependencies . ("m3"))
+          (features
+            . ((wasm-full . "planned")
+               (wasi-integration . "planned")
+               (llvm-backend . "planned")
+               (native-binaries . "planned")
+               (optimizations . "planned"))))
+
+         ((id . "m5")
+          (name . "tooling-ecosystem")
+          (target . "0.6.0-0.7.0")
+          (dependencies . ("m4"))
+          (features
+            . ((vscode-extension . "planned")
+               (lsp-server . "planned")
+               (tree-sitter . "planned")
+               (package-manager . "planned")
+               (test-framework . "planned")
+               (doc-generator . "planned"))))
+
+         ((id . "m6")
+          (name . "stable-release")
+          (target . "1.0.0")
+          (dependencies . ("m5"))
+          (features
+            . ((api-stability . "planned")
+               (semantic-versioning . "planned")
+               (migration-guides . "planned")
+               (lts-support . "planned"))))))
+
+    (completed-work
+      . ((grammar
+           . ((file . "docs/grammar.ebnf")
+              (status . "canonical")))
+         (proofs
+           . ((directory . "docs/proofs/")
+              (lean . "docs/proofs/verification/WokeLang.lean")
+              (coq . "docs/proofs/verification/WokeLang.v")
+              (status . "foundational")))
+         (examples
+           . ((directory . "examples/")
+              (count . 10)
+              (coverage . "basic-features")))))
+
+    (blocking-issues . ())
+
+    (downstream-impact
+      . ((wokelang-playground
+           . "Depends on stable grammar and error message format")
+         (wokelang-vscode
+           . "Depends on LSP implementation (m5)")
+         (wokelang-lsp
+           . "Depends on incremental parsing (m5)")))))