@descent-vtt/spec-harness 0.0.0 → 0.1.0

package/dist/context.js

@@ -0,0 +1,125 @@
+/**
+ * What an agent needs to start a round, and nothing it does not.
+ *
+ * The brief in full - it is the contract, and a summary of a contract is a
+ * different contract. Then what the brief implies but does not say: the scope
+ * as the guard will read it, the rulings already signed, the briefs it waits
+ * on, the rules spec-guard holds the scope's code to, and the documents the
+ * brief cites. The cited documents are the one part that can be large, so
+ * they fill what the budget leaves, in the order the brief cites them, and
+ * the rest are named rather than dropped silently.
+ */
+import { sameId } from './branch.js';
+function list(items, empty) {
+    return items.length === 0 ? `- ${empty}` : items.map((item) => `- \`${item}\``).join('\n');
+}
+function rulesSection(rules) {
+    if (!Array.isArray(rules)) {
+        return `The rules spec-guard holds this code to could not be read: ${rules.unavailable}. Treat every ADR as binding until they can.`;
+    }
+    if (rules.length === 0)
+        return 'spec-guard holds no rule over this scope.';
+    const byDocument = new Map();
+    for (const rule of rules)
+        byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);
+    const parts = [];
+    for (const [document, found] of byDocument) {
+        parts.push(`### ${document}`, '');
+        for (const rule of found)
+            parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);
+        parts.push('');
+    }
+    return parts.join('\n').trimEnd();
+}
+/**
+ * A brief's title without the id it repeats, `012 - Rotate tokens` read as
+ * `Rotate tokens`. Only the brief's own id is taken off: `Fix - the login
+ * bug` is a title, not an id and a title.
+ */
+function titleOf(brief) {
+    if (brief.title === null)
+        return null;
+    return brief.title.replace(/^\s*(\S+)\s+-\s+/, (whole, first) => (sameId(first, brief.id) ? '' : whole));
+}
+/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */
+export function renderContext(input) {
+    const { brief } = input;
+    const title = titleOf(brief);
+    const header = [
+        `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,
+        '',
+        [
+            `Status ${brief.status ?? 'unknown'}`,
+            brief.wave === null ? null : `wave ${brief.wave}`,
+            input.branch === null ? null : `branch \`${input.branch}\``,
+            input.base === null ? null : `measured from \`${input.base}\``,
+        ]
+            .filter((part) => part !== null)
+            .join(' · '),
+        '',
+    ].join('\n');
+    const contract = ['## The contract', '', `\`${brief.file}\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\n');
+    const rulings = input.rulings.length === 0
+        ? '- none'
+        : input.rulings.map((ruling) => `- ${ruling.id}, signed by ${ruling.signer}: ${ruling.paths.map((p) => `\`${p}\``).join(', ')}`).join('\n');
+    const scope = [
+        '## Scope, as the guard reads it',
+        '',
+        'May write:',
+        list(brief.affectedFiles, 'nothing declared: every write is outside the scope'),
+        '',
+        'Must not change without a ruling:',
+        list(brief.protectedFiles, 'nothing declared'),
+        '',
+        'Rulings in force:',
+        rulings,
+        '',
+    ].join('\n');
+    const waiting = input.dependencies.map((dependency) => {
+        const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;
+        return `- ${dependency.id}${dependency.title === null ? '' : ` ${dependency.title}`}: ${state}`;
+    });
+    const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\n'), ''].join('\n');
+    const rules = ['## Rules in force for this scope', '', rulesSection(input.rules), ''].join('\n');
+    const howTo = [
+        '## How this round works',
+        '',
+        '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',
+        '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',
+        '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',
+        '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\'s decision, not the round\'s.',
+        '',
+    ].join('\n');
+    const fixed = [header, contract, scope, dependencies, rules, howTo].join('\n');
+    const included = [];
+    const omitted = [];
+    const unresolved = [];
+    const documents = [];
+    let used = fixed.length;
+    for (const cited of input.cited) {
+        if (cited.text === null) {
+            unresolved.push(cited.path);
+            continue;
+        }
+        const heading = `### \`${cited.path}\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;
+        const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\n');
+        if (used + block.length > input.budget) {
+            omitted.push(cited.path);
+            continue;
+        }
+        used += block.length;
+        included.push(cited.path);
+        documents.push(block);
+    }
+    const citedSection = ['## Documents the brief cites', ''];
+    if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0)
+        citedSection.push('None.', '');
+    citedSection.push(...documents);
+    if (omitted.length > 0) {
+        citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted, ''), '');
+    }
+    if (unresolved.length > 0)
+        citedSection.push('Cited but not found in the repository:', list(unresolved, ''), '');
+    return { markdown: `${fixed}\n${citedSection.join('\n').trimEnd()}\n`, included, omitted, unresolved };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an agent needs to start a round, and nothing it does not.\n *\n * The brief in full - it is the contract, and a summary of a contract is a\n * different contract. Then what the brief implies but does not say: the scope\n * as the guard will read it, the rulings already signed, the briefs it waits\n * on, the rules spec-guard holds the scope's code to, and the documents the\n * brief cites. The cited documents are the one part that can be large, so\n * they fill what the budget leaves, in the order the brief cites them, and\n * the rest are named rather than dropped silently.\n */\n\nimport { sameId } from './branch.js';\nimport type { BriefRow } from './types.js';\n\nexport interface CitedDocument {\n  readonly path: string;\n  readonly title: string | null;\n  readonly status: string | null;\n  /** `null` when the link does not resolve to a readable file. */\n  readonly text: string | null;\n}\n\nexport interface RuleInForce {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n}\n\nexport interface RulingInForce {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface ContextInput {\n  readonly brief: BriefRow;\n  readonly briefText: string;\n  readonly dependencies: readonly BriefRow[];\n  readonly cited: readonly CitedDocument[];\n  /** The rules in force for the scope, or why they could not be read. */\n  readonly rules: readonly RuleInForce[] | { readonly unavailable: string };\n  readonly rulings: readonly RulingInForce[];\n  readonly branch: string | null;\n  readonly base: string | null;\n  readonly budget: number;\n}\n\nexport interface ContextPacket {\n  readonly markdown: string;\n  /** Cited documents included whole. */\n  readonly included: readonly string[];\n  /** Cited documents named but left out for the budget. */\n  readonly omitted: readonly string[];\n  /** Links in the brief that resolve to nothing. */\n  readonly unresolved: readonly string[];\n}\n\nfunction list(items: readonly string[], empty: string): string {\n  return items.length === 0 ? `- ${empty}` : items.map((item) => `- \\`${item}\\``).join('\\n');\n}\n\nfunction rulesSection(rules: ContextInput['rules']): string {\n  if (!Array.isArray(rules)) {\n    return `The rules spec-guard holds this code to could not be read: ${(rules as { unavailable: string }).unavailable}. Treat every ADR as binding until they can.`;\n  }\n  if (rules.length === 0) return 'spec-guard holds no rule over this scope.';\n  const byDocument = new Map<string, RuleInForce[]>();\n  for (const rule of rules) byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);\n  const parts: string[] = [];\n  for (const [document, found] of byDocument) {\n    parts.push(`### ${document}`, '');\n    for (const rule of found) parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);\n    parts.push('');\n  }\n  return parts.join('\\n').trimEnd();\n}\n\n/**\n * A brief's title without the id it repeats, `012 - Rotate tokens` read as\n * `Rotate tokens`. Only the brief's own id is taken off: `Fix - the login\n * bug` is a title, not an id and a title.\n */\nfunction titleOf(brief: BriefRow): string | null {\n  if (brief.title === null) return null;\n  return brief.title.replace(/^\\s*(\\S+)\\s+-\\s+/, (whole, first: string) => (sameId(first, brief.id) ? '' : whole));\n}\n\n/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */\nexport function renderContext(input: ContextInput): ContextPacket {\n  const { brief } = input;\n  const title = titleOf(brief);\n  const header = [\n    `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,\n    '',\n    [\n      `Status ${brief.status ?? 'unknown'}`,\n      brief.wave === null ? null : `wave ${brief.wave}`,\n      input.branch === null ? null : `branch \\`${input.branch}\\``,\n      input.base === null ? null : `measured from \\`${input.base}\\``,\n    ]\n      .filter((part) => part !== null)\n      .join(' · '),\n    '',\n  ].join('\\n');\n\n  const contract = ['## The contract', '', `\\`${brief.file}\\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\\n');\n\n  const rulings =\n    input.rulings.length === 0\n      ? '- none'\n      : input.rulings.map((ruling) => `- ${ruling.id}, signed by ${ruling.signer}: ${ruling.paths.map((p) => `\\`${p}\\``).join(', ')}`).join('\\n');\n  const scope = [\n    '## Scope, as the guard reads it',\n    '',\n    'May write:',\n    list(brief.affectedFiles, 'nothing declared: every write is outside the scope'),\n    '',\n    'Must not change without a ruling:',\n    list(brief.protectedFiles, 'nothing declared'),\n    '',\n    'Rulings in force:',\n    rulings,\n    '',\n  ].join('\\n');\n\n  const waiting = input.dependencies.map((dependency) => {\n    const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;\n    return `- ${dependency.id}${dependency.title === null ? '' : ` ${dependency.title}`}: ${state}`;\n  });\n  const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\\n'), ''].join('\\n');\n\n  const rules = ['## Rules in force for this scope', '', rulesSection(input.rules), ''].join('\\n');\n\n  const howTo = [\n    '## How this round works',\n    '',\n    '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',\n    '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',\n    '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',\n    '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\\'s decision, not the round\\'s.',\n    '',\n  ].join('\\n');\n\n  const fixed = [header, contract, scope, dependencies, rules, howTo].join('\\n');\n  const included: string[] = [];\n  const omitted: string[] = [];\n  const unresolved: string[] = [];\n  const documents: string[] = [];\n  let used = fixed.length;\n  for (const cited of input.cited) {\n    if (cited.text === null) {\n      unresolved.push(cited.path);\n      continue;\n    }\n    const heading = `### \\`${cited.path}\\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;\n    const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\\n');\n    if (used + block.length > input.budget) {\n      omitted.push(cited.path);\n      continue;\n    }\n    used += block.length;\n    included.push(cited.path);\n    documents.push(block);\n  }\n  const citedSection = ['## Documents the brief cites', ''];\n  if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0) citedSection.push('None.', '');\n  citedSection.push(...documents);\n  if (omitted.length > 0) {\n    citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted, ''), '');\n  }\n  if (unresolved.length > 0) citedSection.push('Cited but not found in the repository:', list(unresolved, ''), '');\n\n  return { markdown: `${fixed}\\n${citedSection.join('\\n').trimEnd()}\\n`, included, omitted, unresolved };\n}\n"]}

