@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/README.md

@@ -59,6 +59,8 @@ The first of these names the round's brief; it is never guessed ([ADR-0004](http
 2. `SPEC_BRIEF`;
 3. the branch name: `brief/{id}`, `brief-{id}`, `*/brief/{id}`, `*/brief-{id}`.
 
+The branch is read as HEAD names it, `refs/heads/` taken off, so a tag of the same name does not hide it: `claude/brief-042-x` beside a tag `claude/brief-042-x` names brief 042, where git's short name for it, `heads/claude/brief-042-x`, named none.
+
 CI checks out a commit on no branch, so on a detached HEAD the branch is the one the forge's CI names, the first of:
 
 | Variable | Set by |
@@ -77,6 +79,47 @@ A name that names no brief is not passed over for the next ([ADR-0004](https://g
 - An id spec-brief does not know, or one it has archived, is not passed over either, whichever of the three names it: a command that acts on the brief stops with exit 2, and `doctor` says so in its report. The line says what named it: `the flag names brief 999, and spec-brief knows no such brief`, or `the environment`, `the branch`, or `the argument` for `context 999`.
 - `context`, `rulings`, `audit` and `probe` take the brief's id as their argument as well, which comes before all three. The argument beside `--brief` is refused, whatever the two hold: one of them would not be read.
 
+### Worktrees, and the branches an app makes
+
+An app that makes a branch for a session puts a name of its own before the brief's, and the default `*/brief-{id}` reads it: `claude/brief-042-rotate-tokens` is brief 042. A `*` stands for a run of characters other than `/`, so `claude/team/brief-042-x` names no brief under the defaults, and does with a template of one star more. `branches` replaces the defaults, so name them beside it:
+
+```json
+{ "branches": ["brief/{id}", "brief-{id}", "*/brief/{id}", "*/brief-{id}", "*/*/brief-{id}"] }
+```
+
+- `claude --worktree <name>` makes its worktree under `.claude/worktrees/<name>/`, on a new branch named `worktree-<name>` ([Claude Code's worktrees page](https://code.claude.com/docs/en/worktrees), *Start Claude in a worktree*). No default reads it: `worktree-brief-042-x` names no brief. With `worktree-brief-{id}` among the `branches`, `claude --worktree brief-042-x` works on brief 042.
+- A branch that names an id spec-brief does not list, as `claude/brief-999-x`, is not passed over for the next: every write of the session is held until the brief or the branch is mended. Where Claude Code starts the hook as a session starts, the entry `init` and the plugin write under `SessionStart`, the session is told so before its first write.
+- A tag of the same name as the branch does not hide it: the branch is read as HEAD names it.
+- In a worktree session started from the desktop app, and after Claude enters a worktree mid-session, Claude Code starts the hook with `${CLAUDE_PROJECT_DIR}` at the main checkout and hands it the worktree as the question's `cwd` (the worktrees page, *What worktrees share with the main checkout*; [the hooks reference](https://code.claude.com/docs/en/hooks), *Reference scripts by path*). The worktree's branch names the brief, and a worktree with no install of its own is checked with the project's: an Edit of a file brief 042 protects, in a worktree on `claude/brief-042-x` of a main checkout on `main`, is refused.
+- A path is decided by the work tree that holds it, where that is a work tree of the same repository, whichever `cwd` is in: an Edit of a file brief 042 protects, in a worktree on `claude/brief-042-x`, is refused from a session at the main checkout and from one in another worktree, inside the project or beside it. A path in no work tree of the repository is decided as before ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A nested repository, a submodule or a clone inside the tree, is another repository, and a path in it is decided as before, by the work tree of the project's repository that holds it, under the path it has there. What that lets through: a file the nested repository's own brief protects is outside the project's scope, warned of after the write and not refused, and one the project's brief does not reach passes with no word. That repository is guarded by its own hook, in its own sessions.
+- Where `${CLAUDE_PROJECT_DIR}` points in a session started with `claude --worktree` is on no page of Claude Code's: the hooks reference has it the project root where the session started, the worktrees page has the flag start Claude in the worktree, and a worktree a fresh checkout to install dependencies into, and says where it points only for a session started from the desktop app. Where it is the worktree, the next point holds.
+- git's pre-commit hook in such a worktree runs the main work tree's install where the worktree has none, and refuses the same file at the commit. So does every other command, `guard`, `context`, `audit`, `probe` and the rest, where each said that spec-brief is not installed here. A hook an earlier release wrote reads the worktree's own install alone: take it away and run `init --git-hook --write`.
+- Where `${CLAUDE_PROJECT_DIR}` is the worktree itself, the project root a session started in, the hook's script is looked for in the worktree's own `node_modules`. A worktree is a fresh checkout (the worktrees page, *Set up the worktree environment*), and where it has no install, node cannot find the script and exits 1: Claude Code reads that as a hook's non-blocking error, and the write goes ahead (the hooks reference, *Exit code output*). Install in the worktree before such a session writes. From Claude Code 2.1.295, `"onFailure": "block"` on the hook's entry holds the write instead: `init --block-on-failure` writes it on init's PreToolUse, PostToolUse and SessionStart entries, and the plugin does not carry it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+
+### Sessions that write through a shell, with no rulings
+
+Claude Code starts the guard for `Edit`, `Write`, `MultiEdit` and `NotebookEdit`, the matcher `init` and the plugin write. A `Bash` or `PowerShell` call takes a command, not a file, and the guard is not asked about what it writes. With brief 042 covering `src/**` and protecting `src/db/schema.ts`, and `notes.md` outside its scope, each layer was run:
+
+| Layer | Catches | Lets through |
+| --- | --- | --- |
+| The guard, before an Edit | an Edit of `src/db/schema.ts`: refused, with the next step | an Edit of `notes.md` under `outOfScope: "warn"`; every shell command |
+| The guard, after an Edit | an Edit of `notes.md`: a warning to Claude | every shell command |
+| The hook as a session starts | a configuration that does not load, an id spec-brief does not list, spec-brief missing or too old where a brief is named: one line, to the person and to Claude | everything: it holds nothing, and the event cannot block |
+| The report at the end of a turn, `"turnReport": true` | every path the work tree holds changed, a shell's writes among them: `src/db/schema.ts` reported as protected and `notes.md` as outside the scope, to Claude as the next turn begins | a change made and undone, or committed, within the turn; an ignored file; a turn an interrupt or an API error ends; and it refuses nothing, the write having happened |
+| git's pre-commit hook, `init --git-hook` | every staged path, a shell's writes among them: `src/db/schema.ts` refused; `notes.md` warned of under `warn`, refused under `ask` and `deny` | `git commit --no-verify`, which skips the hook ([githooks](https://git-scm.com/docs/githooks), *pre-commit*) |
+| `spec-harness audit` | the round's commits from the base: `src/db/schema.ts` changed, an error, and `notes.md`, a warning; exit 1 | what the brief, as it stands at the end, allows |
+| `spec-brief archive --strict --base <branch>` | the same, both errors: the brief is not archived | the same |
+
+What every layer lets through:
+
+- **An edit of the brief.** Its file is always writable, and the audit and the archive read the brief as it stands at the end: a round that adds `notes.md` to `affectedFiles` and takes `src/db/schema.ts` out of `protectedFiles` is archived with `--strict`. The change is in the brief's diff, for the person who approved it to read.
+- **A shell's write**, until the commit; with `turnReport` on, it is reported at the end of the turn, and not refused.
+- **`git commit --no-verify`**, until the audit.
+- **A Claude Code mod** that handles `tool.check` can approve a call a `PreToolUse` hook blocked, unless the hook is in managed settings ([Claude Code's permissions page](https://code.claude.com/docs/en/permissions), *Precedence among rules, hooks, and mods*).
+
+Two more layers were weighed and not built. A `PostToolUse` hook for the shell tools: every shell command would pay for it, it is easy to get around, and the audit stays the gate; the report at the end of a turn is paid once a turn, in the background, and reads the work tree rather than a command ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md), amended 2026-09-30). And `"protected": "ask"`: a protected file passes the guard only by a ruling whose commit a person signed, which the audit and the archive check again ([ADR-0006](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0006-a-ruling-is-a-signed-commit.md)), and an approval given in the session is kept nowhere they read.
+
 ## Commands
 
 In the order a round meets them; `init` and `doctor` set a repository up and check it.
@@ -132,10 +175,18 @@ May the round write this?
 Paths are compared as the filesystem spells them, links resolved and case corrected, so `SRC/db/schema.ts` does not walk past a protection on `src/db/schema.ts` on Windows.
 
 - `spec-harness hook claude` answers Claude Code's PreToolUse and PostToolUse hooks: a refusal before the write, with the reason and the next step; a warning after a write outside the scope. It never answers `allow`, which would skip the person's own permission prompt. When it cannot answer - the configuration does not load, the briefs cannot be read, the harness meets an error it did not expect - it exits 2, and before a write Claude Code then holds the write.
+- While `.spec-harness.json` does not load, a write to that file itself is let through, so that a session can mend it: no decision, so the person's own permission prompt stands, and the line that says why every other write is held, to the person as `systemMessage` and to Claude as `additionalContext`, as `.spec-harness.json: unknown key "outofscope"; ..., so every other write is held until it loads; this write, to /work/app/.spec-harness.json itself, is not checked`. The write is to the file and nothing else as the hook reads a path and as the disk does: a file that stands under that name alone, not a link to one and with no second name, named by every path of the call. A file of the same name elsewhere, a link to it, and the configuration of another work tree than the one that does not load are held as every other write is. After the write the hook loads the file again, and says, exit 2, where it still does not load. While it does not load nothing of it is read, so a brief that protects the file, or an `outOfScope` it sets, does not hold this write; the audit and spec-brief's archive still measure the round's change to it ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A write outside every work tree of the repository is decided as one outside the repository is, whatever holds the writes inside: a brief that is archived, or that spec-brief does not list, whichever names it, and a configuration that does not load. It passes with no word, before the write and after it, and spec-brief is not asked about it; `guard` says it is outside the repository. The work trees are the main one and every linked worktree, as the files git keeps under its common directory name them, and a file of a linked worktree is decided as any other inside, by the worktree that holds it. Where they cannot all be named, a git directory kept apart, an entry git keeps that cannot be read, or a `core.worktree` where the configuration does not load, the write is held as before, and so is a path with a `..` in it, which the hook reads before its links where Linux and macOS write it after ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- In a worktree, a write is decided by the worktree's brief. Claude Code names the project a session started in, and hands the hook the directory Claude works in as the question's `cwd`: in a worktree session started from the desktop app, and after Claude enters a worktree, the first is the main checkout and the second the worktree. Where `cwd` is in another work tree of the same repository, that work tree's branch names the brief, its briefs and configuration are read, and its siblings are looked for in its own `node_modules` and then the project's, so a worktree with no install is checked with the project's. A path it does not hold, and every path where `cwd` is in another repository or in none, is decided by the project as before ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- After a write the hook answers from what it decided before it, for the same call: the run before keeps the warnings it would give under the git common directory, in `spec-harness/calls/`, named by the question's `session_id` and `tool_use_id`, and the run after takes them away and answers with no process started. A refused call keeps nothing, nor one that writes `.spec-harness.json`, spec-brief's configuration, the brief or a file beside it, which are decided again after the write; what no run after a write reads is removed after a day. Under `outOfScope: "ask"` or `"deny"` no write is warned of, and the run after one says nothing with no process started ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- On a brief's branch the hook asks spec-brief for the briefs, which on Windows is most of what a write waits on. Within a session it keeps spec-brief's answer, where spec-brief's `list` names every input it was read from (`inputs`), under the git common directory in `spec-harness/answers/`, by the work tree, the session, spec-brief's script and version, the command line, and the variables git and Node read; and it gives the answer again while each file on the list has the digest listed, or is still not there, each directory holds the files listed, or is still not there where it was listed as not there, and the git index and ignore files read as listed, with no process started. Anything else starts spec-brief as before: an input that is missing, unreadable or reads otherwise, `keep` not `true`, an answer with no `inputs`, a command `tools` names, and, where the list names what git read, `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE` or `GIT_COMMON_DIR` set. What is kept is removed after a day; every other command starts spec-brief every time ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- As a session starts, resumes, is cleared, compacted or forked, `hook claude` answers Claude Code's SessionStart with what would hold every write of the session, in one line, to the person as `systemMessage` and to Claude as `additionalContext`: a configuration that does not load, a brief the line, `SPEC_BRIEF` or the branch names that spec-brief does not list, spec-brief missing or too old where a brief is named, and what is wrong with the hook's own line. Nothing is said where all is well, and it exits 0 whatever it finds: the event cannot block, and the session's start is not to be stopped by it ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- With `"turnReport": true` in `.spec-harness.json`, `hook claude` answers Claude Code's `Stop`, which it runs as its main agent finishes a turn: with one `git --no-optional-locks status`, every path the work tree holds changed, a shell's writes among them, that the brief protects or that is outside its scope under the `outOfScope` in force, in the words a write of each is given, twenty by name and how many more, as one `systemMessage`; or nothing. It exits 0 and never has Claude go on. `init` writes the entry with `"async": true`, so the turn waits on none of it and Claude Code hands the report to Claude as the next turn begins; without `async` the person sees it as the turn ends, Claude does not, and the end of the turn waits for it. No ruling is read: a protected file a signed ruling allows is reported, and the audit reads the ruling. The plugin brings no such entry; with it on, `init` says the entry to add ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md), [ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+- A process the hook asks a question of, git or spec-brief's list of the briefs, is stopped after 20 seconds: Claude Code cancels the hook at the 60 seconds `init` and the plugin give its entry, and before a write lets the write go ahead. At the limit the hook says `cannot check this write: spec-brief did not answer within 20 seconds, and was stopped` and exits 2, which holds the write. Every command gives a question the same time, and a round's work, a diff, a probe's worktree, a sibling's check, ten minutes ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
 - `spec-harness hook git` is a pre-commit hook for any agent or none. `init --git-hook` writes it; in a hook of your own it is the line `node node_modules/@descent-vtt/spec-harness/bin/spec-harness.js hook git`.
 - `hook claude` passes over whatever else is on its line that it does not read, as every release has, where every other command [refuses it](#an-input-that-names-nothing): its line is in settings a later release cannot rewrite, and exit 2 from it holds every write.
-- A `--root` on the hook's line that is a file, or is not there, is a guard that was set up and is off: `hook claude` says so on stderr and exits 1, which Claude Code shows as a hook error while the write goes on. It refuses nothing for it. No release wrote a `--root` there; without one the hook reads the project Claude Code names, then the session's directory, and outside a git work tree it has nothing to guard and says nothing.
-- A line the hook cannot read - an option no command has, an option left without its value, a `--format` or an `--at` that is none - is said the same way: one line on stderr, exit 1, and no write held for it. Exit 2 from `hook claude` is for a write it could not check, never for what is wrong with its own line. `hook git` stops the commit on such a line, exit 2, where a person reads why.
+- A `--root` on the hook's line that is a file, or is not there, is a guard that was set up and is off: `hook claude` says so in one line to the person, as `systemMessage`, and exits 0, and the write goes on. It refuses nothing for it. No release wrote a `--root` there; without one the hook reads the project Claude Code names, then the session's directory, and outside a git work tree it has nothing to guard and says nothing.
+- A line the hook cannot read - an option no command has, an option left without its value, a `--format` or an `--at` that is none, two values for an option that takes one, `--help` beside `--version` - is said the same way: one line to the person, exit 0, and no write held for it. So is a question the hook cannot read, one that is not JSON or names no event. Exit 2 from `hook claude` is for a write it could not check, never for what is wrong with its own line; and no answer of the hook's is exit 1, which Claude Code counts as a hook that failed, so that `"onFailure": "block"` holds a write only for a hook that did not run ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)). `hook git` stops the commit on such a line, exit 2, where a person reads why.
 
 A guard is a guardrail - an agent that writes through a shell passes it - so the audit and spec-brief's archive are the gates ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
 
@@ -156,6 +207,8 @@ git commit -S -m "ruling R-012-1: allow" -- briefs/012_rotate-tokens.md
 
 A memo is what a person rules on, so none is written with a part that says nothing: a path, the reason, a recommendation or an option that is empty is [refused](#an-input-that-names-nothing), by `escalate` and by the server's `request_escalation` alike. An option is `"<label>: <cost>"`: the label names the choice and may not be empty, and the cost may be left out, the memo then giving the choice alone.
 
+Requests wait under git's directory, in `spec-harness/escalations` (ADR-0003). Where something that is no directory stands at either path, `escalate` and `rule` say which, exit 2, in a line: `.git/spec-harness is not a directory, where spec-harness keeps its state in one: move it away, and run the command again`.
+
 `escalate --list` prints every request that waits, whichever round raised it, and `escalate --show <id>` one memo. Neither raises a request, so neither reads `--path`, `--reason`, `--option`, `--recommend` or `--brief`, and either beside one of them is [refused](#an-input-that-names-nothing): the request was never raised, and the list looked like an answer to it.
 
 A ruling is a row in the brief's `## Rulings` table. It **counts** when the commit that last changed the row is signed by a key the **base branch's** `.github/allowed_signers` lists. The file is `rulings.allowedSigners` in `.spec-harness.json`, `.github/allowed_signers` by default.
@@ -323,6 +376,8 @@ Run it in CI: exit 1 when a premise is stale, exit 2 when spec-guard is not ther
 
 `start_round`, `check_path`, `request_escalation`, `audit_round` and `list_rounds` over MCP on stdio, with the four workflow prompts. Both protocol eras are served. The architecture rules themselves stay with spec-guard's server.
 
+- The server is started for the project Claude Code names. `check_path` decides an absolute path by the work tree of the same repository that holds it, as the hook decides a write, and `start_round`, `check_path`, `request_escalation` and `audit_round` read the round, its branch and its brief, in one work tree: the one a `directory` argument names; else the one the client's roots name, where they name exactly one work tree of the repository, asked with `roots/list` where the client declared roots; else the project's. Each says which as `workTree`, and in its text where it is not the project's ([ADR-0008](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0008-one-server-for-rounds.md)).
+
 A tool answers an argument it cannot use with a tool error that names the argument, and writes nothing: one it does not take, one of the wrong type, and one that is given and [names nothing](#an-input-that-names-nothing), such as an empty `brief`.
 
 ### `init`
@@ -340,6 +395,8 @@ Configures the family to agree. It prints the plan, merges into files that exist
   - otherwise the branch `init` runs on when it is `main` or `master`, or the only branch, since a repository made with `git init` and pushed to a remote often records no default;
   - when it cannot tell, it says so and writes none: set `"base"` yourself.
 - **Claude Code**: the guard hooks in `.claude/settings.json` and the MCP server in `.mcp.json`, each run with `node` from the project's `node_modules`. The `npx` entries 0.1 wrote are replaced.
+  - Beside the hook's entries under `PreToolUse` and `PostToolUse`, one under `SessionStart`, with no matcher: every way a session starts. In a file whose two an earlier release wrote, `init --write` adds it by itself; beside a line of the hook a person wrote or changed it adds none.
+  - With `--block-on-failure`, each of its entries before and after a write and as a session starts carries `"onFailure": "block"`, and so do those an earlier run wrote (`update`); the entry at the end of a turn, which runs in the background, is left without it, since the hooks reference gives the field no effect on a `Stop` hook or on one in the background. Claude Code 2.1.295 or later then holds a write where the hook cannot start, as where the project's install is not there, or runs past its timeout, where without the field it lets the write go ahead with a notice. Claude Code's documentation does not say what a release before 2.1.295 does with a key it does not know, and the file is read by every clone's Claude Code, so the field is written only where asked for: ask for it where every Claude Code that reads the file is 2.1.295 or later. The plugin's hooks do not carry it, and a line a person wrote is theirs to give it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
   - These are the ones the [Claude Code plugin](#as-a-claude-code-plugin) brings, so while that plugin is on - `"spec-harness@<marketplace>": true` under `enabledPlugins` in your user, project or local Claude Code settings - `init` writes neither and says why (`skip`).
   - To have its entries instead, which every clone reads, turn the Claude Code plugin off for the project, `claude plugin disable spec-harness@spec-tools --scope local`, and run `init` again.
   - It removes nothing: where the Claude Code plugin is on and a file already holds its entry, it says so (`advise`) and leaves the file alone. So where the hook stands in a settings file of your own, which `init` does not write.
@@ -350,7 +407,7 @@ Configures the family to agree. It prints the plan, merges into files that exist
 - **git's pre-commit hook**, where git runs it from: `core.hooksPath`, relative, absolute or under `~`, and the shared hooks of a linked worktree.
   - It refuses a commit that changes what the active brief protects, for any agent or none, a shell's writes included.
   - With `--git-hook` it is written; without, the plan advises it (`advise`).
-  - It runs `node` and the script in the project's `node_modules`, as the Claude Code hooks do, and no `npx`. git starts a pre-commit hook at the top of the work tree it commits in, so the script is read from there: a linked worktree is guarded by its own install, and so is each repository that shares a hooks directory. Where the install is not there, the hook says so and the commit waits.
+  - It runs `node` and the script in the project's `node_modules`, as the Claude Code hooks do, and no `npx`. git starts a pre-commit hook at the top of the work tree it commits in, so the script is read from there: a linked worktree is guarded by its own install, or, where it has none, by the main work tree's, by its own branch and briefs; each repository that shares a hooks directory is guarded by its own. Where neither has the install, the hook says so and the commit waits. A hook an earlier release wrote reads the work tree's own install alone: take it away and run `init --git-hook --write` for this one.
   - It is a POSIX `sh` script on every platform: Git for Windows runs a hook with the `sh` it ships.
   - A hook that exists is never replaced: `init` says to add the line to it. One that runs spec-harness through `npx`, as `init` wrote it through 0.9.1, keeps working, and `init` names the line that runs it with `node`.
   - Nor is anything else that stands at the hook's path. A directory there is said as [`doctor`](#doctor) says it (`advise`), with `--git-hook` or without, and nothing is written over it.
@@ -367,9 +424,10 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
 - **The siblings**: which are installed, at which versions, and how each is run.
   - A sibling older than this release needs is `outdated`, with the minimum and the command that installs a newer one, and exit 1.
   - A command named under `tools` is run as named, and its version is not checked.
+  - In a linked worktree with no install of its own, the siblings are the main work tree's, as git's hook runs them there, and each such row says whose install it is: `(0.8.0, the install of /work/app: this work tree has none of its own)`. `--format json` has it as `elsewhere`, `null` for a sibling of the work tree's own.
 - **The repository**: its root, the branch, and the brief the flag, `SPEC_BRIEF` or the branch names.
   - A brief no round can work under is said on that line, with why: `brief   none: the flag names brief 999, and spec-brief knows no such brief`. So is one spec-brief has archived, an empty `--brief`, and a spec-brief that could not list the briefs. The guard holds every write while it stands, which is often why `doctor` is being run.
-  - It fails nothing, as a base that names no commit fails nothing: `doctor` exits as it would have. `--format json` has the id as `brief` and the reason as `briefProblem`, `null` where there is none.
+  - Where the branch names it, a brief spec-brief does not know or has archived, the hook holds every write on that branch, and `doctor` exits 1, as for a hook's line that holds every write: `brief   none: the branch names brief 999, and spec-brief knows no such brief`. One the flag or `SPEC_BRIEF` names fails nothing: the flag is the question `doctor` was asked, and the variable `doctor` reads is its own, which need not be the one Claude Code's hook is started with. Nor does a spec-brief that could not list the briefs, which is a sibling's row to judge. A base that names no commit fails nothing either. `--format json` has the id as `brief` and the reason as `briefProblem`, `null` where there is none ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
 - **What a signed ruling needs to count**:
   - the base, and whether `--base`, `.spec-harness.json` or the remote named it;
   - whether the allowed-signers file is on that base;
@@ -379,11 +437,14 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
   - A `cert-authority` line is a certificate authority's key, not a person's, and is left out.
   - A line OpenSSH refuses is named as no signer, with why. Its quotes are read as OpenSSH reads them: in the principals, the first double quote, wherever it opens, is taken out with the next, which ends the field; an option's value is always in double quotes, `\"` a quote inside it. And its options are OpenSSH's: `cert-authority`, `namespaces`, `valid-after` and `valid-before`, separated by commas.
 - **How Claude Code runs the guard**: the Claude Code plugin, with the settings file that turns it on; `init`'s hooks and server; both, which guards every write twice and exits 1, with how to keep one; or neither.
+  - Where a settings file guards writes and none starts the hook as a session starts, a note says so and how to add it, `spec-harness init --write`, and fails nothing. `--format json` has `claudeCode.sessionStart`.
+  - Run in a linked worktree where something wires the guard, a note says which release of spec-harness the hook's line runs, where the main checkout's install and this work tree's are not one: the line names its script under `${CLAUDE_PROJECT_DIR}`, which is this work tree in a session started in it, and the main checkout in a worktree session of the desktop app, where by [Claude Code's worktrees page](https://code.claude.com/docs/en/worktrees) Claude Code reads the hooks from the main checkout's root and points the placeholder at it. Either decides a write by the work tree that holds it, from 0.19.0 on, so the note says which release answers, and fails nothing.
   - `"disableAllHooks": true` in a settings file switches the guard off: by [Claude Code's settings reference](https://code.claude.com/docs/en/settings-reference) it turns off the hooks of the user's, the project's and the local settings and of plugins. `doctor` reads the key from the three files as Claude Code merges them, the last that sets it deciding, names the file that holds it, and exits 1 where there are guard hooks for it to switch off. Where nothing is wired it is a note. Hooks of managed settings, and of a plugin managed settings force on, keep running; `doctor` reads no managed settings and no `--settings`.
   - A hook in Claude Code's settings is the guard by its command, `spec-harness` or its script, and the words `hook claude`, whatever else is on its line. `doctor` reads the line as the hook reads it, through the same code, with the project in place of `${CLAUDE_PROJECT_DIR}`, and says what the hook does with it.
   - Only an entry Claude Code runs as a command is a line of the hook, `"type": "command"`. An entry of another handler type (`http`, `mcp_tool`, `prompt`, `agent`) runs no command, whatever it holds, and is not reported. One with no `type`, or with a word the hooks reference does not list, is *cannot tell*, never fine: the reference requires the field and says nothing of an entry without it; `--strict` fails it.
   - A line that holds more than `init` writes, such as `--root ${CLAUDE_PROJECT_DIR}` or `--brief 012`, is said as it is and fails nothing: `"hook claude --root ${CLAUDE_PROJECT_DIR}" in .claude/settings.json is more than init writes, and guards: the hook reads the line, and its root, /work/app, is a directory`.
   - A line the hook cannot read, and a `--root` that is a file or is not there, are a guard that is off. Each is said in the words the hook itself says before a write, and exits 1.
+  - A line that asks for the help or the version, with `--help`, `--version`, `-h` or `-v`, is a guard that is off as well. The hook prints the help or the version, exit 0, in place of reading its question, and [Claude Code's hooks reference](https://code.claude.com/docs/en/hooks) has what a hook that exits 0 prints go to the debug log: no write is checked, and nothing says so. `doctor` says it and exits 1, whatever else is on the line: `"hook claude --help" in .claude/settings.json: the line asks for the help, which the hook prints, exit 0, in place of checking the write, so the guard is off and no write is checked`. Beside a `--root` that is a file or is not there, it is a line the hook cannot read, which the hook says before a write as it says the root without either.
   - A `--root` that is a directory outside any git work tree is a guard that is off as well, and the one fault the hook says nothing of: it reads a session outside a work tree there, checks no write, and exits 0. `doctor` asks git about the root as the hook does, says so, and exits 1: `"hook claude --root /elsewhere" in .claude/settings.json: --root is "/elsewhere", a directory outside any git work tree, which the hook reads as a session outside one, exit 0 and no word, so the guard is off and no write is checked`.
   - A `--root` in another git work tree than the project's is read by where that work tree is. The hook opens the work tree its root is in and decides by that work tree's briefs, and a file outside it is none of its repository's, which the hook passes with no word. So where that work tree does not hold the project - another repository beside it, or one inside it: a repository of its own, a submodule, a linked worktree - no write to a file of the project is checked. The guard is off, and `doctor` exits 1: `"hook claude --root ../other" in .claude/settings.json: --root is "../other", a directory in /work/other, the work tree of another repository, which does not hold this project: the hook checks a write to a file of that work tree, by its briefs, and passes any other with no word, exit 0, so the guard is off and no write to a file of this project is checked`. Where the work tree holds the project, as a repository the project is nested in does, or the main work tree around a linked one, a write here is checked, by that work tree's briefs and its branch and under the path the file has there: `doctor` says whose briefs they are and fails nothing. A work tree of the project's own repository, linked or main, is named `another work tree of this repository`, and is read by the same rule: a linked worktree beside the project holds none of its files.
   - A line that names a brief which is not one, as `--brief 404` does where spec-brief knows no brief 404 or has archived it, holds every write: the hook exits 2 before each until the line is mended. `doctor` asks spec-brief about the name as the hook does, in the work tree the line's root is in, says it in the words the hook holds the write with, and exits 1: `"hook claude --brief 404" in .claude/settings.json: the flag names brief 404, and spec-brief knows no such brief, so the hook holds every write until the line is mended: name a brief spec-brief lists, or take --brief off the line`.
@@ -393,9 +454,10 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
     - Those three are the tools a Claude Code from 2.1.139 on writes a file with, by its [tools reference](https://code.claude.com/docs/en/tools-reference). The hook also reads the file a `MultiEdit` names, a tool no release from 2.0.0 on declares, and `init`'s matcher keeps the name; `doctor` says of no line that it leaves `MultiEdit` unchecked, and a line under `Edit|Write|NotebookEdit` is said with nothing more.
     - An `if` on the entry has Claude Code start it only for the tool calls its rule matches. The rule is not read, so which writes the line is asked on is *cannot tell*, never fine; `--strict` fails it. So is a matcher that is neither text nor an array, or is no pattern, or is a pattern that takes more than a tenth of a second to test against the three names: one can be written that never finishes, and `doctor` and `init` come back all the same.
     - A matcher that lists names with a `,` is read as the Claude Code on `PATH` reads it. By [Claude Code's page on debugging a configuration](https://code.claude.com/docs/en/debug-your-config), a comma separates names as a `|` does from 2.1.191 on; before it, a comma was read as part of a pattern, and the matcher matched no tool. So under 2.1.139 to 2.1.190 a line under `Edit, Write` is waited on before no write and is not the guard: `doctor` says it with the release and what the matcher is from 2.1.191 on, `(under PreToolUse it has the matcher "Edit, Write", which Claude Code 2.1.190 reads as a pattern that matches no tool: a comma separates names from 2.1.191 on, where the matcher is Edit and Write)`, and fails nothing for it, as for any line that is no guard. Where the release cannot be told, which writes the line is started for is *cannot tell*, never fine; `--strict` fails it. So is a matcher with a `,` and a `|` under an older release, where read as a pattern it would match a tool, as `Edit|Write, NotebookEdit` would `Edit`: the page has such a matcher never match, and has the comma read as part of a pattern, and for that matcher the two disagree. A matcher with no comma, the one `init` writes among them, is read the same under every release.
-    - A matcher that is an array, `["Edit", "Write"]`, is by the same page an entry Claude Code lists as an invalid setting, and no hook under it is started. Where one stands under `PreToolUse` or `PermissionRequest`, in an entry of the hook's or of any other program's, Claude Code loads none of that settings file's other hooks either. `doctor` says so of every line of the hook the file holds, and a line that stood to be started for a write is a guard that is off, exit 1: `"hook claude" in .claude/settings.json: .claude/settings.json has an array for a matcher under PreToolUse, ["Bash"], which Claude Code lists as an invalid setting, and beside one under PreToolUse or PermissionRequest it loads none of the file's other hooks, so the guard is off and no write is checked`. The hooks of another settings file are read as that file has them.
+    - A matcher of names with a hyphen in one, `Edit|Write|my-tool`, is read as the Claude Code on `PATH` reads it too. By [Claude Code's changelog](https://code.claude.com/docs/en/changelog), 2.1.195, such a matcher matched as a substring before that release and exactly from it on; the changelog does not say how the rest of it was read, the names it lists exactly, the matcher as a pattern, under which `Edit` is in `NotebookEdit` too, or its whole text, which is in no tool's name. So under 2.1.139 to 2.1.194, and where the release cannot be told, which writes the line is started for is *cannot tell* wherever those readings differ, never fine; `--strict` fails it: `(under PreToolUse it has the matcher "Edit|Write|my-tool", which Claude Code 2.1.194 may read otherwise: before 2.1.195 a matcher with a hyphenated name in it matched as a substring, and Claude Code's changelog does not say how the rest of it was read; from 2.1.195 on it is Edit and Write)`. A matcher whose readings all come to no tool that writes, `Bash|my-tool`, is no guard under any release, and nothing is said of the release.
+    - A matcher that is an array, `["Edit", "Write"]`, is by the same page an entry Claude Code lists as an invalid setting, and no hook under it is started. Where one stands under `PreToolUse` or `PermissionRequest`, in an entry of the hook's or of any other program's, Claude Code loads none of that settings file's other hooks either. `doctor` says so of every line of the hook the file holds, and a line that stood to be started for a write is a guard that is off, exit 1: `"hook claude" in .claude/settings.json: .claude/settings.json has an array for a matcher under PreToolUse, ["Bash"], which Claude Code lists as an invalid setting, and beside one under PreToolUse or PermissionRequest it loads none of the file's other hooks, so the guard is off and no write is checked`. The hooks of another settings file are read as that file has them. Where such an array stands in the project's `.claude/settings.json`, the file `init` writes its hooks into, `doctor`'s advice is the array's first, since `init` writes no hook there while it stands, and then `init --write`. `--format json` has the array as `claudeCode.unloaded`, `null` where there is none.
   - A line with no `args` is one Claude Code hands to a shell. Where it holds a quote, a variable or anything else a shell rewrites after its command, what the hook is handed is *cannot tell*, never fine; `--strict` fails it. Written with `args`, each word reaches the hook as it stands, and `doctor` reads it.
-  - `"onFailure": "block"` on the hook's entry is said in a note. Claude Code 2.1.295 or later then holds a write when the hook fails, where without the field the write goes ahead: by the hook's exit 1 for a question it cannot read, by a hook that does not start, or by one that runs past its timeout. With a line that turns the guard off, that is every write, the one that mends the line among them.
+  - `"onFailure": "block"` on the hook's entry is said in a note. Claude Code 2.1.295 or later then holds a write when the hook fails, where without the field the write goes ahead: by a hook that does not start, or by one that runs past its timeout. The hook says each of its own answers with exit 0 or 2, a line that turns the guard off among them, so the field holds no write for those. Where the Claude Code on `PATH` is 2.1.295 or later and a line that guards sets no `onFailure`, a note advises it, with `init --write --block-on-failure` for `init`'s own entries, and fails nothing: every Claude Code that reads the file has to be one that reads the field.
   - `--format json` has each line under `claudeCode.lines`: its `file`, `events`, the `line` as written, its `state` (`guards`, `off`, `held`, `unstarted` or `unknown`), `onFailure`, the writing tools Claude Code waits on it `before` a write by and starts it `after` one by, of `Edit`, `Write` and `NotebookEdit` (`null` where that cannot be told), and what is said of it as `detail`, `cover` and `note`, `null` where there is nothing to say. Beside the lines, `claudeCode.presence` is whether the plugin is on this machine, `null` where no plugin is on and otherwise its `state` (`present`, `absent` or `unknown`) with the reason as `detail`; `claudeCode.hooksOff` is the settings file whose `disableAllHooks` is `true`, or `null`; and `claudeCode.notes` holds what is said of the two.
   - The plugin's own hooks are not read: they are a release's files, and every release wrote `hook claude` and no more on the line, under the matcher `init` writes. What is read is whether the plugin that settings turn on is on this machine, by [Claude Code's plugin loading reference](https://code.claude.com/docs/en/plugins/loading), from the directories Claude Code keeps plugins in: `plugins` in its configuration directory, or what `CLAUDE_CODE_PLUGIN_CACHE_DIR` names, and each directory `CLAUDE_CODE_PLUGIN_SEED_DIR` names.
     - *On the machine*: a version of it is in a cache, `cache/<marketplace>/spec-harness/<version>/`, which no `.orphaned_at` marks as left behind. Nothing more is said.
@@ -409,6 +471,9 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
 - **git's pre-commit hook**: whether it runs spec-harness, where git runs it from: installed, missing, a hook of the repository's own without the line, or, outside Windows, one git skips because it is not executable.
   - A hook that runs it through `npx` is one that runs it. A note names the line that runs it with `node`: `npx` starts npm to start node on every commit, and under npm 12 prints two `npm notice run` lines each time. A note, never a failure; `--format json` has it as `gitHook.note`.
   - What stands at the hook's path and is no file is no hook, and git takes it for one all the same. A directory there, which a repository whose `core.hooksPath` is in its work tree can hold, is one git tries to run where it may execute it, which on Windows is always: it cannot, and stops every commit, with `cannot spawn` on Windows and `cannot exec` elsewhere. `doctor` says the path, what it is and what git does with it, and exits 1, since nothing is checked there and nothing is committed: `.git/hooks/pre-commit is a directory, not a hook, and git stops every commit at it`. Where git may not execute it, it skips it as it skips a hook that is not executable: that is said, and fails nothing. `--format json` has the two as the `gitHook.state` `stops` and `ignored`. Only a file is read, so `doctor` and `init` come back from a named pipe there as well.
+  - A hook file the account may not read is said with what git does with it, where `doctor` and `init` ended on a stack. Where git may not execute it either, it skips it with a hint and commits: said, and nothing fails. Where it may, git runs it, and a script the shell cannot read stops every commit, where a program runs unread: whether it runs spec-harness is *cannot tell*, never fine; `--strict` fails it. `--format json` has the `gitHook.state` `unreadable`.
+  - A `core.hooksPath` that names a file is one git names no hook under: it says `Invalid path ...: Not a directory`, and commits with no hook. `doctor` says that where git runs its hooks cannot be told, in git's own words, where it gave the reason it has for a git older than 2.31. That is *cannot tell*, never fine; `--strict` fails it, where it failed nothing.
+- **What stands where a file is read.** A settings file, `.mcp.json` or a record of Claude Code's plugins that is neither a file nor a directory, such as a named pipe, is read as one that cannot be read as JSON, as a directory is: a pipe nothing writes to was read without end, and neither `doctor` nor `init` came back. `.spec-harness.json` that is neither stops every command, the hook among them, with `.spec-harness.json is neither a file nor a directory, not a configuration file`, exit 2, as one that is a directory does. One that cannot be read, which the account may not read or another process holds open on Windows, is said as that, with the reason: `.spec-harness.json cannot be read: EACCES: permission denied, open ...`, exit 2, where it was said to be JSON that is not valid. Every other file the harness reads is read only where it is a file, and what else stands there as a file that is not there: a document a brief cites, a sibling's `package.json`, what the run before a write kept, git's configuration and a worktree's `commondir` as the hook reads them, a request waiting for a ruling, and a probe's report, said as `neither a file nor a directory`.
 
 ### An input that names nothing
 
@@ -424,7 +489,7 @@ An option, an argument or a value that is given and names nothing is refused: ex
   | `premises` | `--brief`, `--root`, `--format`, `--strict` |
   | `escalate` | `--brief`, `--root`, `--format`, `--path`, `--reason`, `--option`, `--recommend`, `--list`, `--show` |
   | `rule` | `--root`, `--format`, `--allow`, `--deny`, `--note` |
-  | `init` | `--root`, `--format`, `--write`, `--git-hook` |
+  | `init` | `--root`, `--format`, `--write`, `--git-hook`, `--block-on-failure` |
   | `hook` | `--brief`, `--base`, `--root` |
   | `mcp` | `--root` |
 
@@ -434,18 +499,19 @@ An option, an argument or a value that is given and names nothing is refused: ex
 - **An argument a command does not take.** `context`, `rulings`, `audit` and `probe` take one brief's id at most, `rule` one escalation's id, `guard` its paths and `hook` the word `claude` or `git`; `escalate`, `premises`, `init`, `mcp` and `doctor` take none. `init mydir` set up the directory it stood in; `init --root mydir` sets up another.
 - **A value that names nothing.** An option that takes a value refuses one that is empty or only space, by the option's name: `--brief is "", which names no brief`. So does an argument, as in `guard ""`. No option gives an empty value a meaning: leave the option out for what the command does without it.
 - **A `--root` that is no directory**, a file or a path that is not there: `--root is "nowhere", which is not a directory`.
+- **An option that takes one value, given two.** `doctor --root nowhere --root .` ran in `.`, and `--brief 404 --brief 001` was brief 001: the parser kept the last, and the earlier went unread with no word. It is `--root is given twice, as "nowhere" and as ".", and one of the two would go unread; give it one`. Two values are compared as the option reads them, so the same thing given twice is the option once: `--root .` beside `--root ./`, a directory however it is spelt from where the command is started, a drive letter on Windows in either case (`--root C:\work` beside `--root c:\work`, which [spec-core's ADR-0005](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md) has every tool read as one: Windows names a volume by its letter in either case), and `--brief 12` beside `--brief 012`, a brief by its id as spec-brief's names are matched. A base, a format, an id and text are compared as written. `--path` and `--option` are lists, and each use adds to the list.
 - **A `.spec-harness.json` that is a directory** does not load, and is said so in a line, as one that is not JSON is.
 
-`--help` and `--version` answer whatever else is on the line. Three things are read another way, each for its reason:
+A line that is wrong is refused with `--help` or `--version` on it, each of the above and a command that is none, as an option no command has always was: `doctor --help --root a --root b` printed the help, exit 0. `--help` beside `--version` asks for two answers, of which one would go unread, and is refused: `--help is given beside --version, and one of the two answers would go unread; give one of them`. On a line that is right, either answers, a command that needs more than the line gives it among them, as `guard --help` does. Three things are read another way, each for its reason:
 
 - **`hook claude` reads its line as every release has.** The line is in `.claude/settings.json` and in the Claude Code plugin of every release since 0.1.0, which a later release cannot rewrite, and exit 2 from it holds every write of a session, the one that would mend the line among them. So what it does not read is passed over as before, an empty `--brief` with the rest. The releases have handed the harness five command lines, `hook claude`, `hook git`, `mcp`, and `mcp --root` with the project or with `.`, and each is read as the release that wrote it read it ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
 
-  Two things on its line are said, and still refuse nothing. Each is one line on stderr and exit 1, said where there is a write the line leaves unchecked. Claude Code does not block a tool call on exit 1: it goes on with the write and shows the line as a hook error in the transcript. No release wrote more than `hook claude` on the hook's line, so either is a line a person changed.
+  Two things on its line are said, and still refuse nothing. Each is one line to the person, as `systemMessage`, and exit 0, said where there is a write the line leaves unchecked: Claude Code goes on with the write. It was exit 1, which Claude Code counts as a hook that failed, and under `"onFailure": "block"` that held every write of the session. No release wrote more than `hook claude` on the hook's line, so either is a line a person changed.
 
   - **A `--root` that is a file, or is not there.** It read as a session outside a git work tree, exit 0 and no word, and the guard was off. It is `--root is "nowhere", which is not a directory, so the guard is off and this write is not checked`, with what to do. An empty `--root` is the directory the hook was started in, and guards there, as before.
-  - **A line the parser cannot read**: an option no command has, as in `hook claude --nope`; an option left without its value, as `--root $DIR` is in a shell where the variable is not set; a `--format` or an `--at` that is none. Each was exit 2, as it is from every other command, and Claude Code blocks the tool call on a PreToolUse hook's exit 2: every write of the session waited on a line only a write can mend. It is `the hook's line cannot be read (Option '--root <value>' argument missing), so the guard is off and this write is not checked`, with what to do. The parser's own words stand between the brackets, on one line.
+  - **A line the parser cannot read**: an option no command has, as in `hook claude --nope`; an option left without its value, as `--root $DIR` is in a shell where the variable is not set; a `--format` or an `--at` that is none; two values for an option that takes one, whichever option it is, as in `hook claude --brief 001 --brief 404`, with `--help` beside them or not; `--help` beside `--version`; and `--help` or `--version` beside a `--root` that is a file or is not there, which the hook said only as it ran, and printed the help over, exit 0. Each was exit 2, as it is from every other command, and Claude Code blocks the tool call on a PreToolUse hook's exit 2: every write of the session waited on a line only a write can mend. It is `the hook's line cannot be read (Option '--root <value>' argument missing), so the guard is off and this write is not checked`, with what to do. The parser's own words stand between the brackets, on one line.
 
-  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails, and exit 1 is a failure to it; neither `init` nor the plugin writes that field. [`doctor`](#doctor) says each of these of a line it finds in Claude Code's settings, before any write meets it.
+  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails: when it cannot start, runs past its timeout, or exits with a code other than 0 and 2, which no answer of the hook's is. `init --block-on-failure` writes the field; the plugin does not. [`doctor`](#doctor) says each of these of a line it finds in Claude Code's settings, before any write meets it.
 - **`doctor` says an empty `--brief` or `--base` in its report**, as it says a brief spec-brief does not know: a diagnosis is what a person runs when something is wrong, and it reports what is wrong with what it was given.
 - **`SPEC_BRIEF` set and empty is as unset**, since what sets it sets it whether or not there is a round ([Which brief](#which-brief)).
 
@@ -519,6 +585,7 @@ A person who runs the tools by hand runs `npx --no-install @descent-vtt/spec-har
 | `assertions.premises` | `The Defect, Measured`, `Premises`, `Preconditions` | Sections whose assertions state what was true before the round. |
 | `probes.runs`, `probes.timeout` | `2`, `600` | Runs per probe, and seconds per run. |
 | `tools` | found in `node_modules` | A sibling's command by name: `{ "spec-brief": ["node", "path/to/spec-brief.js"] }`. |
+| `turnReport` | `false` | `true`: as each of Claude Code's turns ends, the hook reports every changed path the brief protects or that is outside its scope, to Claude as the next turn begins ([`guard` and the hooks](#guard-path-and-the-hooks)). `init` writes the entry that runs it where it is on. |
 
 **Exit codes:**
 

package/dist/briefs.d.ts

@@ -19,6 +19,51 @@ export declare class SiblingOutputError extends Error {
 }
 /** Reads the document `spec-brief list --format json` prints. */
 export declare function parseBriefList(document: unknown): BriefRow[];
+/**
+ * A file a `list` answer was read from, by the SHA-256 of its bytes in hex;
+ * or `null` where spec-brief looked for it and found none, which is then to
+ * be found none again.
+ */
+export interface InputFile {
+    readonly path: string;
+    readonly sha256: string | null;
+}
+/**
+ * A directory whose files a `list` answer was read from, by their names:
+ * entries that are files, as spec-brief lists them; or `null` where
+ * spec-brief looked for the directory and found none, which is then to be
+ * found none again.
+ */
+export interface InputDirectory {
+    readonly path: string;
+    readonly entries: readonly string[] | null;
+}
+/**
+ * Everything a `list` answer was read from, as spec-brief lists it: its
+ * version, the files and directories it read, and what git read for it, the
+ * index and the ignore files, or `null` where it asked git nothing. A path
+ * is relative to the work tree and POSIX, or absolute where git names a
+ * file outside it (spec-core ADR-0005, amended 2026-10-19).
+ */
+export interface BriefInputs {
+    readonly tool: string;
+    readonly files: readonly InputFile[];
+    readonly directories: readonly InputDirectory[];
+    readonly git: {
+        readonly index: string | null;
+        readonly ignores: readonly InputFile[];
+    } | null;
+}
+/**
+ * What a `list` document says its answer was read from, where it may be
+ * given again; `null` where it lists nothing, where `keep` is anything but
+ * `true`, where it names nothing, and where anything on it is in a form not
+ * read here. Each is a doubt, and a doubt starts spec-brief as before
+ * (ADR-0002). The rows are `parseBriefList`'s to read, whatever this
+ * answers: a list this cannot read keeps an answer from being given again,
+ * and changes nothing of it.
+ */
+export declare function inputsOf(document: unknown): BriefInputs | null;
 /**
  * How the active brief was named, for messages. An argument is the id a
  * command takes after its name, or a tool call's `brief`: said to be the

package/dist/briefs.js

@@ -83,6 +83,79 @@ export function parseBriefList(document) {
         };
     });
 }
+const DIGEST = /^[0-9a-f]{64}$/;
+function inputPath(value) {
+    return typeof value === 'string' && value !== '';
+}
+function digestOf(value) {
+    return value === null || (typeof value === 'string' && DIGEST.test(value)) ? value : undefined;
+}
+function inputFiles(value) {
+    if (!Array.isArray(value))
+        return null;
+    const files = [];
+    for (const item of value) {
+        if (!isObject(item) || !inputPath(item['path']))
+            return null;
+        const sha256 = digestOf(item['sha256']);
+        if (sha256 === undefined)
+            return null;
+        files.push({ path: item['path'], sha256 });
+    }
+    return files;
+}
+function inputDirectories(value) {
+    if (!Array.isArray(value))
+        return null;
+    const directories = [];
+    for (const item of value) {
+        if (!isObject(item) || !inputPath(item['path']))
+            return null;
+        const entries = item['entries'];
+        // A name listed twice is a list that is not of one directory's files.
+        if (entries !== null && (!Array.isArray(entries) || !entries.every((entry) => typeof entry === 'string') || new Set(entries).size !== entries.length))
+            return null;
+        directories.push({ path: item['path'], entries });
+    }
+    return directories;
+}
+/**
+ * What a `list` document says its answer was read from, where it may be
+ * given again; `null` where it lists nothing, where `keep` is anything but
+ * `true`, where it names nothing, and where anything on it is in a form not
+ * read here. Each is a doubt, and a doubt starts spec-brief as before
+ * (ADR-0002). The rows are `parseBriefList`'s to read, whatever this
+ * answers: a list this cannot read keeps an answer from being given again,
+ * and changes nothing of it.
+ */
+export function inputsOf(document) {
+    if (!isObject(document))
+        return null;
+    const inputs = document['inputs'];
+    if (!isObject(inputs) || inputs['keep'] !== true || typeof inputs['tool'] !== 'string')
+        return null;
+    const files = inputFiles(inputs['files']);
+    const directories = inputDirectories(inputs['directories']);
+    const git = inputs['git'];
+    let asked;
+    if (git === null) {
+        asked = null;
+    }
+    else {
+        if (!isObject(git))
+            return null;
+        const index = digestOf(git['index']);
+        const ignores = inputFiles(git['ignores']);
+        if (index === undefined || ignores === null)
+            return null;
+        asked = { index, ignores };
+    }
+    // A list that names nothing is an answer that cannot be told from one that
+    // was read from nowhere.
+    if (files === null || directories === null || files.length + directories.length === 0)
+        return null;
+    return { tool: inputs['tool'], files, directories, git: asked };
+}
 /**
  * The brief a round is working on: named by an argument, by a flag, by
  * `SPEC_BRIEF`, or by the branch - never guessed from which brief happens to

package/dist/briefs.js.map

@@ -1 +1 @@
-{"version":3,"file":"briefs.js","sourceRoot":"","sources":["../src/briefs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The briefs, as spec-brief reports them, and which one a round is working on.\n *\n * spec-brief owns the brief format and its configuration (its ADR-0003), so\n * the harness reads briefs the way spec-brief does by asking it:\n * `spec-brief list --archived --format json`. This module reads that\n * document and nothing else; a shape it does not recognise is an error, never\n * a best-effort reading of half the fields (ADR-0002).\n */\n\nimport { sameId } from './branch.js';\nimport type { BriefRow } from './types.js';\n\n/**\n * The spec-brief JSON document versions this harness reads. Version 1 is the\n * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the\n * harness never reads, so the `list` and `archive` documents are the same.\n */\nexport const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3];\n\nexport class SiblingOutputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SiblingOutputError';\n  }\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction strings(value: unknown, where: string): string[] {\n  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {\n    throw new SiblingOutputError(`${where} is not a list of strings`);\n  }\n  return value;\n}\n\nfunction nullableString(value: unknown, where: string): string | null {\n  if (value === null || value === undefined) return null;\n  if (typeof value !== 'string') throw new SiblingOutputError(`${where} is not a string`);\n  return value;\n}\n\n/** Reads the document `spec-brief list --format json` prints. */\nexport function parseBriefList(document: unknown): BriefRow[] {\n  if (!isObject(document) || document['tool'] !== 'spec-brief' || document['command'] !== 'list') {\n    throw new SiblingOutputError('spec-brief did not print a list document');\n  }\n  const version = document['schemaVersion'];\n  // The list holds numbers alone, so `includes` refuses whatever is not one:\n  // the `typeof` is the compiler's, and the mutant without it is equivalent.\n  if (typeof version !== 'number' || !SUPPORTED_SCHEMA_VERSIONS.includes(version)) {\n    throw new SiblingOutputError(\n      `spec-brief printed schemaVersion ${String(version)}; this harness reads ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}`,\n    );\n  }\n  const briefs = document['briefs'];\n  if (!Array.isArray(briefs)) throw new SiblingOutputError('spec-brief list has no \"briefs\"');\n  return briefs.map((row, index) => {\n    const where = `briefs[${index}]`;\n    if (!isObject(row)) throw new SiblingOutputError(`${where} is not an object`);\n    const id = row['id'];\n    const file = row['file'];\n    if (typeof id !== 'string' || typeof file !== 'string') throw new SiblingOutputError(`${where} has no id or file`);\n    const phase = row['phase'];\n    if (phase !== 'live' && phase !== 'archived') throw new SiblingOutputError(`${where}.phase is \"${String(phase)}\"`);\n    const tasks = row['tasks'];\n    const wave = row['wave'];\n    return {\n      id,\n      file,\n      title: nullableString(row['title'], `${where}.title`),\n      phase,\n      status: nullableString(row['status'], `${where}.status`),\n      type: nullableString(row['type'], `${where}.type`),\n      wave: typeof wave === 'number' ? wave : null,\n      dependsOn: strings(row['dependsOn'] ?? [], `${where}.dependsOn`),\n      affectedFiles: strings(row['affectedFiles'] ?? [], `${where}.affectedFiles`),\n      protectedFiles: strings(row['protectedFiles'] ?? [], `${where}.protectedFiles`),\n      tasks: {\n        total: isObject(tasks) && typeof tasks['total'] === 'number' ? tasks['total'] : 0,\n        checked: isObject(tasks) && typeof tasks['checked'] === 'number' ? tasks['checked'] : 0,\n      },\n      ready: row['ready'] === true,\n      waitingOn: strings(row['waitingOn'] ?? [], `${where}.waitingOn`),\n    };\n  });\n}\n\n/**\n * How the active brief was named, for messages. An argument is the id a\n * command takes after its name, or a tool call's `brief`: said to be the\n * flag's, it sent a person looking for a `--brief` nobody had typed.\n */\nexport type ActiveSource = 'argument' | 'flag' | 'environment' | 'branch';\n\nexport type ActiveBrief =\n  | { readonly kind: 'found'; readonly brief: BriefRow; readonly source: ActiveSource }\n  | { readonly kind: 'none'; readonly reason: string }\n  | { readonly kind: 'unknown'; readonly id: string; readonly source: ActiveSource }\n  | { readonly kind: 'archived'; readonly brief: BriefRow; readonly source: ActiveSource };\n\n/**\n * The brief a round is working on: named by an argument, by a flag, by\n * `SPEC_BRIEF`, or by the branch - never guessed from which brief happens to\n * be the only active one (ADR-0004).\n */\nexport function findActive(\n  briefs: readonly BriefRow[],\n  named: {\n    readonly argument?: string | undefined;\n    readonly flag?: string | undefined;\n    readonly environment?: string | undefined;\n    readonly branch?: string | null | undefined;\n  },\n): ActiveBrief {\n  const pick = (id: string, source: ActiveSource): ActiveBrief => {\n    const matches = briefs.filter((brief) => sameId(brief.id, id));\n    const live = matches.find((brief) => brief.phase === 'live');\n    if (live !== undefined) return { kind: 'found', brief: live, source };\n    const archived = matches[0];\n    if (archived !== undefined) return { kind: 'archived', brief: archived, source };\n    return { kind: 'unknown', id, source };\n  };\n  if (named.argument !== undefined && named.argument.trim() !== '') return pick(named.argument.trim(), 'argument');\n  if (named.flag !== undefined && named.flag.trim() !== '') return pick(named.flag.trim(), 'flag');\n  if (named.environment !== undefined && named.environment.trim() !== '') return pick(named.environment.trim(), 'environment');\n  if (named.branch !== undefined && named.branch !== null) return pick(named.branch, 'branch');\n  return {\n    kind: 'none',\n    reason: 'no brief is named: pass --brief <id>, set SPEC_BRIEF, or work on a branch named like brief/<id>-<topic>',\n  };\n}\n"]}
+{"version":3,"file":"briefs.js","sourceRoot":"","sources":["../src/briefs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The briefs, as spec-brief reports them, and which one a round is working on.\n *\n * spec-brief owns the brief format and its configuration (its ADR-0003), so\n * the harness reads briefs the way spec-brief does by asking it:\n * `spec-brief list --archived --format json`. This module reads that\n * document and nothing else; a shape it does not recognise is an error, never\n * a best-effort reading of half the fields (ADR-0002).\n */\n\nimport { sameId } from './branch.js';\nimport type { BriefRow } from './types.js';\n\n/**\n * The spec-brief JSON document versions this harness reads. Version 1 is the\n * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the\n * harness never reads, so the `list` and `archive` documents are the same.\n */\nexport const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3];\n\nexport class SiblingOutputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SiblingOutputError';\n  }\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction strings(value: unknown, where: string): string[] {\n  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {\n    throw new SiblingOutputError(`${where} is not a list of strings`);\n  }\n  return value;\n}\n\nfunction nullableString(value: unknown, where: string): string | null {\n  if (value === null || value === undefined) return null;\n  if (typeof value !== 'string') throw new SiblingOutputError(`${where} is not a string`);\n  return value;\n}\n\n/** Reads the document `spec-brief list --format json` prints. */\nexport function parseBriefList(document: unknown): BriefRow[] {\n  if (!isObject(document) || document['tool'] !== 'spec-brief' || document['command'] !== 'list') {\n    throw new SiblingOutputError('spec-brief did not print a list document');\n  }\n  const version = document['schemaVersion'];\n  // The list holds numbers alone, so `includes` refuses whatever is not one:\n  // the `typeof` is the compiler's, and the mutant without it is equivalent.\n  if (typeof version !== 'number' || !SUPPORTED_SCHEMA_VERSIONS.includes(version)) {\n    throw new SiblingOutputError(\n      `spec-brief printed schemaVersion ${String(version)}; this harness reads ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}`,\n    );\n  }\n  const briefs = document['briefs'];\n  if (!Array.isArray(briefs)) throw new SiblingOutputError('spec-brief list has no \"briefs\"');\n  return briefs.map((row, index) => {\n    const where = `briefs[${index}]`;\n    if (!isObject(row)) throw new SiblingOutputError(`${where} is not an object`);\n    const id = row['id'];\n    const file = row['file'];\n    if (typeof id !== 'string' || typeof file !== 'string') throw new SiblingOutputError(`${where} has no id or file`);\n    const phase = row['phase'];\n    if (phase !== 'live' && phase !== 'archived') throw new SiblingOutputError(`${where}.phase is \"${String(phase)}\"`);\n    const tasks = row['tasks'];\n    const wave = row['wave'];\n    return {\n      id,\n      file,\n      title: nullableString(row['title'], `${where}.title`),\n      phase,\n      status: nullableString(row['status'], `${where}.status`),\n      type: nullableString(row['type'], `${where}.type`),\n      wave: typeof wave === 'number' ? wave : null,\n      dependsOn: strings(row['dependsOn'] ?? [], `${where}.dependsOn`),\n      affectedFiles: strings(row['affectedFiles'] ?? [], `${where}.affectedFiles`),\n      protectedFiles: strings(row['protectedFiles'] ?? [], `${where}.protectedFiles`),\n      tasks: {\n        total: isObject(tasks) && typeof tasks['total'] === 'number' ? tasks['total'] : 0,\n        checked: isObject(tasks) && typeof tasks['checked'] === 'number' ? tasks['checked'] : 0,\n      },\n      ready: row['ready'] === true,\n      waitingOn: strings(row['waitingOn'] ?? [], `${where}.waitingOn`),\n    };\n  });\n}\n\n/**\n * A file a `list` answer was read from, by the SHA-256 of its bytes in hex;\n * or `null` where spec-brief looked for it and found none, which is then to\n * be found none again.\n */\nexport interface InputFile {\n  readonly path: string;\n  readonly sha256: string | null;\n}\n\n/**\n * A directory whose files a `list` answer was read from, by their names:\n * entries that are files, as spec-brief lists them; or `null` where\n * spec-brief looked for the directory and found none, which is then to be\n * found none again.\n */\nexport interface InputDirectory {\n  readonly path: string;\n  readonly entries: readonly string[] | null;\n}\n\n/**\n * Everything a `list` answer was read from, as spec-brief lists it: its\n * version, the files and directories it read, and what git read for it, the\n * index and the ignore files, or `null` where it asked git nothing. A path\n * is relative to the work tree and POSIX, or absolute where git names a\n * file outside it (spec-core ADR-0005, amended 2026-10-19).\n */\nexport interface BriefInputs {\n  readonly tool: string;\n  readonly files: readonly InputFile[];\n  readonly directories: readonly InputDirectory[];\n  readonly git: { readonly index: string | null; readonly ignores: readonly InputFile[] } | null;\n}\n\nconst DIGEST = /^[0-9a-f]{64}$/;\n\nfunction inputPath(value: unknown): value is string {\n  return typeof value === 'string' && value !== '';\n}\n\nfunction digestOf(value: unknown): string | null | undefined {\n  return value === null || (typeof value === 'string' && DIGEST.test(value)) ? value : undefined;\n}\n\nfunction inputFiles(value: unknown): InputFile[] | null {\n  if (!Array.isArray(value)) return null;\n  const files: InputFile[] = [];\n  for (const item of value) {\n    if (!isObject(item) || !inputPath(item['path'])) return null;\n    const sha256 = digestOf(item['sha256']);\n    if (sha256 === undefined) return null;\n    files.push({ path: item['path'], sha256 });\n  }\n  return files;\n}\n\nfunction inputDirectories(value: unknown): InputDirectory[] | null {\n  if (!Array.isArray(value)) return null;\n  const directories: InputDirectory[] = [];\n  for (const item of value) {\n    if (!isObject(item) || !inputPath(item['path'])) return null;\n    const entries = item['entries'];\n    // A name listed twice is a list that is not of one directory's files.\n    if (entries !== null && (!Array.isArray(entries) || !entries.every((entry) => typeof entry === 'string') || new Set(entries).size !== entries.length)) return null;\n    directories.push({ path: item['path'], entries });\n  }\n  return directories;\n}\n\n/**\n * What a `list` document says its answer was read from, where it may be\n * given again; `null` where it lists nothing, where `keep` is anything but\n * `true`, where it names nothing, and where anything on it is in a form not\n * read here. Each is a doubt, and a doubt starts spec-brief as before\n * (ADR-0002). The rows are `parseBriefList`'s to read, whatever this\n * answers: a list this cannot read keeps an answer from being given again,\n * and changes nothing of it.\n */\nexport function inputsOf(document: unknown): BriefInputs | null {\n  if (!isObject(document)) return null;\n  const inputs = document['inputs'];\n  if (!isObject(inputs) || inputs['keep'] !== true || typeof inputs['tool'] !== 'string') return null;\n  const files = inputFiles(inputs['files']);\n  const directories = inputDirectories(inputs['directories']);\n  const git = inputs['git'];\n  let asked: BriefInputs['git'];\n  if (git === null) {\n    asked = null;\n  } else {\n    if (!isObject(git)) return null;\n    const index = digestOf(git['index']);\n    const ignores = inputFiles(git['ignores']);\n    if (index === undefined || ignores === null) return null;\n    asked = { index, ignores };\n  }\n  // A list that names nothing is an answer that cannot be told from one that\n  // was read from nowhere.\n  if (files === null || directories === null || files.length + directories.length === 0) return null;\n  return { tool: inputs['tool'], files, directories, git: asked };\n}\n\n/**\n * How the active brief was named, for messages. An argument is the id a\n * command takes after its name, or a tool call's `brief`: said to be the\n * flag's, it sent a person looking for a `--brief` nobody had typed.\n */\nexport type ActiveSource = 'argument' | 'flag' | 'environment' | 'branch';\n\nexport type ActiveBrief =\n  | { readonly kind: 'found'; readonly brief: BriefRow; readonly source: ActiveSource }\n  | { readonly kind: 'none'; readonly reason: string }\n  | { readonly kind: 'unknown'; readonly id: string; readonly source: ActiveSource }\n  | { readonly kind: 'archived'; readonly brief: BriefRow; readonly source: ActiveSource };\n\n/**\n * The brief a round is working on: named by an argument, by a flag, by\n * `SPEC_BRIEF`, or by the branch - never guessed from which brief happens to\n * be the only active one (ADR-0004).\n */\nexport function findActive(\n  briefs: readonly BriefRow[],\n  named: {\n    readonly argument?: string | undefined;\n    readonly flag?: string | undefined;\n    readonly environment?: string | undefined;\n    readonly branch?: string | null | undefined;\n  },\n): ActiveBrief {\n  const pick = (id: string, source: ActiveSource): ActiveBrief => {\n    const matches = briefs.filter((brief) => sameId(brief.id, id));\n    const live = matches.find((brief) => brief.phase === 'live');\n    if (live !== undefined) return { kind: 'found', brief: live, source };\n    const archived = matches[0];\n    if (archived !== undefined) return { kind: 'archived', brief: archived, source };\n    return { kind: 'unknown', id, source };\n  };\n  if (named.argument !== undefined && named.argument.trim() !== '') return pick(named.argument.trim(), 'argument');\n  if (named.flag !== undefined && named.flag.trim() !== '') return pick(named.flag.trim(), 'flag');\n  if (named.environment !== undefined && named.environment.trim() !== '') return pick(named.environment.trim(), 'environment');\n  if (named.branch !== undefined && named.branch !== null) return pick(named.branch, 'branch');\n  return {\n    kind: 'none',\n    reason: 'no brief is named: pass --brief <id>, set SPEC_BRIEF, or work on a branch named like brief/<id>-<topic>',\n  };\n}\n"]}

package/dist/cli.d.ts

@@ -19,7 +19,7 @@
  */
 import { type CliIO } from './workspace.js';
 export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version, type CliIO } from './workspace.js';
-export declare const HELP = "spec-harness - context, guards, audits and rulings for rounds of agent work\n\nUsage:\n  spec-harness <command> [options]\n\nCommands:\n  context [brief]     What an agent needs to start a round: the brief, its scope,\n                      rulings, dependencies, the rules in force, the cited documents.\n  guard <path...>     May the round write these paths? Exit 1 if one is refused.\n  hook claude         Answer a Claude Code PreToolUse or PostToolUse hook (stdin).\n  hook git            Answer git's pre-commit hook for the staged files.\n  escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>\n                      [--option \"<label>: <cost>\"]... [--recommend <text>].\n                      --list shows what waits; --show <id> prints one memo. Neither\n                      raises a request: beside one, only --root and --format are read.\n  rule <id>           Record a person's ruling in the brief: --allow or --deny, with\n                      --note <text>. It counts once committed signed.\n  rulings [brief]     The brief's rulings, and whether each one's signature verifies.\n  audit [brief]       Did the round stay inside the lines: what the archive would say,\n                      the brief's assertions, unverified rulings, new dependencies\n                      and the install scripts it allowed.\n  probe [brief]       Run the brief's probes: red at the base, green at the head.\n                      --at <base|head|both>, --id <probe>.\n  premises            Do the live briefs' premises still hold? For CI: exit 1 when one\n                      is stale, or, with --strict, when spec-guard cannot read one.\n  init                Configure the spec-* tools to agree. Prints the plan; --write\n                      applies it; --git-hook adds a pre-commit hook.\n  mcp                 Serve start_round, check_path, request_escalation, audit_round,\n                      list_rounds and the workflow prompts over MCP on stdio.\n  doctor              Which siblings are installed, at which versions, which brief is\n                      named, how Claude Code runs the guard, and git's hook. Exit 1\n                      when a sibling is older than this release needs, the guard is\n                      installed twice, its hook's line turns it off or holds every\n                      write, disableAllHooks or an array for a matcher switches it\n                      off, the plugin that is turned on is not on this machine and\n                      nothing else guards, Claude Code is too old to run its hooks,\n                      or git stops every commit at what stands for its hook.\n\nOptions:\n  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.\n                      For context, guard, hook, escalate, rulings, audit, probe, premises\n                      and doctor.\n  --base <ref>        What the round is measured from. Otherwise \"base\" in\n                      .spec-harness.json, then the remote's default branch. For context,\n                      guard, hook, rulings, audit, probe and doctor.\n  --root <dir>        Run from another directory, which must exist. For every command.\n  --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.\n                      For every command but hook and mcp.\n  --strict            Warnings fail the run. For guard, audit, premises and doctor.\n  --help, --version\n\nAn option a command does not read, an argument it does not take, an option or an\nargument given an empty value, and a brief given both as the argument and as --brief\nare refused, exit 2, not read as if they were not there. doctor says an empty --brief\nor --base in its report. hook claude reads its line as every release has, and says a\nline it cannot read, and a --root that is not a directory, with exit 1: it refuses\nnothing for either.\n\nExit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.\n";
+export declare const HELP = "spec-harness - context, guards, audits and rulings for rounds of agent work\n\nUsage:\n  spec-harness <command> [options]\n\nCommands:\n  context [brief]     What an agent needs to start a round: the brief, its scope,\n                      rulings, dependencies, the rules in force, the cited documents.\n  guard <path...>     May the round write these paths? Exit 1 if one is refused.\n  hook claude         Answer a Claude Code PreToolUse, PostToolUse, SessionStart or Stop\n                      hook (stdin). At session start it says what would hold every\n                      write; at a turn's end, with \"turnReport\" on, what the work tree\n                      holds that the brief protects or that is outside its scope.\n  hook git            Answer git's pre-commit hook for the staged files.\n  escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>\n                      [--option \"<label>: <cost>\"]... [--recommend <text>].\n                      --list shows what waits; --show <id> prints one memo. Neither\n                      raises a request: beside one, only --root and --format are read.\n  rule <id>           Record a person's ruling in the brief: --allow or --deny, with\n                      --note <text>. It counts once committed signed.\n  rulings [brief]     The brief's rulings, and whether each one's signature verifies.\n  audit [brief]       Did the round stay inside the lines: what the archive would say,\n                      the brief's assertions, unverified rulings, new dependencies\n                      and the install scripts it allowed.\n  probe [brief]       Run the brief's probes: red at the base, green at the head.\n                      --at <base|head|both>, --id <probe>.\n  premises            Do the live briefs' premises still hold? For CI: exit 1 when one\n                      is stale, or, with --strict, when spec-guard cannot read one.\n  init                Configure the spec-* tools to agree. Prints the plan; --write\n                      applies it; --git-hook adds a pre-commit hook; --block-on-failure\n                      has Claude Code 2.1.295 or later hold a write when the hook cannot\n                      start or runs past its timeout.\n  mcp                 Serve start_round, check_path, request_escalation, audit_round,\n                      list_rounds and the workflow prompts over MCP on stdio.\n  doctor              Which siblings are installed, at which versions, which brief is\n                      named, how Claude Code runs the guard, and git's hook. Exit 1\n                      when a sibling is older than this release needs, the guard is\n                      installed twice, its hook's line turns it off or holds every\n                      write, the branch names a brief spec-brief does not list or\n                      has archived, disableAllHooks or an array for a matcher\n                      switches it off, the plugin that is turned on is not on this\n                      machine and nothing else guards, Claude Code is too old to\n                      run its hooks, or git stops every commit at what stands for\n                      its hook.\n\nOptions:\n  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.\n                      For context, guard, hook, escalate, rulings, audit, probe, premises\n                      and doctor.\n  --base <ref>        What the round is measured from. Otherwise \"base\" in\n                      .spec-harness.json, then the remote's default branch. For context,\n                      guard, hook, rulings, audit, probe and doctor.\n  --root <dir>        Run from another directory, which must exist. For every command.\n  --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.\n                      For every command but hook and mcp.\n  --strict            Warnings fail the run. For guard, audit, premises and doctor.\n  --block-on-failure  onFailure \"block\" on init's entries but the one as a turn ends. For init.\n  --help, --version   One of the two: both on one line are refused.\n\nAn option a command does not read, an argument it does not take, an option or an\nargument given an empty value, a brief given both as the argument and as --brief,\nand an option that takes one value given two that name two things are refused, exit 2,\nnot read as if they were not there, and so with --help or --version on the line. The\nsame value twice, as --root . --root ./, is read once, and on Windows a drive letter in\neither case. doctor says an empty --brief or --base in its report. hook claude reads its\nline as every release has, and says a line it cannot read, two values for one option or\n--help beside a --root that is not a directory among them, a --root that is not a\ndirectory, and a question it cannot read, as a warning to the person with exit 0: it\nrefuses nothing for any of them.\n\nExit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.\n";
 /**
  * Runs the command line and resolves to the exit code, for an error nothing
  * below expected too.