Quality Gates

The local and CI checks that protect generated data, tokens, builds, links, and tests.

Inner loop

Run focused checks while changing code:

pnpm check
pnpm test:unit

pnpm check typechecks the root host, @zudo-sg/demo-ui, and the demo app. pnpm test:unit runs Vitest unit tests.

For docs-only work, use the filtered docs checks:

pnpm --filter @zudo-sg/doc check
pnpm --filter @zudo-sg/doc build
node scripts/check-links.mjs --dist=doc/dist

Generated-data drift

Generated files are checked in, but their source of truth lives elsewhere. Both checks below wrap the zudo-sg CLI shipped by the @takazudo/zudo-sg styleguide engine (packages/styleguide), not a root-owned script:

• pnpm check:sg-registry runs zudo-sg gen-registry --check, verifying the styleguide story registries generated from packages/demo-ui/src/**/*.stories.tsx.

• pnpm check:token-manifest runs zudo-sg gen-token-manifest --check, verifying the UI token manifest generated from packages/demo-ui/styles/tokens.css and packages/demo-ui/styles/colors.css.

Both commands read the host's zudo-sg.config.mjs for their inputs and outputs (components roots, category order, token CSS files); see Component Catalog Pipeline and Design Tokens.

The docs workspace uses zudo-doc's package-owned default z-index tiers. It has no local z-index generator or drift check.

When a source file changes, run the matching generator before committing:

pnpm gen:sg-registry
pnpm gen:token-manifest

Token and accessibility gates

pnpm lint:tokens enforces the tight-token strategy so components keep using approved semantic token utilities. pnpm contrast:audit checks configured color relationships for contrast regressions.

Story files are also covered by unit tests in packages/demo-ui/src/stories/__tests__, including module-shape and source-drift checks.

Pre-push gate

The local pre-push command is:

pnpm b4push

It runs formatting checks for MDX, token lint, codegen drift checks, typecheck, unit tests, root build, demo build, link checks, HTML validation, Playwright smoke tests, and a final manual interactive smoke prompt.

Use the full gate before pushing broad changes. For documentation-only changes, the required focused checks are usually the docs build, docs check, link check against doc/dist, and git diff --check.

Heavy steps are queued machine-wide

The five expensive steps — unit tests, root build, demo build, doc build, and the Playwright smoke — go through a heavy helper in scripts/run-b4push.sh that delegates to a machine-wide queue (~/.claude/scripts/heavy-guard.sh or the ~/.codex twin, overridable with HEAVY_GUARD). When several agent sessions share one machine, two overlapping heavy lanes exhaust memory and the suites go red for reasons unrelated to the code; the queue serializes them and gates on free memory instead.

The lookup is fail-open: on CI and on any machine without the guard installed, the step runs directly and nothing changes. Exit codes pass through unchanged, so the gate's pass/fail collection is unaffected. Each wrapped step adds one heavy-guard: verdict=PASS|FAIL|ENV_SUSPECT line on stderr; exit 75 means the queue timed out and the step never ran.

Read the verdict before reading the failure. ENV_SUSPECT means the step failed while the machine was starved — rerun it once, and if it is still red with no assertion, type, or lint error in the output, defer that step to CI rather than calling it passed. FAIL is a real failure. Never tune the suite itself (timeouts, worker counts) to fit one machine.

Engine foreign-install gate

pnpm verify:styleguide-install proves the @takazudo/zudo-sg engine installs the same way a project outside this workspace would install it — not only through the workspace link the root host uses day to day:

pnpm verify:styleguide-install

It packs packages/styleguide with pnpm pack, installs the tarball plus exact @takazudo/zfb/@takazudo/zudo-doc pins into a copy of fixtures/engine-host/ placed outside this repository (so its realpath resolves under node_modules, with no workspace link and no packages: [] escape hatch), runs zudo-sg gen-registry, builds, and asserts the four injected routes plus the standalone preview stylesheet exist under the fixture's non-root base (/styleguide/). It then boots zfb dev once with the fixture's islands seed stripped from the temp copy and asserts that ConfiguredPreviewApp and the fixture's Counter island (reached only through the registry virtual module) are registered in /styleguide/assets/islands.js, and that a utility class used only by an injected route reaches the dev stylesheet — the regression guard for zfb 2.18.0's dev-scanner and CSS-glob seeding (ADR finding 4 amendment).

Run this gate after any change under packages/styleguide that touches the routes plugin, the preview-CSS plugin, staging, or the CLI; it is not part of the inner loop or pnpm check.

CI gate

Pull requests target main or base/** branches. CI mirrors the b4push shape with separate jobs for token lint, codegen drift, typecheck, unit tests, root build, demo build, smoke E2E, and dist checks.

Scheduled rich CI is intentionally deferred until after public release. Visual and platform-specific checks are run ad hoc instead of as standing nightly infrastructure.