@descent-vtt/spec-harness 0.16.0 → 0.17.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.16.0",
+  "version": "0.17.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,132 @@ 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.17.0
+
+`doctor` and `init` see four more ways a guard is set up and checks
+nothing: a root on the hook's line that is in no work tree, hooks switched
+off by `disableAllHooks`, an entry that is no command, and a plugin that
+settings turn on and the machine does not have. And they name only a tool
+Claude Code has as one whose writes go unchecked. `doctor`, `init` and the
+hooks ask git at once for what waits on nothing else, about half a second
+of the five a `doctor` takes on a Windows workstation, and a matcher that
+is a pattern is read once in a run.
+
+### Changed
+
+- **`doctor` fails for a hook's line whose root is a directory outside any
+  git work tree.** `hook claude --root <such a directory>` reads a session
+  outside a work tree: the hook checks no write and says nothing, exit 0,
+  as in every release, and `doctor` said of the line that it guards, by
+  its root. It now asks git about the root as the hook does and says the
+  line as a guard that is off: `"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`. `init` says the same
+  of the file (`advise`) and writes nothing into it. The hook answers as it
+  did ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: `doctor` exits 1 for such a line, where it exited 0 while no
+  write was checked: give the line a directory in the work tree, or take
+  `--root` off it for the project Claude Code names.
+- **`doctor` fails where `disableAllHooks` switches the guard off.** With
+  `"disableAllHooks": true` in a settings file, Claude Code's settings
+  reference has it run no hook of the user's, the project's or the local
+  settings and none of a plugin, and `doctor` reported `init`'s entries, or
+  the plugin, as the guard. It now reads the key from the three files as
+  Claude Code merges them, the last that sets it deciding, names the file,
+  and exits 1 where there are guard hooks for the key to switch off; where
+  nothing is wired it is a note. `init` says it of the file that holds the
+  key (`advise`) and writes what it would have written. Hooks of managed
+  settings, and of a plugin managed settings force on, keep running, and
+  neither `doctor` nor `init` reads managed settings or `--settings`.
+  `--format json` has the file as `claudeCode.hooksOff`, `null` where no
+  file switches the hooks off.
+  Upgrading: `doctor` exits 1 in such a tree, where it exited 0 while no
+  hook ran: take the key out, or set it to `false` in a file of higher
+  precedence.
+- **Only an entry Claude Code runs as a command is read as the hook.** An
+  entry of another handler type, `"type": "prompt"`, `"agent"`, `"http"`
+  or `"mcp_tool"`, that held the hook's command was reported as the guard.
+  Such an entry runs no command, so it is no line of the hook: `doctor`
+  reports no guard for it, and `init --write` writes its hooks beside it.
+  An entry with no `"type"`, or with a word the hooks reference does not
+  list, is *cannot tell*: the reference requires the field and says nothing
+  of an entry without it.
+  Upgrading: `doctor --strict` exits 1 for a hook's entry with no
+  `"type"`: give it `"type": "command"`, as `init` and the plugin write it.
+- **`doctor` says whether the plugin that settings turn on is on this
+  machine.** It reported the plugin as the guard, and `init` skipped, on the
+  word of `enabledPlugins` alone. Both now read what Claude Code's plugin
+  loading reference documents of the directories it keeps plugins in
+  (`plugins` in its configuration directory, or
+  `CLAUDE_CODE_PLUGIN_CACHE_DIR`, and each `CLAUDE_CODE_PLUGIN_SEED_DIR`).
+  A version of the plugin in a cache is the plugin on the machine, and
+  nothing more is said. Where the project's `.claude/settings.json` alone
+  turns it on, no version is cached and no marketplace of its name is
+  recorded as fetched or declared in settings, Claude Code fetches none, so
+  the plugin is not the guard: `doctor` says so with what would bring it,
+  and exits 1 where no hook of `init`'s guards instead. Everything else is
+  *cannot tell*, said, and a failure under `--strict` alone: a record that
+  is not there or cannot be read, a marketplace that is there or declared
+  with nothing cached, a `true` in a settings file of your own, an id that
+  names no marketplace. `init` writes no hook on that reading alone: it
+  says what `doctor` says (`advise`), and how to have the hooks in the file
+  instead. `--format json` has `claudeCode.presence`, `null` where no
+  plugin is on, with its `state` (`present`, `absent` or `unknown`) and the
+  reason as `detail`, and `claudeCode.notes`, what is said of the plugin
+  and of `disableAllHooks`
+  ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  Upgrading: `doctor` exits 1 where the project's settings alone turn the
+  plugin on and the machine has neither a version of it nor its
+  marketplace: install the plugin there, or turn it off for the project and
+  run `init --write`. `claudeCode.state` is then `none` or `init`, where
+  it was `plugin` or `both`. `doctor --strict` exits 1 where it cannot
+  tell, as on a machine where Claude Code has recorded no marketplace.
+- **`doctor` and `init` no longer name `MultiEdit` as a tool whose writes
+  go unchecked.** `doctor` says which of the tools that write a file a
+  hook's line is waited on before, and it counted four: `Edit`, `Write`,
+  `MultiEdit` and `NotebookEdit`. So a line under the matcher
+  `Edit|Write|NotebookEdit` was said to leave a write by `MultiEdit`
+  unchecked. No Claude Code the hooks run under has that tool: its tools
+  reference lists `Edit`, `Write` and `NotebookEdit`, and the tool inputs
+  its releases declare hold a `MultiEdit` up to 1.0.128 and none from 2.0.0
+  on, where the hooks need 2.1.139. A line is now read for those three, and
+  one waited on before all of them is said with nothing more, as a line
+  under the matcher `init` writes is. The hook reads the file a `MultiEdit`
+  names as it did, for whatever still sends one, and `init` writes the
+  matcher it wrote
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: in `doctor --format json`, `before` and `after` of each of
+  `claudeCode.lines` hold `Edit`, `Write` and `NotebookEdit` at most, three
+  names for `init`'s own line where they held four, so a script that
+  compared them with the four names compares with three. A line whose
+  matcher lets `MultiEdit` through and none of the three is `unstarted`
+  where it was `guards`: it is no longer one of `init`'s entries, so beside
+  the plugin `doctor` exits 0 where it exited 1 for a double install, and
+  `init --write` writes its hooks beside such a line.
+
+### Fixed
+
+- **`doctor`, `init` and the hooks ask git at once for what waits on nothing
+  else, and `doctor` asks Claude Code its release meanwhile.** Each started
+  its processes one after another, nine for a plain `doctor`, and on a
+  Windows workstation a process is what a command takes: 227 ms for one of
+  git's there, and 2.6 seconds for Claude Code's. Measured there with the
+  two builds taking turns, at the median of ten runs, `doctor` took 4.8
+  seconds where it took 5.3, and 4.3 where it took 5.4 on a brief's branch;
+  with other work holding every processor of the workstation, 20.0 where it
+  took 25.5. `init` and the hooks take a tenth of a second less than they
+  did, of one to two and a half. On Linux, where git answers in 2 ms, a
+  `doctor` takes 0.10 seconds either way. Nothing any of them prints changes
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- **A matcher that is a pattern is read once in a run.** `doctor` read it
+  again for every entry under it, and `init` once more for what to write.
+  Under a pattern that runs out its budget of 100 ms, fifty entries took a
+  `doctor` 5.2 seconds, and take 0.2. A file with a pattern of its own over
+  each entry is read as before, a budget each. In the programmatic API,
+  `mergeClaudeSettings` takes what reads a pattern as an optional third
+  argument; without it, it reads each pattern once for itself.
+
 ## 0.16.0
 
 `doctor` and `init` see the rest of Claude Code's hook. A line that names

