feat(doc-truthing): in-repo DOC-04/05 guard + ADR-019 record (Refs #175 #176 #260)

Drive two in-repo children of the #175 epic index to a concrete state.

DOC-16 (Refs #176): tools/check-doc-truthing.sh — a toolchain-free bash
guard that locks the doc-truthing invariant DOC-04/05 established. It
fails if any over-claiming doc (README, BACKEND-IMPLEMENTATION,
COMPILER-CAPABILITIES, ALPHA-1-RELEASE-NOTES) loses its authoritative
banner pointing at docs/CAPABILITY-MATRIX.adoc, if the matrix stops
self-declaring primacy or loses its "What AffineScript is NOT" section,
or if STATE.a2ml drops its mirror keys. Checks banner *presence* (not
phrase blocklists) so it is green on the current truthed tree and has no
false positives on the "production-ready" strings that legitimately
appear inside negating banners. Wired into `just check` (guard recipe)
and CI (ci.yml build job), mirroring tools/check-no-extension-ts.sh.
Converts the DOC-08/09 MONITOR posture from external-bot-only to a
first-class in-repo gate.

ADR-019 (Refs #260): docs/decisions/0019-compiler-distribution.adoc — a
canonical per-file decision record (matching docs/decisions/0022) for
the already-settled, already-shipped compiler-distribution decision
(Releases-canonical binaries + thin Deno/JSR shim, S1..S4 merged, JSR
publish live). Cross-linked from SETTLED-DECISIONS.adoc, PACKAGING.adoc,
and the TECH-DEBT INT-04 row.

Ledger: TECH-DEBT.adoc gains the DOC-16 row and the ADR-019 cross-links.
Per the epic's update protocol these are Refs (never Closes) on #175 —
only the owner closes the index.

https://claude.ai/code/session_01E3R1oZhGUKfTYeTSVJVTcn

Author: claude

.github/workflows/ci.yml

@@ -75,6 +75,14 @@ jobs:
         # rationale + recovery instructions.
         run: ./tools/check-no-extension-ts.sh
 
+      - name: Issue #176 — block status-doc truthing re-drift
+        # docs/CAPABILITY-MATRIX.adoc is the single authoritative status
+        # doc. This guard fails if the over-claiming docs lose their
+        # banners pointing back at it, if the matrix stops self-declaring
+        # primacy / loses its anti-over-claim section, or if STATE.a2ml
+        # stops flagging itself as a mirror (DOC-01..09). Toolchain-free.
+        run: ./tools/check-doc-truthing.sh
+
       - name: Check formatting
         run: opam exec -- dune build @fmt
 

docs/PACKAGING.adoc

@@ -66,7 +66,8 @@ scoped automation token) — a deliberate exception to Deno-first.
 #181 says "publish *compiler* + runtime". The runtime is the JS
 packages above. The **compiler is a native OCaml binary** — not a
 JSR/npm package. The one-way-door fork (#260) was decided
-(**ADR-019**): *Releases-canonical, dual-channel*.
+(**ADR-019**): *Releases-canonical, dual-channel*. Full decision record:
+link:decisions/0019-compiler-distribution.adoc[docs/decisions/0019-compiler-distribution.adoc].
 
 * *Canonical artifact.* `.github/workflows/release.yml` (#260 S2), on a
   `v*` tag, builds `affinescript-{linux-x64,macos-x64,macos-arm64}`

docs/TECH-DEBT.adoc

@@ -114,10 +114,21 @@ ABI coordination model (four axes: spec authority / coordinated
 landing / test parity / conflict resolution). Both filed in
 META.a2ml; ADR-020 lands first as the first test of ADR-021's
 protocol. Both require owner ratification. |*PROPOSED 2026-05-23*
+|DOC-16 |In-repo enforcement of the DOC-04/05 truthing invariant —
+`tools/check-doc-truthing.sh` (toolchain-free bash) fails if any
+over-claiming doc loses its `CAPABILITY-MATRIX.adoc` banner, if the
+matrix stops self-declaring primacy or loses its "What AffineScript is
+NOT" section, or if `STATE.a2ml` drops its mirror keys. Wired into
+`just check` (the `guard` recipe) and CI (`ci.yml` build job). Converts
+the DOC-08/09 MONITOR posture from external-bot-only to a first-class
+in-repo gate. |*DONE 2026-05-30*
 |===
 
 MONITOR enforcement (DOC-08/09): any PR re-introducing backend-breadth,
 "production-ready", or stdlib-percentage over-claims must be rejected.
+As of DOC-16 (2026-05-30) the banner/mirror half of this is enforced
+in-repo by `tools/check-doc-truthing.sh`; the external Hypatia/gitbot
+DOC rules remain the catch-all for novel over-claim phrasings.
 
 == Section B — CORE (compiler soundness / completeness)
 
@@ -347,8 +358,9 @@ allocates a length-prefixed AS string and byte-copies from the
 WASI buffer.** Real-host main-invoke = S6 (WIT export lifting)
 |INT-04 |Publish to JSR/npm |S2 |#181 packaging READY (dry-run green,
 manual workflow); compiler-binary distribution decided = **ADR-019**
-(#260, Releases + thin Deno/JSR shim, staged S1..S4) — S1/S2/S3
-merged (#283/#284/#285); S4 done — INT-10 closed (#282).
+(#260, Releases + thin Deno/JSR shim, staged S1..S4; per-file record
+link:decisions/0019-compiler-distribution.adoc[decisions/0019-compiler-distribution.adoc])
+— S1/S2/S3 merged (#283/#284/#285); S4 done — INT-10 closed (#282).
 **First JSR publish landed 2026-05-20: `@hyperpolymath/affinescript@0.1.2`
 LIVE** (cross-runtime Deno+Bun+Node, MPL-2.0, sibling .d.ts for
 fast-check). `@hyperpolymath/affine-js` + `@hyperpolymath/affinescript-tea`

docs/decisions/0019-compiler-distribution.adoc

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MPL-2.0
+// SPDX-FileCopyrightText: 2026 hyperpolymath (Jonathan D.A. Jewell) <j.d.a.jewell@open.ac.uk>
+= ADR-019: Compiler distribution — GitHub Releases binaries + thin Deno/JSR shim
+Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+:toc:
+:toclevels: 2
+:icons: font
+
+Status:: Accepted
+Date:: 2026-05-19 (accepted); implementation S1–S4 landed 2026-05-20
+Issue:: https://github.com/hyperpolymath/affinescript/issues/260[INT-04 #260] (split from https://github.com/hyperpolymath/affinescript/issues/181[#181])
+Series:: Settled-decisions ledger; companion entry in `.machine_readable/6a2/META.a2ml [[adr]] id="ADR-019"`; narrative in `docs/specs/SETTLED-DECISIONS.adoc` §"Compiler Distribution".
+
+== Context
+
+INT-04 (#181) is "publish compiler + runtime". The two halves have very
+different shapes:
+
+* The *runtime* JS packages (`@hyperpolymath/affine-js`,
+  `@hyperpolymath/affinescript-tea`) are ordinary JSR/npm packages — their
+  publish path is bounded packaging-prep (`docs/PACKAGING.adoc`) and was
+  already ready/independent of this decision.
+* The *compiler* is a native OCaml binary. It is **not** a JSR/npm package,
+  so "publish the compiler" has no off-the-shelf answer. How consumers — and
+  in particular `affinescript-lsp` (INT-10) — install it is a one-way-door
+  contract: it sets the install surface, the checksum/trust story, and the
+  LSP's compiler-resolution path.
+
+This was escalated as a design fork (issue #260, AskUserQuestion 2026-05-19)
+rather than guessed, because it is irreversible-ish and outside the
+packaging-prep scope.
+
+== Decision
+
+=== Option survey
+
+The fork presented four options:
+
+(1) **GitHub Releases binaries.** Per-platform artifacts via the existing
+    `release.yml` (`v*` tags) + an install script / fetch-pin.
+
+(2) **Guix/Nix channel.** Aligns with the repo's primary packaging
+    (`guix.scm` / `flake.nix`); reproducible, but a narrower audience and no
+    `deno`/`npm` ergonomics for the LSP-installer consumers.
+
+(3) **Thin JSR/npm shim.** A small package that, on first run, downloads a
+    pinned, checksummed prebuilt binary and execs it — `deno`/`npm`
+    ergonomics without shipping OCaml source.
+
+(4) **Combination** of the above.
+
+=== Chosen: (4) — *Releases-canonical, dual-channel*
+
+The owner chose the combination, with GitHub Releases as the **single
+canonical artifact source** and a thin Deno/JSR shim as the ergonomic front
+door:
+
+* *Canonical artifact.* `.github/workflows/release.yml`, on a `v*` tag,
+  builds per-platform compiler binaries and a `SHA256SUMS` manifest, both
+  attached to the GitHub Release. The Release is the one source of truth;
+  Guix/Nix and any later npm tail are **additive fetch-derivations over it**,
+  not separate producers.
+
+* *Ergonomic front door.* A thin Deno/JSR package
+  `@hyperpolymath/affinescript` downloads the host-platform binary from the
+  pinned Release, verifies it against the `SHA256SUMS` checksum embedded in
+  that shim version, then caches and execs it. HTTPS-only, no secrets, one
+  version+checksum pinned per shim release (no floating fetch).
+
+* *LSP path.* `affinescript-lsp` (INT-10) resolves the compiler via
+  `AFFINESCRIPT_COMPILER` → `affinescript` on `PATH` → the
+  `@hyperpolymath/affinescript` shim. Consuming the shim is what unblocks
+  INT-10; the LSP does no bespoke bundling.
+
+* *npm tail deferred.* An npm publish is added only if an npm-native consumer
+  needs it, mirroring the `affine-vscode` runtime exception. It is **not**
+  wired by this ADR.
+
+== Staging
+
+Tracked in `docs/TECH-DEBT.adoc` (INT-04 / INT-10); all four stages have
+landed:
+
+[cols="1,4,1"]
+|===
+|Stage |Content |Status
+
+|S1 |This ADR + plan; file INT-10. No code. |DONE
+|S2 |`release.yml` per-platform binary build + `SHA256SUMS` matrix |DONE (#283/#284/#285)
+|S3 |The shim package — download + checksum-verify + cache + exec + tests; publish owner-gated via the existing manual JSR workflow |DONE
+|S4 |Wire INT-10 `affinescript-lsp` onto the shim |DONE (#282)
+|===
+
+First JSR publish landed 2026-05-20: `@hyperpolymath/affinescript@0.1.2`
+LIVE (cross-runtime Deno + Bun + Node, MPL-2.0, sibling `.d.ts` for
+JSR fast-check). The shim pins all three v0.1.1 binaries by SHA256, so the
+resolution path executes end-to-end. Compiler version-string drift was fixed
+in lock-step via `lib/version.ml` (single source of truth) + a release.yml
+tag-time bake step (#297/#300).
+
+== Consequences
+
+* The install contract is *Releases-first*. Renaming the `SHA256SUMS`
+  manifest or the per-platform asset names is an ABI change for every shim
+  version and for Guix/Nix derivations downstream — do not rename without
+  amending this ADR and the shim's pinned spec.
+* Browsers and Cloudflare Workers are out of scope for the shim by
+  construction (fetch → save to disk → exec a native binary cannot run in a
+  sandboxed JS runtime). The shim's runtime-compatibility matrix is therefore
+  Deno ✅ / Bun ✅ / Node ✅ / Workers ❌ / Browsers ❌ (see `.claude/CLAUDE.md`
+  Runtime Exemptions).
+* Reproducible-build consumers are served by the additive Guix/Nix
+  derivations layered over the same Release artifact, not by a competing
+  artifact source.
+
+== References
+
+* Issue: https://github.com/hyperpolymath/affinescript/issues/260 (INT-04
+  compiler distribution), split from
+  https://github.com/hyperpolymath/affinescript/issues/181[#181].
+* Unblocks: https://github.com/hyperpolymath/affinescript/issues/282[INT-10
+  #282] (`affinescript-lsp` distribution).
+* `docs/specs/SETTLED-DECISIONS.adoc` §"Compiler Distribution: GitHub
+  Releases Binaries + Thin Deno/JSR Shim (ADR-019)" — the narrative twin of
+  this record.
+* `docs/PACKAGING.adoc` §"The compiler itself — decided (ADR-019 / #260)".
+* `docs/TECH-DEBT.adoc` INT-04 / INT-10 rows.
+* `.machine_readable/6a2/META.a2ml [[adr]] id="ADR-019"` — the machine record.
+* `.github/workflows/release.yml` (S2 producer), `.github/workflows/publish-jsr.yml`
+  (owner-gated shim publish), `packages/affinescript-cli/` (the shim).
+
+== Standing rule
+
+This decision is *settled and implemented*. Do not reopen without amending
+this ADR. The companion `SETTLED-DECISIONS.adoc` section and the `META.a2ml`
+ADR-019 record must move in lock-step with any amendment.

docs/specs/SETTLED-DECISIONS.adoc

@@ -456,5 +456,6 @@ tests, publish owner-gated via the existing manual JSR workflow; *S4*
 wire INT-10 `affinescript-lsp` onto the shim.
 
 This decision is settled; do not reopen without amending the ADR. Full
-ADR in `.machine_readable/6a2/META.a2ml` (ADR-019); ledger #260 /
-INT-10 in `docs/TECH-DEBT.adoc`.
+ADR in `.machine_readable/6a2/META.a2ml` (ADR-019) and the per-file
+decision record link:../decisions/0019-compiler-distribution.adoc[docs/decisions/0019-compiler-distribution.adoc];
+ledger #260 / INT-10 in `docs/TECH-DEBT.adoc`.

justfile

@@ -87,10 +87,14 @@ fmt:
 # Run all checks (lint + test + regression guards)
 check: lint test guard
 
-# Issue #35 Phase 3 regression guard — fails if extension.ts reappears
-# under editors/vscode/src or any face's vscode extension dir
+# Regression guards:
+#  - Issue #35 Phase 3: fails if extension.ts reappears under
+#    editors/vscode/src or any face's vscode extension dir.
+#  - Issue #176 (DOC-01..09): fails if the status-doc truthing banners
+#    re-drift (authoritative matrix pointers + STATE.a2ml mirror keys).
 guard:
     ./tools/check-no-extension-ts.sh
+    ./tools/check-doc-truthing.sh
 
 # ── Compiler subcommands ──────────────────────────────────────────────────────
 

tools/check-doc-truthing.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# Doc-truthing re-drift guard for issue #176 (DOC-01..09).
+#
+# Authoritative feature-readiness status lives in docs/CAPABILITY-MATRIX.adoc.
+# Several historical/architectural docs are known to over-claim (backend
+# breadth, "production-ready", stdlib percentage). DOC-04/05 neutralised them
+# with an *authoritative banner* that points every reader back at the matrix,
+# and made the matrix self-declare its primacy + carry an anti-over-claim
+# section.
+#
+# Until now that invariant was enforced only by the external Hypatia/gitbot
+# review bots (the MONITOR posture in issue #176). This guard makes it a
+# first-class, in-repo, toolchain-free gate: it fails if any of the banner
+# pointers, the matrix's self-declaration, the anti-over-claim section, or the
+# STATE.a2ml mirror keys are removed — i.e. if the docs start to re-drift.
+#
+# It deliberately checks *banner presence*, not phrase blocklists: the word
+# "production-ready" legitimately appears inside the negating banners and in
+# clearly-marked future-roadmap sections, so a naive phrase grep would
+# false-positive. Presence-of-the-correction is the durable invariant.
+#
+# Wired into:
+#   - just check  (via the `guard` recipe in justfile)
+#   - CI          (.github/workflows/ci.yml, build job)
+#
+# Run from anywhere; it cd's to the repo root itself.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# The single authoritative status document.
+MATRIX="docs/CAPABILITY-MATRIX.adoc"
+
+# Docs that historically over-claim and MUST carry a pointer back at $MATRIX
+# (DOC-04). Each must mention CAPABILITY-MATRIX.adoc somewhere in its body.
+BANNERED_DOCS=(
+  "README.adoc"
+  "docs/architecture/BACKEND-IMPLEMENTATION.md"
+  "docs/reference/COMPILER-CAPABILITIES.md"
+  "docs/history/ALPHA-1-RELEASE-NOTES.md"
+)
+
+# The machine-readable mirror (DOC-05): it follows the matrix, it does not
+# lead. These keys assert that contract in-band.
+STATE_FILE=".machine_readable/6a2/STATE.a2ml"
+STATE_KEYS=(
+  "authoritative-status-doc"
+  "drift-flag"
+)
+
+fail=0
+note() { printf '%s\n' "$*" >&2; }
+
+# --- 1. The matrix itself exists and asserts its own primacy ----------------
+if [ ! -f "$MATRIX" ]; then
+  note "ERROR: authoritative status doc is missing: $MATRIX"
+  note "       This file is the single source of truth for feature readiness"
+  note "       (DOC-01, issue #176). Restore it or amend this guard."
+  fail=1
+else
+  if ! grep -q "single authoritative source" "$MATRIX"; then
+    note "ERROR: $MATRIX no longer self-declares primacy."
+    note "       Expected the phrase 'single authoritative source' (DOC-01)."
+    fail=1
+  fi
+  # DOC-08/09: the anti-over-claim section must survive.
+  if ! grep -q "What AffineScript is NOT" "$MATRIX"; then
+    note "ERROR: $MATRIX lost its 'What AffineScript is NOT' section."
+    note "       That section is the anti-over-claim record (DOC-08/09,"
+    note "       issue #176). Do not delete it."
+    fail=1
+  fi
+fi
+
+# --- 2. Every over-claiming doc still points back at the matrix (DOC-04) -----
+for doc in "${BANNERED_DOCS[@]}"; do
+  if [ ! -f "$doc" ]; then
+    note "ERROR: bannered doc is missing: $doc"
+    note "       If it was intentionally removed, drop it from BANNERED_DOCS"
+    note "       in this guard. Otherwise restore the file + its banner."
+    fail=1
+    continue
+  fi
+  if ! grep -q "CAPABILITY-MATRIX.adoc" "$doc"; then
+    note "ERROR: $doc no longer points at the authoritative status matrix."
+    note "       DOC-04 requires an authoritative banner referencing"
+    note "       docs/CAPABILITY-MATRIX.adoc so readers are not misled by"
+    note "       this doc's historical over-claims (issue #176)."
+    fail=1
+  fi
+done
+
+# --- 3. STATE.a2ml still declares itself a mirror, not a leader (DOC-05) -----
+if [ ! -f "$STATE_FILE" ]; then
+  note "ERROR: machine-readable state file is missing: $STATE_FILE"
+  fail=1
+else
+  for key in "${STATE_KEYS[@]}"; do
+    if ! grep -q "$key" "$STATE_FILE"; then
+      note "ERROR: $STATE_FILE lost the '$key' key."
+      note "       DOC-05 requires STATE.a2ml to flag that it MIRRORS the"
+      note "       capability matrix and does not lead it (issue #176)."
+      fail=1
+    fi
+  done
+fi
+
+if [ "$fail" -ne 0 ]; then
+  note ""
+  note "Doc-truthing guard failed. The status docs are drifting back toward"
+  note "over-claiming. See docs/CAPABILITY-MATRIX.adoc (authoritative) and"
+  note "docs/TECH-DEBT.adoc section A (DOC-01..09) for the contract."
+  exit 1
+fi
+
+echo "OK: doc-truthing banners intact (matrix primacy + DOC-04 banners + DOC-05 mirror keys)."