Factory model — combined agent reference

Read this once to orient, then drill into the module references in this directory. It uses the Factory's one language and British spelling. Checked against the source at 574e70c on 28 September 2026, then updated for the dashboard brand increment merged from main at f5a8991, which changes no file under src/, for the Producers module (branch factory/producers), accepted on its independent implementation review (Astra round 9 PASS) with both live transports unavailable, and for step 1, increments 1–2 (Repository Assurance, Product gate and delivery records; branch factory/delivery, merged with main at d7e4001), accepted on their independent implementation review (Astra round 6 PASS) and composed into nothing, and for step 1, increment 3 (Repository collector, same branch), accepted on its independent implementation review (Astra round 2 PASS) and composed into nothing, and for step 1, increment 3b (the additive guard on Repository invokeOnce, same branch), accepted on its independent implementation review (Astra round 2 PASS) and composed into nothing, and for lifecycle increment 0 (branch factory/lifecycle, from e62abe6), which changes only src/intelligence.ts (planned declarations for the proposed lifecycle design) and passed independent review (Astra round 2 PASS), and for lifecycle increment 1 (branch factory/lifecycle-schedule, from 217887b), which adds the Lifecycle schedule (src/lifecycle-schedule.ts) and moves its declaration into MODULE_INTELLIGENCE, and passed independent review (Astra round 4 PASS), and for lifecycle increment 2 (branch factory/lifecycle-sources, from 217887b), which adds the Discovery sources collector (src/discovery-sources.ts, src/discovery-text.ts), moves its Intelligence declaration into the accepted list with its files, and passed independent review (Astra round 5 PASS), and for the merge of lifecycle increments 0–2 with main (branch factory/lifecycle-merge), which changes in src/intelligence.ts only where the step-planned declarations render (the Intelligence reference, not the README), and for increment 1 of the Service access module (branch factory/service-access, from main at 985b5f9), built on test fixtures and revised after an adversarial test pass and Astra round 1's FAIL, provisionally accepted — Fable 5.1 (max) round 1; Astra review pending (Codex usage limit until 2026-10-03 18:00) (Fable round 1 PASS, <local evidence archive>; from 3 October 2026 the highest-numbered <local evidence archive> report holds the verdict), and for its merge with main (branch factory/service-access-merge), which adds its declaration to src/intelligence.ts without moving a line the lifecycle cites (the Intelligence reference; independent review pending); the module references, the build review and the receipts under docs/ are the evidence behind every claim here. Where older prose and observed behaviour disagree, trust observed behaviour and accepted receipts.

Verification: independent Astra reviews of this model, AGENTS.md, CLAUDE.md and the docs site are archived at <local evidence archive>; the corrections from rounds 1–9 are applied here, and the highest-numbered report holds the current verdict.

1. Purpose and current truth

