balladeer 1.0.16 → 1.0.18

package/dist/commands/judge.d.ts

@@ -1,7 +1,13 @@
+import type { AnchorBudget } from "../anchor-budget.js";
+import type { AnchorsClient } from "../anchors-client.js";
 import { type BehaviorMap } from "../behavior-map-schema.js";
 import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
-import { type HookHost } from "../judge-hook.js";
+import { type HookHost, type MergeTarget } from "../judge-hook.js";
 import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+import type { RepositoryGraph } from "../risk/graph-cache.js";
+import { type CarriedFile } from "../scratch-worktree.js";
+import type { Features } from "../risk/contract.js";
+import type { AnchorStage, JudgeAnchors } from "./anchor.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.
@@ -18,7 +24,15 @@ 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";
@@ -28,6 +42,13 @@ export type JudgeConfig = Readonly<{
     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.
@@ -64,10 +85,25 @@ export type JudgeVerdict = {
         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;
@@ -77,6 +113,8 @@ export type JudgeVerdict = {
     };
     briefRevision: string;
     mapUsed: boolean;
+    /** The judge was handed the promise's anchors and their neighborhood, where it had no map. */
+    anchorsUsed?: boolean;
     linkedTestRun: {
         file: string;
         outcome: "pass" | "fail" | "error" | "none";
@@ -101,6 +139,8 @@ export type ReproductionCheck = Readonly<{
     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.
@@ -123,6 +163,42 @@ export declare function verifyReproduction(input: Readonly<{
     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
@@ -137,13 +213,19 @@ type JudgeAnswer = Readonly<{
     }>;
     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 { JudgeAnchors } from "./anchor.js";
 export type JudgePromiseInput = Readonly<{
     root: string;
     promise: PromiseDocument;
     map?: BehaviorMap;
+    /** Handed only when there is no map. */
+    anchors?: JudgeAnchors;
     base: string;
     head: string;
     changedFiles: readonly string[];
@@ -180,6 +262,10 @@ export type JudgeArguments = Readonly<{
     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;
@@ -188,13 +274,20 @@ export type JudgeArguments = Readonly<{
     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      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      the top of `balladeer risk`, else every mapped promise, plus\n      .continuity/judge.json's alwaysJudge and a small random sample. Verdicts\n      are kept in .continuity/judge-log/, which git ignores. --install-hook\n      adds the push hook to .claude/settings.json and .codex/hooks.json, or\n      .git/hooks/pre-push with git. With \"offers\": true in that file, the push\n      hook also reads the change for rules no promise records and offers at\n      most three to whoever is pushing; it records nothing and never holds a\n      push (see `balladeer offers`).\n";
+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      every agreed promise whose anchored code the change edits, and every\n      promise with a behavior map whose own code or tests it edits (with\n      \"select\": \"ranked\" in .continuity/judge.json, the top of the maps'\n      ranking and a small random sample); plus that file's alwaysJudge. A\n      promise with no anchors yet is anchored first, by one small call on\n      your own login (see `balladeer anchor`), at most 20 a day on this\n      laptop, and a line says what that cost. 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 agreed 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. */
+/**
+ * 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;
@@ -206,18 +299,39 @@ export declare function defaultBase(root: string, head: string): Promise<string
 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";
+    why: "file" | "named" | "risk" | "anchored" | "sample" | "mapped" | "always";
 }>;
 /**
- * Which promises to judge: named ones, else the top of the risk report plus a
- * random sample below its line, else every mapped promise; then `alwaysJudge`.
- * The sample is what keeps the ranking honest: a break found below the line is
- * a miss the ranking made, counted rather than never seen.
+ * Which promises to judge: named ones; else the promises the change selects
+ * by their anchors and by their maps; then `alwaysJudge`.
+ *
+ * By anchors (`anchored`, chosen before this from the files the change edits):
+ * every promise one of whose anchor files (an entry point's or a symbol's
+ * file) the change edits, with no widening by import distance. The
+ * measurement of 1 October 2026 found that widening multiplied the promises
+ * selected and caught nothing more.
+ *
+ * By maps, 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 mapped promise whose own code or tests the change
+ *   edits (directness tier 3), and nothing else. Only a `--top` given by hand
+ *   caps it, and it caps anchored and mapped promises together.
+ * - "ranked" takes the top k mapped promises 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. Anchored promises are taken too, before the sample.
+ *
+ * Without a risk report, every mapped promise. Anchored and mapped promises
+ * are listed together in the report's order, and one the report does not
+ * list comes after those it does.
  */
 export declare function selectPromises(input: Readonly<{
     named?: readonly string[];
     risk?: readonly RiskEntry[];
     mapped: readonly string[];
+    anchored?: readonly string[];
     config: JudgeConfig;
     topK?: number;
     random: () => number;
@@ -234,14 +348,55 @@ export declare function findLoggedVerdict(root: string, key: Readonly<{
     base: string;
     head: string;
 }>, now: Date): JudgeVerdict | undefined;
-/** One line per verdict, the promise named by its title and id. */
-export declare function verdictLine(verdict: JudgeVerdict, title: string, reused?: boolean): string;
+/** 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>;
+    riskReport?: (root: string, base: string, head: string, 
+    /** The maps in use and, in a map's shape, the anchors of the promises they select. */
+    maps: readonly BehaviorMap[]) => Promise<readonly RiskEntry[] | undefined>;
     /** `null` means "no connection", without trying to find one. */
     reader?: PromiseReader | null;
+    /** The anchors route; `null` means none, without trying to find one. */
+    anchors?: AnchorsClient | null;
+    /** The anchoring call, when it is not the person's own agent. */
+    anchorAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** The repository graph at a commit, when it is not built from this laptop's cache. */
+    graph?: (root: string, head: string) => RepositoryGraph;
+    /** Today's anchoring budget, when it is not this laptop's own. */
+    anchorBudget?: AnchorBudget;
     random?: () => number;
     now?: () => Date;
     stdin?: () => Promise<string>;
@@ -250,7 +405,15 @@ export type JudgeDependencies = Readonly<{
     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;
@@ -259,7 +422,52 @@ export type JudgeRunOptions = Readonly<{
     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 with agreed promises, 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, or 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). 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.
+ *
+ * A connected checkout is not left alone for having no behavior map: since
+ * promise anchors (approved 30 September 2026), its agreed promises are
+ * anchored and checked without one. Whether it has any agreed promise is the
+ * server's to say, after the push, and with none (and no map) the entry still
+ * says nothing.
+ */
+export declare function userScopeTakesThePush(input: {
+    cwd: string;
+    host: "claude" | "codex";
+    environment: NodeJS.ProcessEnv;
+    connected: (root: string) => boolean;
+}): boolean;
+/**
+ * The one line said when nothing was selected, and its code: no agreed
+ * promise here; nothing anchored or mapped (with why, when the anchors could
+ * not be read); or nothing the change touches.
+ */
+export declare function nothingSelected(input: Readonly<{
+    stage: AnchorStage | undefined;
+    maps: number;
+    anchors: number;
+    push: boolean;
+}>): {
+    reason: string;
+    message: string;
+};
 /** `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<{
@@ -268,4 +476,3 @@ export declare function judgeCommand(argv: readonly string[], io: Readonly<{
     write: (text: string) => void;
     error: (text: string) => void;
 }>): Promise<number>;
-export {};