Governance: spec/token/reference validation has no teeth outside Claude Code — wire batch modes into CI (validate-docs is one line away)

[robsongajunior]

Problem

The spec/token/reference guardrails run only as Claude Code write-time hooks. A human editing a .vue in VS Code (or any editor) and pushing through plain git bypasses them entirely — .husky/pre-commit is just lint-staged (ESLint/Stylelint/Prettier), and no CI job re-checks these surfaces:

Hook	Guards	Runs outside Claude Code?
validate-spec-compliance.mjs	.vue ↔ .specs/<name>.md 1-to-1 (props/events/slots, naming, testid, defaults)	❌
validate-tokens.mjs	no HEX/palette/raw typography, no any/@ts-ignore, no class in defineProps	❌
validate-references.mjs	no phantom @aziontech/webkit/* paths, unresolved imports, forbidden deps	❌
validate-story-source.mjs	Storybook "Show code" contract (toSfc, PascalCase tags, no dynamic source)	❌ in CI — but a batch mode already exists

Every rule doc (styling.md, no-invention.md, props.md, naming.md, …) lists these hooks under Enforcement — today those claims are true only for AI-authored edits. Real CI teeth exist for the other surfaces (test:gate, catalog:check, test:toolkit, authoring, doc-standards, lint-canary), which makes the remaining gap easy to miss.

Proposal

Part 1 — the one-liner (ready today). validate-story-source.mjs already has --all, exposed as the root script storybook:validate-docs (root package.json), and it currently passes on the whole tree ("no grandfathering" per storybook-source.md). Wire it into governance.yml — the toolkit job is the natural home (its paths-filter already covers apps/storybook/** and .claude/hooks/**):

- name: Storybook "Show code" contract (storybook-source.md)
  run: pnpm run storybook:validate-docs

Part 2 — batch modes for the other three. validate-spec-compliance, validate-tokens and validate-references only speak the hook protocol (stdin JSON, single file). Give each an --all (and/or a changed-files mode) following the validate-story-source precedent, then:

• run them in CI (toolkit job), and/or
• run them on staged files in pre-commit so human editors get the same write-time feedback the AI gets.

Ratchet as needed: if --all surfaces pre-existing violations, use a baseline file (the doc-standards/authoring pattern) so only new violations block.

Decision point

If Part 2 is not wanted, the honest alternative (per the engineering audit) is to stop advertising these hooks as governance for humans — i.e., annotate the affected rules' Enforcement sections as "AI-authored edits only, human edits gated by review". Either resolves the drift; silently claiming enforcement that doesn't exist is the only wrong option.