• Purpose. Turn customer needs into small, independently verified improvements across several Products, and keep them healthy (design, values). Agents act on behalf of a domain; they are never the system of record.
• What exists. Accepted local infrastructure only: the independently accepted modules in section 3 (fifteen references and sixteen accepted build review rows besides Producers: the review splits Repository into sealing / export, integration and the integration guard seam, and joins Project guidance with Required actions) in one Node.js application over local SQLite and Git, on one macOS host. Intelligence, accepted later, is not counted there, nor are the lifecycle's two modules or Service access below; each has its own build review row (Intelligence since lifecycle increment 0). Producers is accepted as code under independent review, but both of its live transports are unavailable and nothing composes it (section 3). Repository Assurance and the Product gate and delivery records are accepted as step 1, increments 1–2; only tests call them. The Repository collector is accepted as increment 3; only tests call it. The repository guard seam is accepted as increment 3b; nothing in src/ passes a guard. Delivery composition, the delivery CLI and the live Slice (increments 4–8) are not built. The Lifecycle schedule (lifecycle increment 1) is implemented on fixtures with a fake clock and passed independent review (Astra round 4 PASS); only tests call it, and nothing runs on a schedule. Discovery sources, lifecycle increment 2, is implemented, tested offline against a loopback corpus and accepted locally on independent review (Astra round 5 PASS); nothing composes it. Service access increment 1 (a names-only catalogue of Service kinds, Service map and readiness, on test-made fixtures) is built and provisionally accepted — Fable 5.1 (max) round 1; Astra review pending (Codex usage limit until 2026-10-03 18:00) (Astra round 1 FAIL, fixed; Fable round 1 PASS; from 3 October 2026 the highest-numbered <local evidence archive> report holds the verdict); it reads no live source and nothing composes it. The proposed production stack (Temporal, PostgreSQL) is a proposal; nothing of it runs here.
• What does not exist. No active CI: .github/workflows/check.yml is configured on the private origin chrismitchelmore/software-factory but waits for a runner (hosted minutes are blocked by billing; a self-hosted Mac runner needs the owner). No production, pilot, release or customer (older prose calls the fixture path a "local pilot"; it is local synthetic-fixture infrastructure, not a pilot). No provider transport is qualified: the Producers module is accepted, but Claude's rules revision 5 needs re-qualification (the revision-4 live check decided unavailable) and OpenAI has no Platform credential. No nightly or weekly automation is active. No composed Product gate (the gate exists, but nothing calls it), Action gateway or planner, and no Assessment of any real Slice (delivery records can derive one; nothing has).
• All 27 customer-value epics (E01–E27) remain open. Accepted modules, brand artwork and documentation close none of them (outcome map).
• Last accepted full verification (build review): strict typecheck, 350/350 tests with none skipped, frontend build, and real desktop and 390 px browser checks. The later dashboard brand increment (0ab94ed–7b499ea) is recorded only in the handover: Astra high PASS on round 2, root 355/355 and dashboard package 10/10 tests; it has no receipt or build review row. The Producers acceptance (Astra round 9 PASS, <local evidence archive>) rests on 397/397 focused offline tests run locally and Astra's own 128/128 read-only tests and 32 in-memory probes; it is not a live transport qualification (344/344 at qualification time, Claude receipt). The step 1, increments 1–2 acceptance (Astra round 6 PASS, <local evidence archive>) rests on 73/73 increment tests and a 428/428 full check on the pre-merge base f5a8991; after merging main at d7e4001, the full check passes 851/851 with none skipped. At that merge one boundary test was adapted so that the Producers module may import its own contract; that change is not independently reviewed. No receipt or reference review exists for them yet. The step 1, increment 3 acceptance (Astra round 2 PASS, <local evidence archive>) rests on 50/50 focused tests run locally (collector, adversarial, delivery boundaries and Repository Assurance, none skipped) and Astra's own read-only typecheck, boundary tests and placement probes; the full check then passed 881/881 with none skipped. Test counts describe the tested boundary, not release or customer value.
• Six Products are registered for metadata inspection only (JustSpeakToIt, Pasta, Family Watch, Tally, Focus Sentinel, Factory). Their state is <local Portfolio journal> (ignored, local data): preserve it and never re-run onboarding to recreate it.
• Canonical changing status is the Notion Factory record linked from handover; the active task capsule is .intent/tasks/local-factory-completion.md.

2. Domain language as used in code

One line per term. Status says how far the term exists in src/: implemented, narrow (real but limited), pinned only (an identity string, no behaviour) or designed, not implemented.

3. Module map

Arrows are real import statements between src/ files, grouped by module. A dotted arrow is a type-only import or an HTTP call. factory-support.ts, local-factory.ts and cli.ts are composition files and belong to Guarded verification's reference.

