@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/dist/configure.js

@@ -52,12 +52,34 @@ const BEFORE = 'PreToolUse';
 /** The event after a call that succeeded, where a hook can only tell the model what it wrote. */
 const AFTER = 'PostToolUse';
 const GUARDED_EVENTS = [BEFORE, AFTER];
+/**
+ * The event Claude Code runs as a session starts, under which the hook says
+ * what would hold every write of it (ADR-0005). Its entry has no matcher:
+ * left out, it is every way a session starts.
+ */
+const AT_START = 'SessionStart';
+/**
+ * The event Claude Code runs as its main agent finishes a turn, under which
+ * the hook reports what the work tree holds where `turnReport` is on
+ * (ADR-0005). Its entry has no matcher: the event takes none.
+ */
+const AT_TURN_END = 'Stop';
 const GUARD_ARGS = Object.freeze([`${PROJECT_DIR}/${BIN}`, 'hook', 'claude']);
 /**
  * The guard as a Claude Code hook: exec form, `args` given, so the project's
  * path is one argument whatever it holds, and no shell is involved.
  */
 export const GUARD_HOOK = Object.freeze({ type: 'command', command: 'node', args: GUARD_ARGS, timeout: 60 });
+/**
+ * The hook's entry at the end of a turn: the guard's line, run in the
+ * background. Claude Code waits on no part of it, so the turn ends as it
+ * would, and it hands the hook's `systemMessage` to Claude as the next
+ * turn begins, where from an entry it waits on it shows the person the
+ * message instead (the hooks reference,
+ * https://code.claude.com/docs/en/hooks, *Run hooks in the background* and
+ * *JSON output*, read 2026-10-19).
+ */
+export const TURN_HOOK = Object.freeze({ ...GUARD_HOOK, async: true });
 // bare-name: what 0.1 installed, an npx command found from wherever the
 // session stood. Read here so that init replaces it, and never run.
 const LEGACY_HOOK = 'npx --no-install spec-harness hook claude';
@@ -96,10 +118,13 @@ function upgraded(group) {
  * common causes, read 2026-10-14). A matcher that is an array is an entry
  * Claude Code lists as an invalid setting, among the reasons a hook is not
  * loaded and never fires: no tool. And a comma separates names only from
- * {@link COMMA_SINCE} on, so a matcher that lists names with one is read as
- * `commas` has the Claude Code here read it.
+ * {@link COMMA_SINCE} on; its changelog adds that a hyphenated name is
+ * matched exactly only from {@link HYPHEN_SINCE} on. So a matcher of names
+ * with either in it is read as `matching` has the Claude Code here read it
+ * ({@link namesReadings}), and where the readings it may have differ, it
+ * cannot be told.
  */