package/dist/document.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What the harness reads out of a brief or a cited document, through
+ * spec-core's Markdown scanner so that code and comments are never mistaken
+ * for structure: fenced blocks with their info strings, the section a line
+ * sits in, a section's tables, the relative links a document cites, and a
+ * document's title and status.
+ */
+import type { CodeBlock } from './probe.js';
+import type { TableView } from './rulings.js';
+export interface Citation {
+    readonly target: string;
+    /** 1-based. */
+    readonly line: number;
+}
+export interface SectionTables {
+    readonly tables: readonly TableView[];
+    /** 1-based line of the section's heading, or `null` when there is no such section. */
+    readonly headingLine: number | null;
+    /** 0-based index of the line after the section's last table row, or `null` when it has no table. */
+    readonly tableEndLine: number | null;
+}
+export interface DocumentReader {
+    codeBlocks(text: string): CodeBlock[];
+    sectionAt(text: string, line: number): string | null;
+    /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */
+    sectionsAt(text: string, line: number): string[];
+    sectionTables(text: string, section: string): SectionTables;
+    citations(text: string): Citation[];
+    titleAndStatus(text: string): {
+        readonly title: string | null;
+        readonly status: string | null;
+    };
+}

package/dist/document.js

@@ -0,0 +1,9 @@
+/**
+ * What the harness reads out of a brief or a cited document, through
+ * spec-core's Markdown scanner so that code and comments are never mistaken
+ * for structure: fenced blocks with their info strings, the section a line
+ * sits in, a section's tables, the relative links a document cites, and a
+ * document's title and status.
+ */
+export {};
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What the harness reads out of a brief or a cited document, through\n * spec-core's Markdown scanner so that code and comments are never mistaken\n * for structure: fenced blocks with their info strings, the section a line\n * sits in, a section's tables, the relative links a document cites, and a\n * document's title and status.\n */\n\nimport type { CodeBlock } from './probe.js';\nimport type { TableView } from './rulings.js';\n\nexport interface Citation {\n  readonly target: string;\n  /** 1-based. */\n  readonly line: number;\n}\n\nexport interface SectionTables {\n  readonly tables: readonly TableView[];\n  /** 1-based line of the section's heading, or `null` when there is no such section. */\n  readonly headingLine: number | null;\n  /** 0-based index of the line after the section's last table row, or `null` when it has no table. */\n  readonly tableEndLine: number | null;\n}\n\nexport interface DocumentReader {\n  codeBlocks(text: string): CodeBlock[];\n  sectionAt(text: string, line: number): string | null;\n  /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */\n  sectionsAt(text: string, line: number): string[];\n  sectionTables(text: string, section: string): SectionTables;\n  citations(text: string): Citation[];\n  titleAndStatus(text: string): { readonly title: string | null; readonly status: string | null };\n}\n"]}

