Command grammar

Status: frozen design on 2026-09-27, from the operator decision of 2026-09-27. No implementation. The lead settles the open questions; a settled answer changes this file before code does. Remove this specification when the registry, the runner, the hooks, and CI run the grammar, and AGENTS.md, README.md, and the effect-house overlay describe it.

Handoff (2026-09-27)

The operator paused this slice for a handoff to a new lead. This section records the state at the handoff. Remove it when the open questions are answered and this file is landed.

• State. Design only. The branch docs/command-grammar-0927 holds this file in commits on top of main at b3193cb1. main was at 88b5281e at the handoff. The branch is not landed and not pushed.
• Next step. The lead answers the open questions and writes each answer into this file. Then the lead rebases the branch onto main and lands it with just land docs/command-grammar-0927. The branch changes only this file.
• After landing. Implementation starts when the schema collapse branch has landed and the landing queue is empty, in the window of the mono-web heavy-admit cutover (Cutover). Its first step is the registry and the runner with --plan, with falsifiers F4 to F9, F16, and F17 on a scratch repository. Hooks, workflows, and callers change only after that step passes.
• Review. Nobody has reviewed this file. No review finding is open.
• Known gaps for the review:
  1. The package test scripts of packages/domain and apps/dashboard also run fixture programs, D1 proofs, and the preview bundle gate (AGENTS.md, section Commands). This file does not assign them to test:unit or test:pg.
  2. The families come from the heavy-admit design, which is proposed. Its C2 family names can change before it freezes, and its queue order is an open operator decision.
  3. This file does not name the changed inputs of the two model targets. The obvious ones are docs/model/authority.als, docs/model/contexts.cml, and tools/scripts/model.ts.
• Verified:
  • The commit 45094472, which added this file: git commit exited 0 with the hooks on, after devenv shell -- true. hook-config-current, check-merge-conflicts, format, and source-safety passed, and lint skipped because no JavaScript or TypeScript path was staged. .oxfmtrc.json excludes docs/specs/, so the format hook did not examine this file.
  • A scan of this file outside code found no <, >, {, or } that MDX can read as markup.
  • E1 to E3: just 1.58.0 of the devenv shell, on scratch justfiles in /tmp, since deleted. Exit 0 for just check lint --staged and just check::lint --staged under mod check. Exit 1 for just check --staged under mod check, for a recipe named check:lint, for a module and a recipe with one name, and for just check::lint with a check *args recipe.
  • E9, E16, and E17: Turbo 2.8.13, the locked binary of the main checkout, in scratch repositories in /tmp, since deleted, and its source at tag v2.8.13 (commit 0c5af8fb). A research subagent ran these experiments. Nobody repeated them.
  • E8 to E10: the ledger on 2026-09-27, 3411 rows.
  • E4 to E7 and E11 to E15: the repository at 8d1b7e09 and b3193cb1.
• Not verified:
  • No implementation exists, so no falsifier (F1 to F18) exists or ran.
  • just docs build, which builds the site and checks its links, did not run with this file. just layout did not run; its mention check skips docs/specs/.
  • No pre-push or pre-merge hook ran on this branch.
  • The value of PRE_COMMIT_FROM_REF for a new branch (E7) was observed once, with prek 0.5.2.
• Decisions waiting. The lead decides open questions 1 to 11, and question 7 together with the heavy-admit lead. Questions 2 and 3 change an operator decision or the verification policy, so the lead decides whether they need the operator. The slice also waits for the schema collapse branch and for the heavy-admit design.

Goal

One grammar names every verification command, and one typed registry declares it. The justfile recipes, the Git hooks, the hosted CI matrix, the command tables, and the ledger classes derive from the registry. A derived file that differs from the registry fails a check, or cannot differ because it is generated.

Operator decision (2026-09-27)

conventions covers the layout, construct, guide, and Effect exception checks. model is the Alloy check, which is static. mutation tests the tests.

Evidence

Observed on 2026-09-27 at 8d1b7e09 and at b3193cb1, which adds the hook configuration check of 5f734424, unless the row names another source.

Grammar

just <verb> [<kind>] (--staged | --changed | --all) [--filter=<turbo filter>]... [--plan]
just <verb> <kind> <target> [--plan]

