commands.md

# CLI command reference

This page is generated from the abcd command tree by `GenerateReference` in
`internal/surface/cli`. It is a derived artefact: do not edit it by hand. A
drift test regenerates the tree and fails the build whenever this page and the
tree disagree, so the reference can never silently go stale. Regenerate it with
`go generate ./internal/surface/cli`.

Every user-facing command is listed with its sentence (what it does, what it
writes, and when it refuses), its usage line, and its flags; the
operator-internal hook entrypoints are omitted.

## `abcd`

Render the status board, or say what one record id is and its next move: Writes nothing; refuses any other positional argument.

**Usage:** `abcd [<record-id>] [flags]`

Agent-based configuration for development.

Bare `abcd` renders the read-only status board — what can I do. A single
positional matching a record id (`iss-N`, `itd-N`, `spc-N`, `adr-N`, `dcn-N`,
`adm-N`, `srp-N` or `rfm-N`) instead reports what that record is, where it
lives, and the next move for its lifecycle state — what is this. N is either
a short ordinal from before ids were minted or the sixteen-digit stamp minted
since; both resolve. The bare and the id form are strictly read-only; any
other positional is refused as an unknown command.

`--version` reports the running binary's version, install mode and vintage.
When that binary sits in a plugin root other than the one this session
resolves, the report — like bare `abcd ahoy` — adds a `superseded_root` note
naming both roots by the commit each was installed from; the version, vintage
and staleness it reports are unchanged.

**Flags:**

```
      --agent           with --help, list the verbs agents and hosts call as well, each naming the page to read next
      --format string   the board's form: text (the default) or markdown, a list a host session pastes unchanged
      --json            emit machine-readable JSON on stdout; a refusal is a {"abcd":"error","error":…,"exit_code":…} object on stdout too, and exits non-zero
      --no-color        render the banner and the board without color
      --version         print abcd's version, install mode, and vintage, from disk alone (the release check is: abcd update --check)
      --view string     the board's view: product (the default) or facilitator
```

### `abcd ahoy`

Detect abcd's install state and list its gaps, or report one mode a flag names: Writes nothing; refuses any argument or two modes at once.

**Usage:** `abcd ahoy [flags]`

**Flags:**

```
      --dry-run     print the detection result as its JSON envelope, whether or not --json is passed
      --identity    check git's commit author and committer against the identity you recorded on this machine, exiting non-zero when either diverges or is a machine identity (for a pre-commit hook or CI)
      --providers   explain the optional OpenAI-compatible provider adapter, list the providers configured on this machine and where a key can live
      --remote      audit this repository's GitHub settings against abcd's baseline, one line per setting, and say what the remote apply sub-verb would change
```

#### `abcd ahoy connect`

Verify a provider and configure it, or guide setup: Writes ~/.abcd.noindex/ and the key's home, nothing guided; refuses no --model off a terminal.

**Usage:** `abcd ahoy connect [<provider>] [flags]`

**Flags:**

```
      --answer string       with --guide and --resume: the answer to the question the resume object leaves open
      --base-url string     the provider's OpenAI-compatible base URL: https, or http to a server on this machine
      --env string          for --home external: the environment variable that holds the value
      --field string        for --home external: the dotted field of --file that holds the value (auth.token)
      --file string         for --home external: a tool's JSON configuration file under the home directory, written from ~/
      --guide               work the values out one question a turn and print the command to paste into a terminal; writes nothing, and the provider name is optional
      --home string         where the key lives: external (--env, or --file and --field) | abcd (read from stdin, hidden at a terminal, into the owner-only ~/.abcd.noindex/credentials.json) | keychain (read from stdin, hidden at a terminal, into the platform keychain) | none (a server that takes no key)
      --key string          the credential's name (default: the provider's name)
      --model stringArray   a model the provider may serve, repeated for each (the first allowlist; the verification call asks for the first); omitted at a terminal, the service's models are listed with the key and you pick one
      --resume string       with --guide: the last turn's resume object, or - to read it from stdin
      --stream-usage        whether calls ask the server for usage in the stream (stream_options.include_usage), written into the block as stream_usage; omitted, the verification asks, and a server that refuses it is asked once more without it and the block is written with false (default true)
```

**Example:**

```
abcd ahoy connect local --base-url http://127.0.0.1:8080/v1 --model example-model --home none
```

#### `abcd ahoy credential`

List the credentials abcd reads, explain one, or verify and store it: Writes the chosen home only with --home; refuses a value the adapter's call fails.

**Usage:** `abcd ahoy credential [<name>] [flags]`

**Flags:**

```
      --env string     for --home external: the environment variable that holds the value
      --field string   for --home external: the dotted field of --file that holds the value (auth.token)
      --file string    for --home external: a tool's JSON configuration file under the home directory, written from ~/
      --home string    where the credential lives: external (--env, or --file and --field) | abcd (read from stdin into the owner-only ~/.abcd.noindex/credentials.json) | keychain (read from stdin into the platform keychain)
```

#### `abcd ahoy doctor`

Report every install gap, user-scope state included: Writes nothing; refuses any argument.

**Usage:** `abcd ahoy doctor`

#### `abcd ahoy install`

Apply the install gaps the detection finds: Writes .abcd/, the name-guard hooks and the PATH entry, and installs a tool only on a yes; refuses a stale binary.

**Usage:** `abcd ahoy install [flags]`

**Flags:**

```
      --adopt                   adopt an unmanaged repo without prompting
      --allow-stale-binary      proceed even when the running binary is stale against its source tip or its vintage cannot be determined; the default is to refuse before any write and name the rebuild fix
      --answered-in string      where an answers-file entry that names no place was answered: Terminal, or the host whose question tool asked it, as its plugin page passes; recorded with each answer (default "Terminal")
      --answers string          answer the setup questions from this answers file (JSON: schema_version, interview "setup", answers by question id), wherever the install runs; a question the file and no flag answers refuses with exit 2, naming its id, the flag and the file key
      --attribution             opt this repo into the committed prepare-commit-msg prompt asking every commit to declare whether a tool assisted it; the choice is recorded, so a later install without the flag keeps the hook
      --bin-dir string          directory for the PATH entry (default ~/.local/bin, or an existing abcd install adopted in place); fails when it is not writable — abcd never escalates privileges
      --details                 print the full record after the report: core's summary of every write and every note, each path written, the declined kinds of change and the gaps left
      --dev                     track-latest dogfood mode: the PATH entry rebuilds from the source tip on every call instead of pinning the built binary
      --docs-target string      whether AGENTS.md carries the managed block, which names abcd: agents_md | skip (default skip); claude_md and both are refused, with the one setting to change
      --install-tool strings    answer yes to installing this missing tool (repeatable): the answer a host's question tool relays; without it a tool is installed only on an answer typed at a terminal, never on the approve-everything flag, a piped answer or CI
      --live-sessions string    answer the live brief session question: where sessions may run, local, cloud or both, or none, which answers no and is not asked again; stored in .abcd/config.json as sessions.live and honoured in any run, the approve-everything flag included; abcd session setup then does the setting up
      --only-waiting            ask only the setup that waits after an abcd update: the questions this repository never answered and the settings whose default changed, never one answered or deferred with decide later; every kind of change is approved up front, as the yes to the offer abcd update news makes approves them; with the approve-everything flag no question is answered, so each still waits
      --oracle-backend string   oracle backend: host-delegated | native | cli | api | mcp
      --outbound                opt this repo into both outbound checks, which refuse a live agent-session URL or a tool attribution footer: the committed commit-msg hook over every commit message, and the shell guard's check of the title, body and body file a posting gh pr or gh issue command hands the forge, which also refuses a pull request body (gh pr create, new or edit) with no Assisted-by line in an accepted form, or one carrying a Co-authored-by line; it also sets this clone's git config --local abcd.binary to the abcd copy whose build provenance it verified and, where no core.hooksPath is set and no commit-msg hook is there, writes abcd's copy of that hook into the clone's git hooks directory, and says so when it cannot do either; the choice is recorded in .abcd/config.json as outbound.hook and outbound.forge, so a later install without the flag keeps both
      --readme-parts string     answer the README question: the parts of README.md abcd keeps current, comma-separated from licence, links, contents, release-badge, build-badge and abcd-badge, or none, which answers no and is not asked again; stored in .abcd/config.json and honoured in any run, the approve-everything flag included
      --refuse-adopt            decline to adopt an unmanaged repo
      --scan-deep string        enable deep scan: true | false
      --visibility string       repo visibility: private | public
      --yes                     approve every resolvable change category without prompting; excludes recording who you commit as on this machine (asked only at a terminal), the status line and the model-tier routing tables, which need an answered prompt (run without --yes, or answer every prompt with: yes | abcd ahoy install); it never changes the repository's git identity, which is proposed only to a person at a terminal
```

#### `abcd ahoy remote`

Apply abcd's GitHub settings baseline: Writes nothing bare, only the settings, rulesets and their mirrors through apply; refuses an unknown sub-verb.

**Usage:** `abcd ahoy remote`

##### `abcd ahoy remote apply`

Apply every GitHub setting the remote audit finds differing: Writes those settings, abcd's own rulesets and their mirrors; refuses an unconfirmed run.

**Usage:** `abcd ahoy remote apply [flags]`

**Flags:**

```
      --yes   confirm the remote change without being asked (never the install of a missing gh); without it an unanswered run declines and changes nothing
```

#### `abcd ahoy uninstall`

Remove abcd from this repository, leaving .abcd/ in place: Writes the removal of the marker block, PATH copy, and provenance record; refuses any argument.

**Usage:** `abcd ahoy uninstall [flags]`

**Flags:**

```
      --bin-dir string   directory holding the PATH entry to remove; needed only when it was installed with --bin-dir into a directory that is not on PATH
```

#### `abcd ahoy worktree`

List this repository's worktrees and its lane in the worktree store: Writes nothing; refuses a store it cannot trust or a directory outside a checkout.

**Usage:** `abcd ahoy worktree`

##### `abcd ahoy worktree add`

Add a worktree in this repository's lane of the worktree store: Writes the worktree, its start record and its local tier; refuses a taken or reserved name.

**Usage:** `abcd ahoy worktree add <name> [flags]`

**Flags:**

```
      --branch string   check out this existing local branch instead of making a new one
```

**Example:**

```
abcd ahoy worktree add example-lane
```

##### `abcd ahoy worktree list`

List this repository's worktrees and its lane, or every lane with --all: Writes nothing; refuses a store it cannot trust or a directory outside a checkout.

**Usage:** `abcd ahoy worktree list [flags]`

**Flags:**

```
      --all   walk every lane in the worktree store on this machine
```

##### `abcd ahoy worktree prune`

Reclaim this lane's merged, clean worktrees, archiving their notes first: Writes the notes archive and removes the worktrees; refuses a store it cannot trust.

**Usage:** `abcd ahoy worktree prune [flags]`

**Flags:**

```
      --dry-run           archive and remove nothing; report what a real run would
      --yes stringArray   reclaim this quiet candidate too (repeatable); a name not in the lane refuses the run
```

### `abcd announce`

Post a fixed-form announcement on the shared remote: Writes one commit to your status branch; refuses free text, a record not yet public and an embargoed one.

**Usage:** `abcd announce <kind> <item> [flags]`

abcd announce <kind> <item> [--expires-in <duration>]

Post a short fixed-form announcement on the shared remote, so every other
session sees what this one is doing. The kind is one of merging, merged, asking, answered, handed-over;
the item is the record it concerns (iss-N or itd-N) or a pull request (#N, or
the bare number, since a shell reads #N as a comment). --expires-in sets how
long it stands (default 30m, from 1m to 24h). An announcement carries no free text: a
question points at the item, and the conversation happens there.

The announcement is one commit that changes no file on your own status branch,
abcd-status/<your holder id> on the remote named origin, carrying the kind,
the item, you as sender (your holder id), this working copy, the time sent and
the expiry. The verb lists the status branches on origin (git ls-remote),
fetches each one named by a holder id or a lower-case GitHub username (the
names announcements had before the holder id, still read), with origin's default
branch, then makes one plain fast-forward push with the repository's hooks
running. A push that lost a race to another of your sessions is rebuilt on the
new tip and pushed again, up to three times; then it says "not sent" and why.
Nothing is ever forced.

A record must already be on origin's default branch, since an announcement is
public; a record the embargo store on this machine holds is refused, and so is
every announcement when that store cannot be checked. The sender is your holder
id, as reserve's holder is (`abcd reserve --holder` prints it), so no
announcement carries your GitHub login; the account is still worked out as
reserve's is: from user.email when it is a GitHub no-reply address, then
reservation.github_username in the machine configuration, then the session's
forge token, asked whose account it is. When git's identity is not a person's,
the token's account authors the announcement, and the identity git had is
shown nowhere.

abcd's own pushes announce first through this same code: abcd land, and a
build or drain lane's landing, post "merging <item>" and push only once it is
on origin. A push typed by hand with git push posts no announcement.

Exit 0 when the announcement reached origin; exit 2 on every refusal, when it
was not sent, and when a push was made but whether it landed cannot be told.
Nothing is pushed on a refusal except "not sent", which follows pushes origin
refused; the unknown outcome says a refused push may still have reached origin.

**Flags:**

```
      --expires-in duration   how long the announcement stands, from 1m to 24h (default 30m)
```

**Example:**

```
abcd announce merging iss-2609010000000001
```

### `abcd banlist`

Render both banned-names layers: Writes nothing; refuses an unknown word without echoing it.

**Usage:** `abcd banlist`

#### `abcd banlist add`

Add one banned-name entry to the layer a flag names: Writes that layer's store; refuses without exactly one of --private or --public.

**Usage:** `abcd banlist add --private|--public <key> <pattern|-> [flags]`

**Flags:**

```
      --private            the gitignored per-machine layer (.abcd/.work.local/private-names.txt)
      --public             the committed, CI-enforced layer (.abcd/docs-lint.json)
      --severity string    public entry severity: blocker (default) | warn
      --successor string   public entry's replacement, cited in the finding (default "a generic term")
```

**Example:**

```
abcd banlist add --private acme-internal 'acme-internal\.example\.com'
```

#### `abcd banlist list`

Render the banned-names layers, private entries by key only: Writes nothing; refuses --private and --public together.

**Usage:** `abcd banlist list [--private | --public] [flags]`

**Flags:**

```
      --private   the gitignored per-machine layer (.abcd/.work.local/private-names.txt)
      --public    the committed, CI-enforced layer (.abcd/docs-lint.json)
```

#### `abcd banlist migrate`

Key a legacy private store in place, every line matching what it matched: Writes the private store; refuses when no private store exists.

**Usage:** `abcd banlist migrate`

Convert a legacy private store (.abcd/.work.local/private-names.txt with no
'# abcd-banlist: keyed' first line, every line a whole-line pattern) to the keyed
format: the declaration becomes line 1, and each pattern keeps its exact bytes under
the key the guard already names it by, entry-<its line>. Comments and blank lines
survive. add, remove and `abcd library sync-banlist` refuse a legacy store with entries
until it is migrated. A keyed store is left alone. No pattern is printed.

#### `abcd banlist remove`

Remove one banned-name entry from the layer a flag names: Writes that layer's store; refuses a public entry curated by hand.

**Usage:** `abcd banlist remove --private|--public <key> [flags]`

**Flags:**

```
      --private   the gitignored per-machine layer (.abcd/.work.local/private-names.txt)
      --public    the committed, CI-enforced layer (.abcd/docs-lint.json)
```

**Example:**

```
abcd banlist remove --private acme-internal
```

### `abcd build`

Start the loop that takes one READY intent to delivered: Writes the run's state and its reservation; refuses an open question, a hold or a peer holding it.

**Usage:** `abcd build <itd-N|iss-N> [--auto-plan] [--session <id>] [--pace <work-minutes>/<pause-minutes>] [--sub-agents <n>] [--fix-rounds <n>] [--take-over] [--release] [flags]`

Start the implement loop for one intent, or resume the run already in progress for it.
An issue id starts the loop's issue-keyed lane instead (below).
A new run's checks run first, and every one must pass:
the intent is READY (planned, criteria written, its spec linked and written), asks no
open question, has no unanswered claim section, is not held, names no unsettled blocker
in `blocked_by`, its spec leaves a step to build, and no peer holds it (no sibling
worktree or local branch holds it in another bucket having changed it since its
merge-base with this checkout, so a branch holding this checkout's older copy
untouched does not count; no session holds a live claim on it; and no other copy holds
a reservation on it on origin, as this checkout last fetched the reservations; a peer,
claim or view that cannot be read, or a copy that cannot be compared, counts as holding
it). The check reads the reservations from disk alone, and names another copy's with
its holder, its expiry and the view's age; this copy's own is never a holder. A refusal
names the check, the reason and the remedy, and writes nothing. `abcd build next` picks
the intent instead of taking one named.

In a checkout with a remote named origin, the run reserves its key there, as
`abcd reserve` does, once the checks pass and before the run is created: a new run, and a
resumed one, with the files the spec's `## Footprint` packages line names (an issue's
found_at path for an issue id), so every other participant sees it is taken. A spec with
no footprint, or an issue with no found_at path, is refused at the reservation and nothing
is started. Another person's reservation, or your own from another copy, refuses
the start as contention; --take-over moves your own live reservation from another copy
to this one, never another person's. `abcd implement step` renews the reservation, fences
the landing's push and its arming with it and releases it once the run lands; a run
whose issue lane is handed
back releases it then. --release pushes the tombstone over this copy's reservation on the
key and changes nothing in the run's state: a later step meets it at the land fence, and
`abcd build` again reserves it anew. --release takes no other flag. The reservation needs
your GitHub username, read from a no-reply user.email or from
reservation.github_username in ~/.abcd.noindex/config.json.

When the checks pass, the run is created in this checkout's local tier,
`.abcd/.work.local/run/<run-id>/state.json`: one lane for the spec's first unlanded step,
the other unlanded steps pending, and the run record's first line. The tier itself is
never created: only a repository abcd manages has one. Starting again while the run is
in progress creates nothing and names the run without judging the checks again (the
run's own lanes change what they read), so a killed process resumes where it stopped.

--session names the host session's id in the shared run state (`abcd implement join`):
a new run then claims the intent there for that session, the run id as its lane, so a
build of the same intent from any other checkout of the repository is refused as held
before this run's lane has moved or claimed anything, and the session's own claim on the
intent is not counted as a peer's. A session that has not joined is refused. Without it
the run holds no claim, and the result says so.

A new run is paced: a working window, a pause after it, a ceiling on the run's lanes and
validators alive at once, and the fix rounds a lane may take before it is handed back. The
four numbers are read once, when the run starts: --pace <work-minutes>/<pause-minutes>,
--sub-agents <n> and --fix-rounds <n> for this run, else pace.work_minutes, pace.pause_minutes,
pace.sub_agents and pace.fix_rounds in the repository's .abcd/config.json, else in
~/.abcd.noindex/config.json, else the bundled 120/0 (no pause) with 2 sub-agents and 3 fix rounds. The result and the run
record name each number's layer. A malformed pace or ceiling, typed or configured, is
refused naming the value and the accepted form, and writes nothing. Starting again keeps
the run's pace; a flag naming another is refused. The window, the pause and the ceiling
bind through `abcd implement step`, which hands out work only while a slot under the
ceiling is free. A lane whose validators still do not pass after its fix rounds is
handed back: it stops as unachievable with the last round's findings, the run starts nothing
further for it, and `abcd implement step` refuses naming the hand-back.

A new run reads its review set once, too: review.reviewers (one or two model classes per
code-review role, for both roles or per role; bundled: middle and below), review.judge (a
class; refused until a judge agent clears itd-81's calibration gate) and, from
~/.abcd.noindex/config.json alone, review.max_reviewers (1 or 2, bundled 2) and the class map
models.classes (top, middle, below, smallest, each a <provider>/<model> route over the
bundled map). A repository list above the machine's ceiling is clamped with one line on
stderr naming both files; a repository's ceiling or class map is skipped with a warning.
An unknown class or a malformed set is refused at the review stage and writes nothing.
The result's review and the run record name each class with its model and each layer.

The run then moves one step per `abcd implement step`, driven by the host session.

The runner configuration is read before the run is created: roles.<role>.runner (host,
the default, or a runner) and the runners this machine enables under runner.<name> in
~/.abcd.noindex/config.json, each model route admitted against its provider's allowlist. A fault,
a model route the allowlist does not admit included, is refused at the runner stage and
nothing is created or launched. Only a route in ~/.abcd.noindex/config.json hands a role to a
runner, which spends the person's own key: one the repository's .abcd/config.json sets to
a runner is skipped with a warning on stderr, and the role runs on the host as if unrouted.
One it sets to host keeps the role on the host over a runner route in ~/.abcd.noindex/config.json,
since that spends nothing of the person's, with a warning naming both routes.

The budget check runs last, once every other check passes: each runner a role of the
run is routed to is asked for its remaining quota, in agent runs, and compared with the
run's estimate on it (per step to build, one implementer and one round of the two
reviewers, and the fidelity audit once for an intent). An estimate over a runner's
quota is refused at the check budget, naming both numbers, and nothing is written. A
runner that reports no quota, the host included, is named and the check is skipped out
loud; neither shipped runner reports one. The result's budget line and the run record
say which.

An issue id (iss-N, validated by shape) is built as one lane. Its checks are the
repository's own drain rule, read as `abcd drain` reads it (the issue is open, nothing
open blocks it, its category and severity are ones the rule takes, it carries a remedy a
person wrote), and no peer holding it. The brief is the issue's record with its remedy
as the work and the repository's definition of done (a detector watched to fail before
the fix and pass after); the validators run without the fidelity audit (an issue has no
criteria); the implementer's receipt must name the issue in `resolves`, and the landing
resolves it with the commit named there. A receipt carrying `handback` in its place
ends the lane: its worktree and branch are discarded and the issue is handed back by
kind. `abcd drain` starts these runs one at a time.

--auto-plan plans a draft intent with no person present, on the substitute for the
product thinker's sign-off adr-2610310235000654 records. The draft must carry its criteria,
ask no open question, answer its claim sections (a scope condition not yet stamped passes),
be one plan takes (kebab-case slug, no spec_id set), carry `pursued:` as its last ground no
run's pick wrote, carry an origin and production_mode from the vocabulary, not be held and
name no unsettled blocker, and no peer may hold it; a draft short of any is refused naming
the row, and nothing is written. Those rows check that the record is complete, not who wrote
it: for a draft an agent wrote end to end, the two reviews are the only gate. The run's one
lane hands the draft to two fresh ruthless-reviewer agents in turn, one for design and
feasibility and one for record discipline, always on the host, and the loop records each
verdict from its return. A review that does not pass, a draft whose bytes changed, or a
checkout that changed since the start, hands the lane back with the draft unplanned.
Once both pass, the plan stage checks the substitute again and runs `intent plan` in this
checkout, as a person's plan does, and the run is complete: the spec's steps, the commit and
the build of the planned intent are separate acts. The run reserves the draft's two paths and
releases them when its lane ends. On an intent already planned the flag has nothing to plan
and the run builds it; on an issue it is refused. `abcd intent plan` stays the human's act.

Exit 2 on a refusal, exit 3 when a peer holds the intent or the run state is locked
(back off and take other work).

**Flags:**

```
      --auto-plan           plan a draft intent with no person present, after two plan reviews, on adr-2610310235000654's substitute for the sign-off
      --fix-rounds string   the fix rounds a lane of this run may take before it is handed back, a whole number from 0 (bundled: 3); wins over every configured layer
      --pace string         this run's working window and pause, <work-minutes>/<pause-minutes> (e.g. 90/240); wins over every configured layer
      --release             push the tombstone over this copy's reservation on the key, changing nothing in the run's state
      --session string      the host session's id in the shared run state; a new run claims the intent for it
      --sub-agents string   this run's ceiling on lanes and validators alive at once, a whole number; wins over every configured layer
      --take-over           move your own live reservation on the key from another copy to this one; never another person's
```

**Example:**

```
abcd build itd-2609010000000001
```

#### `abcd build next`

Pick the readiest planned intent and start its run: Writes the run's state and the reason as the lane's first commit; refuses when nothing passes the checks.

**Usage:** `abcd build next [--session <id>] [--pace <work-minutes>/<pause-minutes>] [--sub-agents <n>] [--fix-rounds <n>] [--max <n>] [--until-empty] [flags]`

Pick the readiest planned intent, write down why, and start its run.

The candidates are the planned intents that pass every check `abcd build <itd-N>` runs
(READY, no open question, no unanswered claim section, not held, no unsettled blocker in
`blocked_by`, a step left to build, no peer holding it), less one this checkout already has
a run in progress for. Each is scored from its record, three parts at equal weight, each 0
to 100: criteria clarity (the share of its acceptance criteria in Given-When-Then form), a
test path (its spec's `## Footprint` names tests) and the expected footprint (100 divided by
the packages that section names). A part whose section is absent reads zero, and the
reason says the spec carries no footprint. The readiest is taken; the oldest among equals,
and the reason then says the tie was broken by age.

The pick starts the run `abcd build <itd-N>` would start for that intent, with the pick in
the run's state. The reason is one `pursued:` grounds entry opening `picked by run <run-id>
on <date>`: every candidate with its score, the rule, the runner-up and why it lost, and the
falsifier. The lane's worktree stage appends it to the intent in the lane's own worktree and
commits it there as the lane branch's first commit, record-only, before the brief; the
receipt verifier does not count that commit as the implementer's. That commit is made as
your own git makes one: the repository's hooks run, and a hook that refuses it refuses the
stage; it is signed where your git configuration signs every commit; and staging the entry
passes it through the repository's clean filter, as Git LFS needs. A commit still waiting
after ten minutes on a signing prompt or a hook is stopped and refuses the stage, naming
the deadline. The checkout you run this
in is never written but for the run state. `abcd intent ready` keeps reporting the person's
entry as the most recent conjecture.

One pick by default, and nothing picks again once it is delivered. --max <n> (above 1) or
--until-empty begins a series instead, kept in .abcd/.work.local/run/next.json: one move
per invocation, and while a series is in progress every `abcd build next` continues it. A
move reads what the series' last pick has come to. While its run is in progress it picks
nothing and names the run to drive with `abcd implement step`. Once the run is delivered
(complete) or its lane stops (handed back, or its run directory removed), it picks again
among the rest, less every intent the series has picked (excluded at the check `series`),
writing that pick's reason the same way, until --max picks are made or no candidate is
left; either ends the series, exit 0, naming why and each exclusion. The series picks only
inside the pace rule's window: once the window has elapsed it writes next_eligible_at (now
plus the pause) and picks nothing before then; with no pause the next window opens at once.
Every run the series starts runs on the pace flags it began with. --session, --pace,
--sub-agents and --fix-rounds are `abcd build`'s own. A lane handed back after its fix
rounds falsifies the pick: the run record (`abcd implement record`) carries the pick's
score table and says so, and the intent's entry is not edited.

No candidate for a first pick is refused, naming each excluded intent and the check that
excluded it, and nothing is written. Refused too, writing nothing: --max 0 or a negative
--max, --max with --until-empty, and, while a series is in progress, a count or pace other than
the one it began with, and, until it is restored or removed, a series state that cannot be
read, does not parse, or names a count, a pick, an outcome, pace flags or a pace the series
never writes; and a pick whose reason the grounds writer's gate refuses, a defect to report.
Exit 2 on a refusal, exit 3 when the chosen intent's run is already in progress or the run
state or the series is locked.

**Flags:**

```
      --fix-rounds string   the fix rounds a lane of the new run may take before it is handed back; wins over every configured layer
      --max int             how many picks to make, one at a time under the pace rule; above 1 begins a series (default one pick)
      --pace string         the new run's working window and pause, <work-minutes>/<pause-minutes>; wins over every configured layer
      --session string      the host session's id in the shared run state; the new run claims the picked intent for it
      --sub-agents string   the new run's ceiling on lanes and validators alive at once; wins over every configured layer
      --until-empty         pick one at a time under the pace rule until no candidate is left; begins a series
```

### `abcd capture`

File an issue from quoted text, or render the ledger's status bare: Writes one record under open/; refuses a missing --remedy, a lone word or no checkout.

**Usage:** `abcd capture [text] [flags]`

**Flags:**

```
      --blocked-by string            comma-separated iss-N ids this issue is blocked by; each must exist in the ledger — blocked_by is documented in .abcd/work/issues/README.md under "Derived priority" and in commands/capture.md under "Link"
      --category string              issue category: bug | documentation | drift | inconsistency | tech-debt | security | ux | process | architectural-insight | future-work-seed | observation | lapse (default observation)
      --found-at string              optional repo-relative path, which must exist in this checkout, or a conceptual location in words
      --found-during string          session/command context (default manual-capture)
      --lapsed-at string             RFC 3339 instant a discipline gave way (the lapse, not the write-up)
      --production-mode string       how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: the repo's declared mode, else hand-written)
      --remedy abcd capture remedy   the proposed fix, one line (required); abcd capture remedy rewrites it later
      --severity string              severity: nitpick | minor | major | critical (default minor)
      --slug string                  override the slug derived from the text
      --source string                surfacing channel: plan-review | impl-review | manual-test | review-followup | agent-finding | agent-observation | user-observation | drift-detection | memory-curation | managed-repo | security-advisory (default user-observation)
```

#### `abcd capture admit`

Admit one widening proposal into its run's candidate set: Writes its accepted disposition and an adm-N record; refuses before a committed comparative run.

**Usage:** `abcd capture admit <rdi-N> --grounds "<why>" [flags]`

**Flags:**

```
      --grounds string   why the proposal is admitted (free text, held to the grounds floor; on a standing acceptance it must be that acceptance's ground)
```

**Example:**

```
abcd capture admit rdi-2609010000000001 --grounds "the widened configuration is one the next release has to serve"
```

#### `abcd capture defer`

Carry an open major or critical issue past one release cut: Writes deferred_after and deferral_reason; refuses a minor or nitpick issue, or an empty reason.

**Usage:** `abcd capture defer <iss-N> --after <vX.Y.Z> --reason <text> [flags]`

**Flags:**

```
      --after string    the current anchor: the newest vX.Y.Z release tag, which the cut measures from (required)
      --reason string   why the finding is carried past this cut rather than fixed (required)
```

**Example:**

```
abcd capture defer iss-2609010000000001 --after v0.1.0 --reason "the fix needs the parser rewrite that lands next cycle"
```

#### `abcd capture disposition`

Answer one reading item with a disposition record: Writes the record keyed to the item; refuses a second answer without --supersedes.

**Usage:** `abcd capture disposition <rdi-N> --state <accepted|rejected|declined|held> (--grounds <text>, or --exit-condition <text> when held) [--supersedes <dsp-N>] [--recurs <rdi-N,...>] [flags]`

**Flags:**

```
      --exit-condition string        what would end a held disposition (required on held; a hold exits only through a superseding disposition that cites it)
      --grounds string               disposition_grounds: why this answer (free text; required on every state except held)
      --hold-frame-location string   RESERVED (dormant): the frame element a hold sits at; a populated value is refused until activation is ruled
      --hold-moscow string           RESERVED (dormant): must | should | could | wont; a populated value is refused until activation is ruled
      --recurs string                comma-separated prior rdi-ids this item recurs from — the researcher's confirmed recognition; the ingest's duplicates/refines link is only a proposal
      --state string                 the answer: accepted | rejected | declined | held (availability varies by the item's position)
      --supersedes string            the standing dsp-N this answer replaces; required once an item already carries one
```

**Example:**

```
abcd capture disposition rdi-2609010000000001 --state accepted --grounds "pursued: the tension is real and the next reading will show it again"
```

#### `abcd capture link`

Add or remove blocked_by edges on an issue: Writes the issue's blocked_by list; refuses an id the ledger does not hold.

**Usage:** `abcd capture link <iss-N> [--blocked-by <iss-M,...>] [--unblock <iss-M,...>] [flags]`

**Flags:**

```
      --blocked-by string   append: comma-separated iss-N ids this issue is blocked by; each must exist in the ledger — blocked_by is documented in .abcd/work/issues/README.md under "Derived priority" and in commands/capture.md under "Link"
      --unblock string      remove: comma-separated iss-N ids to drop from blocked_by; each must currently be in the list. With --blocked-by in the same call the removals are applied first, then the additions
```

**Example:**

```
abcd capture link iss-2609010000000001 --blocked-by iss-2609010000000002
```

#### `abcd capture list`

List the issues in one status folder or all three: Writes nothing; refuses when no status flag is given.

**Usage:** `abcd capture list [flags]`

**Flags:**

```
      --all        issues across all three states
      --open       issues currently in open/
      --resolved   issues currently in resolved/
      --wontfix    issues currently in wontfix/
```

#### `abcd capture mentions`

List open issues that default-branch history names with no resolution behind them: Writes nothing; refuses outside a git checkout.

**Usage:** `abcd capture mentions [--ref <branch>] [flags]`

**Flags:**

```
      --ref string   history to walk (default: the repository's default branch)
```

#### `abcd capture migrate`

Rewrite retired promote back-links as related_intents and related_issues: Writes the records only with --apply; refuses outside a git checkout.

**Usage:** `abcd capture migrate [--apply] [flags]`

**Flags:**

```
      --apply   write the rewritten records (default: report only)
```

#### `abcd capture promote`

Graduate an issue or an accepted reading item into an intent draft: Writes the draft and both back-links; refuses a promoted issue or an unaccepted item.

**Usage:** `abcd capture promote <iss-N> [--grounds "<token>: <text>"] | promote <rdi-N> [flags]`

**Flags:**

```
      --grounds string           optional; recorded when given — the conjecture being acted on, not the route taken: "<pursued|deferred|declined>: <what is expected, and what would show it wrong>"
      --intent string            link mode: link this existing itd-N instead of minting a draft (writes both halves of the join)
      --production-mode string   how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: the repo's declared mode, else hand-written)
```

**Example:**

```
abcd capture promote iss-2609010000000001
```

#### `abcd capture reframe`

Record a reframe a reading occasioned: Writes one rfm-N fingerprinting the frame before and after; refuses an uncommitted occasion or frame edit without --open.

**Usage:** `abcd capture reframe --occasioned-by <rdi-N|dsp-N|srp-N> --grounds "<why>" [--open] | --complete <rfm-N> [flags]`

**Flags:**

```
      --complete string        the open reframe record (rfm-N) to finish once the rewrite is committed
      --grounds string         why the frame moved (free text, held to the grounds floor)
      --occasioned-by string   the record that occasioned the reframe: a reading item (rdi-N), a disposition (dsp-N) or a surprise (srp-N)
      --open                   record the first half before the rewrite is committed; complete it after with --complete
```

**Example:**

```
abcd capture reframe --occasioned-by rdi-2609010000000001 --grounds "the reading showed the construal assumed a single operator" --open
```

#### `abcd capture remedy`

Write or replace the fix an open issue proposes: Writes the issue's remedy; refuses an empty text, the automatic filers' value or an issue that is not open.

**Usage:** `abcd capture remedy <iss-N> <text>`

**Example:**

```
abcd capture remedy iss-2609010000000001 "make the map before the first write"
```

#### `abcd capture resolve`

Move an open issue to resolved/, naming what fixed it: Writes the moved record; refuses without --impact or on an id this ledger does not hold.

**Usage:** `abcd capture resolve <iss-N> <note> --impact <additive|breaking|fix|internal> [--grounds "<token>: <text>"] [--intent itd-N] [--spec spc-N] [--commit sha] [--shipped-in vX.Y.Z] [flags]`

**Flags:**

```
      --commit string            resolved_by provenance: the fixing commit sha (7-64 hex chars, shape-checked only)
      --grounds string           optional; recorded when given — the conjecture being acted on, not the route taken: "<pursued|deferred|declined>: <what is expected, and what would show it wrong>"
      --impact string            product impact: additive|breaking|fix|internal (required)
      --intent string            resolved_by provenance: the itd-N that fixed it (must exist)
      --production-mode string   restamp how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: leave the record's existing stamp alone; refused on a record that predates disclosure)
      --shipped-in string        MIGRATION USE: the release that already carried this work (vX.Y.Z), leaving the record out of the current cut; unnecessary in a repo abcd managed from the start
      --spec string              resolved_by provenance: the spc-N that fixed it (must exist)
```

**Example:**

```
abcd capture resolve iss-2609010000000001 "fixed by the parser change" --impact fix
```

#### `abcd capture surprise`

Record one surprise a reading item, admission or disposition occasioned: Writes one srp-N record; refuses an unresolved occasion or a text below the floor.

**Usage:** `abcd capture surprise --occasioned-by <rdi-N|adm-N|dsp-N> "<what was unexpected>" [flags]`

**Flags:**

```
      --occasioned-by string   the record that occasioned it: a reading item (rdi-N), an admission (adm-N) or a disposition (dsp-N)
```

**Example:**

```
abcd capture surprise --occasioned-by rdi-2609010000000001 "the proposal nobody expected ranked first"
```

#### `abcd capture wontfix`

Move an open issue to wontfix/ with the reason it is not acted on: Writes the moved record; refuses an id this ledger does not hold.

**Usage:** `abcd capture wontfix <iss-N> <reason> [--grounds "declined: <text>"] [--duplicates <iss-N|itd-N,...>] [flags]`

**Flags:**

```
      --duplicates string        comma-separated iss-N or itd-N ids this issue duplicates, written to its typed duplicates link; each must exist, and a link the record already carries is kept
      --grounds string           override the recorded grounds text (the token stays declined — a wontfix IS that non-action)
      --production-mode string   restamp how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: leave the record's existing stamp alone; refused on a record that predates disclosure)
```

**Example:**

```
abcd capture wontfix iss-2609010000000001 "the behaviour is the documented one"
```

### `abcd checklist`

List this working copy's checklist, every item and field: Writes nothing; refuses outside a git checkout.

**Usage:** `abcd checklist`

The working copy's checklist: what the session is working on, what it waits on
and what it has promised, kept in .abcd/.work.local/checklist.json so it
survives compaction and crashes. One file per working copy.

Bare `abcd checklist` lists every item with every field and writes nothing.
The reader validates and scans the file; one that fails is passed over for the
last copy a checked write produced, and the first line says why. `add`, `set`
and the bare list are the session's verbs; edit the file by hand and the reader
refuses what it cannot vouch for.

Every write validates the whole checklist against its schema and scans every
field for secrets. A refusal names the field and the rule or the pattern kind,
never the value, exits 2 and writes nothing. updated_by is the host's session
id where the host exports one, otherwise the name the away record would give
the writer. No verb makes a network request.

#### `abcd checklist add`

Add one item to the checklist under a new stable id: Writes checklist.json and its last-good copy; refuses a schema violation or a secret, naming the field.

**Usage:** `abcd checklist add "<title>" [flags]`

Add one item under a new id: a short slug of the title, with -2, -3 and so on
when the slug is taken. The id never changes after; `set` and `show` take it.

The item is working, or waiting when --waits-on names what it waits on: a record
id, pr:<number>, person:<role> or slot:<kind>. --next-look is when to look again,
an RFC 3339 timestamp. --promise is "<trigger> => <act>", split at the first =>.
The title is one line of at most 200 characters.

**Flags:**

```
      --next-look string   when to look at the item again, an RFC 3339 timestamp
      --promise string     a trigger and the act it promises, as "<trigger> => <act>"
      --waits-on string    what the item waits on: a record id, pr:<number>, person:<role> or slot:<kind>
```

**Example:**

```
abcd checklist add "Regenerate the CLI reference"
```

#### `abcd checklist render`

Print the checklist as one block of text, open items first: Writes nothing; refuses outside a git checkout.

**Usage:** `abcd checklist render`

Print the checklist as the text a session's context is given: the open items
first, then the done and dropped ones, each on one line. A checklist that fails
the reader's checks is passed over for the last good copy, with one line saying
why. Writes nothing.

#### `abcd checklist set`

Set one checklist item's state by its id: Writes checklist.json and its last-good copy; refuses an unknown id or state.

**Usage:** `abcd checklist set <id> --state <state> [flags]`

Set one item's state: working, waiting, done, dropped. The id is the one `add`
minted, and it stays the same. An unknown id or state is refused (exit 2).

**Flags:**

```
      --state string   the item's new state: working, waiting, done, dropped
```

**Example:**

```
abcd checklist set regenerate-the-cli-reference --state done
```

#### `abcd checklist show`

Show one checklist item, every field, by its id: Writes nothing; refuses an id the checklist does not hold.

**Usage:** `abcd checklist show <id>`

Show one item, every field, by the id `add` minted. Bare `abcd checklist`
lists them all. Writes nothing.

**Example:**

```
abcd checklist show regenerate-the-cli-reference
```

### `abcd completion`

Generate the autocompletion script for the specified shell

**Usage:** `abcd completion`

Generate the autocompletion script for abcd for the specified shell.
See each sub-command's help for details on how to use the generated script.

#### `abcd completion bash`

Generate the autocompletion script for bash

**Usage:** `abcd completion bash`

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

	source <(abcd completion bash)

To load completions for every new session, execute once:

#### Linux:

	abcd completion bash > /etc/bash_completion.d/abcd

#### macOS:

	abcd completion bash > $(brew --prefix)/etc/bash_completion.d/abcd

You will need to start a new shell for this setup to take effect.

**Flags:**

```
      --no-descriptions   disable completion descriptions
```

#### `abcd completion fish`

Generate the autocompletion script for fish

**Usage:** `abcd completion fish [flags]`

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

	abcd completion fish | source

To load completions for every new session, execute once:

	abcd completion fish > ~/.config/fish/completions/abcd.fish

You will need to start a new shell for this setup to take effect.

**Flags:**

```
      --no-descriptions   disable completion descriptions
```

#### `abcd completion powershell`

Generate the autocompletion script for powershell

**Usage:** `abcd completion powershell [flags]`

Generate the autocompletion script for powershell.

To load completions in your current shell session:

	abcd completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command
to your powershell profile.

**Flags:**

```
      --no-descriptions   disable completion descriptions
```

#### `abcd completion zsh`

Generate the autocompletion script for zsh

**Usage:** `abcd completion zsh [flags]`

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

	echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

	source <(abcd completion zsh)

To load completions for every new session, execute once:

#### Linux:

	abcd completion zsh > "${fpath[1]}/_abcd"

#### macOS:

	abcd completion zsh > $(brew --prefix)/share/zsh/site-functions/_abcd

You will need to start a new shell for this setup to take effect.

**Flags:**

```
      --no-descriptions   disable completion descriptions
```

### `abcd dashboard`

Report whether the dashboard runs, where, and the devices that opened it: Writes nothing; refuses any argument.

**Usage:** `abcd dashboard`

Start, stop and report the product thinker's dashboard: one server on this
computer, listening only on this computer's own Tailscale addresses, over plain
HTTP with no certificate, never through Serve or Funnel. Every connection is let
in only when Tailscale's own lookup of its address names a device of a person,
never from a header; any device on the Tailscale network can open it but a
tagged machine and this computer itself, which start checks once and then
refuses, so the dashboard is opened from another device. Until the product
thinker decides, a device shared in from another account and a request
another device's Serve or Funnel relays are refused too.

Bare `abcd dashboard` is `abcd dashboard status`. The server runs until `abcd
dashboard stop`, and never starts by itself. Its run file and the devices that
opened it live in `~/.abcd.noindex/dashboard/`.

Exit 2 on a refusal, with nothing started or stopped.

#### `abcd dashboard start`

Start the dashboard on this computer's own Tailscale addresses: Writes its run file under ~/.abcd.noindex/; refuses when Tailscale is not running.

**Usage:** `abcd dashboard start [flags]`

Start the dashboard on this computer's own Tailscale addresses and print one
line saying where to open it and who can. It refuses outside a checkout abcd
manages, when a dashboard already runs on this computer, when Tailscale is not
running, and when the port is one Tailscale's own Serve or Funnel configuration
uses. It returns once a fetch of its own address through Tailscale answers. An
address the fetch cannot connect to at all is dropped: its listener is closed,
and named with why in the line; if no address answers, or one that connects
does not, the server is stopped and the failure named.

**Flags:**

```
      --port int   the port to listen on, on each of this computer's Tailscale addresses (default 8080)
```

#### `abcd dashboard status`

Report whether the dashboard runs, where, and the devices that opened it: Writes nothing; refuses any argument.

**Usage:** `abcd dashboard status`

Report whether the dashboard runs, where, since when, and the devices that
opened it in this run, each by its Tailscale device name and person. Writes
nothing.

#### `abcd dashboard stop`

Stop the dashboard after checking its process is the one start launched: Writes the run file's removal; refuses when another start or stop holds the lock.

**Usage:** `abcd dashboard stop`

Stop the dashboard this computer runs. It signals only the process start
launched, checked by its process id, start time and executable just before the
signal, waits until its addresses answer nothing, and removes the run file. A
run file naming a process that is gone or is another program is removed with
nothing signalled. It never stops anything by name.

### `abcd decide`

Record a decision, list them bare, or mint an ADR with --adr: Writes one decision record or one proposed ADR; refuses a text with nothing slug-able.

**Usage:** `abcd decide ["<text>" | --adr "<title>"] [flags]`

Record a decision, list the decisions recorded, or mint an architecture decision record.

abcd decide "<text>" records a decision: one new file, .abcd/work/decisions/dcn-<id>-<slug>.md,
whose id is minted through the shared record-id seam and whose body is `<date> — <text>`.
Nothing is appended anywhere, so two branches that each record a decision merge with nothing
to reconcile. It needs the shared tier .abcd/work/, which `abcd ahoy install` lays.

abcd decide with no operand lists every decision recorded, newest first, read from the folder
each time: the id, then the decision. Where a frozen .abcd/work/DECISIONS.md also exists, the
listing ends by naming it as earlier history it does not list. It writes nothing.

abcd decide --adr "<title>" mints an architecture decision record: its id is
`adr-<yymmddHHMMSS><rrrr>` and the store's skeleton lands under
.abcd/development/decisions/adrs/, with the filename ordered by the stamp, so two branches
deciding on the same day cannot allocate the same number. The hand-numbered records
0001-0058 keep their ids and their filenames. The ADR is EMPTY: the verb owns the id, the
date, the filename and the four sections, and states nothing; it lands `proposed` until the
author sets `accepted`.

**Flags:**

```
      --adr   mint an architecture decision record from the operand as its title, instead of recording a decision
```

**Example:**

```
abcd decide "Decisions are one flat file each"
```

### `abcd disembark`

Pack a repository into a lifeboat, probing and planning first: Writes nothing in the source, only inside the lifeboat; refuses an unknown sub-verb.

**Usage:** `abcd disembark`

#### `abcd disembark coverage`

Aggregate saved probe reports into the section-by-repository coverage table: Writes nothing; refuses a file that is not a probe report.

**Usage:** `abcd disembark coverage <report.json>...`

**Example:**

```
abcd disembark coverage probe-report.json
```

#### `abcd disembark graveyard`

Validate host-produced lesson JSON against a packed lifeboat: Writes the lessons that cite their evidence; refuses without --lessons-json.

**Usage:** `abcd disembark graveyard <lifeboat-dir> --lessons-json <file|-> [--dry-run] [flags]`

**Flags:**

```
      --dry-run               check the input and report what would be written; write nothing
      --lessons-json string   path to the host-produced lesson JSON (or - for stdin)
      --route stringArray     route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd disembark graveyard ../lifeboat --lessons-json lessons.json
```

#### `abcd disembark pack`

Pack a lifeboat from a repository into a destination directory: Writes the destination only; refuses when the secret scanner is unavailable.

**Usage:** `abcd disembark pack <repo> <dest> [flags]`

**Flags:**

```
      --include-ignored   also read files git ignores (widens the scan; the report says so)
```

**Example:**

```
abcd disembark pack . ../lifeboat
```

#### `abcd disembark plan`

Show the file set a pack would write: Writes nothing; refuses a repository path that is not a directory.

**Usage:** `abcd disembark plan [repo] [flags]`

**Flags:**

```
      --include-ignored   also read files git ignores (widens the scan; the report says so)
```

#### `abcd disembark press-release`

Compose a lifeboat's press release, or validate the host's: Writes the press-release files in the lifeboat; refuses a host draft citing nothing resolvable.

**Usage:** `abcd disembark press-release <lifeboat-dir> [--press-release-json <file|->] [--dry-run] [flags]`

**Flags:**

```
      --dry-run                     check the input and report what would be written; write nothing
      --press-release-json string   path to host-produced press-release JSON (or - for stdin); absent runs deterministic mode
      --route stringArray           route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd disembark press-release ../lifeboat
```

#### `abcd disembark principles`

Distil a lifeboat's principles from its ADRs, or validate the host's: Writes the principles files in the lifeboat; refuses a directory that is not a lifeboat.

**Usage:** `abcd disembark principles <lifeboat-dir> [--principles-json <file|->] [--dry-run] [flags]`

**Flags:**

```
      --dry-run                  check the input and report what would be written; write nothing
      --principles-json string   path to host-produced principle JSON (or - for stdin); absent runs deterministic mode
      --route stringArray        route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd disembark principles ../lifeboat
```

#### `abcd disembark probe`

Report which brief sections a lifeboat could ground from a repository: Writes nothing; refuses a repository path that is not a directory.

**Usage:** `abcd disembark probe [repo] [flags]`

**Flags:**

```
      --include-ignored   also read files git ignores (widens the scan; the report says so)
```

#### `abcd disembark review`

Review a packed lifeboat against its source repository, or validate the host's verdict: Writes the review in the lifeboat; refuses an unregistered verdict.

**Usage:** `abcd disembark review <lifeboat-dir> <source-repo> [--review-json <file|->] [--dry-run] [flags]`

**Flags:**

```
      --dry-run              check the input and report what would be written; write nothing
      --review-json string   path to the host-produced review verdict JSON (or - for stdin); absent runs deterministic mode
      --route stringArray    route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd disembark review ../lifeboat .
```

### `abcd docs`

Keep the citation baseline `abcd lint docs` enforces, and judge the brief against the binary: Writes nothing bare; refuses an unknown sub-verb.

**Usage:** `abcd docs`

#### `abcd docs cite`

Keep the citation baseline the docs lint enforces offline: Writes nothing bare, and only that baseline; refuses an unknown sub-verb.

**Usage:** `abcd docs cite`

##### `abcd docs cite confirm`

Record that a person verified a cited URL the fetcher could not read: Writes a dated manual entry in the baseline; refuses a URL the docs do not cite.

**Usage:** `abcd docs cite confirm [url...] [flags]`

Record that a human verified a cited URL the fetcher could not read.

Name the URLs directly, or pass --receipt with a receipt file. Both write the same dated manual entry: the baseline records THAT a human confirmed the citation and WHEN, never how. Only URLs the documentation actually cites can be confirmed.

**Flags:**

```
      --config string    path to docs-lint.json (default: <root>/.abcd/docs-lint.json)
      --receipt string   path to a JSON receipt listing the confirmed citations: schema_version 1 and a confirmed list, each entry a url with an optional final_url and verified_on (YYYY-MM-DD)
      --root string      repo root (default: current working directory)
```

##### `abcd docs cite refresh`

Fetch every cited URL once, the one documentation verb that reaches the network: Writes the citation baseline; refuses an unreadable docs-lint configuration.

**Usage:** `abcd docs cite refresh [flags]`

Fetch every cited URL once and rewrite the committed citation baseline.

This is the only abcd verb that reaches the network on behalf of documentation. Each URL gets exactly one bounded attempt; a failure is recorded as an outcome, never retried. Sources that refuse automated fetchers are printed as a manual checklist for `abcd docs cite confirm` rather than recorded as broken.

**Flags:**

```
      --config string   path to docs-lint.json (default: <root>/.abcd/docs-lint.json)
      --root string     repo root (default: current working directory)
```

#### `abcd docs fidelity`

Judge the brief against every shipped surface and the saved docs review: Writes drafted edits only with --apply; refuses a surface no chapter names.

**Usage:** `abcd docs fidelity [flags]`

**Flags:**

```
      --apply            write the reviewer's drafted corrections into the brief and flag each for review
      --autonomous       an unattended run: apply the drafted corrections, list every applied edit, and hand the routine the reviewer's request; the refusals stay
      --intent strings   the intent(s) whose delivery is judged, named in every finding (repeatable)
      --report           the per-task pass: state every finding, refuse nothing, exit 0
```

##### `abcd docs fidelity record`

Save a docs review's verdict as the receipt for HEAD: Writes the receipt in the local tier; refuses a verdict naming no judge.

**Usage:** `abcd docs fidelity record --verdict-json <file|-> [--dry-run] [flags]`

**Flags:**

```
      --dry-run               check the input and report what would be written; write nothing
      --verdict-json string   the reviewer's verdict JSON (a file, or - for stdin)
```

**Example:**

```
abcd docs fidelity record --verdict-json verdict.json
```

### `abcd drain`

Fix the issues needing no decision, one lane at a time, and hand the rest back: Writes its state and user-visible drafts; refuses without the rule's record.

**Usage:** `abcd drain [--dry-run] [--max <n>] [--pace <work-minutes>/<pause-minutes>] [--sub-agents <n>] [--fix-rounds <n>] [--judgement <file>] [--take-over] [--skip <iss-N|path> --reason <why>] [--unskip <iss-N|path>] [flags]`

Work the open issue ledger unattended: fix the issues that need no decision, and
hand the rest back by kind. Which issues need no decision is this repository's own
recorded decision: an accepted decision record whose frontmatter carries the four
fields drain_categories, drain_severities, drain_security and drain_remedy. The
rule reads the issue's fields, and beyond them only the release tags and, for a
consistency finding, the intent store: nothing open in blocked_by; no intent in
related_intents; a category the rule takes; a severity it takes; and a remedy:
field. abcd's strict baseline takes tech-debt, documentation, inconsistency, drift,
bug and ux at nitpick or minor, and hands every security issue to a person. A
repository's record may loosen those floors (major, critical, security), and every
floor it loosens is named. Four hand-backs hold whatever the record says. An issue
whose related_intents names an intent is handed back as promoted, naming the
intents: it goes through its intent (`abcd build <itd-N>`, or `abcd intent audit
<itd-N>` for an audit's owed check), and a person's own `abcd build <iss-N>` still
takes it where no other rule would hand it back; a record the consistency pass files
is the exception, since the intents
it names are the two it found contradicting: once a person has written its remedy,
it is judged by its other fields as if it named no intent, and an intent it was
promoted into still owns it. An issue carrying the decision_needed: marker a drain's
trust-rule hand-back wrote, whose remedy opens "Waits on", or whose deferral past
the current release tag is live, or names a release tag this checkout lacks, is
handed back too. Every other open issue is handed back, listed as ineligible or
unreadable, or skipped naming its blocker, by the rule that excluded it.

In a checkout with a remote named origin, the ledger is read from origin's default
branch, never from the checkout, which may be behind it: each move fetches the
reservations and that branch first, under the drain's lock and before any judgement
or reservation, and plans from what it fetched. A move that cannot read origin (the
fetch fails, the default branch cannot be read, or none can be named: no origin/HEAD
and no origin/main, master, trunk or develop) plans
nothing: it records the failure in the drain's state and waits as for an outage,
looking again after one minute, five, ten, then hourly, and exits 0 saying when.
While it waits a move takes no answer given, saying to give it again, finishes no
merged lane and renews no reservation, and one before the next look fetches nothing.
A probe that fails eight hours into the hourly stage gives up, as the outage gate
does: the drain ends (stopped "origin"), and the next abcd drain begins a new
drain, waiting again if origin still cannot be read.

--dry-run shows every open issue's disposition, the eligible ones first in the
order a drain takes them (by category, then severity, then the issues naming a
file before the rest, then each account's own order on origin, drawn from the
holder git's identity names, when it names one, and the copy's key), and
writes nothing; on a copy with no key yet it takes each group oldest first and
says the copy's own order is drawn at its first move. It fetches nothing either: it plans from origin's default branch as
last fetched, and says how old that view is, how many commits the checkout is
behind it, and which issues open in the checkout it has already finished. The host
judgement over each eligible remedy does not run; it can only ever hand an issue
back.

--take-over moves your own live reservation of an issue from another copy to this one
as the move reaches it, as `abcd build --take-over` does: a hosted session that
restarted lost its local tier, so its new copy reads its own reservations as another
copy's, which a plain move passes over naming the flag. It never moves another
person's reservation, and is given per move: a move without it passes such an issue
over again.

Without --dry-run, each invocation performs one move of the drain and exits. Before
the next eligible issue's lane opens, the host judges its remedy: on origin, the
drain first reserves the issue (passing over, with no push, any issue or footprint
another copy holds), then writes
a request (.abcd/.work.local/run/drain-judgement.request.md) asking whether the
remedy changes what a user sees or a trust boundary, and opens nothing. The host
writes its answer where the request says and hands it back with --judgement <file>,
which is validated strictly; a refused answer changes nothing. When your machine's
config routes the drain-judge role to the claude runner (roles.drain-judge.runner), the
same move asks that runner instead, on a brief of its own in a private directory
outside every working tree, and takes its answer as
--judgement would, abcd computing the remedy's digest itself; a runner that does not
answer leaves the request to the host, recorded as a fallback. A yes hands the
issue back before any lane opens, routed as a lane's hand-back of the same kind
(below); a no lets the lane open on the reservation. The drain releases that
reservation, and only it, with a fetch and one tombstone push whenever no lane will
open on it: on a yes, on an answer over an issue that has left the eligible set,
when the judgement is superseded (the order asks another issue, nothing eligible is
left, the drain stops, or a no comes once the window has elapsed), when the lane's
start is refused or fails, and when a request lapses unanswered. A yes's tombstone
publishes the hand-back on origin, its kind and the blob id of the issue's record
there, as a lane's hand-back does, when the drain's reservation is still the
issue's tip: every account's drain passes the issue over, pushing and asking
nothing, until a person changes that record, and no drain takes over or renews a
reservation a person made over it, lapsed or not. A yes whose reservation has
moved on (renewed, reserved again or taken over since, or released by a person),
or that took none because you held the issue live, publishes nothing yet: the
drain keeps the hand-back pending (pending_hand_backs in --json) and publishes it
over the issue's next release on origin, or, once the sweep has deleted that
release, as the first commit of a branch no one has made again since. A record
changed or finished on origin's default branch since, one origin holds in no one
file, or a tombstone the hand-back would take past its cap drops it, and the move
says it was dropped and why; a default branch that could not be read keeps it
pending. A promotion
this checkout cannot make, not holding the record as origin does, is left to a
checkout that can. The reservation is taken once per request: one unanswered when it lapses is
dropped and the issue asked again only after the drain's other eligible work. The
judgement can never make an issue eligible:
an answer over an issue that has left the eligible set decides nothing, and one over
a remedy rewritten since the request is refused and asked again. Once judged, the
drain hands the next eligible issue, in that order, to the implement loop's issue-keyed
lane (the run `abcd build <iss-N>` starts), one lane at a time, and names the run to
drive with `abcd implement step`. Run it again once that lane is handed back or its
pull request is open, and it routes the lane's outcome and opens the next. A lane
that cannot finish does not hold the drain: each refused step of its run, until its
pull request is armed or left open, is logged on the lane (refused in the run's state: the stage, the check, the reason, a count
of the same refusal in a row, since when and when last it refused there, and why it
cannot change), and once the step has been refused the same way three times, or has
kept refusing at one stage for sixty minutes, from its first refusal there to its
last, a quiet of more than fifteen minutes starting the time afresh
(pace.stuck_refusals and pace.stuck_minutes in the config layers), the next move
hands the lane back as stuck, releases its reservation with a tombstone marking it
stuck, and takes up the next issue. A refusal that cannot change (the issue
finished at the lane's base or on origin's default branch, the reservation now
another person's, the sync's merge conflicting in a file not declared generated)
hands it back at once; the wait for a preflight receipt, an outage's wait, a land
fence that cannot read origin and a release being cut that holds merges are never
counted, and a
step that succeeds as the move hands the lane back keeps it. `abcd implement step
--discard` removes a stuck lane's worktree and branch and ends its run. Every move
that neither waits on origin nor stops at a given-up outage renews the reservation
of the lane in progress at half its lease, waiting on the pace or a judgement or not
(a lane handed back is renewed by none); once the lane's validators pass and it is
at its landing, the first renewal due at half its lease, a fence's renewal keeping the
footprint, narrows its footprint to the files the lane changed
within it, never widening it, and a lane its sync sends back to a fresh round
reserves its whole found_at again before it goes on, or is refused for you;
and the landing checks it before its push,
so a lane whose reservation became another person's pushes nothing and is handed
back as stuck. A move that finds a lane parked at land reads it from its pull
request, in one listing of your latest pull requests (gh pr list): a closed one
hands the lane back as closed, releasing its reservation with a tombstone marking
it closed; a conflicting one is not renewed and is named; an open one is
renewed and named as waiting, or, once the merge-queue watch finds it will not merge
on its own (it left the queue disarmed, or its head moved), as dropped, naming why
(parked in --json); the watch queues one it finds armed and CLEAN outside the queue.
Before its records and push a
lane's sync fetches origin's default branch and merges it whenever it has moved, a
fresh round judging the merge: a conflict confined to files origin declares
linguist-generated goes back to an implementer to regenerate, any other hands the
lane back naming the files, nothing pushed, and a pull request that starts to
conflict on generated files alone, or in no file when this checkout merges, enters
the sync again, an armed merge withdrawn first; one whose head already holds the
default branch waits at exit 3. A lane
that finds a decision in its issue hands it back by kind, its work discarded: a
user-visible change is promoted to an intent draft (`capture promote`, which
stamps the issue's related_intents and nothing else); a trust or safety rule is
flagged as needing a decision record, with the question written onto the open issue
as its decision_needed: marker; a design finding or a second package is flagged with
the home the lane names. Every issue the rule hands back is flagged naming the rule,
less one this drain promoted or marked itself, which is counted once, as its
promotion or decision record. Nothing but the promotion and the decision_needed:
marker is written to the ledger, and every hand-back is in the summary.

The drain is paced as a run is: its window and pause are --pace, --sub-agents and
--fix-rounds as `abcd build` reads them, resolved when the drain begins. At the window's
end the drain's state (.abcd/.work.local/run/drain.json) takes next_eligible_at and
the call opens nothing; before that time a drain opens nothing, and after it the
next invocation continues. --max <n> caps the lanes the drain opens (the default
is all); at the cap, or when nothing eligible is left, held or not, the drain reports
and ends. When you hold your cap of live reservations (ten unless reservation.max_live
in your machine's config.json sets another, from 1 to 100), or every
eligible issue left is held by another, a move neither refuses nor ends: it reserves
and asks nothing, writes waiting_until fifteen minutes on (apart from the pace
window) and waiting, "cap" or "held", for which of the two it waits on, names the
reservations and pull requests or the holds it waits on, and keeps its judgements;
run it again at or after that time. Once a drain has ended, the
next `abcd drain` begins a new one. A cap named while a drain is in progress that
differs from the one it began with is refused. Every lane the drain opens runs on
the drain's pace; --pace, --sub-agents and --fix-rounds given while it runs are
taken, recorded in its state, and applied from the next lane it opens and the next
stage of the lane in progress. An issue the drain handed back is taken up again,
judged afresh, once its record changes on origin's default branch. Once a run gives up on a
lost connection (`abcd implement outage`), the drain opens nothing and ends with
stopped "outage", naming the services down, since when, the probes and the lanes it
opened; the next `abcd drain`, once the outage is cleared, begins a new one.

--skip <iss-N|path> --reason <why> holds one issue, or every issue whose found_at
lies in that path, back for now: the move adds it to the drain's skip list (beginning
a drain when none is in progress) and every move that takes up the eligible issues
passes it over before anything is pushed or asked, named in passed with check "skipped" and the reason. --skip may be
given more than once, all with the one --reason; --unskip takes an entry off. The
list clears when the drain ends.

Without the repository's record, the dry run and the run both refuse (exit 2),
naming how to add it; `abcd ahoy install` offers it. A run that opens nothing or
merges nothing exits 0 and says why. Exit 2 on a refusal, exit 3 when another
drain or run holds the state lock.

**Flags:**

```
      --dry-run              show every open issue's disposition and the order a drain takes them; writes nothing
      --fix-rounds string    the fix rounds a lane may take before it is handed back; wins over every configured layer
      --judgement string     the host's answer to the judgement the drain awaits, at the path its request names
      --max int              cap the lanes this drain opens; the default is all
      --pace string          the drain's working window and pause, <work-minutes>/<pause-minutes>; wins over every configured layer
      --reason string        why --skip holds its issues back, shown in each pass-over
      --skip stringArray     hold an issue (iss-N), or every issue whose found_at lies in a path, back for now; needs --reason; cleared when the drain ends
      --sub-agents string    the ceiling on lanes and validators alive at once; wins over every configured layer
      --take-over            move your own live reservation of each issue this move reaches from another copy to this one; never another person's
      --unskip stringArray   take an issue or path off the drain's skip list
```

**Example:**

```
abcd drain --dry-run
  abcd drain --dry-run --json
  abcd drain --max 3
  abcd drain --json
  abcd drain --judgement .abcd/.work.local/run/drain-judgement.json --json
```

### `abcd embargo`

Keep private security advisories off the public ledger until closed or published: Writes nothing bare, only the embargo store; refuses an unknown sub-verb.

**Usage:** `abcd embargo`

Keep this repository's private security advisories private until their fix
ships. Each advisory GitHub holds in triage or draft becomes a private record
in the embargo store, a detached worktree in abcd's machine-scoped worktree
store that is never committed; the link from advisory to record lives in the
store's state, never in the record. Every sub-verb verifies the store before
it reads or writes it, and refuses, writing nothing, when it is on a branch,
tracks a private record, or sits inside this checkout.

Every remote call is the person's own `gh` against github.com; abcd holds no
token. close and publish each act on GitHub only with --approve naming the
digest of exactly the text or plan they showed, and a host passes it only
after the person, in that session, has seen it and said yes.

Exit 2 on a refusal (nothing written) and on a check finding.

#### `abcd embargo check`

Check a commit range or texts for what would disclose an advisory under embargo: Writes nothing; refuses on each id, reserved CVE id, title or store path found.

**Usage:** `abcd embargo check [flags]`

The outbound embargo check: before anything is made public, read a commit
range (--range <a>..<b>: each commit's message and the lines it adds, a
merge's being those it adds against every parent) and any texts (--file
<path>, repeatable; - reads stdin), and refuse every unpublished advisory's
id, a CVE id reserved for one, its title, the store's location on this
machine, and any other advisory id --allow does not name and GitHub does
not list among this repository's published advisories (asked only when
such an id is found). A finding names where the match is and never repeats
it.

Limits: a title shorter than 12 characters is not matched on its own (its
id still is); a paraphrase or a count ("fixes several private reports") is
not recognised, and stays the author's to avoid; an advisory id of the
placeholder form, each four-character group one character repeated
(GHSA-xxxx-xxxx-xxxx), is not refused as unlisted, though one the store
holds is still refused by its id. The check warns when the last intake is
more than a day old.

Exit 0 clean, or when no embargo store exists on this machine; exit 2 on any
finding.

**Flags:**

```
      --allow stringArray   an advisory id of another project, already public, that may appear (repeatable)
      --file stringArray    a text to read (repeatable; - reads stdin)
      --range string        a commit range <a>..<b> whose messages and added lines are read
```

#### `abcd embargo close`

Show an advisory's closing text and digest, or close it on GitHub with it: Writes GitHub and the store only with --approve; refuses a digest for other text.

**Usage:** `abcd embargo close <iss-N|GHSA-id> [flags]`

Close one advisory whose verdict is not-abcds or not-a-vulnerability on
GitHub, with the closing explanation its triage drafted. GitHub offers no
comment on a repository advisory, so the explanation is posted at the head of
the advisory's description, with the reporter's own text kept whole below a
separator line.

Without --approve it reads the advisory and shows exactly the text that would
be posted and the digest that approves it; nothing but that read is sent. With
--approve <digest> it re-reads both and closes only when the digest is the
one over exactly that text and the description as read, then reads the
advisory back to confirm it is closed with the text. A digest for any other
text sends nothing. A host passes --approve only after the person, in that
session, has seen the text and said yes to it.

**Flags:**

```
      --approve string   the digest shown for the text; only on the person's yes to exactly that text
```

**Example:**

```
abcd embargo close GHSA-xxxx-xxxx-xxxx
```

#### `abcd embargo intake`

Take this repository's private advisories into private records in the embargo store: Writes only the embargo store; refuses a remote that is not on GitHub.

**Usage:** `abcd embargo intake`

List the repository's security advisories in the triage and draft states
(GitHub's REST API, through your own `gh`) and mint one private record per
advisory not seen before, in the embargo store's own ledger. The store is
made on first use, detached at the default branch's tip. Severity maps
critical to critical, high to major, medium and low to minor; an advisory
with no severity is listed for you to set on GitHub and not recorded. A
re-run records nothing twice. Nothing is written to this checkout's ledger
or committed anywhere.

Each advisory the store holds that GitHub lists in neither state is read
from GitHub on its own. One GitHub reports published is recorded published, at
GitHub's own published_at, which releases it from the check; one it reports
closed is recorded closed, at its closed_at, only when its verdict is
not-abcds, not-a-vulnerability or public-track. Each recorded is listed as
ended. One GitHub cannot tell (a failed read, a 404 or 403 on its read, an
unknown state, a missing or malformed time), or reports closed while the
store holds it otherwise, is listed as unread, with the reason, and left
under embargo to be read again. A missing gh, a gh signed in to no account or
holding a token GitHub rejects, or a refusal naming the advisory scope,
refuses the intake with nothing recorded. Each published advisory whose
private record is resolved in the store and not yet in this checkout's
ledger is listed with the command that restores it.

#### `abcd embargo publish`

Show the publication plan with computed patched versions, or publish it: Writes GitHub and the store only with --approve; refuses a digest for another plan.

**Usage:** `abcd embargo publish [flags]`

Show the publication plan for the release tag (--release, default the highest
published release): for each advisory judged a vulnerability and not yet
published, its record resolved in that release, its fix commit, the first
published release holding the fix, the patched version that gives, and the
affected range in GitHub's form. A vMAJOR.MINOR.PATCH tag is a published
release when origin holds the tag at the object this checkout holds and GitHub
reports its release neither a draft nor a prerelease; any other tag gives no
patched version, and --release naming one is refused. When origin's tags, or
GitHub's answer for a release, cannot be read, the plan refuses with nothing
recorded, and so does an origin naming another repository than the store's. The
security rule keeps a security record out of every committed tree until its
advisory is published, so when the release carries no public record the
evidence is the advisory's private record, resolved in the embargo store's own
ledger with the full id of its fix commit; nothing else the store holds is
taken. An advisory resolved in neither, whose fix is in no published release up
to the release, whose package is not set on GitHub, or whose text carries a
secret, a private name or another advisory still under embargo is left out,
saying why. Without --approve nothing but reads is sent.

Every plan first reads from GitHub each advisory the store holds that is
neither published nor closed, as intake does: it records each published one,
and each closed one whose verdict ends its private track, at GitHub's own
time, lists each it recorded as ended, and lists each it could not tell, or
found closed while the store holds it otherwise, as unread, left under
embargo; a 404 or 403 on an advisory's read leaves it unread. When every read
meets one, the plan asks once for the repository's advisory listing: if it
answers, the scope is proven and the plan goes on; if GitHub refuses it, or
it fails otherwise, the plan refuses. A missing gh, a gh signed in to no
account or holding a token GitHub rejects, or a refusal naming the advisory
scope, refuses the plan with nothing recorded.

With --approve <digest> of exactly the plan shown it publishes one advisory as
a canary and reads it back, then the rest the same way, stopping at the first
mismatch, and confirms none is left in draft. Every plan and publication
lists each published advisory whose private record is resolved in the store
and not yet in this checkout's ledger, with the command that copies it into
the public ledger, until the checkout holds it. A host passes --approve only
after the person, in that session, has seen the plan and said yes to it.

**Flags:**

```
      --approve string   the plan's digest; only on the person's yes to exactly that plan
      --release string   the release tag vMAJOR.MINOR.PATCH to publish from (default the highest published release)
```

#### `abcd embargo triage`

Record a verdict on a private advisory, drafting a closing verdict's text: Writes the embargo store; refuses an unknown verdict or one missing its reason.

**Usage:** `abcd embargo triage <iss-N|GHSA-id> <verdict> [flags]`

Record your verdict on one private advisory, with who decided it (--by) and
when (the clock, never typed). The verdicts:

  vulnerability        the record stays open in the store, to be fixed
  not-abcds            needs --exists-without and --cannot-help, the two
                       halves of abcd-fixes-what-it-adds
  not-a-vulnerability  needs --reason
  public-track         needs --reason; prints the `abcd capture` command to
                       run in the public checkout

The two closing verdicts move the record to the store's wontfix/ and draft
the closing explanation, printed here, for `abcd embargo close`. A second
triage of the same advisory keeps the earlier verdict in its history. An
unknown verdict, or one missing its reason, is refused with nothing written.

**Flags:**

```
      --by string               who decided the verdict (required)
      --cannot-help string      not-abcds: why abcd cannot help without changing how the repository works
      --exists-without string   not-abcds: why the problem would exist without abcd
      --reason string           why: required for not-a-vulnerability and public-track
```

**Example:**

```
abcd embargo triage GHSA-xxxx-xxxx-xxxx not-a-vulnerability --by "<who decided>" --reason "the behaviour is the documented one"
```

### `abcd embark`

Unpack a verified lifeboat into a target repository, probing first: Writes only its record families and marker block; refuses the whole write on any conflict.

**Usage:** `abcd embark`

#### `abcd embark from`

Unpack a lifeboat's record families into a target repository: Writes those families and the marker block; refuses the whole write on any conflict.

**Usage:** `abcd embark from <lifeboat-dir> [target-dir]`

**Example:**

```
abcd embark from ../lifeboat
```

#### `abcd embark lessons`

Rank a lifeboat's retrospective lessons against the new voyage's brief: Writes only shadow pairs to the lab home; refuses a lifeboat that fails its manifest.

**Usage:** `abcd embark lessons <lifeboat-dir> [target-dir] [flags]`

**Flags:**

```
      --brief string    rank against this file's text (the press release the interview is writing) instead of the target's framing chapter
      --scores string   rank by the host's scores in this file (a scores document answering every lesson's question; - reads stdin)
```

**Example:**

```
abcd embark lessons ../lifeboat
```

#### `abcd embark probe`

Report what a lifeboat would write into a target, coverage blanks first: Writes nothing; refuses a lifeboat whose manifest does not verify.

**Usage:** `abcd embark probe <lifeboat-dir> [target-dir]`

**Example:**

```
abcd embark probe ../lifeboat
```

### `abcd guard`

Judge a shell command against the hazard registry before it runs: Writes branch records and a question's mode; refuses a hazard and an unknown sub-verb.

**Usage:** `abcd guard`

#### `abcd guard allow`

Let one exact unproven delete through the hook, once: Writes one allow record in your home folder; refuses without --once, and when an agent runs it.

**Usage:** `abcd guard allow --once --command <line> [flags]`

Allows one exact command line through the shell guard's hook, once, within
ten minutes: the person's way past a branch delete or a worktree removal the
guard could not prove safe (merged, with no open pull request, in no
worktree, held by no reservation, and for a worktree clean and in use by
nothing). It lets past nothing else: a line any other hazard blocks stays
blocked.

The allow is the person's own act. The guard refuses this verb when an
agent runs it, and refuses a shell write into the store, so run it yourself
in a terminal (or with your host's `!` prefix). The line must match the
agent's command byte for byte. The allow is recorded under
~/.abcd.noindex/guard-allow/<root-commit>/, keyed on the repository's root
commit, read only while this account owns it and no one else can write it,
and removed as the hook uses it. The store's log.jsonl records each line,
when it was allowed and when it was used, and never who.

--once is required: an allow is only ever for one use.

**Flags:**

```
      --command string   the exact command line to allow
      --once             allow the line for one use (required)
```

**Example:**

```
abcd guard allow --once --command 'git branch -D feat/done'
```

#### `abcd guard approve`

Answer a headless agent's permission prompts over MCP: Writes nothing; refuses every prompt but a shell command the guard reads whole and clears.

**Usage:** `abcd guard approve --dir <working-tree> --base <commit> [--run-dir <dir>]... [flags]`

Answers the permission prompts of an agent abcd started without a terminal,
over MCP on stdio: the claude runner starts it, as the one server of a launch
whose role's contract grants the shell, and names its tool, approve, as the
harness's permission prompt tool. Each prompt is judged against the hazard
registry of the working tree --dir names, read afresh for every prompt, and
in force only where it is at least as strong as the registry at --base, the
commit the run started on: any weakening since then, of a warn or a blocker,
committed or not, refuses every command.

A shell command is approved only when the guard reads it whole and clears
it: no registry entry and no reading signal, a warn included; no note about
the check, such as a script that does not exist; and every program named by
the line rather than by a variable, a substitution or a glob ([, [[ and test
are the test commands they name, not globs). Beyond the registry, it
refuses:

  - arithmetic on anything but written numbers: a name, a quote or an
    expansion in (( )), $(( )) or a for (( )) header, the number tests of
    [[ ]], let, declare -i, a non-numeric array index or substring offset,
    ${!name}, and a name not written in the line handed to read, unset,
    printf -v or a declaration; [ and test compare without evaluating;
  - inline code for python -c, node -e or -p, perl -e, ruby -e, php -r,
    osascript, lua or Rscript -e, deno eval and PowerShell -Command; a flag
    after the script's name, or after python's -m module, is the script's;
  - code on the standard input (a pipe, a here-document, a here-string or a
    redirected file) of one of those interpreters, or of ex, when no script
    file is named;
  - an awk program that calls system(, pipes to or from a command, or is a
    variable; a sed script with the e command or the e flag of s; tar's
    options that run a program (--checkpoint-action, --to-command,
    --use-compress-program, -I and the like); a vim or ex command (-c, --cmd,
    +) holding a !;
  - a write the guard's write model reads (redirections and a list of known
    writers, so a program outside the list writes unread), or a removal,
    whose target the line does not spell out (a variable,
    a substitution, a glob, or a name after an unknown change of directory),
    except a glob removal in a directory inside the working tree, followed
    through symlinks, that no protected name could match, when no earlier
    part of the line writes or removes a file and no wildcard stands in a
    directory part of the glob, nor does it end in a /; a command where an
    unquoted ( stands in a word (x(:A), x(.)) is refused whole, since zsh
    reads it as glob qualifiers that can change the path, but for the (( of
    an arithmetic for-loop and the ( before a case pattern, which bash needs;
  - such a write, or a removal, reaching a protected path, with its directories
    resolved through symlinks and case folded where the filesystem folds it:
    the git common directory and its hooks, each checkout's .git, the home
    shell start-up files and git configuration, the host's settings, .mcp.json,
    .abcd/guard.json, abcd's own folder in the home directory (its
    trusted-roots, rules.json, config.json and the rest, but for the run's
    own worktree kept there), and the names the host protects in any
    working tree;
  - a removal whose target lies outside the working tree, the run's own
    directories (each --run-dir) and the temporary directory; a write
    outside the working tree is judged by the protected paths alone;
  - git config with --global, --system or --file on a write, setting a key
    that starts a program (core.hooksPath, core.pager, an alias and the like)
    or core.worktree, or opening the editor, and any git command setting such
    a key for itself, but for -c core.pager or core.sshCommand set to a
    command the line spells out, which is judged as that command;
  - removing, moving or recursively changing the root, a top-level directory,
    the home directory or a directory directly in it, the working tree or a
    directory above it, or another checkout of the repository; a find that
    deletes from home or above; an rsync --delete into such a directory;
  - a call asking to run outside the host's sandbox.

An approved call runs with the command judged and its description, and
nothing else it carried, from the working tree it was judged for and under
bash: the command comes back as
cd -- '<dir>' && /bin/bash --noprofile --norc -p -c '<command>', since the
host keeps the shell's directory from one call to the next and runs the text
in the person's login shell, which may be zsh, while the guard reads bash's
grammar. The login shell only changes directory and starts /bin/bash with its
profile, rc and environment start-up files ignored (-p), so BASH_ENV,
exported functions and SHELLOPTS do nothing, and bash runs the command and
gives no zsh-only construct its zsh meaning (a glob qualifier is a syntax
error to it); when the directory cannot be entered, no part of the command
runs. The bash call is not an exec, so text the host joins after it still
runs. That text is read again with the guard's own parse and approved only
when it is exactly that change of directory and that one bash call, with the
whole command as its last word. A command holding a NUL byte is refused
before it is read. Everything else is refused with the guard's reason and
what to run instead, which the harness hands the agent, so the agent can
rewrite the command. A prompt for any tool but the shell is refused, since
nobody is there to approve it.

The file tools the role is granted (--allowedTools on the launch) write
without asking the approver, and the abcd binary that answers is not among
the paths it protects; the OS sandbox for launched agents
(spc-2610161751056096) is what bounds those writes.

The guard is a mistake filter, not a security boundary (see `abcd guard
check --help` for what an allow does not see), and this adds no sandbox.
It never touches the person's host settings, and interactive sessions never
start it. It exits 0 when its input ends.

**Flags:**

```
      --base string           the commit the run started on, by its full object name
      --dir string            the working tree the agent runs in, as an absolute path
      --run-dir stringArray   a directory the run keeps its own files in (its brief, its receipt), as an absolute path; repeatable
```

**Example:**

```
abcd guard approve --dir /work/example-repo --base 0123456789abcdef0123456789abcdef01234567
```

#### `abcd guard check`

Judge one shell command against the hazard registry: Writes nothing; refuses a hazard with exit 1 and a command it cannot parse with exit 2.

**Usage:** `abcd guard check [flags]`

Evaluates one candidate command line against the hazard registry — the
bundled defaults merged with this repo's `.abcd/guard.json` — and reports
allow, warn, or block. A blocker exits 1 and names the safe successor; a
warn exits 0 with the warning rendered; an allow exits 0. A guard that
cannot be evaluated at all (an unparsable command line, a malformed
registry) exits 2, so a caller never reads silence as clearance. Unparsable
means an unterminated quote in COMMAND text, which no shell runs either;
an unterminated quote inside a here-document body is document text and is
not one. Grammar a shell does run gets a verdict instead: a trailing
backslash is read as bash reads it, and a here-document whose delimiter
line never comes is a block, because the rest of the input may be commands
the guard did not check.

Matching is shell-token-aware and applies in command position only, so a
hazard named inside a quoted argument never fires.

The guard is a MISTAKE FILTER, not a security boundary. It catches a hazard
typed by accident or reached through an ordinary wrapper — the cases that
actually cost people work. It does not withstand an author trying to get a
command past it, and it does not claim to: the set of programs that launch
another program is open-ended, so no list inside this binary can enumerate
it, and a repository extends that set with one line in a Makefile. Anything
that needs an enforced boundary needs a control at the execution layer — a
sandbox, a permission system, a restricted shell — with this guard in front
of it to teach, never in place of it.

An allow means no registry entry matched — it is never a statement that a
command is safe. A hazard behind a launcher the guard does not recognise is
a WARN naming the entry it matched, rather than an allow, because the guard
cannot tell whether that program runs the rest of the line. A `$(…)`,
backtick, `<(…)` or `>(…)`, quoted or not, IS followed into command
position, and the words written after one stay the enclosing command's,
so `rm $(true) -rf *` is read as `rm -rf *`. What one prints is unknown,
so a word holding one fails closed, read every way it can be at once: led
by a dash (`--$(…)`) it is every flag it could become — standing alone,
taking a value, a shell's `-c` — before the command as well as after it;
after a value flag (`git -C $(pwd) push`) it is that flag's value; as an
operand it is one operand; in command position (`$(echo git) push`) it is
any program its known text allows, so an unknown name with any operand
reads as `pkill` too; a block that fires only on such a name is reported
as program-name-unknown, and the way past is to spell the program's name.
Text beside one in the same word is also read as bash
leaves it when the output is empty. One nested more than eight
double-quoted substitutions deep, holding a case command, or more than
eight of them where the program name could be, is blocked, because the
guard has stopped reading it. An ANSI-C string ends at its closing quote
and its first NUL, as bash ends it. A `${…}` holding a substitution is
unknown from its `${` on, and inside double quotes it ends at its own
`}`, its nested quotes opening a nested string. A here-document body is
data, but a substitution in one whose delimiter is unquoted runs, and is
read as a command; a body line ending in an odd number of backslashes
joins the next before the delimiter compare, as bash joins it. A
backtick's text is read after bash's own pass over it, which drops a
backslash before `$`, a backtick or a backslash (and, directly inside
double quotes, one before a `"` too), so an escaped `\$(…)`
or an escaped backtick pair between backticks is read as the
substitution bash runs, in a here-document body there too. A
`"$(cat <<'EOF' … EOF)"` handed to `sh -c` or `eval` is read as its
document's text, and an unquoted one as the words bash splits its
document into, at every layer, each joined to any text written
beside it in the same word, as bash joins it; a backtick spelling with
no backslash in it is read the same way. On a line where another command
names IFS an unquoted one is blocked (ifs-split-unread), because the
guard splits on the default IFS only. Two `sh -c` or `eval` layers are
followed; a payload nested deeper is blocked.
`$(( … ))` is an expression, not commands. A shell reading
its script from a pipe, a here-document, a here-string, the stdin device
or a process substitution is blocked, and so is a line over 64 KiB.
An unquoted brace group IS
expanded as bash expands it, and one past 4096 words is blocked. What an
allow still does not see is a hazard that never reaches command position at
all: a word that is wholly a `$(…)` standing where a flag would be (read as
an operand, the way a commit message or a branch is spelled), a delete
target printed whole by one (`rm -rf $(echo /)`, read by its known text
the way `rm -rf $(find …)` names its targets every day), one launched
through a known
wrapper carrying a value-taking flag the guard does not name (`sudo -u bob
<hazard>` is seen; the bundled short form `sudo -Hu bob <hazard>` reaches
only the warn, not the entry that names it),
one whose API path an entry names by its ROOT segment but the host serves
under a prefix (a GitHub Enterprise Server install mounts the same endpoints
under `/api/v3/`; the api.github.com URL form IS read), a parameter
expansion that carries no substitution (`$VAR`, `${VAR:-git}`) wherever it
stands — as the program's name, as a flag (`--$VAR`), or inside an
interpreter payload (an execute-a-string payload IS read — `sh -c`,
`env -S`; one the guard cannot read is warned or, for `env -S`, blocked),
because the guard sees the variable, not what the shell expands it to,
an IFS the shell already holds when the line starts or gains during the
line through a name the guard does not read (every line is read from the
default IFS),
a hazard inside a NON-shell interpreter's payload (`python -c`, `perl -e`) —
one opaque token the tokenizer cannot read, today a silent allow (a warn for
it is a recorded design target, not yet raised),
a lone substitution standing as the whole command (`$(cat msg.txt)`,
`$(date)`), which can be any program but matches no entry with no
operand after it, and so a document printed that way through any shape
but exactly `cat <<DELIM`, a newline, the body, the delimiter line and
blanks (`/bin/cat`, `command cat`, `cat -`, a redirection or a command
beside it, a backslash-newline in it, a `${…}` around it),
or a dangerous form no entry describes. Coverage is what the registry
names.

The candidate comes from --command, or from stdin when the flag is absent.
Prefer stdin for a command line you did not type yourself: the shell expands
a double-quoted --command argument before this verb starts, so a candidate
containing a command substitution would run at check time. A quoted-delimiter
heredoc (`abcd guard check <<'EOF'` ... `EOF`) passes it through untouched.

**Flags:**

```
      --command string   the candidate command line (default: read from stdin)
```

#### `abcd guard hook`

Judge the shell command in a host's pre-tool-use payload: Writes branch records and a question's mode; refuses a hazard or a badly built question.

**Usage:** `abcd guard hook`

Reads a host pre-tool-use hook payload on stdin and evaluates its shell
command against the hazard registry. A blocker is refused with the host's
deny: exit 0 and one JSON object on stdout, hookSpecificOutput carrying
permissionDecision "deny" and a permissionDecisionReason that holds the
safe successor and the plain-language why. The host shows that reason to
the person and hands it to the agent. A line the hook wrote before the
block, such as a notice that the repo's guard file did not load, leads
the reason, because the host discards stderr on exit 0. A warn exits 1
with its message on stderr, and an allow exits 0 printing nothing; both
let the command run.

Anything the adapter cannot turn into a decision — an unreadable payload, a
tool call that is not a shell command, a registry that will not load —
allows the command and warns loudly on stderr. A guard that cannot answer
never stops a session, and is never silently absent. A command line the
guard cannot split is not in that set: it is blocked (command-unparsable),
because a line the guard misreads may be one bash runs, and letting it
through would pass every hazard in it. Unparsable means an unterminated
quote in COMMAND text, which no shell runs either — a quote inside a
here-document body is document text and is not one. A trailing backslash
and a here-document with no delimiter line are grammar a shell does run,
so each gets a verdict — the backslash is read as bash reads it, the
unterminated document blocks.

The hook judges only what the host hands it, and the plugin's hook
manifest hands it the shell tool, the question tool and the host's
file-writing tools (Write, Edit, MultiEdit, NotebookEdit) and nothing else.
A file one of those tools writes is not held to the registry: it is denied
with the host's deny when it lands in a main checkout two or more live
sessions started in, with the refusal the record verbs give, naming the
worktree store. The file's working tree is found by walking up to its .git,
so a linked worktree, a checkout one session or none works in, a path in no
checkout, and a file in a checkout's own local tier (.abcd/.work.local/,
which git ignores) are written silently. A file call naming no path, a
relative path with no absolute session directory, or a count that cannot
be made, lets the write run and warns loudly. A call through
any other tool never reaches the guard: a command a tool from another
extension runs is neither checked nor warned about. That is the guard's
standing scope, not a degradation, and the guard: line of abcd ahoy does
not report it.

A host whose shell tool takes a per-call working directory passes it as
tool_input.workdir. It is resolved against the session directory, and a
command whose workdir is an existing directory in another repository is
checked against that repository's registry as well as the session's; the
stricter verdict wins, so the workdir's registry can add a hazard and never
remove one. The workdir is never read as a cd: the one host that has the
field fails the call when the directory is missing, so no failed-cd hazard
exists. A workdir that is not a string, or holds a NUL byte, a control
character or invalid UTF-8, or is over 4096 bytes, is refused with the
host's deny and the reason.

On the host's question tool the hook checks abcd's own questions instead of
consulting the registry. A question is abcd's when a header is in abcd's chip
grammar (such as Product Q2) or when `abcd mode` names somebody; any other
question is another tool's and runs unchecked. abcd's question is held to
the asking rules' field limits wherever the hook runs, and one that breaks
them is refused with the host's deny, whose reason is a head line counting
the parts, then one line per part naming the tab, the part, the value, the
limit and the remedy. The rows limit is the exception: a question whose
only finding is its height is shown, and the hook's stdout carries a note
for the agent (additionalContext, no permission decision) naming each tab
over the limit and the agent that drafts a question to fit. The hook never
rewrites a question. In a checkout abcd manages, an admitted question
carrying abcd's chip sets `abcd mode` from the chip's role (Product to
product-thinker, Tech and Setup to facilitator), so it is never refused on
the mode, and the question is marked open in the local tier; the answer
resets the mode to managed, from `abcd hook question-answered` on the
question tool's PostToolUse or else on the next human message. A questions
field the hook cannot read lets the question run and warns loudly. While
the away mode holds (`abcd mode autonomous`), every question is refused
first, whatever its chip, with one reason that routes it by the act it asks
about: an act only the person may approve to `abcd mode queue`, every other
question to `abcd decide`; no mode is set and nothing is marked open.

#### `abcd guard question`

Check a draft question as the hook will judge it: Writes nothing; refuses an unreadable draft, a store it cannot read, and any finding.

**Usage:** `abcd guard question [<file>|-] [flags]`

Checks a draft question as the guard hook will judge it when it is asked,
and writes nothing: no mode, no open-question marker, no branch record and
no log. The draft is read from the file named, or from stdin when the
argument is - or absent, under the hook's own 1 MiB bound. Without --ask it
is the host question tool's input, {"questions": [...]}, read as the hook
reads it; with --ask it is abcd's structured question type, decoded
strictly, its structural findings reported under the rule structure, and
composed into the host's input (the material first, the Now: and Change
later: lines next, the question last, the decide-later option last) before
it is judged. A line the draft does not carry is never invented: the
check names it.

The verb reads the stores the hook reads (the away record, and the mode
where the status line's badge shows) and calls the one decision the hook
calls, so it reports every finding, the rows each tab takes at 80 columns
(header and frame, question text, options, total), what the hook would do
with the draft in this checkout now (admit, admit-with-rows-note, refuse,
refuse-away, admit-unchecked or unchecked), whether that answer depends on
the mode or the away record, the binary's version, and the input ready to
ask. The ready input is the draft's own bytes for the host form, every key
the check does not read kept, and the composed input for --ask; it is left
out when the hook would refuse. The verdict is evidence about a hook of the
same version; a mode set, or the person marked away, before the ask can
change it.

The limits judged at are the ones the hook holds abcd's question to in
this checkout: abcd's defaults, with the rows, label words and description
sentences the repository's .abcd/config.json sets under question, each
tightened where the person's own ~/.abcd.noindex/config.json sets it
lower. The result reports them (limits) and the file that set each
(limits_source). A limit the hook refuses (a value outside its bounds, not
a whole number, another key under question, or a personal value looser
than the limit in force) is reported as refused, with no ready input, and
a file that could not be read is named in the partial result, the draft
checked at abcd's defaults, as the hook checks it.

Exit 0 when the draft has no finding at all and every store was read,
whatever the hook would do with it: the hook field says whether that is
an admission, a refusal while the person is away, or a pass unchecked as
not abcd's. Exit 1 on any finding, a tab over the rows limit alone
included.
Exit 2 when the draft is not JSON, is over the bound or has neither shape,
when a question limit is refused, whatever the draft, and when a store the
decision needed, the question limits' files included, could not be read:
the result is then partial, names each store and the rules it could not
apply or applied at the defaults, and never reads as clean, even with no
finding.

**Flags:**

```
      --ask   read the draft as abcd's structured question type and judge it as composed into the host's input
```

### `abcd help`

Help about any command

**Usage:** `abcd help [command]`

Help provides help for any command in the application.
Simply type abcd help [path to command] for full details.

### `abcd history`

Keep session transcripts in the user-level store and read them back: Writes nothing bare, and redacts each one it stores; refuses an unknown sub-verb.

**Usage:** `abcd history`

#### `abcd history capture`

Redact and store a session transcript, or a whole session with --all: Writes one record per transcript; refuses stdin or --all without --session.

**Usage:** `abcd history capture [<transcript-file> | - | --session <id> --all <path>...] [flags]`

**Flags:**

```
      --all              capture every transcript of the --session named — its main thread and each sub-agent — found under the paths given (default: ingest_roots)
      --kind string      source route: native (abcd's own capture of the host's transcript) | import (another tool's export) (default native)
      --session string   session id for the record (default: transcript filename; required for stdin)
      --tool string      source tool: the tool that produced the transcript, a lowercase slug (default host on a native capture; required on an import)
```

#### `abcd history discard`

Delete one staged or quarantined raw transcript for good: Writes the deletion; refuses without --yes.

**Usage:** `abcd history discard <staged-filename> --yes [flags]`

**Flags:**

```
      --pending           discard a transcript session-end left pending that no session start could file in a store
      --root-sha string   discard from the repository with this root-commit SHA, with no checkout to stand in (one whose checkout is gone)
      --yes               confirm the irreversible deletion of an unredacted transcript
```

**Example:**

```
abcd history discard 0123abcd-session.raw --yes
```

#### `abcd history drain`

Redact and store every transcript staged for this repository: Writes the records into the store; refuses outside a git checkout.

**Usage:** `abcd history drain`

#### `abcd history ingest`

Redact and store transcripts already on disk into a named repository: Writes that repository's store; refuses without --into.

**Usage:** `abcd history ingest [<path>...] [flags]`

**Flags:**

```
      --adopt stringArray   project directory name to claim for this run, in addition to adopt_projects (repeatable)
      --into string         destination repository root (REQUIRED, no default; its own redaction configuration governs everything stored)
```

#### `abcd history list`

List this repository's stored transcripts, newest first: Writes only a missing store and a legacy corpus moved into it; refuses outside a git checkout.

**Usage:** `abcd history list [flags]`

**Flags:**

```
      --session string   list one session's whole set — its main-thread record and every sub-agent it spawned, main thread first
```

#### `abcd history migrate`

Repair records filed under a composite session id: Writes a missing store, and the repaired records only with --apply; refuses outside a git checkout.

**Usage:** `abcd history migrate [flags]`

**Flags:**

```
      --apply                      write the repaired records (default: report only)
      --sidecar-root stringArray   directory to search for the harness's per-agent metadata (repeatable; default: ingest_roots from .abcd/config/history.json)
```

#### `abcd history reconstruct`

Render one session and its sub-agents as one artefact plus telemetry: Writes both files into --out; refuses an --out that is not an existing directory.

**Usage:** `abcd history reconstruct <session-id> [flags]`

**Flags:**

```
      --max-block-bytes int   truncate one rendered tool input or result at this many bytes (0 disables); what is removed is marked and counted (default 8192)
      --mode string           full (every turn of every agent) | spine (the main thread whole, each sub-agent reduced to its instruction and its conclusion) (default "full")
      --out string            directory to write <session>.md and <session>.telemetry.json into, or - for stdout (default ".")
```

**Example:**

```
abcd history reconstruct 0123abcd-session
```

#### `abcd history separation`

Report whether a retained transcript held both a reading and one run's ledger: Writes a missing store or a legacy corpus move; refuses outside a git checkout.

**Usage:** `abcd history separation`

Report whether any retained transcript held both a reading and the ledger of one run, from
record metadata alone. The store is resolved as every history read resolves it: a missing
store is created and a legacy corpus moved into it. A transcript that held both is a finding:
each is named and the verb exits 1. Outside a git checkout with a commit it refuses.

#### `abcd history show`

Show one stored transcript's metadata and redacted body: Writes only a missing store and a legacy corpus moved into it; refuses an id the store does not hold.

**Usage:** `abcd history show <session-id-or-filename>`

**Example:**

```
abcd history show 0123abcd-session
```

#### `abcd history staged`

List the ended transcripts not yet redacted into the store: Writes only a missing store and a legacy corpus moved into it; refuses outside a git checkout.

**Usage:** `abcd history staged [flags]`

**Flags:**

```
      --all-repos         survey every repository in the store, not just this one
      --root-sha string   list the pile of the repository with this root-commit SHA, with no checkout to stand in (one whose checkout is gone)
```

### `abcd ideate`

Judge an idea through the host-run admission gauntlet: Writes nothing bare, and one verdict record, private or public; refuses an unknown sub-verb.

**Usage:** `abcd ideate`

Record the verdict of abcd's idea-admission protocol — primary-source research, a grill
against the existing record, and an independent adversarial review.

The legs are host work; `/abcd:ideate` orchestrates them. This verb validates what they
produced and writes the durable verdict. Ideate is OPTIONAL and never a gate: no other
verb requires it, and skipping it is never warned about.

#### `abcd ideate record`

Validate a host-composed gauntlet verdict: Writes the dated record, private unless --public; refuses without an idea slug or --verdict-json.

**Usage:** `abcd ideate record <idea-slug> [--private | --public] --verdict-json <file|-> [--dry-run] [flags]`

**Flags:**

```
      --dry-run               check the input and report what would be written; write nothing
      --private               the idea is private, the default: record the verdict in ~/.abcd.noindex/ideas/<root-sha>/, owner-only, with no decision pointing at it (exclusive with --public)
      --public                the idea is public, on the person's word only: commit the verdict under .abcd/development/research/ideas/<root-sha>/ and record a decision pointing at it (exclusive with --private)
      --verdict-json string   path to the host-composed verdict JSON (or - for stdin)
```

**Example:**

```
abcd ideate record widen-the-public-api --verdict-json verdict.json
```

### `abcd identity`

Record the identity block and propose drift corrections: Writes nothing bare, only the block and its pointer; refuses an unknown sub-verb.

**Usage:** `abcd identity`

#### `abcd identity init`

Record this repository's identity block and the pointer to it: Writes the block and the pointer; refuses without --title and --tagline when no block exists.

**Usage:** `abcd identity init [flags]`

**Flags:**

```
      --file string      repo-relative file the identity block lives in (default .abcd/development/IDENTITY.md)
      --heading string   heading the identity block sits under (default "Identity (canonical)")
      --pitch string     the project's short elevator pitch (optional)
      --tagline string   the project's one-line tagline (required unless a block already exists)
      --title string     the project's title (required unless a block already exists)
```

#### `abcd identity render`

Print the correction for every drifted surface as a unified diff: Writes nothing; refuses a repository that records no identity block.

**Usage:** `abcd identity render`

### `abcd implement`

Share one autonomous run between sessions and drive the implement loop: Writes nothing bare, only the run state its sub-verbs name; refuses an unknown sub-verb.

**Usage:** `abcd implement`

The run machinery an autonomous run calls. The shared run lives in the machine-scoped run
state, `~/.abcd.noindex/runs/<root-sha>/`, keyed on the repository's root commit, so sessions
in different worktrees of one repository share one run and no repository file.

Bare `abcd implement` is read-only: the sessions that have joined, the claims and
whether each lease still holds, and the window's division mode. It creates nothing.

A session joins (`join`), which writes its record and a session_open line; nothing
signals any other session. The first session opens each window with its mode
(`mode`). A session claims a record before opening its lane (`claim`): one file per
record, taken by an exclusive create, so of two sessions reaching for one record
exactly one holds it; the claim is a lease, and a lapsed lease is claimable again.
The second session is bounded: one lane at a time, never the release, never a lane
that touches the reading corpus, no lane in a split-roles window (`check` asks before
a stage that is not a claim). `log` appends the run's other events, and `report`
derives the comparison of the modes from the log.

`status`, `step` and `receipt` drive the implement loop `abcd build` starts, whose state
lives in this checkout's local tier: `step` performs the next stage of the current lane
and exits, naming the agent, brief and receipt path when a stage hands work to an agent,
and `receipt` completes that stage once the receipt verifies.

Exit 2 on a refusal (an unrecognised input, a session that has not joined, a bound
the session's role does not permit), exit 3 on contention (the record is claimed by
another session, or the run state is locked): back off and take other work.

#### `abcd implement check`

Ask whether this session may take a stage before taking it: Writes a run-log line only on a refusal; refuses a stage the second session's bounds forbid.

**Usage:** `abcd implement check <lane|release|review|audit|land> --session <id> [flags]`

Say whether this session may take a stage, before it takes it. The first session may
take every stage. The second is refused the release stage always, a lane in a
split-roles window, and a lane whose --path reaches the reading corpus; review,
audit and land are open to it. A refusal exits 2 and is logged; an allowed stage
writes nothing. The verdict reports the agent ceiling the session joined with and the
agents its log lines declare alive (agents_alive).

**Flags:**

```
      --path stringArray   a repository-relative file the stage touches (repeatable)
      --session string     this session's id
```

**Example:**

```
abcd implement check lane --session s-example
```

#### `abcd implement claim`

Claim a record for this session before opening its lane: Writes the claim and a run-log line; refuses a record another session holds.

**Usage:** `abcd implement claim <record> --session <id> --lane <lane> [flags]`

Take a record for this session: one claim file per record in the run state, created
exclusively, so of two sessions reaching for one record exactly one holds it. The
claim is a lease (--lease, default 2h, 1m to 24h). Claiming a record this session
already holds renews the lease. A claim whose lease has passed is claimable again,
and the lapse is logged as claim_lapsed. A record another session holds is refused
at exit 3 and logged as claim_denied naming the holder; the second session also
logs a backoff with its reason and the minutes the attempt spent. A run state
locked by another session's change is exit 3 too, and the second session's
backoff from it is logged the same way.

The second session is refused (exit 2, logged as a refusal) when it already holds
a live claim, when the window is split-roles, or when a --path it declares is in the
reading corpus.

**Flags:**

```
      --lane string        the lane the claim is for
      --lease duration     how long the claim holds before it lapses (1m to 24h) (default 2h0m0s)
      --path stringArray   a repository-relative file the lane will touch (repeatable); checked against the reading corpus
      --session string     this session's id
```

**Example:**

```
abcd implement claim iss-2609010000000001 --session s-example --lane cli
```

#### `abcd implement join`

Join the run with a stated role: Writes the session's record and a session_open line; refuses the other role on a resume.

**Usage:** `abcd implement join --session <id> --role first|second [flags]`

Record this session in the run state with its role and log a session_open line.
Nothing signals any other session: the first learns of a second only by reading the
run state. Joining again with the same role is a resume and is logged as one; asking
for the other role is refused. The role is the session's own statement, recorded
here and read by every bound — never taken from the environment.

--ceiling states the session's own agent ceiling: the most agents it runs at once (for
the second session, on top of the first session's). abcd does not run a session's agents: it counts the
agents the session's own agent_start and agent_end lines declare alive, refuses an
agent_start past the ceiling, and reports the count with every `check`. An agent the
session never logs is invisible to it. A resume keeps the ceiling.

**Flags:**

```
      --ceiling int      this session's own agent ceiling (1 to 64; 0 states none), held against its logged agent_start lines
      --model string     the model this session runs, recorded on the session_open line
      --reason string    why the session opens (run start, window, resume), recorded on the line
      --role string      first | second
      --session string   this session's id (letters, digits, '.', '_', '-')
```

**Example:**

```
abcd implement join --session s-example --role first
```

#### `abcd implement leave`

Leave the run, releasing every claim this session holds: Writes the releases and a session_close line; refuses without --session.

**Usage:** `abcd implement leave --session <id> [flags]`

Release every claim this session holds (each logged as claim_released), log a
session_close line with the reason, and remove the session's record. A session
that stops without leaving strands nothing: its claims lapse with their leases.

**Flags:**

```
      --reason string    why the session closes (window, stop condition, crash recovery)
      --session string   this session's id
```

**Example:**

```
abcd implement leave --session s-example
```

#### `abcd implement load`

Check the load before abcd's tests start, or wait for capacity: Writes a run-log event or the wait's hold; refuses an unknown --site, never a loaded machine.

**Usage:** `abcd implement load --site preflight|eval-harness | --wait [--timeout <duration>] [-- <command>...] | --race-gate [--timeout <duration>] [flags]`

Read the machine's load averages and process table once and warn when a program
outside the running work has used nearly all the CPU it could get for longer than
the stray limit, or when the one-minute load average is above the extreme limit.
What a program could get is its fair share: the online cores divided by the
one-minute load, and never more than one core. A lifetime CPU share of at least 0.9
of it makes a stray, so forty busy loops on 16 cores, each at 0.4 of a core, are all
strays, as one loop at a full core of an idle machine is. Your programs and other
accounts' are judged alike. `make preflight` runs it first, and the eval harness runs
it once at its start; it never runs once per test package. Without --wait it never
refuses, never waits and never stops anything, and it exits 0 on every status: ok, warning, skipped
(in CI, where the line says why) and unchecked (a platform other than macOS and
Linux, or a read that failed).

Your own strays are named with their pid, process group, age and CPU share, with
commands to stop them that re-check each target first and never match by pattern;
names the private banned-names layer matches are masked. Other accounts' strays
appear only as a count and a total CPU share. The check's own parent chain is never
a stray. Inside an autonomous run (a run state with a joined session) a warning is
also written to the run log as a `load` event.

The limits are per machine, in `~/.abcd.noindex/load-limits`, which the check reads and
never creates. `#` starts a comment; every other line is `<key> <value>`:

  stray-minutes 30   minutes at nearly all its share before a program is a stray (1 to 10080)
  extreme-load 64    the one-minute load above which the machine is overloaded

Either key may be omitted. The defaults are 30 minutes and four times the online
core count. The file must be a regular file you own that nobody else can write, at
most 4 KiB; a file that is not, or that holds an unknown key, a repeated key or a
value out of range, is reported loudly and every default is used.

With --wait it waits for capacity instead of warning, and it is the one waiter
concurrent sessions gate a preflight or a race run with, in place of a hand-written
loop; `make preflight` waits at it once, as one whole run (a records-only change
waits at no gate). It blocks until the
one-minute load average is below the wait limit (`wait-load <load>` in the same
file; by default twice the online core count), no other `go test -race` run is
live, no other `make preflight` is running and no other waiter is ahead of it in
the queue (one that started earlier, whatever its pid, or within two seconds of
it with the lower pid) or running its command, under any account: all of it is
read from the process table, which shows every account's processes: no file
another account can write is read; the gate reads only the process table (and,
for the wait limit, your own load-limits). A waiter ahead of yours still delays
yours until it opens or reaches its own --timeout, whatever account it runs
under and whatever its own account's wait limit is, with one exception: a
waiter ahead with a higher pid, as after the process ids wrap, may run an abcd
built before this order, which waits on every lower pid and so on yours, so once
such waiters alone have kept yours shut for 5m0s on end, and a step more
for each such waiter ahead beyond the first, yours stops counting them. A
preflight whose own
waiter is queued
takes that waiter's place in the queue, and a waiter beneath a waiter running its
command (`--wait -- make preflight`) takes that ancestor's place, ahead of every
queued waiter. Once it finds all of that clear it waits
a random 15s to 1m0s and checks everything again, and opens only if the
re-check is clear too, so two starters in one quiet minute do not start together.
With a command it then shows itself as running it and looks once more 2s
later, before starting it: across accounts, which share no hold, two waiters can
open in one moment, and each stands back from the other unless it started earlier
and has the lower pid too: it gives up its hold, re-draws its jitter and waits
again (at most 3 times), while the other runs its command. So the later
start stands back whatever the pids, and the earlier one from a lower pid as well,
which an older abcd (v0.15.1 and earlier) lets run.
The load limit is twice the cores because a busy multi-session machine already
idles near one core-count of load, so a limit of the cores never opens; one
waiter at a time is kept by the process table, the hold below and that last
look, not by the load number; and one race run adds about a core-count, so admitting below twice
the cores bounds the peak near three times them, under the extreme limit.
A race run is a process executing go whose go command is `test` with -race, a
preflight a make whose goals name preflight, and a waiter an abcd running
`implement load --wait`, each read from its arguments, never from a pattern over a
command line, and the waiter's own process and ancestors are never one: a
hand-written `pgrep -f "go test -race"` matched its own shell and never opened.
It reads the machine every 15s, prints one line when it starts waiting and
one when it first finds the machine free, and nothing more until it opens, and
gives up after --timeout (30m0s by default), exiting 1 and naming what it
was still waiting on. --json reports what it waited on and for how long.

With --race-gate in place of --wait it waits at the race gate, which `make
preflight` runs before its race stage. It takes no command after `--`: it gates
the race stage that follows it, and a race run of your own goes through
`--wait -- go test -race`. It is spelt without --wait because an
older abcd reads any `implement load --wait` as a waiter at its first gate, and
would count a preflight at its race gate as queued, not in its tests, so the two
are refused together. At one preflight at a time, the default, it opens at once
once the disk check below passes and memory (below) does not hold it, without
reading the load or the process table (read, inside a memory episode, only to ask
whether the waiter admitted last is its own ancestor), taking a hold or waiting a
jitter, so a
preflight's race stage follows its tests as before. Above one it is shut while
another `go test -race` run is live, a race waiter is ahead of it (by the same
rule) or running its command, the load is at the wait limit, memory holds it
(below), or the race gate's own hold is in force (each gate is shut only by its
own gate's hold). That keeps
race stages apart among the preflights whose checkouts have the race gate: one
at a time within an account, and across accounts all but a narrow window (a
race waiter gone before its race run shows, or, after a pid wrap, two waiters
whose start and pid disagree: one running v0.15.1, which counts a waiter ahead
only with the lower pid as well, or two of the start order whose whole-second
ages read a tie differently or the later of which stopped counting the earlier
past its 5m0s cap). An account at one opens its race gate at once
whatever another account set, and a checkout older than the gate runs its race
stage ungated, so set more than 1 only once no such checkout runs a preflight. A
first gate's waiter never queues behind a race waiter. A preflight whose race
waiter is queued runs nothing: at 1 it still takes its slot, and
above 1 it takes no slot until its race run starts, which the race gate keeps
to one at a time. A waiter that has opened stands back only from a waiter that
opened in the same moment at its own gate, never from one at the other gate.

How many preflights the first gate admits at once, each a whole run, is your
own machine's setting: `load.preflights` in `~/.abcd.noindex/config.json`, or ABCD_LOAD_PREFLIGHTS in the
environment, which wins, for a trial; a whole number from 1 to 4, 1 by default,
and never read from a repository file, so a checkout cannot raise the machine's
load. At 1 both gates read as before the setting existed. Above 1 the
first gate opens while fewer than that many other preflights or gated commands
are running (a `--wait -- make preflight` counts once), a waiter queued ahead
still shuts it, and a live race run does not shut
it by itself; the load limit still does, and the race gate keeps race stages
apart, so one race stage may run beside that many unit stages. A value it
cannot use refuses the wait, naming where it was set. A `~/.abcd.noindex/config.json`
that cannot be read for it (writable by others, not valid JSON, or a `load`
that is not an object) is read past instead: one preflight at a time applies,
and one line on stderr names the file, the cause and how to fix it; so does a
key under `load` that nothing reads.

Both gates refuse, exiting 1 without waiting, while the volume holding the Go
build cache (`go env GOCACHE`) or the one holding the worktree store
(`~/.abcd.noindex/worktrees`) has less free space than the disk floor: 4 GiB for each
preflight the first gate admits at once (`load.preflights`), and 8 GiB at least, so
8 GiB at the default and 16 GiB at four. The waiter reads the disk as it starts
and again just before it opens (the race gate at one preflight at a time reads
it as it starts and at each look while memory holds it), and refuses at any such
look. The refusal names
each low volume, its free space and the floor, and, when the cache's own volume
is low, the cache's size and a command that deletes its build entries unused for
two days. A disk it cannot read, in whole or in part, is never refused: one line
on stderr says it was not checked, and why. The load check (`--site`) prints the
same finding as a warning and never fails for it.

Both gates also stay shut while the system reports memory pressure at or above
your floor: on macOS its own pressure level (kern.memorystatus_vm_pressure_level)
at `load.memory_floor_macos` (`warn`, the default, or `critical`), and on
Linux the share of the last ten seconds some task stalled waiting for memory (the
`some avg10` of /proc/pressure/memory, Linux 4.20 or later) at `load.memory_floor_linux`
(a whole percentage from 1 to 100, 10 by default), each in `~/.abcd.noindex/config.json`
and never read from a repository file: a repository's key is named on stderr as
ignored. A value outside its set refuses the wait, naming the key. Memory waits
rather than refuses, since pressure falls as other work finishes: it is read at
every look and again just before the gate opens (and before the race gate at one
preflight at a time opens, which, once memory has held it, says it opened after
its wait, not at once), the waiting line names the level or the
stalled share and the floor, and a wait still shut at --timeout names memory. A
reading it cannot take (a kernel without the file, a read that fails, or another
platform at the race gate at one preflight at a time) shuts nothing: one line on
stderr says memory was not checked, and why. Any other gate on another platform
opens unchecked, reading no memory.
After any waiter of your account saw the pressure at the floor, for 10m0s the gates
admit one run per 2m0s, in queue order, reading memory again before each, so
the stage just admitted shows its own memory use before the next starts
(`~/.abcd.noindex/load-memory-admit.json` records it; a record it cannot read or write
is named on stderr and holds nothing back). The load check (`--site`) prints a
reading at the floor as a warning, and one it cannot take as a memory check line on
stdout, and never fails for either.

Within one account the waiter that opens also takes a hold,
`~/.abcd.noindex/load-wait.json` at the first gate and `~/.abcd.noindex/load-wait-race.json` at
the race gate, and every other waiter of that account at the same gate stays
shut while it is in force; a hold taken by the waiter's own ancestor does not
shut it.
Without a command the hold lasts 2m0s, long enough for the load average to show
the work admitted. With a command after `--` (`abcd implement load --wait -- go
test -race ./...`) the waiter runs it once the gate opens and exits with its exit code,
or with 128+N, as a shell does, when signal N killed it;
the hold lasts until the command has started its own race run, the command exits,
or 60 minutes pass (above one preflight at a time, a command that is not a
race run holds it for 2m0s, as the plain form does), and a hold whose waiter has
died, or whose pid now belongs to another process (a different start time), is
reclaimed by the next waiter. A SIGINT or SIGTERM to the waiter is passed on to
the command, and the waiter waits for it to exit, exits with its code and
releases a command hold (a settle hold lapses on its own). A
command that is a race run (go, then `test` with -race) is gated as one for both
gates: above one preflight at a time it stays shut while another race run is
live, judges and takes the race gate's hold as well as its own, and from the
moment it opens every race gate and every other such command counts it as a
race run, so a second one waits for the first. A command that is not a race run
takes the command hold only at one preflight at a time; above one its hold lasts
2m0s, as without a command, and the process table counts it in its slot.
A command hold lasts until its command exits, starts its own race run or has run
1h0m0s, so once
the holder's whole process tree has used no more than
10% of a core for 10m0s, each waiter behind it says so in one more
`waiting for capacity:` line naming its pid, its checkout and how long it has held
the slot, and the holder says so on its own standard error while others queue.
Little CPU is a fact, not a verdict: a slow run waiting on its subprocesses uses
little too. The hold stays in force and nothing is signalled; a tree with a
waiter of its own queued at a gate is not counted quiet; only your own
account's hold is said quiet. Every waiting line also names each holder ahead,
of any account, after `holding:`, with its age and its tree's CPU over the last
10m0s, or `not yet measured` until this waiter has watched it that long, and
marks one `quiet:` in place of `using` once that CPU is no more than 10%
of a core and no waiter of its own is queued at a gate, whatever hold it is
under, so a stalled run above one preflight at a time, which no notice names,
still reads as one. The line is said again every 10m0s while the gate
stays shut. A child that starts
and exits between two looks is never seen, so a tree of short children (git)
reads low, and counts as working: neither the notice nor the mark calls it
quiet; a waiter's own reads of the table and its renewals' git and gh in the
tree are not counted. A
symlinked ~/.abcd.noindex is refused. On a CI runner it opens at once.

While it waits, and while its command runs, in a checkout, the waiter keeps
your own reservations from lapsing: at once and then every five minutes it
renews each of your live
reservations that is half through its lease and whose latest commit this copy
pushed, for its own term or
two hours, whichever is longer, and says each renewal on standard error. Your
own reservations it only renews: it reserves nothing new, takes nothing over and
revives none that has lapsed, so a lease shorter than ten minutes can still lapse between two rounds;
a renewal that fails, or a reservation whose latest commit this copy did not push (or pushed before it kept a note of it), is said once, and the wait goes on.
On the same rounds it renews, as implement step does, the due reservation of
each run in progress that lives in this checkout, or in another worktree of
the repository with a lane whose worktree is this checkout, reviving one that
has lapsed and logging each in the run record, but not a run parked at land,
which the drain renews; while another invocation holds the checkout's run
lock the round skips that checkout's runs, and the next round renews them. Each is said
on standard error, a failure once until what is said of it changes. The
renewal runs beside the gate, never in it, so
the gate's order and its open never wait on one; it stops when the waiter
exits, its command done or, without one, its gate open, waiting at most 5s
for a round in flight to finish and be said, so a renewal still pushing then may go unsaid,
since a waiter lingering on a slow push reads as queued and holds every other gate shut.
Since it runs through git and gh, no waiter counts another's git or gh
child as its command: gate make or go, never git or gh itself.

**Flags:**

```
      --race-gate          wait at the race gate, before a race stage, instead of the first gate: open at once at one preflight at a time unless the disk is below the floor or memory pressure is at or above its floor, and above that shut by another go test -race run, a race waiter ahead, the load, memory pressure and the race gate's hold
      --site string        where the check runs: preflight | eval-harness
      --timeout duration   with --wait or --race-gate, give up after this long and exit 1 (default 30m0s)
      --wait               wait until the load is below the wait limit and no other go test -race run is live
```

**Example:**

```
abcd implement load --site preflight
```

#### `abcd implement log`

Append one of the run's events to today's run log: Writes one line; refuses the claim, window, and session events their own verbs write.

**Usage:** `abcd implement log <event> --session <id> [--field key=value ...] [flags]`

Append one event line to today's run log (`~/.abcd.noindex/runs/<root-sha>/<UTC date>.jsonl`)
in a single append, so two sessions writing at once each land whole lines. The line
carries ts, session and event, then each --field. A value that reads as a number or
a boolean is written as one when it reads back as the same text, so `sha=0123456`
stays a string. The events: backoff, lane_open, lane_close, agent_start, agent_end, ceiling_wait, gate_run, review, fallback, stop, refusal, pr, capture, context, ceiling_overrun, intervention, decision.
The claim, window and session events are written by their own sub-verbs and are
refused here, so the log cannot record a claim the run state does not hold.

An event missing a field the report reads is refused, naming it: lane_close (lane, outcome); agent_start (agent); agent_end (agent, role, model, minutes|wall_minutes|wall_min); stop (cause); ceiling_overrun (alive, ceiling, lane, minutes); intervention (kind, by, what, why, autonomy_gap); decision (what, alternative, why).
A backoff names its reason and the minutes it spent (reason=<why>, minutes=<n>),
or it is refused. An intervention's kind is one of session_open, account, ruling, restart, close_session, file_restore, permission, other; an at or
last_productive is an RFC 3339 time, and a *_min or minutes field a number. An agent_start
that would take a session past the ceiling it joined with is refused, and the refusal logged.

**Flags:**

```
      --field stringArray   an event field as key=value (repeatable)
      --session string      this session's id
```

**Example:**

```
abcd implement log lane_open --session s-example
```

#### `abcd implement mode`

Open a window by logging its division mode: Writes a window_mode line; refuses any session but the first.

**Usage:** `abcd implement mode <single|claim|batch|split-roles> --session <id> [flags]`

Log a window_mode line naming how this window divides the work: `single` (one
session), `claim` (a session claims a record before opening its lane), `batch` (the
run file assigns whole batches per session), or `split-roles` (the first session
builds; the second reviews, audits and lands). Only the first session sets it. The
mode in force is the log's last window_mode line, whoever wrote it.

**Flags:**

```
      --session string   this session's id (a first session)
      --window int       the window's number, recorded on the line
```

**Example:**

```
abcd implement mode single --session s-example
```

#### `abcd implement outage`

Render the run's shared lost connection and when its next probe is due: Writes nothing; refuses any argument.

**Usage:** `abcd implement outage`

The run's shared lost connection. A lane that loses the network (git, gh, a
download) or the model service (an agent back overloaded, with a 5xx, a timed-out
request or a lost connection) records it (`record`); the run keeps one outage record
in the run state, and every lane keeps to offline work and waits on one shared
probe (`probe`) instead of retrying alone. The probe runs a minute after the
outage opens, then five minutes and ten minutes after each failed probe, then
hourly; the failed probe eight hours into the hourly stage gives up, stops the
run and raises one notification, held until a session acknowledges it (`ack`).
An authentication error (401), an invalid request (400) or a usage or rate limit
(429) is not an outage: the service answered, so it is an ordinary failure.

The network is proven back by `git ls-remote origin HEAD`; the model service only
by a canary agent the lead runs and reports with `probe --model ok|fail` — the
lead's own turn running is not proof. The outage ends when every service down is
proven back, and `report` lists each outage with its minutes and what was retried.

Bare `abcd implement outage` is read-only: the outage in force, the services down,
when the next probe is due and who holds it. It creates nothing.

##### `abcd implement outage ack`

Acknowledge the notification an outage's give-up raised: Writes the outage record; refuses when no notification is pending.

**Usage:** `abcd implement outage ack --session <id> [flags]`

Acknowledge the give-up's notification once the product thinker has been told.
Refused when no notification is pending, so it is never raised twice.

**Flags:**

```
      --session string   this session's id
```

**Example:**

```
abcd implement outage ack --session s-example
```

##### `abcd implement outage clear`

Close the run's outage by hand, with the reason: Writes an outage_end and an intervention line; refuses without --reason.

**Usage:** `abcd implement outage clear --session <id> --reason <why> [flags]`

Close the outage by hand, open or given up. It logs outage_end with the reason and
an intervention: the shared probe did not prove the connection back on its own.

**Flags:**

```
      --reason string    why it is cleared by hand
      --session string   this session's id
```

**Example:**

```
abcd implement outage clear --session s-example --reason "the network is back"
```

##### `abcd implement outage probe`

Run the shared outage probe when it is due: Writes the probe's result and its run-log lines; refuses a run that gave up.

**Usage:** `abcd implement outage probe --session <id> [--model ok|fail] [flags]`

Run the shared probe if it is due and no other session is running it. The network,
when down, is probed with `git ls-remote --exit-code origin HEAD` (20s at most); the
model service, when down, takes --model, the verdict of the canary agent the lead
ran — without it the model side stays down. Read the bare verb's next probe time
before running the canary, so it runs once per due probe.

Exit 0: no outage, or every service proven back — the network step may go ahead.
Exit 3: wait — the probe is not due, another session holds it, or a service is
still down; --json carries next_probe_at. Exit 2: the run gave up, or a refusal.

**Flags:**

```
      --model string     the canary agent's verdict on the model service: ok | fail
      --session string   this session's id
```

**Example:**

```
abcd implement outage probe --session s-example
```

##### `abcd implement outage record`

Report a lost network or model-service connection: Writes the outage record and, opening it, an outage_start line; refuses an unknown service or kind.

**Usage:** `abcd implement outage record --session <id> --service network|model --kind host|agent|tool --lane <lane> --what <text> [flags]`

Report a lost connection: the service lost (network or model), what noticed it
(host: the host's own model calls; agent: a sub-agent back failed; tool: a tool's
network call), the lane and what it was doing. The first report opens the run's
outage and logs outage_start; a later one joins it. A report to an outage that
gave up joins it and raises no second notification.

**Flags:**

```
      --kind string      what noticed it: agent | host | tool
      --lane string      the lane that lost it
      --service string   the service lost: model | network
      --session string   this session's id
      --what string      what the lane was doing (the step it will retry)
```

**Example:**

```
abcd implement outage record --session s-example --service network --kind tool --lane cli --what "git push"
```

#### `abcd implement receipt`

Hand back the receipt an agent stage of a loop run awaits: Writes the run's state when the receipt verifies; refuses a receipt that does not verify.

**Usage:** `abcd implement receipt <path> [--run <run-id>] [flags]`

Hand back the receipt a lane of the run named when its stage handed work to an agent.
The path is looked up among every outstanding await of the run, and the lane it belongs
to advances; a path no await names is refused, naming the awaits there are, and frees
nothing. The stage's verifier checks it; a verified receipt frees its slot, and a
receipt that verifies completes the stage and the lane moves to its next stage, and one
that does not is refused naming what is missing, with the lane left where it was. A
stage whose verifier this abcd does not carry is refused naming the spec piece that
delivers it.

An implementer's receipt is read strictly (one JSON object, no field the brief does not
name, within its size cap, never through a symlink) and verifies only when every commit
it names is on the lane's branch past its base, the definition of done's output exists
in the lane's directory with a zero exit code, and the report exists there. A receipt
that verifies moves the lane's head to its branch's tip. Its optional resolves list names
each capture the lane fixed, with the commit that fixed it (one the receipt names), the
note, the impact and the grounds; the landing resolves each.

At the validate stage the receipt is the validator's return: a reviewer's is refused
unless it has one Verdict section stating one verdict of its role (SHIP or FIX FIRST;
APPROVE, BLOCK or NEEDS-INPUT), and the intent-auditor's unless it is the fidelity verdict
the request asked for, echoing its receipt and both provenance hashes. The loop records
the verdict and the lane stays at validate for the next validator. A fresh implementer's
receipt after a round is verified as an implementer's is.

--run names the run; without it, the one run in progress in this checkout. Exit 2 on a
refusal, exit 3 on a locked run state.

**Flags:**

```
      --run string   the run the receipt belongs to (run-<16 digits>); the one run in progress when omitted
```

**Example:**

```
abcd implement receipt review-receipt.json --run run-2609010000000001
```

#### `abcd implement record`

Render a loop run's record and capture its transcripts: Writes only with --transcript; refuses it on a run in progress.

**Usage:** `abcd implement record [--run <run-id>] [--transcript <path>]... [flags]`

Render a run's record: every lane with its spec step, branch and head, the implementers'
receipts the loop verified with the model each runner reported, every verdict the loop
recorded from a validator's return, the captures each lane fixed, its pull request and
what its landing did, the route that ran each receipt's or return's agent when a runner
ran it, every fallback from a routed runner to the host with its count per runner and
per role, the transcripts captured into the history store, the pick a run `abcd build
next` started from (its score table, and whether a lane handed back after its fix rounds
met its falsifier), and the record's lines. Read-only unless --transcript is given.

--transcript <path>, repeatable, captures each transcript into the history store as
`abcd history capture <path>` does, one capture per path, and records it in the run's
state; it is refused on a run that is not complete, since the record's transcripts are
the run's, captured at its end. A capture that fails stops the call: the transcripts
before it are recorded, and the refusal names the failure.

--run names the run; without it, the one run in progress, or else the most recently
started run. Exit 2 on a refusal, exit 3 on a locked run state.

**Flags:**

```
      --run string               the run to render (run-<16 digits>); the one in progress, else the latest, when omitted
      --transcript stringArray   a transcript to capture into the history store for a complete run (repeatable; one capture per path)
```

#### `abcd implement release`

Release this session's claim on a record: Writes the release and a claim_released line; refuses a claim another session holds.

**Usage:** `abcd implement release <record> --session <id> [flags]`

Remove this session's claim on a record and log claim_released. Only the holder
releases a claim; another session's claim lapses with its lease instead.

**Flags:**

```
      --session string   this session's id
```

**Example:**

```
abcd implement release iss-2609010000000001 --session s-example
```

#### `abcd implement report`

Derive the comparison of the division modes from the run log: Writes nothing; refuses --date and --log together.

**Usage:** `abcd implement report [--date YYYY-MM-DD | --log <file>] [flags]`

Derive, per division mode, the figures the run's report compares: windows, wall
clock, lanes opened and landed (a lane_close whose outcome is merged or landed),
the second session's lanes landed, collisions (claim_denied), lapsed claims,
backoffs and the minutes backed off, agent minutes (agent_end's minutes, wall_minutes
or wall_min), ceiling wait, ceiling overruns and refusals, per session within each mode.
Each event belongs to the window open when it happened, and a join logged at most a
minute before a window_mode to that window; each session's context lines are totalled
across the run, with the last used_pct seen. `leader` is the mode with the most lanes landed per wall-clock hour —
a figure, not a verdict. Over the whole run it counts the evidence (interventions by
kind, stops, decisions), names the lines lacking a field `log` requires of their event
(missing_fields), and names each of lane_open, lane_close, agent_start, agent_end and
gate_run whose lines stop more than six hours before the run's last line (coverage),
and lists each outage with its minutes, how it ended and what was retried (outages).
Lines the reader cannot use are listed, never dropped silently.

By default the run's whole log is read, every day of it; --date reads one day, and
--log reads one log file named directly. Reads only; creates nothing.

**Flags:**

```
      --date string   read one day's log (YYYY-MM-DD, UTC)
      --log string    read this log file instead of the run's own
```

#### `abcd implement status`

Render the implement loop's runs in this checkout, lane by lane: Writes a due renewal to origin, its outcome to the run record; refuses a --run naming no run.

**Usage:** `abcd implement status [--run <run-id>] [flags]`

