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

[hyperpolymath]

Summary

Documentation refresh + full RSR/standards compliance + root cleanup, in the order requested:

1. README.adoc → current status
2. EXPLAINME.adoc
3. RSR-template-repo + standards compliance — docs sorted for humans and bots
4. Root cleared of cruft; machine-readable artefacts relocated; adoc-first

No source code is touched — this is docs / metadata / config / cruft only. The ExUnit suite remains green.

1 — README.adoc

• Version Standard Candidate 1.0 → 0.9.0 (matches mix.exs).
• Corrected the probabilistic-types claim: they are runtime-represented, with static checking on the roadmap — the old table said "statically checked types", which EXPLAINME contradicts.
• Added the reflexion design layer to the IP/claims table.
• Replaced the aspirational ArangoDB / Virtuoso and Salt tooling rows (Salt is Python — banned) with the consensus + formal-verification tooling that actually ships.

2 — EXPLAINME.adoc

• New Reflexion receipts section (façade Phronesis.Reflexion.review/2, the REPORT-adequacy anchor example, JEG / equivalence / hash-chained ledger), all path-verified.
• Wired the reflexion modules + docs/REFLEXION.adoc into the file map.

3 — RSR + standards compliance (humans and bots)

• .machine_readable/ai/ — Cursor / Cline / Windsurf rules + AI.a2ml + README index, tailored to Phronesis (real languages, MPL-2.0 code + CC-BY-SA-4.0 docs split, no placeholders, no banned-language references).
• .github/copilot-instructions.md — moved from the repo root (where Copilot never read it) and destaled (dropped ReScript, JavaScript → AffineScript, npm/yarn/pnpm → Deno, removed the self-contradictory "GitLab CI preferred" row).
• AUDIT.adoc — honest claims-vs-reality ledger (what is real vs scaffold/roadmap).
• .machine_readable/6a2/anchors/ANCHOR.a2ml — repo identity + golden path (just deps/build/test).
• .machine_readable/root-allow.txt — canonical root allowlist.
• 0-AI-MANIFEST.a2ml — point AI/bot instructions at .machine_readable/ai/ (the .bot_directives/ dir never existed); refresh the structure tree.
• Stale cross-reference sweep across academic/, wiki/, IMPLEMENTATION-ROADMAP, GOVERNANCE, .claude/CLAUDE.md: proof-file refs .md→.adoc; licence misstatements (Apache/MIT and AGPL → MPL-2.0 + CC-BY-SA-4.0); version banners 0.1.0→0.9.0; .scm→.a2ml; Guile state-file row → A2ML; removed the SaltStack-Python exception.

4 — Root cleanup

• Removed cruft: the committed 1.7 MB phronesis escript (now gitignored), ANALYSIS-COMPLETE.adoc (session artefact), the redundant root SPEC.core.a2ml symlink.
• Relocated the estate *.toml configs to .machine_readable/configs/.
• Moved internal status/design docs to docs/ (LSP summary, testing report, test-needs, toolchain wishlist, wokelang comparison) and orphaned root demo scripts to examples/.
• adoc-first: converted the remaining estate .md docs to .adoc (CC-BY-SA-4.0) via pandoc — docs/CONSENSUS, docs/safety_proofs, docs/tech-debt-2026-05-26, deploy/DEPLOYMENT, spec/system-specs, editors/vscode/README, syntax/README. Only GitHub/tool-required Markdown remains.

The root is now reduced to 28 files, every one accounted for in root-allow.txt.

Metadata

• STATE.a2ml: marked the suite green (last-result warn → pass), dropped the resolved test-failure blocker, bumped dates.

Note for review

The 7 converted docs were MPL-2.0 Markdown; their new .adoc files carry CC-BY-SA-4.0, consistent with the owner-authorised documentation-licence policy already applied to the sibling narrative docs. Flag if any of those should remain MPL-2.0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AqMopxUsgu78rg5fhWBUkk

---

Generated by Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 8 issues detected

Severity	Count
🔴 Critical	0
🟠 High	3
🟡 Medium	5

View findings

[
  {
    "reason": "binary_to_term without :safe option -- deserialization attack (1 occurrences, CWE-502)",
    "type": "elixir_send_unsanitised",
    "file": "/home/runner/work/phronesis/phronesis/lib/phronesis/compiler.ex",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  },
  {
    "reason": "Nominal-only SAST in phronesis: codeql.yml language matrix contains no language present in the repo and lacks `actions`, so CodeQL records zero results on every commit. Remediation: set the CodeQL matrix to `language: actions`.",
    "type": "StaticAnalysis",
    "file": "/home/runner/work/phronesis/phronesis",
    "action": "auto_fix",
    "rule_module": "scorecard",
    "severity": "medium",
    "remediation": "Add CodeQL or equivalent SAST workflow.",
    "scorecard_check": "SAST"
  },
  {
    "reason": "Repository has 6 non-main remote branch(es). Policy: single main branch only.",
    "type": "GS007",
    "file": ".",
    "action": "delete_remote_branches",
    "rule_module": "git_state",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/structural_drift/SD007 -- Hypatia structural_drift: SD007 -- 8 day(s) old",
    "type": "CSA001",
    "file": ".claude/CLAUDE.md",
    "action": "review",
    "rule_module": "code_scanning_alerts",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/structural_drift/SD007 -- Hypatia structural_drift: SD007 -- 8 day(s) old",
    "type": "CSA001",
    "file": ".claude/CLAUDE.md",
    "action": "review",
    "rule_module": "code_scanning_alerts",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/structural_drift/SD007 -- Hypatia structural_drift: SD007 -- 8 day(s) old",
    "type": "CSA001",
    "file": ".claude/CLAUDE.md",
    "action": "review",
    "rule_module": "code_scanning_alerts",
    "severity": "medium"
  },
  {
    "reason": "Code scanning (Hypatia): hypatia/code_safety/elixir_send_unsanitised -- Hypatia code_safety: elixir_send_unsanitised -- 8 day(s) old [STALE]",
    "type": "CSA001",
    "file": "lib/phronesis/compiler.ex",
    "action": "escalate",
    "rule_module": "code_scanning_alerts",
    "severity": "high"
  },
  {
    "reason": "Code-scanning alert hypatia/code_safety/elixir_send_unsanitised (high) at lib/phronesis/compiler.ex is 8 days old (threshold: 7 days) -- overdue for remediation",
    "type": "CSA003",
    "file": "lib/phronesis/compiler.ex",
    "action": "escalate",
    "rule_module": "code_scanning_alerts",
    "severity": "high"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence