@descent-vtt/spec-harness 0.14.0 → 0.16.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.14.0",
+  "version": "0.16.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,112 @@ 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.16.0
+
+`doctor` and `init` see the rest of Claude Code's hook. A line that names
+a brief which is not one holds every write, and `doctor` says so, exit 1,
+where it said the line guards. An entry is read with the event it stands
+under and its matcher, so a line Claude Code never starts before a write
+is no longer reported as the guard. And `init` writes no second line
+beside a line of the hook a person changed, and says of each file what
+`doctor` says of it.
+
+### Changed
+
+- **`doctor` says a hook's line that names a brief which is not one, and
+  exits 1.** `hook claude --brief 404` on the line in Claude Code's settings
+  has the hook hold every write, exit 2, where spec-brief knows no brief 404
+  or has archived it, and `doctor` said of that line that it guards. It now
+  asks spec-brief about the name as the hook does, in the work tree the
+  line's root is in, and says the line in the words the hook holds the write
+  with: `"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`. `--format json` has the line's `state` as
+  `held`. 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 every
+  write was held: name a brief spec-brief lists on the line, or take
+  `--brief` off it.
+- **`doctor` reads the event and the matcher of the hook's entries.** It
+  read neither, so a line under `PostToolUse` alone, or under a matcher such
+  as `Bash`, which Claude Code never starts before a write, was reported as
+  the guard. An entry is now read as Claude Code's hooks reference has it:
+  waited on before a tool call under `PreToolUse` alone, for the tools its
+  matcher lets through, and for none where it runs in the background
+  (`async`, `asyncRewake`). A line waited on before no write is said as not
+  the guard, with what it stands under; one waited on before some of `Edit`,
+  `Write`, `MultiEdit` and `NotebookEdit` guards those, and the rest are
+  named as unchecked; an entry with an `if`, whose rule is not read, or with
+  a matcher that is not text, is no pattern, or is a pattern that takes more
+  than a tenth of a second to test against the four names, is *cannot
+  tell*. `--format
+  json` has `before`, `after` and `cover` on each of `claudeCode.lines`, and
+  the states `unstarted` and `held` beside `guards`, `off` and `unknown`.
+  Upgrading: a settings file whose only line of the hook is started for no
+  write, before one or after, is no longer one of `init`'s entries, so
+  beside the plugin it is no double install, exit 0 where it was 1, and
+  alone `doctor` reports no guard and does not ask Claude Code its release.
+  `doctor --strict` exits 1 for a line whose entry has an `if`, or a matcher
+  it cannot read. A script that reads `claudeCode.lines[].state` meets the
+  two new states.
+- **`init` writes no hook beside a line of the hook that is there.** It knew
+  only the line it writes and the one 0.1 wrote, so beside a line a person
+  had changed, such as `hook claude --root ${CLAUDE_PROJECT_DIR}`, `init
+  --write` added its own, and both ran for every write; and with the Claude
+  Code plugin on beside such a line it said `skip` where `doctor` exits 1
+  for the double install. It now knows the hook as `doctor` knows it, by its
+  command and the words `hook claude`, 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, and says which line it
+  left in `doctor`'s words for it: `keep`, or `advise` where the line turns
+  the guard off, holds every write or is waited on before none. Beside the
+  plugin the file is `advise`, the double install, and so where the line
+  stands in a settings file of your own. It rewrites no line but the one 0.1
+  wrote
+  ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  Upgrading: `init --write` leaves `.claude/settings.json` as it is where it
+  added a second line; a file that holds two since an earlier `init` keeps
+  both, and one of them is yours to take out. A line Claude Code starts for
+  no write, under a matcher that names no writing tool or in the background
+  before a write, no longer counts as installed: `init` writes its hooks
+  beside it. In the programmatic API, `mergeClaudeSettings` takes the
+  hook's reading as an optional second argument; without it, it knows
+  `init`'s own line alone, read with its event and matcher as above.
+
+## 0.15.0
+
+`doctor` reads the line of Claude Code's hook as the hook itself reads it:
+a line with more on it than `init` writes is said to guard where it does,
+and a line the hook cannot read, or whose `--root` is no directory, is said
+as a guard that is off, exit 1, where each was reported as no guard at all
+or not reported.
+
+### Changed
+
+- **`doctor` reads the line of Claude Code's hook as the hook reads it.** It
+  knew the hook only where its command and arguments were exactly what
+  `init` writes, or what 0.1 wrote: a line with `--root
+  ${CLAUDE_PROJECT_DIR}` added by hand, which guards, was reported as
+  `neither the spec-harness plugin nor the hooks init writes, so Claude Code
+  guards no write`, and a line that turns the guard off was reported the
+  same way, with exit 0. It now knows the hook by its command and the words
+  `hook claude`, whatever else is on the line, and reads the rest through
+  the code the hook reads it with. A line that guards with more on it than
+  `init` writes is said as it is and fails nothing. A line the hook cannot
+  read, and a `--root` that is not a directory, are said in the hook's own
+  words, as a guard that is off, and `doctor` exits 1. A line with no
+  `args`, which a shell reads first, is *cannot tell* where the shell would
+  change what follows the command: said, and a failure under `--strict`.
+  `"onFailure": "block"` on the entry is said in a note, with what it
+  changes. `--format json` has each line as `claudeCode.lines`
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a hook's line changed by hand is now the guard to `doctor`, so
+  it asks Claude Code its release for it, and beside the plugin it is the
+  double install it always was, exit 1. Where `doctor` now exits 1 for a
+  line, the guard was off already: mend the line it names, or write
+  `hook claude` and nothing after it, as `init` does. The lines `init` and
+  the plugin wrote are reported as before.
+
 ## 0.14.0
 
 `hook claude` says a line of its own that it cannot read with exit 1 and