package/dist/fs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The edge where the harness meets the disk: the configuration, the state
+ * directory outside the work tree, and paths as the filesystem spells them.
+ */
+import { type HarnessConfig } from './config.js';
+/** Reads `.spec-harness.json` at the root, or the defaults when there is none. */
+export declare function loadConfig(root: string): Promise<{
+    config: HarnessConfig;
+    file: string | null;
+}>;
+/**
+ * The real spelling of a path: links resolved and, on a filesystem that
+ * ignores case, the case the directory entries have. A path that does not
+ * exist yet is resolved through its nearest existing ancestor.
+ *
+ * This is what stops `SRC/db/schema.ts` from walking past a protection on
+ * `src/db/schema.ts` on Windows or macOS, where both name one file.
+ */
+export declare function realSpelling(path: string): string;
+/**
+ * A path as the repository names it - relative to the root, POSIX-separated,
+ * real spelling - or `null` when it lies outside the root.
+ */
+export declare function repositoryPath(given: string, root: string, cwd: string): string | null;
+/** The harness's own directory under the git common directory, created on demand (ADR-0003). */
+export declare function stateDirectory(commonDir: string, ...parts: string[]): Promise<string>;
+/** Writes a file whole or not at all: a temporary file renamed over the target. */
+export declare function writeAtomic(file: string, content: string): Promise<void>;
+export declare function readText(file: string): Promise<string | null>;

