Reference

Glossary

Every term with a dotted underline elsewhere in these docs, defined once. The link after each entry goes to the page that uses it most.

Terms

actor

Who is expected to do a step's work: a named skill (site-brief, design-system, site-scaffold, ux-review, commercial-jury, legal-check, site-publish) or orchestrator, the agent driving the run. Printed in brackets by next. Drive a run

blocker

A recorded, validated reason a step cannot be done. Each step lists the blockers it accepts; each blocker has a validator that demands evidence. A blocked step counts as satisfied downstream. The workflow, step by step

DAG

Directed acyclic graph: steps joined by "must come after" arrows, with no way to loop back. spec.mjs refuses a workflow with a cycle at load time. The workflow, step by step

declaration

A fact no program can discover, stated once through site-context.mjs and validated where it is read: mail posture, hosting processor, jurisdiction, BFSG scope, legal form, routes, URLs. Life-cycle of a run

freshness

The rule that a record describing a build must be newer than the build: the ux-review, the jury and the receipt are compared to the newest file under src/, public/, dist/. Life-cycle of a run

gate

tools/site-step.mjs and the logic behind it in spec.mjs: the command that reads the workflow, evaluates exit predicates, and closes or halts steps. The only thing that decides. Architecture

halt

A stopped state written into run-state.json by any refusal. While it stands, only the halted step and its prerequisites may be worked on and deploys are denied. Lifted only by succeeding on the same step. Life-cycle of a run

hook

A script Claude Code runs around a tool call. The machine registers three: site-log after every call, site-guard before Bash calls and at session start. They fail open; the gate fails closed. Hooks and the ledger

ledger

<site>/run-log.jsonl: one JSON line per tool call, appended by the site-log hook. The ledger predicate kind proves claims from it — never from an assertion — and an empty ledger reads as unproven. Hooks and the ledger

Modern Web Guidance

Google Chrome's skill of current web-platform practice, vendored into every site under .agents/skills/modern-web-guidance/ (Apache-2.0) and pinned in skills-lock.json. Must be searched before any component is written; the ledger proves it. The workflow, step by step

orchestrator

The actor name for whoever drives the run — the agent, or a person typing the commands — as opposed to a named skill. Eight steps belong to it. Drive a run

predicate (exit predicate)

A yes/no check a step must pass to close. Twenty-three live in tools/predicates/; each prints what it saw and writes no state. Architecture

predicate kind

One of eight shapes a predicate can take in workflow.yaml: tool, file, json_field, ledger, http, measurement, jury, signoff. Architecture

profile

site (all 15 steps) or app (no scaffold, no flows). Chosen at site-context.mjs init. The workflow, step by step

receipt

<site>/.claude/state/receipt.json: written only by verify-receipt.mjs audit after a real, pinned Lighthouse run grades within budgets.json. Valid 24 hours; must be newer than the build to publish live. Life-cycle of a run

run

One site's passage through the workflow, recorded in its run-state.json. Started by the first mutating gate command. Life-cycle of a run

sign-off

A named human approval recorded by site-step sign on commercial-review or legal-check. One predicate among several; closes nothing on its own. Life-cycle of a run

testimony

A record an actor writes about what it saw and judged — ux-review.json, the jury's ballots, brief.md, licences.json. The gate corroborates it against the build, the catalogue and freshness; it never simply trusts it. From idea to launch

workflow

workflow.yaml: the 15 steps with prerequisites, exit predicates and blockers. The source of truth for order — the skills describe the same pipeline in prose. The workflow, step by step

Numbers that recur

Number	Where
15	Steps in `workflow.yaml`. (The plugin's `CLAUDE.md` still says 14 in one place; the YAML is authoritative.)
23	Predicate files. Also the count of checks in `legal.mjs`.
31	Mandatory patterns: 16 dark + 15 legal, fingerprinted into every ux-review. (Two comments in the code still say 28; the predicate counts 31.)
656	Checks in `patterns/`, 22 files. (`CLAUDE.md` says 637, which is the upstream site-audit count before local additions.)
5 · 5	Lighthouse runs per measurement · maximum spread in points.
3 · 11 · 3	Jury scorers · dimensions · floor for every median.
4.5:1	Contrast for every declared pair, in both colour schemes, no large-text exception.
24 h	Receipt validity; waiver length.
20	Minimum characters for a blocker reason, a ux-review note, and the attestation's scopes text.
12.2.1	The pinned Lighthouse. A report from any other version is refused.