migrate: 6SCM → 6A2ML format family + atomicity protocol (AAP v1.0)

- All documentation updated: SCM → A2ML references throughout
- 0-AI-MANIFEST.a2ml: now references .a2ml files, includes AAP section
- .claude/CLAUDE.md: A2ML format family, not Guile Scheme
- A2ML templates: added [provenance] section and human-readable annotations
- standards-update: migrated .machine_readable/ from .scm to .a2ml
- standards-update/README.adoc: comprehensive SCM→A2ML terminology update,
  fixed dead links (meta-scm→meta-a2ml, etc.), added AAP reference
- Old .scm files archived in 6scm-archive/ for reference
- New: A2ML-ATOMICITY-PROTOCOL.adoc (AAP v1.0) — three-layer concurrent
  access protocol (provenance headers, advisory locks, OCC via git SHA)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.claude/CLAUDE.md

@@ -2,14 +2,14 @@
 
 ## Machine-Readable Artefacts
 
-Every Hyperpolymath repo must have `.machine_readable/` with these 6 SCM files:
+Every Hyperpolymath repo must have `.machine_readable/` with these 6 A2ML files:
 
-- `STATE.scm` - Current project state and progress
-- `META.scm` - Architecture decisions and development practices
-- `ECOSYSTEM.scm` - Position in the ecosystem and related projects
-- `AGENTIC.scm` - AI agent interaction patterns
-- `NEUROSYM.scm` - Neurosymbolic integration config
-- `PLAYBOOK.scm` - Operational runbook
+- `STATE.a2ml` - Current project state and progress
+- `META.a2ml` - Architecture decisions and development practices
+- `ECOSYSTEM.a2ml` - Position in the ecosystem and related projects
+- `AGENTIC.a2ml` - AI agent interaction patterns
+- `NEUROSYM.a2ml` - Neurosymbolic integration config
+- `PLAYBOOK.a2ml` - Operational runbook
 
 See: https://github.com/hyperpolymath/standards
 
@@ -30,7 +30,7 @@ See: https://github.com/hyperpolymath/standards
 | **Bash/POSIX Shell** | Scripts, automation | Keep minimal |
 | **JavaScript** | Only where ReScript cannot | MCP protocol glue, Deno APIs |
 | **Nickel** | Configuration language | For complex configs |
-| **Guile Scheme** | State/meta files | STATE.scm, META.scm, etc. |
+| **A2ML** | State/meta files | STATE.a2ml, META.a2ml, etc. (TOML-like format) |
 | **Julia** | Batch scripts, data processing | Per RSR |
 | **OCaml** | AffineScript compiler | Language-specific |
 | **Ada** | Safety-critical systems | Where required |

0-AI-MANIFEST.a2ml

@@ -1,4 +1,4 @@
-# ⚠️ STOP - CRITICAL READING REQUIRED
+# STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
 
@@ -13,13 +13,13 @@ This is the AI manifest for **standards**. It declares:
 
 ### Machine-Readable Metadata: `.machine_readable/` ONLY
 
-These 6 SCM files MUST exist in `.machine_readable/` directory ONLY:
-1. **STATE.scm** - Project state, progress, blockers
-2. **META.scm** - Architecture decisions, governance
-3. **ECOSYSTEM.scm** - Position in ecosystem, relationships
-4. **AGENTIC.scm** - AI agent interaction patterns
-5. **NEUROSYM.scm** - Neurosymbolic integration config
-6. **PLAYBOOK.scm** - Operational runbook
+These 6 A2ML files MUST exist in `.machine_readable/` directory ONLY:
+1. **STATE.a2ml** - Project state, progress, blockers
+2. **META.a2ml** - Architecture decisions, governance
+3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships
+4. **AGENTIC.a2ml** - AI agent interaction patterns
+5. **NEUROSYM.a2ml** - Neurosymbolic integration config
+6. **PLAYBOOK.a2ml** - Operational runbook
 
 **CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.
 
@@ -40,9 +40,9 @@ Bot-specific instructions for:
 
 ## CORE INVARIANTS
 
-1. **No SCM duplication** - Root must NOT contain STATE.scm, META.scm, etc.
+1. **No A2ML duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc.
 2. **Single source of truth** - `.machine_readable/` is authoritative
