Workflow Server

Quality system

Executable guards encode conventions that matter: reference integrity, naming rules, schema truthfulness, and site link integrity. Recurring authoring mistakes become named anti-patterns, mechanical guards, and baselines that ratchet toward zero.

For contributors. Guards live in scripts/ as npm run check:*; tests run under Vitest in tests/.

The guard suite

Guards are TypeScript scripts under scripts/ that walk the workflows worktree or this site's HTML and report violations. Each convention named in a specification or architecture page has a matching check — the spec defines the rule; the guard enforces it mechanically. Run them with npm run check:<name>; a clean tree always yields the same result.

What the guard suite scans Specifications and schemas define conventions. Guard scripts scan either the workflows worktree — YAML and markdown grouped into loadability, technique shape, wiring, and workflow safety — or the documentation site for link and diagram integrity. Specifications + schemas the rules guards encode scripts/check-*.ts npm run check:<name> workflows worktree YAML + markdown Load schema, refs Techniques protocol shape Wiring bindings, vars Safety workflow rules documentation site hand-authored HTML + generated regions check:site links, nav, anchors check:svg diagram layout
Guards mirror the specification model: corpus checks group around loadability, technique contracts, static wiring, and workflow-specific safety; site checks keep links and inline diagrams honest. Per-guard behaviour lives in the scripts and in the spec pages that name them — for example Workflows, State, Resolution, and Fidelity.
Where guards run Three entry points invoke the same guard scripts: local npm run check commands during authoring, Vitest drift tests for a subset of corpus guards, and the deploy-docs GitHub Actions workflow for site changes. Workflow authoring npm run check:* npm test corpus guards as drift tests deploy-docs CI site guards + build:site scripts/check-*.ts same scripts, reproducible exit codes
Authors run guards locally while editing the workflows branch; Vitest mirrors key corpus checks so regressions fail npm test; the verify workflow walks the whole registry on every pull request, and deploy-docs rebuilds the generated regions and checks them for drift.

Most guards are hard-zero — any finding fails the run. Where a guard measures debt the corpus already carries, every finding is triaged once by hand in a committed file that records a verdict and a named rationale against each one: harmless by design, a real seam accepted for now, or a live bug that keeps the guard red until it is fixed. There is no re-snapshot flag, because classifying a finding is a judgement rather than a regeneration — and an entry that stops matching anything is reported too, so a seam cannot leave the ledger by going quiet. The full command list is in package.json.

The test architecture

The Vitest suite (thirty-plus files) is organized around what could break:

Generated, then guarded

Two artifacts are machine-derived from the source, and both are guarded against drift rather than trusted to stay fresh. The documentation site itself follows the same pattern — hand-authored pages with generated API regions — and check:site / check:svg keep links and diagrams honest:

The two generation pipelines Top row: the Zod sources in src slash schema are compiled by npm run build colon schemas into the checked-in JSON schema files, which serve authoring validation and the schemas MCP resource. Bottom row: the server source is replayed by npm run build colon site into the generated regions of the site's API pages, and tests slash site.test.ts fails when the committed pages drift. src/schema (Zod) the source of truth npm run build:schemas compile to JSON Schema schemas/*.schema.json checked in, tested authoring + validation MCP resource + this site server source tool registrations npm run build:site replayed on a recorder site/api/*.html generated regions tests/site.test.ts fails on drift
The two generation pipelines. The JSON schemas are compiled from the Zod sources; the site's tool and schema pages contain regions regenerated by replaying the real tool registrations against a recording stub. In both cases the generated artifact is committed, and a test fails when it no longer matches a fresh generation — documentation cannot silently lie about the code.

The same discipline extends to deployment: the GitHub Pages workflow rebuilds the generated regions and fails if the committed pages have drifted, so the deployed site is exactly the checked, committed one. The guards themselves run in the verify workflow, which has no path filter — every pull request gets the whole suite, so a site check cannot be skipped by a change that looks unrelated.

Next

Where this machinery lives in the server is server anatomy; how runs are kept on-script at runtime is workflow fidelity.