1. One selector. A command selects by one scope or by one target, never both and never neither.
2. Aggregate. Without a kind, the command runs every kind of the verb that supports the scope, in registry order. An aggregate takes no target and no --filter.
3. Order. The positional words come first, then the flags. Each flag appears once, except --filter.
4. One spelling. There are no aliases. The runner rejects -F, --filter <value> with a space, --affected, --, any other Turbo option, an abbreviated word, and a positional word after a flag. just itself rejects just check::lint (E3).
5. Package axis. --filter is valid only with a package-aware kind at --changed or --all. Turbo resolves each value, and several values form a union. A value that names a Git range ([…]) is a usage error, because the scope selects by change. Values that together select no package are a usage error.
6. Plan. --plan prints the resolved plan as JSON and runs nothing: the base commit, and for each step its entry, packages, files, argv, class, and family.
7. Exit status. A run exits with the status of the first failing step, and stops there. A command line that does not parse against the registry exits 64 and lists the valid words at the failing position. A tree that does not match the scope, or a base that does not resolve, exits 65 and names the cause (Exactness).

Syntax decision: positional arguments

The grammar uses two plain recipes, check *args and test *args, with set positional-arguments. Each passes its words to one runner, which parses them against the registry.

The first two rows decide. Modules give every command a second spelling that the repository cannot turn off, and they cannot express the aggregates that the hooks call. just 1.58 can validate recipe arguments with [arg(pattern=…)] and declare long options with [arg(long)]. The recipes do not use them: the runner parses and validates once, from the registry, and prints the help (just check --help).

Scopes

Selection modes

Each supported scope of an entry declares one mode.

lint is package-aware at changed because a type-aware rule in a dependent package can fail when a dependency's types change. Turbo selects the affected packages with their dependents, and one Oxlint process lints their directories after route type generation. The per-package lint scripts and the Turbo lint task go (E13), so the tree has one lint path.

Base commit of --changed

The runner resolves the base once:

1. TURBO_SCM_BASE, when it is set and not empty.
2. PRE_COMMIT_FROM_REF, when prek runs a push-style hook and the value is neither empty nor all zeros (E7).
3. main otherwise.

It then computes the merge base of that commit and HEAD, once. If either step fails, the run exits 65. It never falls back to every package, as Turbo does silently for some of these failures (E16). Turbo's package selection and the runner's path selection both use this merge base (Turbo mapping). The second rule corrects E9: a push of main compares with the remote state of main, not with main itself.

Exactness

• staged outside prek. The tools of files and tree entries read the working tree. If a selected path has unstaged changes, the run exits 65 and names the paths. During pre-commit, prek sets unstaged changes aside (E7), so the hook always meets this rule. safety reads index blobs and is exact in both cases.
• changed in pre-push. The push sends commits, but Turbo adds uncommitted and untracked paths to every selection, and every tool reads the working tree (E16). If HEAD differs from PRE_COMMIT_TO_REF, or git status --porcelain reports any path, the run exits 65. README.md already asks for a clean worktree before a push.

Turbo mapping

Turbo selects packages, never paths. The runner maps each scope as below, and it always runs Turbo from the repository root, because inside a package directory Turbo adds that package to every selector (E16).

...[<merge-base>], not --affected. Turbo documents --affected as --filter=...[main...HEAD], and with the base given as a merge-base commit the two selected the same packages in clean and dirty trees (E16). The explicit form wins on four points in 2.8.13:

1. It composes with the package axis. --affected with --filter exits 1 in 2.8.13 and intersects from 2.9.4 on, so one command line would change its meaning with the Turbo version.
2. It fails loudly. --affected selects every package with exit 0 when the base is missing or the history is shallow.
3. It reads the previous bun.lock at the merge base. --affected reads it at the tip of the base, which over-selects when main changed the lockfile after the branch point.
4. It never falls back to the default base main, which selects nothing when HEAD is main (E9).

Package axis at changed. The runner reads two selections from Turbo's dry run (turbo run <task> --dry=json, field packages): the change selection above, and the union of the --filter values. It runs the task over their intersection, with one --filter=<name> per package. Turbo 2.9.4 and later compute the same intersection for --affected --filter. An empty intersection is a step with nothing to do. turbo ls --output=json gives the same data, but 2.8.13 marks it experimental.

Selection and execution. The scope selects packages. Turbo still adds the tasks that dependsOn names, such as generate before check-types, and replays a selected task whose hash matches a cached run.

