@descent-vtt/spec-harness 0.19.0 → 0.21.0

package/dist/config.d.ts

@@ -44,6 +44,12 @@ export interface HarnessConfig {
     };
     /** The command for each sibling tool, or `null` to find it (ADR-0002). */
     readonly tools: Readonly<Record<SiblingName, readonly string[] | null>>;
+    /**
+     * Whether Claude Code's hook reports, at the end of each turn, the changed
+     * paths the brief protects or that are outside its scope; off by default,
+     * and `init` writes the entry that runs it only where it is on (ADR-0005).
+     */
+    readonly turnReport: boolean;
 }
 export type SiblingName = 'spec-brief' | 'spec-graph' | 'spec-guard';
 export declare const SIBLINGS: readonly SiblingName[];
@@ -53,7 +59,13 @@ export declare const SPEC_BRIEF_CONFIGS: readonly string[];
 export declare const DEFAULT_MANIFESTS: readonly string[];
 export declare const DEFAULT_CONFIG: HarnessConfig;
 export declare class ConfigError extends Error {
-    constructor(message: string);
+    /**
+     * The configuration file that did not load, where one stands at its path:
+     * the one file a write may still reach while it does not (ADR-0005).
+     * `null` for a configuration that was not read from a file.
+     */
+    readonly file: string | null;
+    constructor(message: string, file?: string | null);
 }
 /** Validates a parsed configuration and fills in every default. */
 export declare function parseConfig(raw: unknown, file?: string): HarnessConfig;

package/dist/config.js

