balladeer 1.0.14 → 1.0.16

package/dist/judge-brief.d.ts

@@ -0,0 +1,36 @@
+import type { BehaviorMap } from "./behavior-map-schema.js";
+import type { PromiseDocument } from "./promise-meaning.js";
+/**
+ * The fixed instructions a judge works from, `judge-brief/v1`.
+ *
+ * One promise, one change, one disposable checkout at the change's head. The
+ * rules are the contract's: cases first, linked test first, broken only with a
+ * command that fails with the change and passes without it, kept only after
+ * each passing case was exercised, and could not tell for everything else,
+ * with what stopped the judge. The runner checks the reproduction itself by
+ * running it both ways, so a judge that claims a break it did not prove is
+ * downgraded rather than believed.
+ *
+ * The text is a constant so a verdict can name the exact brief it was given.
+ * Changing a word here is a new revision.
+ */
+export declare const JUDGE_BRIEF_REVISION = "judge-brief/v1";
+export declare const JUDGE_BRIEF = "You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.\n\nDecide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.\n\nRules:\n\n1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.\n2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.\n3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.\n4. Report \"broken\" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with `git checkout --detach <base>`, run the command, then return with `git checkout --detach <head>`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.\n5. Report \"kept\" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.\n6. Anything else is \"could_not_tell\". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.\n7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.\n8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"promiseId\": \"<the promise id below>\", \"verdict\": \"kept\" | \"broken\" | \"could_not_tell\", \"reproduction\": {\"command\": \"<shell command>\", \"cwd\": \".\"} or null, \"exercisedCases\": [\"passing-1\", ...], \"notes\": \"<at most a few sentences>\"}\n\nA reproduction is required for \"broken\" and optional otherwise.";
+export type JudgeBriefInput = Readonly<{
+    promise: PromiseDocument;
+    map?: BehaviorMap;
+    changedFiles: readonly string[];
+    base: string;
+    head: string;
+    /** What the runner saw when it ran the linked tests itself, before the judge started. */
+    linkedTestRuns?: readonly Readonly<{
+        file: string;
+        command: string;
+        outcome: string;
+        output: string;
+    }>[];
+    /** Roughly how long the judge has, so it answers before it is stopped. */
+    minutes?: number;
+}>;
+/** The brief plus this one judgment's facts, as the prompt the agent receives. */
+export declare function judgePrompt(input: JudgeBriefInput): string;

package/dist/judge-brief.js