package/README.md

@@ -342,7 +342,8 @@ Configures the family to agree. It prints the plan, merges into files that exist
 - **Claude Code**: the guard hooks in `.claude/settings.json` and the MCP server in `.mcp.json`, each run with `node` from the project's `node_modules`. The `npx` entries 0.1 wrote are replaced.
   - 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.
+  - 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.
+  - 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.
   - With `--git-hook` it is written; without, the plan advises it (`advise`).
@@ -374,6 +375,18 @@ 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.
+  - 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.
+  - A line that holds more than `init` writes, such as `--root ${CLAUDE_PROJECT_DIR}` or `--brief 012`, is said as it is and fails nothing: `"hook claude --root ${CLAUDE_PROJECT_DIR}" in .claude/settings.json is more than init writes, and guards: the hook reads the line, and its root, /work/app, is a directory`.
+  - A line the hook cannot read, and a `--root` that is a file or is not there, are a guard that is off. Each is said in the words the hook itself says before a write, and exits 1.
+  - A line that 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 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.
 - **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.
@@ -417,7 +430,7 @@ An option, an argument or a value that is given and names nothing is refused: ex
   - **A `--root` that is a file, or is not there.** It read as a session outside a git work tree, exit 0 and no word, and the guard was off. It is `--root is "nowhere", which is not a directory, so the guard is off and this write is not checked`, with what to do. An empty `--root` is the directory the hook was started in, and guards there, as before.
   - **A line the parser cannot read**: an option no command has, as in `hook claude --nope`; an option left without its value, as `--root $DIR` is in a shell where the variable is not set; a `--format` or an `--at` that is none. Each was exit 2, as it is from every other command, and Claude Code blocks the tool call on a PreToolUse hook's exit 2: every write of the session waited on a line only a write can mend. It is `the hook's line cannot be read (Option '--root <value>' argument missing), so the guard is off and this write is not checked`, with what to do. The parser's own words stand between the brackets, on one line.
 
-  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails, and exit 1 is a failure to it; neither `init` nor the plugin writes that field.
+  Exit 2 from `hook claude` is kept for a write it could not check: a configuration that does not load, briefs that cannot be read, a brief that is named and is not one, an error nothing expected. `hook git` is not read this way. It stops one commit, exit 2, on a line a person reads, who can then mend the hook. Nor is a line that does not say `hook claude`, such as `hook` alone: the harness cannot tell whose it is. A hook entry that sets `"onFailure": "block"`, which Claude Code 2.1.295 and later read, has Claude Code hold the action when the hook fails, and exit 1 is a failure to it; neither `init` nor the plugin writes that field. [`doctor`](#doctor) says each of these of a line it finds in Claude Code's settings, before any write meets it.
 - **`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)).
 

package/dist/answers.js

@@ -134,7 +134,7 @@ export function readArchivePlan(document) {
         const file = read.optionalText(reason['file'], `${where}.file`);
         const line = read.optionalNumber(reason['line'], `${where}.line`);
         const path = read.optionalText(reason['path'], `${where}.path`);
-        return {
+        const carried = {
             rule: read.text(reason['rule'], `${where}.rule`),
             severity: severity,
             message: read.text(reason['message'], `${where}.message`),
@@ -143,6 +143,7 @@ export function readArchivePlan(document) {
             line,
             path,
         };
+        return carried;
     });
     return { blocking: reasons('blocking'), warnings: reasons('warnings') };
 }

package/dist/answers.js.map

