@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/dist/cli.js

@@ -20,13 +20,13 @@
 import { SiblingOutputError } from './briefs.js';
 import { CONFIG_FILE, ConfigError, SIBLINGS, SPEC_BRIEF_CONFIGS } from './config.js';
 import { dirname, join } from 'node:path';
-import { gitDirectories, holdsGit, isDirectory, keepCall, loadConfig, realSpelling, repositoryPath, StateError, takeCall } from './fs.js';
-import { GitError, show, stagedChanges } from './git.js';
-import { afterResponse, callFile, callRecord, claudeResponse, gitResponse, keptCall, parseClaudeHook, SESSION_START, sessionResponse, warningsKept, warningsOf } from './hooks.js';
-import { SiblingError } from './siblings.js';
-import { emptyValue, heldHookLine, isBlank, isClaudeHook, readHookLine, refusal, twoValues, unreadHookLine } from './usage.js';
+import { gitDirectories, isDirectory, keepCall, loadConfig, mainWorkTree, outsideEvery, reachedBy, StateError, takeCall, writesOnly } from './fs.js';
+import { changedPaths, GitError, holdsPath, isShallow, show, stagedChanges, withBudget } from './git.js';
+import { afterResponse, callFile, callRecord, claudeResponse, gitResponse, HOOK_BUDGET_MS, keptCall, mendResponse, NONE, parseClaudeHook, SESSION_START, sessionOf, sessionResponse, TURN_END, turnResponse, warningResponse, warningsKept, warningsOf } from './hooks.js';
+import { declaredVersion, SiblingError } from './siblings.js';
+import { answerBeside, emptyValue, heldHookLine, isBlank, isClaudeHook, readHookLine, refusal, twoValues, unreadHookLine } from './usage.js';
 import { CLAUDE_CODE_MINIMUM, MINIMUM_VERSIONS } from './versions.js';
-import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, findTree, foundCommonDir, json, MAIN_INSTALL, openFound, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, MAIN_INSTALL, mayBeElsewhere, openFound, openWorkspace, otherTree, parseOptions, UsageError, version, writesBy, } 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
 
@@ -37,8 +37,10 @@ Commands:
   context [brief]     What an agent needs to start a round: the brief, its scope,
                       rulings, dependencies, the rules in force, the cited documents.
   guard <path...>     May the round write these paths? Exit 1 if one is refused.
-  hook claude         Answer a Claude Code PreToolUse, PostToolUse or SessionStart hook
-                      (stdin). At session start it says what would hold every write.
+  hook claude         Answer a Claude Code PreToolUse, PostToolUse, SessionStart or Stop
+                      hook (stdin). At session start it says what would hold every
+                      write; at a turn's end, with "turnReport" on, what the work tree
+                      holds that the brief protects or that is outside its scope.
   hook git            Answer git's pre-commit hook for the staged files.
   escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>
                       [--option "<label>: <cost>"]... [--recommend <text>].
@@ -55,17 +57,24 @@ Commands:
   premises            Do the live briefs' premises still hold? For CI: exit 1 when one
                       is stale, or, with --strict, when spec-guard cannot read one.
   init                Configure the spec-* tools to agree. Prints the plan; --write
-                      applies it; --git-hook adds a pre-commit hook.
+                      applies it; --git-hook adds a pre-commit hook; --block-on-failure
+                      has Claude Code 2.1.295 or later hold a write when the hook cannot
+                      start or runs past its timeout.
   mcp                 Serve start_round, check_path, request_escalation, audit_round,
                       list_rounds and the workflow prompts over MCP on stdio.
   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, its hook's line turns it off or holds every
-                      write, disableAllHooks or an array for a matcher switches it
-                      off, the plugin that is turned on is not on this machine and
-                      nothing else guards, Claude Code is too old to run its hooks,
-                      or git stops every commit at what stands for its hook.
+                      write or runs a script that is not there, the branch names a
+                      brief spec-brief does not list, cannot be asked about, or has
+                      archived, but for the branch git says archived it, a round's
+                      last commit, which waits to merge (CI fetches the base with its
+                      history for git to say), disableAllHooks or an array for a
+                      matcher switches it off, the plugin that is turned on is not on
+                      this machine and nothing else guards, Claude Code is too old to
+                      run its hooks, or git stops every commit at what stands for its
+                      hook.
 
 Options:
   --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
@@ -78,16 +87,19 @@ Options:
   --format <fmt>      pretty or json; audit and premises also gitlab, sarif or github.
                       For every command but hook and mcp.
   --strict            Warnings fail the run. For guard, audit, premises and doctor.
+  --block-on-failure  onFailure "block" on init's entries but the one as a turn ends. For init.
   --help, --version   One of the two: both on one line are refused.
 
 An option a command does not read, an argument it does not take, an option or an
 argument given an empty value, a brief given both as the argument and as --brief,
 and an option that takes one value given two that name two things are refused, exit 2,
 not read as if they were not there, and so with --help or --version on the line. The
