@wildorder/nightshift 0.8.0 → 0.9.0

package/dist/run-program.d.ts

@@ -1,10 +1,11 @@
 import { type AgentRunner, type VerifyRunner } from "./agent-runner.js";
 import { type AuthorStageResult } from "./author.js";
-import type { NightshiftConfig } from "./config.js";
+import type { AgentConfig, NightshiftConfig } from "./config.js";
 import { type DecisionLedgerView } from "./decision-ledger.js";
 import { type RenderableRecord } from "./decision-view.js";
 import { type ReviewPassOutcome } from "./review-pass.js";
 import { type ProgramManifest, type Workstream } from "./manifest.js";
+import { type AsBuiltFs, type WholeProgramReviewOutcome } from "./whole-program-review.js";
 /**
  * Git operations the runner needs, injectable so tests drive a real
  * temporary repository or a fake. The runner owns commits — workstream
@@ -32,6 +33,8 @@ export interface GitOps {
     dirtyPaths(cwd: string): Promise<string[]>;
     /** True when `ancestor` is an ancestor of (or equal to) `descendant`. */
     isAncestor(cwd: string, ancestor: string, descendant: string): Promise<boolean>;
+    /** `git merge-base <a> <b>`; undefined when they share no ancestor or either is unknown. */
+    mergeBase(cwd: string, a: string, b: string): Promise<string | undefined>;
     /** Moves the current branch to `commit`, discarding the working tree. */
     resetHard(cwd: string, commit: string): Promise<void>;
     /** Points `ref` at `commit`, creating or moving it. */
@@ -95,6 +98,8 @@ export interface RunProgramResult {
      *  same set the run report's "Needs your attention" section renders. */
     escalations: RenderableRecord[];
     reportPath: string;
+    /** The end-of-run whole-program review stage's result, for a caller that wants the snapshot commit. */
+    wholeProgramReview?: WholeProgramStageResult;
 }
 /** Every workstream in the transitive downstream cone of the given ids. */
 export declare function downstreamCone(workstreams: readonly Workstream[], rootIds: readonly string[]): Set<string>;
