balladeer 1.0.15 → 1.0.17

package/dist/commands/judge.d.ts

@@ -0,0 +1,430 @@
+import { type BehaviorMap } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type HookHost, type MergeTarget } from "../judge-hook.js";
+import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+import { type CarriedFile } from "../scratch-worktree.js";
+import type { Features } from "../risk/contract.js";
+/**
+ * `balladeer judge`: for a change about to leave this machine, ask the person's
+ * own coding agent, one promise at a time, whether the change keeps it.
+ *
+ * A verdict is only as good as its evidence, so the runner does not take a
+ * judge's word for a break. A judge that says "broken" must hand back a command,
+ * and the runner runs that command itself, once at head and once in a clean
+ * checkout of base: it must fail with the change and pass without it. Anything
+ * short of that is "could not tell", with the reason kept. Nothing here ever
+ * says a promise is protected; a judge's "kept" is a local reading of one
+ * change, not a check that holds.
+ */
+export declare const JUDGE_VERDICT_SCHEMA_VERSION = "balladeer-judge-verdict/v1";
+export declare const JUDGE_CONFIG_SCHEMA_VERSION = "balladeer-judge-config/v1";
+export declare const JUDGE_CONFIG_PATH = ".continuity/judge.json";
+export declare const JUDGE_LOG_DIRECTORY = ".continuity/judge-log";
+/**
+ * Where a verified reproduction's files are kept, one folder per promise and
+ * pushed commit, inside the judge log so git ignores them like the log itself.
+ */
+export declare const KEPT_REPRODUCTIONS_DIRECTORY = ".continuity/judge-log/reproductions";
+export declare const KEPT_REPRODUCTION_SCHEMA_VERSION = "balladeer-kept-reproduction/v1";
+export declare const STILL_JUDGING = "still judging; rerun `balladeer judge --wait`";
+/** Block mode's answer to a line that commits and then pushes: the check runs before the line. */
+export declare const COMMIT_THEN_PUSH = "Held: this command makes a commit and then pushes it, and the check runs before the command, so it cannot see a commit that has not been made yet. Commit first, then push in a separate command.";
+export type JudgeConfig = Readonly<{
+    schemaVersion: typeof JUDGE_CONFIG_SCHEMA_VERSION;
+    mode: "report" | "block";
+    topK: number;
+    concurrency: number;
+    budgetSeconds: number;
+    sampleBelowLine: number;
+    alwaysJudge: readonly string[];
+    client: HeadlessClient | "auto";
+    /**
+     * Which promises the risk report hands to a judge: "direct" (the default)
+     * takes every promise whose own code or tests the change edits, and nothing
+     * else; "ranked" takes the top `topK` in the report's order plus a random
+     * sample below that line.
+     */
+    select: "direct" | "ranked";
+    /**
+     * From the push hook, also read the change for rules no promise records and
+     * hand at most three to the pushing session as offers. Off unless set.
+     */
+    offers: boolean;
+    /**
+     * Which pushes are read when offers are on: only those that repair
+     * something ("fixes", the default), or every change ("all").
+     */
+    offersOn: "fixes" | "all";
+    /** How many offers one push may hand to the person: one by default, three at most. */
+    maxOffers: number;
+}>;
+export declare const DEFAULT_JUDGE_CONFIG: JudgeConfig;
+/**
+ * `.continuity/judge.json`, with the contract's defaults for anything absent.
+ * A field that is present and wrong keeps its default and is named, so a typo
+ * in a team's config is visible rather than quietly ignored.
+ */
+export declare function readJudgeConfig(root: string): {
+    config: JudgeConfig;
+    problems: string[];
+};
+export type JudgeVerdict = {
+    schemaVersion: typeof JUDGE_VERDICT_SCHEMA_VERSION;
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+    verdict: "kept" | "broken" | "could_not_tell";
+    reproduction: {
+        command: string;
+        cwd: string;
+        failsOnHead: boolean;
+        passesOnBase: boolean;
+        digest: string;
+        /**
+         * Where the reproduction was kept on this machine, repository-relative:
+         * a folder holding `manifest.json` and, under `files/`, the files the
+         * judge added, at the paths it wrote them. Only for a break verified both
+         * ways, and absent when keeping it failed.
+         */
+        keptIn?: string;
+        /** The kept files' repository-relative paths, each under `<keptIn>/files/`. */
+        keptFiles?: string[];
+    } | null;
+    reproductionRejected: string | null;
+    exercisedCases: string[];
+    notes: string;
+    /**
+     * On a could-not-tell the judge itself reached because the tests need
+     * something this machine lacks: the one step that would let them run, as
+     * the judge wrote it. Absent otherwise. It never changes the verdict.
+     */
+    nextStep?: string;
+    judge: {
+        client: HeadlessClient;
+        model: string;
+        durationMs: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+    briefRevision: string;
+    mapUsed: boolean;
+    linkedTestRun: {
+        file: string;
+        outcome: "pass" | "fail" | "error" | "none";
+    };
+};
+/** A command's exit, as one run of a reproduction or a linked test. */
+export type CommandRun = Readonly<{
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    output: string;
+}>;
+export declare function runShell(command: string, cwd: string, options: Readonly<{
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}>): Promise<CommandRun>;
+export type ReproductionCheck = Readonly<{
+    failsOnHead: boolean;
+    passesOnBase: boolean;
+    digest: string;
+    rejected: string | null;
+    /** The budget ran out while it was being run, so there is no answer yet. */
+    stopped: boolean;
+    /** The files the judge added, carried to base and fingerprinted into `digest`. */
+    files: readonly CarriedFile[];
+}>;
+/**
+ * Run a judge's reproduction both ways.
+ *
+ * At head, in the judge's own checkout, reset to head so a judge that left it
+ * on base cannot fool the check. At base, in a fresh checkout of base, with the
+ * files the judge added carried across so a new test exists on both sides. It
+ * must exit non-zero at head and zero at base; either disagreeing rejects it,
+ * and the reason says which.
+ */
+export declare function verifyReproduction(input: Readonly<{
+    root: string;
+    headTree: string;
+    head: string;
+    base: string;
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+}>): Promise<ReproductionCheck>;
+export type KeptReproduction = Readonly<{
+    /** Repository-relative, forward slashes: the folder under the judge log. */
+    keptIn: string;
+    /** The files kept, repository-relative, each at `<keptIn>/files/<path>`. */
+    files: string[];
+}>;
+/**
+ * Keep a verified reproduction on this machine, so the break can become a
+ * lasting test instead of vanishing with the judge's checkout.
+ *
+ * The files the judge added are copied from its checkout into
+ * `.continuity/judge-log/reproductions/<promise id>-<first 12 of head>/files/`
+ * at the paths the judge wrote them, beside a `manifest.json` that says which
+ * promise, meaning and change they reproduce a break of, with the command,
+ * its cwd, the digest and each file's own fingerprint. The digest can be
+ * recomputed from the manifest alone. A reproduction that added no files
+ * keeps just the manifest. The judge log carries its own `.gitignore`, so
+ * nothing here is ever committed, and nothing here is sent anywhere.
+ *
+ * The folder is written beside its final name and then renamed into place,
+ * replacing an earlier one for the same promise and commit, so a reader never
+ * sees half of one. Keeping is a courtesy to the person, never a condition of
+ * the verdict: when it fails, the verdict stands and says nothing was kept.
+ */
+export declare function keepReproduction(input: Readonly<{
+    root: string;
+    headTree: string;
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+    command: string;
+    cwd: string;
+    digest: string;
+    files: readonly CarriedFile[];
+}>): KeptReproduction | undefined;
+/**
+ * How this repository runs one test file, when it can be told from the files
+ * alone. A runner that cannot be told is `none`, and the judge is left to find
+ * its own way.
+ */
+export declare function linkedTestCommand(tree: string, file: string): string | undefined;
+type JudgeAnswer = Readonly<{
+    verdict: JudgeVerdict["verdict"];
+    reproduction?: Readonly<{
+        command: string;
+        cwd: string;
+    }>;
+    exercisedCases: string[];
+    notes: string;
+    nextStep?: string;
+}>;
+/** The longest `nextStep` kept from a judge's answer, in characters. */
+export declare const NEXT_STEP_LIMIT = 500;
+/** The judge's final JSON, read strictly enough that a malformed answer is not a verdict. */
+export declare function readJudgeAnswer(json: Record<string, unknown> | undefined): JudgeAnswer | undefined;
+export type JudgePromiseInput = Readonly<{
+    root: string;
+    promise: PromiseDocument;
+    map?: BehaviorMap;
+    base: string;
+    head: string;
+    changedFiles: readonly string[];
+    login: LoginCheck;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type JudgeOutcome = Readonly<{
+    status: "judged";
+    verdict: JudgeVerdict;
+}> | Readonly<{
+    status: "stopped";
+}> | Readonly<{
+    status: "not_judged";
+    reason: string;
+}>;
+/**
+ * One promise judged against one change, with its reproduction verified.
+ *
+ * Returns `stopped` when the caller's budget ran out first, which is not a
+ * verdict and is never logged as one: the push is either held or told the
+ * judge is still running, never let through as if it had been judged.
+ */
+export declare function judgePromise(input: JudgePromiseInput): Promise<JudgeOutcome>;
+export type JudgeArguments = Readonly<{
+    promises?: readonly string[];
+    topK?: number;
+    base?: string;
+    head?: string;
+    json: boolean;
+    mode?: "report" | "block";
+    wait: boolean;
+    hook?: HookHost;
+    /** Run by the entry setup writes at the host's user scope, which stands aside where it has nothing to do. */
+    userScope?: true;
+    /** Turn this laptop's user-scope push check on or off. */
+    pushCheck?: "on" | "off";
+    installHook?: HookHost | "agents";
+    fromFile?: string;
+    map?: string;
+    repo?: string;
+    client?: HeadlessClient | "auto";
+    repository?: string;
+    controlPlane: string;
+}>;
+export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n                  [--push-check on|off]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      from `balladeer risk`: every promise whose own code or tests the\n      change edits, or with \"select\": \"ranked\" in .continuity/judge.json the\n      top of its ranking and a small random sample; else every mapped\n      promise; plus that file's alwaysJudge. Verdicts are kept in\n      .continuity/judge-log/, which git ignores. --install-hook adds the push\n      hook to .claude/settings.json and .codex/hooks.json, before and after\n      each shell command: report mode judges after a push has landed, so the\n      push never waits, and block mode judges before it. With git it writes\n      .git/hooks/pre-push, which judges before the push in both modes. With\n      \"offers\": true in .continuity/judge.json, the push hook also reads the\n      change for rules no promise records and offers at most three to\n      whoever is pushing; it records nothing and never holds a push (see\n      `balladeer offers`). Setup also writes the same pair of entries at\n      each host's user scope, running `judge --hook <host> --user-scope`,\n      so the check runs in every connected repository with mapped promises\n      and says nothing anywhere else; a checkout with its own entry keeps\n      the check to that entry. --push-check off turns the user-scope check\n      off on this laptop, and --push-check on turns it back on.\n";
+export declare function parseJudgeArguments(argv: readonly string[]): JudgeArguments;
+/**
+ * The subset of `balladeer-risk/v1` this command reads: enough to order the
+ * entries the way `balladeer risk` does. An entry without `features` reads as
+ * reaching its promise not at all, and one without `evidence` as none.
+ */
+export type RiskEntry = Readonly<{
+    promiseId: string;
+    score: number;
+    band: string;
+    features?: Features;
+    /** The total weight of the entry's reasons. */
+    evidence?: number;
+}>;
+/** Read a risk report out of whatever `balladeer risk --json` printed. */
+export declare function readRiskOutput(stdout: string): RiskEntry[] | undefined;
+/**
+ * The commit a change is measured from: the fork point with the remote default
+ * branch, else with this branch's upstream, else the parent of head.
+ */
+export declare function defaultBase(root: string, head: string): Promise<string | undefined>;
+export declare function changedFiles(root: string, base: string, head: string): Promise<string[]>;
+export type Selection = Readonly<{
+    promiseId: string;
+    why: "file" | "named" | "risk" | "sample" | "mapped" | "always";
+}>;
+/**
+ * Which promises to judge: named ones, else from the risk report, else every
+ * mapped promise; then `alwaysJudge`.
+ *
+ * From the risk report, in the order `balladeer risk` lists it (how directly
+ * the change reaches each promise, then score, then evidence, then id; a score
+ * alone ties at 1 and falls to the alphabet):
+ *
+ * - "direct" takes every promise whose own code or tests the change edits
+ *   (directness tier 3), and nothing else. The first live evaluation found
+ *   that this selects about 1.8 promises a change and included the broken one
+ *   in 17 of 17 cases. Only a `--top` given by hand caps it.
+ * - "ranked" takes the top k with a score above zero, plus a random sample
+ *   below that line. The sample is what keeps a ranking honest: a break found
+ *   below the line is a miss the ranking made, counted rather than never seen.
+ */
+export declare function selectPromises(input: Readonly<{
+    named?: readonly string[];
+    risk?: readonly RiskEntry[];
+    mapped: readonly string[];
+    config: JudgeConfig;
+    topK?: number;
+    random: () => number;
+}>): Selection[];
+/**
+ * Append verdicts to today's log. The directory carries its own `.gitignore`,
+ * so a verdict log never lands in a commit whatever the repository ignores.
+ */
+export declare function appendVerdicts(root: string, verdicts: readonly JudgeVerdict[], now: Date): void;
+/** A verdict already reached for exactly this promise, meaning, change and brief. */
+export declare function findLoggedVerdict(root: string, key: Readonly<{
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+}>, now: Date): JudgeVerdict | undefined;
+/** Said after "fix the behavior": a deliberate change is the person's, and the promise its owner's. */
+export declare const DELIBERATE_CHANGE = "If the person changed this behavior on purpose, do not undo their change: tell them it breaks this promise, whose meaning only its owner can change.";
+export type VerdictLineContext = Readonly<{
+    /** The verdict was reached earlier for this same commit and read back from the log. */
+    reused?: boolean;
+    /**
+     * Whether the promise has a Balladeer check bound, as its connection said.
+     * Absent when that is unknown (a promise from a file or a map's excerpt),
+     * and then the line says nothing about a check rather than guessing.
+     */
+    checkBound?: boolean;
+}>;
+/**
+ * What to do after a reproduced break, as one line an agent reads in order:
+ * where the test that shows it is kept, fix the behavior rather than the
+ * test, then make the break a lasting check in this repository's own tests,
+ * committed with the fix and linked to the promise's map, and tell the person
+ * in one line what was added. When the promise's own Balladeer check missed
+ * the break, a repair of that check is proposed to its owner as well.
+ */
+export declare function afterBreakLine(verdict: JudgeVerdict, checkBound?: boolean): string;
+/**
+ * The verdict as it may be told now: a reproduction said to be kept whose
+ * folder is no longer on this machine (a verdict read back from the log after
+ * somebody cleared it) loses its kept fields, so the line never points at a
+ * file that is not there.
+ */
+export declare function stillKept(root: string, verdict: JudgeVerdict): JudgeVerdict;
+/**
+ * One line per verdict, the promise named by its title and id. A broken one
+ * carries a second, indented line saying what to do next.
+ */
+export declare function verdictLine(verdict: JudgeVerdict, title: string, context?: VerdictLineContext): string;
+export type JudgeDependencies = Readonly<{
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    resolveLogin?: (requested: HeadlessClient | "auto", prefer?: HeadlessClient) => Promise<LoginCheck | undefined>;
+    riskReport?: (root: string, base: string, head: string) => Promise<readonly RiskEntry[] | undefined>;
+    /** `null` means "no connection", without trying to find one. */
+    reader?: PromiseReader | null;
+    random?: () => number;
+    now?: () => Date;
+    stdin?: () => Promise<string>;
+    scratch?: string;
+    /** Replaces the judge itself, for tests of the flow around it. */
+    judge?: (input: JudgePromiseInput) => Promise<JudgeOutcome>;
+    /** The agent run that reads the change for offers, when they are on. */
+    offerAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** The head commit of the pull request a `gh pr merge` names. */
+    pullRequestHead?: (root: string, target: MergeTarget) => Promise<string | undefined>;
+    /** Whether this laptop has a connection for the checkout, read locally. */
+    connected?: (root: string) => boolean;
+}>;
+/** Said instead of verdicts when the check cannot tell which repository a push leaves from. */
+export declare const PUSH_REPOSITORY_UNKNOWN = "Balladeer judge: this push was not judged, because the check could not tell which repository it pushes.";
+/** Said instead of verdicts when every pull request the command opens or merges is in another repository. */
+export declare function pullRequestElsewhereLine(repo: string): string;
+export type JudgeRunOptions = Readonly<{
+    args: JudgeArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+    deps?: JudgeDependencies;
+}>;
+/** What `--push-check off` and `--push-check on` say. */
+export declare const PUSH_CHECK_OFF_LINE = "The push check is off on this laptop: after a push it now says nothing, in every repository. A repository's own entry from `balladeer judge --install-hook` still runs. Turn it back on with `balladeer judge --push-check on`.";
+export declare const PUSH_CHECK_ON_LINE = "The push check is back on for this laptop: after a push in a connected repository whose promises have behavior maps, it reports what the push may have broken, and it never holds the push.";
+/**
+ * Whether the push check's user-scope entry has this push to itself, decided
+ * before anything is started or fetched: the entry runs on every shell command
+ * in every folder on the laptop, and most folders have nothing to judge. It
+ * stands aside, saying nothing, when the laptop turned the check off, the
+ * folder is in no checkout, the checkout has the push check's own project
+ * entry for this host (that entry owns the check there, so a push is judged
+ * once), or no promise here has a behavior map. Only then is the connection
+ * looked for, which reads the checkout's remotes, and a checkout this laptop
+ * has not connected is left alone too.
+ */
+export declare function userScopeTakesThePush(input: {
+    cwd: string;
+    host: "claude" | "codex";
+    environment: NodeJS.ProcessEnv;
+    connected: (root: string) => boolean;
+}): boolean;
+/** `balladeer judge`, from arguments already parsed. */
+/**
+ * The line an answer opens with when the command makes a commit before it
+ * pushes. Robert approved it on 30 September 2026: the check keeps running
+ * before the push, and says plainly that it did not see the commit.
+ */
+export declare function commitFirstLine(made: string): string;
+export declare function runJudge(options: JudgeRunOptions): Promise<number>;
+/** `balladeer judge ...` from raw arguments, as `cli.ts` hands them over. */
+export declare function judgeCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;
+export {};