@descent-vtt/spec-harness 0.17.0 → 0.19.0

package/dist/cli.js

@@ -8,25 +8,25 @@
  * failed, an output its reader closed, an error nothing here expected. A run
  * that could not look must never exit as though it looked and found nothing
  * (spec-core ADR-0005).
+ *
+ * A command loads what it runs. This module imports what every run needs,
+ * the hook's before a write among them, and a module that only some
+ * commands run is imported where one of them is the command: the hook
+ * runs before and after every write an agent makes, and what it loaded of
+ * the other commands was a wait before each (ADR-0002). A module that
+ * cannot be loaded is thrown where it was asked for, and ends the run in a
+ * line and exit 2, as every error does.
  */
 import { SiblingOutputError } from './briefs.js';
-import { auditCommand, contextCommand, escalateCommand, probeCommand, ruleCommand, rulingsCommand } from './commands.js';
-import { ConfigError, SIBLINGS } from './config.js';
-import { describeBase, describeClaudeCode, describeClaudeRelease, describeGitHook, describeHooksOff, describePlugin, describePresence, describeSignerKeys, describeSignerProblem, describeSigners, guardSwitchedOff, wiringState, } from './configure.js';
-import { isDirectory } from './fs.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 { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
-import { claudeVersion } from './host.js';
-import { premisesCommand } from './premises.js';
-import { createReader } from './reader.js';
-import { checkPaths, claudeCodeWiring, diagnoseBrief, resolveBase, specBriefPlugin } from './round.js';
-import { mcpCommand } from './server.js';
-import { gitHook, initCommand } from './setup.js';
-import { notFido2, readAllowedSigners } from './signers.js';
+import { 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, unreadHookLine } from './usage.js';
-import { checkClaudeCode, CLAUDE_CODE_MINIMUM, MINIMUM_VERSIONS } from './versions.js';
-import { activeBrief, answerOf, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+import { 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';
 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,7 +37,8 @@ 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 or PostToolUse hook (stdin).
+  hook claude         Answer a Claude Code PreToolUse, PostToolUse or SessionStart hook
+                      (stdin). At session start it says what would hold every write.
   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>].
@@ -61,9 +62,10 @@ 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, disableAllHooks switches it off, the plugin that is
-                      turned on is not on this machine and nothing else guards, or
-                      Claude Code is too old to run its hooks.
+                      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.
 
 Options:
   --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
@@ -76,25 +78,46 @@ 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.
-  --help, --version
+  --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, and a brief given both as the argument and as --brief
-are refused, exit 2, not read as if they were not there. 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, and a --root that is not a directory, with exit 1: it refuses
-nothing for either.
+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.
 
 Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.
 `;
 /* ------------------------------------------------------------------- guard */
-const reader = createReader();
+/**
+ * The reader of a brief's rulings, loaded where a ruling is read: a write
+ * 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);
     if (problem !== null)
         return { problem };
-    return { decisions: await checkPaths(workspace, brief, note, given, cwd, reader, options.base) };
+    const { checkPaths } = await import('./round.js');
+    return { decisions: await checkPaths(workspace, brief, note, given, cwd, reader, options.base), brief };
+}
+/**
+ * Whether a decision is of a file the answer after the write is made from:
+ * the configuration, spec-brief's, the brief, or a file beside it in the
+ * briefs' directory, which spec-brief reads too. A call that writes one is
+ * decided again after the write, so that what the write changed is read
+ * (ADR-0002).
+ */
+function decidesAnswers(decision, brief) {
+    if (decision.path === CONFIG_FILE || SPEC_BRIEF_CONFIGS.includes(decision.path))
+        return true;
+    if (brief === null)
+        return false;
+    return decision.path === brief.file || decision.path.startsWith(`${dirname(brief.file)}/`);
 }
 const SYMBOL = { allow: 'ok     ', warn: 'warning', ask: 'ask    ', deny: 'refused' };
 async function guardCommand(options, io) {
@@ -134,10 +157,11 @@ async function readStdin(io) {
     return Buffer.concat(chunks).toString('utf8');
 }
 /**
- * The write Claude Code asks the hook about, 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.
+ * 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.
  */
 async function writeAsked(io) {
     let question;
@@ -157,7 +181,7 @@ async function writeAsked(io) {
         io.stderr.write(`spec-harness: ${request.error}\n`);
         return EXIT_FAILED;
     }
-    return request.paths.length === 0 ? EXIT_OK : request;
+    return request.paths.length === 0 && request.event !== SESSION_START ? EXIT_OK : request;
 }
 /**
  * What is wrong with the hook's own line, said and nothing refused for it:
@@ -165,10 +189,47 @@ async function writeAsked(io) {
  * that exits 1 and goes on with the write, where exit 2 would hold every
  * write of the session, the one that mends the line among them (ADR-0005).
  */
-function guardOff(io, { wrong, mend }) {
+function guardOff(io, { wrong, mend }, 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;
 }
+function answer(io, response) {
+    io.stdout.write(response.stdout);
+    return response.exitCode;
+}
+/**
+ * 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
+ * load, a brief named that spec-brief does not list or has archived, and
+ * spec-brief itself, where a brief is named, missing, too old or unable to
+ * list the briefs. Each in the words a write would be held with, and
+ * `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) {
+    const held = 'so every write of this session is held until it is mended';
+    try {
+        const named = await openWorkspace({ ...options, root }, io);
+        // A session in another work tree of the project has its writes decided
+        // 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`;
+    }
+    catch (error) {
+        // A session in no work tree has nothing to guard, as a write there has
+        // not. Anything else that stops the check stops a write's as well, which
+        // is then held as one the hook cannot check: a configuration that does
+        // not load, a spec-brief that is missing, too old or cannot list the
+        // briefs, and whatever a defect throws.
+        if (error instanceof UsageError)
+            return null;
+        return `${error.message}, ${held}; spec-harness doctor says more`;
+    }
+}
 /**
  * Claude Code's hook on a line the parser refused: an option no command has,
  * an option left without its value, a --format or an --at that is none. It
@@ -180,7 +241,115 @@ async function unreadLine(said, io) {
     const request = await writeAsked(io);
     if (typeof request === 'number')
         return request;
-    return guardOff(io, unreadHookLine(said).fault);
+    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).
+ *
+ * The git directory is the one the files at the hook's root name. What the
+ * run before the write kept for this call, if anything, is taken away as it
+ * is read, and answered from where it is this call's: the same release,
+ * session, call, tool, paths, directories, line and variables. And where
+ * nothing is kept, a run after a write says nothing but a warning outside
+ * the scope, which only `outOfScope: "warn"` decides: under `ask` or
+ * `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) {
+    const found = gitDirectories(root, io.env);
+    if (found === null)
+        return null;
+    if (record !== null) {
+        const kept = await takeCall(found.common, callFile(record));
+        // warningsKept reads no text as no record as well: the test is there for
+        // the type, and its mutant is equivalent.
+        const warnings = kept === null ? null : warningsKept(kept, record);
+        if (warnings !== null)
+            return afterResponse(warnings);
+    }
+    if (!found.exact || (cwd !== null && mayBeElsewhere(cwd, found.top)))
+        return null;
+    try {
+        return (await loadConfig(found.top)).config.outOfScope === 'warn' ? null : afterResponse([]);
+    }
+    catch {
+        // A configuration that does not load is said as it was, by the run.
+        return null;
+    }
 }
 async function hookCommand(options, io) {
     const kind = options.positionals[0];
@@ -192,11 +361,22 @@ async function hookCommand(options, io) {
         // reads the line where it finds it in a settings file (usage.ts).
         const line = readHookLine(options.root, io.cwd, isDirectory);
         if (line.state === 'off')
-            return guardOff(io, line.fault);
+            return guardOff(io, line.fault, request.event);
         const cwd = request.cwd ?? io.cwd;
+        const root = line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd;
+        if (request.event === SESSION_START)
+            return answer(io, sessionResponse(await sessionProblem(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);
+            if (answered !== null) {
+                io.stdout.write(answered.stdout);
+                return answered.exitCode;
+            }
+        }
         let workspace;
         try {
-            workspace = await openWorkspace({ ...options, root: line.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);
+            workspace = await openWorkspace({ ...options, root }, io);
         }
         catch (error) {
             if (error instanceof UsageError)
@@ -204,16 +384,35 @@ async function hookCommand(options, io) {
             throw error;
         }
         try {
-            const decided = await decisionsFor(workspace, options, io, request.paths, cwd);
-            if ('problem' in decided) {
-                // Exit 2 blocks the tool call, and its stderr reaches the model. Where
-                // the name stands on the hook's own line, what is wrong with it is
-                // `doctor`'s to say as well, in the same words (usage.ts).
-                io.stderr.write(`spec-harness: ${heldHookLine(decided.problem).wrong}. Fix the brief or the branch before writing.\n`);
-                return EXIT_ERROR;
+            // The answer reads a decision by its verdict, which a mutant's text
+            // put first on this list has none of: that mutant is equivalent.
+            const decisions = [];
+            // Whether the run after the write may answer from what this one keeps:
+            // not where a decision refuses, nor where the write is to what the
+            // 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);
+                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`);
+                    return EXIT_ERROR;
+                }
+                // A line of the answer for each path, by the work tree that decided it.
+                decisions.push(...decided.decisions);
+                if (decided.decisions.some((decision) => decision.verdict === 'deny' || decidesAnswers(decision, decided.brief)))
+                    keeps = false;
             }
-            const response = claudeResponse(request.event, decided.decisions);
+            const response = claudeResponse(request.event, decisions);
             io.stdout.write(response.stdout);
+            // What the run after the write will say, kept for it where the call
+            // goes ahead: a refused call has none. It changes nothing of the
+            // answer, which is made before it is kept.
+            if (request.event === 'PreToolUse' && record !== null && keeps) {
+                await keepCall(workspace.commonDir, callFile(record), keptCall(record, warningsOf(decisions)));
+            }
             return response.exitCode;
         }
         catch (error) {
@@ -226,7 +425,10 @@ async function hookCommand(options, io) {
         }
     }
     if (kind === 'git') {
-        const workspace = await openWorkspace(options, io);
+        // git starts its hook at the top of the work tree it commits in, a
+        // linked worktree's own, whose install may be none: it is then checked
+        // with the main work tree's (ADR-0005).
+        const workspace = await openWorkspace(options, io, MAIN_INSTALL);
         const staged = await stagedChanges(workspace.root);
         const paths = staged.flatMap((change) => (change.from === undefined ? [change.path] : [change.from, change.path]));
         if (paths.length === 0)
@@ -248,7 +450,7 @@ async function hookCommand(options, io) {
  * the base, and the two on nothing else doctor asks. A --base given nothing
  * is no base, said as the brief's is, in the report.
  */