@@ -0,0 +1,89 @@
+/**
+ * The fixed instructions a judge works from, `judge-brief/v1`.
+ *
+ * One promise, one change, one disposable checkout at the change's head. The
+ * rules are the contract's: cases first, linked test first, broken only with a
+ * command that fails with the change and passes without it, kept only after
+ * each passing case was exercised, and could not tell for everything else,
+ * with what stopped the judge. The runner checks the reproduction itself by
+ * running it both ways, so a judge that claims a break it did not prove is
+ * downgraded rather than believed.
+ *
+ * The text is a constant so a verdict can name the exact brief it was given.
+ * Changing a word here is a new revision.
+ */
+export const JUDGE_BRIEF_REVISION = "judge-brief/v1";
+export const JUDGE_BRIEF = `You are judging one change to this repository against one promise about the software's behavior. A named person agreed the promise's meaning. Your working directory is a disposable copy of the repository checked out at the change's head commit; anything you write here is thrown away afterwards.
+
+Decide whether this change keeps the promise, breaks it, or whether you could not tell, and back what you say with evidence you produced yourself.
+
+Rules:
+
+1. Read the promise's cases first. The passing cases (passing-1, passing-2, and so on, in the order listed) say what must keep happening. The failing cases (failing-1, and so on) say what must never happen. The non-goals say what the promise does not cover; a change there is not a break.
+2. If linked tests are listed, run them first, before anything else. If the runner already reports a linked test's outcome below, use it and rerun only when you need its output.
+3. Read the code, not descriptions of it. Commit messages, comments, documentation and pull request text say what someone intended, not what the code does.
+4. Report "broken" only with a command that fails (exits non-zero) with this change and passes (exits zero) without it, and only after you have run it both ways yourself. To run it without the change, check out the base commit in this copy with \`git checkout --detach <base>\`, run the command, then return with \`git checkout --detach <head>\`. If the command needs a test you wrote, put that test in a new file rather than editing an existing one, so it exists on both commits. The command must run from the repository root or from the directory you name as its cwd, and must not depend on anything outside this copy.
+5. Report "kept" only after you have exercised each passing case against the changed code, by running a test or a command that shows it, and list every case you exercised.
+6. Anything else is "could_not_tell". Say in notes what stopped you: a missing dependency, a service you could not reach, a case you could not exercise, time running out.
+7. Name the promise, never the person. Do not put anyone's name, email or account in your answer.
+8. Do not push, open or merge pull requests, publish anything, or change anything outside this copy. Do not read or print credentials.
+
+Your final message must be exactly one JSON object and nothing after it:
+
+{"promiseId": "<the promise id below>", "verdict": "kept" | "broken" | "could_not_tell", "reproduction": {"command": "<shell command>", "cwd": "."} or null, "exercisedCases": ["passing-1", ...], "notes": "<at most a few sentences>"}
+
+A reproduction is required for "broken" and optional otherwise.`;
+const CHANGED_FILES_SHOWN = 300;
+/** The brief plus this one judgment's facts, as the prompt the agent receives. */
+export function judgePrompt(input) {
+    const sections = [JUDGE_BRIEF, ""];
+    sections.push(`Base commit (without the change): ${input.base}`);
+    sections.push(`Head commit (with the change, checked out now): ${input.head}`);
+    if (input.minutes !== undefined)
+        sections.push(`You have about ${input.minutes} minutes. If time is short, answer could_not_tell with what is left.`);
+    sections.push("");
+    sections.push("The promise, as Balladeer returns it:");
+    sections.push(JSON.stringify({
+        promiseId: input.promise.promiseId,
+        title: input.promise.title,
+        semanticDigest: input.promise.semanticDigest,
+        meaning: input.promise.meaning,
+    }, null, 2));
+    if (input.promise.meaning.passingExamples.length === 0)
+        sections.push("Its passing cases were not available here, so no case can be exercised; answer kept only if you can say from the code that none of the failing cases can happen.");
+    sections.push("");
+    if (input.map !== undefined) {
+        // The excerpt repeats the promise printed above; the judge reads it once.
+        const map = { ...input.map };
+        delete map.meaning;
+        sections.push("Where this promise's behavior lives, from its behavior map (built earlier; check it against the code):");
+        sections.push(JSON.stringify(map, null, 2));
+    }
+    else {
+        sections.push("There is no behavior map for this promise; find where its behavior lives yourself.");
+    }
+    sections.push("");
+    const shown = input.changedFiles.slice(0, CHANGED_FILES_SHOWN);
+    sections.push(`Files this change touches (${input.changedFiles.length}):`);
+    for (const file of shown)
+        sections.push(`- ${file}`);
+    if (input.changedFiles.length > shown.length)
+        sections.push(`- and ${input.changedFiles.length - shown.length} more; run git diff to see them`);
+    sections.push(`See the change itself with: git diff ${input.base} ${input.head}`);
+    if (input.linkedTestRuns !== undefined && input.linkedTestRuns.length > 0) {
+        sections.push("");
+        sections.push("The runner already ran the linked tests at head:");
+        for (const run of input.linkedTestRuns) {
+            sections.push(`- ${run.file}: ${run.outcome} (${run.command})`);
+            if (run.output.trim())
+                sections.push(indent(run.output.trim()));
+        }
+    }
+    return `${sections.join("\n")}\n`;
+}
+function indent(text) {
+    return text
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}

