@descent-vtt/spec-harness 0.0.0 → 0.1.1

package/dist/briefs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The briefs, as spec-brief reports them, and which one a round is working on.
+ *
+ * spec-brief owns the brief format and its configuration (its ADR-0003), so
+ * the harness reads briefs the way spec-brief does by asking it:
+ * `spec-brief list --archived --format json`. This module reads that
+ * document and nothing else; a shape it does not recognise is an error, never
+ * a best-effort reading of half the fields (ADR-0002).
+ */
+import type { BriefRow } from './types.js';
+/**
+ * The spec-brief JSON document versions this harness reads. Version 1 is the
+ * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the
+ * harness never reads, so the `list` and `archive` documents are the same.
+ */
+export declare const SUPPORTED_SCHEMA_VERSIONS: readonly number[];
+export declare class SiblingOutputError extends Error {
+    constructor(message: string);
+}
+/** Reads the document `spec-brief list --format json` prints. */
+export declare function parseBriefList(document: unknown): BriefRow[];
+/** How the active brief was named, for messages. */
+export type ActiveSource = 'flag' | 'environment' | 'branch';
+export type ActiveBrief = {
+    readonly kind: 'found';
+    readonly brief: BriefRow;
+    readonly source: ActiveSource;
+} | {
+    readonly kind: 'none';
+    readonly reason: string;
+} | {
+    readonly kind: 'unknown';
+    readonly id: string;
+    readonly source: ActiveSource;
+} | {
+    readonly kind: 'archived';
+    readonly brief: BriefRow;
+    readonly source: ActiveSource;
+};
+/**
+ * The brief a round is working on: named by a flag, by `SPEC_BRIEF`, or by
+ * the branch - never guessed from which brief happens to be the only active
+ * one (ADR-0004).
+ */
+export declare function findActive(briefs: readonly BriefRow[], named: {
+    readonly flag?: string | undefined;
+    readonly environment?: string | undefined;
+    readonly branch?: string | null | undefined;
+}): ActiveBrief;

package/dist/briefs.js

@@ -0,0 +1,111 @@
+/**
+ * The briefs, as spec-brief reports them, and which one a round is working on.
+ *
+ * spec-brief owns the brief format and its configuration (its ADR-0003), so
+ * the harness reads briefs the way spec-brief does by asking it:
+ * `spec-brief list --archived --format json`. This module reads that
+ * document and nothing else; a shape it does not recognise is an error, never
+ * a best-effort reading of half the fields (ADR-0002).
+ */
+import { sameId } from './branch.js';
+/**
+ * The spec-brief JSON document versions this harness reads. Version 1 is the
+ * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the
+ * harness never reads, so the `list` and `archive` documents are the same.
+ */
+export const SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3];
+export class SiblingOutputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SiblingOutputError';
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function strings(value, where) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new SiblingOutputError(`${where} is not a list of strings`);
+    }
+    return value;
+}
+function nullableString(value, where) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        throw new SiblingOutputError(`${where} is not a string`);
+    return value;
+}
+/** Reads the document `spec-brief list --format json` prints. */
+export function parseBriefList(document) {
+    if (!isObject(document) || document['tool'] !== 'spec-brief' || document['command'] !== 'list') {
+        throw new SiblingOutputError('spec-brief did not print a list document');
+    }
+    const version = document['schemaVersion'];
+    if (typeof version !== 'number' || !SUPPORTED_SCHEMA_VERSIONS.includes(version)) {
+        throw new SiblingOutputError(`spec-brief printed schemaVersion ${String(version)}; this harness reads ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}`);
+    }
+    const briefs = document['briefs'];
+    if (!Array.isArray(briefs))
+        throw new SiblingOutputError('spec-brief list has no "briefs"');
+    return briefs.map((row, index) => {
+        const where = `briefs[${index}]`;
+        if (!isObject(row))
+            throw new SiblingOutputError(`${where} is not an object`);
+        const id = row['id'];
+        const file = row['file'];
+        if (typeof id !== 'string' || typeof file !== 'string')
+            throw new SiblingOutputError(`${where} has no id or file`);
+        const phase = row['phase'];
+        if (phase !== 'live' && phase !== 'archived')
+            throw new SiblingOutputError(`${where}.phase is "${String(phase)}"`);
+        const tasks = row['tasks'];
+        const wave = row['wave'];
+        return {
+            id,
+            file,
+            title: nullableString(row['title'], `${where}.title`),
+            phase,
+            status: nullableString(row['status'], `${where}.status`),
+            type: nullableString(row['type'], `${where}.type`),
+            wave: typeof wave === 'number' ? wave : null,
+            dependsOn: strings(row['dependsOn'] ?? [], `${where}.dependsOn`),
+            affectedFiles: strings(row['affectedFiles'] ?? [], `${where}.affectedFiles`),
+            protectedFiles: strings(row['protectedFiles'] ?? [], `${where}.protectedFiles`),
+            tasks: {
+                total: isObject(tasks) && typeof tasks['total'] === 'number' ? tasks['total'] : 0,
+                checked: isObject(tasks) && typeof tasks['checked'] === 'number' ? tasks['checked'] : 0,
+            },
+            ready: row['ready'] === true,
+            waitingOn: strings(row['waitingOn'] ?? [], `${where}.waitingOn`),
+        };
+    });
+}
+/**
+ * The brief a round is working on: named by a flag, by `SPEC_BRIEF`, or by
+ * the branch - never guessed from which brief happens to be the only active
+ * one (ADR-0004).
+ */
+export function findActive(briefs, named) {
+    const pick = (id, source) => {
+        const matches = briefs.filter((brief) => sameId(brief.id, id));
+        const live = matches.find((brief) => brief.phase === 'live');
+        if (live !== undefined)
+            return { kind: 'found', brief: live, source };
+        const archived = matches[0];
+        if (archived !== undefined)
+            return { kind: 'archived', brief: archived, source };
+        return { kind: 'unknown', id, source };
+    };
+    if (named.flag !== undefined && named.flag.trim() !== '')
+        return pick(named.flag.trim(), 'flag');
+    if (named.environment !== undefined && named.environment.trim() !== '')
+        return pick(named.environment.trim(), 'environment');
+    if (named.branch !== undefined && named.branch !== null)
+        return pick(named.branch, 'branch');
+    return {
+        kind: 'none',
+        reason: 'no brief is named: pass --brief <id>, set SPEC_BRIEF, or work on a branch named like brief/<id>-<topic>',
+    };
+}
+//# sourceMappingURL=briefs.js.map

