Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

This page shows how to check a receipt's hashes against the repository, find every receipt that covers a file, write a new receipt skeleton, census the drafts awaiting acceptance, take a draft to an acceptance receipt, and read the readability report. Both tools are tested repository scripts (scripts/receipt-check.ts, scripts/readability.ts), not archive scripts. There is no npm script for either tool, so run them with node.

Check one receipt

node scripts/receipt-check.ts check docs/<name>-receipt.json

Receipt shapes are not uniform (docs/agents/factory-model.md section 7): some pin source and test hashes under files or final_sources; some hash only review and browser evidence under evidenceSha256. The checker does not guess which field holds paths. It treats a JSON object as a hash map only when every value is a 64-character hex string, wherever the object sits in the receipt.

A 64-character hex string that sits anywhere else, such as a lone scalar field or a value beside non-hash fields, is never silently dropped. The report lists every one of these as unattributed (field path and value, with no path to check it against), and the receipt's shape is partial whenever unattributed is not empty, even when some other field in the same receipt is a recognised map. A receipt with no hash anywhere, recognised or not, is shape: "unknown". Unknown is never reported as trivially matching, and an unattributed hash is never silently ignored (Factory rule 1). Unknown is never zero.

A map key that is a label rather than a file path is reported as missing; that does not establish a lost file.

For each path a recognised map holds, the report gives one of five states:

StateMeaning
matchesThe file exists and hashes the same
changedThe file exists and hashes differently
missingNo such file exists: the path, or an ancestor directory, is confirmed absent
unreadableThe path exists but is not a readable regular file, most often a directory, or its existence cannot be established because of a permission or I/O error, such as an inaccessible parent directory
not-checkedThe path is a symbolic link (never followed, so it can never hash a file outside the repository), or is outside the repository: absolute, escaping through .., or under <local evidence directory>, which holds ignored session evidence, not stable repository content

Exit status:

  • 0: every checked path matches, unattributed is empty, and no path is unreadable.
  • 1: no unattributed hash and nothing unreadable, but at least one path changed or is missing. A changed path is not always a fault: receipts are history, so an old receipt's files are expected to have moved on since.
  • 2: the shape is unknown or partial, or at least one hashed path is unreadable. This is never conflated with an ordinary mismatch: unknown or unreadable means the tool could not fully account for the receipt's hashes, not that it found and confirmed a difference.
  • 64: invalid arguments or JSON, or a refused new request (including an empty file list).
  • 70: any other error, such as the receipt file itself not existing.

Find what covers one file

node scripts/receipt-check.ts coverage src/repository.ts