package/dist/judge-hook.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a judge run starts: a coding host's PreToolUse hook, or git's own
+ * pre-push hook.
+ *
+ * The host hook fires on every shell command the agent runs, so the first job
+ * is to say "not a push" and get out of the way in milliseconds. Only `git
+ * push`, `gh pr create` and `gh pr merge` go further. The command is read the
+ * way a shell reads it, so a push inside a quoted commit message is not a push
+ * and `git stash push` is not one either.
+ */
+export type HookHost = "claude" | "codex" | "git";
+export type HookInput = Readonly<{
+    eventName?: string;
+    toolName?: string;
+    command?: string;
+    cwd?: string;
+    model?: string;
+}>;
+/** A coding host's hook payload, or nothing when the text is not one. */
+export declare function parseHookInput(text: string): HookInput | undefined;
+/** The refs git hands a pre-push hook: one line per ref being pushed. */
+export type PushedRef = Readonly<{
+    localRef: string;
+    localSha: string;
+    remoteRef: string;
+    remoteSha: string;
+}>;
+export declare function parsePrePushInput(text: string): PushedRef[];
+/**
+ * The simple commands a shell line runs, as word lists.
+ *
+ * Quotes and backslashes are honored, so quoted text stays one word; `;`,
+ * `&&`, `||`, `|`, `&`, newlines and parentheses end a command, so `npm test
+ * && git push` is two commands and `$(git push)` is found. A comment runs to
+ * the end of its line.
+ */
+export declare function shellCommands(line: string): string[][];
+/** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
+export declare function isPushCommand(line: string, depth?: number): boolean;
+export type HookResponse = Readonly<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+/**
+ * What the host is told. In report mode the lines reach the agent as context
+ * and the push goes ahead; a block is exit 2 with the reason, which both hosts
+ * treat as a refusal of that one command. Claude Code also gets the reason as
+ * `permissionDecision: "deny"`, which it prefers to stderr; Codex is given the
+ * stderr form its documentation names.
+ */
+export declare function hookResponse(host: HookHost, outcome: Readonly<{
+    block: boolean;
+    lines: readonly string[];
+}>): HookResponse;
+/** The status line both hosts show while the hook runs, and the mark of the entry this command owns. */
+export declare const JUDGE_HOOK_MARKER = "Balladeer judge";
+export declare const JUDGE_HOOK_TIMEOUT_SECONDS = 900;
+/**
+ * The most a judge budget may be when the command runs from a host's hook.
+ *
+ * Claude Code documents that a hook reaching its own timeout lets the command
+ * run, and Codex documents no rule; so a budget longer than the hook's timeout
+ * would let a push through with no verdict and no line saying so, which is the
+ * one thing block mode exists to prevent. Login checks and the risk ranking can
+ * spend about ninety seconds before the budget starts, so the cap sits well
+ * under the hook timeout. The hook canary of 29 September 2026 found the gap.
+ */
+export declare const HOOK_BUDGET_CAP_SECONDS = 600;
+export declare const GIT_HOOK_MARKER = "# Installed by: balladeer judge --install-hook git";
+/** The budget a run may spend: as configured, except from a hook, where the host's timeout rules. */
+export declare function effectiveBudgetSeconds(configured: number, fromHook: boolean): number;
+export declare function judgeHookCommand(host: "claude" | "codex"): string;
+export declare const GIT_PRE_PUSH_SCRIPT: string;
+export type HookInstallResult = Readonly<{
+    target: HookHost;
+    path: string;
+    status: "written" | "unchanged" | "refused";
+    reason?: string;
+}>;
+/** Where git looks for hooks in this checkout, which is not `.git/hooks` in a worktree. */
+export declare function gitHooksDirectory(root: string): string;
+/** Install the judge hook for one host. Running it twice changes nothing the second time. */
+export declare function installJudgeHook(root: string, target: HookHost): HookInstallResult;

package/dist/judge-hook.js