package/dist/briefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefs.js","sourceRoot":"","sources":["../src/briefs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The briefs, as spec-brief reports them, and which one a round is working on.\n *\n * spec-brief owns the brief format and its configuration (its ADR-0003), so\n * the harness reads briefs the way spec-brief does by asking it:\n * `spec-brief list --archived --format json`. This module reads that\n * document and nothing else; a shape it does not recognise is an error, never\n * a best-effort reading of half the fields (ADR-0002).\n */\n\nimport { sameId } from './branch.js';\nimport type { BriefRow } from './types.js';\n\n/**\n * The spec-brief JSON document versions this harness reads. Version 1 is the\n * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the\n * harness never reads, so the `list` and `archive` documents are the same.\n */\nexport const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [1, 2, 3];\n\nexport class SiblingOutputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SiblingOutputError';\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 strings(value: unknown, where: string): string[] {\n  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {\n    throw new SiblingOutputError(`${where} is not a list of strings`);\n  }\n  return value;\n}\n\nfunction nullableString(value: unknown, where: string): string | null {\n  if (value === null || value === undefined) return null;\n  if (typeof value !== 'string') throw new SiblingOutputError(`${where} is not a string`);\n  return value;\n}\n\n/** Reads the document `spec-brief list --format json` prints. */\nexport function parseBriefList(document: unknown): BriefRow[] {\n  if (!isObject(document) || document['tool'] !== 'spec-brief' || document['command'] !== 'list') {\n    throw new SiblingOutputError('spec-brief did not print a list document');\n  }\n  const version = document['schemaVersion'];\n  if (typeof version !== 'number' || !SUPPORTED_SCHEMA_VERSIONS.includes(version)) {\n    throw new SiblingOutputError(\n      `spec-brief printed schemaVersion ${String(version)}; this harness reads ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}`,\n    );\n  }\n  const briefs = document['briefs'];\n  if (!Array.isArray(briefs)) throw new SiblingOutputError('spec-brief list has no \"briefs\"');\n  return briefs.map((row, index) => {\n    const where = `briefs[${index}]`;\n    if (!isObject(row)) throw new SiblingOutputError(`${where} is not an object`);\n    const id = row['id'];\n    const file = row['file'];\n    if (typeof id !== 'string' || typeof file !== 'string') throw new SiblingOutputError(`${where} has no id or file`);\n    const phase = row['phase'];\n    if (phase !== 'live' && phase !== 'archived') throw new SiblingOutputError(`${where}.phase is \"${String(phase)}\"`);\n    const tasks = row['tasks'];\n    const wave = row['wave'];\n    return {\n      id,\n      file,\n      title: nullableString(row['title'], `${where}.title`),\n      phase,\n      status: nullableString(row['status'], `${where}.status`),\n      type: nullableString(row['type'], `${where}.type`),\n      wave: typeof wave === 'number' ? wave : null,\n      dependsOn: strings(row['dependsOn'] ?? [], `${where}.dependsOn`),\n      affectedFiles: strings(row['affectedFiles'] ?? [], `${where}.affectedFiles`),\n      protectedFiles: strings(row['protectedFiles'] ?? [], `${where}.protectedFiles`),\n      tasks: {\n        total: isObject(tasks) && typeof tasks['total'] === 'number' ? tasks['total'] : 0,\n        checked: isObject(tasks) && typeof tasks['checked'] === 'number' ? tasks['checked'] : 0,\n      },\n      ready: row['ready'] === true,\n      waitingOn: strings(row['waitingOn'] ?? [], `${where}.waitingOn`),\n    };\n  });\n}\n\n/** How the active brief was named, for messages. */\nexport type ActiveSource = 'flag' | 'environment' | 'branch';\n\nexport type ActiveBrief =\n  | { readonly kind: 'found'; readonly brief: BriefRow; readonly source: ActiveSource }\n  | { readonly kind: 'none'; readonly reason: string }\n  | { readonly kind: 'unknown'; readonly id: string; readonly source: ActiveSource }\n  | { readonly kind: 'archived'; readonly brief: BriefRow; readonly source: ActiveSource };\n\n/**\n * The brief a round is working on: named by a flag, by `SPEC_BRIEF`, or by\n * the branch - never guessed from which brief happens to be the only active\n * one (ADR-0004).\n */\nexport function findActive(\n  briefs: readonly BriefRow[],\n  named: { readonly flag?: string | undefined; readonly environment?: string | undefined; readonly branch?: string | null | undefined },\n): ActiveBrief {\n  const pick = (id: string, source: ActiveSource): ActiveBrief => {\n    const matches = briefs.filter((brief) => sameId(brief.id, id));\n    const live = matches.find((brief) => brief.phase === 'live');\n    if (live !== undefined) return { kind: 'found', brief: live, source };\n    const archived = matches[0];\n    if (archived !== undefined) return { kind: 'archived', brief: archived, source };\n    return { kind: 'unknown', id, source };\n  };\n  if (named.flag !== undefined && named.flag.trim() !== '') return pick(named.flag.trim(), 'flag');\n  if (named.environment !== undefined && named.environment.trim() !== '') return pick(named.environment.trim(), 'environment');\n  if (named.branch !== undefined && named.branch !== null) return pick(named.branch, 'branch');\n  return {\n    kind: 'none',\n    reason: 'no brief is named: pass --brief <id>, set SPEC_BRIEF, or work on a branch named like brief/<id>-<topic>',\n  };\n}\n"]}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The command line: arguments, dispatch, output and exit codes.
+ *
+ * Exit 0: done, nothing refused. Exit 1: something refused or found. Exit 2:
+ * the answer cannot be trusted - a bad flag, a configuration that does not
+ * load, a sibling that is missing or printed something unreadable. A run that
+ * could not look must never exit as though it looked and found nothing
+ * (spec-core ADR-0005).
+ */
+import { type CliIO } from './workspace.js';
+export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version, type CliIO } from './workspace.js';
+export declare const HELP = "spec-harness - context, guards, audits and rulings for rounds of agent work\n\nUsage:\n  spec-harness <command> [options]\n\nCommands:\n  context [brief]     What an agent needs to start a round: the brief, its scope,\n                      rulings, dependencies, the rules in force, the cited documents.\n  guard <path...>     May the round write these paths? Exit 1 if one is refused.\n  hook claude         Answer a Claude Code PreToolUse or PostToolUse hook (stdin).\n  hook git            Answer git's pre-commit hook for the staged files.\n  escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>\n                      [--option \"<label>: <cost>\"]... [--recommend <text>].\n                      --list shows what waits; --show <id> prints one memo.\n  rule <id>           Record a person's ruling in the brief: --allow or --deny, with\n                      --note. It counts once committed signed.\n  rulings [brief]     The brief's rulings, and whether each one's signature verifies.\n  audit [brief]       Did the round stay inside the lines: what the archive would say,\n                      the brief's assertions, unverified rulings, new dependencies.\n  probe [brief]       Run the brief's probes: red at the base, green at the head.\n                      --at base|head|both, --id <probe>.\n  premises            Do the live briefs' premises still hold? For CI: exit 1 when one is stale.\n  init                Configure the spec-* tools to agree. Prints the plan; --write\n                      applies it; --git-hook adds a pre-commit hook.\n  mcp                 Serve start_round, check_path, request_escalation, audit_round,\n                      list_rounds and the workflow prompts over MCP on stdio.\n  doctor              Which siblings are installed, at which versions, and which\n                      brief is named. Exit 1 when one is older than this release needs.\n\nOptions:\n  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.\n  --base <ref>        What the round is measured from. Otherwise \"base\" in\n                      .spec-harness.json, then the remote's default branch.\n  --root <dir>        Run from another directory.\n  --format <fmt>      pretty or json.\n  --strict            Warnings fail the run.\n  --help, --version\n\nExit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.\n";
+export declare function run(argv: readonly string[], io: CliIO): Promise<number>;
+export declare function main(argv?: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,245 @@
+/**
+ * The command line: arguments, dispatch, output and exit codes.
+ *
+ * Exit 0: done, nothing refused. Exit 1: something refused or found. Exit 2:
+ * the answer cannot be trusted - a bad flag, a configuration that does not
+ * load, a sibling that is missing or printed something unreadable. A run that
+ * could not look must never exit as though it looked and found nothing
+ * (spec-core ADR-0005).
+ */
+import { auditCommand, contextCommand, escalateCommand, probeCommand, ruleCommand, rulingsCommand } from './commands.js';
+import { ConfigError, SIBLINGS } from './config.js';
+import { stagedChanges } from './git.js';
+import { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';
+import { premisesCommand } from './premises.js';
+import { createReader } from './reader.js';
+import { checkPaths } from './round.js';
+import { mcpCommand } from './server.js';
+import { initCommand } from './setup.js';
+import { SiblingError } from './siblings.js';
+import { MINIMUM_VERSIONS } from './versions.js';
+import { activeBrief, describeActive, EXIT_ERROR, EXIT_FAILED, EXIT_OK, json, namedId, openWorkspace, parseOptions, UsageError, version, } from './workspace.js';
+export { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version } from './workspace.js';
+export const HELP = `spec-harness - context, guards, audits and rulings for rounds of agent work
+
+Usage:
+  spec-harness <command> [options]
+
+Commands:
+  context [brief]     What an agent needs to start a round: the brief, its scope,
+                      rulings, dependencies, the rules in force, the cited documents.
+  guard <path...>     May the round write these paths? Exit 1 if one is refused.
+  hook claude         Answer a Claude Code PreToolUse or PostToolUse hook (stdin).
+  hook git            Answer git's pre-commit hook for the staged files.
+  escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>
+                      [--option "<label>: <cost>"]... [--recommend <text>].
+                      --list shows what waits; --show <id> prints one memo.
+  rule <id>           Record a person's ruling in the brief: --allow or --deny, with
+                      --note. It counts once committed signed.
+  rulings [brief]     The brief's rulings, and whether each one's signature verifies.
+  audit [brief]       Did the round stay inside the lines: what the archive would say,
+                      the brief's assertions, unverified rulings, new dependencies.
+  probe [brief]       Run the brief's probes: red at the base, green at the head.
+                      --at base|head|both, --id <probe>.
+  premises            Do the live briefs' premises still hold? For CI: exit 1 when one is stale.
+  init                Configure the spec-* tools to agree. Prints the plan; --write
+                      applies it; --git-hook adds a pre-commit hook.
+  mcp                 Serve start_round, check_path, request_escalation, audit_round,
+                      list_rounds and the workflow prompts over MCP on stdio.
+  doctor              Which siblings are installed, at which versions, and which
+                      brief is named. Exit 1 when one is older than this release needs.
+
+Options:
+  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.
+  --base <ref>        What the round is measured from. Otherwise "base" in
+                      .spec-harness.json, then the remote's default branch.
+  --root <dir>        Run from another directory.
+  --format <fmt>      pretty or json.
+  --strict            Warnings fail the run.
+  --help, --version
+
+Exit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.
+`;
+/* ------------------------------------------------------------------- guard */
+const reader = createReader();
+async function decisionsFor(workspace, options, io, given, cwd) {
+    const active = await activeBrief(workspace, options, io.env);
+    const { brief, note, problem } = describeActive(active);
+    if (problem !== null)
+        return { decisions: [], problem };
+    const decisions = await checkPaths(workspace, brief, note, given, cwd, reader);
+    return { decisions, problem: null };
+}
+const SYMBOL = { allow: 'ok     ', warn: 'warning', ask: 'ask    ', deny: 'refused' };
+async function guardCommand(options, io) {
+    if (options.positionals.length === 0)
+        throw new UsageError('guard needs at least one path');
+    const workspace = await openWorkspace(options, io);
+    const { decisions, problem } = await decisionsFor(workspace, options, io, options.positionals, io.cwd);
+    if (problem !== null) {
+        io.stderr.write(`spec-harness: ${problem}\n`);
+        return EXIT_ERROR;
+    }
+    if (options.format === 'json') {
+        io.stdout.write(json('guard', { decisions }));
+    }
+    else {
+        for (const decision of decisions) {
+            io.stdout.write(`${SYMBOL[decision.verdict]}  ${decision.message}\n`);
+            if (decision.verdict !== 'allow')
+                io.stdout.write(`         ${decision.hint}\n`);
+        }
+    }
+    const refused = decisions.some((d) => d.verdict === 'deny' || d.verdict === 'ask');
+    const warned = decisions.some((d) => d.verdict === 'warn');
+    return refused || (options.strict && warned) ? EXIT_FAILED : EXIT_OK;
+}
+/* -------------------------------------------------------------------- hook */
+async function readStdin(io) {
+    if (io.stdin !== undefined)
+        return io.stdin();
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function hookCommand(options, io) {
+    const kind = options.positionals[0];
+    if (kind === 'claude') {
+        const request = parseClaudeHook(await readStdin(io));
+        if ('error' in request) {
+            // A hook that cannot read its question refuses nothing it cannot see,
+            // but says so where the person reads it: a non-blocking error.
+            io.stderr.write(`spec-harness: ${request.error}\n`);
+            return EXIT_FAILED;
+        }
+        if (request.paths.length === 0)
+            return EXIT_OK;
+        const cwd = request.cwd ?? io.cwd;
+        let workspace;
+        try {
+            workspace = await openWorkspace({ ...options, root: options.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);
+        }
+        catch (error) {
+            if (error instanceof UsageError)
+                return EXIT_OK;
+            throw error;
+        }
+        try {
+            const { decisions, problem } = await decisionsFor(workspace, options, io, request.paths, cwd);
+            if (problem !== null) {
+                // Exit 2 blocks the tool call, and its stderr reaches the model.
+                io.stderr.write(`spec-harness: ${problem}. Fix the brief or the branch before writing.\n`);
+                return EXIT_ERROR;
+            }
+            const response = claudeResponse(request.event, decisions);
+            io.stdout.write(response.stdout);
+            return response.exitCode;
+        }
+        catch (error) {
+            if (request.event !== 'PreToolUse')
+                throw error;
+            // A round is named and its briefs cannot be read: the guard cannot
+            // tell a protected file from any other, so the write waits.
+            io.stderr.write(`spec-harness: cannot check this write: ${error.message}\n`);
+            return EXIT_ERROR;
+        }
+    }
+    if (kind === 'git') {
+        const workspace = await openWorkspace(options, io);
+        const staged = await stagedChanges(workspace.root);
+        const paths = staged.flatMap((change) => (change.from === undefined ? [change.path] : [change.from, change.path]));
+        if (paths.length === 0)
+            return EXIT_OK;
+        const { decisions, problem } = await decisionsFor(workspace, options, io, paths, workspace.root);
+        if (problem !== null) {
+            io.stderr.write(`spec-harness: ${problem}\n`);
+            return EXIT_ERROR;
+        }
+        const response = gitResponse(decisions);
+        io.stderr.write(response.text);
+        return response.exitCode;
+    }
+    throw new UsageError('hook takes "claude" or "git"');
+}
+/* ------------------------------------------------------------------ doctor */
+async function doctorCommand(options, io) {
+    const workspace = await openWorkspace(options, io);
+    const rows = SIBLINGS.map((name) => {
+        const sibling = workspace.siblings.locate(name);
+        const row = { tool: name, state: sibling.kind, minimum: MINIMUM_VERSIONS[name] };
+        if (sibling.kind === 'absent')
+            return { ...row, version: null, detail: sibling.reason };
+        if (sibling.kind === 'outdated')
+            return { ...row, version: sibling.version, detail: sibling.reason };
+        const command = sibling.command.join(' ');
+        const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version})`;
+        return { ...row, version: sibling.version, detail };
+    });
+    const named = namedId(workspace, options, io.env);
+    if (options.format === 'json') {
+        io.stdout.write(json('doctor', { root: workspace.root, branch: workspace.branch, brief: named, siblings: rows }));
+    }
+    else {
+        io.stdout.write(`root    ${workspace.root}\nbranch  ${workspace.branch ?? '(detached)'}\nbrief   ${named ?? '(none named)'}\n\n`);
+        for (const row of rows)
+            io.stdout.write(`${row.state.padEnd(8)}  ${row.tool.padEnd(10)}  ${row.detail}\n`);
+    }
+    // An outdated sibling is a problem to fix, where a missing optional one is
+    // a choice; with none installed, the harness can check nothing.
+    const outdated = rows.some((row) => row.state === 'outdated');
+    const usable = rows.some((row) => row.state === 'found');
+    return outdated || !usable ? EXIT_FAILED : EXIT_OK;
+}
+/* ---------------------------------------------------------------- dispatch */
+const COMMANDS = {
+    guard: guardCommand,
+    hook: hookCommand,
+    context: contextCommand,
+    audit: auditCommand,
+    escalate: escalateCommand,
+    rule: ruleCommand,
+    rulings: rulingsCommand,
+    probe: probeCommand,
+    premises: premisesCommand,
+    init: initCommand,
+    mcp: mcpCommand,
+    doctor: doctorCommand,
+};
+export async function run(argv, io) {
+    let options;
+    try {
+        options = parseOptions(argv);
+    }
+    catch (error) {
+        io.stderr.write(`spec-harness: ${error.message}\n`);
+        return EXIT_ERROR;
+    }
+    if (options.version) {
+        io.stdout.write(`${version()}\n`);
+        return EXIT_OK;
+    }
+    if (options.help || options.command === undefined) {
+        io.stdout.write(HELP);
+        return options.command === undefined && !options.help ? EXIT_ERROR : EXIT_OK;
+    }
+    const command = COMMANDS[options.command];
+    if (command === undefined) {
+        io.stderr.write(`spec-harness: unknown command "${options.command}"; see spec-harness --help\n`);
+        return EXIT_ERROR;
+    }
+    try {
+        return await command(options, io);
+    }
+    catch (error) {
+        if (error instanceof UsageError || error instanceof ConfigError || error instanceof SiblingError) {
+            io.stderr.write(`spec-harness: ${error.message}\n`);
+            return EXIT_ERROR;
+        }
+        throw error;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    return run(argv, { stdout: process.stdout, stderr: process.stderr, cwd: process.cwd(), env: process.env });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The command line: arguments, dispatch, output and exit codes.\n *\n * Exit 0: done, nothing refused. Exit 1: something refused or found. Exit 2:\n * the answer cannot be trusted - a bad flag, a configuration that does not\n * load, a sibling that is missing or printed something unreadable. A run that\n * could not look must never exit as though it looked and found nothing\n * (spec-core ADR-0005).\n */\n\nimport { auditCommand, contextCommand, escalateCommand, probeCommand, ruleCommand, rulingsCommand } from './commands.js';\nimport { ConfigError, SIBLINGS } from './config.js';\nimport { stagedChanges } from './git.js';\nimport type { Decision } from './guard.js';\nimport { claudeResponse, gitResponse, parseClaudeHook } from './hooks.js';\nimport { premisesCommand } from './premises.js';\nimport { createReader } from './reader.js';\nimport { checkPaths } from './round.js';\nimport { mcpCommand } from './server.js';\nimport { initCommand } from './setup.js';\nimport { SiblingError } from './siblings.js';\nimport { MINIMUM_VERSIONS } from './versions.js';\nimport {\n  activeBrief,\n  describeActive,\n  EXIT_ERROR,\n  EXIT_FAILED,\n  EXIT_OK,\n  json,\n  namedId,\n  openWorkspace,\n  parseOptions,\n  UsageError,\n  version,\n  type CliIO,\n  type Options,\n  type Workspace,\n} from './workspace.js';\n\nexport { EXIT_ERROR, EXIT_FAILED, EXIT_OK, UsageError, version, type CliIO } from './workspace.js';\n\nexport const HELP = `spec-harness - context, guards, audits and rulings for rounds of agent work\n\nUsage:\n  spec-harness <command> [options]\n\nCommands:\n  context [brief]     What an agent needs to start a round: the brief, its scope,\n                      rulings, dependencies, the rules in force, the cited documents.\n  guard <path...>     May the round write these paths? Exit 1 if one is refused.\n  hook claude         Answer a Claude Code PreToolUse or PostToolUse hook (stdin).\n  hook git            Answer git's pre-commit hook for the staged files.\n  escalate            Ask a person to rule: --path <file> (repeatable) --reason <why>\n                      [--option \"<label>: <cost>\"]... [--recommend <text>].\n                      --list shows what waits; --show <id> prints one memo.\n  rule <id>           Record a person's ruling in the brief: --allow or --deny, with\n                      --note. It counts once committed signed.\n  rulings [brief]     The brief's rulings, and whether each one's signature verifies.\n  audit [brief]       Did the round stay inside the lines: what the archive would say,\n                      the brief's assertions, unverified rulings, new dependencies.\n  probe [brief]       Run the brief's probes: red at the base, green at the head.\n                      --at base|head|both, --id <probe>.\n  premises            Do the live briefs' premises still hold? For CI: exit 1 when one is stale.\n  init                Configure the spec-* tools to agree. Prints the plan; --write\n                      applies it; --git-hook adds a pre-commit hook.\n  mcp                 Serve start_round, check_path, request_escalation, audit_round,\n                      list_rounds and the workflow prompts over MCP on stdio.\n  doctor              Which siblings are installed, at which versions, and which\n                      brief is named. Exit 1 when one is older than this release needs.\n\nOptions:\n  --brief <id>        The brief the round works on. Otherwise SPEC_BRIEF, then the branch.\n  --base <ref>        What the round is measured from. Otherwise \"base\" in\n                      .spec-harness.json, then the remote's default branch.\n  --root <dir>        Run from another directory.\n  --format <fmt>      pretty or json.\n  --strict            Warnings fail the run.\n  --help, --version\n\nExit codes: 0 clean, 1 refused or found something, 2 the answer cannot be trusted.\n`;\n\n\n/* ------------------------------------------------------------------- guard */\n\nconst reader = createReader();\n\nasync function decisionsFor(\n  workspace: Workspace,\n  options: Options,\n  io: CliIO,\n  given: readonly string[],\n  cwd: string,\n): Promise<{ decisions: Decision[]; problem: string | null }> {\n  const active = await activeBrief(workspace, options, io.env);\n  const { brief, note, problem } = describeActive(active);\n  if (problem !== null) return { decisions: [], problem };\n  const decisions = await checkPaths(workspace, brief, note, given, cwd, reader);\n  return { decisions, problem: null };\n}\n\nconst SYMBOL: Record<Decision['verdict'], string> = { allow: 'ok     ', warn: 'warning', ask: 'ask    ', deny: 'refused' };\n\nasync function guardCommand(options: Options, io: CliIO): Promise<number> {\n  if (options.positionals.length === 0) throw new UsageError('guard needs at least one path');\n  const workspace = await openWorkspace(options, io);\n  const { decisions, problem } = await decisionsFor(workspace, options, io, options.positionals, io.cwd);\n  if (problem !== null) {\n    io.stderr.write(`spec-harness: ${problem}\\n`);\n    return EXIT_ERROR;\n  }\n  if (options.format === 'json') {\n    io.stdout.write(json('guard', { decisions }));\n  } else {\n    for (const decision of decisions) {\n      io.stdout.write(`${SYMBOL[decision.verdict]}  ${decision.message}\\n`);\n      if (decision.verdict !== 'allow') io.stdout.write(`         ${decision.hint}\\n`);\n    }\n  }\n  const refused = decisions.some((d) => d.verdict === 'deny' || d.verdict === 'ask');\n  const warned = decisions.some((d) => d.verdict === 'warn');\n  return refused || (options.strict && warned) ? EXIT_FAILED : EXIT_OK;\n}\n\n/* -------------------------------------------------------------------- hook */\n\nasync function readStdin(io: CliIO): Promise<string> {\n  if (io.stdin !== undefined) return io.stdin();\n  const chunks: Buffer[] = [];\n  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);\n  return Buffer.concat(chunks).toString('utf8');\n}\n\nasync function hookCommand(options: Options, io: CliIO): Promise<number> {\n  const kind = options.positionals[0];\n  if (kind === 'claude') {\n    const request = parseClaudeHook(await readStdin(io));\n    if ('error' in request) {\n      // A hook that cannot read its question refuses nothing it cannot see,\n      // but says so where the person reads it: a non-blocking error.\n      io.stderr.write(`spec-harness: ${request.error}\\n`);\n      return EXIT_FAILED;\n    }\n    if (request.paths.length === 0) return EXIT_OK;\n    const cwd = request.cwd ?? io.cwd;\n    let workspace: Workspace;\n    try {\n      workspace = await openWorkspace({ ...options, root: options.root ?? io.env['CLAUDE_PROJECT_DIR'] ?? cwd }, io);\n    } catch (error) {\n      if (error instanceof UsageError) return EXIT_OK;\n      throw error;\n    }\n    try {\n      const { decisions, problem } = await decisionsFor(workspace, options, io, request.paths, cwd);\n      if (problem !== null) {\n        // Exit 2 blocks the tool call, and its stderr reaches the model.\n        io.stderr.write(`spec-harness: ${problem}. Fix the brief or the branch before writing.\\n`);\n        return EXIT_ERROR;\n      }\n      const response = claudeResponse(request.event, decisions);\n      io.stdout.write(response.stdout);\n      return response.exitCode;\n    } catch (error) {\n      if (request.event !== 'PreToolUse') throw error;\n      // A round is named and its briefs cannot be read: the guard cannot\n      // tell a protected file from any other, so the write waits.\n      io.stderr.write(`spec-harness: cannot check this write: ${(error as Error).message}\\n`);\n      return EXIT_ERROR;\n    }\n  }\n  if (kind === 'git') {\n    const workspace = await openWorkspace(options, io);\n    const staged = await stagedChanges(workspace.root);\n    const paths = staged.flatMap((change) => (change.from === undefined ? [change.path] : [change.from, change.path]));\n    if (paths.length === 0) return EXIT_OK;\n    const { decisions, problem } = await decisionsFor(workspace, options, io, paths, workspace.root);\n    if (problem !== null) {\n      io.stderr.write(`spec-harness: ${problem}\\n`);\n      return EXIT_ERROR;\n    }\n    const response = gitResponse(decisions);\n    io.stderr.write(response.text);\n    return response.exitCode;\n  }\n  throw new UsageError('hook takes \"claude\" or \"git\"');\n}\n\n/* ------------------------------------------------------------------ doctor */\n\nasync function doctorCommand(options: Options, io: CliIO): Promise<number> {\n  const workspace = await openWorkspace(options, io);\n  const rows = SIBLINGS.map((name) => {\n    const sibling = workspace.siblings.locate(name);\n    const row = { tool: name, state: sibling.kind, minimum: MINIMUM_VERSIONS[name] };\n    if (sibling.kind === 'absent') return { ...row, version: null, detail: sibling.reason };\n    if (sibling.kind === 'outdated') return { ...row, version: sibling.version, detail: sibling.reason };\n    const command = sibling.command.join(' ');\n    const detail = sibling.version === null ? `${command} (named in .spec-harness.json; its version is not checked)` : `${command} (${sibling.version})`;\n    return { ...row, version: sibling.version, detail };\n  });\n  const named = namedId(workspace, options, io.env);\n  if (options.format === 'json') {\n    io.stdout.write(json('doctor', { root: workspace.root, branch: workspace.branch, brief: named, siblings: rows }));\n  } else {\n    io.stdout.write(`root    ${workspace.root}\\nbranch  ${workspace.branch ?? '(detached)'}\\nbrief   ${named ?? '(none named)'}\\n\\n`);\n    for (const row of rows) io.stdout.write(`${row.state.padEnd(8)}  ${row.tool.padEnd(10)}  ${row.detail}\\n`);\n  }\n  // An outdated sibling is a problem to fix, where a missing optional one is\n  // a choice; with none installed, the harness can check nothing.\n  const outdated = rows.some((row) => row.state === 'outdated');\n  const usable = rows.some((row) => row.state === 'found');\n  return outdated || !usable ? EXIT_FAILED : EXIT_OK;\n}\n\n/* ---------------------------------------------------------------- dispatch */\n\nconst COMMANDS: Readonly<Record<string, (options: Options, io: CliIO) => Promise<number>>> = {\n  guard: guardCommand,\n  hook: hookCommand,\n  context: contextCommand,\n  audit: auditCommand,\n  escalate: escalateCommand,\n  rule: ruleCommand,\n  rulings: rulingsCommand,\n  probe: probeCommand,\n  premises: premisesCommand,\n  init: initCommand,\n  mcp: mcpCommand,\n  doctor: doctorCommand,\n};\n\nexport async function run(argv: readonly string[], io: CliIO): Promise<number> {\n  let options: Options;\n  try {\n    options = parseOptions(argv);\n  } catch (error) {\n    io.stderr.write(`spec-harness: ${(error as Error).message}\\n`);\n    return EXIT_ERROR;\n  }\n  if (options.version) {\n    io.stdout.write(`${version()}\\n`);\n    return EXIT_OK;\n  }\n  if (options.help || options.command === undefined) {\n    io.stdout.write(HELP);\n    return options.command === undefined && !options.help ? EXIT_ERROR : EXIT_OK;\n  }\n  const command = COMMANDS[options.command];\n  if (command === undefined) {\n    io.stderr.write(`spec-harness: unknown command \"${options.command}\"; see spec-harness --help\\n`);\n    return EXIT_ERROR;\n  }\n  try {\n    return await command(options, io);\n  } catch (error) {\n    if (error instanceof UsageError || error instanceof ConfigError || error instanceof SiblingError) {\n      io.stderr.write(`spec-harness: ${error.message}\\n`);\n      return EXIT_ERROR;\n    }\n    throw error;\n  }\n}\n\nexport async function main(argv: readonly string[] = process.argv.slice(2)): Promise<number> {\n  return run(argv, { stdout: process.stdout, stderr: process.stderr, cwd: process.cwd(), env: process.env });\n}\n\n"]}

package/dist/commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The commands that read a round: context, audit, escalate, rule, rulings
+ * and probe. Each resolves the brief, asks `round.ts` for the facts and
+ * prints them; exit codes follow the family contract.
+ */
+import type { BriefRow } from './types.js';
+import { type CliIO, type Options, type Workspace } from './workspace.js';
+/** The brief a command acts on: a positional id, else the active one. A command that needs one and has none is a usage error. */
+export declare function targetBrief(workspace: Workspace, options: Options, io: CliIO, positional: string | undefined): Promise<{
+    brief: BriefRow;
+    briefs: BriefRow[];
+}>;
+export declare function contextCommand(options: Options, io: CliIO): Promise<number>;
+export declare function auditCommand(options: Options, io: CliIO): Promise<number>;
+export declare function escalateCommand(options: Options, io: CliIO): Promise<number>;
+export declare function ruleCommand(options: Options, io: CliIO): Promise<number>;
+export declare function rulingsCommand(options: Options, io: CliIO): Promise<number>;
+export declare function probeCommand(options: Options, io: CliIO): Promise<number>;