chore(a2ml): upgrade .machine_readable/ suite to current standards shape

Suite upgrade deferred from 2026-04-10 manhattan-recovery. No .ml code changes.
dune build clean before and after.

Migrated (git mv — history preserved):
  contractiles/ → .machine_readable/contractiles/
  (dust, k9, lust, must, trust — 5 existing types, all files)

Added to .machine_readable/:
  CLADE.a2ml                        — identity + clade="language"
  ADJUST.contractile                — accessibility invariants (CLI/LSP/docs)
  INTENT.contractile                — purpose + anti-scope-creep
  MUST.contractile                  — hard invariants (build, safety, thesis)
  TRUST.contractile                 — AI agent trust levels (maximal)
  contractiles/adjust/Adjustfile.a2ml
  contractiles/intend/Intentfile.a2ml
  agent_instructions/README.adoc
  agent_instructions/coverage.a2ml
  agent_instructions/debt.a2ml      — BUG-001-004 + ZERO/ONE tokens + traits
  agent_instructions/methodology.a2ml
  integrations/verisimdb.a2ml
  integrations/vexometer.a2ml

Updated:
  anchors/ANCHOR.a2ml — appended suite-upgrade realignment-history entry;
                         updated notes section
  6a2/STATE.a2ml     — marked [deferred-upgrade] done (2026-04-12)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/STATE.a2ml

@@ -191,39 +191,23 @@ regression-test-status = "deferred — fixture needs a known-unknown function na
 # scope creep into that plan.
 
 [deferred-upgrade]
-session = "separate, not Phase 0"
-estimated-effort = "1-2 focused hours"
-
-present:
-# What AffineScript already has
-present = [
-  ".machine_readable/6a2/AGENTIC.a2ml",
-  ".machine_readable/6a2/ECOSYSTEM.a2ml",
-  ".machine_readable/6a2/META.a2ml",
-  ".machine_readable/6a2/NEUROSYM.a2ml",
-  ".machine_readable/6a2/PLAYBOOK.a2ml",
-  ".machine_readable/6a2/STATE.a2ml",
-  ".machine_readable/anchors/ANCHOR.a2ml",  # added 2026-04-10 as first anchor
-  "contractiles/ (root-level, old location) — dust, k9, lust, must, trust"
-]
+# DONE 2026-04-12 — suite upgrade completed in dedicated session (no .ml changes)
+status = "done"
+completed = "2026-04-12"
 