package/dist/fs.js

@@ -0,0 +1,85 @@
+/**
+ * The edge where the harness meets the disk: the configuration, the state
+ * directory outside the work tree, and paths as the filesystem spells them.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { ConfigError, CONFIG_FILE, DEFAULT_CONFIG, parseConfig } from './config.js';
+/** Reads `.spec-harness.json` at the root, or the defaults when there is none. */
+export async function loadConfig(root) {
+    const file = join(root, CONFIG_FILE);
+    if (!existsSync(file))
+        return { config: DEFAULT_CONFIG, file: null };
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${error.message}`);
+    }
+    return { config: parseConfig(raw), file };
+}
+/**
+ * The real spelling of a path: links resolved and, on a filesystem that
+ * ignores case, the case the directory entries have. A path that does not
+ * exist yet is resolved through its nearest existing ancestor.
+ *
+ * This is what stops `SRC/db/schema.ts` from walking past a protection on
+ * `src/db/schema.ts` on Windows or macOS, where both name one file.
+ */
+export function realSpelling(path) {
+    const missing = [];
+    let current = resolve(path);
+    for (;;) {
+        try {
+            const real = realpathSync.native(current);
+            return missing.length === 0 ? real : join(real, ...missing.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            missing.push(current.slice(parent.length).replace(/^[\\/]+/, ''));
+            current = parent;
+        }
+    }
+}
+/**
+ * A path as the repository names it - relative to the root, POSIX-separated,
+ * real spelling - or `null` when it lies outside the root.
+ */
+export function repositoryPath(given, root, cwd) {
+    const absolute = isAbsolute(given) ? given : resolve(cwd, given);
+    const real = realSpelling(absolute);
+    const realRoot = realSpelling(root);
+    const rel = relative(realRoot, real);
+    if (rel === '')
+        return '';
+    // `..env` at the root is inside it; only a `..` segment climbs out.
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return null;
+    return rel.split(sep).join('/');
+}
+/** The harness's own directory under the git common directory, created on demand (ADR-0003). */
+export async function stateDirectory(commonDir, ...parts) {
+    const directory = join(commonDir, 'spec-harness', ...parts);
+    await mkdir(directory, { recursive: true });
+    return directory;
+}
+/** Writes a file whole or not at all: a temporary file renamed over the target. */
+export async function writeAtomic(file, content) {
+    await mkdir(dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, content, 'utf8');
+    await rename(temporary, file);
+}
+export async function readText(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets the disk: the configuration, the state\n * directory outside the work tree, and paths as the filesystem spells them.\n */\n\nimport { existsSync, realpathSync } from 'node:fs';\nimport { mkdir, readFile, rename, writeFile } from 'node:fs/promises';\nimport { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';\n\nimport { ConfigError, CONFIG_FILE, DEFAULT_CONFIG, parseConfig, type HarnessConfig } from './config.js';\n\n/** Reads `.spec-harness.json` at the root, or the defaults when there is none. */\nexport async function loadConfig(root: string): Promise<{ config: HarnessConfig; file: string | null }> {\n  const file = join(root, CONFIG_FILE);\n  if (!existsSync(file)) return { config: DEFAULT_CONFIG, file: null };\n  let raw: unknown;\n  try {\n    raw = JSON.parse(await readFile(file, 'utf8'));\n  } catch (error) {\n    throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${(error as Error).message}`);\n  }\n  return { config: parseConfig(raw), file };\n}\n\n/**\n * The real spelling of a path: links resolved and, on a filesystem that\n * ignores case, the case the directory entries have. A path that does not\n * exist yet is resolved through its nearest existing ancestor.\n *\n * This is what stops `SRC/db/schema.ts` from walking past a protection on\n * `src/db/schema.ts` on Windows or macOS, where both name one file.\n */\nexport function realSpelling(path: string): string {\n  const missing: string[] = [];\n  let current = resolve(path);\n  for (;;) {\n    try {\n      const real = realpathSync.native(current);\n      return missing.length === 0 ? real : join(real, ...missing.reverse());\n    } catch {\n      const parent = dirname(current);\n      if (parent === current) return resolve(path);\n      missing.push(current.slice(parent.length).replace(/^[\\\\/]+/, ''));\n      current = parent;\n    }\n  }\n}\n\n/**\n * A path as the repository names it - relative to the root, POSIX-separated,\n * real spelling - or `null` when it lies outside the root.\n */\nexport function repositoryPath(given: string, root: string, cwd: string): string | null {\n  const absolute = isAbsolute(given) ? given : resolve(cwd, given);\n  const real = realSpelling(absolute);\n  const realRoot = realSpelling(root);\n  const rel = relative(realRoot, real);\n  if (rel === '') return '';\n  // `..env` at the root is inside it; only a `..` segment climbs out.\n  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;\n  return rel.split(sep).join('/');\n}\n\n/** The harness's own directory under the git common directory, created on demand (ADR-0003). */\nexport async function stateDirectory(commonDir: string, ...parts: string[]): Promise<string> {\n  const directory = join(commonDir, 'spec-harness', ...parts);\n  await mkdir(directory, { recursive: true });\n  return directory;\n}\n\n/** Writes a file whole or not at all: a temporary file renamed over the target. */\nexport async function writeAtomic(file: string, content: string): Promise<void> {\n  await mkdir(dirname(file), { recursive: true });\n  const temporary = `${file}.${process.pid}.tmp`;\n  await writeFile(temporary, content, 'utf8');\n  await rename(temporary, file);\n}\n\nexport async function readText(file: string): Promise<string | null> {\n  try {\n    return await readFile(file, 'utf8');\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/git.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The edge where the harness meets git.
+ *
+ * Reads, except for two things ADR-0003 allows and bounds: a temporary
+ * worktree, added and always removed by the sandbox, and nothing else. Every
+ * call is an argument vector, never a shell string, so a path or a ref cannot
+ * become a command.
+ */
+import type { FileChange } from './types.js';
+export interface Run {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Runs git and answers whatever it answered; a missing git is a code of -1. */
+export declare function git(args: readonly string[], cwd: string, input?: string): Promise<Run>;
+export declare class GitError extends Error {
+    constructor(message: string);
+}
+/** The top of the work tree holding `cwd`, POSIX-separated, or `null` outside one. */
+export declare function workTreeRoot(cwd: string): Promise<string | null>;
+/** The git directory every worktree of this repository shares. */
+export declare function commonDirectory(cwd: string): Promise<string | null>;
+/** The checked-out branch's short name, or `null` on a detached head. */
+export declare function currentBranch(cwd: string): Promise<string | null>;
+/** The remote's default branch as a local ref, such as `origin/main`, or `null`. */
+export declare function remoteDefault(cwd: string): Promise<string | null>;
+export declare function revision(ref: string, cwd: string): Promise<string | null>;
+export declare function mergeBase(a: string, b: string, cwd: string): Promise<string | null>;
+/** Parses `git diff --name-status -z` output. */
+export declare function parseNameStatus(output: string): FileChange[];
+/** The files changed from one revision to another, renames found. */
+export declare function changes(from: string, to: string, cwd: string): Promise<FileChange[]>;
+/** The files a commit would change: what is staged. */
+export declare function stagedChanges(cwd: string): Promise<FileChange[]>;
+/** A file's content at a revision, or `null` when it does not exist there. */
+export declare function show(ref: string, path: string, cwd: string): Promise<string | null>;
+/**
+ * The commit that last changed one line of a file, as of a revision, or of
+ * the working tree when `ref` is `null` - where a line nobody committed yet
+ * belongs to the all-zero commit.
+ */
+export declare function blameLine(ref: string | null, path: string, line: number, cwd: string): Promise<string | null>;
+export interface Signature {
+    readonly good: boolean;
+    /** The allowed signer's principal, for a good signature. */
+    readonly principal: string | null;
+    readonly detail: string;
+}
+/**
+ * Whether a commit carries a good SSH signature by a principal in the given
+ * allowed-signers file. The file is passed in, never read from the commit's
+ * own tree: a round cannot vouch for itself (ADR-0006).
+ */
+export declare function verifyCommit(sha: string, allowedSignersFile: string, cwd: string): Promise<Signature>;
+export declare function addWorktree(path: string, rev: string, cwd: string): Promise<void>;
+export declare function removeWorktree(path: string, cwd: string): Promise<boolean>;

package/dist/git.js

@@ -0,0 +1,129 @@
+/**
+ * The edge where the harness meets git.
+ *
+ * Reads, except for two things ADR-0003 allows and bounds: a temporary
+ * worktree, added and always removed by the sandbox, and nothing else. Every
+ * call is an argument vector, never a shell string, so a path or a ref cannot
+ * become a command.
+ */
+import { execFile } from 'node:child_process';
+/** Runs git and answers whatever it answered; a missing git is a code of -1. */
+export function git(args, cwd, input) {
+    return new Promise((resolve) => {
+        const child = execFile('git', [...args], { cwd, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8', windowsHide: true }, (error, stdout, stderr) => {
+            const code = error === null ? 0 : typeof error.code === 'number' ? (error.code) : -1;
+            resolve({ code, stdout, stderr });
+        });
+        if (input !== undefined)
+            child.stdin?.end(input);
+    });
+}
+async function value(args, cwd) {
+    const run = await git(args, cwd);
+    return run.code === 0 ? run.stdout.trim() : null;
+}
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitError';
+    }
+}
+/** The top of the work tree holding `cwd`, POSIX-separated, or `null` outside one. */
+export async function workTreeRoot(cwd) {
+    return value(['rev-parse', '--show-toplevel'], cwd);
+}
+/** The git directory every worktree of this repository shares. */
+export async function commonDirectory(cwd) {
+    return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+}
+/** The checked-out branch's short name, or `null` on a detached head. */
+export async function currentBranch(cwd) {
+    return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);
+}
+/** The remote's default branch as a local ref, such as `origin/main`, or `null`. */
+export async function remoteDefault(cwd) {
+    return value(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd);
+}
+export async function revision(ref, cwd) {
+    return value(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);
+}
+export async function mergeBase(a, b, cwd) {
+    return value(['merge-base', a, b], cwd);
+}
+/** Parses `git diff --name-status -z` output. */
+export function parseNameStatus(output) {
+    const fields = output.split('\0');
+    const out = [];
+    for (let i = 0; i < fields.length;) {
+        const code = fields[i] ?? '';
+        if (code === '') {
+            i += 1;
+            continue;
+        }
+        const status = code.charAt(0);
+        if (status === 'R' || status === 'C') {
+            out.push({ status, from: fields[i + 1] ?? '', path: fields[i + 2] ?? '' });
+            i += 3;
+        }
+        else {
+            out.push({ status, path: fields[i + 1] ?? '' });
+            i += 2;
+        }
+    }
+    return out;
+}
+/** The files changed from one revision to another, renames found. */
+export async function changes(from, to, cwd) {
+    const run = await git(['diff', '--name-status', '-z', '--find-renames', '--no-color', from, to, '--'], cwd);
+    if (run.code !== 0)
+        throw new GitError(`git diff ${from} ${to} failed: ${run.stderr.trim()}`);
+    return parseNameStatus(run.stdout);
+}
+/** The files a commit would change: what is staged. */
+export async function stagedChanges(cwd) {
+    const run = await git(['diff', '--cached', '--name-status', '-z', '--find-renames', '--no-color', '--'], cwd);
+    if (run.code !== 0)
+        throw new GitError(`git diff --cached failed: ${run.stderr.trim()}`);
+    return parseNameStatus(run.stdout);
+}
+/** A file's content at a revision, or `null` when it does not exist there. */
+export async function show(ref, path, cwd) {
+    const run = await git(['show', `${ref}:${path}`], cwd);
+    return run.code === 0 ? run.stdout : null;
+}
+/**
+ * The commit that last changed one line of a file, as of a revision, or of
+ * the working tree when `ref` is `null` - where a line nobody committed yet
+ * belongs to the all-zero commit.
+ */
+export async function blameLine(ref, path, line, cwd) {
+    const run = await git(['blame', '--porcelain', '-L', `${line},${line}`, ...(ref === null ? [] : [ref]), '--', path], cwd);
+    if (run.code !== 0)
+        return null;
+    const sha = /^([0-9a-f]{40,64}) /.exec(run.stdout)?.[1];
+    return sha ?? null;
+}
+/**
+ * Whether a commit carries a good SSH signature by a principal in the given
+ * allowed-signers file. The file is passed in, never read from the commit's
+ * own tree: a round cannot vouch for itself (ADR-0006).
+ */
+export async function verifyCommit(sha, allowedSignersFile, cwd) {
+    const run = await git(['-c', `gpg.ssh.allowedSignersFile=${allowedSignersFile}`, '-c', 'gpg.format=ssh', 'verify-commit', '--raw', sha], cwd);
+    const text = `${run.stderr}\n${run.stdout}`;
+    const principal = /Good "git" signature for (\S+)/.exec(text)?.[1] ?? null;
+    return { good: run.code === 0 && principal !== null, principal, detail: text.trim().split('\n')[0] ?? '' };
+}
+export async function addWorktree(path, rev, cwd) {
+    const run = await git(['worktree', 'add', '--detach', '--force', path, rev], cwd);
+    if (run.code !== 0)
+        throw new GitError(`git worktree add failed: ${run.stderr.trim()}`);
+}
+export async function removeWorktree(path, cwd) {
+    const run = await git(['worktree', 'remove', '--force', path], cwd);
+    if (run.code === 0)
+        return true;
+    await git(['worktree', 'prune'], cwd);
+    return false;
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets git.\n *\n * Reads, except for two things ADR-0003 allows and bounds: a temporary\n * worktree, added and always removed by the sandbox, and nothing else. Every\n * call is an argument vector, never a shell string, so a path or a ref cannot\n * become a command.\n */\n\nimport { execFile } from 'node:child_process';\n\nimport type { FileChange } from './types.js';\n\nexport interface Run {\n  readonly code: number;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\n/** Runs git and answers whatever it answered; a missing git is a code of -1. */\nexport function git(args: readonly string[], cwd: string, input?: string): Promise<Run> {\n  return new Promise((resolve) => {\n    const child = execFile(\n      'git',\n      [...args],\n      { cwd, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8', windowsHide: true },\n      (error, stdout, stderr) => {\n        const code = error === null ? 0 : typeof (error as { code?: unknown }).code === 'number' ? ((error as { code: number }).code) : -1;\n        resolve({ code, stdout, stderr });\n      },\n    );\n    if (input !== undefined) child.stdin?.end(input);\n  });\n}\n\nasync function value(args: readonly string[], cwd: string): Promise<string | null> {\n  const run = await git(args, cwd);\n  return run.code === 0 ? run.stdout.trim() : null;\n}\n\nexport class GitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'GitError';\n  }\n}\n\n/** The top of the work tree holding `cwd`, POSIX-separated, or `null` outside one. */\nexport async function workTreeRoot(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--show-toplevel'], cwd);\n}\n\n/** The git directory every worktree of this repository shares. */\nexport async function commonDirectory(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);\n}\n\n/** The checked-out branch's short name, or `null` on a detached head. */\nexport async function currentBranch(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);\n}\n\n/** The remote's default branch as a local ref, such as `origin/main`, or `null`. */\nexport async function remoteDefault(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd);\n}\n\nexport async function revision(ref: string, cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);\n}\n\nexport async function mergeBase(a: string, b: string, cwd: string): Promise<string | null> {\n  return value(['merge-base', a, b], cwd);\n}\n\n/** Parses `git diff --name-status -z` output. */\nexport function parseNameStatus(output: string): FileChange[] {\n  const fields = output.split('\\0');\n  const out: FileChange[] = [];\n  for (let i = 0; i < fields.length; ) {\n    const code = fields[i] ?? '';\n    if (code === '') {\n      i += 1;\n      continue;\n    }\n    const status = code.charAt(0) as FileChange['status'];\n    if (status === 'R' || status === 'C') {\n      out.push({ status, from: fields[i + 1] ?? '', path: fields[i + 2] ?? '' });\n      i += 3;\n    } else {\n      out.push({ status, path: fields[i + 1] ?? '' });\n      i += 2;\n    }\n  }\n  return out;\n}\n\n/** The files changed from one revision to another, renames found. */\nexport async function changes(from: string, to: string, cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--name-status', '-z', '--find-renames', '--no-color', from, to, '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff ${from} ${to} failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** The files a commit would change: what is staged. */\nexport async function stagedChanges(cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--cached', '--name-status', '-z', '--find-renames', '--no-color', '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff --cached failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** A file's content at a revision, or `null` when it does not exist there. */\nexport async function show(ref: string, path: string, cwd: string): Promise<string | null> {\n  const run = await git(['show', `${ref}:${path}`], cwd);\n  return run.code === 0 ? run.stdout : null;\n}\n\n/**\n * The commit that last changed one line of a file, as of a revision, or of\n * the working tree when `ref` is `null` - where a line nobody committed yet\n * belongs to the all-zero commit.\n */\nexport async function blameLine(ref: string | null, path: string, line: number, cwd: string): Promise<string | null> {\n  const run = await git(['blame', '--porcelain', '-L', `${line},${line}`, ...(ref === null ? [] : [ref]), '--', path], cwd);\n  if (run.code !== 0) return null;\n  const sha = /^([0-9a-f]{40,64}) /.exec(run.stdout)?.[1];\n  return sha ?? null;\n}\n\nexport interface Signature {\n  readonly good: boolean;\n  /** The allowed signer's principal, for a good signature. */\n  readonly principal: string | null;\n  readonly detail: string;\n}\n\n/**\n * Whether a commit carries a good SSH signature by a principal in the given\n * allowed-signers file. The file is passed in, never read from the commit's\n * own tree: a round cannot vouch for itself (ADR-0006).\n */\nexport async function verifyCommit(sha: string, allowedSignersFile: string, cwd: string): Promise<Signature> {\n  const run = await git(\n    ['-c', `gpg.ssh.allowedSignersFile=${allowedSignersFile}`, '-c', 'gpg.format=ssh', 'verify-commit', '--raw', sha],\n    cwd,\n  );\n  const text = `${run.stderr}\\n${run.stdout}`;\n  const principal = /Good \"git\" signature for (\\S+)/.exec(text)?.[1] ?? null;\n  return { good: run.code === 0 && principal !== null, principal, detail: text.trim().split('\\n')[0] ?? '' };\n}\n\nexport async function addWorktree(path: string, rev: string, cwd: string): Promise<void> {\n  const run = await git(['worktree', 'add', '--detach', '--force', path, rev], cwd);\n  if (run.code !== 0) throw new GitError(`git worktree add failed: ${run.stderr.trim()}`);\n}\n\nexport async function removeWorktree(path: string, cwd: string): Promise<boolean> {\n  const run = await git(['worktree', 'remove', '--force', path], cwd);\n  if (run.code === 0) return true;\n  await git(['worktree', 'prune'], cwd);\n  return false;\n}\n"]}