flowchart LR
  subgraph records["Records and runs (plate 1)"]
    CJ["Command journal<br/>journal.ts · canonical-json.ts · errors.ts"]
    EA["Evidence / Assurance<br/>evidence.ts · assurance.ts"]
    EX["Execution<br/>execution.ts"]
    LW["Local fixture worker<br/>local-worker.ts · fixture-child.ts · fixture-gate.ts · fixture-manifest.ts"]
    AF["Attempt fence / workspace<br/>attempt-fence.ts · attempt-workspace.ts"]
    GV["Guarded verification / recovery<br/>guarded-verification.ts · attempt-ledger.ts · factory-support.ts"]
    LF["Local factory CLI<br/>local-factory.ts · cli.ts"]
  end
  subgraph delivery["Isolation and delivery (plate 2)"]
    CE["Confined executor<br/>confined-executor.ts"]
    RP["Repository sealing / export and integration<br/>repository.ts"]
  end
  subgraph visibility["Visibility (plate 2 and unplated)"]
    PF["Portfolio<br/>portfolio.ts · portfolio-inventory.ts"]
    PG["Project guidance<br/>project-guidance.ts"]
    AT["Required actions and blockers<br/>attention.ts"]
    DC["Dashboard contract<br/>dashboard-contract.ts"]
    DS["Dashboard server and view<br/>dashboard-server.ts · dashboard-view.ts"]
    BA["Browser app<br/>apps/dashboard/src"]
  end
  subgraph providers["Providers (accepted; live transports unavailable)"]
    PR["Producers<br/>producer.ts · claude-producer.ts · openai-producer.ts"]
  end
  subgraph access["Service access (increment 1; not composed)"]
    SA["Service access<br/>service-access.ts · service-discovery.ts · service-kinds.ts"]
  end
  subgraph core["Delivery core (step 1, increments 1–3; not composed)"]
    RA["Repository Assurance<br/>repository-assurance.ts"]
    GD["Product gate and delivery records<br/>product-gate.ts · delivery-records.ts"]
    RC["Repository collector<br/>repository-collector.ts"]
  end
  subgraph lifecycle["Lifecycle (increments 1–2; not composed)"]
    LS["Lifecycle schedule<br/>lifecycle-schedule.ts"]
    DSC["Discovery sources<br/>discovery-sources.ts · discovery-text.ts"]
  end
  EX --> CJ
  LW --> EA
  LW --> AF
  GV --> EX
  GV --> AF
  GV --> LW
  GV --> EA
  GV --> CJ
  LF --> GV
  LF --> EX
  LF --> EA
  LF --> LW
  LF --> CJ
  RP -->|canonical JSON only| CJ
  RP -->|snapshotDigest| CE
  PF --> CJ
  PG --> CJ
  PG --> PF
  AT --> DC
  AT -.->|types| PF
  DS --> AT
  DS --> DC
  DS --> PF
  DS --> PG
  DS --> CJ
  BA --> DC
  BA -.->|HTTP, loopback| DS
  PR -->|canonical JSON only| CJ
  PR -->|types and limits only| RP
  RA -->|canonical JSON only| CJ
  RA -->|SNAPSHOT_PROTOCOL only| CE
  RA -->|PIN_FIELDS, isStoreRecord| EA
  RA -->|parseRepositoryIdentity| RP
  GD --> CJ
  GD -->|parseFenceIdentity only| AF
  GD --> RA
  GD -.->|types| RP
  GD -.->|types| EA
  RC -->|run, runtime and profile| CE
  RC -->|EvidenceStore| EA
  RC -->|pins and observation encoding| RA
  RC -->|validatedHoldIdentity| AF
  RC -->|canonical JSON only| CJ
  RC -.->|types| RP
  RC -.->|SnapshotManifest type| GD
  LS -->|journal and canonical JSON| CJ
  DSC -->|journal and canonical JSON only| CJ
  SA --> CJ
  SA -.->|Count and coverage types| PF