Root inputs. A path outside every package selects only the root package //, unless globalDependencies matches it (E17). The cutover adds tsconfig.json and vitest.shared.ts to globalDependencies: a change to either then selects every package, and it enters every task hash, which today it does not. check conventions fails when a workspace tsconfig*.json extends, or a Vitest configuration imports, a root file that globalDependencies lacks. An entry whose tool reads configuration outside the packages that it examines declares that configuration as widenOn: .oxfmtrc.json for format, oxlint.config.ts and tools/oxlint for lint, and tools/source-safety for safety. A change there makes changed select everything for that entry. A Turbo-task entry has no widenOn, because its root inputs belong in globalDependencies, where Turbo's cache sees them too.

Where Turbo cannot express a scope.

• staged, for every kind. Turbo has no index-only selection: [HEAD] adds unstaged and untracked paths, and inside prek's pre-commit the untracked paths still enter (E16). The runner reads the index.
• Paths, at every scope. format, safety, and lint at staged run on files, and Turbo 2.8.13 does not expose its list of changed paths. The runner repeats Turbo's Git queries with the same merge base.
• A pushed commit that is not checked out. Turbo tasks run on the working tree, so pre-push requires the clean tree of Exactness.
• A root file outside globalDependencies. It selects //, which runs nothing.

Kinds at cutover

The registry holds the kinds that have an implementation. duplication and surface join with their specifications (repository conventions, public surface), under the names and scopes below. mutation joins with a specification of its own. Until then, each is an unknown kind and exits 64.

The migration manifest is not part of conventions. The schema collapse branch deletes the numbered migrations, their checksums, the migration registry, just migration-hashes, and the upgrade proofs, and it lands before this cutover (operator decision, 2026-09-27). model has no all scope: its Alloy check takes about ten minutes (E10), so the pre-merge stage does not run it. The pre-push stage runs a model target when its inputs change, and CI hosts both targets. test unit and test pg replace the package test task. A test file that starts a real PostgreSQL cluster (E14) carries the suffix .pg.test.ts, and only the test:pg script of its package runs it. A lint rule rejects startDisposablePostgres, withDisposablePostgres, and apps/backend/test/postgres.ts in any other test file, with a negative control.

The registry

Location

The registry is tools/conventions/src/commands.ts, a typed declaration like layout.ts. It takes over the hosting declarations of journeys.ts: the journey recipes, own jobs, exclusions, evidence scripts, and run files. The run-file check of journeys.ts stays, and reads each target's argv from the registry instead of a case branch of the justfile. One runner, tools/scripts/commands.ts, parses a command line against the registry and runs it.

What an entry declares

The registry also declares, once:

• The stage table. pre-commit runs check at staged. pre-push runs check, then test, at changed. pre-merge-commit runs check, then test, at all.
• The CI aggregate steps. The Checks job runs just check --all. The Tests ts job runs just test --all on the default PostgreSQL major and just test pg --all on every other supported major.
• The operations outside the grammar that need a class or hosting. rehearsal (its targets, profiles, and hosting), and each other recipe that runs a heavy job, today build and migration, with a class and a family each.

Derived facts are never declared: the stages of an entry (from its scopes and the stage table), whether it is package-aware (a packages mode), whether CI hosts it (an all scope through the aggregate steps, or its target hosting), and its ledger classes.

Invariants

The types of the registry enforce these where they can, and a registry test enforces the rest:

1. Every entry supports all or has targets, and every target is hosted or excluded with its reason. So no check exists that nothing runs.
2. A family is a name of the closed heavy-admit set, or light.
3. A writer belongs to a check entry.
4. Verbs, kinds, targets, and operations are kebab-case and unique within their parent.

Derivations

Hooks

• The grammar hooks come from tools/conventions/hooks.json. Each hook runs one aggregate, so a new entry joins its stages through its scopes, and the file does not change.
• The configuration check and the stock conflict-marker check stay fixed in devenv.nix, as the exceptions that it already declares: the configuration check must not depend on the configuration's tools (E6), and the conflict-marker check is a stock prek hook.
• hooks.json joins hookSources in devenv.nix, so a worktree whose hook configuration came from another hooks.json fails with the instruction to run devenv shell -- true.
• The hook slots, the --concurrency=1 arguments, and the just measure wrapper of pre-merge go. Each heavy step admits itself with its family, and Turbo options are registry facts.
• Behaviour change: pre-push checks at changed, where it checked the whole tree. The pre-merge stage and CI still check at all.

