@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.18.0",
+  "version": "0.20.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,378 @@ 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.20.0
+
+The hook decides each path by the work tree that holds it, a third
+worktree's and the MCP server's included, and finds siblings in the main
+checkout's install wherever a work tree has none; every process it starts
+has a time limit, and it reads only a file where a file is expected, so a
+named pipe no longer holds it without end; it says a guard that is off with
+exit 0, and `init --block-on-failure` asks Claude Code to hold a write when
+the hook cannot start. It gives a session spec-brief's answer again where
+nothing that answer was read from has changed, and it can report, at the end
+of a turn and where the configuration asks for it, what the work tree holds
+that the brief protects or that is outside its scope
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+[ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+
+A configuration that does not load lets a write to itself through, so
+that a session can mend it; a write outside every work tree of the
+repository is held by no brief and no configuration; and `doctor` fails
+where the branch names a brief no round can work under
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+[ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+
+`doctor` says a line of Claude Code's hook that asks for the help or the
+version as a guard that is off, fails `--strict` where git cannot say
+where it runs its hooks, and notes in a linked worktree the release the
+hook's line runs; a `.spec-harness.json` that cannot be read is said as
+that; and on Windows a drive letter is one in either case
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+### Added
+
+- **A report at the end of a turn, where `.spec-harness.json` asks for
+  one.** With `"turnReport": true`, `hook claude` answers Claude Code's
+  `Stop`: with one `git status`, every path the work tree holds changed
+  that the brief protects or that is outside its scope, a shell's writes
+  among them, in the words a write of it is given, as one `systemMessage`,
+  exit 0, and never a field that has Claude go on. `init` writes the entry,
+  in the background, where the key is on, and Claude reads the report as the
+  next turn begins; the plugin carries none, and with it on `init` says
+  what to add
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+  [ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  Upgrading: off by default, so nothing changes until the key is turned on
+  and `spec-harness init --write` run again. A `Stop` entry aimed at the
+  hook exited 1, `the hook input names no event or tool`, and now exits 0;
+  a configuration's unknown key is refused with `turnReport` among the keys
+  it names.
+- **`init --block-on-failure` writes `"onFailure": "block"` on its hook
+  entries before and after a write and as a session starts**, and on those
+  an earlier run wrote, so that Claude Code 2.1.295 or later holds a write
+  where the hook cannot start, as in a worktree with no install, or runs
+  past its timeout. It is written only
+  where asked for, and the plugin does not carry it: no page says what an
+  older release does with the key. `doctor` advises it in a note, failing
+  nothing, for a line that guards without it where the Claude Code on
+  `PATH` reads the field
+  ([ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  The entry at the end of a turn is left without it: it runs in the
+  background, where the hooks reference gives the field no effect.
+- **`doctor`, run in a linked worktree, notes the release the hook's line
+  runs.** The line names its script under `${CLAUDE_PROJECT_DIR}`, which
+  in a worktree session of the desktop app is the main checkout. Where the
+  main checkout's install of spec-harness and the worktree's are not one
+  release, a note names both; it fails nothing.
+
+### Changed
+
+- **The hook gives a session spec-brief's list of the briefs again, where
+  nothing it was read from has changed.** On a brief's branch the hook
+  started spec-brief before every write, most of what a write waited for on
+  Windows. Where spec-brief's `list --format json` names everything its
+  answer was read from, its `inputs`, the hook keeps the answer for the
+  session under the git common directory, in `spec-harness/answers/`, and
+  gives it again to the session's later runs while every file, directory
+  and index on the list reads as listed, with no process started; anything
+  else starts spec-brief as before. No answer changes
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md),
+  [ADR-0003](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0003-state-outside-the-work-tree.md)).
+  Upgrading: nothing to change. A spec-brief whose `list` names no
+  `inputs`, 0.9.0 and every release before it, is started before every
+  write as it was.
+- **A process the harness asks a question of is stopped after 20 seconds,
+  and the hook holds the write there.** git had no limit and spec-brief
+  ten minutes, where Claude Code cancels the hook at the 60 seconds its
+  entry gives it, and before a write lets the write go ahead: a named pipe
+  at `.spec-brief.json` or `.git/config` kept the hook, `doctor` and
+  every command from coming back. git's reads and spec-brief's list are
+  now stopped at 20 seconds and said, `spec-brief did not answer within
+  20 seconds, and was stopped`; before a write that is `cannot check this
+  write: ...`, exit 2, which holds it. A round's work, a diff, a probe's
+  worktree, a sibling's check, keeps ten minutes
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+  Upgrading: where git or spec-brief takes longer than 20 seconds to
+  answer, which none measured does, writes are held and commands exit 2
+  with the line: find what it waits on.
+- **A path is decided by the work tree that holds it.** A path in a work
+  tree of the repository that was neither the one the project names nor
+  the one the question's `cwd` is in was read from the project's top, as a
+  file of `.claude/worktrees/<name>/` under the project's branch or as one
+  outside the project, and a write its own brief protects passed with no
+  word. That work tree now decides it, by its branch, briefs and
+  configuration; a nested repository's file is decided as before
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a session that writes into another worktree has the write
+  refused where that worktree's brief protects it.
+- **Every command finds the siblings in the main work tree's install** where
+  a linked worktree has none, as git's hook and `doctor` did: `guard`,
+  `context`, `audit`, `probe` and the rest exited 2, `spec-brief is not
+  installed here`.
+  Upgrading: in such a worktree these commands run, and `guard` and
+  `audit` can exit 1 where they exited 2.
+- **The server reads the work tree a path is in, and the round in the one
+  its client names.** `check_path` read every path as the project's, and
+  every tool the project's branch, so a worktree's file read as
+  `.claude/worktrees/<name>/...` and its brief went unnamed. `check_path`
+  decides an absolute path by the work tree of the repository that holds
+  it, and `start_round`, `check_path`, `request_escalation` and
+  `audit_round` read the round in the work tree a new `directory`
+  argument names, else the one the client's roots name where they name
+  exactly one of the repository's, else the project's, and say which as
+  `workTree`
+  ([ADR-0008](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0008-one-server-for-rounds.md)).
+  Upgrading: a client that declares roots naming a worktree has its calls
+  answered for that worktree; a script reading the tools' structured
+  answers finds `workTree`.
+- **The hook says the guard is off with exit 0, where it exited 1.** A
+  question it cannot read and a line of its own that turns the guard off
+  (one it cannot read, a `--root` that is no directory) were one line on
+  stderr and exit 1, which Claude Code counts as a hook that failed: under
+  `"onFailure": "block"` that held every write of the session, the one
+  that mends the line among them. Each is now the same line to the person,
+  as `systemMessage`, and exit 0, and the write goes on as it did, so
+  `onFailure` holds only a hook that did not run
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a script that read the hook's exit 1 or its stderr reads the
+  line as `systemMessage` on stdout, with exit 0.
+- **A write to `.spec-harness.json` itself goes on while it does not
+  load.** Every write was held, exit 2, the one that mends the file among
+  them, so a session could not mend a typo in it. Before a write to that
+  file and to nothing else, the hook now decides nothing, exit 0, so the
+  person's own permission prompt stands, and says why every other write is
+  held, to the person and to Claude. A file of that name elsewhere, a link
+  to it, a second name of it and the configuration of another work tree
+  are held as before, and so is a configuration that is a directory, a
+  named pipe, or a link to a file of the repository. As a session starts
+  the hook says the same.
+  Upgrading: a brief that protects `.spec-harness.json` does not hold that
+  write while the file does not load, since none of it is read; the audit
+  and spec-brief's archive still measure the change.
+- **`doctor` exits 1 where the branch names a brief spec-brief does not
+  know, or has archived.** The hook holds every write on such a branch,
+  and `doctor` said so on its `brief` line and exited 0. One the flag or
+  `SPEC_BRIEF` names still fails nothing.
+  Upgrading: a branch whose name only reads as a brief's, as
+  `fix/brief-list-order` names `list` under the default `branches`, fails
+  `doctor` as it holds every write: rename the branch, or set `branches` in
+  `.spec-harness.json`.
+- **A write outside every work tree of the repository is not held by what
+  holds the writes inside.** A brief that is archived, or that spec-brief
+  does not list, whichever names it, and a configuration that does not
+  load held every write, a file outside the repository among them, and
+  `guard` refused such a path, exit 2. Such a write passes as one outside
+  the repository does, with no word, and spec-brief is not asked about it;
+  one inside any work tree of the repository, a linked worktree's among
+  them, is decided as before, by the work tree that holds it, and a path
+  with a `..` in it is held as before.
+  Upgrading: `guard` of a path outside the repository exits 0 under such
+  a brief, where it exited 2.
+- **A hook line that asks for the help or the version is a guard that is
+  off.** `hook claude --help`, `--version`, `-h` and `-v` print the help
+  or the version, exit 0, and check no write, which Claude Code takes for a
+  hook that succeeded; `doctor` said such a line guards, and said a
+  `--brief 404` beside it held every write. It says the line as one under
+  which no write is checked, whatever else is on it, and exits 1.
+  Upgrading: take the option off the hook's line; `doctor` exits 1 until
+  it is.
+- **`--help` or `--version` beside a `--root` that is not a directory is
+  a line the hook cannot read.** `hook claude --help --root nowhere`
+  printed the help, exit 0, where without `--help` the hook says the
+  root. It says `the hook's line cannot be read (--help is given beside a
+  fault, --root is "nowhere", which is not a directory, ...)` as it says
+  every line it cannot read, to the person with exit 0, before a write and
+  after one, and holds no write; as a session starts it says the same.
+  `doctor` says the line in the same words.
+  Upgrading: mend the line; no line a release wrote carries either.
+- **`doctor --strict` fails where git cannot say where it runs its
+  hooks.** Under a `core.hooksPath` that names a file, `where git runs its
+  hooks cannot be told` failed nothing, under `--strict` or not, where a
+  release, a hook's line, a plugin or a hook file that cannot be told
+  fails `--strict`.
+  Upgrading: point `core.hooksPath` at a directory, or leave it unset.
+
+### Fixed
+
+- **A named pipe where the harness reads a file** no longer keeps a
+  command from coming back: a document a brief cites, a sibling's
+  `package.json`, what the run before a write kept, git's configuration
+  and a worktree's `commondir` as the hook reads them, a request waiting
+  for a ruling, a probe's report. Only a regular file is read, and what
+  else stands there is read as a file that is not there
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+- **A `.spec-harness.json` that cannot be read is said as that.** One the
+  account may not read, or one another process holds open on Windows, was
+  `.spec-harness.json is not valid JSON: EACCES: ...`. It is
+  `.spec-harness.json cannot be read: EACCES: ...`, exit 2 as before, and
+  a write to the file itself goes on, as to one that does not load.
+- **On Windows `--root C:\work` beside `--root c:\work` is one root.**
+  Every command refused the two as two directories, exit 2, and the hook
+  read such a line as one it cannot read, under which it checked no write;
+  Windows names a volume by its letter in either case. The hook now guards
+  under that root, and the rest of the path is compared as before.
+
+## 0.19.0
+
+An option that takes one value is given one, and a line that is wrong is
+refused with `--help` or `--version` on it, as the family's contract has
+it from 2026-10-18 (spec-core's ADR-0005, and
+[ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)
+here).
+
+`doctor` reads a hyphen in a matcher as the Claude Code on `PATH` reads
+it, and no command ends on a stack or fails to come back for what stands
+where a repository or a settings file is read
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+The hook decides a write in the work tree Claude works in, where a write a
+worktree's brief protects went through unchecked in a worktree session, and
+names the brief of a branch beside a tag of its name; it answers after a
+write from what it decided before it, and says as a session starts what
+would hold every write of it
+([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+[ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+
+### Changed
+
+- **Two values for an option that takes one are refused.** The parser kept
+  the last and passed over the earlier with no word: `doctor --root nowhere
+  --root .` ran in `.`, `--brief 404 --brief 001` was brief 001, and
+  `probe --at sideways --at head` ran at the head. Every command but
+  Claude Code's hook now exits 2 with one line that names both, as
+  `--root is given twice, as "nowhere" and as ".", and one of the two would
+  go unread; give it one`. The two are compared as the option reads them,
+  so one directory spelt two ways, or `--brief 12` beside `--brief 012`,
+  is the option once. `--path` and `--option` are lists, as before.
+  Upgrading: give each such option once; a script that builds a line by
+  adding a second `--root` or `--format` to override the first exits 2.
+- **Claude Code's hook says two values for one option on its own line.**
+  `hook claude --root nowhere --root .` guarded in `.`, and `hook claude
+  --brief 001 --brief 404` held every write for 404. It is a line the hook
+  cannot read, said in one line on stderr with exit 1, before a write and
+  after one, and holds no write: the guard is off until the line is
+  mended. `doctor` says the line in the same words and exits 1. No line a
+  release wrote gives an option two values.
+  Upgrading: a hook's line with an option given twice, which only a person
+  writes, is said and checks no write; give the option once.
+- **A wrong line is refused beside `--help` or `--version`, and the two
+  beside each other.** `doctor --help --root a --root b`, `doctor --help
+  --note x`, `doctor --help extra`, `doctor --help --root nowhere` and
+  `bogus --help` printed the help, exit 0, and `--help --version` printed
+  the version. Each is now exit 2 and the line it is refused with without
+  either; `--help` beside `--version`, in either order, is
+  `--help is given beside --version, and one of the two answers would go
+  unread; give one of them`. On `hook claude`'s line it is a line the
+  hook cannot read, exit 1. A line that is right answers as before, `guard
+  --help` among them.
+  Upgrading: ask for one of the two, on a line that is right.
+- **A matcher of names with a hyphen in one is read as the release on
+  `PATH` reads it.** By Claude Code's changelog such a matcher matched as a
+  substring before 2.1.195, and the changelog does not say how the rest of
+  it was read. Under an older release, or one that cannot be told, a line
+  under `Edit|Write|my-tool` is *cannot tell* where it said the line
+  guards a write by `Edit` and `Write`, and `init` writes no hook beside
+  it.
+  Upgrading: `doctor --strict` fails such a line under Claude Code 2.1.139
+  to 2.1.194 or with no `claude` on `PATH`: take the hyphenated name out of
+  the matcher, or update Claude Code.
+- **A hook file the account may not read is said, where `doctor` and `init`
+  ended on EACCES and a stack.** One git may not execute is skipped by git,
+  and is said and fails nothing; one it may is *cannot tell*, since git runs
+  it and a script it cannot read stops every commit. `--format json` has
+  the `gitHook.state` `unreadable`.
+  Upgrading: `doctor` exits 0, or 1 under `--strict`, and `init` 0, where
+  each exited 2: make the file readable.
+- **A write in a worktree is decided by the worktree's brief.** In a
+  worktree session started from the desktop app, and after Claude enters a
+  worktree, Claude Code names the main checkout as the project and hands the
+  hook the worktree as the question's `cwd`; the hook read the main
+  checkout's branch, which named no brief, and a write the worktree's brief
+  protects passed with no word. Where `cwd` is in another work tree of the
+  same repository, that work tree's branch, briefs and configuration now
+  decide the paths it holds, with its siblings looked for in its own install
+  and then the project's; any other path, and a `cwd` in another repository
+  or in none, is decided as before
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: in a worktree session a write the worktree's brief protects is refused, and one outside its scope warned of by that brief; nothing on the hook's line changes.
+- **A branch beside a tag of its name names its brief.** The branch was read
+  by git's short name, `heads/<name>` where a tag or a ref `refs/<name>` has
+  the name, which no template reads: the hook passed a protected write,
+  git's hook a protected commit, and `doctor` said `(none named)`. It is
+  read as HEAD names it; a base `init` writes for such a branch is still the
+  name git reads as the branch, `heads/main` beside a tag `main`.
+  Upgrading: on such a branch the guard refuses what its brief protects.
+- **git's hook in a linked worktree with no install runs the main work
+  tree's.** The hook `init` writes refused the commit there; it now reads
+  the script from the repository's main work tree after the worktree's own,
+  and `hook git` and `doctor` find the siblings there too, `doctor` saying
+  whose install each is (`elsewhere` in `--format json`).
+  Upgrading: `init` writes the hook once, so one an earlier release wrote still stops such a commit: take it away and run `spec-harness init --git-hook --write`.
+- **The hook answers after a write from what it decided before it.** Claude
+  Code starts the hook before a write and after it, and the run after
+  decided the write again, at what the run before costs: git, and spec-brief
+  on a brief's branch. The run before now keeps what the run after would say
+  under the git common directory, named by the question's `session_id` and
+  `tool_use_id`, and the run after answers from it with no process started;
+  one that finds nothing kept for its call, or another call's, decides as
+  before. Under `outOfScope: "ask"` or `"deny"`, where nothing was kept, it
+  says nothing with no process started
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+  Upgrading: nothing to change. What another process changes between the two runs of one write, the configuration or what spec-brief reads, is read at the next write rather than after this one.
+- **The hook says, as a session starts, what would hold every write of it.**
+  A SessionStart entry aimed at `hook claude` exited 1, `the hook input
+  names no event or tool`. It now reads the question, however the session
+  starts, and says in one line, to the person and to Claude, a configuration
+  that does not load, a brief named that spec-brief does not list,
+  spec-brief missing or too old where a brief is named, or a hook's line it
+  cannot read; nothing where all is well, and exit 0 whatever it finds.
+  `init` writes the entry beside its two, the plugin's `hooks/hooks.json`
+  carries it, and `doctor` notes a settings file that guards writes and has
+  none
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md),
+  [ADR-0012](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0012-one-way-into-claude-code.md)).
+  Upgrading: `init` writes its lines once, so run `spec-harness init
+  --write` again to add the entry to a `.claude/settings.json` an earlier
+  release wrote; a plugin brings it with this release. A script reading
+  `doctor --format json` finds `claudeCode.sessionStart`.
+
+### Fixed
+
+- **A named pipe where a settings file, `.mcp.json` or `.spec-harness.json`
+  is read** no longer keeps `doctor`, `init` or every command from coming
+  back: the first two are read as files that cannot be read as JSON, and
+  `.spec-harness.json` is `neither a file nor a directory, not a
+  configuration file`, exit 2, as a directory there is.
+- **`escalate` and `rule` say a path under git's directory, where the
+  harness keeps its state, that is no directory**, exit 2, in a line, where
+  they ended on Node's ENOTDIR and a stack.
+- **A `core.hooksPath` that names a file is said in git's own words**, where
+  `doctor` and `init` gave the reason for a git older than 2.31.
+- **`doctor`'s first line advises an array that unloads the project's
+  settings** before `init --write`, which writes no hook while it stands
+  and only advised the array in turn. `--format json` gains
+  `claudeCode.unloaded`.
+
+### Documentation
+
+- **Worktrees, the branches an app makes, and sessions that write through a
+  shell.** Two sections of the README, under *A round*. One says which
+  branch names the default templates read (`claude/brief-042-rotate-tokens`
+  is brief 042; `*` does not cross `/`; `claude --worktree <name>` makes
+  `worktree-<name>`, which needs a template of its own), and how a worktree
+  is checked: by its own branch and briefs, with the project's install where
+  it has none, at the commit as before the write; and that where a session's
+  project is a worktree with no install, the hook cannot start and the write
+  goes ahead. The other has, layer by layer, what the guard, the check as a
+  session starts, git's pre-commit hook, the audit and spec-brief's archive
+  each catch and let through, each run, and what every layer lets through:
+  an edit of the brief, a shell's write until the commit, `git commit
+  --no-verify`, and a Claude Code mod that approves a call a hook blocked.
+  It says why a shell `PostToolUse` hook and `"protected": "ask"` were not
+  built (ADR-0005, ADR-0006).
+  Upgrading: nothing to change; it describes this release.
+
 ## 0.18.0
 
 `doctor` and `init` say more of what looks like a guard and checks