docs: refresh README/EXPLAINME, RSR + bot-doc compliance, clean root

.claude/CLAUDE.md

@@ -32,9 +32,8 @@ RSR layout — see https://github.com/hyperpolymath/standards):
 | **Gleam** | Backend services | Runs on BEAM or compiles to JS |
 | **Bash/POSIX Shell** | Scripts, automation | Keep minimal |
 | **JavaScript** | Only where AffineScript cannot | MCP protocol glue, Deno APIs |
-| **Python** | SaltStack only | No other Python permitted |
 | **Nickel** | Configuration language | For complex configs |
-| **Guile Scheme** | State/meta files | STATE.scm, META.scm, ECOSYSTEM.scm |
+| **A2ML** | State/meta files | STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml (TOML-like) |
 | **Julia** | Batch scripts, data processing | Per RSR |
 | **OCaml** | AffineScript compiler | Language-specific |
 | **Ada** | Safety-critical systems | Where required |
@@ -71,7 +70,7 @@ Both are FOSS with independent governance (no Big Tech).
 2. **No package.json - use deno.json deps** - Use deno.json imports
 3. **No node_modules in production** - Deno caches deps automatically
 4. **No Go code** - Use Rust instead
-5. **Python only for SaltStack** - All other Python must be rewritten
+5. **No Python** - Python is fully banned (no exceptions); rewrite in AffineScript/Rust
 6. **No Kotlin/Swift for mobile** - Use Tauri 2.0+ or Dioxus
 
 ### Package Management

copilot-instructions.md → .github/copilot-instructions.md

@@ -13,15 +13,15 @@ When reviewing code in this repository, apply these standards strictly.
 3. Ada/SPARK — safety-critical, formal verification
 4. Haskell — pure functional, type-heavy domains
 5. Elixir — concurrent, distributed, fault-tolerant systems
-6. ReScript — frontend when JS interop needed
+6. AffineScript — application code where a typed web/Deno target is needed
 7. Chapel — parallel computing, HPC workloads
 8. Julia — numerical computing, scientific applications
 
 **Avoid:**
 - C — use Zig instead
 - C++ — use Zig or Rust instead
-- Python — reject unless interfacing with Python-only libraries
-- JavaScript — use ReScript or TypeScript instead
+- Python — reject (banned across the estate)
+- JavaScript — use AffineScript instead
 - Shell scripts over 50 lines — rewrite in a proper language
 
 **Flag for justification:**
@@ -80,8 +80,7 @@ When reviewing code in this repository, apply these standards strictly.
 |-----------|-----------|
 | Docker | Podman |
 | Makefile | Justfile |
-| GitHub Actions self-reference | GitLab CI preferred for personal projects |
-| npm/yarn | pnpm (if JS unavoidable) |
+| npm/yarn/pnpm | Deno |
 | pip/poetry | Reject (avoid Python) |
 
 **Build files:**

.gitignore

@@ -23,3 +23,6 @@ Thumbs.db
 # Temporary
 *.tmp
 *.log
+
+# Built escript binary (mix escript.build)
+/phronesis

.machine_readable/6a2/STATE.a2ml

@@ -5,9 +5,9 @@
 [metadata]
 project = "phronesis"
 version = "0.9.0"
-last-updated = "2026-06-18"
+last-updated = "2026-06-20"
 status = "active"
-session = "reflexion design layer + docs/metadata/licence sync — 2026-06-18"
+session = "docs refresh + RSR/bot-doc compliance + root cleanup — 2026-06-20"
 
 [project-context]
 name = "Phronesis"