@@ -1 +1 @@
-{"version":3,"file":"answers.js","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What spec-guard and spec-brief answer in JSON, besides the brief list\n * briefs.ts reads: a query's rules, a run's results and errors, and an\n * archive's plan. Each is checked for the fields the harness reads, with the\n * types it reads them as, and a document of another shape is an error that\n * names the tool and the field (ADR-0002): the command that asked stops with\n * exit 2, as for any sibling that printed something it cannot read, rather\n * than crash halfway through the document or count what it could not read as\n * clean. Fields the harness does not read are not checked, so a sibling may\n * add to its documents freely.\n */\n\nimport type { ArchiveReason } from './audit.js';\nimport { SiblingOutputError } from './briefs.js';\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Reads fields of one document, naming the tool, its command and the field in every refusal. */\nfunction reader(printer: string) {\n  const refuse = (where: string, expected: string): never => {\n    throw new SiblingOutputError(`${printer} printed ${where} that is not ${expected}`);\n  };\n  return {\n    object(value: unknown, where: string): Json {\n      return isObject(value) ? value : refuse(where, 'an object');\n    },\n    /** A list that is absent is an empty one. */\n    list(value: unknown, where: string): unknown[] {\n      if (value === undefined) return [];\n      return Array.isArray(value) ? (value as unknown[]) : refuse(where, 'a list');\n    },\n    text(value: unknown, where: string): string {\n      return typeof value === 'string' ? value : refuse(where, 'text');\n    },\n    optionalText(value: unknown, where: string): string | undefined {\n      return value === undefined ? undefined : typeof value === 'string' ? value : refuse(where, 'text');\n    },\n    number(value: unknown, where: string): number {\n      return typeof value === 'number' ? value : refuse(where, 'a number');\n    },\n    optionalNumber(value: unknown, where: string): number | undefined {\n      return value === undefined ? undefined : typeof value === 'number' ? value : refuse(where, 'a number');\n    },\n    flag(value: unknown, where: string): boolean {\n      return typeof value === 'boolean' ? value : refuse(where, 'true or false');\n    },\n    refuse,\n  };\n}\n\n/** Where spec-guard places a directive. */\nexport interface Spec {\n  readonly file: string;\n  readonly line: number;\n}\n\nexport interface QueryRule {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n  /** Absent from a document that says nothing of it, which is in force. */\n  readonly inForce: boolean;\n}\n\n/** The rules in each of the results of `spec-guard query --json`, in order. */\nexport function readQueryRules(document: unknown): QueryRule[][] {\n  const read = reader('spec-guard query');\n  const top = read.object(document, 'a document');\n  return read.list(top['results'], 'results').map((value, index) => {\n    const result = read.object(value, `results[${index}]`);\n    return read.list(result['rules'], `results[${index}].rules`).map((ruleValue, at) => {\n      const where = `results[${index}].rules[${at}]`;\n      const rule = read.object(ruleValue, where);\n      const reason = rule['reason'];\n      if (reason !== undefined && reason !== null && typeof reason !== 'string') read.refuse(`${where}.reason`, 'text or null');\n      const inForce = rule['inForce'];\n      return {\n        document: read.text(rule['document'], `${where}.document`),\n        line: read.number(rule['line'], `${where}.line`),\n        kind: read.text(rule['kind'], `${where}.kind`),\n        description: read.text(rule['description'], `${where}.description`),\n        reason: typeof reason === 'string' ? reason : null,\n        inForce: inForce === undefined ? true : read.flag(inForce, `${where}.inForce`),\n      };\n    });\n  });\n}\n\n/**\n * The spec patterns `spec-guard query --json` says matched no file, as\n * written. A document that says nothing of them names none: spec-guard has\n * written the field since 0.22.0, and only where there is such a pattern.\n */\nexport function readQueryUnmatched(document: unknown): string[] {\n  const read = reader('spec-guard query');\n  const top = read.object(document, 'a document');\n  return read.list(top['unmatchedSpecs'], 'unmatchedSpecs').map((value, index) => read.text(value, `unmatchedSpecs[${index}]`));\n}\n\nexport interface GuardResult {\n  readonly ok: boolean;\n  readonly description: string;\n  readonly message: string;\n  readonly spec?: Spec | undefined;\n}\n\nexport interface GuardError {\n  readonly message: string;\n  readonly raw: string;\n  readonly spec?: Spec | undefined;\n}\n\n/** The results and the unreadable directives of a spec-guard run over briefs, `--json`. */\nexport function readGuardRun(document: unknown): { results: GuardResult[]; errors: GuardError[] } {\n  const read = reader('spec-guard');\n  const top = read.object(document, 'a document');\n  const spec = (value: unknown, where: string): Spec | undefined => {\n    if (value === undefined) return undefined;\n    const placed = read.object(value, where);\n    return { file: read.text(placed['file'], `${where}.file`), line: read.number(placed['line'], `${where}.line`) };\n  };\n  const results = read.list(top['results'], 'results').map((value, index) => {\n    const where = `results[${index}]`;\n    const result = read.object(value, where);\n    return {\n      ok: read.flag(result['ok'], `${where}.ok`),\n      description: read.text(result['description'], `${where}.description`),\n      message: read.text(result['message'], `${where}.message`),\n      spec: spec(result['spec'], `${where}.spec`),\n    };\n  });\n  const errors = read.list(top['errors'], 'errors').map((value, index) => {\n    const where = `errors[${index}]`;\n    const error = read.object(value, where);\n    return {\n      message: read.text(error['message'], `${where}.message`),\n      raw: read.optionalText(error['raw'], `${where}.raw`) ?? '',\n      spec: spec(error['spec'], `${where}.spec`),\n    };\n  });\n  return { results, errors };\n}\n\nconst SEVERITIES: readonly string[] = ['error', 'warning', 'note'];\n\n/**\n * What `spec-brief archive --dry-run --format json` would refuse and warn\n * about. A document with no plan plans nothing to refuse. spec-brief gives a\n * reason without a hint where it has no next step, and the reason is carried\n * as it gave it: a field it left out is undefined, which JSON leaves out too.\n */\nexport function readArchivePlan(document: unknown): { blocking: ArchiveReason[]; warnings: ArchiveReason[] } {\n  const read = reader('spec-brief archive');\n  const top = read.object(document, 'a document');\n  if (top['plan'] === undefined) return { blocking: [], warnings: [] };\n  const plan = read.object(top['plan'], 'plan');\n  const reasons = (key: 'blocking' | 'warnings'): ArchiveReason[] =>\n    read.list(plan[key], `plan.${key}`).map((value, index) => {\n      const where = `plan.${key}[${index}]`;\n      const reason = read.object(value, where);\n      const severity = read.text(reason['severity'], `${where}.severity`);\n      if (!SEVERITIES.includes(severity)) read.refuse(`${where}.severity`, 'error, warning or note');\n      const hint = read.optionalText(reason['hint'], `${where}.hint`);\n      const file = read.optionalText(reason['file'], `${where}.file`);\n      const line = read.optionalNumber(reason['line'], `${where}.line`);\n      const path = read.optionalText(reason['path'], `${where}.path`);\n      return {\n        rule: read.text(reason['rule'], `${where}.rule`),\n        severity: severity as ArchiveReason['severity'],\n        message: read.text(reason['message'], `${where}.message`),\n        hint,\n        file,\n        line,\n        path,\n      } as ArchiveReason;\n    });\n  return { blocking: reasons('blocking'), warnings: reasons('warnings') };\n}\n"]}
+{"version":3,"file":"answers.js","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What spec-guard and spec-brief answer in JSON, besides the brief list\n * briefs.ts reads: a query's rules, a run's results and errors, and an\n * archive's plan. Each is checked for the fields the harness reads, with the\n * types it reads them as, and a document of another shape is an error that\n * names the tool and the field (ADR-0002): the command that asked stops with\n * exit 2, as for any sibling that printed something it cannot read, rather\n * than crash halfway through the document or count what it could not read as\n * clean. Fields the harness does not read are not checked, so a sibling may\n * add to its documents freely.\n */\n\nimport type { ArchiveReason } from './audit.js';\nimport { SiblingOutputError } from './briefs.js';\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Reads fields of one document, naming the tool, its command and the field in every refusal. */\nfunction reader(printer: string) {\n  const refuse = (where: string, expected: string): never => {\n    throw new SiblingOutputError(`${printer} printed ${where} that is not ${expected}`);\n  };\n  return {\n    object(value: unknown, where: string): Json {\n      return isObject(value) ? value : refuse(where, 'an object');\n    },\n    /** A list that is absent is an empty one. */\n    list(value: unknown, where: string): unknown[] {\n      if (value === undefined) return [];\n      return Array.isArray(value) ? (value as unknown[]) : refuse(where, 'a list');\n    },\n    text(value: unknown, where: string): string {\n      return typeof value === 'string' ? value : refuse(where, 'text');\n    },\n    optionalText(value: unknown, where: string): string | undefined {\n      return value === undefined ? undefined : typeof value === 'string' ? value : refuse(where, 'text');\n    },\n    number(value: unknown, where: string): number {\n      return typeof value === 'number' ? value : refuse(where, 'a number');\n    },\n    optionalNumber(value: unknown, where: string): number | undefined {\n      return value === undefined ? undefined : typeof value === 'number' ? value : refuse(where, 'a number');\n    },\n    flag(value: unknown, where: string): boolean {\n      return typeof value === 'boolean' ? value : refuse(where, 'true or false');\n    },\n    refuse,\n  };\n}\n\n/** Where spec-guard places a directive. */\nexport interface Spec {\n  readonly file: string;\n  readonly line: number;\n}\n\nexport interface QueryRule {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n  /** Absent from a document that says nothing of it, which is in force. */\n  readonly inForce: boolean;\n}\n\n/** The rules in each of the results of `spec-guard query --json`, in order. */\nexport function readQueryRules(document: unknown): QueryRule[][] {\n  const read = reader('spec-guard query');\n  const top = read.object(document, 'a document');\n  return read.list(top['results'], 'results').map((value, index) => {\n    const result = read.object(value, `results[${index}]`);\n    return read.list(result['rules'], `results[${index}].rules`).map((ruleValue, at) => {\n      const where = `results[${index}].rules[${at}]`;\n      const rule = read.object(ruleValue, where);\n      const reason = rule['reason'];\n      if (reason !== undefined && reason !== null && typeof reason !== 'string') read.refuse(`${where}.reason`, 'text or null');\n      const inForce = rule['inForce'];\n      return {\n        document: read.text(rule['document'], `${where}.document`),\n        line: read.number(rule['line'], `${where}.line`),\n        kind: read.text(rule['kind'], `${where}.kind`),\n        description: read.text(rule['description'], `${where}.description`),\n        reason: typeof reason === 'string' ? reason : null,\n        inForce: inForce === undefined ? true : read.flag(inForce, `${where}.inForce`),\n      };\n    });\n  });\n}\n\n/**\n * The spec patterns `spec-guard query --json` says matched no file, as\n * written. A document that says nothing of them names none: spec-guard has\n * written the field since 0.22.0, and only where there is such a pattern.\n */\nexport function readQueryUnmatched(document: unknown): string[] {\n  const read = reader('spec-guard query');\n  const top = read.object(document, 'a document');\n  return read.list(top['unmatchedSpecs'], 'unmatchedSpecs').map((value, index) => read.text(value, `unmatchedSpecs[${index}]`));\n}\n\nexport interface GuardResult {\n  readonly ok: boolean;\n  readonly description: string;\n  readonly message: string;\n  readonly spec?: Spec | undefined;\n}\n\nexport interface GuardError {\n  readonly message: string;\n  readonly raw: string;\n  readonly spec?: Spec | undefined;\n}\n\n/** The results and the unreadable directives of a spec-guard run over briefs, `--json`. */\nexport function readGuardRun(document: unknown): { results: GuardResult[]; errors: GuardError[] } {\n  const read = reader('spec-guard');\n  const top = read.object(document, 'a document');\n  const spec = (value: unknown, where: string): Spec | undefined => {\n    if (value === undefined) return undefined;\n    const placed = read.object(value, where);\n    return { file: read.text(placed['file'], `${where}.file`), line: read.number(placed['line'], `${where}.line`) };\n  };\n  const results = read.list(top['results'], 'results').map((value, index) => {\n    const where = `results[${index}]`;\n    const result = read.object(value, where);\n    return {\n      ok: read.flag(result['ok'], `${where}.ok`),\n      description: read.text(result['description'], `${where}.description`),\n      message: read.text(result['message'], `${where}.message`),\n      spec: spec(result['spec'], `${where}.spec`),\n    };\n  });\n  const errors = read.list(top['errors'], 'errors').map((value, index) => {\n    const where = `errors[${index}]`;\n    const error = read.object(value, where);\n    return {\n      message: read.text(error['message'], `${where}.message`),\n      raw: read.optionalText(error['raw'], `${where}.raw`) ?? '',\n      spec: spec(error['spec'], `${where}.spec`),\n    };\n  });\n  return { results, errors };\n}\n\nconst SEVERITIES: readonly string[] = ['error', 'warning', 'note'];\n\n/**\n * What `spec-brief archive --dry-run --format json` would refuse and warn\n * about. A document with no plan plans nothing to refuse. spec-brief gives a\n * reason without a hint where it has no next step, and the reason is carried\n * as it gave it: a field it left out is undefined, which JSON leaves out too.\n */\nexport function readArchivePlan(document: unknown): { blocking: ArchiveReason[]; warnings: ArchiveReason[] } {\n  const read = reader('spec-brief archive');\n  const top = read.object(document, 'a document');\n  if (top['plan'] === undefined) return { blocking: [], warnings: [] };\n  const plan = read.object(top['plan'], 'plan');\n  const reasons = (key: 'blocking' | 'warnings'): ArchiveReason[] =>\n    read.list(plan[key], `plan.${key}`).map((value, index) => {\n      const where = `plan.${key}[${index}]`;\n      const reason = read.object(value, where);\n      const severity = read.text(reason['severity'], `${where}.severity`);\n      if (!SEVERITIES.includes(severity)) read.refuse(`${where}.severity`, 'error, warning or note');\n      const hint = read.optionalText(reason['hint'], `${where}.hint`);\n      const file = read.optionalText(reason['file'], `${where}.file`);\n      const line = read.optionalNumber(reason['line'], `${where}.line`);\n      const path = read.optionalText(reason['path'], `${where}.path`);\n      const carried = {\n        rule: read.text(reason['rule'], `${where}.rule`),\n        severity: severity as ArchiveReason['severity'],\n        message: read.text(reason['message'], `${where}.message`),\n        hint,\n        file,\n        line,\n        path,\n      };\n      return carried as ArchiveReason;\n    });\n  return { blocking: reasons('blocking'), warnings: reasons('warnings') };\n}\n"]}