-3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
+3. **No stale metadata** - If root A2ML files exist, they are OUT OF DATE
 4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
 5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
 
@@ -57,24 +57,36 @@ standards/
 ├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
 ├── README.md                   # Project overview
 ├── [your source files]         # Main code
-├── .machine_readable/          # SCM files (6 files)
-│   ├── STATE.scm
-│   ├── META.scm
-│   ├── ECOSYSTEM.scm
-│   ├── AGENTIC.scm
-│   ├── NEUROSYM.scm
-│   └── PLAYBOOK.scm
+├── .machine_readable/          # A2ML files (6 files)
+│   ├── STATE.a2ml
+│   ├── META.a2ml
+│   ├── ECOSYSTEM.a2ml
+│   ├── AGENTIC.a2ml
+│   ├── NEUROSYM.a2ml
+│   └── PLAYBOOK.a2ml
 └── .bot_directives/            # Bot instructions
 ```
 
+## A2ML ATOMICITY PROTOCOL (AAP)
+
+When multiple agents or bots may be writing to A2ML files concurrently:
+
+1. **Read** the file and record `git-sha-at-read` in the `[provenance]` section
+2. **Lock** by creating `.machine_readable/.lock-<FILENAME>` (advisory)
+3. **Write** the updated file with new `[provenance]` metadata
+4. **Release** by removing the lock file
+5. **Conflict** — if `git-sha-at-read` does not match current HEAD, re-read and retry
+
+This prevents lost writes when multiple agents update state files simultaneously.
+
 ## SESSION STARTUP CHECKLIST
 
-✅ Read THIS file (0-AI-MANIFEST.a2ml) first
-✅ Understand canonical locations (.machine_readable/, .bot_directives/)
-✅ Know the invariants (no SCM duplication, etc.)
-✅ Check for MCP enforcement (if applicable)
-✅ Read `.machine_readable/STATE.scm` for current status
-✅ Read `.machine_readable/AGENTIC.scm` for interaction patterns
+- Read THIS file (0-AI-MANIFEST.a2ml) first
+- Understand canonical locations (.machine_readable/, .bot_directives/)
+- Know the invariants (no A2ML duplication, etc.)
+- Check for MCP enforcement (if applicable)
+- Read `.machine_readable/STATE.a2ml` for current status
+- Read `.machine_readable/AGENTIC.a2ml` for interaction patterns
 
 ## LIFECYCLE HOOKS
 
@@ -86,15 +98,15 @@ When starting a new session:
 2. Log session start (optional but recommended)
    - Format: `[YYYY-MM-DD HH:MM:SS] Session started: [agent-name]`
    - Location: `.machine_readable/session-log.txt`
-3. Read `.machine_readable/STATE.scm`
+3. Read `.machine_readable/STATE.a2ml`
 4. Check for blockers
 5. State understanding of canonical locations
 
 ### on-exit (Session End)
 
 When ending a session:
 
-1. Update `.machine_readable/STATE.scm` if changes made
+1. Update `.machine_readable/STATE.a2ml` if changes made
 2. Log session end (optional but recommended)
    - Format: `[YYYY-MM-DD HH:MM:SS] Session ended: [summary]`
    - Location: `.machine_readable/session-log.txt`
@@ -105,7 +117,7 @@ When ending a session:
 
 After reading this file, demonstrate understanding by stating:
 
-**"I have read the AI manifest. SCM files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files in the root directory."**
+**"I have read the AI manifest. A2ML files are located in `.machine_readable/` ONLY, bot directives in `.bot_directives/`, and I will not create duplicate files in the root directory."**
 
 ## META
 

a2ml-templates/AGENTIC.a2ml.template

@@ -1,25 +1,78 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # AGENTIC.a2ml - AI agent interaction patterns
 # Template from: https://github.com/hyperpolymath/standards
+#
+# HUMAN SUMMARY: This file configures how AI coding agents (Claude, etc.)
+# should behave when working on this project. It sets model preferences,
+# permitted tools, coding patterns, and language constraints. Think of it
+# as a "rules of engagement" file for AI assistants.
 
+# ── Agent Configuration ────────────────────────────────────────────────────
 [agentic-config]
+# version: Format version for this file.
 version = "1.0.0"
+
+# project: Must match the repo name exactly.
 project = "{{PROJECT_NAME}}"
 
+# ── Claude Code Settings ──────────────────────────────────────────────────
 [agentic-config.claude-code]
+# model: Which Claude model to use. Update when new models release.
 model = "claude-opus-4-5-20251101"
+
+# tools: Which Claude Code tools the agent may use.
 tools = ["read", "edit", "bash", "grep", "glob"]
+
+# permissions: Default file access level.
+#   read-all  — can read any file
+#   read-some — restricted to certain directories
 permissions = "read-all"
 
+# ── Coding Patterns ───────────────────────────────────────────────────────
 [agentic-config.patterns]
+# code-review: How thorough should code review be?
+#   thorough     — check every line, suggest improvements
+#   standard     — check for bugs and style issues
+#   quick        — only flag critical issues
 code-review = "thorough"
+
+# refactoring: How aggressive should refactoring be?
+#   conservative — minimal changes, preserve structure
+#   moderate     — improve when opportunity arises
+#   aggressive   — restructure freely for better design
 refactoring = "conservative"
+
+# testing: How much test coverage to aim for?
+#   comprehensive — test all paths, property-based tests
+#   standard      — test main paths and edge cases
+#   minimal       — test critical paths only
 testing = "comprehensive"
+
+# documentation: Where to put documentation?
+#   inline — comments in code
+#   adoc   — separate AsciiDoc files
+#   both   — inline + external docs
 documentation = "inline"
 
+# ── Language Constraints ──────────────────────────────────────────────────
 [agentic-config.constraints]
+# languages: Languages the agent is allowed to write in this project.
 languages = ["rescript", "rust", "gleam", "{{PRIMARY_LANGUAGE}}"]
+
+# banned: Languages the agent must NEVER use, even if asked.
 banned = ["typescript", "go", "python", "makefile"]
 
+# ── Project-Specific Overrides ────────────────────────────────────────────
 [agentic-config.project-specific]
-# Custom patterns for this project
+# Custom patterns for this project. Add any project-specific agent
+# instructions here (e.g., "always use Result types", "no unwrap()").
+
+# ── Provenance ─────────────────────────────────────────────────────────────
+[provenance]
+# Audit trail — updated automatically by agents/bots on every write.
+# Humans: you can ignore this section, but don't delete it.
+last-modified-by = "{{AGENT_ID}}"
+last-modified-at = "{{TIMESTAMP}}"
+last-session-id = ""
+git-sha-at-read = ""
+modification-summary = "Initial creation from template"

a2ml-templates/ECOSYSTEM.a2ml.template

@@ -1,27 +1,71 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # ECOSYSTEM.a2ml - Project ecosystem positioning
 # Template from: https://github.com/hyperpolymath/standards
+#
+# HUMAN SUMMARY: This file explains where this project fits in the broader
+# Hyperpolymath ecosystem. It describes what it is, what it isn't, and how
+# it relates to sibling/parent/child projects.
 
+# ── Ecosystem Identity ─────────────────────────────────────────────────────
 [ecosystem]
+# version: Format version for this file.
 version = "1.0.0"
+
+# name: Must match the repo name exactly.
 name = "{{PROJECT_NAME}}"
-type = "{{PROJECT_TYPE}}"  # language, library, tool, infrastructure, playground
+
+# type: What kind of project is this?
+#   language       — a programming language or dialect
+#   library        — reusable code package
+#   tool           — developer tooling (CLI, linter, etc.)
+#   infrastructure — build systems, CI/CD, deployment
+#   playground     — experimental sandbox
+type = "{{PROJECT_TYPE}}"
+
+# purpose: One-sentence description of why this project exists.
 purpose = "{{PURPOSE}}"
-position-in-ecosystem = "{{POSITION}}"  # core, supporting, experimental
 
+# position-in-ecosystem: How central is this project?
+#   core         — essential, many things depend on it
+#   supporting   — useful but not critical
+#   experimental — exploring ideas, may be discarded
+position-in-ecosystem = "{{POSITION}}"
+
+# ── Related Projects ───────────────────────────────────────────────────────
 [ecosystem.related-projects]
-# relationship-type: sibling-standard, parent, child, dependency, inspiration
+# List related projects and their relationship type:
+#   sibling-standard  — same level, different focus
+#   parent            — this project belongs to / is part of
+#   child             — this project contains / manages
+#   dependency        — this project depends on
+#   inspiration       — influenced design but not a dependency
 nextgen-languages = "parent"
 language-playgrounds = "parent"
 
+# ── What This Is ───────────────────────────────────────────────────────────
 [ecosystem.what-this-is]
+# Short descriptions of what the project provides. Helps humans and
+# AI agents quickly understand the scope.
 descriptions = [
   "{{DESCRIPTION_1}}",
   "{{DESCRIPTION_2}}",
 ]
 
+# ── What This Is NOT ──────────────────────────────────────────────────────
 [ecosystem.what-this-is-not]
+# Explicit boundaries — things people might assume this project does
+# but it intentionally does not. Prevents scope creep.
 descriptions = [
   "{{NOT_1}}",
   "{{NOT_2}}",
 ]
+
+# ── Provenance ─────────────────────────────────────────────────────────────
+[provenance]
+# Audit trail — updated automatically by agents/bots on every write.
+# Humans: you can ignore this section, but don't delete it.
+last-modified-by = "{{AGENT_ID}}"
+last-modified-at = "{{TIMESTAMP}}"
+last-session-id = ""
+git-sha-at-read = ""
+modification-summary = "Initial creation from template"

a2ml-templates/META.a2ml.template

@@ -1,22 +1,66 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # META.a2ml - Project metadata and architectural decisions
 # Template from: https://github.com/hyperpolymath/standards
+#
+# HUMAN SUMMARY: This is the project's "constitution". It records the big
+# decisions (Architecture Decision Records / ADRs), coding practices, and
+# design philosophy. Read this to understand *why* things are the way they are.
 
+# ── Project Identity ───────────────────────────────────────────────────────
 [project-meta]
+# version: Format version for this file.
 version = "1.0.0"
+
+# name: Must match the repo name exactly.
 name = "{{PROJECT_NAME}}"
 
+# ── Architecture Decisions ─────────────────────────────────────────────────
 [project-meta.architecture-decisions]
-# ADR format: [project-meta.architecture-decisions.adr-NNN]
-# status, date, context, decision, consequences
+# ADRs go here as sub-tables. Each ADR is numbered:
+#   [project-meta.architecture-decisions.adr-001]
+#   status = "accepted"        # proposed | accepted | deprecated | superseded | rejected
+#   date = "2026-01-15"
+#   context = "Why this decision was needed"
+#   decision = "What was decided"
+#   consequences = "What changed as a result"
 
+# ── Development Practices ──────────────────────────────────────────────────
 [project-meta.development-practices]
-code-style = "{{CODE_STYLE}}"  # rescript, rust, gleam, etc.
+# code-style: Which language's conventions to follow.
+#   Common values: rescript, rust, gleam, elixir, idris2
+code-style = "{{CODE_STYLE}}"
+
+# security: Which security framework is used.
 security = "openssf-scorecard"
+
+# testing: Testing philosophy.
+#   property-based — QuickCheck-style generative tests
+#   unit           — traditional unit tests
+#   integration    — end-to-end tests
 testing = "property-based"
+
+# versioning: Version numbering scheme.
 versioning = "semver"
+
+# documentation: Preferred documentation format.
 documentation = "asciidoc"
+
+# branching: Git branching strategy.
+#   trunk-based — single main branch, short-lived feature branches
+#   git-flow    — develop/release/hotfix branches
 branching = "trunk-based"
 
+# ── Design Rationale ──────────────────────────────────────────────────────
 [project-meta.design-rationale]
-# Key design decisions and their reasoning
+# Key design decisions and their reasoning. Free-form notes about
+# why the project is structured the way it is. Not as formal as ADRs.
+
+# ── Provenance ─────────────────────────────────────────────────────────────
+[provenance]
+# Audit trail — updated automatically by agents/bots on every write.
+# Humans: you can ignore this section, but don't delete it.
+last-modified-by = "{{AGENT_ID}}"
+last-modified-at = "{{TIMESTAMP}}"
+last-session-id = ""
+git-sha-at-read = ""
+modification-summary = "Initial creation from template"