package/dist/guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * May this round write this file?
+ *
+ * The answer is read from the brief the round runs under: `protectedFiles`
+ * are refused unless a person has ruled otherwise, `affectedFiles` are the
+ * round's to write, and anything else is outside the scope the person
+ * approved. A guard is a guardrail, not a boundary - an agent that writes
+ * through a shell passes it - so the audit and spec-brief's archive are the
+ * gates, and this is what keeps an honest agent from needing them (ADR-0005).
+ */
+import type { OutOfScope } from './config.js';
+import type { BriefRow } from './types.js';
+export type Verdict = 'allow' | 'warn' | 'ask' | 'deny';
+export type Reason = 'outside-repository' | 'no-brief' | 'brief-file' | 'protected' | 'ruled' | 'unreadable-protection' | 'in-scope' | 'out-of-scope';
+export interface Decision {
+    /** Repository-relative, or the path as given when it lies outside. */
+    readonly path: string;
+    readonly verdict: Verdict;
+    readonly reason: Reason;
+    /** The patterns or ruling that decided it. */
+    readonly because: readonly string[];
+    readonly message: string;
+    readonly hint: string;
+}
+/** A ruling whose signature has been verified: a person allowed these paths. */
+export interface VerifiedRuling {
+    readonly id: string;
+    readonly paths: readonly string[];
+    readonly signer: string;
+}
+export interface GuardInput {
+    /** Repository-relative POSIX path, or `null` for a path outside the repository. */
+    readonly path: string | null;
+    /** The path as the caller gave it, for messages. */
+    readonly given: string;
+    readonly brief: BriefRow | null;
+    /** Why there is no brief, when there is none. */
+    readonly noBrief?: string | undefined;
+    readonly rulings: readonly VerifiedRuling[];
+    readonly outOfScope: OutOfScope;
+}
+/** Decides one path. Pure: the caller resolved the path, the brief and the rulings. */
+export declare function decide(input: GuardInput): Decision;