Lists every docs/*-receipt.json that hashes the given path, with its state. This read-only report exits 0 and never changes a receipt. Receipts that cannot be read or parsed appear in unreadable, with a reason. An unreadable hashed file has its own entry state; it does not make its receipt unreadable. An empty coverage list therefore retains gaps in receipt coverage.

Write a new receipt skeleton

node scripts/receipt-check.ts new --out docs/<name>-receipt.json --files <path> [<path> ...] [--base <commit>] [--component <name>]

The command writes:

  • each given file's SHA-256;
  • base: the given commit, or the current git rev-parse --short HEAD, or unknown outside a Git repository;
  • branch: the current Git branch, or unknown;
  • component: the given name, or the output file's own name with -receipt.json removed;
  • the fixed disposition implemented-awaiting-independent-review;
  • an empty review list.

The command checks every file before it writes anything. It refuses, and writes nothing, in five cases: the file list is empty; the output already exists; a given path leaves the repository; a given path is a symbolic link, directly or through a symbolic-linked ancestor directory; a given file cannot be read. The same escape and symbolic-link checks apply to --out itself and --files, so the command can never write outside the repository, even through a symbolic-linked ancestor directory the destination path passes through. It never edits an existing receipt; a fresh review still adds a new one, kept alongside the old as history.

Census the drafts awaiting acceptance

node scripts/receipt-check.ts drafts [dir]

Checks every *-draft.json in dir (default docs) the same way check checks a receipt, and reports one entry per draft as JSON. Pinned paths resolve against the working directory, so run it from the repository root. Each entry gives the draft's schema, disposition, status and scope fields where present, the hash-map shape, and counts of matching, changed, missing, unreadable, outsideRepository, linked and unattributed pins. A linked pin is inside the repository but reached through a symbolic link; it is never followed. It also lists the changed, missing and unreadable paths, and every *-receipt.json in the same directory that names the draft in one of its parsed JSON strings (a key or a value). Only a complete name counts. A name with a letter, digit or any of . _ - ~ @ + straight before it, or with a longer name or path straight after it, is another file. So docs/sample-draft.json/child, docs/sample-draft.json.bak, docs/sample-draft.json~ and sample-draft.jsoné never name sample-draft.json. A full stop, comma, bracket, quote or colon after the name still counts. A bare file name (sample-draft.json or ./sample-draft.json) names any draft with that file name. A name with a directory names the draft only when that path, resolved against the working directory as pinned paths are, is the draft's own path, so archive/sample-draft.json never names docs/sample-draft.json. A name after a backslash, or a written path longer than 4,096 characters, names no draft.

Each draft has one state, in this order of precedence:

StateMeaning
changedAt least one pinned repository file now hashes differently. The draft no longer describes the current bytes
missingNothing changed, but at least one pinned path does not exist. The path may be a removed file or a label; the census cannot tell which
unknownThe draft could not be read or parsed, is not a regular file or is over the limits below, or it holds no hash, an unattributed hash, an unreadable or linked pinned path, or no repository pin matched
currentEvery checked repository pin matches and nothing is unknown. Paths outside the repository are counted, never checked, as in check

A draft or pinned file that cannot be read is unknown, never current. The receipt reference is referenced, not-referenced, or unknown when no readable receipt names the draft but some receipt could not be read or parsed; those receipts are listed in unreadableReceipts. Text in a receipt that is not valid JSON never counts as a reference. The census reads each draft and receipt once, and only as a regular file: a directory, symbolic link, FIFO or device is refused without waiting on it. It refuses any file larger than 4 MiB, nested deeper than 64 levels or holding more than 100,000 JSON values, and never reads or searches part of it. Such a receipt is listed as unreadable; such a draft is unknown with its reason. Every draft is still reported. The output holds no time or machine state, so two runs over the same tree are byte-identical. The census is advice only: it writes nothing and exits 0. It exits 64 for invalid arguments and 70 when the directory itself cannot be read.

current means only that the pinned bytes still match. It is not acceptance, a Verdict or proof of release or customer value.

From draft to acceptance receipt

A draft records a Candidate's evidence while it awaits acceptance. Acceptance adds a new receipt; it never edits the draft.

  1. Run the census. A changed, missing or unknown draft needs fresh evidence first: rerun its checks on the current bytes, or record a new draft for the current Candidate. Never accept a stale draft as it stands.
  2. Freeze the Candidate: record its commit and the hashes of every file the acceptance covers. current in the census means those hashes still match the repository.
  3. Obtain independent review of that frozen snapshot from the reviewer already designated by the current working agreement. If no reviewer is designated, resolve that consequential choice; the implementer never supplies its own independent acceptance.
  4. Complete the required source, installed-consumer, documentation and CI gates for the claimed scope. Partial acceptance names its exclusions. Mint a new receipt for the accepted files with receipt-check new --out docs/<name>-receipt.json --files ..., and record the review and its evidence in that new receipt before it is committed.
  5. Record exact commit/package integrity, report identity and hash, commands and outcomes; reconcile build review, inventory and canonical status. Never rewrite a draft or an old receipt. Both are history: a later receipt supersedes them by naming them, and the census then shows the draft as referenced.

Read a readability report

node scripts/readability.ts [root]

The Node tool follows the archived Python script and counts the same files: README.md, AGENTS.md, CLAUDE.md, handover.md, and docs/*.md, docs/agents/, docs/guide/, docs/brand/, docs/ui/design-system.md, docs/tutorials/, docs/how-to/, docs/explanation/ and docs/reference/. The columns show words, prose words outside fenced code and table rows, sentence count and length (mean, 90th percentile, the share over 30 and 50 words), the share of words in tables and in fenced code, second-person words, sentence-initial imperatives, and words that date a claim. root defaults to the working directory, so run it from the repository root. The report supports review. It marks a file it cannot read as unavailable, and the command always exits 0.

Source: docs/how-to/check-receipts.md