@descent-vtt/spec-harness 0.18.0 → 0.20.0

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `.spec-harness.json` may say, the defaults, and validation.\n *\n * Every key has a default, so a repository without the file works; a file\n * that says something this version does not understand stops the run with\n * exit 2, because a guard that silently ignored a misspelt key would be\n * guarding something other than what its owner wrote.\n */\n\nimport { templateError } from './branch.js';\n\nexport type OutOfScope = 'warn' | 'ask' | 'deny';\n\nexport interface HarnessConfig {\n  /** Branch-name templates that carry the active brief's id (ADR-0004). */\n  readonly branches: readonly string[];\n  /** What a write outside the brief's `affectedFiles` gets: a warning, a question to the person, or a refusal. */\n  readonly outOfScope: OutOfScope;\n  /** The branch rounds merge into, which audits and rulings are measured against. `null`: the remote's default branch. */\n  readonly base: string | null;\n  readonly rulings: {\n    /** The brief section whose table holds the rulings. */\n    readonly section: string;\n    /** The allowed-signers file, read from the base branch, never from the round's own tree. */\n    readonly allowedSigners: string;\n  };\n  readonly dependencies: {\n    /** Manifest file names whose added dependencies an audit reports. */\n    readonly manifests: readonly string[];\n  };\n  readonly context: {\n    /** The most a context packet may hold, in characters. Cited documents fill what the rest leaves; those that do not fit are named by path. */\n    readonly budget: number;\n  };\n  readonly assertions: {\n    /**\n     * Brief sections whose assertions state what was true before the round -\n     * the defect, measured - and are expected to stop holding when it ends.\n     * Every other assertion in a brief is a goal.\n     */\n    readonly premises: readonly string[];\n  };\n  readonly probes: {\n    /** How many times a probe runs; every run must agree. */\n    readonly runs: number;\n    /** Seconds one run may take. */\n    readonly timeout: number;\n  };\n  /** The command for each sibling tool, or `null` to find it (ADR-0002). */\n  readonly tools: Readonly<Record<SiblingName, readonly string[] | null>>;\n}\n\nexport type SiblingName = 'spec-brief' | 'spec-graph' | 'spec-guard';\nexport const SIBLINGS: readonly SiblingName[] = ['spec-brief', 'spec-graph', 'spec-guard'];\n\nexport const CONFIG_FILE = '.spec-harness.json';\n\nexport const DEFAULT_MANIFESTS: readonly string[] = [\n  'package.json',\n  'Cargo.toml',\n  'go.mod',\n  'pyproject.toml',\n  'requirements*.txt',\n  'Directory.Packages.props',\n  '*.csproj',\n  '*.fsproj',\n  '*.vbproj',\n  'Gemfile',\n];\n\nexport const DEFAULT_CONFIG: HarnessConfig = {\n  branches: ['brief/{id}', 'brief-{id}', '*/brief/{id}', '*/brief-{id}'],\n  outOfScope: 'warn',\n  base: null,\n  rulings: { section: 'Rulings', allowedSigners: '.github/allowed_signers' },\n  dependencies: { manifests: DEFAULT_MANIFESTS },\n  context: { budget: 60_000 },\n  assertions: { premises: ['The Defect, Measured', 'Premises', 'Preconditions'] },\n  probes: { runs: 2, timeout: 600 },\n  tools: { 'spec-brief': null, 'spec-graph': null, 'spec-guard': null },\n};\n\nexport class ConfigError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ConfigError';\n  }\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isStringList(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === 'string');\n}\n\nfunction checkKeys(value: Json, allowed: readonly string[], where: string): void {\n  for (const key of Object.keys(value)) {\n    if (!allowed.includes(key)) {\n      throw new ConfigError(`${where}: unknown key \"${key}\"; the keys are ${allowed.join(', ')}`);\n    }\n  }\n}\n\nfunction positive(value: unknown, where: string): number {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {\n    throw new ConfigError(`${where} must be a whole number of at least 1`);\n  }\n  return value;\n}\n\nfunction nonEmpty(value: unknown, where: string): string {\n  if (typeof value !== 'string' || value.trim() === '') throw new ConfigError(`${where} must be a non-empty string`);\n  return value;\n}\n\n/** Validates a parsed configuration and fills in every default. */\nexport function parseConfig(raw: unknown, file = CONFIG_FILE): HarnessConfig {\n  if (!isObject(raw)) throw new ConfigError(`${file} must hold a JSON object`);\n  checkKeys(raw, ['$schema', 'branches', 'outOfScope', 'base', 'rulings', 'dependencies', 'context', 'assertions', 'probes', 'tools'], file);\n\n  let branches = DEFAULT_CONFIG.branches;\n  if (raw['branches'] !== undefined) {\n    if (!isStringList(raw['branches']) || raw['branches'].length === 0) {\n      throw new ConfigError(`${file}: \"branches\" must be a non-empty list of templates`);\n    }\n    for (const template of raw['branches']) {\n      const error = templateError(template);\n      if (error !== null) throw new ConfigError(`${file}: \"branches\": ${error}`);\n    }\n    branches = raw['branches'];\n  }\n\n  let outOfScope = DEFAULT_CONFIG.outOfScope;\n  if (raw['outOfScope'] !== undefined) {\n    if (raw['outOfScope'] !== 'warn' && raw['outOfScope'] !== 'ask' && raw['outOfScope'] !== 'deny') {\n      throw new ConfigError(`${file}: \"outOfScope\" must be \"warn\", \"ask\" or \"deny\"`);\n    }\n    outOfScope = raw['outOfScope'];\n  }\n\n  let base = DEFAULT_CONFIG.base;\n  if (raw['base'] !== undefined && raw['base'] !== null) base = nonEmpty(raw['base'], `${file}: \"base\"`);\n\n  let rulings = DEFAULT_CONFIG.rulings;\n  if (raw['rulings'] !== undefined) {\n    const value = raw['rulings'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"rulings\" must be an object`);\n    checkKeys(value, ['section', 'allowedSigners'], `${file}: \"rulings\"`);\n    rulings = {\n      section: value['section'] === undefined ? rulings.section : nonEmpty(value['section'], `${file}: \"rulings.section\"`),\n      allowedSigners:\n        value['allowedSigners'] === undefined\n          ? rulings.allowedSigners\n          : nonEmpty(value['allowedSigners'], `${file}: \"rulings.allowedSigners\"`),\n    };\n  }\n\n  let dependencies = DEFAULT_CONFIG.dependencies;\n  if (raw['dependencies'] !== undefined) {\n    const value = raw['dependencies'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"dependencies\" must be an object`);\n    checkKeys(value, ['manifests'], `${file}: \"dependencies\"`);\n    if (value['manifests'] !== undefined) {\n      if (!isStringList(value['manifests'])) throw new ConfigError(`${file}: \"dependencies.manifests\" must be a list of file names`);\n      dependencies = { manifests: value['manifests'] };\n    }\n  }\n\n  let context = DEFAULT_CONFIG.context;\n  if (raw['context'] !== undefined) {\n    const value = raw['context'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"context\" must be an object`);\n    checkKeys(value, ['budget'], `${file}: \"context\"`);\n    if (value['budget'] !== undefined) context = { budget: positive(value['budget'], `${file}: \"context.budget\"`) };\n  }\n\n  let assertions = DEFAULT_CONFIG.assertions;\n  if (raw['assertions'] !== undefined) {\n    const value = raw['assertions'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"assertions\" must be an object`);\n    checkKeys(value, ['premises'], `${file}: \"assertions\"`);\n    if (value['premises'] !== undefined) {\n      if (!isStringList(value['premises'])) throw new ConfigError(`${file}: \"assertions.premises\" must be a list of section names`);\n      assertions = { premises: value['premises'] };\n    }\n  }\n\n  let probes = DEFAULT_CONFIG.probes;\n  if (raw['probes'] !== undefined) {\n    const value = raw['probes'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"probes\" must be an object`);\n    checkKeys(value, ['runs', 'timeout'], `${file}: \"probes\"`);\n    probes = {\n      runs: value['runs'] === undefined ? probes.runs : positive(value['runs'], `${file}: \"probes.runs\"`),\n      timeout: value['timeout'] === undefined ? probes.timeout : positive(value['timeout'], `${file}: \"probes.timeout\"`),\n    };\n  }\n\n  const tools: Record<SiblingName, readonly string[] | null> = { ...DEFAULT_CONFIG.tools };\n  if (raw['tools'] !== undefined) {\n    const value = raw['tools'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"tools\" must be an object`);\n    checkKeys(value, SIBLINGS, `${file}: \"tools\"`);\n    for (const name of SIBLINGS) {\n      const command = value[name];\n      if (command === undefined || command === null) continue;\n      // A list that is not empty has a first entry: the `?.` is the\n      // compiler's, and the mutant without it is equivalent.\n      if (!isStringList(command) || command.length === 0 || command[0]?.trim() === '') {\n        // A sibling runs without a shell, so the example is node and the\n        // script: npx is a shim Windows cannot start without one.\n        throw new ConfigError(`${file}: \"tools.${name}\" must be a command as a list, such as [\"node\", \"node_modules/@descent-vtt/${name}/bin/${name}.js\"], or null`);\n      }\n      tools[name] = command;\n    }\n  }\n\n  return { branches, outOfScope, base, rulings, dependencies, context, assertions, probes, tools };\n}\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `.spec-harness.json` may say, the defaults, and validation.\n *\n * Every key has a default, so a repository without the file works; a file\n * that says something this version does not understand stops the run with\n * exit 2, because a guard that silently ignored a misspelt key would be\n * guarding something other than what its owner wrote.\n */\n\nimport { templateError } from './branch.js';\n\nexport type OutOfScope = 'warn' | 'ask' | 'deny';\n\nexport interface HarnessConfig {\n  /** Branch-name templates that carry the active brief's id (ADR-0004). */\n  readonly branches: readonly string[];\n  /** What a write outside the brief's `affectedFiles` gets: a warning, a question to the person, or a refusal. */\n  readonly outOfScope: OutOfScope;\n  /** The branch rounds merge into, which audits and rulings are measured against. `null`: the remote's default branch. */\n  readonly base: string | null;\n  readonly rulings: {\n    /** The brief section whose table holds the rulings. */\n    readonly section: string;\n    /** The allowed-signers file, read from the base branch, never from the round's own tree. */\n    readonly allowedSigners: string;\n  };\n  readonly dependencies: {\n    /** Manifest file names whose added dependencies an audit reports. */\n    readonly manifests: readonly string[];\n  };\n  readonly context: {\n    /** The most a context packet may hold, in characters. Cited documents fill what the rest leaves; those that do not fit are named by path. */\n    readonly budget: number;\n  };\n  readonly assertions: {\n    /**\n     * Brief sections whose assertions state what was true before the round -\n     * the defect, measured - and are expected to stop holding when it ends.\n     * Every other assertion in a brief is a goal.\n     */\n    readonly premises: readonly string[];\n  };\n  readonly probes: {\n    /** How many times a probe runs; every run must agree. */\n    readonly runs: number;\n    /** Seconds one run may take. */\n    readonly timeout: number;\n  };\n  /** The command for each sibling tool, or `null` to find it (ADR-0002). */\n  readonly tools: Readonly<Record<SiblingName, readonly string[] | null>>;\n  /**\n   * Whether Claude Code's hook reports, at the end of each turn, the changed\n   * paths the brief protects or that are outside its scope; off by default,\n   * and `init` writes the entry that runs it only where it is on (ADR-0005).\n   */\n  readonly turnReport: boolean;\n}\n\nexport type SiblingName = 'spec-brief' | 'spec-graph' | 'spec-guard';\nexport const SIBLINGS: readonly SiblingName[] = ['spec-brief', 'spec-graph', 'spec-guard'];\n\nexport const CONFIG_FILE = '.spec-harness.json';\n\n/** spec-brief's configuration files, in the order spec-brief looks for them in a directory. */\nexport const SPEC_BRIEF_CONFIGS: readonly string[] = ['.spec-brief.json', 'spec-brief.json'];\n\nexport const DEFAULT_MANIFESTS: readonly string[] = [\n  'package.json',\n  'Cargo.toml',\n  'go.mod',\n  'pyproject.toml',\n  'requirements*.txt',\n  'Directory.Packages.props',\n  '*.csproj',\n  '*.fsproj',\n  '*.vbproj',\n  'Gemfile',\n];\n\nexport const DEFAULT_CONFIG: HarnessConfig = {\n  branches: ['brief/{id}', 'brief-{id}', '*/brief/{id}', '*/brief-{id}'],\n  outOfScope: 'warn',\n  base: null,\n  rulings: { section: 'Rulings', allowedSigners: '.github/allowed_signers' },\n  dependencies: { manifests: DEFAULT_MANIFESTS },\n  context: { budget: 60_000 },\n  assertions: { premises: ['The Defect, Measured', 'Premises', 'Preconditions'] },\n  probes: { runs: 2, timeout: 600 },\n  tools: { 'spec-brief': null, 'spec-graph': null, 'spec-guard': null },\n  turnReport: false,\n};\n\nexport class ConfigError extends Error {\n  /**\n   * The configuration file that did not load, where one stands at its path:\n   * the one file a write may still reach while it does not (ADR-0005).\n   * `null` for a configuration that was not read from a file.\n   */\n  readonly file: string | null;\n\n  constructor(message: string, file: string | null = null) {\n    super(message);\n    this.name = 'ConfigError';\n    this.file = file;\n  }\n}\n\ntype Json = Record<string, unknown>;\n\nfunction isObject(value: unknown): value is Json {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isStringList(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === 'string');\n}\n\nfunction checkKeys(value: Json, allowed: readonly string[], where: string): void {\n  for (const key of Object.keys(value)) {\n    if (!allowed.includes(key)) {\n      throw new ConfigError(`${where}: unknown key \"${key}\"; the keys are ${allowed.join(', ')}`);\n    }\n  }\n}\n\nfunction positive(value: unknown, where: string): number {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {\n    throw new ConfigError(`${where} must be a whole number of at least 1`);\n  }\n  return value;\n}\n\nfunction nonEmpty(value: unknown, where: string): string {\n  if (typeof value !== 'string' || value.trim() === '') throw new ConfigError(`${where} must be a non-empty string`);\n  return value;\n}\n\n/** Validates a parsed configuration and fills in every default. */\nexport function parseConfig(raw: unknown, file = CONFIG_FILE): HarnessConfig {\n  if (!isObject(raw)) throw new ConfigError(`${file} must hold a JSON object`);\n  checkKeys(raw, ['$schema', 'branches', 'outOfScope', 'base', 'rulings', 'dependencies', 'context', 'assertions', 'probes', 'tools', 'turnReport'], file);\n\n  let branches = DEFAULT_CONFIG.branches;\n  if (raw['branches'] !== undefined) {\n    if (!isStringList(raw['branches']) || raw['branches'].length === 0) {\n      throw new ConfigError(`${file}: \"branches\" must be a non-empty list of templates`);\n    }\n    for (const template of raw['branches']) {\n      const error = templateError(template);\n      if (error !== null) throw new ConfigError(`${file}: \"branches\": ${error}`);\n    }\n    branches = raw['branches'];\n  }\n\n  let outOfScope = DEFAULT_CONFIG.outOfScope;\n  if (raw['outOfScope'] !== undefined) {\n    if (raw['outOfScope'] !== 'warn' && raw['outOfScope'] !== 'ask' && raw['outOfScope'] !== 'deny') {\n      throw new ConfigError(`${file}: \"outOfScope\" must be \"warn\", \"ask\" or \"deny\"`);\n    }\n    outOfScope = raw['outOfScope'];\n  }\n\n  let base = DEFAULT_CONFIG.base;\n  if (raw['base'] !== undefined && raw['base'] !== null) base = nonEmpty(raw['base'], `${file}: \"base\"`);\n\n  let rulings = DEFAULT_CONFIG.rulings;\n  if (raw['rulings'] !== undefined) {\n    const value = raw['rulings'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"rulings\" must be an object`);\n    checkKeys(value, ['section', 'allowedSigners'], `${file}: \"rulings\"`);\n    rulings = {\n      section: value['section'] === undefined ? rulings.section : nonEmpty(value['section'], `${file}: \"rulings.section\"`),\n      allowedSigners:\n        value['allowedSigners'] === undefined\n          ? rulings.allowedSigners\n          : nonEmpty(value['allowedSigners'], `${file}: \"rulings.allowedSigners\"`),\n    };\n  }\n\n  let dependencies = DEFAULT_CONFIG.dependencies;\n  if (raw['dependencies'] !== undefined) {\n    const value = raw['dependencies'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"dependencies\" must be an object`);\n    checkKeys(value, ['manifests'], `${file}: \"dependencies\"`);\n    if (value['manifests'] !== undefined) {\n      if (!isStringList(value['manifests'])) throw new ConfigError(`${file}: \"dependencies.manifests\" must be a list of file names`);\n      dependencies = { manifests: value['manifests'] };\n    }\n  }\n\n  let context = DEFAULT_CONFIG.context;\n  if (raw['context'] !== undefined) {\n    const value = raw['context'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"context\" must be an object`);\n    checkKeys(value, ['budget'], `${file}: \"context\"`);\n    if (value['budget'] !== undefined) context = { budget: positive(value['budget'], `${file}: \"context.budget\"`) };\n  }\n\n  let assertions = DEFAULT_CONFIG.assertions;\n  if (raw['assertions'] !== undefined) {\n    const value = raw['assertions'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"assertions\" must be an object`);\n    checkKeys(value, ['premises'], `${file}: \"assertions\"`);\n    if (value['premises'] !== undefined) {\n      if (!isStringList(value['premises'])) throw new ConfigError(`${file}: \"assertions.premises\" must be a list of section names`);\n      assertions = { premises: value['premises'] };\n    }\n  }\n\n  let probes = DEFAULT_CONFIG.probes;\n  if (raw['probes'] !== undefined) {\n    const value = raw['probes'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"probes\" must be an object`);\n    checkKeys(value, ['runs', 'timeout'], `${file}: \"probes\"`);\n    probes = {\n      runs: value['runs'] === undefined ? probes.runs : positive(value['runs'], `${file}: \"probes.runs\"`),\n      timeout: value['timeout'] === undefined ? probes.timeout : positive(value['timeout'], `${file}: \"probes.timeout\"`),\n    };\n  }\n\n  const tools: Record<SiblingName, readonly string[] | null> = { ...DEFAULT_CONFIG.tools };\n  if (raw['tools'] !== undefined) {\n    const value = raw['tools'];\n    if (!isObject(value)) throw new ConfigError(`${file}: \"tools\" must be an object`);\n    checkKeys(value, SIBLINGS, `${file}: \"tools\"`);\n    for (const name of SIBLINGS) {\n      const command = value[name];\n      if (command === undefined || command === null) continue;\n      // A list that is not empty has a first entry: the `?.` is the\n      // compiler's, and the mutant without it is equivalent.\n      if (!isStringList(command) || command.length === 0 || command[0]?.trim() === '') {\n        // A sibling runs without a shell, so the example is node and the\n        // script: npx is a shim Windows cannot start without one.\n        throw new ConfigError(`${file}: \"tools.${name}\" must be a command as a list, such as [\"node\", \"node_modules/@descent-vtt/${name}/bin/${name}.js\"], or null`);\n      }\n      tools[name] = command;\n    }\n  }\n\n  const turnReport = raw['turnReport'] ?? DEFAULT_CONFIG.turnReport;\n  if (typeof turnReport !== 'boolean') throw new ConfigError(`${file}: \"turnReport\" must be true or false`);\n\n  return { branches, outOfScope, base, rulings, dependencies, context, assertions, probes, tools, turnReport };\n}\n"]}

package/dist/configure.d.ts

@@ -8,6 +8,7 @@
  * nothing to add.
  */
 import type { AllowedSigner } from './signers.js';
+import type { LocalBranch } from './types.js';
 import { type HookLine } from './usage.js';
 import { type ClaudeCodeCheck } from './versions.js';
 type Json = Record<string, unknown>;
@@ -24,6 +25,16 @@ export declare const PROJECT_DIR_OR_HERE = "${CLAUDE_PROJECT_DIR:-.}";
  * path is one argument whatever it holds, and no shell is involved.
  */
 export declare const GUARD_HOOK: Readonly<Json>;
+/**
+ * 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 declare const TURN_HOOK: Readonly<Json>;
 /**
  * The release of Claude Code from which a comma in a matcher separates
  * names as a `|` does. Its page on debugging a configuration (Check hooks,
@@ -34,25 +45,34 @@ export declare const GUARD_HOOK: Readonly<Json>;
  */
 export declare const COMMA_SINCE = "2.1.191";
 /**
- * How the Claude Code that runs the hooks reads a comma in a matcher of
- * names: as a separator, from {@link COMMA_SINCE} on; as part of a pattern,
- * in the release named, which is older; or it cannot be told, where the
- * release cannot.
+ * 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 declare const HYPHEN_SINCE = "2.1.195";
+/**
+ * How the Claude Code that runs the hooks reads a matcher of names: as every
+ * release from {@link HYPHEN_SINCE} on, and the hooks reference today; as
+ * the release named, which is older; or it cannot be told, where the release
+ * cannot.
  */
-export type Commas = {
-    readonly as: 'separator';
+export type Matching = {
+    readonly as: 'today';
 } | {
-    readonly as: 'pattern';
+    readonly as: 'older';
     readonly release: string;
 } | {
     readonly as: 'untold';
 };
 /**
- * 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.
+ * 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 declare function commasUnder(release: ClaudeCodeCheck | null): Commas;
+export declare function matchingUnder(release: ClaudeCodeCheck | null): Matching;
 /** What reads a matcher that is a pattern: the writing tools it matches, or `null` where that cannot be told. */
 export type PatternReader = (source: string) => readonly string[] | null;
 /**
@@ -86,12 +106,68 @@ export declare function patternReader(read?: PatternReader): PatternReader;
  *
  * `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 declare function mergeClaudeSettings(current: Json, isHook?: (words: readonly string[]) => boolean, pattern?: PatternReader, commas?: Commas): Json | null;
+export declare function mergeClaudeSettings(current: Json, isHook?: (words: readonly string[]) => boolean, pattern?: PatternReader, matching?: Matching): Json | 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 declare function withSessionStart(settings: Json, isHook: (words: readonly string[]) => boolean): Json | null;
+/**
+ * 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 declare function withOnFailure(settings: Json): Json | 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 declare function startsSessions(settings: unknown, isHook: (words: readonly string[]) => boolean): boolean;
+/**
+ * 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 declare function withTurnReport(settings: Json, isHook: (words: readonly string[]) => boolean): Json | null;
+/** 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 declare function reportsTurns(settings: unknown, isHook: (words: readonly string[]) => boolean): boolean;
+/**
+ * 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 declare 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 declare function describeInstalls(main: string, there: string | null, here: string | null): string | null;
 /** The server's entry, reading the project at `projectDir`: {@link PROJECT_DIR} for the plugin, {@link PROJECT_DIR_OR_HERE} for a project. */
 export declare function mcpServer(projectDir: string): Json;
 /**
@@ -166,6 +242,14 @@ export interface HookReport {
     /** What `onFailure` changes, where the entry sets it to `"block"`. */
     readonly note: string | null;
 }
+/**
+ * The release of Claude Code that reads `onFailure` on a hook's entry, by its
+ * 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 declare 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 declare function readsOnFailure(release: ClaudeCodeCheck | null): boolean;
 /** An array that stands for a matcher where it unloads a settings file's hooks: the event it stands under, and the array as written. */
 export interface ArrayMatcher {
     readonly event: string;
@@ -210,17 +294,17 @@ export declare function handedLines(sources: readonly ClaudeSettings[], 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 declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader, commas?: Commas): HookReport[];
+export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader, matching?: Matching, onFailureHere?: boolean): HookReport[];
 /** Whether a project's `.mcp.json` registers a server under the harness's name, however it runs it. */
 export declare function registersServer(mcp: unknown): boolean;
 /** A Claude Code settings file, named as a person finds it, and what reading it gave: an object, or nothing usable. */
@@ -345,17 +429,26 @@ export interface ClaudeCodeWiring {
     readonly lines: readonly HookReport[];
     /** Whether `.mcp.json` registers the server. */
     readonly server: boolean;
+    /** Whether a settings file has Claude Code start the hook as a session starts (startsSessions). */
+    readonly sessionStart: boolean;
     /**
      * The release of the Claude Code on `PATH`, where it was asked: a matcher
      * that lists names with a comma is read as that release reads it
-     * ({@link commasUnder}). `null` where it was not asked.
+     * ({@link matchingUnder}). `null` where it was not asked.
      */
     readonly release: ClaudeCodeCheck | null;
+    /**
+     * An array for a matcher that keeps Claude Code from loading the hooks of
+     * the project's settings file, the file init writes its hooks into, or
+     * `null`: init writes none there while it stands ({@link arrayMatcher}).
+     */
+    readonly unloaded: ArrayMatcher | null;
 }
 export type WiringState = 'plugin' | 'init' | 'both' | 'none';
-/** The wiring as its descriptions read it: what a caller knows of the plugin's presence, which one that does not ask leaves out. */
+/** The wiring as its descriptions read it: what a caller knows of the plugin's presence, and of an array in the project's settings, which one that does not ask leaves out. */
 type Wired = Pick<ClaudeCodeWiring, 'plugin' | 'hooks' | 'server'> & {
     readonly presence?: PluginPresence | null;
+    readonly unloaded?: ArrayMatcher | null;
 };
 /**
  * Which of the four the wiring is. `both` is a double install, and doctor
@@ -370,6 +463,8 @@ export declare function wiringState(wiring: Wired): WiringState;
  * checks no write.
  */
 export declare function guardSwitchedOff(wiring: Wired & Pick<ClaudeCodeWiring, 'hooksOff'>): boolean;
+/** 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 declare function guardWired(wiring: Wired): boolean;
 /**
  * What doctor and init say of `disableAllHooks` in `file`. `guarded` is
  * whether there are guard hooks for it to switch off; without any it is a
@@ -388,8 +483,7 @@ export declare function describePresence(wiring: Wired): string | null;
 export declare function describeClaudeCode(wiring: Wired): string;
 /** The spec-brief plugin this package ships, as spec-brief's `plugins` names it. */
 export declare 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 declare const SPEC_BRIEF_CONFIGS: readonly string[];
+export { SPEC_BRIEF_CONFIGS } from './config.js';
 /**
  * The file a package's `exports` target names for an import, as Node's
  * PACKAGE_TARGET_RESOLVE finds it, or `null` when it names none: a string
@@ -435,10 +529,10 @@ export declare function describePlugin(state: PluginState): string;
 export interface BaseFacts {
     /** The remote's default branch as a local ref, such as `origin/main`, or `null`. */
     readonly remoteDefault: string | null;
-    /** The branch checked out, or `null` on a detached head. */
+    /** The name of the branch checked out, or `null` on a detached head. */
     readonly branch: string | null;
-    /** Every local branch. */
-    readonly branches: readonly string[];
+    /** Every local branch, by its name and the ref a base names it by. */
+    readonly branches: readonly LocalBranch[];
 }
 /** The base `init` names, and why; `base` is `null` when none can be told. */
 export interface BaseChoice {
@@ -496,6 +590,19 @@ export type GitHookState = {
     readonly state: 'stops' | 'ignored';
     readonly file: string;
     readonly what: string;
+}
+/**
+ * A file the account may not read, `reason` being why, and `runs` whether
+ * git may execute it. One git may not execute it skips, with a hint, and
+ * commits. One it may it runs, and a script the shell cannot read either
+ * stops every commit there (measured with git 2.47 as an ordinary account),
+ * where a program runs without being read: which it is cannot be read.
+ */
+ | {
+    readonly state: 'unreadable';
+    readonly file: string;
+    readonly runs: boolean;
+    readonly reason: string;
 } | {
     readonly state: 'unknown';
     readonly reason: string;
@@ -522,13 +629,17 @@ export declare const PROTECT_RULE_FILES: string;
 export declare const GIT_HOOK_LINE = "node node_modules/@descent-vtt/spec-harness/bin/spec-harness.js 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 declare const PRE_COMMIT = "#!/bin/sh\n# spec-harness: refuse a commit that changes what the active brief protects.\n# git runs this at the top of the work tree it commits in, a linked worktree's\n# own, wherever the hook is kept: the project's install is read from there.\nbin=node_modules/@descent-vtt/spec-harness/bin/spec-harness.js\nif [ ! -f \"$bin\" ]; then\n  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\n  exit 2\nfi\nexec node \"$bin\" hook git\n";
+export declare const PRE_COMMIT = "#!/bin/sh\n# spec-harness: refuse a commit that changes what the active brief protects.\n# git runs this at the top of the work tree it commits in, a linked worktree's\n# own, wherever the hook is kept: the project's install is read from there,\n# or, where a linked worktree has none, from the repository's main work tree.\nbin=node_modules/@descent-vtt/spec-harness/bin/spec-harness.js\nif [ ! -f \"$bin\" ]; then\n  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)\n  if [ \"${common##*/}\" = .git ] && [ -f \"${common%/.git}/$bin\" ]; then\n    bin=${common%/.git}/$bin\n  else\n    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\n    exit 2\n  fi\nfi\nexec node \"$bin\" hook git\n";
 /**
  * What doctor and init add of a hook whose text runs the harness through
  * npx: the hook init wrote through 0.9.1, or the line it advised for a hook
@@ -553,4 +664,3 @@ export declare function graphReadsBriefs(config: Json, briefs: string): boolean;
 export declare function describeGraph(archiveGlob: string, briefs: string, reads: boolean, added: boolean): string;
 /** spec-graph's configuration with the archive read as history, or `null` when it already is. */
 export declare function mergeSpecGraph(current: Json, archiveGlob: string): Json | null;
-export {};