Merge pull request #67 from ChanMeng666/docs/testing-reference-sync

docs: add testing-system reference; sync all agent-facing docs to the shipped gates

Author: ChanMeng666

.claude/commands/release-check.md

@@ -62,7 +62,26 @@ you observed. Do NOT push anything — this command only verifies.
      a hard CI gate (`.github/workflows/ci.yml`) and it is separate from `npm run check`, which
      does **not** run it. It is the gate that catches a `src/manifest.ts` edit whose
      `docs/cli-reference.md` was never regenerated — the single most common way a release goes red.
+   - `npm run typecheck:all` — the four workspaces typecheck too (CI's `builds` job).
    - `npm run docs:build` — the docs site still builds (the core suite does not compile it).
+   - **Confirm the PR gates for the release commit are green on GitHub** —
+     `gh run list --branch main --limit 5` / `gh run view <id>`. `ci.yml` alone has five gating
+     jobs and `codeql.yml` a sixth; a green local `npm run check` is a subset of them, not a
+     substitute. What each job catches: `docs/testing.md` §1.
+
+7. **The two artifacts that used to need a by-hand probe are now GATED — confirm the gate, don't
+   redo the recipe.** Both live in CI's `builds` job; run them locally if it has not run yet:
+
+   ```bash
+   npm run build && npm run mcp:build:only
+   node packages/mcp/scripts/check-dist-resources.mjs   # every baked MCP resource == its repo source
+   npm run vscode:build:only && npx vitest run editors/vscode   # incl. the __CORE_VERSION__ bundle stamp
+   npx vitest run packages/mcp/test/lockstep.test.ts    # both server.json versions, mcpName, dep range
+   ```
+
+   A red `check-dist-resources` means rebuild (and `npm run gen:all` first if the repo artifact is
+   itself stale). A red dep-range assertion is **expected on every core release** and is the
+   intended prompt to bump the shim — see item 2.
 
 ## Reminders (do not act on these here — they are context for the push)
 
@@ -74,41 +93,37 @@ you observed. Do NOT push anything — this command only verifies.
   management is human-with-interactive-2FA only.
 - **The VS Code extension bundles the core at build time.** A language-surface change (new
   token/keyword, grammar change, new quick-fix) means a Marketplace republish of
-  `ChanMeng.archlang` — see `CONTRIBUTING.md#releasing`. Verify the `.vsix` by searching the built
-  `editors/vscode/dist/server.js` for a new keyword/code, not by reading the version string.
-  **Verify it by COUNT, with Node — a bare "no match" is not evidence.** Read the bundle and count
-  occurrences of each new symbol, so a present symbol shows a number and an absent one shows `0`:
-
-  ```bash
-  node -e "const s=require('fs').readFileSync('editors/vscode/dist/server.js','utf8'); \
-    for (const k of ['E_LEVEL_MIX','escalator']) console.log(k, s.split(k).length - 1)"
-  ```
-
-  This is immune to two ways a grep-style check lies about a build artifact: the bundle's line
-  shape (esbuild's wrapping is not guaranteed, and a line-oriented matcher on a one-line bundle can
-  read as a false negative), and regex metacharacters in the pattern — several of this language's
-  surface strings contain `|`, `"`, or `-` (`dir up|down`, `"stair"`, `--level`), which a PowerShell
-  `Select-String` will interpret as a regex unless you pass `-SimpleMatch`. A `0` count for a symbol
-  the new core defines is the real failure signal; anything else means the rebundle took.
-  *(2026-07-26, v1.21.0: `server.js` was 24,595 lines / 3,983 max line and `Select-String` did work —
-  but the count is what proved it, and it costs nothing to be shape-independent.)*
+  `ChanMeng.archlang` — see `CONTRIBUTING.md#releasing`. **"Did the rebundle take?" is now a test,
+  not a by-hand probe:** esbuild stamps the resolved core version into `dist/server.js` as
+  `__CORE_VERSION__` and `editors/vscode/test/stdio.test.ts` asserts it equals that version, over a
+  real LSP round-trip against the built bundle. Confirm the gate — `npm run vscode:build:only &&
+  npx vitest run editors/vscode` (CI's `builds` job runs exactly this) — rather than counting
+  symbols in the artifact. The old count-with-Node recipe was replaced because a version stamp
+  cannot be stale-but-plausible the way a hand-picked symbol list can: it fails for *every* core
+  change, not only the ones somebody remembered to grep for.
+  - Still true, and why the test spawns the bundle rather than reading it: never judge a build
+    artifact with a line-oriented or regex matcher. esbuild's wrapping is not guaranteed, and
+    several of this language's surface strings contain `|`, `"` or `-`, which PowerShell's
+    `Select-String` treats as a regex unless you pass `-SimpleMatch`.
 - **The shim's handshake drift is FIXED** (0.2.3, 2026-07-26): `packages/mcp/src/server.ts` derives
   its `McpServer` version from `package.json` via `readShimVersion()`, mirroring the core's
   `readVersion()` in `src/cli/io.ts`, and a test pins the two together. Don't "fix" it again — and
   don't reintroduce a literal.
 - **Ask what the shim SHIPS, not just what its diff says.** Its `archlang://spec` / `context` /
   `grammar` resources are copied into the tarball at **pack time**
   (`packages/mcp/scripts/copy-resources.mjs`), so they freeze at the last publish while the `^1.x`
-  dep range resolves to a current core. Nothing catches that: `check:drift` compares the *repo-root*
-  artifacts, and `git diff <lasttag>..main -- packages/mcp` is empty. Published 0.2.2 handed hosts a
-  **v1.19 GBNF grammar that could not decode** `arc`/`polygon`/`zone`/`level` at all. On any release
-  that changed the language surface, unpack the published shim and **count** symbols:
-
-  ```bash
-  npm pack @chanmeng666/archlang-mcp@<published> && tar -xzf chanmeng666-archlang-mcp-*.tgz
-  node -e "const s=require('fs').readFileSync('package/dist/archlang.gbnf','utf8'); \
-    for (const k of ['arc','circle','polygon','zone','level','paper']) console.log(k, s.split(k).length-1)"
-  ```
-
-  A `0` for a keyword the current core defines means the shim is lying to hosts, and **only a version
-  bump ships the fix** — that is a legitimate reason to spend one even when the diff is empty.
+  dep range resolves to a current core. `check:drift` does not see it (it compares the *repo-root*
+  artifacts) and `git diff <lasttag>..main -- packages/mcp` is empty. Published 0.2.2 handed hosts a
+  **v1.19 GBNF grammar that could not decode** `arc`/`polygon`/`zone`/`level` at all.
+
+  **Two gates now cover this class, and item 7 above is how you confirm them** — the by-hand
+  `npm pack` + symbol-count probe is retired:
+  `packages/mcp/scripts/check-dist-resources.mjs` byte-compares every baked resource against its
+  repo source (CI's `builds` job), and the dep-range assertion in
+  `packages/mcp/test/lockstep.test.ts` is a **string** equality against `^` + the root version, so a
+  core release reddens the shim on purpose until it is consciously re-pinned and rebuilt. Do not
+  relax that to a semver-satisfies check to green a release.
+
+  What the gates cannot do is publish for you: **only a version bump ships the refreshed
+  resources** — that is a legitimate reason to spend one even when the diff is empty — and the bump
+  must land in BOTH `packages/mcp/package.json` and BOTH of `server.json`'s version fields.

.claude/commands/verify-loop.md

@@ -25,11 +25,34 @@ scripts and report a pass/fail table.
    - If you touched the CLI, expect `docs/cli-reference.md` to move — it is generated from
      `src/manifest.ts`. **Read that diff**; it is the one artifact a CLI change always rewrites.
 
-3. **If tests fail, fix the root cause.** Do not paper over a red suite.
-   - Never run `vitest -u` or `UPDATE_GOLDENS=1 vitest run test/visual.test.ts` without first
-     reviewing the diff and being able to justify **every changed byte**. `compile()` output is
-     byte-for-byte stable and snapshot/golden-tested; an unexplained golden change is a real
-     regression, not a snapshot to bless.
+3. **`npm run typecheck:all`** — REQUIRED whenever the change touched anything outside `src/` +
+   `test/`; skippable (and worth skipping, it is slow) when it did not. Step 1's `typecheck` only
+   covers `src`; this adds the root dev config (`test`, `eval`, `dataset`, `scripts`, `bench`) plus
+   the playground, docs-site (vue-tsc), MCP shim and VS Code extension. CI runs it in the `builds`
+   job.
+   - A `TS2345 … | undefined` on a workspace file that `tsc -p <workspace>` calls clean means a
+     ROOT test imported that module into the strict root program. Fix it in the shared module —
+     never by relaxing the root option (AGENTS.md → Gotchas; `docs/testing.md` §4).
+
+4. **Conditional gates — run the ones the diff earns:**
+   - touched `docs/*.md` or `docs-site/` ⇒ **`npm run docs:build`** (the core suite never compiles
+     the site).
+   - touched `playground/` ⇒ `npm run build && npm run playground:build:only && npm run
+     e2e:playground`.
+   - touched `docs-site/` ⇒ `npm run build && npm run docs:build:only && npm run e2e:docs`.
+   - touched `packages/mcp` ⇒ `npm run mcp:build && node packages/mcp/scripts/check-dist-resources.mjs`.
+   - touched `editors/vscode` ⇒ `npm run vscode:build:only && npx vitest run editors/vscode`
+     (the stdio + bundle-freshness tests SKIP without a built bundle).
+
+5. **If tests fail, fix the root cause.** Do not paper over a red suite.
+   - Never run `vitest -u`, `UPDATE_GOLDENS=1 vitest run test/visual.test.ts` or
+     `ASCII_UPDATE=1 vitest run test/ascii.test.ts` without first reviewing the diff and being able
+     to justify **every changed byte**. `compile()` output is byte-for-byte stable and
+     snapshot/golden-tested; an unexplained golden change is a real regression, not a snapshot to
+     bless.
+   - For any other red guard — a lockstep pin, a docs tripwire, an MCP gate — look up its row in
+     **`docs/testing.md` §2** before touching it: each says whether the answer is *fix the source*,
+     *regenerate*, or *consciously update the pin*.
 
 ## Report
 
@@ -50,5 +73,10 @@ Finish with a pass/fail table:
 | drift: schemas/plan.schema.json | pass/fail |
 | drift: schemas/intent.schema.json | pass/fail |
 
-Note: `docs:build` is a separate gate — the core suite does NOT compile the docs site, so a
-`docs/*.md` edit still needs `npm run docs:build` to catch a broken site build.
+Add a row for each conditional gate you ran (`typecheck:all`, `docs:build`, `e2e:playground`,
+`e2e:docs`, MCP dist resources, vscode bundle tests) and mark the ones the diff did not earn as
+`n/a — <reason>`. Never report a gate you skipped as `pass`.
+
+Note: `npm run check` covers neither `check:drift` nor `typecheck:all` nor `docs:build` — the core
+suite does not compile the docs site or any workspace. Full map of what each gate catches, and the
+red-run response for every guard: `docs/testing.md`.