CI

• The Checks job runs just check --all. The four separate convention steps go, because the aggregate runs conventions first.
• The Tests ts job runs just build, then just test --all on the default major, and just test pg --all on the other majors, where it filtered to two packages.
• The generated Tests matrix hosts one test or rehearsal target per leg. A leg keeps its current name, such as Browser journeys (e2e contact), so that no status name changes.
• A second generated matrix job in the Tests workflow hosts the check targets: check model authority and check model contexts, which no job runs today (E10). The Checks workflow stays the fast feedback of every push (checks.yml:3).
• The own jobs stay: golden-school-service (its CI wrapper accepts the exact-source evidence), identity-browser-evidence, and applicant-evidence. Each runs its target command.
• The steps of E11 that are not a target stay outside the grammar until a follow-up moves them (Open questions). The registry lists each one with its reason, and check conventions fails when a listed step no longer exists.
• No workflow passes Turbo options. CI has no admission tool, and the runner runs each step directly there (Admission and ledger).

Admission and ledger

The registry is the one client registry that the heavy-job admission design asks each project for (homelab docs/specs/2026-09-27-heavy-job-admission.md, C2, on branch heavy-admit-0927, proposed). Each step whose family is not light runs through the mono-web admission client with its class. The client maps the class to its family, queues, measures, and records one ledger row with the class and a label. The label is the full command line. A light step runs directly and records no row.

Classes. A scope step records <verb>-<kind>-<scope>, such as check-lint-staged. A target step records <verb>-<kind>-<target>, such as test-e2e-onboarding. An ad hoc slice of a kind, such as one Vitest file against PostgreSQL through just measure, records <verb>-<kind>, such as test-pg. An operation records its name, or <operation>-<target>, such as rehearsal-receipt-import. The class set is a closed union derived from the registry, and each class has exactly one family. just measure --class accepts only its members. A registry test fails when two classes are equal.

For the heavy-admit lead

1. Aggregate families. Each step of an aggregate admits itself, so mono-web uses neither the check nor the test family. Stage-level admission is the alternative: one ticket per hook stage, with nested steps (C8). It holds one large reservation through the cheap steps too.
2. hook family. Under the grammar it covers staged-scope and ad hoc lint only. Pre-push steps admit as lint, types, unit, and postgres, not as "a pre-push check at concurrency 1" (C2).
3. Calibration. The C2 provenance filters class names by pattern (E8 of that design). After this cutover, each class names one workload, so calibration can group by class.
4. CI. The mono-web cutover spec decides how CI runs without the tool (its point 6). This design needs one rule: the runner admits a step exactly when heavy-admit resolves on PATH, and no flag or environment variable of the runner changes that.
5. Hook jobs inside a job. A commit inside an admitted job runs its hooks nested (C8). Nothing in this design takes a second ticket for them.

Current surface and its new form

Recipes

Hooks, workflows, and package scripts

Falsifiers

Each row is a test of tools/conventions or tools/scripts, a scratch-repository test, or a hook run on a scratch branch. Scope tests build a scratch Git repository with four Bun workspace packages (a; b depends on a; c depends on b; d), root files, a main branch, a remote, and a feature branch, and read --plan.

Cutover

Sequencing. Start after the schema collapse branch lands and the current landing queue drains, because the rename touches the justfile, devenv.nix, both workflows, and every guide. Land in the same window as the mono-web heavy-admit cutover, before the next branch is cut. The collapse decides which proofs stay: authorization-rules reads the migration definitions and a migration proof today. The registry takes the target names that remain. If the homelab tool is not active yet, the runner's admission client keeps today's lock for that window: a hook family takes a hook slot, another family takes the exclusive lock, and light takes nothing. The heavy-admit cutover then replaces only the client.

One change, no aliases. One branch renames every caller, and no old recipe remains as an alias or a forwarding recipe:

• the justfile, devenv.nix (hooks and hookSources), hooks.json, turbo.json (test:unit, test:pg, no lint task, and tsconfig.json and vitest.shared.ts in globalDependencies), and the package manifests;
• the Checks and Tests workflows;
• README.md, AGENTS.md (the commands, verification, and landing sections, and the construction-over-trust precedents that name recipes), and STATE.md;
• .agents/skills/effect-house/SKILL.md and its references;
• docs/web-system-functional-testing.md, docs/module-developer-documentation.md, the construct pages, and every module guide, which just write conventions regenerates;
• the active specifications that name recipes to come: repository conventions (just duplication, just duplication --staged, just duplication baseline) and public surface (just surface), which change to just check duplication, just write duplication, and just check surface;
• the messages of tools/scripts (land.ts, dev.ts, changelog.ts, measure-job.ts, model.ts) and apps/dashboard/e2e/native-users-journey-seed.mjs.

Deletions. hook-slot.ts and the lock code go with the heavy-admit cutover. This cutover deletes the case dispatch of golden, e2e, proof, and rehearsal, the case parser of justfile.ts that only they feed, the --staged option of the conventions command line, the lint scripts and task, the package format scripts, and the tests that pin old recipe strings, such as tools/conventions/tests/layout.test.ts:89-91. A test that pinned wording is deleted, not moved to the new wording.

Turbo upgrades. The runner never passes --affected, so an upgrade past 2.9.4, where --affected --filter changed from an error to an intersection (E16), does not change what a grammar command selects.

Done when. F1 to F18 pass; the hooks run the grammar on a scratch commit, push, and merge; the Checks and Tests workflows pass on the cutover commit; and rg -n 'just (check-types|lint-files|source-safety|layout|constructs|guides|exceptions|migration-hashes|model|e2e|golden|proof|hook-slot|hooks)\b' finds nothing outside CHANGELOG.md and docs/specs/.

Open questions for the lead

1. Writers. This design adds just write <kind> for the check kinds that have a writer: format, conventions, and later duplication. It sits beside the grammar and derives from the same entries. The alternative keeps one writer per tool, which leaves layout, constructs, and guides as recipe names beside check conventions.
2. Rehearsal. The operator placed rehearsal outside the grammar, and it stays there, but its hosted names come from the registry. The alternative is a test kind, just test rehearsal <name>: a rehearsal verifies import code against a disposable database.
3. Pre-push at changed. The stage map narrows pre-push from the whole tree to the change. A direct commit on main then relies on prek's push base and on globalDependencies (E17). Pre-merge and CI still check at all.
4. Model. check model has no all scope, so landings do not run the ten-minute Alloy check. Pushes run a target when its inputs change, and CI hosts both targets. The alternative adds all, and every landing runs Alloy.
5. CI steps outside the grammar (E11). Proposed follow-ups: proof:receipt, proof:identity-postgres, and the focused auth-live test start their own cluster and become test proof targets and part of test pg; the two bun test files join test unit through test:unit scripts in tools/placements-docs and tools/e2e. The placements reference gate needs a decision: the operator's kinds include none for documentation.
6. Unhosted proofs (E12). After the schema collapse, each remaining proof becomes a hermetic test proof target, or it goes.
7. Admission granularity. Per step, as designed, or one ticket per hook stage. This question is shared with the heavy-admit lead (For the heavy-admit lead).
8. Admission before the homelab tool is active. Cutover keeps today's lock for that window. The alternative waits for the tool.
9. mutation. It needs a specification of its own: the tool, scopes, family, and hosting. If it supports all, every landing runs it.
10. surface and duplication. Implement both under the grammar names after this cutover, so that nothing is renamed twice. Their specifications change in the cutover change.
11. just hooks. It goes, because each stage is its grammar commands. prek run --hook-stage <stage> in devenv still runs the literal stage configuration.

Rejected alternatives

• just modules. Two spellings for every command and no aggregate (Syntax decision).
• A package selector of our own. Turbo's filter syntax and --affected already select by name, dependents, dependencies, directory, and Git range. A second selector would need its own graph and could disagree with Turbo's.
• A separate stages field per entry. It would repeat what the scopes and the stage table already fix, and the two could disagree. An entry that must not run in a stage does not support that stage's scope, and a target hosts it instead, as model shows.
• Per-package Turbo lint processes. Each process builds its own TypeScript programs for type-aware rules. One Oxlint process over the Turbo selection builds them once.
• Scope defaults. A default scope would make just check lint and just check lint --all two spellings of one command, and a default hides the caller's intent.