package/README.md

@@ -343,6 +343,8 @@ Configures the family to agree. It prints the plan, merges into files that exist
   - 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.
+  - Where the plugin that is turned on is not on this machine, as [`doctor`](#doctor) reads it, `init` still writes neither entry: a plugin that is there after all would bring them a second time. It says what `doctor` says (`advise`), and how to have the entries in the files instead. Where that cannot be told, it says so beside the `skip`.
+  - `"disableAllHooks": true` in a settings file is said of that file (`advise`): the hooks `init` writes do not run while it stands. `init` writes what it would have written.
   - A line of the hook that is there already is known as [`doctor`](#doctor) knows it: by its command and the words `hook claude`, however a person changed it, with the event and the matcher its entry stands under. Where the file holds such a line that Claude Code starts for a write, `init` writes no hook into it, since a second line would run beside the first, and says which line it left, in `doctor`'s words for it (`keep`, or `advise` where the line is no guard: it turns the guard off, holds every write, or is waited on before none). It rewrites no line but the one 0.1 wrote, and completes only its own line where that stands under one event alone. A line Claude Code starts for no write is left as it is, and `init` writes its own beside it.
 - **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.
@@ -375,18 +377,25 @@ 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.
+  - `"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 `--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 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`.
   - An entry is read with the event it stands under and its matcher, as [Claude Code's hooks reference](https://code.claude.com/docs/en/hooks) has them: Claude Code waits on a hook before a tool call under `PreToolUse` alone, and starts an entry for the tools its matcher lets through - every tool where the matcher is left out, empty or `*`, the tools it names where it is a list of names, and the names a pattern matches otherwise. An entry that runs in the background (`async`, `asyncRewake`) is waited on for none.
     - A line Claude Code waits on before no write is not the guard, whatever the hook would do with it. `doctor` says so with what the line stands under, `"hook claude" in .claude/settings.json: Claude Code waits on it before no write, so it is not the guard and refuses none (under PreToolUse it has the matcher "Bash")`, and a file whose only line is started for no write, before one or after, is not counted among `init`'s entries. It fails nothing: no guard is a choice.
-    - A line waited on before some of `Edit`, `Write`, `MultiEdit` and `NotebookEdit` guards those, and `doctor` names the rest, whose writes go unchecked. A line started after no write warns of none, which is said too. Neither fails anything.
-    - 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 not text, or is no pattern, or is a pattern that takes more than a tenth of a second to test against the four names: one can be written that never finishes, and `doctor` and `init` come back all the same.
+    - A line waited on before some of `Edit`, `Write` and `NotebookEdit` guards those, and `doctor` names the rest, whose writes go unchecked. A line started after no write warns of none, which is said too. Neither fails anything.
+    - 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 not text, 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 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.
-  - `--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 (`null` where that cannot be told), and what is said of it as `detail`, `cover` and `note`, `null` where there is nothing to say.
-  - 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. Nor is whether the plugin a settings file turns on is installed on this machine.
+  - `--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.
+    - *Not on the machine*: the project's `.claude/settings.json` alone turns it on, no version of it is cached, and no marketplace of its name is recorded as fetched (`known_marketplaces.json`) or declared in settings (`extraKnownMarketplaces`). Claude Code fetches no plugin that a project's settings alone turn on, so the plugin brings no hook and is not counted. With `init`'s hooks in a settings file, those are the guard, and the plugin is a note. Without them `doctor` exits 1 and says what would bring it.
+    - *Cannot tell*, never fine, and a failure under `--strict` alone: a record that is not there or cannot be read; a marketplace that is on the machine, or declared, while nothing is cached, since a plugin its marketplace lists by a relative path loads from the marketplace, whose list is not read; marketplaces hosted on claude.ai; a `true` in a settings file of your own, for which Claude Code fetches; and an id that names no marketplace (`@inline`, `@skills-dir`, `@synced`).
 - **Which Claude Code**, when Claude Code runs the guard: `claude --version`, found on `PATH` and run without a shell.
   - Older than 2.1.139 exits 1. An older release ignores a hook's `args` and runs a bare `node`, which reads the hook's input as a script and fails, and a PreToolUse hook that fails with anything but exit 2 blocks nothing: every write passes unguarded.
   - On Windows, npm installs Claude Code as a `claude.cmd` shim, which cannot be run without a shell, so it is read instead: the `node_modules\@anthropic-ai\claude-code` it runs, as npm's shim or pnpm's names it, and that package.json's `version`, which doctor says it read. Nothing is run.

package/dist/cli.d.ts

@@ -11,7 +11,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, 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, 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 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 switches it off, the plugin that is\n                      turned on is not on this machine and nothing else guards, or\n                      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, 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";
 /**
  * Runs the command line and resolves to the exit code, for an error nothing
  * below expected too.

package/dist/cli.js

@@ -12,7 +12,7 @@
 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 { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, wiringState, } from './configure.js';
 import { isDirectory } from './fs.js';
 import { GitError, show, stagedChanges } from './git.js';
 import { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
@@ -26,7 +26,7 @@ import { notFido2, readAllowedSigners } from './signers.js';
 import { SiblingError } from './siblings.js';
 import { emptyValue, heldHookLine, isBlank, isClaudeHook, readHookLine, refusal, unreadHookLine } from './usage.js';
 import { checkClaudeCode, CLAUDE_CODE_MINIMUM, MINIMUM_VERSIONS } from './versions.js';
-import { activeBrief, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
 export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version } from './workspace.js';
 export const HELP = `spec-harness - context, guards, audits and rulings for rounds of agent work
 
@@ -61,7 +61,9 @@ Commands:
                       named, how Claude Code runs the guard, and git's hook. Exit 1
                       when a sibling is older than this release needs, the guard is
                       installed twice, its hook's line turns it off or holds every
-                      write, or Claude Code is too old to run its hooks.
+                      write, disableAllHooks switches it off, the plugin that is
+                      turned on is not on this machine and nothing else guards, or
+                      Claude Code is too old to run its hooks.
 
 Options:
   --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
@@ -241,6 +243,31 @@ async function hookCommand(options, io) {
     throw new UsageError('hook takes "claude" or "git"');
 }
 /* ------------------------------------------------------------------ doctor */
+/**
+ * The base, and the allowed-signers file as it is on it: the file waits on
+ * the base, and the two on nothing else doctor asks. A --base given nothing
+ * is no base, said as the brief's is, in the report.
+ */
+async function baseAndSigners(workspace, flag, signersFile) {
+    // Nothing in doctor asks what kind a base is but whether it is resolved, so
+    // the mutant that names this one otherwise is equivalent.
+    const base = flag !== undefined && isBlank(flag) ? { kind: 'unresolved', reason: emptyValue('--base', 'base', flag) } : await resolveBase(workspace, flag);
+    // An unresolved base has no commit: git shows nothing for one, so asking
+    // anyway reads as no file, and that mutant is equivalent.
+    const signersText = base.kind === 'resolved' ? await show(base.sha, signersFile, workspace.root) : null;
+    return { base, signersText };
+}
+/**
+ * How Claude Code is wired to the guard, and the release of the one on
+ * `PATH`, which waits on the wiring: only a Claude Code that runs the guard
+ * is asked its release, since one older than the hooks need lets every
+ * write through unguarded. `null` where it was not asked.
+ */
+async function wiringAndRelease(root, io) {
+    const wiring = await claudeCodeWiring(root, io);
+    const release = wiringState(wiring) === 'none' ? null : checkClaudeCode(await claudeVersion(io.env));
+    return { wiring, release };
+}
 async function doctorCommand(options, io) {
     const workspace = await openWorkspace(options, io);
     const rows = SIBLINGS.map((name) => {
@@ -254,19 +281,25 @@ 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 = await diagnoseBrief(workspace, options, io.env);
+    const signersFile = workspace.config.rulings.allowedSigners;
+    // Five things that wait on the work tree and on nothing of one another,
+    // each a process or a chain of them. Asked one after another, Claude
+    // Code's release, the longest wait of a doctor on Windows, was asked for
+    // only when every answer of git's before it was in. So they are asked at
+    // once, and read below in the order they were asked in before: where more
+    // than one fails, the first of that order is the one thrown, whichever
+    // failed first by the clock (ADR-0002).
+    const [briefAsked, baseAsked, pluginAsked, claudeAsked, hookAsked] = await Promise.allSettled([
+        diagnoseBrief(workspace, options, io.env),
+        baseAndSigners(workspace, options.base, signersFile),
+        specBriefPlugin(workspace.root),
+        wiringAndRelease(workspace.root, io),
+        gitHook(workspace.root),
+    ]);
+    const named = answerOf(briefAsked);
     // 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.
-    // 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.
-    const signersText = base.kind === 'resolved' ? await show(base.sha, signersFile, workspace.root) : null;
+    const { base, signersText } = answerOf(baseAsked);
     const onBase = base.kind === 'resolved' ? signersText !== null : null;
     const signers = describeSigners(signersFile, base.kind === 'resolved' ? base.ref : null, onBase === true);
     // Which keys sign, as notes: a key that is not FIDO2 can still be one the
@@ -274,10 +307,10 @@ async function doctorCommand(options, io) {
     const read = readAllowedSigners(signersText ?? '');
     const plain = notFido2(read.signers);
     const signerNotes = [describeSignerKeys(plain), ...read.problems.map(describeSignerProblem)].filter((note) => note !== null);
-    const plugin = await specBriefPlugin(workspace.root);
+    const plugin = answerOf(pluginAsked);
     // The plugin and init's entries both on: Claude Code runs every guard twice
     // and registers the server twice (ADR-0012).
-    const wiring = await claudeCodeWiring(workspace.root, io);
+    const { wiring, release } = answerOf(claudeAsked);
     const claude = wiringState(wiring);
     // What the hook does with each line the settings hold for it, where there
     // is something to say: more on it than init writes, a line that turns the
@@ -285,12 +318,14 @@ async function doctorCommand(options, io) {
     // Claude Code starts it for where they are not all of them, and what
     // onFailure changes.
     const lineNotes = wiring.lines.flatMap((line) => [line.detail, line.cover, line.note]).filter((note) => note !== null);
-    // Only a Claude Code that runs the guard is asked its release: one older
-    // than the hooks need lets every write through unguarded.
-    const release = claude === 'none' ? null : checkClaudeCode(await claudeVersion(io.env));
+    // What stands over every line: a plugin that is turned on and is not on
+    // this machine, or cannot be told to be, and disableAllHooks, which
+    // switches off whatever hooks there are.
+    const switchedOff = guardSwitchedOff(wiring);
+    const wiringNotes = [describePresence(wiring), wiring.hooksOff === null ? null : describeHooksOff(wiring.hooksOff, switchedOff)].filter((note) => note !== null);
     // How the hook runs the harness is a note: one that goes through npx guards
     // as well as one that does not, and fails nothing, --strict or not.
-    const { hook, note: hookNote } = await gitHook(workspace.root);
+    const { hook, note: hookNote } = answerOf(hookAsked);
     const branch = workspace.branch === null ? '(detached)' : `${workspace.branch}${workspace.branchSource === undefined ? '' : ` (detached; ${workspace.branchSource} names it)`}`;
     if (options.format === 'json') {
         io.stdout.write(json('doctor', {
@@ -312,6 +347,7 @@ async function doctorCommand(options, io) {
                 state: claude,
                 ...wiring,
                 detail: describeClaudeCode(wiring),
+                notes: wiringNotes,
                 release: release === null
                     ? { state: 'unchecked', version: null, minimum: CLAUDE_CODE_MINIMUM, detail: 'not asked: nothing wires Claude Code to the guard here' }
                     : { state: release.state, version: 'version' in release ? release.version : null, minimum: CLAUDE_CODE_MINIMUM, detail: describeClaudeRelease(release) },
@@ -331,6 +367,7 @@ async function doctorCommand(options, io) {
             ...more(signerNotes),
             `plugin  ${describePlugin(plugin)}`,
             `claude  ${describeClaudeCode(wiring)}`,
+            ...more(wiringNotes),
             ...more(lineNotes),
             ...more(release === null ? [] : [describeClaudeRelease(release)]),
             `git     ${describeGitHook(hook)}`,
@@ -345,15 +382,19 @@ async function doctorCommand(options, io) {
     // a choice; with none installed, the harness can check nothing. A double
     // install is a problem too, where no Claude Code wiring at all is a choice,
     // and so are a hook whose own line turns the guard off or holds every
-    // write, and a Claude Code too old to run the hooks. A release that cannot
-    // be told is not fine either, nor a line whose reading cannot be: --strict
-    // fails both.
+    // write, guard hooks that disableAllHooks switches off, a plugin that is
+    // turned on and is not on this machine where no hook of init's stands in
+    // for it, and a Claude Code too old to run the hooks. A release that
+    // cannot be told is not fine either, nor a line whose reading cannot be,
+    // nor a plugin that cannot be told to be on this machine: --strict fails
+    // the three.
     const outdated = rows.some((row) => row.state === 'outdated');
     const usable = rows.some((row) => row.state === 'found');
     const off = wiring.lines.some((line) => line.state === 'off' || line.state === 'held');
+    const missing = wiring.presence?.state === 'absent' && wiring.hooks.length === 0;
     const tooOld = release?.state === 'outdated';
-    const untold = options.strict && (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown'));
-    return outdated || !usable || claude === 'both' || off || tooOld || untold ? EXIT_FAILED : EXIT_OK;
+    const untold = options.strict && (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown');
+    return outdated || !usable || claude === 'both' || off || switchedOff || missing || tooOld || untold ? EXIT_FAILED : EXIT_OK;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**