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 guards/ as npm run check:*; tests run under Vitest in tests/.

The guard suite

Guards are TypeScript programs under guards/ that walk the pointed corpus 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 pointed corpus — 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 guards/check-*.ts npm run check:<name> pointed corpus 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 guards/ 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 engine verify GitHub Actions workflow, which runs the schema and tool-call guards. Workflow authoring npm run check:* npm test corpus guards as drift tests verify CI schema + tool-call guards guards/check-*.ts same scripts, reproducible exit codes
Authors run guards locally while editing a corpus; Vitest mirrors key corpus checks so regressions fail npm test when a live corpus is present; a corpus tree may carry its own verify job that walks the registry; engine verify runs typecheck, check:schemas, the tool-call-shape guard, test:ci, and the fixture delivery gate; 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 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 job typechecks the server source before it rebuilds.

Next

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