-same value twice, as --root . --root ./, is read once. doctor says an empty --brief or
---base in its report. hook claude reads its line as every release has, and says a line
-it cannot read, two values for one option among them, and a --root that is not a
-directory, with exit 1: it refuses nothing for either.
+same value twice, as --root . --root ./, is read once, and on Windows a drive letter in
+either case. doctor says an empty --brief or --base in its report. hook claude reads its
+line as every release has, and says a line it cannot read, two values for one option or
+--help beside a --root that is not a directory among them, a --root that is not a
+directory, and a question it cannot read, as a warning to the person with exit 0: it
+refuses nothing for any of them.
 
 Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.
 `;
@@ -97,11 +109,38 @@ Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be truste
  * to a file no brief protects reads none.
  */
 const reader = async () => (await import('./reader.js')).createReader();
-async function decisionsFor(workspace, options, io, given, cwd) {
-    const active = await activeBrief(workspace, options, io.env);
-    const { brief, note, problem } = describeActive(active);
+/**
+ * The work tree with spec-brief's answers kept for a session of Claude
+ * Code's, and given again to it where all they were read from reads the
+ * same (ADR-0002); as it is where no session is named.
+ */
+function keptFor(workspace, session) {
+    return session === null ? workspace : { ...workspace, siblings: workspace.siblings.keeping(workspace.commonDir, session) };
+}
+/**
+ * Whether the brief the branch names is one spec-brief has archived: a
+ * closed round's branch, whose every write is held as under any name that is
+ * no brief's, and in words of its own, since nothing on it is to be mended:
+ * its round ends when the branch merges (ADR-0004).
+ */
+function closesRound(active) {
+    return active.kind === 'archived' && active.source === 'branch';
+}
+/** What the hook says after what holds the write: how to mend it, or that a closed round's branch has nothing to mend. */
+const MEND = 'Fix the brief or the branch before writing.';
+const CLOSED = 'The round is archived and ends when this branch merges: write on the branch of a live brief.';
+async function decisionsFor(workspace, options, io, given, cwd, session = null) {
+    // A path outside every work tree of the repository is decided as one
+    // outside it, whichever brief is named and whatever is wrong with the
+    // name: the problem held every write, a file outside the repository
+    // among them, where no brief decides one (ADR-0005). So no brief is asked
+    // about for such a write, and spec-brief is not run for it.
+    const outside = outsideEvery(given, workspace.root, workspace.commonDir, cwd);
+    const active = outside ? null : await activeBrief(keptFor(workspace, session), options, io.env);
+    const { brief, note, problem } = active === null ? { brief: null, note: undefined, problem: null } : describeActive(active);
+    // A problem is said only of a brief something names, so `active` is one.
     if (problem !== null)
-        return { problem };
+        return { problem, closed: closesRound(active) };
     const { checkPaths } = await import('./round.js');
     return { decisions: await checkPaths(workspace, brief, note, given, cwd, reader, options.base), brief };
 }
@@ -158,10 +197,11 @@ async function readStdin(io) {
 }
 /**
  * The write Claude Code asks the hook about, or the session that starts, or
- * the exit code that answers already: 1 for a question that cannot be read,
- * 0 for a tool that writes no file. Asked before anything on the hook's own
- * line is, so that a line that is wrong is said where there is a write it
- * leaves unchecked, or a session whose every write it leaves so.
+ * the exit code that answers already, 0: for a question that cannot be read,
+ * said to the person, and for a tool that writes no file. Asked before
+ * anything on the hook's own line is, so that a line that is wrong is said
+ * where there is a write it leaves unchecked, or a session whose every write
+ * it leaves so.
  */
 async function writeAsked(io) {
     let question;
@@ -171,34 +211,61 @@ async function writeAsked(io) {
     catch (error) {
         // A question that could not be read is one the hook cannot see, as one
         // it cannot parse is, below: it has no event to hold a write by.
-        io.stderr.write(`spec-harness: the hook input could not be read: ${error.message}\n`);
-        return EXIT_FAILED;
+        return answer(io, warningResponse(`the hook input could not be read: ${error.message}, so nothing it asks about is checked`));
     }
     const request = parseClaudeHook(question);
-    if ('error' in request) {
-        // A hook that cannot read its question refuses nothing it cannot see,
-        // but says so where the person reads it: a non-blocking error.
-        io.stderr.write(`spec-harness: ${request.error}\n`);
-        return EXIT_FAILED;
-    }
-    return request.paths.length === 0 && request.event !== SESSION_START ? EXIT_OK : request;
+    // A hook that cannot read its question refuses nothing it cannot see, and
+    // says so where the person reads it.
+    if ('error' in request)
+        return answer(io, warningResponse(`${request.error}, so nothing it asks about is checked`));
+    return request.paths.length === 0 && request.event !== SESSION_START && request.event !== TURN_END ? EXIT_OK : request;
 }
 /**
  * What is wrong with the hook's own line, said and nothing refused for it:
- * one line, since Claude Code shows the first line of the stderr of a hook
- * 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).
+ * one line, shown to the person, and exit 0, where exit 2 would hold every
+ * write of the session, the one that mends the line among them. Exit 1 said
+ * it as well, and is what Claude Code counts as a hook that failed, which
+ * `onFailure: "block"` holds the write for (ADR-0005).
  */
 function guardOff(io, { wrong, mend }, event) {
     if (event === SESSION_START)
         return answer(io, sessionResponse(`${wrong}, so the guard is off and no write of this session is checked; ${mend}`));
-    io.stderr.write(`spec-harness: ${wrong}, so the guard is off and this write is not checked; ${mend}\n`);
-    return EXIT_FAILED;
+    if (event === TURN_END)
+        return answer(io, turnResponse(`spec-harness: ${wrong}, so the guard is off and no write of this session is checked; ${mend}`));
+    return answer(io, warningResponse(`${wrong}, so the guard is off and this write is not checked; ${mend}`));
 }
 function answer(io, response) {
     io.stdout.write(response.stdout);
     return response.exitCode;
 }
+/**
+ * The answer to a write a configuration that does not load holds no more,
+ * or `null` for every other write, which is held as before (ADR-0005). Every
+ * write was held. A write outside every work tree of the repository is
+ * decided as such a write is, after the write as before it: nothing of the
+ * repository's decides it. And before a write to the configuration file
+ * itself, and to nothing else, the line says why every other write is held,
+ * so that a session can mend a typo in it. `cwd` is what a relative path
+ * is read from.
+ */
+function mending(error, request, cwd, env) {
+    // Every configuration the hook loads is read from a file, so `file` is
+    // never `null` here, and the test of it is the compiler's: its mutant is
+    // equivalent.
+    if (!(error instanceof ConfigError) || error.file === null)
+        return null;
+    // The work trees are named by the files git keeps, where git would name
+    // the same ones; a repository whose configuration or environment moves a
+    // work tree elsewhere is not known to leave the path outside. The file
+    // was loaded from the top git named, where a `.git` stands, so the files
+    // name a work tree, and the test of `null` is the compiler's.
+    const found = gitDirectories(dirname(error.file), env);
+    if (found !== null && found.exact && outsideEvery(request.paths, found.top, found.common, cwd))
+        return NONE;
+    if (request.event !== 'PreToolUse' || !writesOnly(request.paths, error.file, cwd))
+        return null;
+    return mendResponse(`${error.message}, so every other write is held until it loads; this write, to ${error.file} itself, is not checked`);
+}
 /**
  * What would hold every write of the session that starts, said once as it
  * starts and no write waits on it (ADR-0005): a configuration that does not
@@ -208,7 +275,7 @@ function answer(io, response) {
  * `doctor` says, and with what mends it. `null` where nothing does. The
  * check never ends the session's start: whatever it meets is said.
  */
-async function sessionProblem(options, io, root, cwd) {
+async function sessionProblem(options, io, root, cwd, session) {
     const held = 'so every write of this session is held until it is mended';
     try {
         const named = await openWorkspace({ ...options, root }, io);
@@ -216,8 +283,13 @@ async function sessionProblem(options, io, root, cwd) {
         // there, and so is the check (ADR-0005).
         const found = cwd === null ? null : await otherTree(named, cwd);
         const workspace = found === null ? named : await openFound(found, io, () => [named.root]);
-        const { problem } = describeActive(await activeBrief(workspace, options, io.env));
-        return problem === null ? null : `${heldHookLine(problem).wrong}, ${held}: fix the brief or the branch before writing; spec-harness doctor says more`;
+        const active = await activeBrief(keptFor(workspace, session), options, io.env);
+        const { problem } = describeActive(active);
+        if (problem === null)
+            return null;
+        if (closesRound(active))
+            return `${heldHookLine(problem).wrong}, so every write of this session is held: the round is archived and ends when this branch merges, so write on the branch of a live brief; spec-harness doctor says more`;
+        return `${heldHookLine(problem).wrong}, ${held}: fix the brief or the branch before writing; spec-harness doctor says more`;
     }
     catch (error) {
         // A session in no work tree has nothing to guard, as a write there has
@@ -227,7 +299,57 @@ async function sessionProblem(options, io, root, cwd) {
         // briefs, and whatever a defect throws.
         if (error instanceof UsageError)
             return null;
-        return `${error.message}, ${held}; spec-harness doctor says more`;
+        // But a write to the configuration file itself, which mends it, where
+        // the file is one a write may reach under its name alone (ADR-0005). The
+        // configuration is read from a file here as before a write, so the test
+        // of `file` is the compiler's, and its mutant is equivalent.
+        const mendable = error instanceof ConfigError && error.file !== null && writesOnly([error.file], error.file, root);
+        return `${error.message}, ${held}${mendable ? `, but for a write to ${error.file} itself, which is not checked` : ''}; spec-harness doctor says more`;
+    }
+}
+/** The most paths a report names one by one: past it, how many more there are. */
+const REPORTED = 20;
+/**
+ * What the work tree holds at the end of a turn that the brief protects or
+ * that is outside its scope, one line a path in the words a write of it is
+ * given; or `null` where there is nothing to say: `turnReport` is off, no
+ * brief is named, nothing changed is either, or the session is in no work
+ * tree (ADR-0005). The work tree is the one a write of the session is
+ * decided in. One start of git reads what changed, and nothing is asked of
+ * the base, so no ruling is read: a protected file a signed ruling allows
+ * is said as protected, and the audit reads the ruling. A configuration
+ * that does not load is said by every write and as the session starts, and
+ * here holds the report back without a word.
+ */
+async function turnReport(options, io, root, cwd) {
+    try {
+        const named = await openWorkspace({ ...options, root }, io);
+        const found = cwd === null ? null : await otherTree(named, cwd);
+        const workspace = found === null ? named : await openFound(found, io, () => [named.root]);
+        if (!workspace.config.turnReport)
+            return null;
+        const active = await activeBrief(workspace, options, io.env);
+        const { brief, problem } = describeActive(active);
+        if (problem !== null) {
+            const ends = closesRound(active) ? ': the round is archived and ends when this branch merges' : '';
+            return `spec-harness: ${heldHookLine(problem).wrong}, so what the work tree holds is not reported, and every write is held but one to a file outside every work tree of the repository${ends}; spec-harness doctor says more`;
+        }
+        if (brief === null)
+            return null;
+        const [changed, { decide }] = await Promise.all([changedPaths(workspace.root), import('./guard.js')]);
+        const outOfScope = workspace.config.outOfScope;
+        const said = changed.map((path) => decide({ path, given: path, brief, rulings: [], outOfScope })).filter((decision) => decision.verdict !== 'allow');
+        if (said.length === 0)
+            return null;
+        const lines = said.slice(0, REPORTED).map((decision) => `- ${decision.message}. Next: ${decision.hint}.`);
+        const more = said.length > REPORTED ? [`- and ${said.length - REPORTED} more: spec-harness guard <path> says each`] : [];
+        const paths = said.length === 1 ? `a path that brief ${brief.id} protects or that is outside its scope` : `${said.length} paths that brief ${brief.id} protects or that are outside its scope`;
+        return [`spec-harness: as this turn ended, the work tree held changes to ${paths}:`, ...lines, ...more].join('\n');
+    }
+    catch (error) {
+        if (error instanceof UsageError || error instanceof ConfigError)
+            return null;
+        return `spec-harness: ${error.message}, so what the work tree holds is not reported`;
     }
 }
 /**
@@ -243,79 +365,6 @@ async function unreadLine(said, io) {
         return request;
     return guardOff(io, unreadHookLine(said).fault, request.event);
 }
-/**
- * Whether a work tree other than the one whose top is `top` may hold `cwd`:
- * `cwd` is outside it, or a `.git` stands in a directory between the two,
- * where a linked worktree, a submodule or a repository of its own starts.
- * Where neither is so, `cwd` is in that work tree, and git is asked nothing
- * more: a session works at its project's top, or below it, for nearly every
- * write. Answering that one may is what git is then asked, so the mutant
- * that always answers so is equivalent, at the cost of a process, and so
- * is each that only answers so more often: a slice one short reaches the
- * top itself, which holds a `.git`, and a part named in place of none is
- * a directory no top holds.
- */
-function mayBeElsewhere(cwd, top) {
-    const path = repositoryPath(cwd, top, cwd);
-    if (path === null)
-        return true;
-    const parts = path === '' ? [] : path.split('/');
-    return parts.some((_, index) => holdsGit(join(top, ...parts.slice(0, index + 1))));
-}
-/**
- * The work tree that holds `cwd`, where it is another work tree of the
- * repository the hook's root names, by the git directory the two share;
- * `null` where `cwd` is in the root's own, in another repository, or in
- * none (ADR-0005).
- */
-async function otherTree(named, cwd) {
-    if (!mayBeElsewhere(cwd, named.root))
-        return null;
-    const found = await findTree(cwd);
-    // The project's own work tree, found again, would decide every path the
-    // same way once more: the check saves reading its configuration twice, and
-    // its mutant is equivalent.
-    if (found === null || found.root === named.root)
-        return null;
-    const common = await foundCommonDir(found);
-    // git names a common directory wherever it names a top, so `null` is
-    // there for the type.
-    if (common === null || realSpelling(common) !== realSpelling(named.commonDir))
-        return null;
-    return found;
-}
-/**
- * The work trees a write is decided in, each with the paths it decides
- * (ADR-0005). The repository is the one the hook's root names, as before,
- * and so is the work tree, but where the question's `cwd` is in another
- * work tree of that repository, linked or main, by the git directory the
- * two share: there a session works in a worktree while Claude Code names
- * the project it started in, and the hook decided by the project's branch,
- * which named no brief, so a protected write passed with no word. That work
- * tree decides the paths it holds, by its branch, its briefs and its
- * configuration, with its siblings looked for in its install and then the
- * project's. A path it does not hold is decided as before, by the work tree
- * the root names: a write to the project's own file from a worktree is
- * refused where it was. Where both hold a path, one is inside the other,
- * and the inner one holds it as git reads it. A `cwd` in another
- * repository, or in none, leaves every path where it was.
- */
-async function writesBy(named, cwd, paths, io) {
-    const asBefore = [{ workspace: named, paths }];
-    if (cwd === null)
-        return asBefore;
-    const found = await otherTree(named, cwd);
-    if (found === null)
-        return asBefore;
-    const inner = repositoryPath(found.root, named.root, cwd) !== null;
-    const holds = (path) => repositoryPath(path, found.root, cwd) !== null && (inner || repositoryPath(path, named.root, cwd) === null);
-    const own = paths.filter(holds);
-    if (own.length === 0)
-        return asBefore;
-    const workspace = await openFound(found, io, () => [named.root]);
-    const rest = paths.filter((path) => !holds(path));
-    return [{ workspace, paths: own }, ...(rest.length === 0 ? [] : [{ workspace: named, paths: rest }])];
-}
 /**
  * The answer after a write, where it can be given with no process started,
  * or `null` where it is to be decided as before (ADR-0002, ADR-0003).
@@ -329,7 +378,7 @@ async function writesBy(named, cwd, paths, io) {
  * `deny` there is nothing to say, where the configuration read is the one
  * git would have the hook read, of the work tree the session is in.
  */
-async function answeredAfter(root, record, cwd, io) {
+async function answeredAfter(root, record, cwd, paths, io) {
     const found = gitDirectories(root, io.env);
     if (found === null)
         return null;
@@ -341,7 +390,10 @@ async function answeredAfter(root, record, cwd, io) {
         if (warnings !== null)
             return afterResponse(warnings);
     }
-    if (!found.exact || (cwd !== null && mayBeElsewhere(cwd, found.top)))
+    // A path in another work tree than the one this configuration is read
+    // from may be decided by another's, which may warn, and so may the file a
+    // link has a path written to.
+    if (!found.exact || (cwd !== null && mayBeElsewhere(cwd, found.top)) || paths.some((path) => reachedBy(path, cwd ?? io.cwd).some((spelled) => mayBeElsewhere(spelled, found.top))))
         return null;
     try {
         return (await loadConfig(found.top)).config.outOfScope === 'warn' ? null : afterResponse([]);
@@ -351,7 +403,25 @@ async function answeredAfter(root, record, cwd, io) {
         return null;
     }
 }
-async function hookCommand(options, io) {
+/**
+ * The answer before a write the hook could not check: one line, and exit 2,
+ * which holds the write. Claude Code shows the line to Claude as the
+ * reason.
+ */
+function cannotCheck(io, error) {
+    io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
+    return EXIT_ERROR;
+}
+/**
+ * `hook claude` within one budget for every process it starts, below the
+ * timeout Claude Code gives its entry, so that a run of slow processes ends
+ * with its own answer and not the cancelling of it (ADR-0002); `hook git`
+ * as it was, which no entry of Claude Code's runs.
+ */
+function hookCommand(options, io) {
+    return options.positionals[0] === 'claude' ? withBudget(HOOK_BUDGET_MS, () => answerHook(options, io)) : answerHook(options, io);
+}
+async function answerHook(options, io) {
     const kind = options.positionals[0];
     if (kind === 'claude') {
         const request = await writeAsked(io);
@@ -364,11 +434,14 @@ async function hookCommand(options, io) {
             return guardOff(io, line.fault, request.event);
         const cwd = request.cwd ?? io.cwd;
         const root = line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd;
+        const session = sessionOf(request);
         if (request.event === SESSION_START)
-            return answer(io, sessionResponse(await sessionProblem(options, io, root, request.cwd)));
+            return answer(io, sessionResponse(await sessionProblem(options, io, root, request.cwd, session)));
+        if (request.event === TURN_END)
+            return answer(io, turnResponse(await turnReport(options, io, root, request.cwd)));
         const record = callRecord(request, { root: line.root, brief: options.brief, base: options.base }, io.cwd, io.env, version());
         if (request.event === 'PostToolUse') {
-            const answered = await answeredAfter(root, record, request.cwd, io);
+            const answered = await answeredAfter(root, record, request.cwd, request.paths, io);
             if (answered !== null) {
                 io.stdout.write(answered.stdout);
                 return answered.exitCode;
@@ -381,6 +454,14 @@ async function hookCommand(options, io) {
         catch (error) {
             if (error instanceof UsageError)
                 return EXIT_OK;
+            const mended = mending(error, request, cwd, io.env);
+            if (mended !== null)
+                return answer(io, mended);
+            // git asked where the work tree is and did not answer within its time
+            // limit: before a write that is a write the hook could not check, said
+            // as one (ADR-0002).
+            if (error instanceof GitError && request.event === 'PreToolUse')
+                return cannotCheck(io, error);
             throw error;
         }
         try {
@@ -392,12 +473,12 @@ async function hookCommand(options, io) {
             // answer is made from, in any work tree that decides it.
             let keeps = true;
             for (const part of await writesBy(workspace, request.cwd, request.paths, io)) {
-                const decided = await decisionsFor(part.workspace, options, io, part.paths, cwd);
+                const decided = await decisionsFor(part.workspace, options, io, part.paths, cwd, session);
                 if ('problem' in decided) {
                     // 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`);
