docs(agents): add a test-audit procedure with the mutation discipline that worked

[thymikee]

Summary

Adds docs/agents/test-audit.md and routes it from the AGENTS.md task table. Adapted from the upstream openclaw test-audit card (https://github.com/openclaw/openclaw/blob/main/.agents/skills/test-audit/SKILL.md). This is the workflow that produced #2930-#2944; capturing it here so the next sweep starts from the repo's own rules instead of rediscovering them.

It lives under docs/agents/ rather than skills/, per AGENTS.md: skills stay minimal routing cards and task procedures go in docs. A test audit is not an app-driving capability the CLI skill routes to, so it does not need a card at all.

What is repo-specific versus upstream:

• Junk patterns are the shapes that turned up as real findings here: type pins surviving erasure (Equal<A,B> = true, X ? true : never, satisfies compared after it stops existing at runtime), a lone typeof x === 'function' sitting directly above the test that calls x, an ordering claim with no ordering assertion, a switch written inside a test body and compared to its own arms.
• Retention bar is earned, not copied: registry/gate-manifest/layering completeness, golden tables and cross-language source inspection, @ts-expect-error directives (an unused directive is a compile error — they do bite), exact-array facets where a membership scan can't see duplicates, identity pins deep-equal can't subsume, vocabulary pins that survive a production+fixture co-update.
• Mutation discipline is the part worth keeping even if the rest gets rewritten: plant the production edit that represents the claimed bug, show old body green and new body red with both counts, revert, show git status clean. Arguing detection is not evidence; measuring it is.
• Never-run detection asks which runner and gate actually executes a file — a Vitest project, a node --test script (test:smoke, check:*:test), native XCTest, or a CHECK_CATALOG gate id. Vitest-project matching alone would have misclassified the healthy node:test integration and gate suites.
• Validation commands are ours (pnpm exec vitest --project unit-core/apple-runner, pnpm check:quick, pnpm check:affected --run, git diff --numstat origin/main...HEAD), and the doc records that the upstream run-vitest.mjs/check-changed.mjs helpers do not exist here. It also records a trap found the hard way: most scripts/** tests are in no tsconfig include, so helpers added there need an explicit check that they execute.
• Dispatch plan for parallel subagent lanes is included (subsystem lanes + cross-cutting pattern sweep + never-run inventory), with the mandatory per-prompt rules: read-only, name the production bug, verify skip guards and runner/gate ownership, retention list verbatim, cap output.

Validation

• pnpm check:agent-guidance — 5 pass. The doc is 3,943 bytes, inside the 10,000-per-file budget, and docs/agents/ totals 39,897 of 40,000 bytes with AGENTS.md at 7,989 of 10,000.
• pnpm format, pnpm lint, pnpm check:quick
• pnpm check:affected --run on the pushed head: selects only agent-guidance, passes

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.83 MB	4.82 MB	-13.4 kB
Package (unpacked)	4.83 MB	4.82 MB	-13.4 kB
Package (download)	1.45 MB	1.44 MB	-3.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	25.1 ms	25.3 ms	+0.2 ms
CLI --help	71.6 ms	73.3 ms	+1.7 ms

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[thymikee]

Reviewed 0602822. This is a docs-only change, and I found no wrong claim in the commands and paths it names. I did not check every statement about tool behavior, for example the exact effect of fallow's --gate all.

One question about shape. skills/test-audit/SKILL.md holds the full procedure inline: the authoring gate, the junk-pattern catalog, retention criteria, mutation discipline, validation commands and the landing checklist. AGENTS.md says skills stay minimal routing cards and task procedures go in docs/agents/, and the sibling skills are 22-32 lines that point to help topics or docs. Would it work to move the body to docs/agents/test-audit.md and keep SKILL.md as a short card that says when to load it and links the doc, like skills/agent-device/SKILL.md? If there is a reason the procedure must live in the skill itself, please say what it is.

CI passes; Smoke Tests was still running and does not exercise this diff. There are no conflicts.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-25 11:57 UTC

[thymikee]

Addressed in 4791a65.

Shape (your question): agreed — the procedure moved to docs/agents/test-audit.md (4,020 B, inside the 10,000-per-file and 40,000-total docs/agents budgets agent-guidance-contract.test.ts enforces) and skills/test-audit/SKILL.md is now a 12-line card: when to load it, the one non-negotiable, and a link. The AGENTS.md router names both. check:affected --run selects agent-guidance for the new doc and passes; npm-skills-exclusion still passes.

Cubic findings, checked one by one:

1. node:test misclassification — valid. test/integration/*.test.ts and the scripts/** gate suites run under node --test (test:smoke, test:integration:node, check:*:test), and no Vitest project includes them, so "unmatched Vitest project = never-run" would have deleted healthy coverage. The evidence field now asks which runner and gate executes the file (Vitest project, node --test script, XCTest, or a CHECK_CATALOG gate id) and only calls a file no runner reaches never-run. The macos.yml note went away rather than being kept half-true: that lane runs pnpm exec vitest run on named paths, which is already the gate-id case, and the card shouldn't track per-workflow file lists.
2. npx vs pnpm exec — valid; the doc uses pnpm exec vitest and pnpm check:quick (the repo's own lint+typecheck entry, package.json:166). Bare npx resolved outside the workspace.
3. npx tsc -b packages/... — valid, and worse than reported: tsc takes no glob there. Replaced with pnpm check:quick. The tsc -p tsconfig.json half was also dropped because that project's include is src + test, which pnpm check:quick already covers.
4. Bare git diff --numstat — valid; a clean pushed commit has no unstaged diff. Now git diff --numstat origin/main...HEAD, matching pull-requests.md:36.

The scripts/**-outside-tsconfig trap survives as written: tsconfig.json includes src, test, and one named script, so pnpm typecheck really does skip a new scripts/ helper.

Validation: pnpm format, pnpm lint, pnpm check:quick, pnpm check:agent-guidance (5 pass), pnpm exec vitest run --project unit-core scripts/__tests__/npm-skills-exclusion.test.ts scripts/__tests__/simulator-skills-contract.test.ts test/ci/root-docs-paths-ignore.test.ts (23 pass), pnpm check:affected --run on 4791a65 (only agent-guidance selected, passed). Docs-only, so no device lane is selected.

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[thymikee]

The update at 4791a65 answers the earlier shape question. The procedure now lives in docs/agents/test-audit.md, AGENTS.md routes to it, and skills/test-audit/SKILL.md is a 12-line card. It also fixes the earlier wrong claim about which runner test/integration uses. docs/agents is now at 39,958 of its 40,000-byte budget, so the next addition there will need room.

CI is green, and this change is docs-only.

Not blocking: should this card live in skills/? That directory is what users install with npx skills add callstack/agent-device, and this card triggers on generic test-writing and points at a file that exists only in this repository. A contributor-only location such as .claude/skills/test-audit/, or only the docs/agents file, may fit better.

[thymikee]

Dropped the skill card in 5559b23. Once the procedure moved to docs/agents/test-audit.md, a card that only pointed at it carried no decision of its own — and unlike skills/agent-device, a test audit isn't an app-driving capability a launcher discovers. The PR is now two files: the doc and its AGENTS.md router row.

Trimming the doc to absorb the freed budget left docs/agents/ at 39,871 / 40,000 bytes rather than 12 over. pnpm check:agent-guidance (5 pass), pnpm format, pnpm lint, pnpm check:quick, and pnpm check:affected --run on 5559b23 all pass.