@descent-vtt/spec-harness 0.20.0 → 0.21.0

package/dist/cli.js

@@ -19,10 +19,10 @@
  */
 import { SiblingOutputError } from './briefs.js';
 import { CONFIG_FILE, ConfigError, SIBLINGS, SPEC_BRIEF_CONFIGS } from './config.js';
-import { dirname, join, resolve } from 'node:path';
-import { gitDirectories, isDirectory, keepCall, loadConfig, mainWorkTree, outsideEvery, StateError, takeCall, writesOnly } from './fs.js';
-import { changedPaths, GitError, show, stagedChanges } from './git.js';
-import { afterResponse, callFile, callRecord, claudeResponse, gitResponse, keptCall, mendResponse, NONE, parseClaudeHook, SESSION_START, sessionOf, sessionResponse, TURN_END, turnResponse, warningResponse, warningsKept, warningsOf } from './hooks.js';
+import { dirname, join } from 'node:path';
+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';
@@ -66,12 +66,15 @@ Commands:
                       named, how Claude Code runs the guard, and git's hook. Exit 1
                       when a sibling is older than this release needs, the guard is
                       installed twice, its hook's line turns it off or holds every
-                      write, the branch names a brief spec-brief does not list or
-                      has archived, 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.
@@ -114,6 +117,18 @@ const reader = async () => (await import('./reader.js')).createReader();
 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
@@ -123,8 +138,9 @@ async function decisionsFor(workspace, options, io, given, cwd, session = null)
     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 };
 }
@@ -267,8 +283,13 @@ async function sessionProblem(options, io, root, cwd, session) {
         // 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(keptFor(workspace, session), 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
@@ -307,9 +328,12 @@ async function turnReport(options, io, root, cwd) {
         const workspace = found === null ? named : await openFound(found, io, () => [named.root]);
         if (!workspace.config.turnReport)
             return null;
-        const { brief, problem } = describeActive(await activeBrief(workspace, options, io.env));
-        if (problem !== null)
-            return `spec-harness: ${heldHookLine(problem).wrong}, so what the work tree holds is not reported, and every write is held; spec-harness doctor says more`;
+        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')]);
@@ -367,8 +391,9 @@ async function answeredAfter(root, record, cwd, paths, io) {
             return afterResponse(warnings);
     }
     // A path in another work tree than the one this configuration is read
-    // from may be decided by another's, which may warn.
-    if (!found.exact || (cwd !== null && mayBeElsewhere(cwd, found.top)) || paths.some((path) => mayBeElsewhere(resolve(cwd ?? io.cwd, path), found.top)))
+    // 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([]);
@@ -387,7 +412,16 @@ function cannotCheck(io, error) {
     io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
     return EXIT_ERROR;
 }
-async function hookCommand(options, io) {
+/**
+ * `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);
@@ -444,7 +478,7 @@ async function hookCommand(options, io) {
                     // 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.
@@ -511,6 +545,38 @@ 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
@@ -527,17 +593,18 @@ function harnessRelease(root) {
  * 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, describeInstalls, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, guardWired, 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;
@@ -565,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
@@ -593,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.
@@ -601,10 +679,12 @@ 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;
+    // 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 main = mainWorkTree(workspace.commonDir);
     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
@@ -618,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,
@@ -646,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),
@@ -655,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]),
             '',
@@ -667,8 +752,11 @@ 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, a branch that names a brief no round can work under, which holds
-    // every write as well (ADR-0004), guard hooks that disableAllHooks
+    // 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
@@ -684,11 +772,12 @@ async function doctorCommand(options, io) {
     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) || hook.state === 'unknown');
-    return outdated || !usable || claude === 'both' || off || named.branch || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
+    return outdated || !usable || claude === 'both' || off || unworkable || named.holds || switchedOff || missing || tooOld || stopped || untold ? EXIT_FAILED : EXIT_OK;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**