package/dist/branch.js

@@ -25,6 +25,11 @@ function isIdChar(ch) {
  */
 function prefixEnds(prefix, name) {
     // reach[j]: the prefix read so far can end at name offset j.
+    // An offset nothing was written at reads as one that cannot be reached,
+    // and `forEach` passes over it. So a list made with no places, here and
+    // for `next`, is equivalent to its mutant, and so is one made two places
+    // short, for every name but the empty one, whose list would have fewer
+    // places than none: a test holds that name.
     let reach = new Array(name.length + 1).fill(false);
     reach[0] = true;
     for (const token of prefix) {
@@ -41,12 +46,17 @@ function prefixEnds(prefix, name) {
             }
         }
         else {
+            // One place past the end `charAt` gives the empty string, which is no
+            // token, so `<=` for `<` is equivalent.
             for (let j = 0; j < name.length; j += 1)
                 if (reach[j] && name.charAt(j) === token)
                     next[j + 1] = true;
         }
         reach = next;
     }
+    // `idFromBranch` reads an id from each offset and passes over one where
+    // none starts, which a text among them is: a list that starts with one is
+    // equivalent.
     const ends = [];
     reach.forEach((ok, j) => {
         if (ok)
@@ -70,6 +80,8 @@ export function idFromBranch(template, name) {
     const prefix = template.slice(0, -'{id}'.length);
     for (const start of prefixEnds(prefix, name)) {
         let end = start;
+        // Past the end `charAt` gives the empty string, which is no character of
+        // an id, so the bound is equivalent to its mutants.
         while (end < name.length && isIdChar(name.charAt(end)))
             end += 1;
         if (end === start)

package/dist/branch.js.map

@@ -1 +1 @@
-{"version":3,"file":"branch.js","sourceRoot":"","sources":["../src/branch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which brief a branch is working on, read from its name.\n *\n * A round runs on a branch, and naming the branch after the brief is the one\n * convention every repository that runs agents on briefs already has. Reading\n * it from there keeps the harness stateless: no file says which brief is\n * active, so no file can say it wrongly (ADR-0004).\n *\n * A template is a branch name with `{id}` where the id goes and `*` for any\n * run of characters other than `/`: `brief/{id}`, `*\\/brief-{id}`. The id is\n * the longest run of letters and digits at that point, and must be followed\n * by the end of the name or a separator - so `brief/012-rotate-tokens` names\n * 012, and `brief/012x` names 012x, never 012.\n */\n\nconst SEPARATORS = new Set(['-', '_', '/', '.']);\n\nfunction isIdChar(ch: string): boolean {\n  // Asked of one character at a time, so the mutants that drop either anchor\n  // are equivalent.\n  return /^[A-Za-z0-9]$/.test(ch);\n}\n\n/**\n * The offsets in `name` at which a template prefix can end, by dynamic\n * programming over prefix and name, so a template of many stars costs their\n * product and never an exponent.\n */\nfunction prefixEnds(prefix: string, name: string): number[] {\n  // reach[j]: the prefix read so far can end at name offset j.\n  let reach: boolean[] = new Array<boolean>(name.length + 1).fill(false);\n  reach[0] = true;\n  for (const token of prefix) {\n    const next = new Array<boolean>(name.length + 1).fill(false);\n    if (token === '*') {\n      let open = false;\n      for (let j = 0; j <= name.length; j += 1) {\n        if (reach[j]) open = true;\n        if (open) next[j] = true;\n        if (name.charAt(j) === '/') open = false;\n      }\n    } else {\n      for (let j = 0; j < name.length; j += 1) if (reach[j] && name.charAt(j) === token) next[j + 1] = true;\n    }\n    reach = next;\n  }\n  const ends: number[] = [];\n  reach.forEach((ok, j) => {\n    if (ok) ends.push(j);\n  });\n  return ends;\n}\n\n/** Why a template cannot be used, or `null`. */\nexport function templateError(template: string): string | null {\n  const count = template.split('{id}').length - 1;\n  if (count !== 1) return `\"${template}\" must contain {id} exactly once`;\n  if (!template.endsWith('{id}')) return `\"${template}\" must end with {id}; whatever follows the id is the branch's own`;\n  return null;\n}\n\n/** The brief id a branch name carries under one template, or `null`. */\nexport function idFromBranch(template: string, name: string): string | null {\n  if (templateError(template) !== null) return null;\n  const prefix = template.slice(0, -'{id}'.length);\n  for (const start of prefixEnds(prefix, name)) {\n    let end = start;\n    while (end < name.length && isIdChar(name.charAt(end))) end += 1;\n    if (end === start) continue;\n    if (end < name.length && !SEPARATORS.has(name.charAt(end))) continue;\n    return name.slice(start, end);\n  }\n  return null;\n}\n\n/**\n * The branch a CI run is building, as the forge names it, for a checkout on\n * no branch: CI checks out a commit, and without the branch a round's own\n * run would name no brief. In order: a GitHub pull request's head branch; the\n * branch a GitHub push built; a GitLab merge request's source branch; the\n * branch a GitLab pipeline built. Each is set only where it names a branch -\n * GitHub's `GITHUB_REF_NAME` names a tag too, so only when `GITHUB_REF_TYPE`\n * says `branch` - and an empty one is not set. `null` outside CI.\n */\nexport function ciBranch(env: Readonly<Record<string, string | undefined>>): { readonly branch: string; readonly source: string } | null {\n  const named = (name: string): { branch: string; source: string } | null => {\n    const value = env[name]?.trim() ?? '';\n    return value === '' ? null : { branch: value, source: name };\n  };\n  return (\n    named('GITHUB_HEAD_REF') ??\n    (env['GITHUB_REF_TYPE'] === 'branch' ? named('GITHUB_REF_NAME') : null) ??\n    named('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME') ??\n    named('CI_COMMIT_BRANCH')\n  );\n}\n\n/** The first template that yields an id, in order; `null` for a head on no branch, which names no brief. */\nexport function briefIdFromBranch(templates: readonly string[], name: string | null): string | null {\n  if (name === null) return null;\n  for (const template of templates) {\n    const id = idFromBranch(template, name);\n    if (id !== null) return id;\n  }\n  return null;\n}\n\n/**\n * Whether two ids name the same brief: equal as written, or equal as numbers\n * when both are all digits, since a branch says `brief/12` of a brief whose\n * file says `012`.\n */\nexport function sameId(a: string, b: string): boolean {\n  if (a === b) return true;\n  return /^\\d+$/.test(a) && /^\\d+$/.test(b) && BigInt(a) === BigInt(b);\n}\n"]}
+{"version":3,"file":"branch.js","sourceRoot":"","sources":["../src/branch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which brief a branch is working on, read from its name.\n *\n * A round runs on a branch, and naming the branch after the brief is the one\n * convention every repository that runs agents on briefs already has. Reading\n * it from there keeps the harness stateless: no file says which brief is\n * active, so no file can say it wrongly (ADR-0004).\n *\n * A template is a branch name with `{id}` where the id goes and `*` for any\n * run of characters other than `/`: `brief/{id}`, `*\\/brief-{id}`. The id is\n * the longest run of letters and digits at that point, and must be followed\n * by the end of the name or a separator - so `brief/012-rotate-tokens` names\n * 012, and `brief/012x` names 012x, never 012.\n */\n\nconst SEPARATORS = new Set(['-', '_', '/', '.']);\n\nfunction isIdChar(ch: string): boolean {\n  // Asked of one character at a time, so the mutants that drop either anchor\n  // are equivalent.\n  return /^[A-Za-z0-9]$/.test(ch);\n}\n\n/**\n * The offsets in `name` at which a template prefix can end, by dynamic\n * programming over prefix and name, so a template of many stars costs their\n * product and never an exponent.\n */\nfunction prefixEnds(prefix: string, name: string): number[] {\n  // reach[j]: the prefix read so far can end at name offset j.\n  // An offset nothing was written at reads as one that cannot be reached,\n  // and `forEach` passes over it. So a list made with no places, here and\n  // for `next`, is equivalent to its mutant, and so is one made two places\n  // short, for every name but the empty one, whose list would have fewer\n  // places than none: a test holds that name.\n  let reach: boolean[] = new Array<boolean>(name.length + 1).fill(false);\n  reach[0] = true;\n  for (const token of prefix) {\n    const next = new Array<boolean>(name.length + 1).fill(false);\n    if (token === '*') {\n      let open = false;\n      for (let j = 0; j <= name.length; j += 1) {\n        if (reach[j]) open = true;\n        if (open) next[j] = true;\n        if (name.charAt(j) === '/') open = false;\n      }\n    } else {\n      // One place past the end `charAt` gives the empty string, which is no\n      // token, so `<=` for `<` is equivalent.\n      for (let j = 0; j < name.length; j += 1) if (reach[j] && name.charAt(j) === token) next[j + 1] = true;\n    }\n    reach = next;\n  }\n  // `idFromBranch` reads an id from each offset and passes over one where\n  // none starts, which a text among them is: a list that starts with one is\n  // equivalent.\n  const ends: number[] = [];\n  reach.forEach((ok, j) => {\n    if (ok) ends.push(j);\n  });\n  return ends;\n}\n\n/** Why a template cannot be used, or `null`. */\nexport function templateError(template: string): string | null {\n  const count = template.split('{id}').length - 1;\n  if (count !== 1) return `\"${template}\" must contain {id} exactly once`;\n  if (!template.endsWith('{id}')) return `\"${template}\" must end with {id}; whatever follows the id is the branch's own`;\n  return null;\n}\n\n/** The brief id a branch name carries under one template, or `null`. */\nexport function idFromBranch(template: string, name: string): string | null {\n  if (templateError(template) !== null) return null;\n  const prefix = template.slice(0, -'{id}'.length);\n  for (const start of prefixEnds(prefix, name)) {\n    let end = start;\n    // Past the end `charAt` gives the empty string, which is no character of\n    // an id, so the bound is equivalent to its mutants.\n    while (end < name.length && isIdChar(name.charAt(end))) end += 1;\n    if (end === start) continue;\n    if (end < name.length && !SEPARATORS.has(name.charAt(end))) continue;\n    return name.slice(start, end);\n  }\n  return null;\n}\n\n/**\n * The branch a CI run is building, as the forge names it, for a checkout on\n * no branch: CI checks out a commit, and without the branch a round's own\n * run would name no brief. In order: a GitHub pull request's head branch; the\n * branch a GitHub push built; a GitLab merge request's source branch; the\n * branch a GitLab pipeline built. Each is set only where it names a branch -\n * GitHub's `GITHUB_REF_NAME` names a tag too, so only when `GITHUB_REF_TYPE`\n * says `branch` - and an empty one is not set. `null` outside CI.\n */\nexport function ciBranch(env: Readonly<Record<string, string | undefined>>): { readonly branch: string; readonly source: string } | null {\n  const named = (name: string): { branch: string; source: string } | null => {\n    const value = env[name]?.trim() ?? '';\n    return value === '' ? null : { branch: value, source: name };\n  };\n  return (\n    named('GITHUB_HEAD_REF') ??\n    (env['GITHUB_REF_TYPE'] === 'branch' ? named('GITHUB_REF_NAME') : null) ??\n    named('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME') ??\n    named('CI_COMMIT_BRANCH')\n  );\n}\n\n/** The first template that yields an id, in order; `null` for a head on no branch, which names no brief. */\nexport function briefIdFromBranch(templates: readonly string[], name: string | null): string | null {\n  if (name === null) return null;\n  for (const template of templates) {\n    const id = idFromBranch(template, name);\n    if (id !== null) return id;\n  }\n  return null;\n}\n\n/**\n * Whether two ids name the same brief: equal as written, or equal as numbers\n * when both are all digits, since a branch says `brief/12` of a brief whose\n * file says `012`.\n */\nexport function sameId(a: string, b: string): boolean {\n  if (a === b) return true;\n  return /^\\d+$/.test(a) && /^\\d+$/.test(b) && BigInt(a) === BigInt(b);\n}\n"]}

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, 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, 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";
 /**
  * Runs the command line and resolves to the exit code, for an error nothing
  * below expected too.

package/dist/cli.js

@@ -19,14 +19,14 @@ import { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
 import { claudeVersion } from './host.js';
 import { premisesCommand } from './premises.js';
 import { createReader } from './reader.js';
-import { checkPaths, claudeCodeWiring, resolveBase, specBriefPlugin } from './round.js';
+import { checkPaths, claudeCodeWiring, diagnoseBrief, resolveBase, specBriefPlugin } from './round.js';
 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, isClaudeHook, noDirectory, refusal } from './usage.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, namedId, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+import { activeBrief, 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
 
@@ -60,7 +60,8 @@ Commands:
   doctor              Which siblings are installed, at which versions, which brief is
                       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, or Claude Code is too old to run its hooks.
+                      installed twice, its hook's line turns it off or holds every
+                      write, 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.
@@ -162,7 +163,7 @@ async function writeAsked(io) {
  * that exits 1 and goes on with the write, where exit 2 would hold every
  * write of the session, the one that mends the line among them (ADR-0005).
  */
-function guardOff(io, wrong, mend) {
+function guardOff(io, { wrong, mend }) {
     io.stderr.write(`spec-harness: ${wrong}, so the guard is off and this write is not checked; ${mend}\n`);
     return EXIT_FAILED;
 }
@@ -170,14 +171,14 @@ function guardOff(io, wrong, mend) {
  * Claude Code's hook on a line the parser refused: an option no command has,
  * an option left without its value, a --format or an --at that is none. It
  * was exit 2 before the question was read, for the line a settings file
- * holds as for one typed at a terminal. The parser's words are kept, on one
- * line: what node says of an option that may have lost its value is three.
+ * holds as for one typed at a terminal. What is said of it is `doctor`'s
+ * to say as well, of a line it finds in a settings file (usage.ts).
  */
-async function unreadHookLine(said, io) {
+async function unreadLine(said, io) {
     const request = await writeAsked(io);
     if (typeof request === 'number')
         return request;
-    return guardOff(io, `the hook's line cannot be read (${said.split('\n').join(' ')})`, 'mend it in Claude Code\'s settings, where init writes "hook claude" and nothing after it');
+    return guardOff(io, unreadHookLine(said).fault);
 }
 async function hookCommand(options, io) {
     const kind = options.positionals[0];
@@ -185,20 +186,15 @@ async function hookCommand(options, io) {
         const request = await writeAsked(io);
         if (typeof request === 'number')
             return request;
-        // An empty root is the directory the hook was started in: git starts
-        // there when it is handed no directory, so the hook has guarded there
-        // for an empty root in every release.
-        const root = options.root === '' ? io.cwd : options.root;
-        // A root written on the hook's line that is a file, or is not there: git
-        // starts in neither, which read as a session outside a work tree, exit 0
-        // and no word, and the guard someone had configured was off.
-        if (root !== undefined && !isDirectory(root)) {
-            return guardOff(io, noDirectory(root), "give the hook's line a directory that exists, or leave --root out for the project Claude Code names");
-        }
+        // The root the line gives, or what is wrong with it: read as `doctor`
+        // reads the line where it finds it in a settings file (usage.ts).
+        const line = readHookLine(options.root, io.cwd, isDirectory);
+        if (line.state === 'off')
+            return guardOff(io, line.fault);
         const cwd = request.cwd ?? io.cwd;
         let workspace;
         try {
-            workspace = await openWorkspace({ ...options, root: root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);
+            workspace = await openWorkspace({ ...options, root: line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);
         }
         catch (error) {
             if (error instanceof UsageError)
@@ -208,8 +204,10 @@ async function hookCommand(options, io) {
         try {
             const decided = await decisionsFor(workspace, options, io, request.paths, cwd);
             if ('problem' in decided) {
-                // Exit 2 blocks the tool call, and its stderr reaches the model.
-                io.stderr.write(`spec-harness: ${decided.problem}. Fix the brief or the branch before writing.\n`);
+                // Exit 2 blocks the tool call, and its stderr reaches the model. Where
+                // the name stands on the hook's own line, what is wrong with it is
+                // `doctor`'s to say as well, in the same words (usage.ts).
+                io.stderr.write(`spec-harness: ${heldHookLine(decided.problem).wrong}. Fix the brief or the branch before writing.\n`);
                 return EXIT_ERROR;
             }
             const response = claudeResponse(request.event, decided.decisions);
@@ -243,32 +241,6 @@ 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) => {
@@ -305,8 +277,14 @@ async function doctorCommand(options, io) {
     const plugin = await specBriefPlugin(workspace.root);
     // 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.env);
+    const wiring = await claudeCodeWiring(workspace.root, io);
     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
+    // guard off or holds every write, one only a shell can read, the writes
+    // 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));
@@ -353,6 +331,7 @@ async function doctorCommand(options, io) {
             ...more(signerNotes),
             `plugin  ${describePlugin(plugin)}`,
             `claude  ${describeClaudeCode(wiring)}`,
+            ...more(lineNotes),
             ...more(release === null ? [] : [describeClaudeRelease(release)]),
             `git     ${describeGitHook(hook)}`,
             ...more(hookNote === null ? [] : [hookNote]),
@@ -365,13 +344,16 @@ async function doctorCommand(options, io) {
     // An outdated sibling is a problem to fix, where a missing optional one is
     // 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 is a Claude Code too old to run the hooks. One whose release
-    // cannot be told is not fine either: --strict fails it.
+    // 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.
     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 tooOld = release?.state === 'outdated';
-    const untold = options.strict && release?.state === 'unknown';
-    return outdated || !usable || claude === 'both' || tooOld || untold ? EXIT_FAILED : EXIT_OK;
+    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;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**
@@ -407,7 +389,7 @@ async function dispatch(argv, io) {
         // write for it.
         const refused = error;
         if (isClaudeHook(refused.words[0], refused.words[1]))
-            return unreadHookLine(refused.message, io);
+            return unreadLine(refused.message, io);
         io.stderr.write(`spec-harness: ${refused.message}\n`);
         return EXIT_ERROR;
     }