@@ -109,6 +114,65 @@ export declare function downstreamCone(workstreams: readonly Workstream[], rootI
  * verify commands itself, and writes the run report last, whatever happened.
  */
 export declare function runProgram(options: RunProgramOptions): Promise<RunProgramResult>;
+/**
+ * Resolves the program's diff base for the whole-program review: the
+ * merge-base with the default branch, when it exists and differs from HEAD
+ * (the program's real branch point — the same range a pull request shows a
+ * human); otherwise `runStartCommit`, when it differs from HEAD (a
+ * `--force` run made directly on the default branch, where the merge-base is
+ * HEAD itself); otherwise `undefined` — an ordinary outcome, not a failure.
+ */
+export declare function resolveProgramDiffBase(args: {
+    root: string;
+    git: GitOps;
+    isRepository: boolean;
+    /** HEAD as it stood before the run's first agent ran. */
+    runStartCommit: string | undefined;
+}): Promise<string | undefined>;
+/** The synthetic workstream id whole-program findings are journaled under (SC-07). */
+export declare const WHOLE_PROGRAM_SUBJECT = "whole-program";
+export interface WholeProgramStageResult {
+    outcome: WholeProgramReviewOutcome;
+    /** The snapshot commit, when one landed. */
+    commit?: string;
+    /** True when a commit was skipped because the tree is not a git repository. */
+    commitSkipped: boolean;
+    /**
+     * Ledger ids this stage journaled, for the fix-now cross-reference. Empty
+     * when the append failed — these are ids that are *in* the ledger.
+     */
+    findingIds: string[];
+    /** Post-pass failures — commit, ledger append, triage. Reported, never fatal. */
+    errors: string[];
+}
+/**
+ * The end-of-run whole-program review stage: establishes the diff base,
+ * calls WS-01's never-throwing pass exactly once, commits exactly what it
+ * wrote, and routes its findings through the existing findings path. Every
+ * risky step around the pass gets its own catch so a stage failure is a
+ * sentence in the report, never a change to the run's outcome (SC-05,
+ * SC-12) — see the outer catch below for the belt-and-braces case where a
+ * bug in this function's own body throws before the pass has even run.
+ */
+export declare function runWholeProgramStage(args: {
+    root: string;
+    programId: string;
+    manifest: ProgramManifest;
+    config: NightshiftConfig;
+    agentRunner: AgentRunner;
+    git: GitOps;
+    isRepository: boolean;
+    results: WorkstreamResult[];
+    authorResult: AuthorStageResult;
+    runStartCommit: string | undefined;
+    decider: AgentConfig | undefined;
+    reviewed: Set<string>;
+    triaged: Set<string>;
+    now: () => Date;
+    log: (line: string) => void;
+    /** Test seam only; production never sets it. Passed straight to the pass. */
+    fs?: AsBuiltFs;
+}): Promise<WholeProgramStageResult>;
 export interface FixAttempt {
     /** "kept" = the attempt verified clean under the runner's configured
      *  commands; "failed" = it did not. Mirrors the critique loop's existing
@@ -126,5 +190,5 @@ export interface FixAttempt {
     /** The verification diagnosis, present only when `outcome === "failed"`. */
     failure?: string;
 }
-export declare function renderRunReport(manifest: ProgramManifest, results: WorkstreamResult[], ledger: DecisionLedgerView, triagedThisRun: ReadonlySet<string>, authorResult: AuthorStageResult, at: Date): string;
+export declare function renderRunReport(manifest: ProgramManifest, results: WorkstreamResult[], ledger: DecisionLedgerView, triagedThisRun: ReadonlySet<string>, authorResult: AuthorStageResult, at: Date, wholeProgram?: WholeProgramStageResult): string;
 //# sourceMappingURL=run-program.d.ts.map

package/dist/run-program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-program.d.ts","sourceRoot":"","sources":["../src/run-program.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-program.d.ts","sourceRoot":"","sources":["../src/run-program.ts"],"names":[],"mappings":"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"}

package/dist/run-program.js

@@ -17,6 +17,7 @@ import { detectDefaultBranch, programBranchName } from "./program-branch.js";
 import { restoreProgramsDir, snapshotProgramsDir } from "./programs-dir.js";
 import { CouldNotStartError } from "./exit-codes.js";
 import { runReportPath } from "./report-path.js";
+import { AS_BUILT_PATH, runWholeProgramReview, renderWholeProgramReview, } from "./whole-program-review.js";
 const execFileAsync = promisify(execFile);
 /** Matches every wording git uses to report an empty commit attempt. */
 const NOTHING_TO_COMMIT = /nothing to commit|nothing added to commit|no changes added to commit/u;
@@ -111,6 +112,15 @@ export const defaultGitOps = {
             return false;
         }
     },
+    async mergeBase(cwd, a, b) {
+        try {
+            const { stdout } = await execFileAsync("git", ["merge-base", a, b], { cwd });
+            return stdout.trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
     async resetHard(cwd, commit) {
         await execFileAsync("git", ["reset", "--hard", commit], { cwd });
     },
@@ -299,8 +309,8 @@ export async function runProgram(options) {
         ? `decider: ${describeAgent(decider)}`
         : "decider: none configured — implementer defaults will stand unratified");
     log(reviewer
-        ? `test critique reviewer: ${describeAgent(reviewer)}`
-        : "test critique reviewer: none configured — test critique disabled");
+        ? `reviewer (test critique, whole-program review): ${describeAgent(reviewer)}`
+        : "reviewer: none configured — test critique and the whole-program review are disabled");
     const cycles = findCycles(manifest.workstreams);
     if (cycles.length > 0) {
         // A cyclic graph cannot be ordered; this is a planning defect, not a
@@ -356,6 +366,11 @@ export async function runProgram(options) {
             }
         }
     }
+    // HEAD as it stood before the run's first agent ran — the whole-program
+    // review stage's fallback diff base (see resolveProgramDiffBase) when a
+    // resumed run's merge-base with the default branch is unavailable or
+    // equal to HEAD.
+    const runStartCommit = isRepository ? await git.currentCommit(root) : undefined;
     // Subject ids already sent to the decider this run — shared across the
     // authoring and build stages (a run is one process) and across the
     // decision and finding paths, so "once per subject per run" (SC-10) is
@@ -430,23 +445,51 @@ export async function runProgram(options) {
             }
         }
     }