-missing = [
+added = [
   ".machine_readable/CLADE.a2ml",
-  ".machine_readable/contractiles/ (should migrate from root contractiles/)",
-  ".machine_readable/contractiles/adjust/",
-  ".machine_readable/contractiles/intend/",
-  ".machine_readable/agent_instructions/",
-  ".machine_readable/integrations/",
-  ".machine_readable/ADJUST.contractile (top-level instance)",
-  ".machine_readable/INTENT.contractile (top-level instance)",
-  ".machine_readable/MUST.contractile (top-level instance)",
-  ".machine_readable/TRUST.contractile (top-level instance)"
+  ".machine_readable/contractiles/ (migrated from root via git mv — history preserved)",
+  ".machine_readable/contractiles/adjust/Adjustfile.a2ml",
+  ".machine_readable/contractiles/intend/Intentfile.a2ml",
+  ".machine_readable/agent_instructions/README.adoc",
+  ".machine_readable/agent_instructions/coverage.a2ml",
+  ".machine_readable/agent_instructions/debt.a2ml",
+  ".machine_readable/agent_instructions/methodology.a2ml",
+  ".machine_readable/integrations/verisimdb.a2ml",
+  ".machine_readable/integrations/vexometer.a2ml",
+  ".machine_readable/ADJUST.contractile",
+  ".machine_readable/INTENT.contractile",
+  ".machine_readable/MUST.contractile",
+  ".machine_readable/TRUST.contractile"
 ]
-
-notes = """
-Root-level contractiles/ directory has 5 of 7 current types. The canonical
-pattern is .machine_readable/contractiles/ with all 7 types. Migration is
-deferred to a separate session because it requires reading each contractile
-definition from the standards repo and deciding which apply to AffineScript
-specifically. Do not conflate with Manhattan Phase 0.
-"""

.machine_readable/ADJUST.contractile

@@ -0,0 +1,38 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; ADJUST.contractile — Accessibility instance for AffineScript
+; Compiler/LSP accessibility — subset of WCAG 2.2 AA applicable to developer tools.
+
+(adjust-contractile
+  (version "1.0.0")
+  (repo "nextgen-languages/affinescript")
+  (standard "CLI-accessible (WCAG 2.2 AA where applicable to developer tools)")
+
+  (invariants
+    ; ── CLI output ──
+    (adjust "all error messages include file:line:col — not just a message")
+    (adjust "error messages use plain language — not jargon codes alone")
+    (adjust "no information conveyed by ANSI colour alone (symbol + colour)")
+    (adjust "output safe in non-TTY (piped to file or CI log)")
+    (adjust "all subcommands support --help with plain-text output")
+    (adjust "exit codes documented in QUICKSTART-USER.adoc")
+
+    ; ── Affine type errors ──
+    (adjust "affine/linear violation messages name the variable and say why it is consumed")
+    (adjust "error code E#### always accompanied by human-readable description")
+    (adjust "quantity annotation syntax documented in both @annotation and :sugar forms (ADR-007)")
+
+    ; ── LSP ──
+    (adjust "hover responses in plain Markdown (no raw HTML)")
+    (adjust "completion items include kind field for screen reader discrimination")
+    (adjust "diagnostic ranges use start+end, not character offset alone")
+
+    ; ── Documentation ──
+    (adjust "all diagrams in docs/ have alt text or text description")
+    (adjust "code examples in guides include explanatory comments")
+  )
+
+  (enforcement
+    (ci "panic-attack checks for colour-only output patterns")
+    (manual "LSP output reviewed for plain-Markdown compliance on new diagnostic types")
+  )
+)

.machine_readable/CLADE.a2ml

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+# Clade declaration — part of the gv-clade-index registry
+# See: https://github.com/hyperpolymath/gv-clade-index
+
+[identity]
+uuid = "b3f82c1a-4e9d-4b7a-a831-6c2d5e9f0a14"
+primary-forge = "github"
+primary-owner = "hyperpolymath"
+canonical-name = "affinescript"
+prefixed-name = "gv-affinescript"
+
+[clade]
+primary = "language"
+secondary = ["compiler", "type-system"]
+assigned = "2026-04-12"
+rationale = "AffineScript is a programming language with affine types targeting Typed WASM. Primary clade is 'language'; secondary clades capture the compiler pipeline and type-system research aspects."
+
+[forges]
+github = "hyperpolymath/nextgen-languages"
+# affinescript lives in the nextgen-languages monorepo submodule
+# it is NOT a standalone GitHub repo
+
+[lineage]
+type = "submodule"
+parent = "nextgen-languages — the hyperpolymath language monorepo"
+born = "2025-09-12"
+note = "Predates ANCHOR.a2ml convention. Retroactively assigned clade 2026-04-12 during suite upgrade."
+
+[language]
+# AffineScript-specific fields
+paradigm = ["functional", "affine", "typed"]
+compile-targets = ["typed-wasm", "julia", "wasm-gc"]
+inspiration = ["ReScript", "Rust", "Granule", "OCaml"]
+headline-feature = "affine-types-with-javascript-ergonomics"
+
+[thesis]
+one-sentence = "AffineScript is JavaScript-ergonomic correctness: the developer experience of the -script family raised to a higher correctness floor through affine types, compiling to Typed WASM."

.machine_readable/INTENT.contractile

@@ -0,0 +1,40 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; INTENT.contractile — Purpose and anti-scope-creep for AffineScript
+; See ANCHOR.a2ml for the full thesis. This file is the machine-readable summary.
+
+(intent-contractile
+  (version "1.0.0")
+  (repo "nextgen-languages/affinescript")
+
+  (purpose
+    "AffineScript is a programming language with affine types and JavaScript
+     ergonomics, compiling to Typed WASM. Feature set is fixed by thesis in
+     ANCHOR.a2ml.")
+
+  (anti-purpose
+    "NOT a language with dependent types (Typed WASM project)."
+    "NOT a language with linear types as a separate concept (bot scope creep — subsumed by affine)."
+    "NOT a language with tropical types (Typed WASM project)."
+    "NOT a language with units of measure (Typed WASM project)."
+    "NOT a general-purpose JS replacement.")
+
+  (load-bearing-decisions
+    (adr "ADR-001" "Split-Γ typing context")
+    (adr "ADR-002" "Scaled Let rule")
+    (adr "ADR-003" "Left-to-right evaluation")
+    (adr "ADR-007" "Quantity annotation surface syntax")
+    (adr "ADR-010" "Faces architecture"))
+
+  (ecosystem-position
+    (upstream "nextgen-languages monorepo — sister to Ephapax, WokeLang, Eclexia")
+    (compile-target-primary "typed-wasm")
+    (compile-target-secondary "julia")
+    (downstream-consumer "IDApTIK (AGPL, game engine)")
+    (downstream-consumer "airborne-submarine-squadron (AGPL, game)"))
+
+  (scope-creep-history
+    (event "2026-04-10 manhattan-recovery"
+      "Bot scope creep added linear types, dependent types, algebraic effect
+       handler ambitions. Scope narrowed back to 8-feature thesis. Three ADRs
+       adopted. See ANCHOR.a2ml realignment-history for full record."))
+)

.machine_readable/MUST.contractile

@@ -0,0 +1,52 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; MUST.contractile — Hard invariants for AffineScript
+; These MUST NOT be violated by any AI agent or human contributor.
+
+(must-contractile
+  (version "1.0.0")
+  (repo "nextgen-languages/affinescript")
+
+  (invariants
+
+    ; === Build ===
+    (must "dune build passes before and after every change")
+    (must "dune runtest passes — all E2E tests green")
+    (must "no compilation errors introduced by any commit")
+
+    ; === Safety patterns ===
+    (must "no assert_total in any OCaml file")
+    (must "no Obj.magic in any OCaml file")
+    (must "no believe_me in any Idris2 file")
+    (must "no TODO-as-implementation (stub bodies are forbidden in shipped code; use explicit failwith with a tag)")
+
+    ; === Scope ===
+    (must "thesis in ANCHOR.a2ml is authoritative — new features require a new ADR")
+    (must "linear types may not be added as a separate concept — they are subsumed by affine types")
+    (must "dependent types remain out of scope — they belong in the Typed WASM project")
+    (must "algebraic effect handlers beyond try/catch remain out of scope (ADR-004 extension point only)")
+
+    ; === Architecture ===
+    (must "the Split-Γ typing context (ADR-001) is canonical — do not introduce alternative context shapes")
+    (must "the Scaled Let rule (ADR-002) governs all let-binding — do not bypass with ad-hoc quantity inference")
+    (must "left-to-right evaluation order (ADR-003) — do not evaluate argument lists right-to-left")
+    (must "face-specific logic belongs in lib/face.ml — do not inline face dispatch in parser.mly or typecheck.ml")
+
+    ; === Tests ===
+    (must "every new language feature ships with at least one E2E test in test/e2e/")
+    (must "regression fixtures must be added when a bug is fixed")
+
+    ; === Licenses ===
+    (must "SPDX-License-Identifier: PMPL-1.0-or-later in every source file")
+    (must "MPL-2.0 as legal fallback (lawyer-confirmed) — no re-labelling needed")
+
+    ; === IDApTIK integration ===
+    (must "do not break the AffineTEA Wasm output consumed by IDApTIK (AGPL project, co-developed with son)")
+    (must "wasm/titlescreen.wasm, wasm/router.wasm in idaptik/public/assets/wasm/ must remain valid after compiler changes")
+  )
+
+  (enforcement
+    (ci "panic-attack assail runs on every PR")
+    (ci "dune build + dune runtest in CI")
+    (pr-block "build failure blocks merge")
+  )
+)

.machine_readable/TRUST.contractile

@@ -0,0 +1,38 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; TRUST.contractile — AI agent trust levels for AffineScript
+
+(trust-contractile
+  (version "1.0.0")
+  (repo "nextgen-languages/affinescript")
+
+  (default-trust "maximal")
+  ; Rationale: AffineScript is a research compiler. Claude is the primary
+  ; implementer. Maximal trust for all non-destructive work. Jonathan reviews
+  ; via git diff before committing.
+
+  (trust-grant "maximal"
+    (allow "read any file in the repo")
+    (allow "write to lib/*.ml, lib/*.mli, bin/*.ml, test/e2e/")
+    (allow "write to .machine_readable/ (except STATE.a2ml open-bugs — append only)")
+    (allow "write to spec/, docs/")
+    (allow "add new test fixtures in test/e2e/fixtures/")
+    (allow "update CHANGELOG.md")
+    (allow "run dune build and dune runtest")
+    (allow "run panic-attack assail")
+  )
+
+  (trust-deny "all-tiers"
+    (deny "commit directly — always produce a diff for Jonathan to review in this private repo")
+    (deny "push without confirmation in the same session")
+    (deny "add a language feature not in ANCHOR.a2ml thesis")
+    (deny "reverse any ADR (ADR-001 through ADR-010) without a new ADR")
+    (deny "delete or overwrite the 6a2/ core files (STATE/META/ECOSYSTEM/AGENTIC/NEUROSYM/PLAYBOOK)")
+    (deny "modify IDApTIK without explicit instruction (AGPL — separate repo, separate session)")
+  )
+
+  (scope-boundary
+    (note "AffineScript is private (ALL RIGHTS RESERVED in Claude context).")
+    (note "The thesis in ANCHOR.a2ml is the scope boundary. Violating it is a MUST violation.")
+    (note "007 is a separate private language — do not confuse the two compilers.")
+  )
+)

.machine_readable/agent_instructions/README.adoc

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= AffineScript Agent Instructions
+:toc: preamble
+
+Methodology-aware configuration for AI agents working in this repository.
+Read at session start by any AI agent (Claude, Gemini, Copilot, etc.).
+
+== Critical: read before touching code
+
+1. **ANCHOR.a2ml is authoritative for scope.** The thesis is fixed. New features require a new ADR, not a code change. Bot scope creep has been a recurring problem (see manhattan-recovery 2026-04-10).
+2. **No `.ml` edits without reading ANCHOR.a2ml + META.a2ml first.** The type system has interdependencies that are not obvious from reading individual files.
+3. **dune build must pass** before and after every change. Run it.
+4. **Thesis is the authority; code must conform.** If code contradicts thesis, code is wrong.
+
+== Files
+
+[cols="1,3"]
+|===
+| File | Purpose
+
+| `methodology.a2ml`
+| Default mode, ring ceiling, priority weights, wave cap
+
+| `coverage.a2ml`
+| Session coverage tracking — what was visited, what was skipped
+
+| `debt.a2ml`
+| Meander debt — things found but not fixed, carried between sessions
+|===
+
+== Open bugs (from ANCHOR.a2ml)
+
+BUG-001 through BUG-004 are tracked in STATE.a2ml. Check before starting any type-system work — one of these may already cover the issue you found.
+
+== Faces architecture
+
+AffineScript supports multiple surface-syntax dialects (canonical, python-face, js-face, pseudocode-face). New faces follow the pattern in `lib/face.ml`. Do NOT add face-specific logic directly to the parser or type checker.

.machine_readable/agent_instructions/coverage.a2ml

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# coverage.a2ml — Session coverage tracking for AffineScript
+# Updated at the end of each AI agent session.
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-12"
+
+[coverage]
+total-components = 39          # compiler modules (from STATE.a2ml [stats])
+visited-components = 0
+coverage-percent = 0
+
+# ============================================================================
+# VISITED COMPONENTS
+# ============================================================================
+# Component → session date + what was done
+
+[coverage.visited]
+# Suite upgrade session (2026-04-12) — .machine_readable/ only, no .ml changes
+
+# [coverage.visited.typecheck]
+# date = "2026-04-11"
+# ring = 1
+# fixes = 3
+# note = "Traits wired, linear arrows enforced, borrow checker gated"
+
+# [coverage.visited.lsp-server]
+# date = "2026-04-11"
+# ring = 1
+# fixes = 4
+# note = "Phases A-D complete: hover, goto-def, completion, JSON-RPC server"