# Gates

How a change is verified here, and how to read a red you cannot reproduce alone.

## When the slate is complete

Nothing here runs while code remains to be written, unless explicitly asked ([AGENTS.md](../../AGENTS.md)): the one test
then is the journey walk (the life, the published examples and their coverage), and the one review the regression review
after every 30 commits of a build. When
the whole slate is written it is verified once, by the packages it touched and the checks below; findings reopen the
slate, and the checks run again when it is written. There is no CI; the checks run on the box that merges, and a report
states exactly which ran.

The tools and hook look for the pack repository and catalog index beside this checkout, then beside the main
checkout (found through Git's common directory). A worktree away from the main checkout uses those siblings.

**A pack** ([Creating a pack](./architecture.md#creating-a-pack), step 11), run from the packs repository's root with
`T` the twin-world checkout:

| check | holds |
|---|---|
| `bun $T/scripts/score-pack.ts <vendor> --write` | the life walked through the pack's fetch on a fresh World with every check (status, expectations, captures, shape, the beats) and a second World answering byte for byte the same; what the life and the vendor's published examples reach of the hand-written code and the declared states, with what no World reaches recorded in `journeys/unreachable.json`; the spec's breadth |
| `bun $T/scripts/branch-round-trip.ts <vendor>` | the round trip derived from the life (architecture, "Evidence"): a checkpoint changes no read, a branch starts where its base stands and keeps its own entries, a base that moves leaves the branch behind it, and a rebase moves it with no conflict and no entry lost |
| `bun $T/scripts/shape-parity.ts <vendor>` | what a local write stores and what the refresh adapter observes over the twin's own wire are the same subjects with the same fields; advisory until the descriptor says `shapeParity: 'held'`, nothing to compare without a refresh adapter |
| `bun $T/scripts/invariants.ts <vendor>` | the pack's row of the invariants matrix (R1 standalone, R2 mounts and makes its resources, R4 no host-derived path, R5 its doors answer, R6 listeners only in the server, R7 no hardcoded port, R9 two fresh roots answer the same beyond the World's own randomness, R12b no Bun-only API on the serve path), each cell passing or not applicable |
| `bun $T/packages/twin-standard/src/cli.ts conform <pack dir>` | the pack's conformance (architecture, "Conformance"): every served operation decided and every demanded or refreshed one served; every citation recorded and its quotes found; every stored resource's refresh declared and events ingested; every vendor-backed unit reaching the registered state system; a budget above the fallback on a cited allowance; served on its own by its `server.ts`, it answers HTTP and every declared socket upgrades |
| `bun $T/scripts/serve-check.ts <vendor>` | served by its `server.ts` as a World runs it (the World's boot id set), the pack answers HTTP and the World's boot probe, and each socket its manifests declare takes an upgrade (a walk drives the fetch directly and cannot see this) |
| one judging per pack ([What a judge rejects](./architecture.md#what-a-judge-rejects)) | the life is plausible to a judge that is not its author; the verdict stands, and the life's later changes keep it |
| one independent adversarial review per pack | a reviewer that did not build it, reading the pack against its spec, its demand and this architecture |
| `bun $T/packages/twin-standard/src/cli.ts grade <unit>` | the Protocol 3 standard's criteria, each with its reason |
| `bun $T/scripts/grades.ts <unit>... --write` (from twin-world, with the packs repository beside this or the main checkout) | the record of each named unit's grade, `generated/grades.json` and `generated/INDEX.md`, refused when a criterion the record holds as met no longer is. A contributor names their own pack's units; the slate's verification runs it with none named, every unit graded |
| the blind walk | an agent that has never seen the pack adopts it in an application (the company workspace's record) |

**The platform** (the kernel, the runtime, the tools): the touched packages' own suites (`bun test` in the package,
`bun run test` where it names one; started there, the run and every process it starts use that directory's
`.volter-test-home`, never the host's `~/.volter`: `scripts/isolated-home.ts`; a whole suite runs only with
`VOLTER_FULL_RUN=1`, which this slate's one verification sets: while code is written a run names the test files the change
touched, as paths, and `scripts/test-scope.ts` refuses a bare run, a directory, a name filter and more than eight files), their typecheck (`bun run typecheck` in the package: `tsc --noEmit`), the lint
(`bun run lint`: Biome, lint only; `biome.json` names every rule that is off and why), the docs (`bun run docs:check`:
every link resolves, the user docs use only the user glossary's words, and `scripts/docs-reference.ts` holds the reference
pages and the map to the code: every CLI verb and flag, every World method and export, every platform endpoint, every page linked; `packages/cli/src/journeys/tutorials.test.ts`
executes each tutorial page as written, against this checkout's packages and the pack repository's published to a
registry on the machine (`scripts/registry.ts`, with `scripts/hosted-stack.ts` and `scripts/issuer-stack.ts` behind the
pages that need them), and `bun scripts/docs-media.ts --check` finds each page's recording), `bun scripts/pack-standing.ts` when a pack changed (it writes twin-packs-p3's `STANDING.md` from the grade's form, by the gate; `--check` refuses a stale one), `bun scripts/pack-done.ts <vendor> --installed-assessment <report.json>` for a pack the slate takes to done (the one definition of done: it validates the installed evidence before the final source slate, then prints `DONE <vendor>` or the first failing step and its fix),
`bun scripts/p3-only.ts --check` in every change (it reads this repository, the pack repository and the catalog index, and
fails on any trace of an older protocol), `bun scripts/architecture-auto.ts --check` (the architecture's [auto] rules over
the kernel and every pack), `bun scripts/policy-check.ts --check` (`policy/human-required-paths.yml` fails closed, covers
every check and names only what exists; `policy/architecture-invariants.yml` is one-to-one with the architecture's rules,
`checked_by` exactly on the [auto] ones), `bun scripts/pack-hygiene.ts --check` (no NUL byte in this repository or a pack; a pack's CLI on the kernel's flag reader
and offering its server's options; a pack's imports declared by its own package and none private),
`bun scripts/rate-budget-check.ts --check` (every pack's declared rate budget accepted, unchanged, never free, never
more permissive than its vendor's documented allowance, which it declares and its manifest cites; one ledger per vendor), `bun scripts/packless-claims.ts --check`
(the packless-vendor registry, `world-runtime/known-external-services.json`, names no dependency or env stem a pack
adopts), and `bun scripts/pack-facts.ts` (the committed `world-core/generated/pack-facts.json` must be what it writes). The pre-commit
hook (`.githooks/pre-commit`) runs the last seven and `bun run docs:check` on every commit, regenerating and staging the facts.

**Not carried.** The older repository (`volter-ai/twin`) also ran a full gate, a per-package T0
(`verify-pack.ts`), the spec census, a nightly maintenance cycle and sharded T1/T2 runners. A gate a merge waits on and
a sharded CI runner have no place here (review and merge are local); T0's per-pack typecheck and tests are the grade's
executed criteria (`bun scripts/grades.ts --full`); a Protocol 3 pack's surface is its derivation's, not a census; and
catalog upkeep is the board's `catalog-maintenance-process` card.

## Reading a red

**The box is shared.** Other sessions can starve listeners or extend test deadlines. A red under load and a green
serial rerun are separate observations, not proof of a root cause. Retain both logs, check load and owned-process
identities, and reproduce the failing path. Persistent rate-budget ledgers can also affect repeat runs; isolate test
ledgers or wait for the window, never delete another actor's ledger to obtain a pass.

**A different package each run.** Changing failures can indicate resource contention, leaked listeners or a port
race. If a test receives a response its own server cannot produce, identify which process owned that port before
attributing the response to another service. Check `lsof -iTCP -sTCP:LISTEN -P -n | wc -l` first: compare the count
with the expected owned listeners and inspect lifecycle records before calling it a leak. The package named in the
failure may be a victim. Use the owning World's `down`/`prune` or the test's retained child handles for cleanup.

**Serving readiness.** Local World serving announces its URL and tokens after the mounted World finishes booting, as
the multi-world host does. The outer listener binds first so an occupied port fails before boot; until boot
completes, vendor routes answer 503. Tutorials that launch a server in the background expect its serving
announcement before using it.

**Bind scope.** A port free on `127.0.0.1` can conflict with another listener when a server binds `0.0.0.0`.
Automatic World port allocation probes the wildcard address used by the HTTP transport's default listener, with a
bounded search that fails on exhaustion. The probe is released before the child starts: it is not a held
reservation, so startup must still report a bind race rather than adopt another listener.

**Disk failures.** Check `volter-world resources` for actual filesystem free space and lifecycle ownership, then
preview `volter-world prune`. Declarations do not reserve capacity. Prune only eligible stopped instances with
verified teardown; do not stop another actor's World or delete its ownership evidence.

## Paths a machine may not change alone

`policy/human-required-paths.yml` lists them: the kernel packages, the doctrine documents, the policy files
themselves. A change to one is the owner's to approve. `bun scripts/policy-check.ts --check` holds the list honest.