-async function baseAndSigners(workspace, flag, signersFile) {
+async function baseAndSigners({ resolveBase }, workspace, flag, signersFile) {
     // Nothing in doctor asks what kind a base is but whether it is resolved, so
     // the mutant that names this one otherwise is equivalent.
     const base = flag !== undefined && isBlank(flag) ? { kind: 'unresolved', reason: emptyValue('--base', 'base', flag) } : await resolveBase(workspace, flag);
@@ -261,25 +463,38 @@ async function baseAndSigners(workspace, flag, signersFile) {
  * 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
  * is asked its release, since one older than the hooks need lets every
- * write through unguarded. `null` where it was not asked.
+ * 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.
  */
-async function wiringAndRelease(root, io) {
-    const wiring = await claudeCodeWiring(root, io);
-    const release = wiringState(wiring) === 'none' ? null : checkClaudeCode(await claudeVersion(io.env));
+async function wiringAndRelease({ claudeCodeWiring }, root, io) {
+    const { release, ...wiring } = await claudeCodeWiring(root, io);
     return { wiring, release };
 }
 async function doctorCommand(options, io) {
-    const workspace = await openWorkspace(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 { diagnoseBrief, specBriefPlugin } = round;
+    const { gitHook } = setup;
+    const { notFido2, readAllowedSigners } = signing;
+    // The siblings as git's hook finds them in this work tree: its own
+    // install, and in a linked worktree with none the main work tree's.
+    const workspace = await openWorkspace(options, io, MAIN_INSTALL);
     const rows = SIBLINGS.map((name) => {
         const sibling = workspace.siblings.locate(name);
         const row = { tool: name, state: sibling.kind, minimum: MINIMUM_VERSIONS[name] };
         if (sibling.kind === 'absent')
-            return { ...row, version: null, detail: sibling.reason };
+            return { ...row, version: null, elsewhere: null, detail: sibling.reason };
+        const elsewhere = sibling.elsewhere ?? null;
+        const whose = elsewhere === null ? '' : `, the install of ${elsewhere}: this work tree has none of its own`;
         if (sibling.kind === 'outdated')
-            return { ...row, version: sibling.version, detail: sibling.reason };
+            return { ...row, version: sibling.version, elsewhere, detail: `${sibling.reason}${whose}` };
         const command = sibling.command.join(' ');
-        const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version})`;
-        return { ...row, version: sibling.version, detail };
+        const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version}${whose})`;
+        return { ...row, version: sibling.version, elsewhere, detail };
     });
     const signersFile = workspace.config.rulings.allowedSigners;
     // Five things that wait on the work tree and on nothing of one another,
@@ -291,9 +506,9 @@ async function doctorCommand(options, io) {
     // failed first by the clock (ADR-0002).
     const [briefAsked, baseAsked, pluginAsked, claudeAsked, hookAsked] = await Promise.allSettled([
         diagnoseBrief(workspace, options, io.env),
-        baseAndSigners(workspace, options.base, signersFile),
+        baseAndSigners(round, workspace, options.base, signersFile),
         specBriefPlugin(workspace.root),
-        wiringAndRelease(workspace.root, io),
+        wiringAndRelease(round, workspace.root, io),
         gitHook(workspace.root),
     ]);
     const named = answerOf(briefAsked);
@@ -322,6 +537,9 @@ async function doctorCommand(options, io) {
     // this machine, or cannot be told to be, and disableAllHooks, which
     // switches off whatever hooks there are.
     const switchedOff = guardSwitchedOff(wiring);
+    // 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);
     // 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.
@@ -370,6 +588,7 @@ async function doctorCommand(options, io) {
             ...more(wiringNotes),
             ...more(lineNotes),
             ...more(release === null ? [] : [describeClaudeRelease(release)]),
+            ...more(atStart === null ? [] : [atStart]),
             `git     ${describeGitHook(hook)}`,
             ...more(hookNote === null ? [] : [hookNote]),
             '',
@@ -384,17 +603,22 @@ async function doctorCommand(options, io) {
     // 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, and a Claude Code too old to run the hooks. A release that
-    // cannot be told is not fine either, nor a line whose reading cannot be,
-    // nor a plugin that cannot be told to be on this machine: --strict fails
-    // the three.
+    // 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.
     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 untold = options.strict && (release?.state === 'unknown' || wiring.lines.some((line) => line.state === 'unknown') || wiring.presence?.state === 'unknown');
-    return outdated || !usable || claude === 'both' || off || switchedOff || missing || tooOld || untold ? EXIT_FAILED : EXIT_OK;
+    const stopped = hook.state === 'stops';
+    // 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;
 }
 /* ---------------------------------------------------------------- dispatch */
 /**
@@ -404,19 +628,21 @@ async function doctorCommand(options, io) {
  * construct` is an unknown command with exit 2.
  */
 const COMMANDS = new Map(
-// One for every command that has a shape (usage.ts), which the compiler holds.
+// One for every command that has a shape (usage.ts), which the compiler
+// holds. A command of another module loads its module when it is the one
+// typed, and no other command's.
 Object.entries({
     guard: guardCommand,
     hook: hookCommand,
-    context: contextCommand,
-    audit: auditCommand,
-    escalate: escalateCommand,
-    rule: ruleCommand,
-    rulings: rulingsCommand,
-    probe: probeCommand,
-    premises: premisesCommand,
-    init: initCommand,
-    mcp: mcpCommand,
+    context: async (options, io) => (await import('./commands.js')).contextCommand(options, io),
+    audit: async (options, io) => (await import('./commands.js')).auditCommand(options, io),
+    escalate: async (options, io) => (await import('./commands.js')).escalateCommand(options, io),
+    rule: async (options, io) => (await import('./commands.js')).ruleCommand(options, io),
+    rulings: async (options, io) => (await import('./commands.js')).rulingsCommand(options, io),
+    probe: async (options, io) => (await import('./commands.js')).probeCommand(options, io),
+    premises: async (options, io) => (await import('./premises.js')).premisesCommand(options, io),
+    init: async (options, io) => (await import('./setup.js')).initCommand(options, io),
+    mcp: async (options, io) => (await import('./server.js')).mcpCommand(options, io),
     doctor: doctorCommand,
 }));
 async function dispatch(argv, io) {
@@ -434,16 +660,20 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: ${refused.message}\n`);
         return EXIT_ERROR;
     }
-    if (options.version) {
-        io.stdout.write(`${version()}\n`);
-        return EXIT_OK;
-    }
-    if (options.help || options.command === undefined) {
-        io.stdout.write(HELP);
-        return options.help ? EXIT_OK : EXIT_ERROR;
+    // Two values for an option that takes one: the parser kept the last, and
+    // which was meant cannot be told from the line, so it is refused as a line
+    // the parser cannot read is, and Claude Code's hook says it of its own.
+    const twice = twoValues(options, io.cwd);
+    if (twice !== null) {
+        if (isClaudeHook(options.command, options.positionals[0]))
+            return unreadLine(twice, io);
+        io.stderr.write(`spec-harness: ${twice}; give it one\n`);
+        return EXIT_ERROR;
     }
-    const command = COMMANDS.get(options.command);
-    if (command === undefined) {
+    // A line that is wrong is refused before --help or --version answers: an
+    // answer beside it said nothing of what was wrong, exit 0, as an option no
+    // command has never was (spec-core ADR-0005).
+    if (options.command !== undefined && !COMMANDS.has(options.command)) {
         io.stderr.write(`spec-harness: unknown command "${options.command}"; see spec-harness --help\n`);
         return EXIT_ERROR;
     }
@@ -453,7 +683,15 @@ async function dispatch(argv, io) {
         io.stderr.write(`spec-harness: ${refused}\n`);
         return EXIT_ERROR;
     }
-    return command(options, io);
+    if (options.version) {
+        io.stdout.write(`${version()}\n`);
+        return EXIT_OK;
+    }
+    if (options.help || options.command === undefined) {
+        io.stdout.write(HELP);
+        return options.help ? EXIT_OK : EXIT_ERROR;
+    }
+    return COMMANDS.get(options.command)(options, io);
 }
 /**
  * Runs the command line and resolves to the exit code, for an error nothing
@@ -474,6 +712,12 @@ async function dispatch(argv, io) {
  * launcher answers in the same words; here it is a caller's stream that
  * throws it. It is read by its code: stdout and stderr are the only pipes
  * the harness writes to.
+ *
+ * Nor is a module of the build that is not there. The launcher says a build
+ * without its command line in a line, and a module a command asks for where
+ * it runs is said in the same line: a build with a file missing is not a
+ * defect a stack leads to. It is read by its code too: the harness imports
+ * nothing but its own modules and Node's.
  */
 export async function run(argv, io) {
     try {
@@ -482,12 +726,15 @@ export async function run(argv, io) {
     catch (error) {
         // A sibling's document of a shape the harness does not read is a sibling
         // that printed something it cannot read (answers.ts): exit 2. A git
-        // command that failed is what git said, and no line of the harness's.
+        // command that failed is what git said, and no line of the harness's;
+        // and a path under git's directory where the harness keeps its state,
+        // which holds something else, is said in a line of its own (fs.ts).
         if (error instanceof UsageError ||
             error instanceof ConfigError ||
             error instanceof SiblingError ||
             error instanceof SiblingOutputError ||
-            error instanceof GitError) {
+            error instanceof GitError ||
+            error instanceof StateError) {
             io.stderr.write(`spec-harness: ${error.message}\n`);
             return EXIT_ERROR;
         }
@@ -495,6 +742,8 @@ export async function run(argv, io) {
             io.stderr.write(`spec-harness: unexpected error: ${String(error)}\n`);
         else if (error.code === 'EPIPE')
             io.stderr.write('spec-harness: stdout was closed before all of the output was written\n');
+        else if (error.code === 'ERR_MODULE_NOT_FOUND')
+            io.stderr.write('spec-harness: build output is missing; run "npm run build" first, or install the published package.\n');
         else
             io.stderr.write(`spec-harness: unexpected error: ${error.stack ?? error.message}\n`);
         return EXIT_ERROR;