[AAASM-5529] ✅ (tests): Bind quick-start enforcement claims to their proving controls

.github/workflows/publish-docs.yml

@@ -17,6 +17,12 @@ on:
       - "src/generated/**"
       - "metadata/**"
       - "scripts/generate-docs-metadata.mjs"
+      # AAASM-5529: the claim-binding gate below reads the control files and the
+      # deny path. Without these, a PR that only WEAKENS the gate — renaming a
+      # control, or changing which error the deny throws — would not re-run it.
+      - "tests/**"
+      - "src/gateway/**"
+      - "src/wrappers/**"
   push:
     branches:
       - main
@@ -74,6 +80,30 @@ jobs:
           pnpm run generate:docs-metadata
           git diff --exit-code -- README.md docs src/generated
 
+      # AAASM-5529. The step above round-trips the quickstart tab block as TEXT:
+      # it proves docs match the vendored snippets under metadata/ and nothing
+      # more. The snippets are never executed or linted in CI — they are excluded
+      # from ESLint (eslint.config.mjs) and Prettier (.prettierignore), and they
+      # import "./policy.js", a file the reader supplies. The base tsconfig.json
+      # does include them, but no CI job type-checks with it (pnpm typecheck runs
+      # tsconfig.test.json), so nothing gates them.
+      #
+      # This step gates a different surface: the prose in §2, §3 and §4, where
+      # the quick-start states what governance does. Each claim is bound to the
+      # control that proves it.
+      #
+      # It runs HERE because test-matrix.yml sets paths-ignore on docs/** and
+      # **/*.md, so a docs-only PR — precisely the change that rewords a claim —
+      # runs no tests at all.
+      #
+      # SCOPE OF ENFORCEMENT, so nobody reads this as more than it is: this
+      # workflow is NOT one of the workflows ci-success.yml aggregates, and
+      # branch protection on main currently declares no required status checks
+      # at all. This step therefore makes the drift VISIBLE on the PR; it does
+      # not by itself block a merge. Closing that gap is AAASM-5677's scope.
+      - name: Every documented enforcement claim names the control that proves it
+        run: pnpm exec vitest run tests/quickstart-claim-bindings.test.ts
+
       - name: Install website dependencies
         # `--ignore-workspace` tells pnpm to skip the parent
         # `pnpm-workspace.yaml` (added under AAASM-1220) when installing

docs/02-quick-start/index.md

@@ -52,7 +52,7 @@ The package ships dual ESM/CJS entries and selects a prebuilt native binding for
 platform during `postinstall`, so there is no extra build step for typical consumers.
 
 :::note[Pre-1.0 / release candidate]
-The public surface (`initAssembly`, `withAssembly`) is stabilizing but may change
+The public surface (`initAssembly`, `withAssembly`) is stabilizing. It may change
 between pre-releases. Pin an exact version for reproducible installs:
 {/* BEGIN GENERATED: current-version-pin */}
 {/* GENERATED BY scripts/generate-docs-metadata.mjs — DO NOT EDIT. Block: current-version-pin. */}