-function matchedTools(matcher, pattern, commas) {
+function matchedTools(matcher, pattern, matching) {
     if (matcher === undefined || matcher === '' || matcher === '*')
         return CALLABLE_TOOLS;
     if (Array.isArray(matcher))
@@ -108,14 +133,11 @@ function matchedTools(matcher, pattern, commas) {
         return null;
     if (!NAMES.test(matcher))
         return pattern(matcher);
-    const comma = commas.as === 'separator' ? null : commaReading(matcher, pattern);
-    if (comma === null)
-        return listedTools(matcher);
-    if (commas.as === 'pattern')
-        return comma.earlier;
-    // Which of the two readings holds cannot be told, and where both are no
-    // tool that writes it need not be.
-    return comma.earlier !== null && comma.listed.length === 0 ? comma.listed : null;
+    // A reading that cannot be told, or two that differ, leave the matcher one
+    // whose tools cannot be told; where every reading comes to the same tools,
+    // nothing turns on which the release has.
+    const readings = namesReadings(matcher, pattern, matching);
+    return readings.every((tools) => sameStrings(tools, readings[0])) ? readings[0] : null;
 }
 /** A matcher that is a name, or names between `|` and `,`: what the reference compares with a tool's name exactly. */
 const NAMES = /^[A-Za-z0-9_\- ,|]*$/;
@@ -133,26 +155,63 @@ function listedTools(matcher) {
  * silently never firing.
  */
 export const COMMA_SINCE = '2.1.191';
-/** The reading every release from {@link COMMA_SINCE} on has, and what a caller that asks no release is given. */
-const SEPARATOR = { as: 'separator' };
 /**
- * How the Claude Code doctor asked its release reads a comma. A release that
- * was not asked, or could not be told, leaves the reading untold: asked or
- * not, nothing says which it is.
+ * The release of Claude Code from which a hyphenated name in a matcher of
+ * names is matched exactly. Its changelog
+ * (https://code.claude.com/docs/en/changelog, 2.1.195, read 2026-10-18) has,
+ * among its fixes, hook matchers with hyphenated identifiers that matched as
+ * substrings, and match exactly from this release on; it does not say how
+ * the rest of such a matcher was read.
  */
-export function commasUnder(release) {
+export const HYPHEN_SINCE = '2.1.195';
+/** The reading every release from {@link HYPHEN_SINCE} on has, and what a caller that asks no release is given. */
+const TODAY = { as: 'today' };
+/**
+ * How the Claude Code doctor asked its release reads a matcher of names. A
+ * release that was not asked, or could not be told, leaves the reading
+ * untold: asked or not, nothing says which it is.
+ */
+export function matchingUnder(release) {
     if (release === null || release.state === 'unknown')
         return { as: 'untold' };
     // A release that was told is one whose version was read as one, and the
     // constant is a version, so both parse.
-    return meets(parseVersion(release.version), parseVersion(COMMA_SINCE)) ? SEPARATOR : { as: 'pattern', release: release.version };
-}
-/** The two readings of a matcher of names that holds a comma, or `null` for any other matcher, which every release reads one way. */
-function commaReading(matcher, pattern) {
-    if (typeof matcher !== 'string' || !NAMES.test(matcher) || !matcher.includes(','))
-        return null;
+    return meets(parseVersion(release.version), parseVersion(HYPHEN_SINCE)) ? TODAY : { as: 'older', release: release.version };
+}
+/** Whether `release` reads a comma in `matcher` as part of a pattern: one before {@link COMMA_SINCE}, where the matcher holds one. */
+function commaAsPattern(matcher, release) {
+    return matcher.includes(',') && !meets(parseVersion(release), parseVersion(COMMA_SINCE));
+}
+/** A matcher of names that holds a comma, as a release before {@link COMMA_SINCE} reads it. */
+function commaEarlier(matcher, pattern) {
+    // No tool, where the matcher read as a pattern matches none of the writing
+    // tools, which is what the page has such a matcher do; and where it matches
+    // one, as `Edit|Write,Bash` matches `Edit`, the page's two sentences, that
+    // a comma is read as part of a pattern and that the matcher never matched,
+    // disagree, and it cannot be told.
     const read = pattern(matcher);
-    return { listed: listedTools(matcher), earlier: read !== null && read.length === 0 ? read : null };
+    return read !== null && read.length === 0 ? read : null;
+}
+/**
+ * Each reading the Claude Code here may have of a matcher of names: the
+ * writing tools it lists, or `null` where a reading cannot be told. From
+ * {@link HYPHEN_SINCE} on there is one, the names matched exactly. Before
+ * {@link COMMA_SINCE} a comma in it makes it a pattern ({@link commaEarlier}).
+ * Before {@link HYPHEN_SINCE} a hyphen in it made it match as a substring,
+ * and the changelog does not say which way: each name matched exactly but
+ * the one with the hyphen, the matcher read as a pattern, which matches
+ * anywhere in a tool's name, or its whole text found in a tool's name, which
+ * no writing tool's holds, since none has a hyphen. A release that cannot be
+ * told may read it any way a release does.
+ */
+function namesReadings(matcher, pattern, matching) {
+    const listed = listedTools(matcher);
+    if (matching.as === 'today')
+        return [listed];
+    const substring = matcher.includes('-') ? [pattern(matcher), []] : [];
+    if (matching.as === 'older')
+        return commaAsPattern(matcher, matching.release) ? [commaEarlier(matcher, pattern)] : [listed, ...substring];
+    return [listed, ...(matcher.includes(',') ? [commaEarlier(matcher, pattern)] : []), ...substring];
 }
 /**
  * How long the reading of one pattern may take, in milliseconds of the
@@ -223,12 +282,12 @@ function inBackground(hook) {
  * entry started only for the calls its rule matches, in the syntax of a
  * permission rule, which is not read here.
  */
-function answered(event, matcher, hook, pattern, commas) {
+function answered(event, matcher, hook, pattern, matching) {
     if (event === BEFORE && inBackground(hook))
         return [];
     if (hook['if'] !== undefined)
         return null;
-    return matchedTools(matcher, pattern, commas);
+    return matchedTools(matcher, pattern, matching);
 }
 /**
  * `.claude/settings.json`, or the plugin's hooks, with the guard hooks merged
@@ -245,14 +304,14 @@ function answered(event, matcher, hook, pattern, commas) {
  *
  * `pattern` reads a matcher that is a pattern: the run's own reader, where
  * the run has read the file's matchers already ({@link patternReader}).
- * `commas` is how the Claude Code here reads a comma in a matcher of names,
- * where the run asked its release ({@link commasUnder}): a line that
+ * `matching` is how the Claude Code here reads a matcher of names, where
+ * the run asked its release ({@link matchingUnder}): a line that
  * release starts for no write is no guard, and init's own is written beside
  * it.
  */
-export function mergeClaudeSettings(current, isHook = () => false, pattern = patternReader(), commas = SEPARATOR) {
+export function mergeClaudeSettings(current, isHook = () => false, pattern = patternReader(), matching = TODAY) {
     const hooks = isObject(current['hooks']) ? current['hooks'] : {};
-    const theirs = harnessEntries(current).some((entry) => !isGuard(entry.hook) && !isLegacyGuard(entry.hook) && isHook(entry.words) && isStarted(toolsOf(entry, pattern, commas)));
+    const theirs = harnessEntries(current).some((entry) => !isGuard(entry.hook) && !isLegacyGuard(entry.hook) && isHook(entry.words) && isStarted(toolsOf(entry, pattern, matching)));
     if (theirs)
         return null;
     let changed = false;
@@ -262,7 +321,7 @@ export function mergeClaudeSettings(current, isHook = () => false, pattern = pat
         const before = Array.isArray(listed) ? listed : [];
         const groups = before.map(upgraded);
         const replaced = groups.some((group, index) => group !== before[index]);
-        const present = harnessEntries({ hooks: { [event]: groups } }).some((entry) => isGuard(entry.hook) && isStarted(toolsOf(entry, pattern, commas)));
+        const present = harnessEntries({ hooks: { [event]: groups } }).some((entry) => isGuard(entry.hook) && isStarted(toolsOf(entry, pattern, matching)));
         if (!present)
             groups.push({ matcher: HOOK_MATCHER, hooks: [{ ...GUARD_HOOK, args: [...GUARD_ARGS] }] });
         if (replaced || !present) {
@@ -272,6 +331,110 @@ export function mergeClaudeSettings(current, isHook = () => false, pattern = pat
     }
     return changed ? { ...current, hooks: next } : null;
 }
+/**
+ * Settings with init's entry under `SessionStart` added beside its two, or
+ * `null` where it is not to be: where init's own line does not stand
+ * under both `PreToolUse` and `PostToolUse`, a file init writes no hook
+ * into or one it has yet to complete; and where a line of the hook stands
+ * under `SessionStart` already, init's or one `isHook` knows, which would
+ * say the same twice (ADR-0012).
+ */
+export function withSessionStart(settings, isHook) {
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const own = GUARDED_EVENTS.every((event) => harnessEntries({ hooks: { [event]: hooks[event] } }).some((entry) => isGuard(entry.hook)));
+    if (!own || startsSessions(settings, isHook))
+        return null;
+    const listed = hooks[AT_START];
+    return { ...settings, hooks: { ...hooks, [AT_START]: [...(Array.isArray(listed) ? listed : []), { hooks: [{ ...GUARD_HOOK, args: [...GUARD_ARGS] }] }] } };
+}
+/** The events init writes its own line under. */
+const INIT_EVENTS = [BEFORE, AFTER, AT_START];
+/**
+ * Settings with `onFailure: "block"` on each of init's own entries, under
+ * the three events it writes them under, or `null` where each has it
+ * already: `init --block-on-failure`. Claude Code's hooks reference
+ * (https://code.claude.com/docs/en/hooks, Block the action when a hook
+ * fails, read 2026-10-19) has the field read by Claude Code 2.1.295 and
+ * later, and a failure under it, a hook that cannot start or that reaches
+ * its timeout among them, do what exit 2 does on its event: before a write,
+ * hold it. What a release before 2.1.295 does with the key is on no page, so
+ * init writes it only where it is asked to (ADR-0012). An entry a person
+ * wrote is theirs, and is left as it is.
+ */
+export function withOnFailure(settings) {
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const unblocked = (hook) => isGuard(hook) && hook['onFailure'] !== 'block';
+    const next = { ...hooks };
+    let changed = false;
+    for (const event of INIT_EVENTS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups) || !groups.some((group) => hooksOf(group).some(unblocked)))
+            continue;
+        next[event] = groups.map((group) => (hooksOf(group).some(unblocked) ? { ...group, hooks: hooksOf(group).map((hook) => (unblocked(hook) ? { ...hook, onFailure: 'block' } : hook)) } : group));
+        changed = true;
+    }
+    return changed ? { ...settings, hooks: next } : null;
+}
+/**
+ * Whether settings have Claude Code start the hook as a session starts: an
+ * entry under `SessionStart` whose line is init's, or one `isHook` knows
+ * as the hook's. Its matcher is not read: one that names some of the ways a
+ * session starts has the check made for those.
+ */
+export function startsSessions(settings, isHook) {
+    const groups = field(field(settings, 'hooks'), AT_START);
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => hooksOf(group).some((hook) => isObject(hook) && (isGuard(hook) || knownAs(hook, isHook))));
+}
+/**
+ * Settings with init's entry under `Stop` added, or `null` where a line
+ * of the hook stands there already, init's or one `isHook` knows, which
+ * would report the turn twice (ADR-0012).
+ */
+export function withTurnReport(settings, isHook) {
+    if (reportsTurns(settings, isHook))
+        return null;
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const listed = hooks[AT_TURN_END];
+    return { ...settings, hooks: { ...hooks, [AT_TURN_END]: [...(Array.isArray(listed) ? listed : []), { hooks: [{ ...TURN_HOOK, args: [...GUARD_ARGS] }] }] } };
+}
+/** Whether settings have Claude Code start the hook as a turn ends: an entry under `Stop` whose line is init's, or one `isHook` knows as the hook's. */
+export function reportsTurns(settings, isHook) {
+    const groups = field(field(settings, 'hooks'), AT_TURN_END);
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => hooksOf(group).some((hook) => isObject(hook) && (isGuard(hook) || knownAs(hook, isHook))));
+}
+/** Whether `isHook` knows an entry's line as the hook's. */
+function knownAs(hook, isHook) {
+    const written = writtenHook(hook);
+    return written !== null && isHook(written.words);
+}
+/**
+ * What doctor notes where settings hold the guard hooks and none under
+ * `SessionStart`: what would hold every write is said at the first write,
+ * which it holds, and not as the session starts.
+ */
+export const NO_SESSION_START = 'note: no settings file has Claude Code start the hook as a session starts, so a configuration that does not load, or a brief named that spec-brief does not list, is said only at the first write, which it holds: spec-harness init --write adds the entry beside the two it wrote';
+/**
+ * What doctor notes, run in a linked worktree, of the spec-harness the
+ * hook's line runs: the one installed where `${CLAUDE_PROJECT_DIR}` points,
+ * which is this work tree in a session started in it, and the main
+ * checkout in a worktree session of the desktop app's, where Claude Code
+ * reads the hooks from the main checkout's root and points the placeholder
+ * at it (its worktrees page, What worktrees share with the main checkout,
+ * read 2026-10-19). Said where the two are not one release, `null` for
+ * none, and `null` where they are. A note: from 0.19.0 on either decides a
+ * write by the work tree that holds it, so it says which release answers,
+ * not where a write is decided.
+ */
+export function describeInstalls(main, there, here) {
+    if (there === here)
+        return null;
+    const release = (version) => (version === null ? 'none' : version);
+    return `note: this is a linked worktree of ${main}, and the hook's line runs the spec-harness installed where \${CLAUDE_PROJECT_DIR} points: this work tree's, ${release(here)}, in a session started here, and ${main}'s, ${release(there)}, in one started there, as a worktree session of the desktop app is`;
+}
 /** The server's entry, reading the project at `projectDir`: {@link PROJECT_DIR} for the plugin, {@link PROJECT_DIR_OR_HERE} for a project. */
 export function mcpServer(projectDir) {
     return { command: 'node', args: [`${projectDir}/${BIN}`, 'mcp', '--root', projectDir] };
@@ -367,8 +530,8 @@ function sameLine(one, other) {
  * `null` where that cannot be told. Read where it is asked for and no
  * sooner: a matcher that is a pattern can cost its whole budget.
  */
-function toolsOf(entry, pattern, commas) {
-    return answered(entry.event, entry.matcher, entry.hook, pattern, commas);
+function toolsOf(entry, pattern, matching) {
+    return answered(entry.event, entry.matcher, entry.hook, pattern, matching);
 }
 /** Every entry that runs the harness under the two events the guard answers, in the order the settings hold them. */
 function harnessEntries(settings) {
@@ -395,17 +558,40 @@ export function isStarted(tools) {
 }
 /**
  * The release of Claude Code that reads `onFailure` on a hook's entry, by its
- * hooks reference (https://code.claude.com/docs/en/hooks, read 2026-10-12).
+ * hooks reference (https://code.claude.com/docs/en/hooks, Command hook
+ * fields, read 2026-10-19) and its changelog, which adds the field under it.
+ */
+export const ON_FAILURE_SINCE = '2.1.295';
+/** Whether the Claude Code doctor asked its release reads `onFailure`: one that was told, at {@link ON_FAILURE_SINCE} or later. */
+export function readsOnFailure(release) {
+    // A release that was told is one whose version was read as one, and the
+    // constant is a version, so both parse.
+    return release !== null && release.state !== 'unknown' && meets(parseVersion(release.version), parseVersion(ON_FAILURE_SINCE));
+}
+/**
+ * What `onFailure: "block"` changes for a line, named by `where` it stands,
+ * or `null` where the entry does not set it. The hook fails for none of its
+ * own answers, a line of its own that turns the guard off among them, which
+ * it says with exit 0 (ADR-0005): what the field holds is a hook that does
+ * not run.
  */
-const ON_FAILURE_SINCE = '2.1.295';
-/** What `onFailure: "block"` changes for a line, named by `where` it stands, or `null` where the entry does not set it. */
-function describeOnFailure(where, blocks, off) {
+function describeOnFailure(where, blocks) {
     if (!blocks)
         return null;
-    const holds = `${where} sets onFailure to "block", so Claude Code ${ON_FAILURE_SINCE} or later holds a write when the hook fails`;
-    if (off)
-        return `${holds}, which with this line is every write, the one that mends the line among them: mend it by hand`;
-    return `${holds}, where it lets the write go ahead without it: by its exit 1 for a question it cannot read, by not starting, or by running past its timeout`;
+    return `${where} sets onFailure to "block", so Claude Code ${ON_FAILURE_SINCE} or later holds a write when the hook fails, where it lets the write go ahead without it: by not starting, as where the script on its line is not there, or by running past its timeout`;
+}
+/**
+ * What is said of a line that guards and whose entries set no `onFailure`,
+ * where the Claude Code here reads the field: a hook that cannot start lets
+ * the write go ahead, and the field would hold it. Advice, which fails
+ * nothing: the file is read by every clone's Claude Code, and what a release
+ * before {@link ON_FAILURE_SINCE} does with the key is on no page. `own` is
+ * whether the entries are init's, in the file init writes, which
+ * `init --block-on-failure` gives the field.
+ */
+function adviseOnFailure(where, own) {
+    const how = own ? 'spec-harness init --write --block-on-failure writes it on these entries' : 'it is written on each of its entries';
+    return `${where} sets no onFailure, so Claude Code lets a write go ahead where the hook cannot start, as where the script on its line is not there, or runs past its timeout: where every Claude Code that reads the file is ${ON_FAILURE_SINCE} or later, as the one here is, "onFailure": "block" holds the write instead, and ${how}`;
 }
 /** Names as a sentence lists them: one, two with "and", more with commas before it. Never asked of none. */
 function named(names) {
@@ -414,30 +600,38 @@ function named(names) {
 }
 /** The writing tools a line's entries under `event` are waited on for between them, or `null` where an entry that cannot be told might add one. */
 function toolsUnder(event, entries, reading) {
-    const read = entries.filter((entry) => entry.event === event).map((entry) => toolsOf(entry, reading.pattern, reading.commas));
+    const read = entries.filter((entry) => entry.event === event).map((entry) => toolsOf(entry, reading.pattern, reading.matching));
     const sure = CALLABLE_TOOLS.filter((tool) => read.some((tools) => tools !== null && tools.includes(tool)));
     return sure.length < CALLABLE_TOOLS.length && read.some((tools) => tools === null) ? null : sure;
 }
 /**
  * What is said after a matcher that Claude Code does not read as its text
- * suggests: an array, which it loads no hook under, and names with a comma
- * where the release here reads the comma another way than the newest does,
- * or cannot be told. Nothing for any other matcher, and nothing for a comma
- * where both readings come to no tool that writes.
+ * suggests: an array, which it loads no hook under, and names with a comma or
+ * a hyphen where the release here reads them another way than the newest
+ * does, or cannot be told. Nothing for any other matcher, and nothing where
+ * every reading the release may have is the names as listed.
  */
-function saidOfMatcher(matcher, { pattern, commas }) {
+function saidOfMatcher(matcher, { pattern, matching }) {
     if (Array.isArray(matcher))
         return ', an array, which Claude Code lists as an invalid setting and loads no hook under';
-    if (commas.as === 'separator')
+    if (typeof matcher !== 'string' || !NAMES.test(matcher))
         return '';
-    const comma = commaReading(matcher, pattern);
-    if (comma === null || (comma.earlier !== null && comma.listed.length === 0))
+    const tools = listedTools(matcher);
+    if (namesReadings(matcher, pattern, matching).every((read) => sameStrings(read, tools)))
         return '';
-    const listed = comma.listed.length === 0 ? 'no tool that writes' : named(comma.listed);
-    const earlier = comma.earlier === null ? 'a pattern whose matches its documentation does not give' : 'a pattern that matches no tool';
-    if (commas.as === 'untold')
+    const listed = tools.length === 0 ? 'no tool that writes' : named(tools);
+    const earlier = commaEarlier(matcher, pattern) === null ? 'a pattern whose matches its documentation does not give' : 'a pattern that matches no tool';
+    const substring = "a matcher with a hyphenated name in it matched as a substring, and Claude Code's changelog does not say how the rest of it was read";
+    if (matching.as === 'older') {
+        if (commaAsPattern(matcher, matching.release))
+            return `, which Claude Code ${matching.release} reads as ${earlier}: a comma separates names from ${COMMA_SINCE} on, where the matcher is ${listed}`;
+        return `, which Claude Code ${matching.release} may read otherwise: before ${HYPHEN_SINCE} ${substring}; from ${HYPHEN_SINCE} on it is ${listed}`;
+    }
+    // The release cannot be told: a comma alone turns on 2.1.191, and a hyphen on 2.1.195.
+    if (!matcher.includes('-'))
         return `, which is ${listed} from Claude Code ${COMMA_SINCE} on, where a comma separates names, and ${earlier} before it: the release here cannot be told`;
-    return `, which Claude Code ${commas.release} reads as ${earlier}: a comma separates names from ${COMMA_SINCE} on, where the matcher is ${listed}`;
+    const comma = matcher.includes(',') ? `, and before ${COMMA_SINCE} ${earlier}, where a comma separated no names` : '';
+    return `, which is ${listed} from Claude Code ${HYPHEN_SINCE} on, and may be read otherwise before it, where ${substring}${comma}: the release here cannot be told`;
 }
 /** What a line's entries under `event` hold that decides when Claude Code starts them, as written. */
 function entriesUnder(event, entries, reading) {
@@ -538,18 +732,18 @@ export function handedLines(sources, project) {
  *
  * `pattern` reads a matcher that is a pattern, once for every entry under
  * it in every file: the run's own reader, where something else in the run
- * reads the same files ({@link patternReader}). `commas` is how the Claude
- * Code here reads a comma in a matcher of names, where its release was
- * asked ({@link commasUnder}); a caller that asks none reads a comma as
- * every release from {@link COMMA_SINCE} on does.
+ * reads the same files ({@link patternReader}). `matching` is how the
+ * Claude Code here reads a matcher of names, where its release was asked
+ * ({@link matchingUnder}); a caller that asks none reads one as every
+ * release from {@link HYPHEN_SINCE} on does.
  *
  * A file that holds an array for a matcher under `PreToolUse` or
  * `PermissionRequest` has none of its hooks loaded ({@link arrayMatcher}):
  * each line of the hook there is started for no write, and one that stood
  * to be started for a write is a guard that is off.
  */
-export function reportHooks(sources, project, read, pattern = patternReader(), commas = SEPARATOR) {
-    const reading = { pattern, commas };
+export function reportHooks(sources, project, read, pattern = patternReader(), matching = TODAY, onFailureHere = false) {
+    const reading = { pattern, matching };
     return sources.flatMap(({ file, settings }) => {
         const entries = harnessEntries(settings);
         const array = arrayMatcher(settings);
@@ -579,7 +773,10 @@ export function reportHooks(sources, project, read, pattern = patternReader(), c
                 return [{ ...unloaded, state: 'unstarted', detail: `${said}: the line is not started, and stood to be started for no write as it is, so no guard is switched off` }];
             }
             const written = { file, events: hook.events, line: hook.words, onFailure: hook.blocks ? 'block' : null, before, after, cover: describeCover(where, before, after, mine, reading) };
-            const note = describeOnFailure(where, hook.blocks, false);
+            const note = describeOnFailure(where, hook.blocks);
+            // Where the release here reads the field, a line that guards without it is advised it.
+            const own = file === PROJECT_SETTINGS && mine.every((entry) => isGuard(entry.hook));
+            const guards = (detail) => ({ ...written, state: 'guards', detail, note: note ?? (onFailureHere ? adviseOnFailure(where, own) : null) });
             if (hook.untyped !== null) {
                 const detail = `${where} stands on an entry with ${hook.untyped}, where Claude Code's hooks reference has "type": "command" on an entry it runs as a command, so whether Claude Code runs it cannot be told here: give the entry "type": "command"`;
                 return [{ ...written, state: 'unknown', detail, note }];
@@ -593,15 +790,12 @@ export function reportHooks(sources, project, read, pattern = patternReader(), c
             const waited = before === null || before.length > 0;
             if (handed.state === 'off') {
                 const detail = `${where}: ${handed.fault.wrong}, so the guard is off and ${handed.unchecked ?? 'no write is checked'}; ${handed.fault.mend}`;
-                // A fault the hook says, it says with exit 1 after every write it is
-                // started for as well, so it is said wherever the line stands.
-                if (handed.silent !== true)
-                    return [{ ...written, state: 'off', detail, note: describeOnFailure(where, hook.blocks, true) }];
-                // A root outside any work tree, or in one that does not hold the
-                // project, of which the hook says nothing: no run of it fails
-                // there, so onFailure holds no write for it, and where the line is
-                // waited on before no write there is none it leaves unchecked.
-                return [waited ? { ...written, state: 'off', detail, note } : unstarted];
+                // A fault the hook says, it says after every write it is started for
+                // as well, so it is said wherever the line stands. A root outside
+                // any work tree, or in one that does not hold the project, it says
+                // nothing of, and where the line is waited on before no write there
+                // is none it leaves unchecked.
+                return [handed.silent !== true || waited ? { ...written, state: 'off', detail, note } : unstarted];
             }
             if (!waited)
                 return [unstarted];
@@ -613,11 +807,11 @@ export function reportHooks(sources, project, read, pattern = patternReader(), c
                 return [{ ...written, state: 'unknown', detail: null, note }];
             // What a release wrote: its hook, and nothing after it.
             if (sameStrings(hook.words, ['hook', 'claude']))
-                return [{ ...written, state: 'guards', detail: null, note }];
+                return [guards(null)];
             const root = handed.root === undefined ? '' : `, and its root, ${handed.root}, is a directory`;
             // Whose briefs a write is checked by, where they are not the project's own.
             const holder = handed.holder === undefined ? '' : ` in ${namedTree(handed.holder)}, which holds this project: the hook checks a write here by that work tree's briefs and its branch, as a file under ${handed.holder.path}/ there`;
-            return [{ ...written, state: 'guards', detail: `${where} is more than init writes, and guards: the hook reads the line${root}${holder}`, note }];
+            return [guards(`${where} is more than init writes, and guards: the hook reads the line${root}${holder}`)];
         });
     });
 }
@@ -812,6 +1006,18 @@ export function describeSkipped(plugin, part, present, elsewhere = []) {
     }
     return `${isOn(plugin)} and brings ${words.brings}, so ${words.skipped}: with both, ${words.twice}. To have ${words.them} here instead, for every clone of the repository, ${turnOff(plugin)} and run init again`;
 }
+/**
+ * How init comes to write the guard hooks. Where an array unloads the
+ * project's settings file, init writes none there and says the array, so
+ * the advice is the array's, and init after it: advice that led to more
+ * advice is the advice at the end.
+ */
+function runInit(wiring) {
+    const unloaded = wiring.unloaded ?? null;
+    if (unloaded === null)
+        return 'run spec-harness init --write';
+    return `${describeArrayMatcher(PROJECT_SETTINGS, unloaded)}, those init writes among them: ${ONE_STRING}, then run spec-harness init --write`;
+}
 /** Why the plugin settings turn on is not on this machine, or `null` where it is, may be, or none is on. */
 function absence(wiring) {
     return wiring.presence?.state === 'absent' ? wiring.presence.detail : null;
@@ -834,7 +1040,11 @@ export function wiringState(wiring) {
  * checks no write.
  */
 export function guardSwitchedOff(wiring) {
-    return wiring.hooksOff !== null && (wiring.hooks.length > 0 || (wiring.plugin !== null && absence(wiring) === null));
+    return wiring.hooksOff !== null && guardWired(wiring);
+}
+/** Whether something brings the guard hooks: a settings file that holds them, or a plugin settings turn on that may be on this machine. */
+export function guardWired(wiring) {
+    return wiring.hooks.length > 0 || (wiring.plugin !== null && absence(wiring) === null);
 }
 /**
  * What doctor and init say of `disableAllHooks` in `file`. `guarded` is
@@ -862,11 +1072,11 @@ export function describePresence(wiring) {
         return `whether ${plugin.id} is on this machine cannot be told: ${presence.detail}. A plugin that is not there brings no hook: Claude Code's /plugin lists it, and its errors`;
     if (wiring.hooks.length > 0)
         return `${isAbsent(plugin, presence.detail, 'no hook')}. With the plugin installed as well, ${PARTS.hooks.twice}: ${turnOff(plugin)}`;
-    return wiring.server ? unguarded(plugin, presence.detail) : null;
+    return wiring.server ? unguarded(plugin, presence.detail, wiring) : null;
 }
 /** That the plugin settings turn on is not on this machine and no hook of init's stands in for it, with the two ways to a guard. */
-function unguarded(plugin, detail) {
-    return `${isAbsent(plugin, detail, 'no hook')}, and Claude Code guards no write. To have the guard, ${bring(plugin)}, or ${turnOff(plugin)} and run spec-harness init --write`;
+function unguarded(plugin, detail, wiring) {
+    return `${isAbsent(plugin, detail, 'no hook')}, and Claude Code guards no write. To have the guard, ${bring(plugin)}, or ${turnOff(plugin)} and ${runInit(wiring)}`;
 }
 /** What `doctor` says of the wiring, and what to do when it is doubled or missing. */
 export function describeClaudeCode(wiring) {
@@ -875,12 +1085,12 @@ export function describeClaudeCode(wiring) {
     const own = `init's entries: ${entries}`;
     if (plugin === null) {
         if (entries === '')
-            return 'neither the spec-harness plugin nor the hooks init writes, so Claude Code guards no write: run spec-harness init --write, or install the plugin';
+            return `neither the spec-harness plugin nor the hooks init writes, so Claude Code guards no write: ${runInit(wiring)}, or install the plugin`;
         return own;
     }
     const absent = absence(wiring);
     if (absent !== null)
-        return entries === '' ? unguarded(plugin, absent) : own;
+        return entries === '' ? unguarded(plugin, absent, wiring) : own;
     if (entries === '')
         return `${isOn(plugin)} and brings the guard hooks and the server`;
     const twice = [...(wiring.hooks.length > 0 ? [PARTS.hooks.twice] : []), ...(wiring.server ? [PARTS.server.twice] : [])].join(' and ');
@@ -888,8 +1098,7 @@ export function describeClaudeCode(wiring) {
 }
 /** The spec-brief plugin this package ships, as spec-brief's `plugins` names it. */
 export const PLUGIN = '@descent-vtt/spec-harness/spec-brief-plugin';
-/** spec-brief's configuration files, in the order spec-brief looks for them in a directory. */
-export const SPEC_BRIEF_CONFIGS = ['.spec-brief.json', 'spec-brief.json'];
+export { SPEC_BRIEF_CONFIGS } from './config.js';
 /** The conditions an import meets in Node, its `defaultConditions`, and `default`, which every one meets. */
 const IMPORT_CONDITIONS = ['node', 'import', 'default'];
 /** A target Node refuses as invalid, which an array passes over and anything else stops at. */
@@ -999,9 +1208,13 @@ export function chooseBase(facts) {
     const unrecorded = 'no remote records a default branch (refs/remotes/origin/HEAD)';
     if (branch !== null) {
         const conventional = branch === 'main' || branch === 'master';
-        if (conventional || facts.branches.every((name) => name === branch)) {
+        if (conventional || facts.branches.every((local) => local.name === branch)) {
             const which = conventional ? 'the branch init runs on' : 'the only branch';
-            return { base: branch, detail: `rounds are measured from ${branch}, ${which}: ${unrecorded}; change "base" if rounds merge into another` };
+            // The base is a ref git and spec-brief read, so it is the name git
+            // reads as the branch and nothing else: `heads/main` beside a tag
+            // `main`. A branch with no commit yet is listed by no ref.
+            const base = facts.branches.find((local) => local.name === branch)?.ref ?? branch;
+            return { base, detail: `rounds are measured from ${base}, ${which}: ${unrecorded}; change "base" if rounds merge into another` };
         }
     }
     const where = branch === null ? 'HEAD is detached' : `${branch} is not main, master or the only branch`;
@@ -1083,20 +1296,30 @@ export const PROTECT_RULE_FILES = "Have the forge protect this file, the ADRs, t
 export const GIT_HOOK_LINE = `node ${BIN} hook git`;
 /**
  * The hook init writes. It is a POSIX sh script on every platform, since Git
- * for Windows runs a hook with the sh it ships. Where the project's install
- * is not in the work tree - a linked worktree nobody installed into, a
+ * for Windows runs a hook with the sh it ships. git starts it at the top of
+ * the work tree it commits in, so the project's install is read from there,
+ * and where a linked worktree has none, from the repository's main work
+ * tree: the work tree whose `.git` the common directory is, where `git
+ * worktree add` was run and the project installed (ADR-0005). Where neither
+ * has the install - a worktree of a repository nobody installed into, a
  * repository that shares its hooks with one that uses the harness - node
- * would end on a stack trace, so the hook says what is missing and where, and
- * the commit waits, as it did when npx found nothing to run.
+ * would end on a stack trace, so the hook says what is missing and where,
+ * and the commit waits, as it did when npx found nothing to run.
  */
 export const PRE_COMMIT = `#!/bin/sh
 # spec-harness: refuse a commit that changes what the active brief protects.
 # git runs this at the top of the work tree it commits in, a linked worktree's
-# own, wherever the hook is kept: the project's install is read from there.
+# own, wherever the hook is kept: the project's install is read from there,
+# or, where a linked worktree has none, from the repository's main work tree.
 bin=${BIN}
 if [ ! -f "$bin" ]; then
-  printf '%s\\n' "spec-harness: $bin is not in $PWD, the work tree git commits in: install the project's dependencies there, as with npm ci, and commit again" >&2
-  exit 2
+  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+  if [ "\${common##*/}" = .git ] && [ -f "\${common%/.git}/$bin" ]; then
+    bin=\${common%/.git}/$bin
+  else
+    printf '%s\\n' "spec-harness: $bin is not in $PWD, the work tree git commits in, nor in its repository's main work tree: install the project's dependencies there, as with npm ci, and commit again" >&2
+    exit 2
+  fi
 fi
 exec node "$bin" hook git
 `;
@@ -1127,6 +1350,10 @@ export function describeGitHook(hook) {
             return `${hook.file} is ${hook.what}, not a hook, and git stops every commit at it, since it cannot run it ("cannot spawn" on Windows, "cannot exec" elsewhere): nothing is checked there, and nothing is committed. Take it away, then run spec-harness init --git-hook --write`;
         case 'ignored':
             return `${hook.file} is ${hook.what}, not a hook, and is not executable, so git skips it and runs no hook: take it away, then run spec-harness init --git-hook --write`;
+        case 'unreadable':
+            if (!hook.runs)
+                return `${hook.file} cannot be read (${hook.reason}), and is not executable, so git skips it and runs no hook: make it readable and executable, or take it away and run spec-harness init --git-hook --write`;
+            return `${hook.file} cannot be read (${hook.reason}), so whether it runs spec-harness cannot be told: git runs it at a commit, and a script there that cannot be read stops every commit, where a program runs; make it readable`;
         case 'absent':
             return missingGitHook(hook.file);
         case 'unknown':