@@ -0,0 +1,420 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+/** A coding host's hook payload, or nothing when the text is not one. */
+export function parseHookInput(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const input = value;
+    const toolInput = input.tool_input;
+    const command = commandText(toolInput?.command);
+    return {
+        ...(typeof input.hook_event_name === "string" ? { eventName: input.hook_event_name } : {}),
+        ...(typeof input.tool_name === "string" ? { toolName: input.tool_name } : {}),
+        ...(command === undefined ? {} : { command }),
+        ...(typeof input.cwd === "string" ? { cwd: input.cwd } : {}),
+        ...(typeof input.model === "string" ? { model: input.model } : {}),
+    };
+}
+const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+/** Codex can send a command as an argument vector; a shell's `-c` script is what runs. */
+function commandText(value) {
+    if (typeof value === "string")
+        return value;
+    if (!Array.isArray(value) || !value.every((word) => typeof word === "string"))
+        return undefined;
+    const words = value;
+    if (words.length >= 3 && SHELLS.has(basename(words[0])) && /^-[a-z]*c[a-z]*$/.test(words[1]))
+        return words[2];
+    return words.join(" ");
+}
+const ZERO = /^0{40}$/;
+export function parsePrePushInput(text) {
+    const refs = [];
+    for (const line of text.split("\n")) {
+        const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+        if (!localRef || !localSha || !remoteRef || !remoteSha)
+            continue;
+        if (!/^[0-9a-f]{40}$/.test(localSha) || ZERO.test(localSha))
+            continue;
+        refs.push({ localRef, localSha, remoteRef, remoteSha });
+    }
+    return refs;
+}
+/**
+ * The simple commands a shell line runs, as word lists.
+ *
+ * Quotes and backslashes are honored, so quoted text stays one word; `;`,
+ * `&&`, `||`, `|`, `&`, newlines and parentheses end a command, so `npm test
+ * && git push` is two commands and `$(git push)` is found. A comment runs to
+ * the end of its line.
+ */
+export function shellCommands(line) {
+    const commands = [];
+    let words = [];
+    let word = "";
+    let inWord = false;
+    const endWord = () => {
+        if (inWord)
+            words.push(word);
+        word = "";
+        inWord = false;
+    };
+    const endCommand = () => {
+        endWord();
+        if (words.length > 0)
+            commands.push(words);
+        words = [];
+    };
+    for (let at = 0; at < line.length; at += 1) {
+        const char = line[at];
+        if (char === "'") {
+            const close = line.indexOf("'", at + 1);
+            const end = close < 0 ? line.length : close;
+            word += line.slice(at + 1, end);
+            inWord = true;
+            at = end;
+        }
+        else if (char === '"') {
+            inWord = true;
+            at += 1;
+            while (at < line.length && line[at] !== '"') {
+                if (line[at] === "\\" && at + 1 < line.length)
+                    at += 1;
+                word += line[at];
+                at += 1;
+            }
+        }
+        else if (char === "\\") {
+            if (at + 1 < line.length && line[at + 1] !== "\n")
+                word += line[at + 1];
+            inWord = true;
+            at += 1;
+        }
+        else if (char === "#" && !inWord) {
+            const end = line.indexOf("\n", at);
+            at = end < 0 ? line.length : end - 1;
+        }
+        else if (/\s/.test(char)) {
+            if (char === "\n")
+                endCommand();
+            else
+                endWord();
+        }
+        else if (";&|()`".includes(char)) {
+            endCommand();
+        }
+        else {
+            word += char;
+            inWord = true;
+        }
+    }
+    endCommand();
+    return commands;
+}
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const WRAPPERS = new Set(["env", "command", "exec", "time", "nohup", "nice", "sudo", "builtin"]);
+/** The command's words with leading assignments and wrappers like `env` and `sudo` removed. */
+function program(words) {
+    let at = 0;
+    while (at < words.length) {
+        const word = words[at];
+        if (ASSIGNMENT.test(word))
+            at += 1;
+        else if (WRAPPERS.has(basename(word))) {
+            at += 1;
+            while (at < words.length && (words[at].startsWith("-") || ASSIGNMENT.test(words[at])))
+                at += 1;
+        }
+        else
+            break;
+    }
+    return words.slice(at);
+}
+/** git's global options that take the next word as their value. */
+const GIT_VALUE_OPTIONS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--super-prefix",
+    "--config-env",
+]);
+function gitSubcommand(args) {
+    for (let at = 0; at < args.length; at += 1) {
+        const word = args[at];
+        if (GIT_VALUE_OPTIONS.has(word)) {
+            at += 1;
+            continue;
+        }
+        if (word.startsWith("-"))
+            continue;
+        return word;
+    }
+    return undefined;
+}
+/** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
+export function isPushCommand(line, depth = 0) {
+    for (const words of shellCommands(line)) {
+        const run = program(words);
+        if (run.length === 0)
+            continue;
+        const name = basename(run[0]);
+        if (name === "git" && gitSubcommand(run.slice(1)) === "push")
+            return true;
+        if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge"))
+            return true;
+        if (SHELLS.has(name) && depth < 3) {
+            const flag = run.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word));
+            const script = flag > 0 ? run[flag + 1] : undefined;
+            if (script !== undefined && isPushCommand(script, depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * What the host is told. In report mode the lines reach the agent as context
+ * and the push goes ahead; a block is exit 2 with the reason, which both hosts
+ * treat as a refusal of that one command. Claude Code also gets the reason as
+ * `permissionDecision: "deny"`, which it prefers to stderr; Codex is given the
+ * stderr form its documentation names.
+ */
+export function hookResponse(host, outcome) {
+    const text = outcome.lines.join("\n");
+    if (outcome.block) {
+        if (host === "claude")
+            return {
+                stdout: `${JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "deny",
+                        permissionDecisionReason: text,
+                    },
+                })}\n`,
+                stderr: `${text}\n`,
+                exitCode: 2,
+            };
+        return { stdout: "", stderr: `${text}\n`, exitCode: 2 };
+    }
+    if (outcome.lines.length === 0)
+        return { stdout: "", stderr: "", exitCode: 0 };
+    if (host === "git")
+        return { stdout: `${text}\n`, stderr: "", exitCode: 0 };
+    return {
+        stdout: `${JSON.stringify({
+            hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: text },
+        })}\n`,
+        stderr: "",
+        exitCode: 0,
+    };
+}
+/** The status line both hosts show while the hook runs, and the mark of the entry this command owns. */
+export const JUDGE_HOOK_MARKER = "Balladeer judge";
+export const JUDGE_HOOK_TIMEOUT_SECONDS = 900;
+/**
+ * The most a judge budget may be when the command runs from a host's hook.
+ *
+ * Claude Code documents that a hook reaching its own timeout lets the command
+ * run, and Codex documents no rule; so a budget longer than the hook's timeout
+ * would let a push through with no verdict and no line saying so, which is the
+ * one thing block mode exists to prevent. Login checks and the risk ranking can
+ * spend about ninety seconds before the budget starts, so the cap sits well
+ * under the hook timeout. The hook canary of 29 September 2026 found the gap.
+ */
+export const HOOK_BUDGET_CAP_SECONDS = 600;
+export const GIT_HOOK_MARKER = "# Installed by: balladeer judge --install-hook git";
+/** The budget a run may spend: as configured, except from a hook, where the host's timeout rules. */
+export function effectiveBudgetSeconds(configured, fromHook) {
+    return fromHook ? Math.min(configured, HOOK_BUDGET_CAP_SECONDS) : configured;
+}
+export function judgeHookCommand(host) {
+    return `balladeer judge --hook ${host}`;
+}
+function expectedEntry(host) {
+    return {
+        matcher: "Bash",
+        hooks: [
+            {
+                type: "command",
+                command: judgeHookCommand(host),
+                timeout: JUDGE_HOOK_TIMEOUT_SECONDS,
+                statusMessage: JUDGE_HOOK_MARKER,
+            },
+        ],
+    };
+}
+export const GIT_PRE_PUSH_SCRIPT = [
+    "#!/bin/sh",
+    GIT_HOOK_MARKER,
+    "# It judges the promises this push could break, on this machine's own coding agent login.",
+    "# In block mode it stops a push whose break was reproduced both ways. Delete this file to remove it.",
+    "command -v balladeer >/dev/null 2>&1 || exit 0",
+    "balladeer judge --hook git",
+    "",
+].join("\n");
+function readOwnFile(path) {
+    if (!existsSync(path)) {
+        try {
+            lstatSync(path);
+        }
+        catch {
+            return undefined;
+        }
+        throw new Error(`${path} is a link to nothing`);
+    }
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`${path} is not a regular file`);
+    if (stat.size > 1024 * 1024)
+        throw new Error(`${path} is larger than this command edits`);
+    return readFileSync(path, "utf8");
+}
+function writeAtomically(path, content, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = join(dirname(path), `.balladeer-judge-${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(temporary, content, { flag: "wx", mode });
+    try {
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Already gone. */
+        }
+        throw error;
+    }
+}
+/**
+ * The PreToolUse entry in a host's JSON hook file, added once.
+ *
+ * The entry this command owns is the one whose handler carries the marker. A
+ * second run finds it and changes nothing, byte for byte. An owned entry that
+ * somebody edited is left alone and reported, the same rule the guidance
+ * installer follows: it is theirs now, and silently putting it back would undo
+ * a decision somebody made on purpose.
+ */
+function installJsonHook(root, host) {
+    const relativePath = host === "claude" ? ".claude/settings.json" : ".codex/hooks.json";
+    const path = join(root, relativePath);
+    try {
+        const before = readOwnFile(path);
+        const document = before === undefined ? {} : JSON.parse(before);
+        if (document === null || typeof document !== "object" || Array.isArray(document))
+            return {
+                target: host,
+                path: relativePath,
+                status: "refused",
+                reason: `${relativePath} is not a JSON object`,
+            };
+        const settings = document;
+        const hooks = settings.hooks === undefined ? {} : settings.hooks;
+        if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
+            return {
+                target: host,
+                path: relativePath,
+                status: "refused",
+                reason: `hooks in ${relativePath} is not an object`,
+            };
+        const events = hooks;
+        const rows = events.PreToolUse === undefined ? [] : events.PreToolUse;
+        if (!Array.isArray(rows))
+            return {
+                target: host,
+                path: relativePath,
+                status: "refused",
+                reason: `hooks.PreToolUse in ${relativePath} is not a list`,
+            };
+        const own = rows.filter((row) => Array.isArray(row?.hooks)
+            ? row.hooks.some((handler) => handler?.statusMessage === JUDGE_HOOK_MARKER)
+            : false);
+        const expected = expectedEntry(host);
+        if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
+            return { target: host, path: relativePath, status: "unchanged" };
+        if (own.length > 0)
+            return {
+                target: host,
+                path: relativePath,
+                status: "refused",
+                reason: `${relativePath} already has a Balladeer judge entry that was edited by hand, so it was left as it is. Remove it to have this command write the current one.`,
+            };
+        events.PreToolUse = [...rows, expected];
+        settings.hooks = events;
+        const mode = before === undefined ? 0o644 : lstatSync(path).mode & 0o777;
+        writeAtomically(path, `${JSON.stringify(settings, null, 2)}\n`, mode);
+        return { target: host, path: relativePath, status: "written" };
+    }
+    catch (error) {
+        return {
+            target: host,
+            path: relativePath,
+            status: "refused",
+            reason: error instanceof SyntaxError
+                ? `${relativePath} is not valid JSON`
+                : error instanceof Error
+                    ? error.message
+                    : String(error),
+        };
+    }
+}
+/** Where git looks for hooks in this checkout, which is not `.git/hooks` in a worktree. */
+export function gitHooksDirectory(root) {
+    try {
+        const answer = execFileSync("git", ["-C", root, "rev-parse", "--git-path", "hooks"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        }).trim();
+        if (answer)
+            return isAbsolute(answer) ? answer : join(root, answer);
+    }
+    catch {
+        /* Fall through to the ordinary place. */
+    }
+    return join(root, ".git", "hooks");
+}
+function installGitHook(root) {
+    const directory = gitHooksDirectory(root);
+    const path = join(directory, "pre-push");
+    const shown = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+    try {
+        const before = readOwnFile(path);
+        if (before === GIT_PRE_PUSH_SCRIPT)
+            return { target: "git", path: shown, status: "unchanged" };
+        if (before !== undefined)
+            return {
+                target: "git",
+                path: shown,
+                status: "refused",
+                reason: before.includes(GIT_HOOK_MARKER)
+                    ? `${shown} was installed by this command and edited since, so it was left as it is.`
+                    : `${shown} already exists and is not Balladeer's, so nothing was written. Add this line to it yourself: balladeer judge --hook git`,
+            };
+        writeAtomically(path, GIT_PRE_PUSH_SCRIPT, 0o755);
+        chmodSync(path, 0o755);
+        return { target: "git", path: shown, status: "written" };
+    }
+    catch (error) {
+        return {
+            target: "git",
+            path: shown,
+            status: "refused",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Install the judge hook for one host. Running it twice changes nothing the second time. */
+export function installJudgeHook(root, target) {
+    return target === "git" ? installGitHook(root) : installJsonHook(root, target);
+}

package/dist/map-brief.d.ts

@@ -0,0 +1,16 @@
+import type { PromiseDocument } from "./promise-meaning.js";
+/**
+ * The fixed instructions a map builder works from, `map-brief/v1`.
+ *
+ * The map says where one promise's behavior lives, so a later change can be
+ * matched against it cheaply and a judge can start in the right place. It is
+ * built once per promise, from the code, by the person's own agent, in a
+ * disposable read-only checkout, and it never leaves the machine. The runner
+ * fills in the fields it owns (the promise id, the digest, when and on what
+ * commit it was mapped, and the meaning excerpt) and checks the rest against
+ * the contract before anything is written.
+ */
+export declare const MAP_BRIEF_REVISION = "map-brief/v1";
+export declare const MAP_BRIEF = "You are mapping where one promise's behavior lives in this repository. A named person agreed the promise's meaning; it is below. Your working directory is a disposable copy of the repository at its current commit. Read only: anything you write here is thrown away.\n\nFind, by reading and searching the code:\n\n1. entryPoints: where the behavior starts, such as a route handler, a command, a UI action, a scheduled job or an event handler. kind is one of route, command, ui, job, event, function. note is one short phrase or \"\".\n2. symbols: the specific functions, classes, methods, constants, types or modules on the path from those entry points to the outcome. role is core for the ones that decide the outcome and supporting for the ones it passes through. kind is one of function, class, method, const, type, module. Name each symbol exactly as it is spelled in its file, because a later check searches the file for that name. Prefer specific symbols over whole modules.\n3. resources: what the behavior depends on outside the code: tables, columns, routes, feature flags, environment keys, queues, events, outbound calls, files, configuration. kind is one of table, column, route, flag, env, queue, event, outbound, file, config; access is one of read, write, both, call.\n4. linkedTests: search the test suite for tests that exercise this behavior. For each, give the test file, the test's own name as written in the file, and which passing cases it covers (passing-1, passing-2, in the order the meaning lists them). Only tests that exist; an empty list is a fine answer.\n5. sinks: for each failing case (failing-1, failing-2, in order), the effect that must not happen, the resources where it would happen, and the symbols where it would happen, written as path#symbol.\n6. confidence: a number from 0 to 1 for how sure you are that this map points at the code that decides the behavior.\n7. notes: anything a later reader needs, in at most three sentences, or \"\".\n8. meaning: copy this excerpt of the promise verbatim: title, observableOutcome, nonGoals, and failingExamples as {\"id\": \"failing-1\", \"text\": \"...\"}.\n\nPaths are relative to the repository root, with forward slashes. Every path must exist. Keep the map small: at most 20 entry points, 60 symbols, 40 resources, 20 linked tests.\n\nDo not push, publish or change anything outside this copy. Do not read or print credentials.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"entryPoints\": [{\"file\": \"\", \"symbol\": \"\", \"kind\": \"function\", \"note\": \"\"}], \"symbols\": [{\"file\": \"\", \"name\": \"\", \"kind\": \"function\", \"role\": \"core\"}], \"resources\": [{\"kind\": \"table\", \"name\": \"\", \"access\": \"read\"}], \"linkedTests\": [{\"file\": \"\", \"name\": \"\", \"cases\": [\"passing-1\"]}], \"sinks\": [{\"caseId\": \"failing-1\", \"effect\": \"\", \"resources\": [], \"symbols\": [\"path#symbol\"]}], \"confidence\": 0.5, \"notes\": \"\", \"meaning\": {\"title\": \"\", \"observableOutcome\": \"\", \"failingExamples\": [{\"id\": \"failing-1\", \"text\": \"\"}], \"nonGoals\": []}}";
+/** The brief plus the promise, as the prompt the agent receives. */
+export declare function mapPrompt(promise: PromiseDocument): string;