fix(workflow-primer): scope CLI ban to mutating commands, document read-only guard surface

[utx0]

Summary

The workflow primer generated by metta refresh claimed a blanket ban on direct metta CLI calls while the metta-guard-bash PreToolUse hook actually permits a read-only query surface. Consumer sessions treated the primer as authoritative, never discovered the permitted commands, and hand-computed wrong answers (zeus session, 2026-08-26). Resolves issue generated-workflow-primer-contradicts-the-bash-guard-blanket (major).

• src/delivery/workflow-primer.ts — scoped MANDATE (state-mutating commands require skills; names metta-guard-bash as enforcement authority; fail-closed framing), new READ_ONLY_POINTER (short variant) and ### Read-only queries (permitted directly) subsection (long variant) enumerating the hook's single-word/two-word/bare allow surface with generation-time qualifier, bare-metta discovery pointer, and attempt-it fail-closed guidance; Forbidden bullet now enumerates the full blocked surface (incl. verify, backlog migrate, milestone/roadmap mutating forms, release cut).
• Both metta-guard-bash.mjs copies — comment-only SYNC annotations above all five list declarations; byte-identical; zero behavioral change (all four guard suites pass unchanged).
• docs/workflows/README.md and metta's own CLAUDE.md region (regenerated byte-exact from buildWorkflowSection()) — same scoped wording; "CLAUDE.md wins" note, doc-only-exceptions line, and stub-prohibition sentence preserved.
• tests/delivery.test.ts / tests/refresh.test.ts — mandate byte-identity pin, retired-wording negative assertions, and a primer↔hook seam test (ADR-4 pin pattern) that regex-extracts the hook's allow/block lists and fails CI on drift.

Review & verification

• Reviews: correctness PASS_WITH_WARNINGS (minor test-hardening suggestions), security PASS, quality PASS — no critical/major findings.
• Gates: stories-valid, tests, lint, typecheck, build — all pass at finalize.
• Verifiers: tsc --noEmit + lint clean; spec coverage 15/15 scenarios evidenced; full suite green (2812 passed / 2 skipped; loaded-machine reruns confirmed flakes were environmental).

UAT results

Result: 28 pass / 0 fail / 7 skip (of 35 steps) — PASS
Run: 2026-08-26 · record committed as docs(fix-generated-workflow-primer-contradicts-bash-guard-blanket): UAT run record (1980a4b) · spec/archive/2026-08-26-fix-generated-workflow-primer-contradicts-bash-guard-blanket/UAT.md

Skipped — needs manual acceptance

Step	Reason
5.1 / 7.13	requires metta refresh in a consumer project (mutating command forbidden to UAT runner)
5.2 / 7.14	requires metta refresh over a hand-edited region (same restriction)
5.3	requires a live downstream session running metta milestone show
6.3 / 7.17	pre-change hook state unobservable to runner; current allowed/blocked/unknown behavior exercised and consistent

🤖 Generated with Claude Code

https://claude.ai/code/session_01AA8wwFpob25iYZFCBBEtKK