+                    io.stderr.write(`spec-harness: ${heldHookLine(decided.problem).wrong}. ${decided.closed ? CLOSED : MEND}\n`);
                     return EXIT_ERROR;
                 }
                 // A line of the answer for each path, by the work tree that decided it.
@@ -418,10 +499,15 @@ async function hookCommand(options, io) {
         catch (error) {
             if (request.event !== 'PreToolUse')
                 throw error;
+            // The configuration of another work tree the write is decided in,
+            // which does not load, lets a write to itself through as the
+            // project's does.
+            const mended = mending(error, request, cwd, io.env);
+            if (mended !== null)
+                return answer(io, mended);
             // A round is named and its briefs cannot be read: the guard cannot
             // tell a protected file from any other, so the write waits.
-            io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
-            return EXIT_ERROR;
+            return cannotCheck(io, error);
         }
     }
     if (kind === 'git') {
@@ -459,6 +545,47 @@ async function baseAndSigners({ resolveBase }, workspace, flag, signersFile) {
     const signersText = base.kind === 'resolved' ? await show(base.sha, signersFile, workspace.root) : null;
     return { base, signersText };
 }
+async function closedRound(workspace, base, brief) {
+    if (base.kind === 'unresolved') {
+        return { state: 'unknown', brief, reason: `the base cannot be resolved (${base.reason}): fetch it under that name, with its history, as git fetch origin main:main fetches main` };
+    }
+    const [shallow, atBase, atHead] = await Promise.all([isShallow(workspace.root), holdsPath(base.mergeBase, brief.file, workspace.root), holdsPath(base.head, brief.file, workspace.root)]);
+    // A merge base read in a history cut short can be older than the one the
+    // whole history has, and a file absent from it present at the true one.
+    if (shallow !== false) {
+        return { state: 'unknown', brief, reason: 'the history is shallow, or git cannot say that it is not, and a merge base found in it may be older than the one the whole history has: fetch the whole history' };
+    }
+    if (atBase === null || atHead === null)
+        return { state: 'unknown', brief, reason: `git could not list ${brief.file} at the merge base with ${base.ref}, or at HEAD` };
+    if (atBase)
+        return { state: 'archived-before', brief, ref: base.ref, mergeBase: base.mergeBase };
+    // Absent from HEAD as well, the archive is not committed, or the file is
+    // not the one git names: neither is the archive this branch committed.
+    if (!atHead)
+        return { state: 'unknown', brief, reason: `${brief.file} is not committed at HEAD; commit the archive` };
+    return { state: 'waiting-to-merge', brief, ref: base.ref, mergeBase: base.mergeBase };
+}
+/** The note on doctor's `brief` line for a branch that names a brief spec-brief has archived. */
+function describeClosedRound(closed) {
+    const { id, file } = closed.brief;
+    switch (closed.state) {
+        case 'waiting-to-merge':
+            return `brief ${id} was archived on this branch, which waits to merge: ${file} is in HEAD and not at the merge base with ${closed.ref}, ${closed.mergeBase.slice(0, 12)}, so this fails nothing; the hook holds every write on the branch all the same`;
+        case 'archived-before':
+            return `brief ${id} was archived before this branch: ${file} is at the merge base with ${closed.ref}, ${closed.mergeBase.slice(0, 12)}, so the branch is a closed round's, used again, and every write on it is held`;
+        case 'unknown':
+            return `whether brief ${id} was archived on this branch, which waits to merge, cannot be told: ${closed.reason}`;
+    }
+}
+/**
+ * The release of spec-harness installed in a work tree, where the hook's
+ * line, init's and the plugin's, names its script under the project's
+ * `node_modules`; `null` where none is, or its manifest gives no version.
+ */
+function harnessRelease(root) {
+    const version = declaredVersion(join(root, 'node_modules', '@descent-vtt', 'spec-harness', 'package.json'));
+    return typeof version === 'string' ? version : null;
+}
 /**
  * How Claude Code is wired to the guard, and the release of the one on
  * `PATH`, which waits on the wiring: only a Claude Code that runs the guard
@@ -466,17 +593,18 @@ async function baseAndSigners({ resolveBase }, workspace, flag, signersFile) {
  * write through unguarded. `null` where it was not asked. The wiring asks
  * it itself, since which writes a line is started for can turn on the
  * release as well (round.ts); the two are told apart here for the report,
- * which has a place of its own for the release.
+ * which has a place of its own for the release. The script each line runs
+ * is looked for in `places`, where `${CLAUDE_PROJECT_DIR}` can point.
  */
-async function wiringAndRelease({ claudeCodeWiring }, root, io) {
-    const { release, ...wiring } = await claudeCodeWiring(root, io);
+async function wiringAndRelease({ claudeCodeWiring }, root, io, places) {
+    const { release, ...wiring } = await claudeCodeWiring(root, io, undefined, true, places);
     return { wiring, release };
 }
 async function doctorCommand(options, io) {
     // What doctor alone runs of them, loaded before anything is asked: the
     // five things below are asked at once, and none waits on a module.
     const [configure, round, setup, signing] = await Promise.all([import('./configure.js'), import('./round.js'), import('./setup.js'), import('./signers.js')]);
-    const { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, NO_SESSION_START, wiringState } = configure;
+    const { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describeInstalls, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, guardWired, NO_SESSION_START, NO_TURN_END, wiringState } = configure;
     const { diagnoseBrief, specBriefPlugin } = round;
     const { gitHook } = setup;
     const { notFido2, readAllowedSigners } = signing;
@@ -504,17 +632,28 @@ async function doctorCommand(options, io) {
     // once, and read below in the order they were asked in before: where more
     // than one fails, the first of that order is the one thrown, whichever
     // failed first by the clock (ADR-0002).
+    // In a linked worktree, `${CLAUDE_PROJECT_DIR}` names it in a session
+    // started there and the main checkout in a worktree session of the desktop
+    // app (https://code.claude.com/docs/en/worktrees, What worktrees share with
+    // the main checkout, read 2026-10-24): the hook's script is looked for in
+    // both, and is not there only where it is in neither.
+    const main = mainWorkTree(workspace.commonDir);
     const [briefAsked, baseAsked, pluginAsked, claudeAsked, hookAsked] = await Promise.allSettled([
         diagnoseBrief(workspace, options, io.env),
         baseAndSigners(round, workspace, options.base, signersFile),
         specBriefPlugin(workspace.root),
-        wiringAndRelease(round, workspace.root, io),
+        wiringAndRelease(round, workspace.root, io, main === null ? [workspace.root] : [workspace.root, main]),
         gitHook(workspace.root),
     ]);
     const named = answerOf(briefAsked);
     // A ruling counts only by a signature checked against the allowed signers
     // on the base, and only once spec-brief's archive asks the plugin about it.
     const { base, signersText } = answerOf(baseAsked);
+    // A branch that names a brief spec-brief has archived holds every write,
+    // and fails doctor, but for the branch that archived it: the last commit
+    // of every round, whose own CI run must not fail for it. git tells the
+    // two apart by the base, so they are told once it is resolved (ADR-0004).
+    const closed = named.archived === null ? null : await closedRound(workspace, base, named.archived);
     const onBase = base.kind === 'resolved' ? signersText !== null : null;
     const signers = describeSigners(signersFile, base.kind === 'resolved' ? base.ref : null, onBase === true);
     // Which keys sign, as notes: a key that is not FIDO2 can still be one the
@@ -532,7 +671,7 @@ async function doctorCommand(options, io) {
     // 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);
+    const lineNotes = wiring.lines.flatMap((line) => [line.detail, line.cover, line.note, line.timeout]).filter((note) => note !== null);
     // What stands over every line: a plugin that is turned on and is not on
     // this machine, or cannot be told to be, and disableAllHooks, which
     // switches off whatever hooks there are.
@@ -540,7 +679,14 @@ async function doctorCommand(options, io) {
     // And whether the hook is started as a session starts, where settings hold
     // the guard: a note, failing nothing, and `sessionStart` in the document.
     const atStart = wiring.hooks.length > 0 && !wiring.sessionStart ? NO_SESSION_START : null;
-    const wiringNotes = [describePresence(wiring), wiring.hooksOff === null ? null : describeHooksOff(wiring.hooksOff, switchedOff)].filter((note) => note !== null);
+    // And whether the report the configuration asks for at a turn's end is
+    // made at all: a note, failing nothing, and `turnEnd` in the document.
+    const atEnd = workspace.config.turnReport && !wiring.turnEnd ? NO_TURN_END : null;
+    // And, in a linked worktree where something wires the guard, the release
+    // the hook's line runs where it is not this work tree's own: a note. In
+    // the main work tree both are read from one install, and are one.
+    const installs = guardWired(wiring) && main !== null ? describeInstalls(main, harnessRelease(main), harnessRelease(workspace.root)) : null;
+    const wiringNotes = [describePresence(wiring), wiring.hooksOff === null ? null : describeHooksOff(wiring.hooksOff, switchedOff), installs].filter((note) => note !== null);
     // How the hook runs the harness is a note: one that goes through npx guards
     // as well as one that does not, and fails nothing, --strict or not.
     const { hook, note: hookNote } = answerOf(hookAsked);
@@ -552,6 +698,9 @@ async function doctorCommand(options, io) {
             branchSource: workspace.branchSource ?? null,
             brief: named.id,
             briefProblem: named.problem,
+            closedRound: closed === null
+                ? null
+                : { state: closed.state, file: closed.brief.file, mergeBase: closed.state === 'unknown' ? null : closed.mergeBase, detail: describeClosedRound(closed) },
             base: base.kind === 'resolved' ? { ref: base.ref, source: base.source, mergeBase: base.mergeBase } : { unresolved: base.reason },
             allowedSigners: {
                 file: signersFile,
@@ -580,6 +729,7 @@ async function doctorCommand(options, io) {
             `root    ${workspace.root}`,
             `branch  ${branch}`,
             `brief   ${named.problem === null ? (named.id ?? '(none named)') : `none: ${named.problem}`}`,
+            ...more(closed === null ? [] : [describeClosedRound(closed)]),
             `base    ${describeBase(base)}`,
             `signers ${signers}`,
             ...more(signerNotes),
@@ -589,6 +739,7 @@ async function doctorCommand(options, io) {
             ...more(lineNotes),
             ...more(release === null ? [] : [describeClaudeRelease(release)]),
             ...more(atStart === null ? [] : [atStart]),
+            ...more(atEnd === null ? [] : [atEnd]),
             `git     ${describeGitHook(hook)}`,
             ...more(hookNote === null ? [] : [hookNote]),
             '',
@@ -601,24 +752,32 @@ async function doctorCommand(options, io) {
     // a choice; with none installed, the harness can check nothing. A double
     // install is a problem too, where no Claude Code wiring at all is a choice,
     // and so are a hook whose own line turns the guard off or holds every
-    // write, guard hooks that disableAllHooks switches off, a plugin that is
-    // turned on and is not on this machine where no hook of init's stands in
-    // for it, a Claude Code too old to run the hooks, and something at the
-    // path of git's pre-commit hook that git cannot run and stops every
-    // commit at. A release that cannot be told is not fine either, nor a
-    // line whose reading cannot be, nor a plugin that cannot be told to be on
-    // this machine, nor a hook git runs that cannot be read, which stops every
-    // commit as a script and runs as a program: --strict fails the four.
+    // write, or whose script is not there, a branch that names a brief no round
+    // can work under, which holds every write as well, but for the branch that
+    // archived its brief and waits to merge (ADR-0004), or one that names a
+    // brief spec-brief cannot be asked about, which the hook holds every write
+    // for too, guard hooks that disableAllHooks
+    // switches off, a plugin that is turned on and is not on this machine
+    // where no hook of init's stands in for it, a Claude Code too old to run
+    // the hooks, and something at the path of git's pre-commit hook that git
+    // cannot run and stops every commit at. A release that cannot be told is
+    // not fine either, nor a line whose reading cannot be, nor a plugin that
+    // cannot be told to be on this machine, nor a hook git runs that cannot be
+    // read, which stops every commit as a script and runs as a program, nor a
+    // place git runs its hooks from that git cannot name: --strict fails the
+    // five.
     const outdated = rows.some((row) => row.state === 'outdated');
     const usable = rows.some((row) => row.state === 'found');
     const off = wiring.lines.some((line) => line.state === 'off' || line.state === 'held');
     const missing = wiring.presence?.state === 'absent' && wiring.hooks.length === 0;
     const tooOld = release?.state === 'outdated';
     const stopped = hook.state === 'stops';
+    const unworkable = named.branch && closed?.state !== 'waiting-to-merge';
     // Only an unreadable hook has `runs`, so the test of its state is the
     // compiler's, and its mutant is equivalent.
-    const untold = options.strict && (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown' || (hook.state === 'unreadable' && hook.runs));
-    return outdated || !usable || claude === 'both' || off || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
+    const untold = options.strict &&
+        (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown' || (hook.state === 'unreadable' && hook.runs) || hook.state === 'unknown');
+    return outdated || !usable || claude === 'both' || off || unworkable || named.holds || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**
@@ -683,6 +842,13 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: ${refused}\n`);
         return EXIT_ERROR;
     }
+    // Claude Code's hook is exempt from every refusal above, and said a root
+    // that is not a directory only as it ran, which the help or the version
+    // answered in place of: printed beside one, either is a line it cannot
+    // read, said where there is a write it leaves unchecked (ADR-0005).
+    const beside = isClaudeHook(options.command, options.positionals[0]) ? answerBeside(options, io.cwd, isDirectory) : null;
+    if (beside !== null)
+        return unreadLine(beside, io);
     if (options.version) {
         io.stdout.write(`${version()}\n`);
         return EXIT_OK;