Facts the graph cannot show: only the Repository collector calls ConfinedExecutor.run, nothing in src/ calls the collector, and nothing in src/ calls repository.seal; the src/ importers of repository.ts are the Producers contract (src/producer.ts, for FileEdit, Proposal, SourceFile and REPOSITORY_LIMITS), Repository Assurance (parseRepositoryIdentity and types) and the Product gate, delivery records and Repository collector (types only); nothing in src/ or apps/ imports the Producers module, and nothing outside the delivery core (Repository Assurance, the Product gate and delivery records, and the Repository collector) imports any of its four files; nothing imports the Lifecycle schedule; nothing imports Discovery sources, and it imports only the Command journal, canonical JSON and Node built-ins; tests compose Repository with the executor (one in the Repository suite, and the collector's suite, which seals real Candidates and runs them). Nothing in src/ imports the three Service access files. npm run factory never starts the dashboard. The Dashboard's repository check is Portfolio.inspectProduct over an existing checkout, not Repository integration. Command IDs are journal-wide, so every module's prefixes must stay distinct.

Reference review. Each accepted module's agent reference, except Producers, Repository Assurance, the Product gate, the Repository collector, Intelligence, the Lifecycle schedule, Discovery sources and Service access, was checked independently against the source by Astra (gpt-6-astra, high effort); the reports are under <local evidence archive>, and the highest-numbered report for a slug holds its current verdict. Every one of those references has a PASS report: Execution, Local fixture worker and Required actions (round 3); Command journal, Project guidance and Repository (round 4); Attempt fence, Guarded verification and Portfolio (round 5); Confined executor, Dashboard and Evidence / Assurance (round 6). Producers was accepted on its implementation review instead: rounds 1–8 FAIL and round 9 PASS (<local evidence archive>; the current verdict is <local evidence archive>). Its agent reference has no separate reference-review report yet. Repository Assurance and the Product gate and delivery records were likewise accepted on their implementation review: rounds 1–5 FAIL and round 6 PASS (<local evidence archive>); their agent references have no reference-review report yet. The Repository collector was accepted on its implementation review, after an independent adversarial pass, rounds 1 FAIL and 2 PASS (<local evidence archive>); its agent reference has no reference-review report yet. Intelligence was accepted on its implementation review, rounds 1 FAIL and 2 PASS (<local evidence archive>); its agent reference has no reference-review report yet. The Lifecycle schedule passed its implementation review likewise, after an independent adversarial pass: rounds 1–3 FAIL and round 4 PASS (<local evidence archive>); its agent reference has no reference-review report yet. Discovery sources was likewise accepted on its implementation review: rounds 1–4 FAIL and round 5 PASS (<local evidence archive>); its agent reference has no reference-review report yet. Service access (increment 1) is provisionally accepted — Fable 5.1 (max) round 1; Astra review pending (Codex usage limit until 2026-10-03 18:00): Astra round 1 FAIL, Fable 5.1 interim round 1 PASS (<local evidence archive>), and from 3 October 2026 the highest-numbered <local evidence archive> report holds the verdict; its agent reference has no reference-review report. A reference review checks the documentation, not the module's behaviour or acceptance.

Each accepted module has one labelled position on one of two brand plates; Project guidance, Required actions, Producers, Repository Assurance, the Product gate, the Repository collector and Intelligence have no plate position yet, and neither have the Lifecycle schedule, Discovery sources and Service access (increment 1). Show a plate whole, name the position in text, and never crop it.

4. Lifecycle: what exists and what is planned

The designed loop is Need → Slice → Candidate → Verdict → Receipt → Assessment. The middle of it runs today only for four synthetic fixtures. Everything in the Planned column comes from the handover next steps 1–4; none of it is accepted, and nothing here claims otherwise.

Proposed, two parts built: discovery and post-development. The lifecycle design (Astra round 3 PASS on the design only) would add nine modules: scheduled discovery of public Sources, triage into Signals and Clusters, at most five Opportunities a week that a rule-first gate admits, parks or rejects, a weekly owner bundle with single-use Action grants, release drafts with a claim trace, outcome validation and Capability retirement. Increment 0 adds only their planned Intelligence declarations; increment 1 builds the Lifecycle schedule on fixtures (Astra round 4 PASS; nothing composes it); increment 2 builds the Discovery sources collector (Astra round 5 PASS), which runs only against a loopback corpus, and nothing schedules or reads it; increments 3–11 build the rest on fixtures before any live run, and every owner decision in its §11 is open. It depends on step 1's delivery composition (its A12).

5. Cross-cutting invariants every agent preserves

Each line names where the rule already lives, so a change can be checked against it.

1. Unknown is not zero, and not failed. Portfolio Counts are exact only under declared complete coverage; the Dashboard renders unknown as —; Assurance folds a timeout, signal, collector error or missing reference to Inconclusive; the executor's unresolved and Repository's unknown are neither failed nor done.
2. A historical Verdict is not current validity. Guarded verification shows historicalVerdict as issued and recomputes currentValidity from the Evidence and the source digests now; any source drift invalidates without rewriting the Run.
3. SQLite and Git (or any provider) are never one transaction. Journal commands wrap no external effect; Repository's claim, target move and receipt are separate single-ref updates with no crash atomicity claimed; the journal's replay avoids re-running the decision only, so a caller's other effects can repeat.
4. An unknown effect never permits a blind retry. invokeOnce throws only before submission and never downgrades unknown to "not applied"; after a lost acknowledgement, repeat the same command ID with identical inputs (journal, Execution, guidance, Product gate) and let the replay say whether it committed. The Product gate blocks every later integration of a Product while one is null or unknown, and its REPLAYED answer is history, never a permit.
5. The implementer is never the verifier, and output has no authority. The worker and the executor observe and never judge; a producer's passed flag, printed control text or exit claim never changes admission or a Verdict; hand-built records never qualify; Opus builds, Astra verifies.
6. Products stay isolated. One repository binds to one Product; a Candidate manifest includes its repository identity; guidance is never copied between Products; the executor denies reads of another Product's files; usage is attributed once and never moves; the Product gate keys every record, ID and pin by Product, so one Product cannot integrate with another's Candidate, proof or store; Service access (increment 1) binds each repository and vault to one Product and hashes the Product into every reference id.
7. Everything is bounded; input limits refuse rather than truncate. JOURNAL_LIMITS, EXECUTION_LIMITS, worker and executor bounds, REPOSITORY_LIMITS, PORTFOLIO_LIMITS, GUIDANCE_LIMITS, DASHBOARD_LIMITS, REPOSITORY_ASSURANCE_LIMITS, GATE_LIMITS, RECORD_LIMITS, SCHEDULE_LIMITS and (Service access, increment 1) ACCESS_LIMITS bound what modules accept, and oversized input is refused, not cut short; so does DISCOVERY_LIMITS (lifecycle increment 2), for fetched bodies, items and Captures. Presentation is capped instead: the worker and the executor keep a bounded prefix of process output, report the overflow and request termination (local-worker.ts:601-612, confined-executor.ts:1022-1031); diagnostic and error messages are shortened to fixed lengths (for example DASHBOARD_LIMITS.maxMessageLength); an attention item lists at most MAX_WINDOWS (5) source windows. A Budget is never extended; recovery loops have round counts; there are no leases, heartbeats or takeover by time.
8. No human gate for self-solvable work. Attention infers nothing: empty guidance, unresolved verification, dirty files and zero counts make no item; ownerRequired needs a source that names the owner and an exhaustion; a missing fact is never an owner approval request.
9. Never weaken tests, acceptance or pins. Drift blocks dispatch by design; never re-pin silently; never relax a corrupt check; a stored-shape change is a protocol revision, not an edit in place; a reused command ID with other content is a conflict, not an update.
10. Validate before writing, fail closed, and never adopt, recreate or repair silently. Validation order is module-specific: modules check input before writing, but journal open configures WAL before it detects missing tables (journal.ts:161-162, :354-357; see command journal). Missing or replaced fences and repository roots are refused, never recreated, and the executor quarantines a changed namespace. For journals, openExisting and openReadOnly refuse a missing file while open may create one, and storage identity is not fenced: a valid replacement journal is accepted. Cleanup is non-recursive and anything uncertain is quarantined and reported.
11. Local proof is not release, and neither is customer value. Fixture recovery is not customer-release recovery; a merge, an upload, a screenshot or a green suite establishes nothing about availability or benefit; all 27 epics stay open until their own evidence closes them.
12. Plumb is editorial. The character belongs in docs, onboarding and calm empty states; in the dashboard the mark sits beside the wordmark and Plumb appears only on an empty Portfolio that a successful current read confirms is calm (calmEmptyPortfolio in apps/dashboard/src/brand.ts); failures, security, destructive actions, blockers, privacy, spend, uncertain effects, Verdicts and Assessments use plain words, no character, no colour-only meaning (brand guide).

6. Trust scope summary

Condensed from the module references. Every established item holds for trusted local code on one macOS arm64 host with Node 26.8.1, a local POSIX filesystem and process-crash tests.

Established locally

• Atomic, idempotent journal commands under real process races and SIGKILL on either side of a commit; openExisting and openReadOnly refuse foreign, corrupt, empty or missing stores (open refuses foreign or unknown schemas but creates or initialises a missing or empty one); read-only inspection that initialises nothing.
• Content-addressed Evidence that survives a killed writer; Verdicts that producer flags and hand-built records cannot forge.
• One owner per Attempt under racing claims; stale reports refused; durable cancellation decided by commit order alone.
• Real bounded fixture processes with an explicit environment; fence-held admission; drift refusal; quarantine instead of claimed cleanup.
• Recovery from controller death at every protected boundary within the pinned Budget, including actual CLI crash recovery, with one fresh payload per epoch and no resurrection of terminal Runs.
• A stateless sandbox boundary with tested denials of writes, foreign reads, network, subprocesses and signals, judged from host-side evidence with negative controls.
• Exact sealing and export with fail-closed handling of corruption and forged manifests; one integration invocation per intent across repeats, concurrent processes and kills, with truthful unknowns and read-only reconciliation; a native HEAD.lock tolerated, never taken.
• Metadata-only registration of six local Products with checkouts left unchanged; globally deduplicated usage; exact, partial and unknown Counts that never collapse to 0.
• A loopback-only dashboard whose reads never write or run Git, with Host, Origin and token guards, two guarded commands, and checks at desktop and 390 px widths; decorative brand placement tested by the root suite and the dashboard package's rendered read states (no receipt, and no browser check of it is recorded).
• Revisioned guidance with exact replay, stale refusal and immutable pins; source-derived attention with no inferred gates and no resolve route.
• Service access increment 1 (test-made fixtures only; provisionally accepted — Fable 5.1 (max) round 1; Astra review pending (Codex usage limit until 2026-10-03 18:00), as above): names-only discovery that opens no deny-listed path, reads no line inside a workflow or env-template value and no text inside a manifest's string, an expression's literal or a comment as a name, records no path, name or identifier shaped like a credential, and, for every position and form its canary, adversarial and regression suites plant, records no value in any journal byte, event, view, answer or error (evidence for those forms, not proof for every construct); absence only from a complete, authenticated, non-empty listing and a use that shows where the name resolves (never from an unknown environment, a reusable workflow or a file not scanned whole), and an environment job's name resolved only through a conclusive listing of its environment; exclusive bindings under racing processes, one repository per Product; readiness that is presence, never validity, and says when only the owner can act.
• At module level, with no composition: Product gate admissions linearised against revocation in real processes, ownership passed only by fence proof, integration refused unless its Verdict re-derives inside the decision and its Candidate stays inside the Slice's scope, separate allowance counters and refusal of corrupt state; repository-scope Verdicts over store-written records that refuse fixture proof and omitted or forged records; create-once delivery records.

7. How agents work here

Commands (Node 26.8.1, npm 11; dependencies are already installed; the root has no runtime dependency, and apps/dashboard has its own manifest and lockfile that the root suite never needs):

npm run check                                   # strict typecheck + node:test suite (the final stage runs it; do not run mid-task unless told)
npm --prefix apps/dashboard run build           # browser typecheck + Vite bundle; restart the server afterwards (assets load at startup)
npm --prefix apps/dashboard run check           # build, then the dashboard package's own tests (apps/dashboard/test)
node src/dashboard-server.ts --journal <local-portfolio-journal> --port 4317   # loopback only; check whether a server already owns the port
npm run factory -- verify pass --run-id demo-pass --state-dir .factory         # fixtures: pass, fail, hang, noisy; then inspect / cancel / recover
rm -rf site && npm run docs                     # regenerates site/ from docs/ (the build only creates files; it refuses a differing site/); commit site/ with any docs change (test/docs-site.test.ts fails on drift)

Focused suites per module are listed under each reference's Changing it safely. Test fixtures use disposable journals and repositories, never <local Portfolio journal> or a registered checkout. Bulky logs and regenerable output go under <local evidence archive>, never /tmp.

Worktrees. Parallel producers work in separate worktrees under <home directory path>, each on its own branch from main. Never edit the main checkout or a worktree another coordinator owns; touch only the files assigned to you; node_modules is symlinked, so install nothing. Preserve dirty work, <local Portfolio journal> and the ignored evidence under <local evidence directory>. Do not commit unless told.

Review protocol. Opus 5.5 implements (exact claude-opus-5-5; report the effort actually used and never substitute a model silently). Fable 5.1 collaborates on documentation, review and composition. Astra (gpt-6-astra) verifies independently, for example codex exec -m gpt-6-astra -c model_reasoning_effort=high ...; the accepted reviews in the build review record Astra at xhigh. Prove each component before composing dependants, and refine an interface when an observed failure reveals a weakness. A module is complete only when independent verification, its docs/agents/<slug>.md reference and its docs/guide/<slug>.md page all exist and the docs site is rebuilt.

Receipts. Each acceptance has a receipt under docs/*-receipt.json, but they are not uniform. Some pin source and test hashes directly (files or final_sources); some hash only review and browser evidence (evidenceSha256, often files under the ignored <local evidence directory>); guidance relies on a source-hash list that is not in Git. Before saying a module's current files are covered, compare its receipt's actual coverage with the files now; each module reference says which receipt still matches. Any edit to a covered file makes that coverage stale: get a fresh independent review, add a new receipt (never rewrite hashes in an old one), and update the build review row, the module's narrative section and its references. Keep old receipts as history.

Local-only authority. Only the coordinator pushes verified main to the private origin; CI runs deterministic checks only, never a model, sign-in or secret. No production change, public release, customer account, advertising or broader credential. Registration permits metadata inspection, not delivery. Do not extract OAuth credentials, infer Platform API access from a sign-in, or substitute a transport or model. Resolve self-solvable blockers within existing authority and keep independent work moving; escalate only a genuinely unavailable decision, access or resource, with what was tried.

Writing. British spelling, the one language above, and the brand voice: warm and brief where calm, plain where it matters. Never overclaim: say accepted local scope, say what is not established, keep unknown distinct from zero, and never call an epic complete, a release safe or a customer helped without the evidence.

8. Design language

Read this before building or changing any UI or docs page. The design system is Factory · Plumb (version 1790613544-ec35), iterated in Claude Design; its link is in the Notion status, not in this repository. docs/brand/tokens.json is the canonical copy of its tokens, byte for byte as exported; design language says where each token goes and how to re-sync.

• Tokens only. Use the token names and values (--ink, --blue, --space-4, --radius-md, --rail-width, --focus and the rest). Add no colour, family, type size, spacing, radius, shadow or layout size that is not a token, and never edit tokens.json by hand: change the design system, then copy its export over. The design system has no token for a reading measure or a minimum width yet; the docs site names its few such measures once (SITE_MEASURES in the builder), and its only other lengths are 1 to 3 px lines and offsets.
• Light only. One theme. Add no dark scheme and invent no dark palette until the design system has one.
• Colour. Flat surfaces: no gradients, glow, texture or raised shadows. blue is for links and the one primary action per view. ok, warn and problem mean status only, on their status grounds, always beside a word and never in artwork; ok is for icons and borders, not text. rail, rule and select are decorative, never the only boundary or state.
• Type. The sans and mono system stacks, no font files; weights 400, 500, 650 and 750 only; the named type styles (page-title once per view, body, supporting, code and the rest). The wordmark is live text, never an image.
• Space and shape. Spacing space-1 to space-12 (4, 8, 12, 16, 24, 32, 40, 48 px) with nothing in between; radii radius-sm, radius-md and radius-lg (4, 6, 8 px), and nothing is a pill. Controls are control-height; targets are at least touch-min. At 1280 px and below the rail is 224 px and the inset 32 px; at 960 px and below the rail becomes a top bar and the inset 20 px.
• Focus. Every control shows the focus ring, the only shadow, on keyboard focus; links and linked rows show a 3 px blue outline.
• Status. Always a word, never colour or an icon alone. Unknown is an em dash with its reason, never zero.
• Plumb. Docs, onboarding and calm empty states only, at illustration size, below the words, never replacing them, never clickable, with empty alt text when the words carry the meaning. Never in tables, metrics, navigation (the mark excepted), decisions, blockers, failures, spend or unknowns. The mark is never below mark-min, and the favicon stays favicon.svg. Module plates are shown whole, never cropped; nicknames are captions only.
• Voice. Warm, brief and curious, in British spelling and the Factory's domain words; plain words for limits, status and anything that matters; no emoji, exclamation marks or hype. The say-and-not table is in the brand guide.

How parity is tested. test/design-tokens.test.ts fails when tokens.json stops being one light theme with system fonts, and reads both stylesheets and the docs' drawings with allow-lists, so a value it does not know fails. The allow-lists cover colour, type, radius, spacing, shadow and outline; custom properties and var(); resets; at-rules; the responsive values at 1280 and 960 px; and the drawings' elements and fills. The design language lists the rules; scripts/render_docs.py draws the diagrams from tokens.json. Its mutation cases show each check failing on altered copies. test/docs-site.test.ts checks the site's status words, notices, Plumb placement and whole plates on every page. After any UI or docs change, run node --test test/design-tokens.test.ts test/docs-site.test.ts and rebuild the site.

Where it is iterated. Visual changes start in Claude Design (link in the Notion status) and reach this repository only through a re-sync of tokens.json, followed by the stylesheets that use it.