@@ -32,18 +32,16 @@ milestones = [
 
 [blockers-and-issues]
 issues = [
-  { id = "pre-existing-test-failures", note = "DebuggerTest (Trace.merge/2 undefined; State.variables), DocGeneratorTest, IncrementalLexerTest, ConformanceTest 04_boolean_logic — predate the reflexion work" },
   { id = "compiler-backend", note = "Rust to WASM codegen is still AST scaffolding only" },
 ]
 
 [critical-next-actions]
 actions = [
-  "Repair pre-existing test failures (Trace.merge/2 in debugger; State.variables field)",
   "Wire reflexion claim ingest for the compiler, formal/proof, and benchmark sources",
   "Advance the Rust to WASM production compiler beyond AST scaffolding",
   "Add Idris2 ABI definitions and the Zig FFI layer",
 ]
 
 [maintenance-status]
-last-run-utc = "2026-06-18T00:00:00Z"
-last-result = "warn"  # unknown | pass | warn | fail  (reflexion suite green; pre-existing failures remain)
+last-run-utc = "2026-06-20T00:00:00Z"
+last-result = "pass"  # unknown | pass | warn | fail  (full ExUnit suite green; consensus/Raft cases skipped pending :ra)

.machine_readable/6a2/anchors/ANCHOR.a2ml

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# ANCHOR.a2ml - authoritative anchor for the phronesis repository.
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-06-20"
+
+[anchor]
+schema = "hyperpolymath.anchor/1"
+repo = "hyperpolymath/phronesis"
+authority = "upstream-canonical"
+
+purpose = [
+  "Define canonical semantics and policy boundaries for Phronesis.",
+  "Declare what downstream/satellite repos can extend but not redefine.",
+  "Provide a stable golden path and invariant contract for release readiness.",
+]
+
+[identity]
+project = "phronesis"
+kind = "language"
+one-sentence = "A neuro-symbolic, provably-safe language for agentic ethical reasoning on the BEAM."
+domain = "ethical AI / policy languages / formal verification"
+
+[semantic-authority]
+policy = "canonical"
+owns = [
+  "Phronesis language semantics and specification (spec/, formal/)",
+  "Invariant definitions and contractiles (.machine_readable/contractiles/)",
+  "Reference implementation behaviour (lib/phronesis/)",
+]
+
+[implementation-policy]
+# Languages actually used in this repo, plus estate-allowed neighbours.
+allowed = ["Elixir", "Rust", "Idris2", "Agda", "Zig", "TLA+", "AsciiDoc", "Just", "Guix Scheme"]
+forbidden = ["Python", "Go", "TypeScript", "ReScript", "V-lang", "Node.js", "npm"]
+
+[golden-path]
+smoke-test-command = [
+  "just deps",
+  "just build",
+  "just test",
+]
+success-criteria = [
+  "Full ExUnit suite passes (consensus/Raft cases skipped — see docs/TESTING-REPORT.adoc)",
+  "just build is clean under --warnings-as-errors",
+  "No unresolved critical security findings",
+]
+
+[satellite-policy]
+must-pin-upstream = true
+must-declare-authority = true
+must-have-anchor = true
+must-have-golden-path = true
+
+[semantic-authority-files]
+language-spec = "spec/grammar.ebnf"
+operational-semantics = ".machine_readable/SPEC.core.a2ml"
+formal-consensus-spec = "formal/PhronesisConsensus.tla"
+proof-corpus = "academic/proofs/"
+claims-vs-reality = "AUDIT.adoc"

.machine_readable/ai/.clinerules

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# Phronesis — Cline AI rules. Kept in sync with .cursorrules / .windsurfrules.
+# Authoritative AI instructions: 0-AI-MANIFEST.a2ml (root) and .claude/CLAUDE.md.
+
+# STARTUP (read in this order)
+# 1. 0-AI-MANIFEST.a2ml          — canonical file locations + invariants
+# 2. .machine_readable/6a2/anchors/ANCHOR.a2ml — identity + golden path
+# 3. .machine_readable/6a2/STATE.a2ml          — current status + blockers
+# 4. .claude/CLAUDE.md           — full language / licence policy
+
+# LICENSE (per-file, REUSE-style; SPDX header required on EVERY file)
+# Code (*.ex/*.exs/*.rs/*.idr/*.tla/*.zig, mix.exs, Justfile, Mustfile, *.a2ml,
+#   Guix *.scm): MPL-2.0.
+# Documentation (narrative *.adoc, wiki/, academic/ prose): CC-BY-SA-4.0.
+# GitHub community files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
+#   CHANGELOG.md): MPL-2.0.
+# Never AGPL-3.0. Copyright: Jonathan D.A. Jewell (hyperpolymath)
+#   <j.d.a.jewell@open.ac.uk>.
+
+# STATE FILES (.machine_readable/6a2/ ONLY)
+# The 6 core A2ML files — STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK —
+# live in .machine_readable/6a2/ and NOWHERE else. Never create *.a2ml metadata
+# in the repo root; the root copy is always treated as stale drift.
+
+# LANGUAGES (this repo)
+# Reference implementation: Elixir/BEAM (lib/phronesis/).
+# Production compiler: Rust -> WASM (compiler/phronesis-ast, compiler/phronesis-wasm).
+# Formal: TLA+ (formal/); proof corpus in academic/ (lattice/order/type theory).
+# Estate-allowed elsewhere: AffineScript, Rust/SPARK, Zig, Idris2, Agda, Gleam, Elixir.
+# BANNED: Python, Go, TypeScript, ReScript, V-lang, Java/Kotlin/Swift, Node.js, npm.
+
+# BANNED UNSAFE PATTERNS
+# Elixir: no bare `raise` without a rescue strategy; use {:ok,_}/{:error,_} tuples;
+#   supervisors need explicit restart strategies.
+# Rust: no `transmute` (unless FFI with a // SAFETY: comment); no `.unwrap()`/
+#   `.expect()`/`panic!` in library code without justification.
+# Idris2: no believe_me/assert_total/assert_smaller. Coq: no Admitted. Lean: no sorry.
+
+# CONTAINERS
+# Runtime: Podman (never Docker). File: Containerfile (never Dockerfile).
+
+# BUILD SYSTEM
+# Use `just` (Justfile) for build/test/lint/format. No Makefiles (use Mustfile/
+# Justfile). `just test` is the definitive correctness gate.
+
+# DOCUMENTATION
+# AsciiDoc (.adoc) for all docs. Markdown only for GitHub-required files
+# (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md, .github/**).
+# README is .adoc here.
+
+# CODE STYLE
+# British English in user-facing strings and docs. Descriptive names. No
+# commented-out code (git has history). Must pass `mix format` / `rustfmt`.

.machine_readable/ai/.cursorrules

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# Phronesis — Cursor AI rules. Kept in sync with .clinerules / .windsurfrules.
+# Authoritative AI instructions: 0-AI-MANIFEST.a2ml (root) and .claude/CLAUDE.md.
+
+# STARTUP (read in this order)
+# 1. 0-AI-MANIFEST.a2ml          — canonical file locations + invariants
+# 2. .machine_readable/6a2/anchors/ANCHOR.a2ml — identity + golden path
+# 3. .machine_readable/6a2/STATE.a2ml          — current status + blockers
+# 4. .claude/CLAUDE.md           — full language / licence policy
+
+# LICENSE (per-file, REUSE-style; SPDX header required on EVERY file)
+# Code (*.ex/*.exs/*.rs/*.idr/*.tla/*.zig, mix.exs, Justfile, Mustfile, *.a2ml,
+#   Guix *.scm): MPL-2.0.
+# Documentation (narrative *.adoc, wiki/, academic/ prose): CC-BY-SA-4.0.
+# GitHub community files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
+#   CHANGELOG.md): MPL-2.0.
+# Never AGPL-3.0. Copyright: Jonathan D.A. Jewell (hyperpolymath)
+#   <j.d.a.jewell@open.ac.uk>.
+
+# STATE FILES (.machine_readable/6a2/ ONLY)
+# The 6 core A2ML files — STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK —
+# live in .machine_readable/6a2/ and NOWHERE else. Never create *.a2ml metadata
+# in the repo root; the root copy is always treated as stale drift.
+
+# LANGUAGES (this repo)
+# Reference implementation: Elixir/BEAM (lib/phronesis/).
+# Production compiler: Rust -> WASM (compiler/phronesis-ast, compiler/phronesis-wasm).
+# Formal: TLA+ (formal/); proof corpus in academic/ (lattice/order/type theory).
+# Estate-allowed elsewhere: AffineScript, Rust/SPARK, Zig, Idris2, Agda, Gleam, Elixir.
+# BANNED: Python, Go, TypeScript, ReScript, V-lang, Java/Kotlin/Swift, Node.js, npm.
+
+# BANNED UNSAFE PATTERNS
+# Elixir: no bare `raise` without a rescue strategy; use {:ok,_}/{:error,_} tuples;
+#   supervisors need explicit restart strategies.
+# Rust: no `transmute` (unless FFI with a // SAFETY: comment); no `.unwrap()`/
+#   `.expect()`/`panic!` in library code without justification.
+# Idris2: no believe_me/assert_total/assert_smaller. Coq: no Admitted. Lean: no sorry.
+
+# CONTAINERS
+# Runtime: Podman (never Docker). File: Containerfile (never Dockerfile).
+
+# BUILD SYSTEM
+# Use `just` (Justfile) for build/test/lint/format. No Makefiles (use Mustfile/
+# Justfile). `just test` is the definitive correctness gate.
+
+# DOCUMENTATION
+# AsciiDoc (.adoc) for all docs. Markdown only for GitHub-required files
+# (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md, .github/**).
+# README is .adoc here.
+
+# CODE STYLE
+# British English in user-facing strings and docs. Descriptive names. No
+# commented-out code (git has history). Must pass `mix format` / `rustfmt`.

.machine_readable/ai/.windsurfrules

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# Phronesis — Windsurf AI rules. Kept in sync with .cursorrules / .clinerules.
+# Authoritative AI instructions: 0-AI-MANIFEST.a2ml (root) and .claude/CLAUDE.md.
+
+# STARTUP (read in this order)
+# 1. 0-AI-MANIFEST.a2ml          — canonical file locations + invariants
+# 2. .machine_readable/6a2/anchors/ANCHOR.a2ml — identity + golden path
+# 3. .machine_readable/6a2/STATE.a2ml          — current status + blockers
+# 4. .claude/CLAUDE.md           — full language / licence policy
+
+# LICENSE (per-file, REUSE-style; SPDX header required on EVERY file)
+# Code (*.ex/*.exs/*.rs/*.idr/*.tla/*.zig, mix.exs, Justfile, Mustfile, *.a2ml,
+#   Guix *.scm): MPL-2.0.
+# Documentation (narrative *.adoc, wiki/, academic/ prose): CC-BY-SA-4.0.
+# GitHub community files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
+#   CHANGELOG.md): MPL-2.0.
+# Never AGPL-3.0. Copyright: Jonathan D.A. Jewell (hyperpolymath)
+#   <j.d.a.jewell@open.ac.uk>.
+
+# STATE FILES (.machine_readable/6a2/ ONLY)
+# The 6 core A2ML files — STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK —
+# live in .machine_readable/6a2/ and NOWHERE else. Never create *.a2ml metadata
+# in the repo root; the root copy is always treated as stale drift.
+
+# LANGUAGES (this repo)
+# Reference implementation: Elixir/BEAM (lib/phronesis/).
+# Production compiler: Rust -> WASM (compiler/phronesis-ast, compiler/phronesis-wasm).
+# Formal: TLA+ (formal/); proof corpus in academic/ (lattice/order/type theory).
+# Estate-allowed elsewhere: AffineScript, Rust/SPARK, Zig, Idris2, Agda, Gleam, Elixir.
+# BANNED: Python, Go, TypeScript, ReScript, V-lang, Java/Kotlin/Swift, Node.js, npm.
+
+# BANNED UNSAFE PATTERNS
+# Elixir: no bare `raise` without a rescue strategy; use {:ok,_}/{:error,_} tuples;
+#   supervisors need explicit restart strategies.
+# Rust: no `transmute` (unless FFI with a // SAFETY: comment); no `.unwrap()`/
+#   `.expect()`/`panic!` in library code without justification.
+# Idris2: no believe_me/assert_total/assert_smaller. Coq: no Admitted. Lean: no sorry.
+
+# CONTAINERS
+# Runtime: Podman (never Docker). File: Containerfile (never Dockerfile).
+
+# BUILD SYSTEM
+# Use `just` (Justfile) for build/test/lint/format. No Makefiles (use Mustfile/
+# Justfile). `just test` is the definitive correctness gate.
+
+# DOCUMENTATION
+# AsciiDoc (.adoc) for all docs. Markdown only for GitHub-required files
+# (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md, .github/**).
+# README is .adoc here.
+
+# CODE STYLE
+# British English in user-facing strings and docs. Descriptive names. No
+# commented-out code (git has history). Must pass `mix format` / `rustfmt`.

.machine_readable/ai/AI.a2ml

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# AI.a2ml — machine-readable AI-assistant directives for Phronesis.
+
+[repository-focus]
+name = "phronesis"
+kind = "language"
+one-sentence = "A neuro-symbolic, provably-safe language for agentic ethical reasoning on the BEAM."
+authority = ".machine_readable/ is authoritative; the 6 core A2ML files live in .machine_readable/6a2/ only."
+
+[read-order]
+1 = "0-AI-MANIFEST.a2ml"
+2 = ".machine_readable/6a2/anchors/ANCHOR.a2ml"
+3 = ".machine_readable/6a2/STATE.a2ml"
+4 = ".machine_readable/6a2/META.a2ml"
+5 = ".claude/CLAUDE.md"
+
+[workflow]
+step-1 = "Inspect .machine_readable/6a2/STATE.a2ml for blockers and next actions."
+step-2 = "Respect constraints in .machine_readable/6a2/AGENTIC.a2ml when changing tooling."
+step-3 = "Run `just test` (the correctness gate) before claiming a change is done."
+step-4 = "After edits, update STATE.a2ml outcomes and commit with a concise, imperative message."
+
+[languages]
+reference-implementation = "Elixir/BEAM (lib/phronesis/)"
+compiler = "Rust -> WASM (compiler/)"
+formal = "TLA+ (formal/); proof corpus in academic/"
+banned = ["Python", "Go", "TypeScript", "ReScript", "V-lang", "Java", "Kotlin", "Swift", "Node.js", "npm"]
+
+[licence]
+code = "MPL-2.0"
+documentation = "CC-BY-SA-4.0"
+never = "AGPL-3.0"
+rule = "SPDX-License-Identifier header required on every file."
+
+[delivery-promises]
+report-changes-to = ["STATE.a2ml", ".machine_readable/contractiles/", ".machine_readable/ai/"]
+keep-in-sync = "Update this file if repository governance changes."

.machine_readable/ai/README.adoc

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+= AI Guidance Directory (`.machine_readable/ai/`)
+:toc:
+
+Centralised, tool-specific AI-assistant instructions for Phronesis. Keeping them
+here (rather than scattered at the repo root) is the RSR convention.
+
+== Contents
+
+[cols="1,3"]
+|===
+| File | Purpose
+
+| `.cursorrules`   | Rules for Cursor.
+| `.clinerules`    | Rules for Cline.
+| `.windsurfrules` | Rules for Windsurf.
+| `AI.a2ml`        | Machine-readable workflow + repository-focus directives.
+| `README.adoc`    | This index.
+|===
+
+The three `.*rules` files carry identical guidance with a tool-specific header
+line; keep them in sync when one changes.
+
+== Canonical AI authority (outside this directory)
+
+* `0-AI-MANIFEST.a2ml` (repo root) — the universal entry point: canonical file
+  locations and invariants.
+* `.claude/CLAUDE.md` — full language and licence policy for Claude.
+* `.github/copilot-instructions.md` — GitHub Copilot code-review conventions.
+
+== Recommended machine read order
+
+. `0-AI-MANIFEST.a2ml`
+. `.machine_readable/6a2/anchors/ANCHOR.a2ml` — identity + golden path
+. `.machine_readable/6a2/STATE.a2ml` — current status + blockers
+. `.machine_readable/6a2/META.a2ml` — architecture decisions
+. `.claude/CLAUDE.md` — language / licence policy