-    const ledger = await readDecisionLedger(root, options.programId);
-    const escalations = escalatedRecords(ledger);
     const complete = results.every((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped");
     manifest.program.status = complete ? "complete" : "partial";
     await saveManifest(root, options.programId, manifest);
+    const wholeProgram = await runWholeProgramStage({
+        root,
+        programId: options.programId,
+        manifest,
+        config,
+        agentRunner,
+        git,
+        isRepository,
+        results,
+        authorResult,
+        runStartCommit,
+        decider,
+        reviewed,
+        triaged,
+        now,
+        log,
+    });
+    const ledger = await readDecisionLedger(root, options.programId);
+    const escalations = escalatedRecords(ledger);
     const reportPath = runReportPath(root, options.programId);
-    await writeFile(reportPath, 
-    // `triaged` is the run-local set of subject ids the decider actually
-    // ruled on this run (built up across the authoring and build stages,
-    // see its declaration above) — exactly the `triagedThisRun` basis the
-    // "this run" triage ratio needs, since the projected ledger carries no
-    // run identifier of its own. It excludes ids that were merely sent but
-    // whose invocation failed or returned no valid verdict.
-    renderRunReport(manifest, results, ledger, triaged, authorResult, now()), "utf8");
-    if (isRepository) {
-        await git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]);
+    // Every workstream verdict, `complete`, and the exit-code mapping are
+    // already settled above; writing and committing the report is bookkeeping
+    // that must not be able to reject `runProgram` after the fact (SC-05,
+    // SC-12) — a full disk or an EISDIR here is a logged line, not a thrown
+    // run.
+    try {
+        await writeFile(reportPath, 
+        // `triaged` is the run-local set of subject ids the decider actually
+        // ruled on this run (built up across the authoring, build, and
+        // whole-program stages, see its declaration above) — exactly the
+        // `triagedThisRun` basis the "this run" triage ratio needs, since the
+        // projected ledger carries no run identifier of its own. It excludes
+        // ids that were merely sent but whose invocation failed or returned no
+        // valid verdict.
+        renderRunReport(manifest, results, ledger, triaged, authorResult, now(), wholeProgram), "utf8");
+        if (isRepository) {
+            await git.commitPaths(root, `nightshift(${options.programId}): run report and decision ledger`, ["docs/programs"]);
+        }
+    }
+    catch (error) {
+        log(`run report: could not write or commit ${reportPath}: ${error.message}`);
     }
     log(`run report: ${reportPath}`);
     return {
@@ -455,6 +498,7 @@ export async function runProgram(options) {
         workstreams: results,
         escalations,
         reportPath,
+        wholeProgramReview: wholeProgram,
     };
     async function runWorkstream(workstream) {
         const base = {
@@ -762,6 +806,192 @@ export async function runProgram(options) {
         return kept ? fix.greenCommit : greenCommit;
     }
 }
+/**
+ * Resolves the program's diff base for the whole-program review: the
+ * merge-base with the default branch, when it exists and differs from HEAD
+ * (the program's real branch point — the same range a pull request shows a
+ * human); otherwise `runStartCommit`, when it differs from HEAD (a
+ * `--force` run made directly on the default branch, where the merge-base is
+ * HEAD itself); otherwise `undefined` — an ordinary outcome, not a failure.
+ */
+export async function resolveProgramDiffBase(args) {
+    const { root, git, isRepository, runStartCommit } = args;
+    if (!isRepository)
+        return undefined;
+    const head = await git.currentCommit(root);
+    if (head === undefined)
+        return undefined;
+    const defaultBranch = await detectDefaultBranch(root);
+    const base = await git.mergeBase(root, defaultBranch, head);
+    if (base !== undefined && base !== head)
+        return base;
+    if (runStartCommit !== undefined && runStartCommit !== head)
+        return runStartCommit;
+    return undefined;
+}
+/** The synthetic workstream id whole-program findings are journaled under (SC-07). */
+export const WHOLE_PROGRAM_SUBJECT = "whole-program";
+function emptyWholeProgramSeverityCounts() {
+    return { blocker: 0, major: 0, minor: 0, advisory: 0 };
+}
+/** The placeholder outcome for the (practically unreachable) case where the stage's own body throws before the pass ever runs. */
+function stageFailureOutcome(reason) {
+    return {
+        ran: false,
+        status: "reviewer-error",
+        refreshed: false,
+        writtenPaths: [],
+        findings: [],
+        errors: [],
+        severityCounts: emptyWholeProgramSeverityCounts(),
+        lengthOverrun: false,
+        missingLimitations: [],
+        inputClipped: false,
+        reason,
+    };
+}
+/** Failed and parked workstreams only (SC-08) — a `skipped` result means already complete, i.e. built. */
+function notBuiltRoster(results, authorResult) {
+    const authorById = new Map(authorResult.results.map((entry) => [entry.id, entry]));
+    const notBuilt = [];
+    for (const result of results) {
+        const outcome = result.outcome;
+        if (outcome.status !== "failed" && outcome.status !== "parked")
+            continue;
+        const authorOutcome = authorById.get(result.id)?.outcome;
+        const reason = authorOutcome !== undefined &&
+            (authorOutcome.status === "failed" || authorOutcome.status === "parked")
+            ? `${outcome.reason} (spec authoring: ${authorOutcome.reason})`
+            : outcome.reason;
+        notBuilt.push({
+            id: result.id,
+            name: result.name,
+            status: outcome.status,
+            reason,
+        });
+    }
+    return notBuilt;
+}
+/**
+ * The end-of-run whole-program review stage: establishes the diff base,
+ * calls WS-01's never-throwing pass exactly once, commits exactly what it
+ * wrote, and routes its findings through the existing findings path. Every
+ * risky step around the pass gets its own catch so a stage failure is a
+ * sentence in the report, never a change to the run's outcome (SC-05,
+ * SC-12) — see the outer catch below for the belt-and-braces case where a
+ * bug in this function's own body throws before the pass has even run.
+ */
+export async function runWholeProgramStage(args) {
+    const { root, programId, manifest, config, agentRunner, git, isRepository, results, authorResult, runStartCommit, decider, reviewed, triaged, now, log, fs, } = args;
+    const errors = [];
+    let commit;
+    let commitSkipped = false;
+    let findingIds = [];
+    let outcome = stageFailureOutcome("the whole-program review stage did not complete");
+    // The caller's log callback is itself a risky step — it is not this
+    // stage's own code and can throw (a full log file, a broken transport).
+    // Both of the stage's own lines go through this wrapper rather than `log`
+    // directly, so a throwing logger costs one sentence in `errors` and never
+    // aborts the commit or the findings routing that follow it.
+    const safeLog = (line) => {
+        try {
+            log(line);
+        }
+        catch (error) {
+            errors.push(`the whole-program review logger failed: ${error.message}`);
+        }
+    };
+    try {
+        safeLog("whole-program review: starting");
+        const base = await resolveProgramDiffBase({ root, git, isRepository, runStartCommit });
+        const diff = base === undefined ? "" : await git.diffSince(root, base);
+        const notBuilt = notBuiltRoster(results, authorResult);
+        const reviewCommit = isRepository ? await git.currentCommit(root) : undefined;
+        outcome = await runWholeProgramReview({
+            root,
+            programId,
+            manifest,
+            config,
+            agentRunner,
+            diff,
+            ...(base === undefined ? {} : { baseCommit: base }),
+            ...(notBuilt.length === 0 ? {} : { notBuilt }),
+            ...(fs === undefined ? {} : { fs }),
+            log,
+        });
+        safeLog(outcome.status === "refreshed"
+            ? `whole-program review: refreshed ${AS_BUILT_PATH}` +
+                (outcome.archivedTo ? ` (archived to ${outcome.archivedTo})` : "")
+            : `whole-program review: ${outcome.status}` +
+                (outcome.reason ? ` — ${outcome.reason}` : ""));
+        if (outcome.writtenPaths.length > 0) {
+            if (isRepository) {
+                try {
+                    commit = await git.commitPaths(root, `nightshift(${programId}): as-built snapshot`, outcome.writtenPaths);
+                }
+                catch (error) {
+                    errors.push(`could not commit the as-built snapshot: ${error.message}`);
+                }
+            }
+            else {
+                commitSkipped = true;
+            }
+        }
+        const events = findingsToLedgerEvents({
+            workstreamId: WHOLE_PROGRAM_SUBJECT,
+            findings: outcome.findings.filter(hasRoutableEvidence),
+            ...(reviewCommit === undefined ? {} : { baseCommit: reviewCommit }),
+            now,
+        });
+        let journaled = false;
+        if (events.length === 0) {
+            journaled = true;
+        }
+        else {
+            try {
+                await appendLedgerEvents(root, programId, events);
+                journaled = true;
+                findingIds = events.map((event) => event.id);
+            }
+            catch (error) {
+                errors.push(`could not journal the whole-program findings: ${error.message}`);
+            }
+        }
+        if (journaled && events.length > 0) {
+            try {
+                await triageFindings({
+                    root,
+                    programId,
+                    manifest,
+                    workstreamId: WHOLE_PROGRAM_SUBJECT,
+                    findings: events,
+                    baseCommit: reviewCommit,
+                    decider,
+                    agentRunner,
+                    git,
+                    isRepository,
+                    reviewed,
+                    triaged,
+                    now,
+                    log,
+                });
+            }
+            catch (error) {
+                errors.push(`the decider failed to triage the whole-program findings: ${error.message}`);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(`the whole-program review stage failed unexpectedly: ${error.message}`);
+    }
+    return {
+        outcome,
+        ...(commit === undefined ? {} : { commit }),
+        commitSkipped,
+        findingIds,
+        errors,
+    };
+}
 /** Undefined means the attempt verified clean; otherwise the diagnosis. */
 async function verifyAttempt(config, verifyRunner, root, agentExitCode) {
     if (agentExitCode !== 0) {
@@ -1173,36 +1403,36 @@ function renderRawFinding(finding, workstreamLabel, sinceFixed) {
     return `- **${finding.subject}** (${finding.severity}, ${workstreamLabel}) — ${finding.message}${suffix}`;
 }
 /**
- * A pass's minor/advisory findings, `open` and `resolved` alike (SC-07's
- * "every ... raised" — a finding the writer fixed was still raised),
- * deduped within the pass's own union so a finding present in both (should
- * WS-02's own dedup ever let that happen) is not double-listed.
+ * Minor/advisory findings from one list, deduped by subject/message/location.
+ * Shared by `collectPassLimitations` (a pass's `open` and `resolved` findings)
+ * and the whole-program review's flat `Finding[]`.
  */
-function collectPassLimitations(outcome, workstreamLabel) {
-    if (!outcome)
-        return [];
+function collectLimitationLines(findings, label, sinceFixed = false) {
     const seen = new Set();
     const lines = [];
-    for (const finding of outcome.open) {
-        if (finding.severity !== "minor" && finding.severity !== "advisory")
-            continue;
-        const key = limitationKey(finding);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        lines.push(renderRawFinding(finding, workstreamLabel, false));
-    }
-    for (const finding of outcome.resolved) {
+    for (const finding of findings) {
         if (finding.severity !== "minor" && finding.severity !== "advisory")
             continue;
         const key = limitationKey(finding);
         if (seen.has(key))
             continue;
         seen.add(key);
-        lines.push(renderRawFinding(finding, workstreamLabel, true));
+        lines.push(renderRawFinding(finding, label, sinceFixed));
     }
     return lines;
 }
+/**
+ * A pass's minor/advisory findings, `open` and `resolved` alike (SC-07's
+ * "every ... raised" — a finding the writer fixed was still raised).
+ */
+function collectPassLimitations(outcome, workstreamLabel) {
+    if (!outcome)
+        return [];
+    return [
+        ...collectLimitationLines(outcome.open, workstreamLabel),
+        ...collectLimitationLines(outcome.resolved, workstreamLabel, true),
+    ];
+}
 /**
  * One aggregated section (SC-07): every minor/advisory finding raised
  * anywhere in the run, every finding the decider accepted, any finding
@@ -1210,11 +1440,14 @@ function collectPassLimitations(outcome, workstreamLabel) {
  * every fix-now attempt, and the run-local triage ratio. Fail-open
  * throughout — an empty run renders a plain statement, never nothing.
  */
-function renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId) {
+function renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId, wholeProgram) {
     const lines = ["## Known limitations", ""];
     const passLimitations = [
         ...results.flatMap((result) => collectPassLimitations(result.testCritique, `${result.id} test critique`)),
         ...authorResult.results.flatMap((entry) => collectPassLimitations(entry.specCritique, `${entry.id} spec critique`)),
+        ...(wholeProgram
+            ? collectLimitationLines(wholeProgram.outcome.findings, "whole-program review")
+            : []),
     ];
     const acceptedFindings = ledger.findings.filter((record) => record.status === "accepted");
     const openFindings = ledger.findings.filter((record) => record.status === "open");
@@ -1259,6 +1492,10 @@ function renderKnownLimitations(results, authorResult, ledger, escalated, triage
                     : "";
                 lines.push(`- **${record.subject}** — fixed in the run${commitPart}: ${record.fixAttempt.note}`, "");
             }
+            else if (record.workstream === WHOLE_PROGRAM_SUBJECT) {
+                lines.push(`- **${record.subject}** — from the whole-program review, triaged ` +
+                    "`fix-now`: carried to the next run; nothing was fixed in this one.", "");
+            }
             else {
                 lines.push(`- **${record.subject}** — fix-now triaged; outcome pending.`, "");
             }
@@ -1270,7 +1507,54 @@ function renderKnownLimitations(results, authorResult, ledger, escalated, triage
         `${escalatedThisRunCount} ${escalatedThisRunCount === 1 ? "was" : "were"} escalated.`, "");
     return lines;
 }
-export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at) {
+/** The commit fact WS-01's outcome cannot know — sha and paths, or why there is none. */
+function commitFactLines(wholeProgram) {
+    const { commit, commitSkipped, outcome } = wholeProgram;
+    if (commit !== undefined) {
+        return [`Committed as \`${commit}\`: ${outcome.writtenPaths.join(", ")}.`];
+    }
+    if (outcome.writtenPaths.length === 0) {
+        return ["No commit — nothing was written."];
+    }
+    if (commitSkipped) {
+        return [
+            "Written to the working tree but not committed: this is not a git repository.",
+        ];
+    }
+    return ["The snapshot was written, but committing it failed — see the stage error below."];
+}
+/**
+ * A whole-program finding this stage journaled that the decider triaged
+ * `fix-now` this run. Keys on `findingIds` (this run's own journaling), not
+ * on `record.workstream` — that broader statement is §3.7's, in
+ * `renderKnownLimitations`, and applies across runs.
+ */
+function carriedFixNowLines(wholeProgram, ledger) {
+    if (wholeProgram.findingIds.length === 0)
+        return [];
+    const ids = new Set(wholeProgram.findingIds);
+    const carried = ledger.findings.filter((record) => ids.has(record.id) && record.status === "fix-now");
+    if (carried.length === 0)
+        return [];
+    return carried.map((record) => `Triaged \`fix-now\`: **${record.subject}** — carried to the next run; nothing was fixed in this one.`);
+}
+/**
+ * The `## Whole-program review` section: delegates its body to WS-01's own
+ * renderer verbatim, and adds only what that module cannot know — the commit
+ * fact, this run's carried fix-now findings, and this stage's own errors.
+ */
+function renderWholeProgramSection(wholeProgram, ledger) {
+    const lines = ["## Whole-program review", ""];
+    lines.push(...renderWholeProgramReview(wholeProgram.outcome));
+    lines.push(...commitFactLines(wholeProgram));
+    lines.push(...carriedFixNowLines(wholeProgram, ledger));
+    if (wholeProgram.errors.length > 0) {
+        lines.push(...wholeProgram.errors.map((error) => `Stage error: ${error}`));
+    }
+    lines.push("");
+    return lines;
+}
+export function renderRunReport(manifest, results, ledger, triagedThisRun, authorResult, at, wholeProgram) {
     const programId = manifest.program.id;
     const built = results.filter((result) => result.outcome.status === "complete" ||
         result.outcome.status === "skipped").length;
@@ -1332,6 +1616,9 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
         }
     }
     lines.push("");
+    if (wholeProgram !== undefined) {
+        lines.push(...renderWholeProgramSection(wholeProgram, ledger));
+    }
     const settledDecisions = ledger.decisions.filter((record) => record.status !== "escalated");
     lines.push("## Decisions made along the way", "", "Every judgment call an agent surfaced, with its review status.", "Anything here can be revisited: roll back to the anchor commit and", "re-run, or just say which option you want changed.", "");
     if (settledDecisions.length === 0) {
@@ -1342,7 +1629,7 @@ export function renderRunReport(manifest, results, ledger, triagedThisRun, autho
             lines.push(...renderRecord(record, { density: "compact", programId }), "");
         }
     }
-    lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId));
+    lines.push(...renderKnownLimitations(results, authorResult, ledger, escalated, triagedThisRun, programId, wholeProgram));
     const decisionErrors = results.flatMap((result) => result.decisionErrors);
     if (decisionErrors.length > 0) {
         lines.push("## Decision blocks the runner could not read", "", ...decisionErrors.map((error) => `- ${error}`), "");