@descent-vtt/spec-harness 0.11.0 → 0.12.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "spec-harness",
       "source": "./",
       "description": "Rounds of agent work under a brief.",
-      "version": "0.11.0"
+      "version": "0.12.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Rounds of agent work under a brief: context, a guard on every write, escalations a person signs, an audit at the end. Needs Claude Code 2.1.139 or later, and @descent-vtt/spec-harness and @descent-vtt/spec-brief 0.2.0 or later installed in the project.",
   "author": {
     "name": "DescentVTT",

package/CHANGELOG.md

@@ -9,6 +9,149 @@ only fixes, reports less or documents, so `^0.7.0` takes only releases that
 cannot turn a run red. The family's policy is
 [spec-core's ADR-0009](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md).
 
+## 0.12.0
+
+A probe's command is answered when its shell ends, by the shell's exit code,
+where one that left something holding its output was waited for until its
+timeout and then called stopped. And an input that is set and names nothing
+is refused by a line that names it, where it was read as if it had not been
+given: an option another command reads, an argument a command does not
+take, an empty `--root`, `--brief` or `--base`, an escalation with an empty
+path or reason, from the command line or through the server. Every command
+line a release's `init` wrote is read as it was.
+
+### Changed
+
+- **A probe's command is answered when its shell ends, by the shell's exit
+  code.** A command that ended and left something holding its output, as a
+  server started in the background does, was waited for until its timeout,
+  ten minutes by default, and then counted as stopped: its `run` was a
+  `timeout` and the probe `invalid`, and its `setup` stopped the probe.
+  `probe` now waits three seconds for that output, as GitHub's runner waits
+  five for a step's, judges the command by its exit code and what it had
+  printed, and says that something it started was left running
+  ([ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)).
+  Upgrading: a command's work must be done when its shell ends, so have it
+  wait for what it starts. A probe that was `invalid` at its timeout may now
+  be `measured`, `vacuous`, `fixed` or `still-failing`, and a `setup` that
+  stopped the probe may pass.
+- On Linux and macOS, what a probe's command left running in its process
+  group is stopped when `probe` is done at that commit, before the worktree
+  is removed. One that held the command's output was stopped at the
+  command's timeout, and one that held nothing ran on after `probe` had
+  ended. Upgrading: a process a `setup` starts in the background serves the
+  runs at that commit and does not outlive them. On Windows it still runs
+  on, since nothing a command left can be reached there.
+- **An option a command does not read is refused by that command.** Every
+  command took every option, so `doctor --note x`, `init --base main`,
+  `mcp --brief 012` and `hook git --strict` ran as if the option were not
+  there. Each is now exit 2 and one line that names it, `doctor does not
+  take --note; its options are --brief, --base, --root, --format and
+  --strict`
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+  [An input that names nothing](README.md#an-input-that-names-nothing)).
+  Upgrading: drop the option. The README's table has what each command
+  reads; `--strict` is for `guard`, `audit`, `premises` and `doctor`, and
+  `init` and `mcp` take neither `--brief` nor `--base`.
+- **An argument a command does not take is refused.** `doctor extra`,
+  `premises extra` and `context 012 extra` ran as if it were not there, and
+  `init mydir` set up the directory it stood in; each is exit 2 with the
+  argument named. Upgrading: drop the argument; `init --root mydir` sets up
+  another directory.
+- **An option or an argument given an empty value is refused by name, not
+  read as left out.** `--root ""` ran in the current directory, `--brief ""`
+  was answered for the branch's brief, `audit --base ""` measured no change
+  and warned, and `guard src/a.ts ""` judged the repository itself. Each is
+  exit 2 and a line such as `--root is "", which names no directory`, for a
+  value of only space too; `probe --id ""` and `escalate --show ""`, exit 2
+  before, say the same line
+  ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+  Upgrading: where a script may hand an option nothing, leave the option
+  out, as `${ID:+--brief "$ID"}` does in a shell. `SPEC_BRIEF` set and
+  empty is still as unset.
+- **A memo is not written with a part that says nothing.** `escalate` with
+  an empty `--path`, `--reason`, `--option` or `--recommend`, and
+  `request_escalation` with an empty path, recommendation or option label,
+  recorded a request a person could not rule on: a file with no name, an
+  empty *Why*, `1. **** - `. Each is refused, exit 2 or a tool error that
+  names the argument, and nothing is recorded
+  ([ADR-0006](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0006-a-ruling-is-a-signed-commit.md)).
+  Upgrading: give each of them something, or leave `--option` and
+  `--recommend` out; an option needs a label, `"<label>: <cost>"`, and its
+  cost may be left out.
+- **The server's tools refuse an empty `brief`, `base` or path.**
+  `start_round`, `check_path`, `request_escalation` and `audit_round`
+  answered an empty `brief` for the branch's brief and an empty `base` with
+  no ruling verified, and `check_path` judged an empty path as the project
+  itself. Each is a tool error that names the argument, `"brief" is "",
+  which names no brief`. Upgrading: omit an argument there is nothing to
+  give.
+- `hook claude` refuses none of the above: whatever else is on its line is
+  passed over as before, since exit 2 from it holds every write of a
+  session. Every command line a release's `init` wrote, or its plugin
+  ships, is read as it was, and a test holds each
+  ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+
+### Added
+
+- `doctor` says when the brief a round would work under is no brief: one
+  spec-brief does not know or has archived, whichever of `--brief`,
+  `SPEC_BRIEF` or the branch names it, and an empty `--brief` or `--base`.
+  It printed the id and no more, `brief   999`, for a brief under which the
+  guard held every write. Its exit code is as it was, and `--format json`
+  has the reason as `briefProblem`.
+
+### Fixed
+
+- A `--root` that is a file, or is not there, is refused by name, `--root
+  is "nowhere", which is not a directory`, where the line said the path was
+  outside a git work tree. Exit 2, as before.
+- A `.spec-harness.json` that is a directory is said in the harness's
+  words, `.spec-harness.json is a directory, not a configuration file`,
+  where it was `is not valid JSON: EISDIR: illegal operation on a
+  directory, read`. Exit 2, as before.
+- A memo gives an option that states no cost as the choice alone,
+  `2. **Refuse**`, where it ended in a dash that led nowhere.
+
+## 0.11.1
+
+A probe's timeout ends the wait as well as the command, where a process out
+of reach that held the command's output kept the probe waiting without
+limit; and an exit 2 the harness could foresee says so in a line.
+
+### Fixed
+
+- **A reader that closes the output is answered in one line, not a stack.**
+  `spec-harness context | head` could end with `spec-harness: unexpected
+  error: Error: EPIPE: broken pipe, write` and a stack once `head` had left;
+  it now prints `spec-harness: stdout was closed before all of the output
+  was written` on stderr, from every command and the server. The exit code
+  is 2, as it was
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+- A git command that failed - the diff `audit` reads, the staged files
+  `hook git` reads, the worktree `probe` adds - is reported as what git
+  said, on one line: `spec-harness: git diff --cached failed: fatal: ...`.
+  It was `unexpected error: GitError:` and a stack. Exit 2, as before.
+- A probe's timeout ends the wait for its command. Where a process the
+  command started still held its output and was out of the timeout's reach -
+  one in a session of its own, or on Windows anything left by a command whose
+  shell had ended - `probe` waited for that process to end, and never ended
+  while it ran. The command is now answered three seconds after its timeout,
+  as stopped at it, with what it had printed, and the run's evidence says
+  that something it started was left running
+  ([ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)).
+- A probe's `setup` that was stopped at its timeout says so, and after how
+  many seconds. It said only that the setup failed, with whatever the setup
+  had printed.
+
+### Documentation
+
+- The README said an interrupted `probe` stops every command "with
+  everything those started". It and ADR-0003 now say what a timeout and an
+  interrupt reach - the command's process group on Linux and macOS, the
+  processes under the command's shell on Windows while that shell runs - and
+  what they leave running.
+
 ## 0.11.0
 
 An error the harness did not expect is exit 2, where it was Node's exit 1; a

package/README.md

@@ -70,6 +70,12 @@ CI checks out a commit on no branch, so on a detached HEAD the branch is the one
 
 A branch checked out always wins, and `doctor` says which variable named the branch. Without them, a round's own CI run would name no brief, and `premises` would report the premise the round retires as stale.
 
+A name that names no brief is not passed over for the next ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)):
+
+- `--brief` given nothing, `--brief ""`, is refused, as `--brief "$ID"` is where the variable is not set: it was read as the option left out, and the branch's brief answered.
+- `SPEC_BRIEF` set and empty, or to space alone, is as unset. A hook's settings and a pipeline's `env` block set it whether or not a round is under way, and the branch then names the brief, which `doctor` shows.
+- 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.
+
 ## Commands
 
 In the order a round meets them; `init` and `doctor` set a repository up and check it.
@@ -124,6 +130,7 @@ Paths are compared as the filesystem spells them, links resolved and case correc
 
 - `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.
 - `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 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)).
 
@@ -142,6 +149,8 @@ npx --no-install @descent-vtt/spec-harness rule E-012-1 --allow --note "Add rota
 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.
+
 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.
 
 - An agent can write a row and compute any hash; it cannot produce the person's signature, and an edit to the row moves it to a commit that must be signed again ([ADR-0006](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0006-a-ruling-is-a-signed-commit.md)).
@@ -278,7 +287,17 @@ signature: expected 401, got 200
 - A probe's commands fetch nothing through `npx` unless you say so. Given a tool's name alone where `setup` did not install the tool, `npx` would fetch the registry's package of that name and run it, unasked, since the command has no terminal to be asked on ([Names](#names)). `probe` runs a probe's commands with `npm_config_yes=false`, so npm stops there and names the package, `npx canceled due to missing packages`, and the probe is `invalid`. To have npm fetch, say `--yes` on the probe's line, or set `npm_config_yes` yourself, in lower case or upper: `probe` leaves the variable as it finds it. The variable outranks a `yes=true` in an `.npmrc`. It is npm's alone, so `pnpm dlx` fetches whatever it says, and it stops a download only: a copy an earlier fetch left in npm's cache still runs.
 - A run that proves nothing says what its command printed. Where a run failed for another reason than the probe declares, was stopped at its timeout or left no report - every run of an `invalid` probe, and any such run of a `flaky` one - `probe` shows the last 2,000 characters of its command's output, where the reason is. With the table that is on the standard error, for the first such run of each probe, under a line that names the probe and the run; with `--format json` it is `output` on each such run, and nothing is written beside the document. Colours are dropped and any other control character but the line feed and the tab is written as its escape, `\u001b`, so nothing in it reaches a terminal as a command. A `setup` that fails shows its output the same way.
 - The evidence table it prints names the hash of the probe it measured with ([ADR-0007](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0007-probes-declare-their-failure.md)).
-- Interrupted, it stops every command it started, with everything those started, before it removes the worktree ([ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)).
+- A command, a `setup` as well as a `run`, is its shell, as a step is in CI: it is answered when its shell ends, by the shell's exit code and what was printed until then. A `run` is red, green or neither by those, and a `setup` has passed when the code is 0. What the command started and did not wait for is no part of the answer, so a command's work must be done when its shell ends: have it wait for what it starts.
+- Where something the command started still holds its output once the shell has ended, as a server left in the background does, `probe` waits three seconds for that output, then reads no more of it and goes on; GitHub's runner does the same with a step, after five. The run's evidence then ends `, and something it started was left running, holding its output`. A `setup` that passed says so in a line on the standard error, `spec-harness: the probe setup "<line>" passed at base, and something it started was left running, holding its output`, and one that failed says it in the error that stops the probe. A process that writes to that output afterwards has the write fail, as it would once `probe` had ended. Send a process's output to a file and nothing is held, nothing waited for and nothing said; on Windows a process the shell started with `start /b` holds the command's output even so.
+- What a command left running runs on beside the commands after it, as what a step left does in CI, and is stopped when `probe` is done at that commit, before the worktree is removed, as far as `probe` can still reach it ([ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)):
+  - On Linux and macOS that is every process still in the command's process group, forced: what the shell put in the background with `&`, whether or not it holds the command's output. Not what moved to a session or a group of its own, as a daemon does, `setsid`, and a process Node starts `detached`.
+  - On Windows it is nothing: once a command's shell has ended, nothing the command left can be found again.
+  - What is out of reach runs on until it ends or you end it: through the runs after it, and through the head's when it was left at the base.
+- A command whose shell still runs at its timeout - `probes.timeout` seconds, or for a `run` the probe's own `timeout` - is stopped, forced, with what `probe` can reach of what it started, and no more:
+  - On Linux and macOS that is every process still in the command's process group: all the command started, except what moved to a session or a group of its own.
+  - On Windows it is the command's shell and the processes under it, each found through a parent that still runs. A process whose parent has ended is not found.
+- The timeout ends the wait as well. Three seconds after it has stopped what it can, the run is answered whether or not something still holds the command's output: it is a run stopped at its timeout, with what was printed until then, and its evidence says the same of what was left running. A `setup` answered so says it in the error that stops the probe.
+- Interrupted - by Ctrl+C, SIGTERM or SIGHUP, or by Ctrl+Break on Windows - `probe` stops the commands still running, with the reach a timeout has, waits up to three seconds for their output, stops what earlier commands left, with the reach the end of a commit has, and removes the worktree before it exits.
 - A worktree's directory that cannot be deleted - on Windows, one that something a command started is still running in - costs the verdict nothing: git forgets the worktree, `probe` prints and exits as it would have, and it names the directory it left on the standard error as it exits.
 
 ### `premises`
@@ -295,6 +314,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.
 
+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`
 
 Configures the family to agree. It prints the plan, merges into files that exist, keeping what is there, and changes nothing without `--write`. Each step names its file and what `init` does there: `skip` is a step it does not take and `advise` one it leaves to you, each with the reason.
@@ -333,6 +354,8 @@ The first thing to run when a hook refuses something unexpectedly. It reports:
   - 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.
 - **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.
 - **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;
@@ -350,6 +373,38 @@ 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`.
 
+### An input that names nothing
+
+An option, an argument or a value that is given and names nothing is refused: exit 2, one line on stderr that names it and says what to do, nothing read or written for it. None is read as if it had not been given. `--root "$DIR"` where the variable is not set would otherwise run in the current directory, and the answer would look like the one that was asked for ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+- **An option a command does not read.** A command takes the options its answer depends on, and refuses any other by name, with the ones it takes: `doctor does not take --note; its options are --brief, --base, --root, --format and --strict`.
+
+  | Command | Reads |
+  | --- | --- |
+  | `context`, `rulings` | `--brief`, `--base`, `--root`, `--format` |
+  | `guard`, `audit`, `doctor` | `--brief`, `--base`, `--root`, `--format`, `--strict` |
+  | `probe` | `--brief`, `--base`, `--root`, `--format`, `--id`, `--at` |
+  | `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` |
+  | `hook` | `--brief`, `--base`, `--root` |
+  | `mcp` | `--root` |
+
+  `init` chooses the base itself, and the server is told the brief and the base by each call, so neither takes `--base` or `--brief`: taking one would say the base or the brief had been set.
+- **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`.
+- **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:
+
+- **`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; an option no command has is exit 2 there, as it always was. 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)).
+- **`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)).
+
+**In a tool call.** The server's tools refuse the same in their arguments, with a tool error that names the argument, as in `"paths[1]" is "", which names no file`: an empty `brief` or `base`, an empty path, an empty `recommendation`, an option whose `label` is empty. An argument a tool does not take was refused already.
+
 ## As a Claude Code plugin
 
 spec-harness ships two different things called a plugin. This section is the **Claude Code plugin**, installed into Claude Code. The **spec-brief plugin**, `@descent-vtt/spec-harness/spec-brief-plugin`, is a module spec-brief's archive loads to learn of signed rulings; `init` configures it ([above](#escalate-rule-rulings)).
@@ -425,7 +480,7 @@ A person who runs the tools by hand runs `npx --no-install @descent-vtt/spec-har
 | --- | --- |
 | `0` | Clean. |
 | `1` | Refused, found something, or waiting on a person. |
-| `2` | The answer cannot be trusted. An error the harness did not expect is one: `spec-harness: unexpected error:` and its stack, on stderr. |
+| `2` | The answer cannot be trusted, or did not arrive. An option, an argument or a value that [names nothing](#an-input-that-names-nothing) is one. A git command that failed is one, and so is a stdout its reader closed before all of the output was written, as a pipeline into `head` does: each is one line on stderr. An error the harness did not expect is one too: `spec-harness: unexpected error:` and its stack, on stderr. |
 | `130` | A `probe` interrupted by SIGINT (Ctrl+C) while it runs. |
 | `143` | A `probe` interrupted by SIGTERM. |
 | `129` | A `probe` interrupted by SIGHUP. |

package/bin/spec-harness.js

@@ -7,8 +7,15 @@
 // main answers the errors it awaits with exit 2. What nothing awaits - a
 // stream's error, a timer's, a promise nobody holds - Node ends with exit 1,
 // which a script reads as a refusal or a finding: the same answer for those.
+//
+// A reader that closed stdout, as `| head` does, is no defect, and it arrives
+// here, as the stream's error: one line, with no stack to send a person
+// looking for a bug. The code alone names it, since stdout and stderr are the
+// only pipes the harness writes to, and a line about a closed stderr reaches
+// nobody.
 process.on('uncaughtException', (error) => {
-  process.stderr.write(`spec-harness: unexpected error: ${error?.stack ?? error}\n`);
+  const said = error?.code === 'EPIPE' ? 'stdout was closed before all of the output was written' : `unexpected error: ${error?.stack ?? error}`;
+  process.stderr.write(`spec-harness: ${said}\n`);
   process.exit(2);
 });
 

package/dist/cli.d.ts

@@ -2,14 +2,16 @@
  * The command line: arguments, dispatch, output and exit codes.
  *
  * Exit 0: done, nothing refused. Exit 1: something refused or found. Exit 2:
- * the answer cannot be trusted - a bad flag, a configuration that does not
- * load, a sibling that is missing or printed something unreadable, an error
- * nothing here expected. A run that could not look must never exit as though
- * it looked and found nothing (spec-core ADR-0005).
+ * the answer cannot be trusted - a bad flag, an option, an argument or a
+ * value that names nothing, a configuration that does not load, a sibling
+ * that is missing or printed something unreadable, a git command that
+ * failed, an output its reader closed, an error nothing here expected. A run
+ * that could not look must never exit as though it looked and found nothing
+ * (spec-core ADR-0005).
  */
 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.\n  rule <id>           Record a person's ruling in the brief: --allow or --deny, with\n                      --note. 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, or Claude Code is too old to run its hooks.\n\nOptions:\n  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.\n  --base <ref>        What the round is measured from. Otherwise \"base\" in\n                      .spec-harness.json, then the remote's default branch.\n  --root <dir>        Run from another directory.\n  --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.\n  --strict            Warnings fail the run.\n  --help, --version\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 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.\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, or Claude Code is too old to run its hooks.\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, and an option or an\nargument given an empty value are refused, exit 2, not read as if they were not there.\ndoctor says an empty --brief or --base in its report, and hook claude reads its line\nas every release has.\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.
@@ -21,6 +23,14 @@ export declare const HELP = "spec-harness - context, guards, audits and rulings
  * write the guard could not check went ahead. The stack is what makes a
  * report of it something to act on, and it goes to stderr alone: a script
  * that reads a document from stdout is handed no part of one.
+ *
+ * A write its reader had closed the pipe for is not such an error: the answer
+ * was not delivered, which is still 2, and nothing in the harness is at
+ * fault, so it is said in a line and no stack sends a person looking for a
+ * defect. The process's own streams report it as an event, which the
+ * launcher answers in the same words; here it is a caller's stream that
+ * throws it. It is read by its code: stdout and stderr are the only pipes
+ * the harness writes to.
  */
 export declare function run(argv: readonly string[], io: CliIO): Promise<number>;
 export declare function main(argv?: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -2,16 +2,19 @@
  * The command line: arguments, dispatch, output and exit codes.
  *
  * Exit 0: done, nothing refused. Exit 1: something refused or found. Exit 2:
- * the answer cannot be trusted - a bad flag, a configuration that does not
- * load, a sibling that is missing or printed something unreadable, an error
- * nothing here expected. A run that could not look must never exit as though
- * it looked and found nothing (spec-core ADR-0005).
+ * the answer cannot be trusted - a bad flag, an option, an argument or a
+ * value that names nothing, a configuration that does not load, a sibling
+ * that is missing or printed something unreadable, a git command that
+ * failed, an output its reader closed, an error nothing here expected. A run
+ * that could not look must never exit as though it looked and found nothing
+ * (spec-core ADR-0005).
  */
 import { SiblingOutputError } from './briefs.js';
 import { auditCommand, contextCommand, escalateCommand, probeCommand, ruleCommand, rulingsCommand } from './commands.js';
 import { ConfigError, SIBLINGS } from './config.js';
 import { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describePlugin, describeSignerKeys, describeSignerProblem, describeSigners, wiringState, } from './configure.js';
-import { show, stagedChanges } from './git.js';
+import { isDirectory } from './fs.js';
+import { GitError, show, stagedChanges } from './git.js';
 import { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
 import { claudeVersion } from './host.js';
 import { premisesCommand } from './premises.js';
@@ -21,6 +24,7 @@ import { mcpCommand } from './server.js';
 import { gitHook, initCommand } from './setup.js';
 import { notFido2, readAllowedSigners } from './signers.js';
 import { SiblingError } from './siblings.js';
+import { emptyValue, isBlank, refusal } from './usage.js';
 import { checkClaudeCode, CLAUDE_CODE_MINIMUM, MINIMUM_VERSIONS } from './versions.js';
 import { activeBrief, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, namedId, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
 export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version } from './workspace.js';
@@ -39,13 +43,13 @@ Commands:
                       [--option "<label>: <cost>"]... [--recommend <text>].
                       --list shows what waits; --show <id> prints one memo.
   rule <id>           Record a person's ruling in the brief: --allow or --deny, with
-                      --note. It counts once committed signed.
+                      --note <text>. It counts once committed signed.
   rulings [brief]     The brief's rulings, and whether each one's signature verifies.
   audit [brief]       Did the round stay inside the lines: what the archive would say,
                       the brief's assertions, unverified rulings, new dependencies
                       and the install scripts it allowed.
   probe [brief]       Run the brief's probes: red at the base, green at the head.
-                      --at base|head|both, --id <probe>.
+                      --at <base|head|both>, --id <probe>.
   premises            Do the live briefs' premises still hold? For CI: exit 1 when one
                       is stale, or, with --strict, when spec-guard cannot read one.
   init                Configure the spec-* tools to agree. Prints the plan; --write
@@ -59,13 +63,22 @@ Commands:
 
 Options:
   --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
+                      For context, guard, hook, escalate, rulings, audit, probe, premises
+                      and doctor.
   --base <ref>        What the round is measured from. Otherwise "base" in
-                      .spec-harness.json, then the remote's default branch.
-  --root <dir>        Run from another directory.
+                      .spec-harness.json, then the remote's default branch. For context,
+                      guard, hook, rulings, audit, probe and doctor.
+  --root <dir>        Run from another directory, which must exist. For every command.
   --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.
-  --strict            Warnings fail the run.
+                      For every command but hook and mcp.
+  --strict            Warnings fail the run. For guard, audit, premises and doctor.
   --help, --version
 
+An option a command does not read, an argument it does not take, and an option or an
+argument given an empty value are refused, exit 2, not read as if they were not there.
+doctor says an empty --brief or --base in its report, and hook claude reads its line
+as every release has.
+
 Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.
 `;
 /* ------------------------------------------------------------------- guard */
@@ -184,6 +197,32 @@ async function hookCommand(options, io) {
     throw new UsageError('hook takes "claude" or "git"');
 }
 /* ------------------------------------------------------------------ doctor */
+/**
+ * The brief a round here works on, as doctor reports it: its id, and what is
+ * wrong with the name when no round can work under it. Every other command
+ * stops there. A diagnosis says it, being what a person runs when the guard
+ * holds a write they expected it to pass.
+ */
+async function diagnoseBrief(workspace, options, env) {
+    if (options.brief !== undefined && isBlank(options.brief))
+        return { id: null, problem: emptyValue('--brief', 'brief', options.brief) };
+    const id = namedId(workspace, options, env);
+    // A spec-brief that cannot be run is a row of the report, with the reason.
+    if (workspace.siblings.locate('spec-brief').kind !== 'found')
+        return { id, problem: null };
+    try {
+        // Where nothing names a brief, spec-brief is not asked (ADR-0004), and
+        // there is no problem to state.
+        return { id, problem: describeActive(await activeBrief(workspace, options, env)).problem };
+    }
+    catch (error) {
+        // Asking spec-brief throws nothing but this, so the check is equivalent
+        // to its mutant; it keeps any other error the stack it needs.
+        if (!(error instanceof SiblingError))
+            throw error;
+        return { id, problem: `spec-brief could not say whether it knows brief ${id}: ${error.message}` };
+    }
+}
 async function doctorCommand(options, io) {
     const workspace = await openWorkspace(options, io);
     const rows = SIBLINGS.map((name) => {
@@ -197,10 +236,15 @@ async function doctorCommand(options, io) {
         const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version})`;
         return { ...row, version: sibling.version, detail };
     });
-    const named = namedId(workspace, options, io.env);
+    const named = await diagnoseBrief(workspace, options, io.env);
     // A ruling counts only by a signature checked against the allowed signers
     // on the base, and only once spec-brief's archive asks the plugin about it.
-    const base = await resolveBase(workspace, options.base);
+    // A --base given nothing is no base, said as the brief's is, in the report.
+    // Nothing below asks what kind a base is but whether it is resolved, so the
+    // mutant that names this one otherwise is equivalent.
+    const base = options.base !== undefined && isBlank(options.base)
+        ? { kind: 'unresolved', reason: emptyValue('--base', 'base', options.base) }
+        : await resolveBase(workspace, options.base);
     const signersFile = workspace.config.rulings.allowedSigners;
     // An unresolved base has no commit: git shows nothing for one, so asking
     // anyway reads as no file, and that mutant is equivalent.
@@ -229,7 +273,8 @@ async function doctorCommand(options, io) {
             root: workspace.root,
             branch: workspace.branch,
             branchSource: workspace.branchSource ?? null,
-            brief: named,
+            brief: named.id,
+            briefProblem: named.problem,
             base: base.kind === 'resolved' ? { ref: base.ref, source: base.source, mergeBase: base.mergeBase } : { unresolved: base.reason },
             allowedSigners: {
                 file: signersFile,
@@ -256,7 +301,7 @@ async function doctorCommand(options, io) {
         io.stdout.write([
             `root    ${workspace.root}`,
             `branch  ${branch}`,
-            `brief   ${named ?? '(none named)'}`,
+            `brief   ${named.problem === null ? (named.id ?? '(none named)') : `none: ${named.problem}`}`,
             `base    ${describeBase(base)}`,
             `signers ${signers}`,
             ...more(signerNotes),
@@ -289,20 +334,22 @@ async function doctorCommand(options, io) {
  * `Object` as a command and ended on a stack trace, where `spec-harness
  * construct` is an unknown command with exit 2.
  */
-const COMMANDS = new Map([
-    ['guard', guardCommand],
-    ['hook', hookCommand],
-    ['context', contextCommand],
-    ['audit', auditCommand],
-    ['escalate', escalateCommand],
-    ['rule', ruleCommand],
-    ['rulings', rulingsCommand],
-    ['probe', probeCommand],
-    ['premises', premisesCommand],
-    ['init', initCommand],
-    ['mcp', mcpCommand],
-    ['doctor', doctorCommand],
-]);
+const COMMANDS = new Map(
+// One for every command that has a shape (usage.ts), which the compiler holds.
+Object.entries({
+    guard: guardCommand,
+    hook: hookCommand,
+    context: contextCommand,
+    audit: auditCommand,
+    escalate: escalateCommand,
+    rule: ruleCommand,
+    rulings: rulingsCommand,
+    probe: probeCommand,
+    premises: premisesCommand,
+    init: initCommand,
+    mcp: mcpCommand,
+    doctor: doctorCommand,
+}));
 async function dispatch(argv, io) {
     let options;
     try {
@@ -325,6 +372,12 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: unknown command "${options.command}"; see spec-harness --help\n`);
         return EXIT_ERROR;
     }
+    // What parsed and names nothing, before anything is read or written for it.
+    const refused = refusal(options, isDirectory);
+    if (refused !== null) {
+        io.stderr.write(`spec-harness: ${refused}\n`);
+        return EXIT_ERROR;
+    }
     return command(options, io);
 }
 /**
@@ -338,6 +391,14 @@ async function dispatch(argv, io) {
  * write the guard could not check went ahead. The stack is what makes a
  * report of it something to act on, and it goes to stderr alone: a script
  * that reads a document from stdout is handed no part of one.
+ *
+ * A write its reader had closed the pipe for is not such an error: the answer
+ * was not delivered, which is still 2, and nothing in the harness is at
+ * fault, so it is said in a line and no stack sends a person looking for a
+ * defect. The process's own streams report it as an event, which the
+ * launcher answers in the same words; here it is a caller's stream that
+ * throws it. It is read by its code: stdout and stderr are the only pipes
+ * the harness writes to.
  */
 export async function run(argv, io) {
     try {
@@ -345,12 +406,22 @@ export async function run(argv, io) {
     }
     catch (error) {
         // A sibling's document of a shape the harness does not read is a sibling
-        // that printed something it cannot read (answers.ts): exit 2.
-        if (error instanceof UsageError || error instanceof ConfigError || error instanceof SiblingError || error instanceof SiblingOutputError) {
+        // that printed something it cannot read (answers.ts): exit 2. A git
+        // command that failed is what git said, and no line of the harness's.
+        if (error instanceof UsageError ||
+            error instanceof ConfigError ||
+            error instanceof SiblingError ||
+            error instanceof SiblingOutputError ||
+            error instanceof GitError) {
             io.stderr.write(`spec-harness: ${error.message}\n`);
             return EXIT_ERROR;
         }
-        io.stderr.write(`spec-harness: unexpected error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+        if (!(error instanceof Error))
+            io.stderr.write(`spec-harness: unexpected error: ${String(error)}\n`);
+        else if (error.code === 'EPIPE')
+            io.stderr.write('spec-harness: stdout was closed before all of the output was written\n');
+        else
+            io.stderr.write(`spec-harness: unexpected error: ${error.stack ?? error.message}\n`);
         return EXIT_ERROR;
     }
 }