@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-harness",
-  "version": "0.19.0",
+  "version": "0.21.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,331 @@ 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.21.0
+
+A path through a link is decided as it reads and as the system writes it,
+and the stricter answer stands; a run of the hook has one budget, 45
+seconds, for every process it starts; and the server's `check_path` answers
+each path as the hook decides a write of it. `doctor` passes the branch that
+archived its brief, a round's last commit, where git says the branch
+archived it, so a CI job that runs it passes a round's last pull request;
+and it fails for a hook's line whose script is not there and for a brief the
+branch names that spec-brief cannot be asked about
+([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)).
+
+### Changed
+
+- **A path through a link is decided as it reads and as the system writes
+  it, and the stricter answer stands.** On Linux and macOS a `..` after a
+  link is written after the link: `deep/../schema.ts`, `deep` a link to
+  `lib/x`, reads as `schema.ts` and is written to `lib/schema.ts`, and the
+  hook, `guard` and the server's `check_path` decided it as `schema.ts`.
+  A link to nothing was decided as the link, where a write makes the file
+  it names, and a path outside the repository whose `..` after a link
+  leads into it as outside. Each such path is now decided both ways, each
+  file by the work tree that holds it, and a refusal says where the link
+  leads. On Windows, which reads the `..` first, no answer changes
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: nothing to change. A write through a link to a file the brief
+  protects, which passed, is refused, and `guard` exits 1 for it.
+- **A run of the hook has one budget, 45 seconds, for every process it
+  starts, and holds the write at it.** Each process the hook asked a
+  question of had 20 seconds, and several that answered slowly, none of
+  them at that, passed the 60 seconds `init` and the plugin give the
+  hook's entry, where Claude Code cancels the hook and lets the write go
+  ahead. A process is now given its 20 seconds or what is left of the
+  run's 45, whichever is less, and one stopped at the budget says so:
+  `cannot check this write: spec-brief did not answer within the 45
+  seconds the hook's run is given, and was stopped`, exit 2. `doctor`
+  notes an entry of the hook whose `timeout` is below the 45 seconds, and
+  `--format json` has the note as each line's `timeout`
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.md)).
+  Upgrading: nothing to change where the hook's entry has the 60 seconds
+  `init` writes, or no timeout; an entry below 45 is noted, and fails
+  nothing.
+- **The server's `check_path` answers each path as the hook decides a
+  write of it.** A file outside every work tree of the repository is
+  outside the repository whatever names the brief, where a brief that
+  spec-brief does not list or has archived failed the call; a path inside
+  that such a brief holds is `deny`, with the reason `held` and the
+  hook's words; and with no brief named each path is answered as no
+  brief's, where the call was a tool error. spec-brief is asked only where
+  a brief is named and a path is inside. The report at the end of a turn
+  says that every write is held but one to a file outside every work tree
+  ([ADR-0008](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0008-one-server-for-rounds.md),
+  [ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a client that read a tool error from `check_path` for a
+  brief's problem or for no brief named reads an answer for each path, and
+  `held` is a new `reason` of a decision.
+- **`doctor` fails nothing for the branch that archived its brief, a
+  round's last commit.** A round archives its brief on its own branch
+  before the branch merges, and since 0.20.0 `doctor` exited 1 there, so a
+  CI job that runs it failed every round's last pull request. Where git
+  says the brief's archived file is in HEAD and not at the merge base of
+  the base and HEAD, `doctor` says so in a note and exits 0 for it; where
+  the file is at the merge base, a closed round's branch used again, it
+  exits 1 as before, and so where git cannot say. `--format json` has the
+  answer as `closedRound`. The hook holds every write on such a branch as
+  before, and says the round is archived and ends when the branch merges
+  ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+  Upgrading: a CI job that runs `doctor` fetches the base under the name it
+  is configured by, with its history (`git fetch origin main:main`, in a
+  clone that is not shallow); without it, a base that names no commit or a
+  shallow history, a round's last pull request still fails `doctor`. Run
+  `doctor` in CI without `--strict`, which fails where the release of
+  Claude Code cannot be told.
+- **`doctor` fails for a line of Claude Code's hook whose script is not
+  there**, which Claude Code cannot start and lets every write past: a
+  guard that is off, or, under `"onFailure": "block"` that the Claude
+  Code on `PATH` reads, one that holds every write. The script is looked
+  for where `${CLAUDE_PROJECT_DIR}` can point, a linked worktree's main
+  checkout among them; a relative path, npx's package and a word a shell
+  reads are not
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+  Upgrading: a project whose hook's line names an install that is not
+  there has `doctor` exit 1 where it exited 0: install
+  `@descent-vtt/spec-harness`, or mend the line. `claudeCode.lines` has a
+  line for each way an entry names the harness.
+- **`doctor` fails where the branch names a brief spec-brief cannot be
+  asked about**, not installed, too old, or failing as it lists the
+  briefs, since the hook holds every write there, and says why on its
+  `brief` line; a hook's line that names a brief where spec-brief cannot
+  be run is said as one that holds every write
+  ([ADR-0004](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+  Upgrading: exit 1 where it was 0; the flag and `SPEC_BRIEF` still fail
+  nothing.
+
+### Added
+
+- **`doctor` notes a report at the end of a turn that nothing runs**:
+  `"turnReport"` on, and no settings file starting the hook as a turn
+  ends. It fails nothing; `--format json` has `claudeCode.turnEnd`
+  ([ADR-0005](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+### Fixed
+
+- **A `tools` command that cannot be started is said in one way on every
+  host**: `cannot start "<command>": name the tool's script, such as
+  ["node", ...]`, the words a name no program has was given. On Windows a
+  script with no `node` before it, or a `.cmd`, ended a command on
+  `unexpected error: Error: spawn EFTYPE` (or `EINVAL`) and a stack trace,
+  and on Linux a file that may not be run was `exited -1` and nothing more;
+  the hook holds the write as it did
+  ([ADR-0002](https://github.com/DescentVTT/spec-harness/blob/main/docs/adr/0002-siblings-through-their-command-lines.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