@@ -33,11 +33,19 @@ export const DEFAULT_CONFIG = {
     assertions: { premises: ['The Defect, Measured', 'Premises', 'Preconditions'] },
     probes: { runs: 2, timeout: 600 },
     tools: { 'spec-brief': null, 'spec-graph': null, 'spec-guard': null },
+    turnReport: false,
 };
 export class ConfigError extends Error {
-    constructor(message) {
+    /**
+     * The configuration file that did not load, where one stands at its path:
+     * the one file a write may still reach while it does not (ADR-0005).
+     * `null` for a configuration that was not read from a file.
+     */
+    file;
+    constructor(message, file = null) {
         super(message);
         this.name = 'ConfigError';
+        this.file = file;
     }
 }
 function isObject(value) {
@@ -68,7 +76,7 @@ function nonEmpty(value, where) {
 export function parseConfig(raw, file = CONFIG_FILE) {
     if (!isObject(raw))
         throw new ConfigError(`${file} must hold a JSON object`);
-    checkKeys(raw, ['$schema', 'branches', 'outOfScope', 'base', 'rulings', 'dependencies', 'context', 'assertions', 'probes', 'tools'], file);
+    checkKeys(raw, ['$schema', 'branches', 'outOfScope', 'base', 'rulings', 'dependencies', 'context', 'assertions', 'probes', 'tools', 'turnReport'], file);
     let branches = DEFAULT_CONFIG.branches;
     if (raw['branches'] !== undefined) {
         if (!isStringList(raw['branches']) || raw['branches'].length === 0) {
@@ -168,6 +176,9 @@ export function parseConfig(raw, file = CONFIG_FILE) {
             tools[name] = command;
         }
     }
-    return { branches, outOfScope, base, rulings, dependencies, context, assertions, probes, tools };
+    const turnReport = raw['turnReport'] ?? DEFAULT_CONFIG.turnReport;
+    if (typeof turnReport !== 'boolean')
+        throw new ConfigError(`${file}: "turnReport" must be true or false`);
+    return { branches, outOfScope, base, rulings, dependencies, context, assertions, probes, tools, turnReport };
 }
 //# sourceMappingURL=config.js.map

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\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};\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

@@ -25,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,
@@ -111,6 +121,19 @@ export declare function mergeClaudeSettings(current: Json, isHook?: (words: read
  * 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
@@ -118,12 +141,39 @@ export declare function withSessionStart(settings: Json, isHook: (words: readonl
  * 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 where `turnReport` is on and no settings file has Claude
+ * Code start the hook as a turn ends: the report the configuration asks for
+ * is made at no turn's end. The plugin brings no entry for it (ADR-0012).
+ */
+export declare const NO_TURN_END = "note: \"turnReport\" is on, and no settings file has Claude Code start the hook as a turn ends, so no turn's end is reported: spec-harness init --write adds the entry beside init's, and says where it goes where the plugin brings the guard hooks";
+/**
+ * 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;
 /**
@@ -149,6 +199,15 @@ export interface WrittenHook {
     readonly shell: boolean;
     /** Whether the entry sets `onFailure` to `"block"`. */
     readonly blocks: boolean;
+    /**
+     * The word that names the harness, its script's path or its name, as
+     * written, and whether a shell reads it first: an entry with no `args`.
+     * Entries that name the harness in two ways are two lines.
+     */
+    readonly launcher: {
+        readonly word: string;
+        readonly shell: boolean;
+    };
     /**
      * What the entry has for `type` where that is not `"command"`, as it is
      * said of the line: none at all, or a word the reference does not list.
@@ -165,6 +224,15 @@ export interface WrittenHook {
  * alone.
  */
 export declare function writtenHooks(settings: unknown): WrittenHook[];
+/**
+ * Where doctor looks for the script a line runs: each directory
+ * `${CLAUDE_PROJECT_DIR}` can name as a session starts, which Claude Code
+ * fills in, in either form, and how a file is told to stand at a path.
+ */
+export interface ScriptPlaces {
+    readonly projects: readonly string[];
+    readonly isFile: (path: string) => boolean;
+}
 /** Whether Claude Code starts a line for a write, by the tools it is waited on for: one whose tools cannot be told is taken as started. */
 export declare function isStarted(tools: readonly string[] | null): boolean;
 /** What doctor reports of one line of Claude Code's hook. */
@@ -179,8 +247,11 @@ export interface HookReport {
      * checks it. `off`: the hook checks no write, for a line it cannot read, a
      * root that is no directory, or a root that is a directory outside any
      * work tree; or it is never started, in a file an array for a matcher
-     * keeps Claude Code from loading the hooks of. `held`: the hook holds every write, for a
-     * brief the line names that is not one. `unstarted`: Claude Code waits on
+     * keeps Claude Code from loading the hooks of, or it cannot start, its
+     * script not there. `held`: the hook holds every write, for a brief the
+     * line names that is not one or that spec-brief cannot be asked about;
+     * or Claude Code does, for a hook that cannot start under `onFailure:
+     * "block"`. `unstarted`: Claude Code waits on
      * the line before no write, so it is not the guard. `unknown`: what the
      * hook is handed, which writes it is started for, or whether Claude Code
      * runs the entry at all, cannot be told here.
@@ -197,7 +268,17 @@ export interface HookReport {
     readonly cover: string | null;
     /** What `onFailure` changes, where the entry sets it to `"block"`. */
     readonly note: string | null;
+    /** What is said of an entry whose `timeout` is below what a run of the hook is given, or `null`. */
+    readonly timeout: 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;
@@ -251,8 +332,14 @@ export declare function handedLines(sources: readonly ClaudeSettings[], project:
  * `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.
+ *
+ * `scripts` is where a caller that says whether the script a line runs is
+ * there looks for it; with none it is not asked. A line whose script is
+ * not there is a hook Claude Code cannot start, which it lets each write
+ * go ahead without, or holds every write for where the entry sets
+ * `onFailure` to `"block"` and the release here reads it.
  */
-export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader, matching?: Matching): HookReport[];
+export declare function reportHooks(sources: readonly ClaudeSettings[], project: string, read: (words: readonly string[]) => HookLine | null, pattern?: PatternReader, matching?: Matching, onFailureHere?: boolean, scripts?: ScriptPlaces | null): 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. */
@@ -379,6 +466,8 @@ export interface ClaudeCodeWiring {
     readonly server: boolean;
     /** Whether a settings file has Claude Code start the hook as a session starts (startsSessions). */
     readonly sessionStart: boolean;
+    /** Whether a settings file has Claude Code start the hook as a turn ends (reportsTurns): the plugin brings no such entry. */
+    readonly turnEnd: 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
@@ -411,6 +500,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