Render the runs `abcd build` started in this checkout, or the one --run names: the
intent and spec, each lane with its spec step and next stage, what an awaiting lane
waits on, the pending spec steps, the fallbacks from a routed runner to the host counted
per runner and per role, and the run record. Before it renders, it renews the
reservation of each run it shows that is due, as implement step does (half
through its lease, or lapsed and still this copy's), fetching the reservations
from origin and pushing the renewal there, and logs the renewal, its failure,
or a reservation another person or copy now holds (reservation_lost), in the
run record. It renews no issue run whose lane is parked at land, which the
drain renews, nor one whose lane was handed back, whose hand-back released
its reservation; it writes nothing else and creates nothing.
Exit 2 when --run names no run.

**Flags:**

```
      --run string   the run to render (run-<16 digits>); every run in this checkout when omitted
```

#### `abcd implement step`

Perform the next stage of an implement loop run's lane and exit: Writes the run's state and the lane's stages; refuses a push with no preflight receipt.

**Usage:** `abcd implement step [--run <run-id>] [--release <lane-id> | --discard <lane-id> | --restart <lane-id> [--yielded <line>]] [--accept-config-change] [--route <role>=runner:<name>[@<provider>/<model>]]... [flags]`

Perform the run's next move, write the state, and exit. At a stage that hands work to
an agent, the result names the agent to start, the brief it is handed and the path its
receipt goes to; that work advances only on `abcd implement receipt`. A lane lands one
step of the spec; its stages are how it gets there. A complete run says so.

A run works in parallel up to its ceiling (--sub-agents, pace.sub_agents): each agent
handed work and not yet verified is a slot, implementers and validators alike. Each call
first performs a stage the binary owns on any lane (the worktree, the brief, a round's
close, the landing's steps), which takes no slot and is never held by the ceiling; then,
while a slot is free, it hands out the first waiting work: a lane already open before a
new one, the lower spec step first, a round's validators in order, then a new lane's
implementer. A call that finds the ceiling reached hands out nothing, exits 0 naming
every lane alive with the role and receipt it awaits, and records the held work with the
time it was first held. A lane opens for a spec step once every step it needs has
landed (its `- needs:` line, or by default every earlier step), and only when a helper is
free to take it: a slot is left for its implementer, and fewer step worktrees than the
ceiling are on disk; its worktree is made just before its implementer takes the slot, and
a step waiting for a helper has none. A landing waiting on the forge's merge, or on the
preflight receipt its push needs (shown as waiting for its full check, since the time
the wait began), holds only its own lane: the call moves another and names the wait
under blocked:; any other refused stage is the call's answer. Landing is one lane at a
time; a lane whose sibling landed
since its base is synced first (the default branch merged in with a merge commit, never a
rebase) and judged by a fresh round, and a conflicting sync goes to a fresh implementer;
a sync counts no fix round. The sync's merge is made as your own `git merge` makes one, in
the lane's worktree: the repository's hooks run, its merge commit is signed where your git
configuration signs every commit, the signature of the commit it merges in is verified where
merge.verifySignatures says so, the merge driver the repository configures or merge.default
names merges each path it covers, and each file it writes passes through the repository's
smudge filter, as Git LFS needs. A merge the repository refuses before it begins refuses
the step, naming what git reported. A merge still waiting after ten minutes on a signing
prompt or a hook (a passphrase dialog nobody answers) is stopped and refuses the step,
so an unattended run is never held by it; the merged result git had staged is reset away,
leaving the lane's worktree clean at its judged head, and the refusal says so. A sync
starts only from a clean worktree, so that reset never touches a change the loop did not
make.

The lane's stages, in order: worktree makes the lane's worktree in the machine-scoped
store, ~/.abcd.noindex/worktrees/<root-sha>/<run-id>-<lane-id>, on a branch build/<run-id>-<lane-id>
cut from the default branch, as your own `git worktree add` makes one (the repository's
post-checkout hook runs, as Git LFS needs); its checkout's time scales with the tree, so it
is bounded at sixty minutes rather than the ten of a commit or a merge, and one stopped
there refuses the stage naming the checkout and the bound; brief renders the lane's brief from that base (the intent,
the spec, the conventions of AGENTS.md, the decisions the intent cites, and the spec
steps before the lane's with what landed each) into the lane's directory of the run;
implement hands the lane to a fresh implementer and awaits
its receipt; validate hands the lane's head to validators that did not implement it, each
a fresh agent, side by side up to the ceiling — a ruthless-reviewer, a security-reviewer
and, on the lane whose landing closes the spec and ships the intent, an intent-auditor over
the whole delivery, each of the run's lanes' own diff (a lane that does not close the
spec takes no audit) — and records each verdict itself, parsed from the validator's own
return. A round one of them did not pass goes to a fresh implementer, who applies each
finding or rejects it in writing in its report, and the next round judges the new head
afresh; a round that passes completes the stage, unless a lane report states a verdict,
which is refused naming the report. The audit passes only when every criterion is met: a
criterion it could not decide (INCONCLUSIVE) fails the round as a not-met one does, and
goes to the fresh implementer with the finding. Each role a round hands out is asked for
the model tier its routing row names, which the result names as tier and the brief's
routing section carries, and a round that does not pass asks each role of the next one
tier up (local, economy, frontier; frontier and host-decides stay), recorded under the
round's routes with the failing gate output; a role on a runner, a review the reviewer
route takes, one pointed at a provider, a host-decides row and the implementer name no
tier and do not move. A round
that does not pass once the lane
has taken the run's fix rounds (--fix-rounds, bundled 3) hands the lane back instead: it
stops as unachievable, the result and the run record name the last round's findings, and
the run starts nothing further for it. Its sibling lanes finish: no new lane opens, no
lane closes the spec, and a sibling whose round passes is held before its push, or before
arming once its pull request is open (an armed one is disarmed, and where the forge
refuses the withdrawal the step is refused naming the pull request; one the forge reports
merged is recorded as landed); once nothing is left to move, a step is refused naming
the hand-back and each held lane. --release <lane-id> lands a held lane as it is;
--discard <lane-id> removes its worktree and branch, then closes its pull request, and
leaves its step unlanded. Either is refused, changing nothing,
for a lane that is not held or while any lane still has work. --discard also takes
an issue run's lane a drain handed back as stuck or closed, and ends that run.
--restart <lane-id> restarts a lane whose implementer died, or yielded on a network
failure (--yielded passes its `NETWORK: <cmd>` line), as a fresh agent from the lane's
last commit: everything left uncommitted is saved aside under the lane's directory
(aside/<UTC stamp>/: changes.patch, aside.json, any partial receipt) once the patch is
proved to apply to that commit, the lane's worktree is reset and cleaned as your own git
resets and cleans it (the repository's hooks run on the reset), the run record
names the aside for review, and the implementer await is re-told; the brief never names
the aside. When a route is in force for the re-told role (roles.<role>.runner, or a
--route given with --restart), the fresh agent is started on that runner at once instead,
and one it fails to start pauses the lane as a step's does; a --route for a role the
restart does not re-tell is refused before anything is changed. An await a rate limit
kept, because what its agent left could not be saved
aside, is marked in the run state, and --restart re-tells it the same way once that is
settled, a validator's included: only a validator's partial return is saved aside, its
worktree is not touched, and a validator of the round that is still out unmarked is left
alone. It is refused, changing nothing, while the run has an outage (open or given up),
for a blank --yielded, for a lane with neither an implementer out nor an await a rate
limit kept, or for a worktree that is not the one the loop derives.
land follows a passing round, one step per call: it checks the lane's worktree is clean
at the judged head; on an intent lane it marks the lane's step landed on the open spec with a `- landed:`
line naming the judged head (unless the spec lists no steps or already marks it); on
the lane that closes the spec it runs `spec close` in the lane's
worktree and ingests the audit that lane took, and for every capture the lane's receipts
declared fixed it runs `capture resolve` with the lane's commit, committing them on the
lane's branch with Delivers: and Resolves: trailers and an Assisted-by: naming the model
the lane's receipts reported (refused when one reported none), the repository's hooks
running and the commit signed as your git configuration says; it pushes the branch only once the
repository's preflight receipt names its head (the pre-push hook runs; nothing is
skipped or forced); it opens the pull request through gh, with a body built from the
records and passed through the outbound scrub, then re-reads the body the forge holds and
strips a session URL or tool footer; it arms auto-merge with the merge-queue method the
ruleset mirror (.abcd/work/rulesets/) names at the lane's base, or leaves the pull request
open while the merge gate does not arm it (with no merge queue it arms with a merge
commit), and pushes nothing while it is armed; and
once the pushed head is an ancestor of the default branch on origin it removes the lane's
worktree and branch and the lane is done. Until then the call exits 3 and waits. A pull
request the forge reports CONFLICTING (gh pr view <n> --json mergeable,mergeStateStatus)
is refused at exit 2 instead, before arming or at the merged check, naming the files a
local merge with every merge driver off conflicts in and the hand merge that settles it;
an issue lane whose conflict lies in declared generated files alone, or in no file when
this checkout merges, enters its sync again instead, an armed merge withdrawn first,
and one whose head already holds the default branch keeps the exit-3 wait.

A stage whose body this abcd does not carry is refused naming the spec piece that
delivers it, and the run is unchanged. A stage that fails leaves the state as it was,
so the next invocation performs it again; a completed stage is never repeated.

A role routed to a command-line runner (roles.<role>.runner in ~/.abcd.noindex/config.json:
claude or opencode, enabled under runner.<name> there) is started by the step itself when the stage
hands the lane out: the runner gets the brief and the receipt path the host would get,
runs in the lane's worktree (claude with the role's tools granted and nothing else asked,
opencode under its own permission configuration), its
transcript is stored in abcd's history store, and its receipt is verified by the stage's
own verifier, so a verified one completes the stage in the same call and the result and
the run record name the route that ran it. The claude runner runs in print mode with
--bare, so the repository's hooks, plugins and configured servers do not run; opencode
runs in run mode with --pure and with its project configuration, its CLAUDE.md reading and
its external skills switched off, so the repository's instruction files, settings, agents,
skills and plugins do not reach it. A route the repository's .abcd/config.json sets to a
runner is skipped with a warning on stderr, and the role is the host's as if unrouted;
one it sets to host keeps the role on the host over the machine's runner route, with a
warning naming both routes.
--route <role>=runner:<name>[@<provider>/<model>] routes one role this step hands out
(implementer, ruthless-reviewer, security-reviewer or intent-auditor) to a runner for this
step alone, over every configured route, asking for the model named after @ in place of
the runner's own runner.<name>.model, which every other role keeps; one per role. The
runner must be one the machine enables and the model one its provider lists, or the step
is refused before anything is written, naming the fix; a tier route, and a --route with
--release, --discard or --accept-config-change (which writes its acceptance before the
step is judged), are refused too. The model is held to the pins the machine
sets for it, as the runner's own model is: opencode holds them, and a --route naming
claude, which holds none, for a pinned model is refused before anything is written,
naming runner.opencode.model. A step hands at most one role out, so
a --route for a role it will not hand out (it performs a stage abcd runs itself, hands out
another role, or re-tells an agent already out) is refused before anything is written,
naming the role it hands out or that it hands none. When a lane's landing comes first and
may wait on the forge, whether the role is handed out is known only after the landing
moves: a --route it then did not use is warned of on stderr, named in route_unused, and
recorded in the run record. A setup warning about a role's configured route is not said
for a role the --route replaces. The role's receipt in the run's state, and the run
record, carry the --route verbatim.
A runner that is absent, refuses, fails, runs past its time,
or writes a receipt the verifier refuses pauses the lane: the role is handed to no one,
the host included, the result names it as paused with why (the runner's reason and the
first line it wrote to stderr, redacted), and the call records one fallback naming the
role, the runner asked for, the reason and none as the route that ran it. Each later
step that hands no agent out retries one held role once on its runner, the one waiting
longest: a paused role, or one already with the host (from an earlier fallback, or a
step before its route existed) whose receipt nothing has written; the run record names
each retry. A --route for a held role retries it at once on that route, and is the
step's one move; with --restart, and with any route in force, the restarted role starts
on its runner at once. A role a runner is running is claimed in the run's state, so no
second step starts another for it. A paused role whose route has since moved to the
host is handed to the host by the next step that hands no agent out, its pause cleared
and the person's route, not a fallback, named in the run record. A role left unset is
the host's, and the call is
exactly the host-driven step. An interrupt kills the runner's process group.

With oracle.review set to rp (in .abcd/config.json or ~/.abcd.noindex/config.json, the
MCP oracle's address, oracle.rp.url, in the latter alone), a ruthless or security review
the step hands to the host is sent instead to that MCP oracle, with a request rendered
beside the reviewer's brief (its agent definition, the lane's brief, the reports and the
diff): the answer is written to the review's return path and its verdict recorded through
the same receipt, and the result's route names rp; a return the host's agent wrote first
stands, and the answer is kept aside beside it. A review the route does not return (no
server named on this machine, a refused connection, a bound run out, the server's error,
a return with no verdict or too large, a request too large to compose, or an interrupt)
falls back: the host is handed the same brief and return path, and the call records one
fallback naming the role, rp, the reason and the host, which status and record count. The
intent-auditor, and a reviewer routed to a runner, are unchanged; with oracle.review unset
or host nothing changes, and abcd never starts, installs or configures the oracle.

The run's window clock: once the run's working window has elapsed, the call starts
nothing, writes next_eligible_at (now plus the run's pause) and exits 0 naming it; an
agent already started may still hand back its receipt. Before next_eligible_at the call
is refused as a pause and nothing changes; at or after it, a new window opens.

A runner that answers with a rate-limit response is not fallen back on, since every
lane spends the same budget: the run's window ends early, next_eligible_at is written
(now plus the run's pause; a pause already running is kept), and the call exits 0
naming the response and the lane it came from. That lane is checkpointed to its branch:
its agent's uncommitted work and partial receipt are saved aside for review, never built
on, its worktree is reset to its last commit, and the first call after the pause hands
the same work to a fresh agent. Every other lane with work in flight is checkpointed at
its branch's head and left running; its agents may hand back their receipts inside the
pause. The run record names each checkpoint.

The run's lost connection (`abcd implement outage`) is read before every move. While
the network is down, a lane whose move reaches the remote or the forge (a landing's
push, pull request, arming or merged check; a hold's disarm) waits on the shared probe,
named under blocked: with the next probe's time, and the other lanes move; while the
model service is down no agent is handed work, and while the network is down no runner
is started. A git or gh failure that reads as the network becomes the same wait and is
recorded for the session whose claim names the run. A call that finds the network
probe due runs it; the model side waits for the lead's canary. Once the run has given
up on the outage, every call is refused at the stage outage, naming since when, the
probes, what was done, what is left and whether the product thinker's notification is
pending (notify).

The run tripwire: the repository's git settings that can name a program (filter.*,
core.hooksPath, core.sshCommand, core.fsmonitor, core.pager, core.editor, core.askPass,
core.gitProxy, core.worktree, extensions.worktreeConfig, credential.*, a remote's url,
pushurl, proxy, vcs, uploadpack and receivepack, url rewrites, protocol allow rules, diff
and merge drivers, gpg programs and gpg.ssh.defaultKeyCommand, include and includeIf
paths), every such setting each lane worktree reads and the hooks directory git runs
there, the hooks directory and info/attributes are fingerprinted at the run's first
check, and checked again at the start of every step, discard and restart, before the
shared network probe and before a rate-limit checkpoint saves a lane aside. They run on
the loop's git as on your own, so abcd never changes them; a change during the run is
refused at the stage config, before the call reaches its git, naming each changed key or
file (never a value; a key whose name can hold a URL is named url.<hidden-id>.insteadof),
and a checkpoint keeps the lane as it is. The check is made when the call starts, not
together with git: a change made while the call runs is seen by the next one. A run
started before the tripwire records its fingerprint at its next check and moves.
--accept-config-change, once you have looked at what changed, records the configuration
as it stands, names what it accepted on stderr, in the result (accepted_config_change) and
in the run record, and takes the step.

--run names the run; without it, the one run in progress in this checkout. Exit 2 on a
refusal, exit 3 on a pause or a locked run state.

**Flags:**

```
      --accept-config-change   accept, once you have looked, a change to the repository's git settings that the run tripwire stopped, then take the step
      --discard string         discard a held lane (lane-<n>), or one a drain handed back as stuck or closed: remove its worktree and branch, then close its pull request
      --release string         land a held lane as it is (lane-<n>), once no lane has work left
      --restart string         restart a lane whose implementer died (lane-<n>) as a fresh agent from its last commit, its uncommitted work saved aside
      --route stringArray      route one role this step hands to an agent to a runner, for this invocation alone: <role>=runner:<name>[@<provider>/<model>], the runner one this machine enables and the model one its provider lists (else the runner's own model); one per role (implementer, ruthless-reviewer, security-reviewer, intent-auditor); wins over every configured route for this step alone, and the role's receipt records it verbatim
      --run string             the run to step (run-<16 digits>); the one run in progress when omitted
      --yielded string         with --restart: the line the agent yielded with, NETWORK: <cmd>, when a network failure stopped it rather than it dying
```

#### `abcd implement widen`

Widen an issue lane's hold to a path before it is edited: Writes the reservation and a run record line; refuses another copy's live hold, with exit 3.

**Usage:** `abcd implement widen <path>... --lane <lane-id> [--run <run-id>] [flags]`

Widen an issue run's reservation to each path named before the lane's implementer
edits it: the issue is reserved again on origin with the footprint its reservation holds
and the paths it does not cover yet, judged for overlap and against the cap like any
reservation. A path already covered adds nothing, and when every one is, nothing is
pushed. The run record says what was widened. Only the run's current lane, at its
implement or validate stage, widens; an intent's run holds its spec's footprint and is
refused. A run holding no reservation has nothing to widen and says so.

An implementer's receipt is refused while the lane's branch changes a path the
reservation does not cover, naming this command, so a widening forgotten or an edit made
through the shell is caught before the lane moves on.

Run it from the checkout the run lives in; the lane's brief names the command in full.
--run names the run; without it, the one run in progress in this checkout. Exit 2 on a
refusal; exit 3 when another copy holds a live reservation on one of the paths, with
nothing pushed (edit none of them, and stop without a receipt: the lane is handed to an
implementer again on a later step), or on a locked run state.

**Flags:**

```
      --lane string   the lane whose implementer is about to edit the paths (lane-<n>)
      --run string    the run the lane belongs to (run-<16 digits>); the one run in progress when omitted
```

**Example:**

```
abcd implement widen internal/widget/b.go --lane lane-1 --run run-2609010000000001
```

### `abcd inbox`

List the reports managed repositories filed back to abcd, newest first: Writes nothing; refuses any argument.

**Usage:** `abcd inbox`

Read the reports repositories abcd manages filed with `abcd report`, from the
inbox in the user account's machine store (`~/.abcd.noindex/inbox/`).

Bare `abcd inbox` lists the waiting reports newest first, naming each sender
repository plainly; `abcd inbox show <id>` renders one whole. Both are
read-only and file nothing. A report written to a template version this abcd
does not know is listed as unreadable, naming the version, and is never
dropped. Everything a report says is another repository's words and is
sanitised before it reaches the terminal.

`abcd inbox promote <id>` is the one act that files anything: it files the
report as a capture in the ledger of abcd's own checkout, through the capture
verb's own path and redactor, with source `managed-repo`. Every report is about
abcd, so run anywhere else it is refused. The capture carries the sender's
root-commit key and the words "a managed repository", never the sender's
name, and the report's id as its evidence; a record id the report names is the
sender's, and is written as one word so it cites nothing in abcd's record. The
report is kept, marked promoted.

Exit 2 on a refusal, with nothing written.

#### `abcd inbox promote`

File one report as a capture in abcd's own ledger: Writes the capture and marks the report promoted; refuses outside abcd's own checkout.

**Usage:** `abcd inbox promote <id>`

**Example:**

```
abcd inbox promote rpt-2609010000000001
```

#### `abcd inbox show`

Render one report whole: Writes nothing; refuses an id the inbox does not hold.

**Usage:** `abcd inbox show <id>`

**Example:**

```
abcd inbox show rpt-2609010000000001
```

### `abcd intent`

File a draft intent from quoted text, or render the intent store's status bare: Writes the draft into drafts/; refuses a lone word.

**Usage:** `abcd intent [text] [flags]`

**Flags:**

```
      --impact string            stamp the draft's product impact: additive|breaking|fix (optional)
      --production-mode string   how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: the repo's declared mode, else hand-written)
      --title string             the draft's H1 title (default: the first sentence of the text, cut on a word boundary at 60 characters)
```

#### `abcd intent audit`

List or drain owed fidelity reviews, emit an intent's request, or check issue drift: Writes an OWED stub only for --owed or an id; refuses an unshipped intent.

**Usage:** `abcd intent audit [<itd-N>] | audit --owed [--max <n>] | audit --issue-drift [--strict] [flags]`

**Flags:**

```
      --issue-drift         walk the intent store and the issue ledger for promote joins that do not read the same from both ends (related_issues ↔ related_intents); warns on stderr, exits 0
      --max int             with --owed: list at most n owed reviews (0: no cap); the summary names how many remain
      --owed                drain the owed fidelity reviews: list them oldest shipped first and emit the oldest's request; writes (parks an OWED stub in a markerless intent, a committed record, and rewrites its request); runs no reviewer
      --route stringArray   route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
      --strict              with --issue-drift: exit 1 when any finding is reported (the CI mode)
```

**Example:**

```
abcd intent audit itd-2609010000000001
```

##### `abcd intent audit ingest`

Ingest an intent-audit verdict into the shipped intent: Writes its Audit Notes; refuses without --verdict-json.

**Usage:** `abcd intent audit ingest --verdict-json <path> [--dry-run] [flags]`

**Flags:**

```
      --dry-run               check the input and report what would be written; write nothing
      --route stringArray     route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
      --verdict-json string   path to the intent-audit verdict JSON, in the shape the Verdict shape section of its review request states
```

**Example:**

```
abcd intent audit ingest --verdict-json verdict.json
```

#### `abcd intent condition`

Read or disposition a shipped intent's scope conditions: Writes a dated condition block; refuses an unresolved occasion or thin grounds.

**Usage:** `abcd intent condition <itd-N> [<cond-id> --disposition <survived|narrowed|falsified|untested> --occasioned-by <rdi-N|itd-N> --grounds "<why>" [--narrowing "<what now holds>"]] [flags]`

**Flags:**

```
      --disposition string     the condition's disposition: survived|narrowed|falsified|untested
      --grounds string         why: held to the grounds substance floor, redacted before it is written
      --narrowing string       what now holds: required on narrowed and refused on every other value
      --occasioned-by string   what occasioned it: a reading item (rdi-N) or a shipped intent (itd-N)
```

**Example:**

```
abcd intent condition itd-2609010000000001
```

#### `abcd intent consistency`

Emit the consistency request over the brief and every intent, or one intent against them: Writes the request locally; refuses a superseded intent.

**Usage:** `abcd intent consistency [<itd-N>] [flags]`

**Flags:**

```
      --max-chunks int      on a provider route, the most chunks of an overflowing corpus sent in one run; a plan of more is refused, naming its count and bytes (default 8)
      --route stringArray   route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

##### `abcd intent consistency ingest`

Ingest consistency findings as a dated review and a capture per finding: Writes the report and the ledger records; refuses without --findings-json.

**Usage:** `abcd intent consistency ingest --findings-json <path> [--findings-json <path>...] [--dry-run] [flags]`

**Flags:**

```
      --dry-run                     check the input and report what would be written; write nothing
      --findings-json stringArray   path to the consistency findings JSON the intent-auditor returned; give it once per chunk of an overflowing corpus
      --route stringArray           route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd intent consistency ingest --findings-json findings.json
```

#### `abcd intent edge`

Add or remove an intent's blocked_by and builds_on edges: Writes the two lists in place; refuses an id no intent store holds.

**Usage:** `abcd intent edge <itd-N> [--blocked-by <itd-M,...>] [--unblock <itd-M,...>] [--builds-on <itd-M,...>] [--drop-builds-on <itd-M,...>] [flags]`

**Flags:**

```
      --blocked-by string       append: comma-separated itd-N ids this intent cannot ship before; each must exist in the intent store
      --builds-on string        append: comma-separated itd-N ids this intent builds on; each must exist in the intent store
      --drop-builds-on string   remove: comma-separated itd-N ids to drop from builds_on; each must currently be in the list
      --unblock string          remove: comma-separated itd-N ids to drop from blocked_by; each must currently be in the list
```

**Example:**

```
abcd intent edge itd-2609010000000001 --blocked-by itd-2609010000000002
```

#### `abcd intent hold`

Hold a draft or planned intent so that planning refuses it: Writes the held line with its reason; refuses without --reason.

**Usage:** `abcd intent hold <itd-N> --reason "<text>" [flags]`

**Flags:**

```
      --reason string   why the record is held: one line, required; redacted before it is written
```

**Example:**

```
abcd intent hold itd-2609010000000001 --reason "waiting on the product thinker's ruling on scope"
```

#### `abcd intent interview`

Run an intent's planning interview in a plain Terminal on your own route: Writes the answers record and the role's edits; refuses with no route of yours.

**Usage:** `abcd intent interview <itd-N> [--answers <file>] [--answered-in <place>] [flags]`

Run the planning interview in a plain Terminal, with no host session: the planning-interviewer,
on the runner the person routed it to in their own machine's config, writes each question and edits
the intent record with the tools its contract grants; abcd draws each question, takes the answer,
and reports the readiness gate when the interview ends. With no route of the person's to a runner it
refuses before anything runs, writing nothing. Off a terminal the questions are answered from
--answers, by ordinal (Q1, Q2, ...). The plan act stays the product thinker's: `abcd intent plan`.

**Flags:**

```
      --answered-in string   where an answers-file entry that names no place was answered: Terminal, or the host whose question tool asked it, as its plugin page passes; recorded with each answer (default "Terminal")
      --answers string       answer the questions from this answers file (JSON: schema_version, interview "planning", answers by ordinal Q1, Q2, ...) instead of drawing them; the run refuses at the first question the file does not answer
```

**Example:**

```
abcd intent interview itd-2609010000000001
```

#### `abcd intent link`

Link a planned intent to an existing spec: Writes the intent's spec_id; refuses an intent that is not planned.

**Usage:** `abcd intent link <itd-N> <spc-N>`

**Example:**

```
abcd intent link itd-2609010000000001 spc-2609010000000002
```

#### `abcd intent plan`

Plan a draft, or several as a named bundle, or stamp a planned one's conditions: Writes the intents and their spec; refuses a held intent or a bundle's blocker.

**Usage:** `abcd intent plan <itd-N> [<itd-N>…] [--bundle <name>] [--target <vX.Y.Z|next>] [flags]`

**Flags:**

```
      --bundle string            the name of the bundle several intents are planned as: kebab-case, required with two or more intents and refused with one
      --impact string            stamp the intent's product impact: additive|breaking|fix (optional; refused when it disagrees with one already recorded)
      --production-mode string   how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: the repo's declared mode, else hand-written)
      --target string            the release the planned intent must land by: vX.Y.Z or next, written as target_release (optional; one intent only)
```

**Example:**

```
abcd intent plan itd-2609010000000001
```

#### `abcd intent prepass`

Print a draft's pre-pass input, or write its planning brief from the host's findings: Writes only the brief; refuses a record not on drafts/.

**Usage:** `abcd intent prepass <itd-N> [--findings-json <path> [--dry-run]] [flags]`

**Flags:**

```
      --dry-run                check the input and report what would be written; write nothing
      --findings-json string   path to the host's findings over the input; validates them and writes the planning brief
```

**Example:**

```
abcd intent prepass itd-2609010000000001 --json
```

#### `abcd intent ready`

Report whether an intent is ready to implement, exiting 1 when not: Writes its grounds only with --grounds; refuses malformed grounds.

**Usage:** `abcd intent ready <itd-N> [--grounds "<pursued|deferred|declined>: <conjecture>"] [flags]`

**Flags:**

```
      --grounds string   record the conjecture behind this gate decision: "<pursued|deferred|declined>: <what is expected, and what would show it wrong>"
```

**Example:**

```
abcd intent ready itd-2609010000000001
```

#### `abcd intent reclassify`

Change an intent's kind, or retire it as superseded by a named successor: Writes the record and its successor together; refuses a shipped intent's kind change.

**Usage:** `abcd intent reclassify <itd-N> --kind <standalone|bundle-member --bundle <name>|superseded --by <itd-M|adr-N> --reason "<why>"> [flags]`

**Flags:**

```
      --bundle string   with --kind bundle-member: the bundle to join, one another record already names
      --by string       with --kind superseded: the successor, an intent (itd-M) or an ADR (adr-N)
      --kind string     the new kind: standalone, bundle-member, or superseded (a discipline is filed, never reclassified into)
      --reason string   why, one line, redacted before it is written; required with --kind superseded
```

**Example:**

```
abcd intent reclassify itd-2609010000000001 --kind superseded --by itd-2609010000000002 --reason "absorbed by the later intent"
```

#### `abcd intent target`

Name the release a planned intent must land by: Writes its target_release line; refuses a draft, a shipped intent, or a value not vX.Y.Z or next.

**Usage:** `abcd intent target <itd-N> <vX.Y.Z|next>`

**Example:**

```
abcd intent target itd-2609010000000001 v0.11.0
```

#### `abcd intent unhold`

Lift an intent's hold: Writes the removal of its held line; refuses a record not held.

**Usage:** `abcd intent unhold <itd-N>`

**Example:**

```
abcd intent unhold itd-2609010000000001
```

### `abcd lab`

List this repository's labs with their pins, probe counts and halts: Writes nothing; refuses outside a git checkout.

**Usage:** `abcd lab`

A lab is a throwaway world pinned at one commit of this repository, run to
answer one question. Its evidence lives at the operator level, in
~/.abcd.noindex/lab/<root-sha>/<lab-id>/ (the same root-commit key the transcript
store uses), and its knowledge enters the record only through capture:
nothing any lab verb does writes into the repository.

Bare `abcd lab` lists this repository's labs, read-only: each lab's pin,
probe count, and whether a gate holds it halted.

A gate refusal halts the lab and is recorded as a finding in its findings
log rather than adapted around: the preflight and the retraction sweep exit 1
on a refusal, write their artefact, and hold the lab halted — no probe is
recorded — until the same gate passes again. The finding stays.

Exit 2 on a refusal of the request itself (no checkout, an unknown lab, a bad
name or question); nothing is written on any of them.

#### `abcd lab harvest`

Assemble a lab's harvest with its capture candidates: Writes harvest/harvest.md; refuses a finding its probe records cannot back, or a hand-written harvest.

**Usage:** `abcd lab harvest <lab-id>`

Assemble harvest/harvest.md from INTENTION.md, the findings log and the probe
records, in the lifeboat's section shape: intention, method, findings that
worked, findings still open, candidates, coverage. Each finding cites its probe
records by path; each product finding is listed as a capture candidate with
the capture line that files it, found during the lab, and flagged where no
refutation was attempted. Nothing is filed.

No claim outlives its input: a finding citing no probe record or evidence
file, or one missing or incomplete, is listed and the harvest refuses (exit 1,
nothing written). A hand-written harvest.md is never overwritten. A halted lab
is still harvested, its gate findings first.

**Example:**

```
abcd lab harvest lab-260901000000-0123abc
```

#### `abcd lab matrix`

Show a model matrix run's plan, or record the run its digest consents to: Writes the run record only with --approve; refuses a metered run with no cap.

**Usage:** `abcd lab matrix <lab-id> <declaration.json> [flags]`

abcd lab matrix <lab-id> <declaration.json> [--approve <digest>]

Show the plan for a model matrix run of the declaration in the lab: how many
copies each cell makes, the expected cost by source against the spending cap,
the load cap below this machine's cores, the time, and the judges each task
needs. Building it reads the declaration and this machine's configuration and
nothing else: no network call, no price fetched, nothing written. Its digest
names exactly that plan.

--approve <digest> records the run, once the person has seen the plan and said
yes to it: the plan is built again and must carry that digest. A host passes
--approve only after the person, in that session, has seen the plan and said
yes to it. Starting the run's copies is not built yet, so a consented run is
recorded in the lab and nothing is launched; the output says so.

Refused, exit 2, with nothing written: a declaration that does not parse, a
cell route the runner rung or this machine's runner configuration refuses, a
cell on a runner that names no model, a model its provider does not list, an
OpenRouter or local cell with no pin, a metered cell with no spending cap, a
local cell with no load cap or one at or above the cores, and an approval that
is not the plan's digest. A halted lab exits 1.

**Flags:**

```
      --approve string   the digest of the plan the person saw and said yes to; records the run
```

**Example:**

```
abcd lab matrix lab-260901000000-0123abc matrix.json
```

#### `abcd lab mint`

Mint a lab for one question, with a standalone snapshot at the pin: Writes only under the lab store; refuses a multi-line question or a pin naming no commit.

**Usage:** `abcd lab mint <question> [flags]`

Mint a lab for one question. The lab home is created under this repository's
lane of the lab store with a registry line; the snapshot is a standalone
clone of this repository detached at the pin (HEAD unless --pin names
another commit), made with no hook firing and with its remote cut, so
nothing done in the lab world reaches this checkout. INTENTION.md,
findings.md, corrections.md and amendments.md are scaffolded, with the
lifecycle mapped onto the home. Nothing is written into the repository.

**Flags:**

```
      --pin string   the commit the snapshot is pinned at (default HEAD)
```

**Example:**

```
abcd lab mint "does the snapshot keep the checkout's hooks from firing?"
```

#### `abcd lab preflight`

Run a lab's harness-isolation and dual-binary checks: Writes the preflight artefact, and a finding and halt on a failure; refuses an unknown lab.

**Usage:** `abcd lab preflight <lab-id>`

Run the preflight against a lab's home and write it to state/preflight.md.

Harness isolation: the lab's own HOME holds no link out of the lab; the
snapshot is a standalone clone (not a linked worktree, borrowing no object
store) descending from the pin; it has no remote; and the hooks path a
session in it would run, with the operator's global configuration in force,
resolves inside the lab.

Dual binary: bin/abcd is a regular file (never a link to an operator-level
installation) whose embedded vintage — read without running it — is the
pin, unmodified; it is the same binary the first passing preflight pinned,
since the work binary is never rebuilt; and bin/abcd-test, when present, is a
separate file. The group holds a lab of abcd's own repository: its root
commit is abcd's, or the pin carries cmd/abcd/main.go. For any other
repository no bin/abcd can be built from the snapshot, so each binary check
passes marked not applicable (n/a, and not_applicable in --json), saying why.

A failed check halts the lab naming it: exit 1, the refusal recorded as a
gate finding. A preflight that passes lifts that halt.

**Example:**

```
abcd lab preflight lab-260901000000-0123abc
```

#### `abcd lab record`

Scaffold one probe record naming the artefact it observes: Writes the probe's files under state/probes/; refuses a halted lab or a probe already recorded.

**Usage:** `abcd lab record <lab-id> <probe>`

Scaffold the record one probe writes before any harvest may cite it:
input, argv, exit, stdout and stderr, empty, and record.md naming the
artefact observed (the work binary's vintage and sha256, when there is one).
The verb runs nothing: the probe's command is run by whoever runs the lab, with
its output redirected into the scaffold. A probe is recorded once and never
overwritten; a re-run is a new probe. Refused on a halted lab.

**Example:**

```
abcd lab record lab-260901000000-0123abc bare-status
```

#### `abcd lab sweep`

Sweep a lab's documents for every retracted pattern: Writes the sweep artefact, and a finding and halt on an unapplied correction; refuses an unknown lab.

**Usage:** `abcd lab sweep <lab-id>`

A retraction is a sweep, not an edit. Every correction line in corrections.md
names a literal that must be absent from the lab's own documents; the sweep
searches them all for it — the pattern, not the instance — and lists every
place it still stands. The snapshot, the lab's HOME and binaries, transcripts
and each probe's five capture files are not swept: they are the world and the
instruments, not claims. Nor are the records a procedure writes under
state/matrix/ (a matrix run's declaration, run and trial records), which are
what a run was given and measured; any other file there is swept. A probe's
record.md is prose, and is swept. The
result is written to state/sweep.md. An unapplied correction, one too short
to mean anything, or — while any correction is recorded — a document the
sweep could not read (too large, binary, or not a regular file; each listed
by path) fails the sweep: exit 1, the lab halted and the refusal recorded as
a gate finding that names corrections by number, so it never becomes an
instance itself. A sweep that passes lifts that halt.

**Example:**

```
abcd lab sweep lab-260901000000-0123abc
```

### `abcd land`

Push a branch whose preflight passed and queue its pull request: Writes a push to origin and arms a merge; refuses the default branch or a dirty tree.

**Usage:** `abcd land [<branch>] [flags]`

abcd land [<branch>] [--no-push] [--no-enqueue]
abcd land [<branch>] --record-review <return> --record-review <return> [...]
abcd land [<branch>] --approve

Land a branch whose work is committed: the checkout's current branch, or the one
named, from the worktree that has it checked out. Each step can be resumed by
running abcd land again.

land runs the branch's own `make preflight` with your environment and
credentials, so run it only on a branch whose content you trust.

  1. Origin: every fetch and push URL of origin must be the repository the forge
     client resolves, and the forge's default branch must be the one origin
     itself names (git ls-remote --symref origin HEAD) and not the branch;
     checked before anything runs. A stale or missing local origin/HEAD is
     reported and passed over, never written.
  2. Landed: origin's default branch is fetched; a head already on it has landed,
     and so has one the forge lists a merged pull request of this repository's
     branch at (a squash or rebase merge): land says so and stops, pushing,
     gating and queueing nothing. A forge that cannot be asked gets no push.
  3. Gate: when a preflight receipt already names the branch's head (in any
     worktree, as the pre-push hook looks), the gate is skipped; otherwise
     `make preflight` runs in the branch's checkout, its output on stderr, and the
     head must be unchanged, a receipt present and origin's URLs as checked after
     it. A repository whose make file declares no preflight target gets no push.
  4. Announce (with land.push on): before the push, "merging <item>" is posted on
     your status branch, as abcd announce posts it, for each issue, intent or pull
     request the branch's own commits name in a Refs:, Resolves: or Delivers:
     trailer, and the push waits until each is on origin. One you already
     announced, standing a minute more, is not sent again; a record not yet on
     the default branch is not announced, and the step says so. One that cannot
     be published refuses the landing, nothing pushed. A push typed by hand with
     git push posts no announcement.
  5. Push (land.push): a plain push of the gated commit to the branch's name on
     origin, with the repository's hooks running, never forced, never the default
     branch.
  6. Enqueue (land.enqueue): the branch's open pull request, armed where the merge
     gate allows it, pinned to the head: into the merge queue by its method where
     one gates the default branch (then confirmed in the queue), otherwise as the
     forge's auto-merge (a merge commit; a forge that refuses it is said). An
     arming someone else made is left as it is. With no pull request it composes
     the body from the branch's commits (each subject, their Refs:, Resolves: and
     Delivers: lines, abcd's own Assisted-by label and the models their
     Assisted-by: lines name) into the checkout's .abcd/.work.local/ where it has
     one, judges it as the shell guard judges a posted body, prints the `gh pr
     create` command naming it with --body-file, and stops; it never opens one.

The merge gate reads facilitator.mode from the default branch's committed
.abcd/config.json and ~/.abcd.noindex/config.json (human from either wins;
human by default), never from the branch being landed. A pull request whose
author has Read or Triage permission, or none, is armed only once an approval of
its head counts, in either mode. An approval counts when it is the latest review
by someone with Write, Maintain or Admin permission, approves the head commit
and is not the author's, or when the technical facilitator recorded it with
--approve. Then, and for an author with one of those: human arms only once an
approval of the head counts, and otherwise says it waits for the technical
facilitator's; auto arms only a head a review receipt names (--record-review),
and otherwise names the commit. An author whose permission cannot be read is
unverified, and nothing is armed. human stops an agent merging by mistake, not
one set on getting round it: the recorded approval is a file anything running
under your account can write, so it is a rule your agents keep, not a proof
that you approved.

land.push and land.enqueue are read from .abcd/config.json (in the working
directory's checkout and the branch's own) and ~/.abcd.noindex/config.json,
default true, and off wins from any layer: any file can turn an act off and none
can turn it back on. --no-push and --no-enqueue turn one off for this run. An act
that is off says which layer turned it off; with both off nothing runs. With
land.push off and land.enqueue on the gate still runs: arming says the head is
ready, and readiness is the gate.

Refused on the default branch, a detached HEAD, a tree with uncommitted changes, an
origin that is not the repository the forge client resolves (an SSH host alias
included), and a pull request only another repository opened.

Before the push, the reservations and origin's release tags are fetched, and the
release hold is judged for the checkout land runs in: while another session cuts
a release (a live rel-vX.Y.Z reservation, or an unreadable one within its hold),
nothing is pushed, armed or queued. The copy cutting the release lands through
its own hold. A release reserved with a date more than five minutes ahead of
this clock holds from when this checkout first saw it; one this checkout cannot
keep that sighting for (no .abcd/.work.local/) is not counted, and a notice
line on stderr names it.

Exit 0 when every step did its act or said why it stopped. Exit 2 on a refusal,
which names what was done before it; reservations that cannot be fetched are
one, and so is an announcement that cannot be published, each made before
anything is pushed. Exit 3 when a release being cut holds the
landing: it names the release, its holder and until when.

--record-review records the review pair's verdicts for the branch's head and
lands nothing: given once per reviewer's return (at least two, no two the
same), each naming the head's first nine characters under one ### Verdict
heading, it writes the head's review receipt in
.abcd/.work.local/review-receipts/ when every verdict passes the stop rule
(SHIP or APPROVE: no critical or major finding). A return that does not pass is
refused naming it, exit 2, and nothing is written. It takes no --no-push or
--no-enqueue.

--approve records the technical facilitator's approval of the branch's head and
lands nothing: it writes .abcd/.work.local/approvals/<head>, which the merge
gate counts as an approval of that commit, and of no other. It is the
facilitator's own act, for a pull request they authored (the forge refuses an
author's approval of their own): the shell guard refuses it to an agent.

**Flags:**

```
      --approve                     record the technical facilitator's approval of the branch's head, a person's act the shell guard refuses to an agent; lands nothing
      --no-enqueue                  do not arm or queue the pull request this run
      --no-push                     do not push the branch this run; print the push command instead
      --record-review stringArray   record the review pair's verdicts for the branch's head from this reviewer's return (give it once per return, at least two); lands nothing
```

### `abcd launch`

Preview the release cut, the launch bundle, its secret scan and the gates: Writes only its pre-flight report, to the local tier; refuses without --dry-run.

**Usage:** `abcd launch [flags]`

Preview the release bundle and run the release gates with --dry-run; nothing is
published. The preview also renders the release cut the next `launch ship` would
make: the derived version, the deciding impact, the records, and the guard verdict.
A refused cut is reported, and changes nothing about the preview's exit.

The dirty-tree gate compares the working tree with HEAD byte for byte. The repository's
content filters (filter.<name>.clean, .smudge and .process) are switched off for that
comparison, so no program a filter names runs. A filter the repository marks required
(filter.<name>.required, which `git lfs install --local` sets) makes git refuse the
comparison instead wherever the file timestamps git saved do not match the working
tree (a copied or restored checkout, say): the gate then reports the tree unreadable,
never clean.

The comparison does not look inside a checked-out submodule, so uncommitted content
inside one does not make the tree dirty and no program the submodule's own
configuration names runs; a submodule moved to a different commit still does.

**Flags:**

```
      --baseline string   the release tag the payload parity diff measures against (default: the newest release tag)
      --deep-smoke        also run the installability smoke's deep tier: render every command, skill and agent page's help in an isolated subprocess (always on in the cut)
      --dry-run           preview the launch bundle, its gates and the release cut without publishing
      --fetch-baseline    read the parity baseline from the tag's published plugin archive, verified against the release's checksums.txt (a network fetch; default: a fresh render at the tag)
```

#### `abcd launch archive`

Render the release's plugin archive: Writes the archive into --out; refuses a dirty tree without --verify, and exits 1 when --verify finds it unpinned.

**Usage:** `abcd launch archive --out <dir> [--tag <vX.Y.Z>] [--verify] [--repository <owner/name>] [flags]`

Render the release's plugin archive into --out and, with --verify, prove the
committed catalog pins it (exit 1 on a mismatch).

With --verify the pin judges the working tree: a payload file that differs
from the commit changes the archive's digest, and the pin refuses it. Without
--verify nothing else judges the tree, so an uncommitted change, tracked or
untracked and outside the local tier, refuses the render (exit 2) and nothing
is written to --out.

**Flags:**

```
      --out string          existing directory to write <plugin>-plugin-v<version>.zip into
      --repository string   refuse (exit 1) unless the archive's address is this GitHub owner/name's release download for the tag
      --tag string          refuse unless the newest dated CHANGELOG version is this tag
      --verify              refuse (exit 1) unless the committed catalog pins this archive's address and digest; without it, a tree with an uncommitted change refuses (exit 2)
```

**Example:**

```
abcd launch archive --out dist
```

#### `abcd launch manifests`

Check the release manifests agree on the version, or carry none on a dev tree: Writes nothing; refuses with exit 1 on drift and exit 2 on an unreadable input.

**Usage:** `abcd launch manifests --tree public|dev [--root <dir>] [flags]`

Run the manifest lockstep check over a tree. --tree public requires the
version-location primary present as strict SemVer and every pinned secondary
to agree with it; --tree dev requires every version key absent (adr-19). The
tree is the working directory, or --root. Exit 0 consistent, 1 drift (one
line per field), 2 unreadable. Nothing is written.

**Flags:**

```
      --root string   the tree to check (default: the working directory)
      --tree string   the polarity to check: public (versions present and agreeing) or dev (versions absent)
```

**Example:**

```
abcd launch manifests --tree public
```

#### `abcd launch receipts`

Run the release job's semantic-receipt gate locally, before the merge: Writes nothing; refuses with exit 1 when the release job would refuse the receipts.

**Usage:** `abcd launch receipts`

#### `abcd launch scaffold`

Scaffold the release gate for the declared artefact kind: Writes its workflows and runbook; refuses an undeclared kind, or a hand-edited file without --confirm.

**Usage:** `abcd launch scaffold [--confirm] [--dependency-reauthor] [flags]`

**Flags:**

```
      --confirm               overwrite a hand-edited scaffolded file with the current machinery
      --dependency-reauthor   opt in to re-authoring bot-opened dependency bumps as the repository owner (seeds .abcd/config/dependency-reauthor.conf)
```

#### `abcd launch ship`

Cut a release, deriving its version and records from what shipped: Writes the CHANGELOG heading, RELEASE.md, and the archive pin; refuses a cut its gates stop.

**Usage:** `abcd launch ship [--changelog-json <file|->] [--payload-dir <dir>] [--allow-dirty] [--fetch-baseline] [--dry-run] [flags]`

Cut a release from HEAD, deriving its version and changelog from the records that shipped
since the last tag. A fresh cut runs the pre-flight gates before it writes anything.

The dirty-tree gate, the check for uncommitted records, and the check that the plugin
payload is committed each compare the working tree with HEAD with the repository's
content filters switched off, so no program a filter names runs. Where a filter the
repository marks required (filter.<name>.required, which `git lfs install --local` sets)
meets file timestamps git saved that do not match the working tree, git refuses the
comparison, and the cut is refused rather than read as committed; --allow-dirty does not
waive that refusal.

None of these comparisons looks inside a checked-out submodule, so uncommitted content
inside one does not make the tree dirty and no program the submodule's own
configuration names runs; a submodule moved to a different commit still does.

With --changelog-json, --dry-run is a practice run: the composed changelog is judged against
the cut exactly as the real ingest judges it, the pre-flight gates run when the ship renders a
payload, and the report names every file the cut would write and the tag, push and release
the release workflow makes after it. Nothing is written: no pre-flight report, no release
record, no archive pin and no staged payload. It reads the parity baseline already in the
checkout, so --fetch-baseline is refused beside it.

**Flags:**

```
      --allow-dirty             cut from a working tree with uncommitted changes; the pre-flight report records the override and every path it carried (waives the dirty-tree gate only — never lockstep, the archive pin's clean-payload refusal, the cut's uncommitted-records refusal, or the findings gate's refusal of an uncommitted open/ issue record)
      --changelog-json string   path to the host-composed changelog JSON (or - for stdin); absent runs the deterministic emit step
      --dry-run                 check the input and report what would be written; write nothing
      --fetch-baseline          read the parity baseline from the anchor tag's published plugin archive, verified against the release's checksums.txt (a network fetch; default: a fresh render at the tag)
      --payload-dir string      stage the versioned release payload in this directory (must be empty and outside the repository)
      --route stringArray       route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

### `abcd library`

Render the sources corpus and the checkout's memory store, read-only: Writes nothing; refuses only when neither store can be read.

**Usage:** `abcd library`

Two stores under one verb, never connected to each other.

The personal sources corpus: documents you may consult, a CSL-JSON bibliography, and one
append-only influence ledger per repository, in a local-only git repository with no
remote (~/.abcd.noindex/sources by default; --corpus names another). The folder a source sits
in — confidential/<key>/ or public/<key>/ — is its classification. Its verbs are init,
add, declassify, ledger, sync-banlist and cite-check.

Consult freely, cite deliberately: confidential entries are projected into this
repository's untracked private banlist (sync-banlist), which the committed pre-commit
guard refreshes and enforces; cite-check clears text before it leaves the machine; and
a ledger line becomes a public citation only when the source permits it AND a person
flips the line (adr-41). No output names a confidential source except by key. Every
corpus verb but init exits 3 when there is no corpus.

The checkout's memory store (.abcd/memory/): cited pages distilled from a source with
ingest, queried with ask, and health-checked with lint. Its verbs refuse outside a
checkout.

Bare `abcd library` is read-only and renders both: a store that cannot be read is one
line naming what would create it, and the verb refuses only when neither can be read.

**Flags:**

```
      --corpus string   the sources corpus directory (absolute; default ~/.abcd.noindex/sources)
```

#### `abcd library add`

Register a source in its class folder, with its entry and text: Writes the corpus and commits it, asking its class at a terminal; refuses off one with no class.

**Usage:** `abcd library add [document] [flags]`

Register a source: write its CSL-JSON entry (with the custom block), store the document
as original.<ext> and its extracted text as text.md under confidential/<key>/ or
public/<key>/, and commit the corpus. The class is declared here, once, and never
guessed: --private (filed under confidential/) or --public. Given neither, abcd asks
at a terminal and refuses off one, writing nothing. abcd converts nothing and fetches nothing:
a Markdown or text document is its own text, any other needs --text, and a URL
alone registers a metadata stub.

A confidential entry's title, aliases and (under --ban-authors) authors become banned
phrases, so each must hold at least three letters or digits, and its key must not
contain any of them — the key is what every refusal and scan prints. Pass those
strings with --meta FILE (or --meta - on stdin) to keep them out of argv and shell
history.

**Flags:**

```
      --alias stringArray      another identifying name for a confidential source (repeatable)
      --author stringArray     an author, "Family, Given" or a literal name (repeatable)
      --ban-authors            also ban the authors' names (a confidential source whose authorship is itself identifying)
      --key string             the source key: lowercase, opaque for a confidential source (e.g. conf2026a)
      --keywords stringArray   retrieval keywords, comma-separated (repeatable)
      --meta string            a JSON file (or - for stdin) with "title", "aliases", "author" and "keywords"
      --permission string      permission_status: citable | no-public-citation | internal-never-cite | ai-generated-never-cite | ask-author (default by class)
      --private                the source is private: file it under confidential/ (exclusive with --public)
      --public                 the source is public: file it under public/ (exclusive with --private)
      --text string            the extracted text of a non-text document
      --title string           the exact title (for a confidential source prefer --meta)
      --type string            the CSL item type (default document)
      --url string             the canonical URL (recorded, never fetched)
      --venue string           the container title (journal, site, publisher)
      --year int               the year of issue
```

#### `abcd library ask`

Query memory and synthesise a cited answer: Writes a memory page only with --file-back; refuses outside a git checkout.

**Usage:** `abcd library ask <question> [--dry-run] [flags]`

**Flags:**

```
      --dry-run            with --file-back: check the input and report what would be written; write nothing
      --file-back          file the synthesised answer back as a new memory page
      --page-json string   the answer page dict as JSON (file path, or - for stdin)
      --top-n int          retrieval depth (0 uses the pinned default)
```

**Example:**

```
abcd library ask "why do record ids carry a timestamp?"
```

#### `abcd library cite-check`

Scan text for confidential sources and report each hit by key only: Writes nothing; refuses without a corpus, and exits 1 on a hit.

**Usage:** `abcd library cite-check <file|->`

Scan a file, or stdin with -, for every confidential source's title, aliases and
opted-in authors, through the private banlist's matcher — the engine the pre-commit
guard runs. Offenders are reported by key, field, line and byte offset, never by the
text matched, so the report is safe to relay. The offset counts bytes from the start
of the whole text, not from the start of the line, to the start of the matched span,
which can be the one byte before the phrase that bounds it. Exit 1 when anything is found.

**Example:**

```
abcd library cite-check draft.md
```

#### `abcd library declassify`

Move a published confidential source to public/ in one visible commit: Writes the corpus and commits it; refuses a key that is not confidential.

**Usage:** `abcd library declassify <key> [flags]`

Declassify a confidential source once it is published: `git mv` its folder from
confidential/ to public/ and set the entry's confidential flag and permission_status
(citable unless --permission says otherwise), in one corpus commit. The next
sync-banlist drops its strings, and its ledger lines become flippable.

**Flags:**

```
      --permission string   permission_status after the move: citable | no-public-citation | internal-never-cite | ai-generated-never-cite | ask-author (default citable)
```

**Example:**

```
abcd library declassify example-paper-2026
```

#### `abcd library ingest`

Distil a local file or an https source into cited memory pages: Writes the pages; refuses a URL that is not https.

**Usage:** `abcd library ingest <path-or-https-url> [--dry-run] [flags]`

**Flags:**

```
      --dry-run             check the input and report what would be written; write nothing
      --keep-original       store the original at .abcd/memory/sources/<sha256>.<ext>
      --pages-json string   DistilledPage JSON array (file path, or - for stdin)
```

**Example:**

```
abcd library ingest https://example.com/article.html
```

#### `abcd library init`

Create an empty sources corpus, a git repository with no remote: Writes the corpus in one commit; refuses an existing corpus or one inside another working tree.

**Usage:** `abcd library init`

Create the corpus at its location (0700): a git repository with no remote, an empty
sources.json and a README, in one commit. Refuses an existing corpus, a non-empty
directory, and a location inside another repository's working tree.

#### `abcd library ledger`

Append an influence line to this repository's ledger, or flip one to cited: Writes one ledger line; refuses a flip for a source that is not public and citable.

**Usage:** `abcd library ledger [flags]`

Append one influence record — {ts, repo, decision_ref, claim, source_key, locator,
influence, cited_publicly: false} — to this repository's ledger in the corpus, and
commit it. The ledger is append-only: a correction is a new line (--corrects N).

--flip N is the person's act of citing line N publicly. It checks the source first
(adr-41 gate 1: the folder is public/ and permission_status is citable), refuses
naming the failing gate, and on success appends a NEW line with cited_publicly true.
An agent never runs it. --list prints the ledger, numbered.

The repository is named by its root commit's first twelve hex digits unless --repo
names it.

**Flags:**

```
      --claim string          what was decided or claimed
      --corrects int          the line this record corrects
      --decision string       the decision influenced: a decision id, an ADR or intent id, or free text
      --flip int              cite line N publicly (the person's act; checks the source's permission first)
      --influence string      the influence: supports | contradicts | method | background
      --list                  print the ledger, numbered (read-only)
      --locator string        where in the source (pp., §)
      --repo string           the ledger's repository handle (default: this checkout's root commit, 12 hex digits)
      --source string         the source key
      --used-in stringArray   a repository-relative path the influence landed in (repeatable)
```

#### `abcd library lint`

Health-check the whole memory store: Writes a lint report; refuses a store with a blocker finding.

**Usage:** `abcd library lint`

#### `abcd library sync-banlist`

Project confidential titles and aliases into the private banlist: Writes the store's generated block; refuses a corpus whose folders and entries disagree.

**Usage:** `abcd library sync-banlist [flags]`

Regenerate the corpus's block in this repository's untracked private banlist
(.abcd/.work.local/private-names.txt, the banlist verb's private layer): every
confidential source's title and aliases, and its authors under ban_authors, as
whitespace-flexible, case-insensitive phrases. Lines outside the block survive.
A corpus whose folders and entries disagree is refused and nothing is written.

--refresh is the pre-commit guard's mode: it updates a private store that already
exists and declares the keyed format, and never creates one. With no corpus, no store
or a legacy store (migrate it with `abcd banlist migrate`) it says so on one line and
exits 0.

**Flags:**

```
      --refresh   the guard's mode: update an existing store only; an absent corpus or store is a one-line notice and exit 0
```

### `abcd lint`

Check this repository against the conventions, every target but outbound: Writes nothing; refuses with exit 2 on an error finding and exit 1 on warnings alone.

**Usage:** `abcd lint [flags]`

**Flags:**

```
      --root string   repo root to lint (default: current working directory)
```

#### `abcd lint docs`

Lint the docs for change-narration, broken links, citations, and stray root markdown: Writes nothing; refuses a tree with a blocker finding.

**Usage:** `abcd lint docs [flags]`

**Flags:**

```
      --config string   path to docs-lint.json (default: <root>/.abcd/docs-lint.json)
      --release-gate    run as the release gate: a citation past its staleness threshold blocks instead of warning (release-time only)
      --root string     repo root to lint (default: current working directory)
```

#### `abcd lint identity`

Show this repository's identity block and every surface held to it: Writes nothing; refuses a repository that records no identity block.

**Usage:** `abcd lint identity`

#### `abcd lint outbound`

Judge one outbound text against the session-URL and tool-footer policy: Writes nothing; refuses a text carrying either with exit 1.

**Usage:** `abcd lint outbound [FILE] [flags]`

Judge one outbound artefact — a commit message, a pull-request body, an issue, a
comment, a release note — against abcd's outbound policy: never a live
agent-session URL, never a tool's own attribution footer.

Reads FILE, or standard input when FILE is absent or `-`. It REPORTS and REFUSES;
it never rewrites the text it was given, because the text belongs to whoever
wrote it. Exit 0 clean, 1 the artefact is refused, 2 the check could not run.

**Flags:**

```
      --label string   what the artefact is (commit-message, pr-body, issue, comment) — it names the artefact in the report (default "outbound-artefact")
      --root string    repo root supplying the scanner configuration (default: current working directory)
```

#### `abcd lint site`

Gate the built website, rendering it first when absent: Writes only inside the output directory; refuses a site failing any gate with exit 1.

**Usage:** `abcd lint site [flags]`

**Flags:**

```
      --base-path string   path the site is served below on its host, such as /widgets/ for a project's GitHub Pages address; every root-absolute link is placed under it (default "/")
      --out string         built output directory to check (rendered first if absent) (default "site")
      --project            gate a project site, every page built from what abcd writes to the repository and the interface words, styles and scripts taken from the binary; .abcd/site.json then holds the site's settings only
```

### `abcd memory`

Count the memory notes in both layers and name any layer it cannot read: Writes nothing; refuses an unknown sub-verb.

**Usage:** `abcd memory`

Keep memory notes: short lessons an agent writes so a later session does not
relearn them. Personal notes live in the machine layer, `~/.abcd.noindex/memory.json`;
notes a person promoted into the project live in its `.abcd/memory.json`, beside each
rules.json. Both are read with the trust checks the rules layers get.

Bare `abcd memory` counts the personal notes tied to this repository and those
recalled everywhere, and the notes in the project's file, and names any layer
that could not be read and why. `abcd memory add` writes one note to the machine
layer and nothing else, after a gate refuses any note holding a secret, a
network address or a name this checkout's private banlist holds. `abcd memory
list` shows every note with its body, recall words, stamps and reach; `abcd
memory remove <mem-id>` removes any personal note. A note in the project's file
is removed by editing that file in a reviewed change, never by this verb.

Exit 2 on a refusal, with nothing written.

#### `abcd memory add`

Write one memory note, its body read from stdin: Writes ~/.abcd.noindex/memory.json only; refuses a secret, a network address or a private name.

**Usage:** `abcd memory add --title <title> --recall <word> --by <vendor:model> [flags]`

Write one note to the machine layer, the body read from stdin. The note is
stamped with the writer (--by, the Assisted-by form <Vendor>:<model-version>),
the clock's time and the host's session id (--session; without it the session
is recorded as unknown, and the write says so). It is tied to this repository
unless --everywhere recalls it in every repository; such a note has been
checked against this checkout's private names only, and the write says so.
--moved-from-host stamps a lesson the person pointed at in the host's own
memory files; the text still arrives on stdin, since add takes no path.

Exit 2 on a refusal — a field past its limit, a secret, a network address or
a private name, a session shaped like a link — with nothing written.

**Flags:**

```
      --by string            the writer, in the Assisted-by form <Vendor>:<model-version>
      --everywhere           recall the note in every repository, not only this one
      --moved-from-host      stamp a lesson the person pointed at in the host's own memory files
      --recall stringArray   a word or short phrase a later prompt would use (repeatable, 1 to 12)
      --session string       the host's id for this session; without it the session is recorded as unknown
      --title string         the note's title, one line of at most 120 characters
```

**Example:**

```
abcd memory add --title "The tests need the race flag" --recall test --recall race --by Example:model-1 < note.txt
```

#### `abcd memory list`

List every memory note with its body, recall words, stamps and reach: Writes nothing; refuses any argument.

**Usage:** `abcd memory list`

List every note in both layers: its id, title, body, recall words, who wrote
it, when and in which session, its origin, and its reach (this repository,
everywhere, another repository, or the project's file). Read-only.

#### `abcd memory remove`

Remove one personal memory note, whoever wrote it: Writes ~/.abcd.noindex/memory.json only; refuses a note in the project's file.

**Usage:** `abcd memory remove <mem-id>`

Remove one personal note from the machine layer, whoever wrote it, run by a
person or by an agent at a person's request. A note in the project's file is
removed by editing that file in a reviewed change, and is refused here.

Exit 2 on a refusal, with nothing written.

**Example:**

```
abcd memory remove mem-2609010000000001
```

### `abcd mode`

Print or set whose answer the agent loop is waiting on: Writes the state only when setting it; refuses an unknown state or a checkout with no local tier.

**Usage:** `abcd mode [<state>]`

Print or set the waiting-on state behind the status line's badge.

Bare `abcd mode` prints the stored state: `managed` (abcd is here and nobody
is waiting), `facilitator` (the loop is parked on the facilitator, the person
at the terminal running the agents), or `product-thinker` (the loop is parked
on the product thinker, who answers on a surface of their own). An absent
store reads as `managed`.

`abcd mode <state>` sets it. Two writers share the verb: the agent runs it
when it stops for a verdict other than a question, naming whom it is
addressing, and the human runs it by hand to say which hat they wear. The state lives per checkout at
`.abcd/.work.local/mode`, so only a repository abcd manages — one that has
the local-ephemeral tier — can hold it; elsewhere the set refuses and creates
nothing. The next status-line refresh and the bare `abcd` board read the
same file.

A question needs no setting: when the guard admits abcd's question through
the host's question tool, it sets the state from the question's chip
(Product to product-thinker, Tech and Setup to facilitator) and marks the
question open. The answer resets the state to `managed` and says so once on
stderr: the question tool's PostToolUse hook resets it when the answer comes
back, and the prompt hook on the next human message where the host runs no
PostToolUse. A state set by hand with no question open is left as it is.

Where this machine has no status surface — no `~/.abcd.noindex/statusline.json`, or
one with `disabled` set — the set form prints one line naming whose answer
is owed, once, because the verb call is the stop. Setting `managed` owes
nobody and prints nothing; with a surface installed nothing is printed at
all. With --json the notice is a field. Both forms make no network request.

Exit 2 on a refusal — an unknown state, no local tier, or no checkout —
and nothing is written on any of them.

The away mode sits beside the badge, not as a fourth word: `abcd mode
autonomous [--until <time>] [--hold-pushes]` records that the person is away,
`abcd mode queue "<step>"` keeps a step for their return, and `abcd mode back`
ends it and prints what was queued and recorded. While it holds, setting
`product-thinker` or `facilitator` is refused (exit 2), naming `abcd decide`:
a stop parked on a person who is away is a question nobody answers. The away
mode grants no rights; the person's standing instruction decides what is pushed.

#### `abcd mode autonomous`

Record that the person is away and sessions work on, until a time or open-ended: Writes the away record; refuses an end already past or past seven days.

**Usage:** `abcd mode autonomous [flags]`

Record that the person is away, for every working copy of this repository on
this machine: who set it (the holder name reservations resolve without a
network read, else git's user.name), from which working copy, and when it ends.

--until takes a clock time (its next occurrence, local time, as 09:00) or a
timestamp (2026-10-19T09:00, or RFC 3339). Without it the mode is open-ended,
and every record ends seven days after it was set at most: an --until past that,
or one already past, is refused. --hold-pushes records the person's word that
pushes wait for their return; it narrows what sessions do and grants nothing.

The away mode grants no rights: the person's own standing instruction decides
what is committed, pushed, and opened or merged as a pull request. It ends at its
time or with `abcd mode back`; a prompt never ends it. Setting it again keeps
whatever is queued or recorded and not yet read.

The record lives in ~/.abcd.noindex/away/<root-sha>/record.json, keyed on the repository's
root commit, and is changed under its lock, which only `abcd mode back` goes
around. A record merely past its 64 KiB is carried, its oldest lines let go.
Exit 2 on a refusal (an unreadable or past --until, one past seven days, no local
tier, no checkout, or a record or lock that is not safely this account's) with
nothing written. No network request.

**Flags:**

```
      --hold-pushes    the person's word that pushes wait for their return (grants nothing)
      --until string   when the mode ends: a clock time (09:00) or a timestamp; open-ended (seven days at most) when omitted
```

#### `abcd mode back`

End the away mode, printing what was queued and recorded one line each: Writes its ending whatever the record's or lock's state; refuses outside a git checkout.

**Usage:** `abcd mode back`

End the away mode: print one plain line per queued step, per item handed back
and per recorded stop (a stop at the host's cap is labelled "possibly forced by
the cap"), record who ended it and from which working copy, and close the record.
On a record whose time has already passed it prints the same and closes it. With
no record, or one already closed, it says there is nothing to end.

A session runs it only on the person's word in that session. It ends the mode
whatever state the record is in: one past its 64 KiB is printed whole and kept
with its oldest lines let go and counted; one that does not parse, or is not
safely this account's, is replaced by a closed record, printing nothing from
it; and a lock not had in time is gone around. Each is named on its own line.
No network request.

#### `abcd mode queue`

Queue one step for the person's return while they are away: Writes the away record; refuses when no away record holds.

**Usage:** `abcd mode queue <step>`

Queue one step for the person's return, while the away mode holds: an act only
the person may approve, which a session queues instead of asking, then carries on
with other work. `abcd mode back` prints each queued step on one line.

Exit 2 when no away record holds (ask the person instead), on an empty step or one
over 500 characters, when the queue is full (it is never cut), and when the record
or its lock is not safely this account's, with nothing written. No network request.

**Example:**

```
abcd mode queue "approve the embargo close for the example advisory"
```

### `abcd peers`

List what peers hold that this checkout lacks, and the reservations: Writes the fetched reservations, re-arms withdrawn merges; refuses outside a git checkout.

**Usage:** `abcd peers`

List what this checkout's peers hold that it does not, before capturing, fixing or
filing anything. A peer is a linked worktree sharing this repository's git
common dir, read off its disk so an uncommitted capture is seen, or a local
branch no worktree has checked out, read from the object store.

Per peer, three kinds of row: an issue open there and absent here; an issue
open here and resolved or won't-fixed there; an intent drafted there and
absent here. A peer whose worktree directory is gone, or whose branch is
merged into the default branch (a worktree only when its record folders are
also clean), is skipped and counted. A peer git refuses to answer for, one
whose common dir is another repository's, or one whose ledger holds an id in
two status folders is named with the reason and not read; a gone or refused
worktree's branch is then read from the object store instead.

Then the reservations on the shared remote: one fetch from origin of every
abcd-reserved/ branch, with pruning, and of the default branch, then every
reservation with its record, holder, footprint, effective expiry and state
(live, expired, released, or unreadable with its reason and the end of its
hold), a live drain lane's stage when its renewal names one, the worktree of
this repository on this machine that made one (by its folder's name, with
parent folders added only where two would otherwise read alike),
each person's count of live reservations, the reader's own counted by copy
(this copy, each such worktree, elsewhere) against this machine's
reservation.max_live with a warning from four fifths of it, since every
session and account on the same login counts toward the same total, and a
line for each release being cut (a live
rel-vX.Y.Z reservation, which holds every other session's merge until its
tag is on origin). Then each holder's hand-backs of the last day, from the
same view: the record and kind of each released tip marking one, newest
first, the newest ten shown and the rest counted; one dated more than five
minutes ahead of this computer's clock is not shown. Then each release's
withdrawn pull requests (release_withdrawals): those a live release holds or
admitted, a lease that lapsed before the release ended (ended by its own
person's next act five minutes after), those an ended one has still to re-arm
(yours, or another person's, named
with whose), and those its tombstone skipped for their owners; and those a
later commit on a recent release's branch dropped (lost_withdrawals). The fetch
reads origin's release tags with the reservations; it updates the
remote-tracking reservation branches and the release tags abcd keeps under
refs/abcd/release-tags/, stamps when it ran in the local tier, with when it
first fetched each reservation dated ahead of this computer's clock or
undated, and keeps there each verdict of the forge's record of pushes that
never changes. One more act follows it, only when a release has ended (its tag on
origin, or a tombstone its holder pushed) with pull requests you withdrew for
it not yet re-armed: a tombstone is pushed first, then each one the forge's
record of pushes says you recorded is re-armed through gh in the form you
recorded, pinned to its withdrawn head, or skipped when its head
moved, it was closed or merged, or it can only be merged by hand, and a second
tombstone records every state (settled). Each pull request re-armed, found
armed or skipped for its owner then gets one fixed comment, and a comment
that fails is named in settled.failures. Nothing else is written or posted. The release-tag refs are ordinary
refs of this checkout, so git log --all lists the commits they name and
git push --mirror would push them. A checkout with no remote named origin
lists no reservations.
When the fetch fails, the reservations are listed as last fetched, with that
view's age, and the failure is named on stderr and in fetch_error.

When ~/.abcd.noindex/holder-ids is there and its guarded read refuses it, no
declared id is read as yours, and one line on stderr names the class of the
refusal, never the file's contents (holder_ids_refused in --json).

When your holder id is set or kept but refused (ABCD_HOLDER_ID set to
anything but one holder id, or ~/.abcd.noindex/holder-id refused by its
guarded read), no hold or withdrawal under it is read as yours, and one line
on stderr names the class of the refusal, never the value or the file's
contents (holder_id_refused in --json).

A worktree is named home-relative (~/...), or by its directory name when it
sits outside HOME, on every stream. Exit 0 whatever the peers hold; exit 1 when
the reservations could not be fetched; exit 2 outside a git checkout.

### `abcd reading`

Render the cold-reading assembler's state: Writes nothing; refuses any argument.

**Usage:** `abcd reading`

Assemble the input a cold reading is handed.

Blindness is a property of the input, not a promise the reader makes: a positive include
table names what may travel, fields are projected out of records rather than files copied
whole, and a hashed manifest records what was passed so a reader can judge contamination
rather than accept a disclosure on trust.

Bare `abcd reading` renders the assembler's state and writes nothing.

#### `abcd reading assemble`

Assemble one reading's input and its hashed manifest at one position: Writes both artefacts; refuses a target that is not HEAD or a commit sha.

**Usage:** `abcd reading assemble --position <position> --target <HEAD|sha> [flags]`

Walk the repository under the include table at one reading position and write two
artefacts: the assembled input, which carries no repository path, and the manifest,
which maps every passed item back to its path, its field and its hash.

The invocation is a position and a target state, and nothing else. --position takes
one of four closed tokens; --target takes HEAD or a hexadecimal commit sha of 7 to 40
digits, because a branch or a tag moves and the manifest's re-runnability rests on a
reference that cannot. Both are required.

What the reading is handed comes from the committed preset entry for the position, in
.abcd/config/reading-presets.json, applied with no operand. Changing it is a commit to
that file, reviewed and inside the dirty gate; the manifest records the entry applied
and its hash, so a run is reproducible from the commit it names.

**Flags:**

```
      --dry-run           write nothing; with --out the two artefacts still land in that directory
      --out string        an empty or absent directory the assembled input and the manifest are written to,
                          for inspection: reading ingest finds a run only in the local-tier run directory,
                          so a run written here cannot be ingested (default: the local-tier run directory)
      --position string   the reading position: widening, entailment, comparative, detection
                          (comparative derives its candidate set from the record: the one committed
                          widening run at the target whose items carry no disposition and no
                          admission — at the target, or at an ancestor of it across which only the
                          readings store and the issue ledger changed, so a run's own records can be
                          committed between its ingest and this assembly. None, or more than one,
                          refuses and lists the runs)
      --target string     the commit the assembly describes: HEAD, or a hexadecimal sha of 7 to 40 digits
```

**Example:**

```
abcd reading assemble --position widening --target HEAD
```

#### `abcd reading ingest`

Validate the JSON one cold reading returned: Writes its reading records; refuses output the position's licence does not allow.

**Usage:** `abcd reading ingest --reading-json <path> [--dry-run] [flags]`

Validate the JSON a cold reading returned and write its reading records.

The verb checks what the reading was LICENSED to produce, not only what it saw: the
supply regime is read from the position's definition and compared with the output's own
claim, and an item carrying a reserved name as one of its own fields is refused with the
licence stated. The reserved-name table is read at the run's own regime, one row per
regime, and the generative regime has no row: no name is reserved at the generative
position.

Item identifiers are minted here. The payload carries none, so a supplied one is refused
as an unknown field. A refusal becomes DURABLE once the run's identity is proven — the run
id resolving to a parked manifest whose content hash matches — and from there a list-level
refusal writes refusal.json under the run's directory; before that point nothing durable is
written anywhere. No OTHER run's durable state is touched until the whole payload validates:
a refusal after the run is proven writes its refusal record and nothing else, and the one
delete it makes is on its OWN run id — the records of an earlier attempt at it that never
committed. The reading records land as one batch and the run metadata is written last as the
commit marker: a run without one never happened.

An ingest interrupted before that marker leaves an orphaned stage, and every invocation names
it. Only the next one whose payload validates sweeps it: where the run reached no commit
marker the sweep ROLLS THAT RUN'S READING RECORDS OUT OF THE COMMITTED LEDGER, because the
run never happened; where the marker is there the run stands and only the stage goes. A
refused run reports the orphans it left in place, and the ids a sweep removed are reported as
rolled_back_records on every exit, including a failing one.

Every stored finding is matched against the record as a capture is: its pattern and body are
compared with the open and resolved issues, the intents and every earlier reading item, never
with another item of the same run, and a likely repeat is written onto the reading record as a
duplicates: or refines: link and shown, printed and as matches in --json.

With --dry-run the output is judged as above, short of the ledger writer's own matching,
redaction and refusals, which run only when it writes, so a practice run that passes can
still be refused there. Nothing is written: no reading record, no refusal record, no stage,
no sweep and no run metadata. The report names each file the ingest would write; a refusal
the ingest would record says where instead.

**Flags:**

```
      --dispatch string       send the parked run <rdg-N> to the provider its position is pointed at (oracle.roles.cold-reading-<position>) and ingest the answer
      --dry-run               check the input and report what would be written; write nothing
      --reading-json string   path to the JSON the cold reading returned
      --route stringArray     route one agent for this run: <agent>=<tier>[@<connection>][?k=v,...], tier one of local | economy | frontier | host-decides (one per agent this invocation dispatches, and each invocation dispatches one; wins over every accepted routing table for this run alone, and the receipt records it verbatim)
```

**Example:**

```
abcd reading ingest --reading-json reading.json
```

### `abcd reflect`

Render the seed a cut release's retrospective interview opens from: Writes nothing; refuses a release that shipped no intent, or an intent id.

**Usage:** `abcd reflect <release-tag>`

Open the retrospective for a cut release: render the seed the interview opens from —
the intents the tag shipped, which of them carry audit notes, the intents targeted at
the release that have not shipped, the changelog section and the computed metrics —
and write nothing. `reflect write` writes the retrospective from the answers.

The release is the only grain: an intent id is refused, because per-intent
reflection is the intent audit's (`abcd intent audit <itd-N>`).

**Example:**

```
abcd reflect v0.11.0
```

#### `abcd reflect interview`

Run a cut release's retrospective interview in a plain Terminal on your own route: Writes the answers record and README; refuses with no route of yours.

**Usage:** `abcd reflect interview <release-tag> [--answers <file>] [--answered-in <place>] [--proceed] [flags]`

Run the retrospective interview in a plain Terminal, with no host session: the reflection-composer,
on the runner the person routed it to in their own machine's config, writes each question, abcd
draws it and takes the answer, and the outcome is filed through reflect write's own checks. With
no route of the person's to a runner it refuses before anything runs, writing nothing. Off a
terminal the questions are answered from --answers, by ordinal (Q1, Q2, ...).

**Flags:**

```
      --answered-in string   where an answers-file entry that names no place was answered: Terminal, or the host whose question tool asked it, as its plugin page passes; recorded with each answer (default "Terminal")
      --answers string       answer the questions from this answers file (JSON: schema_version, interview "retrospective", answers by ordinal Q1, Q2, ...) instead of drawing them; the run refuses at the first question the file does not answer
      --proceed              run although intents targeted at the release are unshipped (the person's confirmation)
```

**Example:**

```
abcd reflect interview v0.11.0
```

#### `abcd reflect write`

Write a cut release's retrospective from the interview's answers: Writes its README once; refuses a thin answer or unconfirmed unshipped work.

**Usage:** `abcd reflect write <release-tag> --answers <file> [flags]`

Write the retrospective for a cut release from the interview's answers, a JSON
object with one {"answer", "follow_up"} entry per asked section (went_well,
could_improve, lessons, decisions). It refuses, writing nothing, while an answer is
under the floor and its follow-up is unanswered, while intents targeted at the release
are unshipped and --proceed was not given, and when the retrospective already exists.

**Flags:**

```
      --answers string   the interview's answers, a JSON file
      --proceed          write although intents targeted at the release are unshipped (the person's confirmation)
```

**Example:**

```
abcd reflect write v0.11.0 --answers answers.json
```

### `abcd report`

File a defect report or an enhancement proposal about abcd: Writes it into your account's inbox; refuses a malformed field or a filesystem path.

**Usage:** `abcd report [<file>|-] [flags]`

File a written account about abcd itself, from a repository abcd manages, into
the inbox in the user account's machine store (`~/.abcd.noindex/inbox/`). Nothing is
written into this repository or into abcd's, and nothing becomes a record until
a person or a session runs `abcd inbox promote`.

`abcd report --template` prints the skeleton: a block of fields between `---`
lines (template version, kind, severity, category, title, the abcd version and
surface in play, an optional remedy and evidence pointers) and the prose below
it. `abcd report <file>` validates a filled report and files it; `-` reads it
from stdin. Bare `abcd report` opens the skeleton in $VISUAL or $EDITOR when
the session is a terminal, and files what is saved.

The report is held to the template: a missing or malformed field is refused
naming the field, a report over 32 KiB or carrying a control byte is refused,
and a field naming a filesystem path is refused, because a report points at
records, commits and URLs, never at a location on a machine. abcd names the
file from the time and this repository's root-commit key; the verb prints the
report's id and where it landed.

Exit 2 on a refusal, with nothing filed. Exit 1 when filing fails (the inbox
cannot be created, every id drawn this second is taken, the write fails), with
nothing filed. After the editor ran, both name where what was written is kept.

**Flags:**

```
      --template   print the report skeleton to fill (writes nothing)
```

### `abcd reserve`

Reserve an issue, intent or release on the shared remote, or release it: Writes one commit to its origin branch; refuses what someone else holds, with exit 3.

**Usage:** `abcd reserve <record-id> [flags]`

abcd reserve <record-id> --footprint <path> [--footprint <path>…] [--take-over] [--lease <duration>]
abcd reserve rel-vX.Y.Z --admit <pr>
abcd reserve <record-id> --release
abcd reserve --holder
abcd reserve --sweep [--apply] [--older-than <days>]

Reserve an issue or an intent on the shared remote before starting work on it, so
every other participant sees it is taken. The reservation is the branch
abcd-reserved/<record-id> on the remote named origin: a chain of empty-tree commits
naming the record, the holder (your holder id, below), this working copy, the files
the work will change (--footprint, once per repository-relative path) and the
lease (--lease, from 1m to 24h; default 2h, or 24h for a release).

A session cutting a release reserves the release instead, rel-vX.Y.Z, with no
footprint: while it is live every other session's land step holds its merge.
It holds for 24h unless --lease names less, sits outside the per-person cap,
and ends when the tag vX.Y.Z is on origin or its holder releases it; running
the same command again from the same copy renews it.

A release reserved anew (not renewed from the same copy while live) also withdraws
every pull request into origin's default branch that has auto-merge on or sits in
the merge queue, but the release pull request from this checkout's branch,
through gh under your own identity (refused when gh acts as another account),
and records each on the reservation first, with the form it was armed in and its
head (withdrew in --json). A withdrawal the forge refuses is named and the
reservation stands (forge_failures); the launch check then refuses the cut while
that pull request is armed. One release is cut at a time: another release live
backs this one off. --admit <pr>, from the copy cutting the release, records one
withdrawn pull request admitted, then re-arms it in its recorded form, pinned to
its withdrawn head. --release from that copy pushes the tombstone, then re-arms
every other one the same way; once the tag is on origin, any act of a copy of
the same person that fetches the reservations does so, and so does one five
minutes after the lease lapsed with no tag, for the cut's own person alone; a cut
still going on renews it by reserving again. One
whose head moved, that was closed or merged, or that can only be merged by hand
(no merge queue), is skipped and named for its owner; every state is recorded on
the tombstone (settles in --json), so no copy acts twice, a copy of another
person never re-arms (stranded in --json), and each id you declare with no
login beside it that names one of those is listed (unpaired in --json): writing
its account's login after it in ~/.abcd.noindex/holder-ids lets this copy settle
them. A person's withdrawals are read only from their own newest push to the
release's branch, as the forge's record of pushes shows it: commits others
pushed above it are counted and never read (not_read in settles), and when that
push cannot be found or placed nothing is acted on for that person (unplaced in
settles).

Every act fetches the reservations from origin, judges the tip, writes one
commit and makes one plain fast-forward push, with the repository's hooks
running: a reservation, a renewal by the same person and copy, a take-over of
a reservation lapsed past its expiry by five minutes, or a release (--release),
which pushes a tombstone. --take-over moves your own live reservation from
another copy to this one; it never moves another person's. A record already
resolved, won't-fixed, shipped or superseded on origin's default branch counts
as released whatever its reservation says, and so does a release whose tag is
on origin.

A new reservation or a take-over asks GitHub whether origin is a fork, and a
fork is refused unless reservation.fork_origin names it; when GitHub cannot say,
the act goes on and warns (not checked: whether origin is a fork, fork_unchecked
in --json). An issue a drain handed back carries the hand-back on its tombstone:
your own reservation over it is made, with a note (handed_back in --json), and a
plain --release of it keeps the hand-back standing until a person changes the
record on origin's default branch (hand_back_kept in --json), so no drain takes
the issue, nor takes over or renews your reservation over it. A release whose
tombstone cannot mark the hand-back is still made, plain, and says why
(hand_back_unpublished in --json).

A footprint sharing a path with another person's live reservation backs off
(exit 3). A file that origin's default branch, as last fetched, declares
linguist-generated in its root .gitattributes is shared, never an overlap, and
is named on a shared: line for whoever lands second to regenerate after
merging (generated_shared in --json); a directory never is. When that
declaration cannot be read nothing is shared, and the act says why
(generated_unread in --json). Your own reservation sharing a path with yours
from another copy is made, and warns on stderr, naming that copy (own_overlap
in --json). Name files, not directories: a directory holds off every
reservation of a file inside it. A footprint path naming a directory git
tracks is reserved all the same, and warns on stderr, naming it and how many
tracked files it covers on origin's default branch, or HEAD
(directory_footprint in --json). A path named twice is written once. A reserve
of a record you already hold writes its footprint in place of the one held,
and warns on stderr, naming each held path it leaves out (dropped_footprint in
--json): name them again to keep holding them.

A reservation, a renewal and a take-over consult the embargo store on this
machine before anything is pushed, as an announcement does: a record the store
holds, or a footprint naming something under embargo, is refused (exit 2) with
nothing pushed, and so is the act when a store cannot be read, naming that
store. A release does not consult it. A build's and a drain's reservations
consult it too.

The holder is named by your holder id: h_ and 32 random lower-case hex
characters, minted the first time one is needed into ~/.abcd.noindex/holder-id
(owner-only) and kept. No trailer and no branch name abcd pushes carries your
GitHub login. Each commit's author and committer fields carry your git
identity when it is a person's; when it is unset or a machine's, they carry the
GitHub account the token resolves to, by its login and no-reply address. Holds
already pushed under your login are not rewritten. A fresh
mint says so once on stderr: holds made under an earlier id of yours read as
someone else's until they lapse. ABCD_HOLDER_ID, when set, is your id instead,
read before the file and never written to it: set it to the id --holder prints
in a hosted or ephemeral session's own settings, whose home is not kept; set to
anything but one id, every act refuses. A holder-id file another account owns
or could write, or one that holds no id, is refused, never replaced. A
reservation under an id listed in
~/.abcd.noindex/holder-ids (one per line, # comments; the ids your other
machines and accounts print with --holder) is yours too, from another copy.
Write the GitHub login of the account an id is yours on after it, on its line
(h_<32 hex> <login>), and a release's commit naming that id counts only when
that account pushed it; an id with no login beside it is held to your own
login, as your other home under the same login pushes it, so abcd reads a
release end from it, and acts on its withdrawals, only when your own login
pushed the reservation that recorded them. The login is read on this machine
only and never pushed. A holder-ids file the guarded read refuses (another
account owns or could write it, it is not a regular file, it is too large or a
line is malformed) refuses every act; --holder, abcd peers and abcd status read
it as declaring no id, and each says so in one line on stderr naming the class
of the refusal, never its contents (holder_ids_refused in --json).

abcd still works out your GitHub username, which is never pushed, from the first
of these that names it: user.email, when it is a GitHub no-reply address;
reservation.github_username in the machine configuration (the repository's own
configuration is never read for it); and the account this session's own GitHub
token belongs to, which takes one call to GitHub's user endpoint, through gh. A
reservation made before the holder id names that username, and is still yours.
When git's identity is not a person's (unset, or a machine's), the token alone
names the account, that account authors the reservation commit, and the
identity git had is shown nowhere. The checkout must have its local tier
(.abcd/.work.local/), where this copy's key is kept. `abcd peers` lists every
reservation.

--holder prints the account an act from this checkout would reserve as and the
source that named it (git, config or token), then your holder id, where it
comes from, and any ids declared as yours, or its --json document. It may make that
one call to the user endpoint in two cases: git's identity is a person's but
carries neither a GitHub no-reply address nor a machine key; or git's identity
is not a person's (unset, or a machine's), when the machine key is skipped. It
takes no record id and no other flag, reserves and pushes nothing, and writes
only the holder id, when none is kept yet. It exits 0 when the account and the
holder id are known and 2 when not.

Exit 0 when the act reached origin (or a release was already made); exit 3 when
the record is held by someone else or by your other copy, so back off; exit 2
on every other refusal and failure. Nothing is pushed on a refusal, and a failed
push leaves no reservation and nothing in the checkout.

--sweep lists the spent reservation branches on origin and, with --apply, deletes
them, each with a lease on the exact tip it judged, so a branch re-reserved
meanwhile survives. A branch is spent when its tip has settled, its lease past
the five-minute margin included (a plain release, or a hand-back on a finished
record, at once, at the next sweep; any other tip only once untouched for
--older-than days, default 7, at least 1),
and either its record is resolved, won't-fixed, shipped or superseded
on origin's default branch, or every commit on it is a reservation or a plain
release, whether or not any is a release, since a lapsed lease already lets any
session take the record over. A hand-back on a record still open, a commit of
a kind the sweep cannot classify, a history it cannot read to its root, and an
unreadable tip keep the branch.
The reservations ruleset lets only its bypass actor delete these branches, so
the scheduled reservation-sweep workflow is what applies it; anyone else's
--apply is refused by origin. It takes no record id and no other flag; exit 0
when it ran (a branch that moved since it was judged is kept, not a failure),
exit 2 when it could not run or origin refused a deletion.

**Flags:**

```
      --admit int               on a release reservation, from the copy cutting it: re-arm this withdrawn pull request and record it admitted
      --apply                   with --sweep, delete the spent branches, each only while its tip is the one judged
      --footprint stringArray   a repository-relative path the work will change; repeat once per path (never split on commas)
      --holder                  say which GitHub account an act would reserve as, and from where, and your holder id; reserves nothing
      --lease duration          how long the reservation holds, from 1m to 24h (default 2h, or 24h for a release)
      --older-than int          with --sweep, the days a tip other than a release must have been untouched past its lease (at least 1) (default 7)
      --release                 release your reservation from this copy by pushing a tombstone
      --sweep                   list the spent reservation branches on origin, which --apply deletes; a dry run without it
      --take-over               move your own live reservation from another copy to this one
```

**Example:**

```
abcd reserve iss-2609010000000001 --footprint internal/core/example/example.go
```

### `abcd rules`

Render the active rule set, or the one domain named: Writes nothing; refuses an unknown domain.

**Usage:** `abcd rules [domain] [flags]`

Render the rule set the modular-rules loader injects: the bundled default
domains, overridden by this machine's ~/.abcd.noindex/rules.json and then by this repo's
.abcd/rules.json, each layer per field, so the repo wins a field both set.
Either file may be absent. Bare, it renders every active domain; a positional
DOMAIN (case-insensitive) renders that one domain regardless of its state or the
kill switch, so a dormant domain is still inspectable.

Every domain says which layer it came from. A domain an override names — its
rules replaced, its state changed, or a custom domain declared — renders as
"## NAME (user override)" or "## NAME (repo override)" here, in the injected
block and in the hook's diagnostic, and carries "source": "user" or "repo" in
--json; the last layer to name a domain labels it. An untouched bundled domain
renders bare and carries "source": "bundled".

A list an override sets replaces the one it would inherit, so an override can
hold back an entry abcd ships or, in SHELL, one the repository's
.abcd/guard.json teaches. For the guardrail domains (COMMITTING, LOAD, PII,
SHELL), every such recall keyword, alias or rule that an override's list leaves
out is named on stderr, with the file that set the list, here and on every hook
prompt. To keep an entry, restate it in the list, or leave the field out to
inherit the list.

SHELL is generated from the shell-hazard registry that "abcd guard" enforces
in this repository, the bundled entries and the repository's own
.abcd/guard.json entries alike: one rule per registry entry, naming the
command, why it is dangerous and what to run instead, recalled by the commands
the registry names. A rule in the repository's words is marked "(repo)" after
its entry id. A guard.json the guard refuses is named on stderr and not taught;
SHELL then teaches the registry the guard enforces in its place. It teaches
before shell work what the guard refuses at the moment a command runs.

GRILL is generated from the asking rules every abcd interview follows, every
limit they state (the header chip's width, the options per question, the words
per label, the rows at eighty columns) filled from the one value the question
check in "abcd guard hook" enforces, so the rules and the check cannot state a
limit differently. It recalls on words of asking and choosing, so it lands in
most sessions; a repository silences it with {"GRILL": {"state": "dormant"}} in
its .abcd/rules.json.

--prompt "<text>" shows what that one prompt would bring back to a fresh
session: each rule domain it matches, with the recall words that hit, and
each memory note it recalls from ~/.abcd.noindex/memory.json and .abcd/memory.json,
and each memory page from .abcd/memory/ and ~/.abcd.noindex/memory/, with its
layer and the recall words that hit. Each comes back in the form the
context bracket gives it — a domain in full or as its heading and first
rule, a note or page in full or as one line — or as not fitting the
per-turn budget, or as larger than the whole budget, which no turn can
carry in full. Notes and pages share one ranked order, a BM25F relevance
score that decides which of them fit the budget: each shows its rank and
score and, under it, every matched term with the fields it was found in
(recall words, title, body) and what it added to the score. It reads
against an empty ledger and writes nothing.

--fill <percent-used>, with --prompt, sets how full the context window is,
and so the bracket shown; without it the diagnostic has no session, so the
fill is unknown and it renders the unknown-fill form. The brackets, read as
the share of the window still free, are the loader's one table:

- fresh (70% or more of the window free): Rules in full; notes and pages in
  full, in ranked order, within the per-turn budget.
- moderate (40% to 70% of the window free): Each rule domain as its heading
  and first rule, with a line naming the command that renders the rest; the
  top-ranked notes and pages in full within 8 KiB, the rest as one line
  each.
- depleted (below 40% of the window free, to the end of the session): Each
  rule domain as its heading and first rule, with a line naming the command
  that renders the rest; notes and pages as one line each, the top-ranked
  lines within 2 KiB and always at least the top-ranked one.
- unknown (no source tells how full the session is): Rules in full; notes
  and pages as one line each, the top-ranked lines within 2 KiB and always
  at least the top-ranked one.

--prompt and a DOMAIN are two forms and are refused together, exit 2, as is
--fill without --prompt or outside 0 to 100.
Read-only.

**Flags:**

```
      --fill float      with --prompt, the share of the context window used, 0 to 100, which sets the context bracket shown; without it the fill is unknown
      --prompt string   show what this one prompt would bring back to a fresh session: the domains it matches and the memory notes and pages it recalls
```

### `abcd scribe`

Assemble a ledger scribe's context and ingest what it transcribed: Writes nothing bare; refuses an unknown sub-verb.

**Usage:** `abcd scribe`

Build the ledger scribe's context and ingest what the scribe returns.

The scribe transcribes a reading run's records and the researcher's dispositions into the
ledger's declared shapes, and authors nothing. Its context is the reading assembler's exact
inverse: ledger content only, drawn from the issue ledger's own directories, and the
researcher's supplied text. `assemble` builds it with a manifest of every path passed;
`ingest` validates the scribe's output and refuses anything the scribe authored.

#### `abcd scribe assemble`

Build a scribe session's context from the ledger and supplied dispositions: Writes it and a hashed manifest; refuses an uningested run or a symlinked ledger.

**Usage:** `abcd scribe assemble --run <rdg-N> --dispositions <path> [flags]`

Build the context one scribe session is handed, for one ingested reading run.

The context is positive inclusion at directory grain: the issue ledger's own directories
(its reading records, dispositions, admissions, surprises and reframes, and its three status
directories), derived from the ledger's directory list, and the researcher's dispositions
text read whole. Nothing else is walked, and an item outside that list is refused whatever
route it arrived by. The run must be ingested: its records come from the store, never from
a raw reading output handed over again.

The context and a manifest naming every path passed, by hash, are parked in the local tier
(or under --out, which may not be a directory a reading's include table reaches). Nothing in
the durable record is touched. Both carry the scribe's per-run context stamp.

**Flags:**

```
      --dispositions string   the researcher's dispositions text, read whole and carried verbatim
      --dry-run               write nothing; with --out the two artefacts still land in that directory
      --out string            an empty or absent directory the context and the manifest are written to
                              (default: the local-tier scribe run directory)
      --run string            the ingested reading run the session transcribes for (rdg-N)
```

**Example:**

```
abcd scribe assemble --run rdg-2609010000000001 --dispositions dispositions.md
```

#### `abcd scribe ingest`

Validate a scribe's output against the supplied dispositions: Writes what it transcribed through the capture verbs; refuses anything the scribe authored.

**Usage:** `abcd scribe ingest --scribe-json <path> --dispositions <path> [--dry-run] [flags]`

Validate the JSON a scribe session returned and write its records through the capture verbs.

The context the session was handed is proven first: it must hash to its parked manifest, and
the output must cite that hash. The pair is parked where a scribe session could rewrite it, so
--dispositions names the researcher's own text again, the file assemble was handed: the
manifest's supplied hash and the context's supplied copy must both equal it, and every check
below reads it. Then the output is refused if the scribe authored anything —
a field outside the declared shapes, an item the supplied dispositions never name, a state or an
admission the item's own line of the supplied text does not carry, or a ground, exit condition
or surprise that does not stand verbatim in the supplied text once whitespace is folded — or if
it passes over an unanswered item of the run in silence. Nothing is written until all of that
holds.

Dispositions, admissions and surprises are then written in that order through the capture verbs,
which apply their own redaction and refusals, the ordering gate included; the first refusal stops
the ingest and names what landed before it. Fidelity flags and refusals are reported and never
written. Once every write has landed, and when at least one record did, the manifest is promoted
beside the run, write-once; an ingest that lands no record leaves the run open.

With --dry-run every check above is made and nothing is written: the report names each
record the capture verbs would write, its id shown as <id>, and the manifest it would promote.
The capture verbs' own redaction and refusals are made only when they write.

**Flags:**

```
      --context string        the context the session was handed, when assemble wrote it under --out
                              (default: the local-tier scribe run directory of the output's run)
      --dispositions string   the researcher's dispositions text, the file assemble was handed
      --dry-run               check the input and report what would be written; write nothing
      --scribe-json string    path to the JSON the scribe session returned
```

**Example:**

```
abcd scribe ingest --scribe-json scribe.json --dispositions dispositions.md
```

### `abcd session`

Set up live brief sessions, start one here, or run, deploy or write the team's relay and page: Writes nothing bare; refuses an unknown sub-verb.

**Usage:** `abcd session`

Set up live brief sessions for this project, start one on this computer, run
the relay a team's cloud sessions go through, write the blueprint that deploys
that relay to the team's own Render account, or write the session's static page
for the team to serve.
The relay holds each session's edits in memory only, as opaque bytes, and drops
them when the host closes the session or nobody has been connected for half an
hour; it writes nothing to disk and logs nothing. abcd runs no relay of its own:
the team runs it, on the host's computer reached over Tailscale Serve
(`abcd session start`), or on the team's own relay (`abcd session serve`).

Bare `abcd session` prints this help and writes nothing.

#### `abcd session blueprint`

Write the team relay's Render blueprint and Dockerfile, pinned to a release: Writes render.yaml and .abcd/relay/; refuses an edited file or no GitHub origin.

**Usage:** `abcd session blueprint [flags]`

Write the team's own relay deployment into this checkout: render.yaml, a Render
Blueprint declaring one free web service, at the repository's root, where
Render's Deploy button reads it, and .abcd/relay/Dockerfile,
which downloads the released abcd binary for linux/amd64 and checks it against
the SHA-256 that release's checksums.txt publishes. The checksum is read from the
release page when the files are written (the one network read this verb makes,
named on stderr) and pinned in the Dockerfile. The relay serves sessions for this
checkout's origin repository on github.com, named in render.yaml as
ABCD_SESSION_REPOS, a plain value; it refuses a checkout without one.

render.yaml also names, in ABCD_SESSION_ORIGINS, the page origins the relay
admits: each --origin, an https origin followed by the page's base path when it
is served below one, or https://abcdesign.app by default, and,
once repository setup has recorded the team's GitHub App in
.abcd/relay/github-app.json, its public client id, so Render's form asks
only for the secret. A root render.yaml the team wrote is never touched: the
Blueprint then goes to .abcd/relay/render.yaml, picked by its Blueprint Path on
Render's New Blueprint form.

While the live brief session question is unanswered, a person at a terminal is
asked it first, as repository setup asks it.

--relay-origin names the deployed relay's https origin, once Render has given it
one; the verb then also writes .abcd/relay/relays.json, naming it as the relay
this repository trusts, which the session page reads from the repository, and
prints the callback URL the team's GitHub App must list for the relay's sign-in:
the relay's origin followed by /auth/callback.

--release names the release to pin; it defaults to this abcd's own version when
that is a release. A file left exactly as abcd wrote it is replaced; one that was
edited, or that abcd did not write, is never overwritten, and nothing is written.

Exit 2 on a refusal, with nothing written but an answer given to the live brief
session question.

**Flags:**

```
      --origin stringArray    a session page origin the relay admits, as https://host[:port], followed by the page's base path when it is served below one, as https://host/base/ (repeatable; default https://abcdesign.app)
      --relay-origin string   the deployed relay's https origin, as https://host[:port]; given, .abcd/relay/relays.json names it as the relay this repository trusts
      --release string        the abcd release tag to pin, as vMAJOR.MINOR.PATCH (default: this abcd's own version, when it is a release)
```

#### `abcd session page`

Write the brief session's static page and its editor bundle into a directory: Writes only the page's six files; refuses a directory holding anything else.

**Usage:** `abcd session page [flags]`

Write the brief session's page into --out: index.html and an identical 404.html,
session.js, session.css, and the vendored editor bundle with its licences under
vendor/. The files are plain and static, embedded in this binary; serve them
from any static host, such as GitHub Pages, whose 404.html fallback is how
/<owner>/<repo>/brief/ reaches the page. The page connects only to the relay it
finds itself (its own origin, the invite link's, or the first the repository's
relays.json names) and to api.github.com with the person's own token, and it
sends the
person to github.com for sign-in and to open the pre-filled issues a session
sends. It reads nothing from this checkout.

--base-path names the path the site is served under, such as a project's
GitHub Pages address owner.github.io/<repo>/: the page then loads its files from
under it and opens at <base-path>/<owner>/<repo>/brief/. It is plain path
segments, and the root by default.

It writes those six files and nothing else, and removes nothing. --out may be
absent, empty, or a directory an earlier run wrote, whose files are replaced; a
directory holding anything else, a symlink or a file is refused.

Exit 2 on a refusal, with nothing written.

**Flags:**

```
      --base-path string   the path the site is served under, as plain path segments (default "/")
      --out string         the directory to write the page into: absent, empty, or one an earlier run wrote
```

#### `abcd session serve`

Run the brief session relay in the foreground, on loopback by default: Writes nothing; refuses a bad --listen, or no repository to serve beyond loopback.

**Usage:** `abcd session serve [flags]`

Run the brief session relay in the foreground until interrupted. It listens on
this computer alone (127.0.0.1:8787) unless --listen names another address,
which is the second, explicit choice: the team's own relay deployment listens on
0.0.0.0 behind its host's proxy, with --behind-proxy. On a person's own machine,
teammates reach it through Tailscale Serve, on the tailnet only; the start line
prints the command. Never Funnel: a guest outside the tailnet joins through the
team's relay instead.

It serves sessions only for the repositories it is given: each --repo owner/name,
every repository of each --owner, and each entry of ABCD_SESSION_REPOS, a
comma list of either. Nobody signs in against, or hosts, any other. Listening
beyond this computer it refuses to start without one; on loopback it serves this
checkout's origin repository, or any repository outside a GitHub checkout.

It serves the session WebSocket at /session, the sign-in's callback at
/auth/callback (the callback URL the team's GitHub App lists) and its exchange
at /auth/token, the GitHub App's public client id at /config and a health check
at /healthz. It admits a browser only from https://abcdesign.app or a loopback
page, or, when --origin is given, from exactly the origins it names, and otherwise, when
ABCD_SESSION_ORIGINS is set, from exactly the origins that comma list names.
An entry for a page served below a base path names it, as abcd session page
--base-path wrote it (https://host/base/); the callback forwards a sign-in only
to the page's own base path, the root for an entry that names none.
Sign-in goes through the team's GitHub App only, and nobody pastes a token: the
relay takes only a GitHub App user access token. Its client id is read from
--client-id or ABCD_SESSION_GITHUB_CLIENT_ID, and its secret from
ABCD_SESSION_GITHUB_CLIENT_SECRET; with both, members sign in with GitHub's web
flow. Without both, sign-in is not offered and only guests can join: GitHub's
device flow, which needs no secret, belongs to abcd session start alone, whose
relay serves its own session page.
ABCD_SESSION_GITHUB_APP_TYPE set to anything but github-app is refused: the
relay takes no OAuth app.

Exit 2 on a refusal, with nothing started.

**Flags:**

```
      --behind-proxy         trust the last X-Forwarded-For entry as the client's address; only for the team relay behind its host's proxy
      --client-id string     the team's GitHub sign-in app's public client id (default: ABCD_SESSION_GITHUB_CLIENT_ID)
      --listen string        the address to listen on: an IP address (or localhost) and a port; anything but loopback is listening beyond this computer (default "127.0.0.1:8787")
      --origin stringArray   a page origin to admit, as scheme://host[:port], followed by the page's base path when it is served below one, as https://host/base/ (repeatable; also ABCD_SESSION_ORIGINS); given, it replaces the default of https://abcdesign.app and loopback pages
      --owner stringArray    a GitHub user or organisation whose every repository to serve sessions for (repeatable)
      --repo stringArray     a repository to serve sessions for, as owner/name (repeatable; also ABCD_SESSION_REPOS)
```

#### `abcd session setup`

Set up live brief sessions with the team's own GitHub sign-in app: Writes its client id, the answer and the blueprint; refuses no GitHub origin or no answer.

**Usage:** `abcd session setup [flags]`

Set up live brief sessions for this project, the step repository setup asks
about (Set up live brief sessions? Where may sessions run?). It runs by hand at any
time, a no at repository setup included. Where sessions may run comes from
--where, else from .abcd/config.json (sessions.live), else, at a terminal, from
the question; the answer is recorded there.

It registers the team's own GitHub sign-in app through GitHub's App manifest
flow: it prints an address on this computer whose page opens GitHub with the app
filled in (Contents and Pull requests read and write, Metadata read, no
webhook), and the person clicks Create GitHub App. It keeps only the app's public
client id, in .abcd/relay/github-app.json; the client secret, the webhook
secret and the private key GitHub hands back are never written or shown. An app
already recorded is kept, and setup says to remove the session page's own
address from its callback URLs if it is listed, as an earlier setup had it.

It then says what is left, with GitHub's own pages: installing the app on the
repository; for local sessions, ticking Enable Device Flow on the app's settings
page, which a manifest cannot do; for the cloud only, leaving it off. For the
cloud it writes the relay's blueprint (as abcd session blueprint does) and gives
Render's Deploy button, whose form asks for the client secret, which the person
generates on the app's settings page and pastes straight in. --relay-origin
records the deployed relay's address in .abcd/relay/relays.json and names the
callback URL the app must list, the relay's origin followed by /auth/callback;
given before the app is created, the manifest sets it.

It asks api.github.com whether the owner is an organisation, and converts the
app GitHub created; for the cloud it reads the release's checksums. It waits up
to an hour for the app to be created. Where sessions may run is recorded once
the app is. Exit 2 on a refusal before then, with nothing written; a blueprint
that cannot be written afterwards exits 2 with the app and the answer kept.

**Flags:**

```
      --relay-origin string   the deployed relay's https origin, once Render shows it, as https://host[:port]; recorded in .abcd/relay/relays.json
      --release string        the abcd release the cloud relay pins, as vMAJOR.MINOR.PATCH (default: this abcd's own version, when it is a release)
      --where string          where sessions may run: local, cloud or both (default: the answer recorded in .abcd/config.json)
```

#### `abcd session start`

Start a live brief session on this computer, over your tailnet: Writes only an answer it asks; refuses no recorded GitHub App, no Tailscale or no GitHub origin.

**Usage:** `abcd session start [flags]`

Start a live brief session on this computer, for a project whose brief should
not leave the team's tailnet. It runs the session relay on loopback and serves the
session page from it, so nothing goes to abcdesign.app, and prints the one
Tailscale step that shares it on your tailnet and the link to open.

It serves sessions for this checkout's origin repository on github.com. Team
members sign in with GitHub's device flow: the page shows a short code to confirm
on github.com, so no secret sits on this computer. The GitHub App's public client
id comes from --client-id, ABCD_SESSION_GITHUB_CLIENT_ID, or
.abcd/relay/github-app.json, which repository setup writes; without
one it refuses, since nobody could sign in, and a person at a terminal is first
asked the live brief session question while it is unanswered. Anyone else joins
as a guest with a
name, and suggests changes.

It asks Tailscale for this computer's tailnet name and changes nothing in
Tailscale. It answers only that name and its own loopback address, as hosts and
as page origins. People outside your tailnet join as guests once you share this
computer with them in Tailscale. Never Funnel.

It runs in the foreground until interrupted; every session ends with it.
Exit 2 on a refusal, with nothing started.

**Flags:**

```
      --client-id string   the team's GitHub App's public client id (default: ABCD_SESSION_GITHUB_CLIENT_ID, then .abcd/relay/github-app.json)
      --port int           the port on this computer to listen on (0 lets the system choose) (default 8787)
```

### `abcd site`

Report what the website declares and what was built: Writes nothing; refuses any argument.

**Usage:** `abcd site [flags]`

**Flags:**

```
      --out string   output directory to report on (default "site")
```

#### `abcd site build`

Render the website into the output directory: Writes there, plus a missing label into site-src/ui.json; refuses a non-empty directory it did not write.

**Usage:** `abcd site build [flags]`

**Flags:**

```
      --base-path string   path the site is served below on its host, such as /widgets/ for a project's GitHub Pages address; every root-absolute link is placed under it (default "/")
      --commit string      commit for the footer and the build stamp (default: git HEAD)
      --date string        date for the build stamp (default: the newest release's date)
      --out string         directory to render into (default "site")
      --preview            stamp the build as unreleased at this commit, for a preview deployment of an untagged tree
      --project            build a project site, every page built from what abcd writes to the repository and the interface words, styles and scripts taken from the binary; .abcd/site.json then holds the site's settings only
      --version string     version for the footer and the build stamp (default: the newest dated CHANGELOG heading)
```

#### `abcd site setup`

Take the website from this checkout to a live address: Writes its files, and the forge and host changes once confirmed; refuses a folder abcd does not manage.

**Usage:** `abcd site setup [flags]`

**Flags:**

```
      --confirm            replace a workflow or host configuration that differs from what setup writes
      --domain string      custom domain to route to the host when the composition names none
      --name string        host name when the composition names none (default: the repository's name)
      --project            set up a project site; where .abcd/site.json is a composition, its settings and workflow go beside it, in .abcd/project-site.json and .github/workflows/project-site.yml, and the composed site is left as it is
      --provider string    hosting provider when the composition names none: cloudflare or github-pages (default cloudflare); github-pages asks whether to switch the project site on
      --replace-existing   publish over a site the host already serves for this repository without asking; with --yes and no --replace-existing, setup refuses when such a site exists
      --yes                confirm the forge and host changes without being asked (never the install of a missing gh, nor publishing over a site already live, which takes --replace-existing); without it an unanswered run declines them
```

### `abcd spec`

Render the spec store's status: Writes nothing; refuses outside a git checkout.

**Usage:** `abcd spec`

#### `abcd spec close`

Close a spec, and ship its intent when no open spec names it: Writes the moves to closed/ and shipped/; refuses to ship an intent with no impact.

**Usage:** `abcd spec close <spc-N> [flags]`

Moves the spec to closed/ and, when no open spec still names its intent, moves the intent to shipped/.

The close that ships an intent also makes its fidelity review owed: it mints an OWED receipt (rcp-…), parks an `<!-- abcd-review: OWED receipt=rcp-… -->` marker in the intent's Audit Notes, and writes the review request to `.abcd/.work.local/reviews/<rcp>.request.md`, the input `abcd intent audit ingest` answers. A failed emit is a warning on stderr; the intent ships regardless.

In the repository whose brief describes the binary, a close that ships an intent first runs the doc-fidelity gate (`abcd docs fidelity`): a surface no brief chapter names, a missing or stale docs review, or a confirmed false sentence refuses the close, and nothing moves. A close that ships no intent, a --remainder close included, still refuses a surface no brief chapter names, and needs no docs review.

**Flags:**

```
      --impact string            product impact to stamp on an intent that declares none: additive|breaking|fix (an intent may not be internal); accepted only at the close that ships the intent
      --production-mode string   how this record's text was produced: hand-written|dictated-and-formatted|scribe-transcribed (default: the repo's declared mode, else hand-written)
      --remainder string         kebab-case slug of a follow-on spec to mint for what this spec did not deliver, attached to the same intent (which then stays planned); it carries the steps not marked landed
```

**Example:**

```
abcd spec close spc-2609010000000001
```

### `abcd status`

List everyone's announcements, reservations and releases being cut: Writes the fetched status branches and reservations; refuses outside a git checkout.

**Usage:** `abcd status`

List everyone's status on the shared remote: the announcements every session
posted (abcd announce), newest first, each with its sender, kind, item, the
time sent and how long it still stands, then who holds which reservation and
each release being cut, which holds every other session's merge, with a live
drain lane's stage and each holder's hand-backs from the last day.

It reads the remote once: it lists the status branches on origin (git
ls-remote), then fetches, in one command, the reservations with origin's
release tags, the first 500 status branches whose names are holder ids or
GitHub usernames in lower case (the names before the holder id), and
origin's default branch, and stamps when in
the local tier. A branch under abcd-status/ by any other name is counted,
never named, and not fetched; branches past the 500 are counted and not
fetched. Before the fetch, this checkout's copy of each status branch that
is not among the names it fetches is deleted, so a branch deleted on
origin, one whose name is not read and one past the 500 leave nothing to
read; a copy that cannot be deleted is named, and the fetch goes on. Then
it asks the forge (gh api, the repository's activity record) who pushed
each standing announcement it has not asked about yet, on at most ten
branches named by a username, the one waiting longest first: a sender is
verified when the forge names the branch's owner, doubtful when it names
someone else, and claimed when the forge cannot say or an app pushed it. A
branch named by a holder id names no account the forge's record could
match, so it is not asked about and its senders stay claimed.

An announcement stands for its life from when this checkout first fetched it,
not by the sender's clock. One whose sender is not its branch's owner, one
that does not read as an announcement (never shown but by its branch and the
reason), and a branch that was rewritten, passed a merge or gained more than
one read covers are marked doubtful, and every other branch is still read.
A running session sees each new line once, at its next prompt, in a
block headed STATUS of at most ten lines and one more that counts the
rest, read from disk alone.
An announcement informs and grants nothing.

When ~/.abcd.noindex/holder-ids is there and its guarded read refuses it, no
declared id is read as yours, and one line on stderr names the class of the
refusal, never the file's contents (holder_ids_refused in --json).

When your holder id is set or kept but refused (ABCD_HOLDER_ID set to
anything but one holder id, or ~/.abcd.noindex/holder-id refused by its
guarded read), no hold or withdrawal under it is read as yours, and one line
on stderr names the class of the refusal, never the value or the file's
contents (holder_id_refused in --json).

When the fetch fails, the status is listed as last fetched, with that view's
age and a line saying it is unread since then and why. Exit 0 when the fetch
succeeded and with no remote named origin; exit 1 when it failed, when
what it fetched could not be read, or in a checkout without its local
tier; exit 2 outside a git checkout or with an operand.

### `abcd statusline`

Render abcd's status-line row from the host's payload on stdin: Writes nothing; never refuses.

**Usage:** `abcd statusline`

Render abcd's row for the host harness's status line.

The harness runs this on every status refresh, with its JSON status
payload on stdin, and shows what it prints. In a checkout abcd manages the
row is abcd's own: the presence badge first — `abcd-managed`, `waiting on
the technical facilitator` or `waiting on the product thinker`, from the state
`abcd mode` stores, its colour ending at the badge — then the session's
name when the harness supplies one, the repository name, the branch,
`autonomous merging` while the repository's facilitator.mode is auto (read
as the merge gate reads it: the default branch's committed
`.abcd/config.json` and the machine layer), the model, the context
percentage, the five-hour and seven-day usage percentages, and the record's
counts of intents not yet shipped and open issues. Each element after the
session name is switchable in
`~/.abcd.noindex/statusline.json`; a payload field the harness did not
supply drops its element with no placeholder.

Outside a managed checkout, or with `disabled` set in the user-level
setting, it runs the status command recorded there at install time with the
same stdin and passes its output and exit code through unchanged, so the
user's own line is untouched everywhere abcd does not manage. With none
recorded it prints nothing and exits 0.

The checkout is resolved from the payload's `cwd` (falling back to the
working directory). Empty stdin is an empty payload. It writes one file
only: when it renders abcd's own row for a payload carrying the session id
and the context percentage, it records that percentage and the time in the
session's fill file, `~/.abcd.noindex/fill/<sha256 of the session id>.json`,
where abcd's prompt hook reads how full the session is. It writes there only
when that folder already exists (abcd's session-start hook makes it), creates
no folder, and writes nothing else, nor anything at all when it runs the
recorded command. Nothing here prompts, reads a terminal, or touches the
network.

It is time-bounded, because the harness waits on it at every refresh: abcd's
own work stops at 500ms and the recorded status command at 5s.
At either bound it prints what it has (a row without the element that did
not answer, the command's output so far, or nothing), says why on stderr and
exits 0. With --json the row is emitted as its ordered elements, each with a
key, a rendered and a plain form.

### `abcd update`

Swap the PATH-installed binary for a verified release, or with --check only compare: Writes the swapped binary; refuses a binary it cannot prove is abcd's.

**Usage:** `abcd update [tag] [flags]`

Fetches the named release (or resolves the latest, naming it before acting),
verifies the platform binary against the same release's checksums.txt and
against the SLSA build provenance the release workflow signed for it
(fetched from GitHub's attestations API and checked against the Sigstore
trusted root, pinned to intentdriven/abcd's release.yml on main and to
the commit the release tag names), and swaps the
PATH-installed copy atomically. A binary whose provenance cannot be
verified, offline included, is refused with the way to install it by hand;
nothing is swapped unverified. The verb is the only ask: abcd
never checks for or applies updates on its own (adr-38). A plugin-root
binary, the dev shim, and package-manager installs are refused with the
command that owns them. The file being replaced must be provably abcd's:
the binary running the command, an install ~/.abcd.noindex/path-entry records, or
a digest a published release still names. Anything else is refused with a
remedy that reinstalls over it — never one that deletes it.

The release it installs or verifies is recorded as this machine's newest
(~/.abcd.noindex/release-mark). A bare update whose latest release is older
than that is refused, since the newer one may have been withdrawn; naming
the older tag installs it and records it, which is the one way back.

With --check it only asks: it fetches the latest release's tag once, says
whether this binary is behind and which command takes the update for this
install's shape, and swaps nothing.

**Flags:**

```
      --check   fetch the latest release once and compare it with this binary, swapping nothing (it reaches the network only when invoked; abcd never fetches implicitly — adr-38); names its source and the command that takes the update
      --yes     skip the TTY confirmation of a freshly resolved tag
```

#### `abcd update news`

Say what changed since the update, and offer the setup that waits: Writes only an answer or --seen, to ~/.abcd.noindex/; refuses --answer with --full or --seen.

**Usage:** `abcd update news [flags]`

After an abcd update, print what the agent relays at the start of its first reply: one line per release this computer has not been shown, saying how many changes it made and which need the person to act, and, where the update brings this repository setup it never answered, the offer to run setup again. It prints nothing when there is nothing to say. --full prints every change of the releases since the last update, those that need action first, each with the record it cites, and what waits here. Neither writes anything. Only a person's reply is recorded: --answer yes|not-now records the answer to the offer for this repository and release, once, and --seen records that the news was read where no offer was made, both in abcd's home folder. On yes, run abcd ahoy install --only-waiting. The text comes only from the binary's own digest and checked release numbers, and nothing is fetched.

**Flags:**

```
      --answer string   record the person's reply to the offer, yes or not-now, once for this repository and release; run it only with their reply
      --full            print the full summary of the releases since the last update and what waits here; writes nothing
      --seen            record that the person read the news where no offer was made; run it only after they were shown it
```