backpass 0.1.0

package/src/commands/analyze.js

@@ -0,0 +1,88 @@
+import { analyzeTranscripts } from "../analyze.js";
+import { UserError, color, info, json, out, warn } from "../logger.js";
+import { resolveMemoryFiles } from "../memory.js";
+import { emitProgress } from "../progress.js";
+import { discoverForRun } from "./scan.js";
+import { printUsage } from "./usage.js";
+import { capTranscripts } from "../sample.js";
+
+/**
+ * The memory file a run optimizes: the first configured file that exists (AGENTS.md by
+ * default - canonical). Resolution is pointer-aware: a CLAUDE.md that is just
+ * `@AGENTS.md` is covered by optimizing AGENTS.md and needs no mention. A second file
+ * with its own content is NOT updated - that would either be ignored silently or
+ * double-written into divergence - so the run says so and recommends consolidating.
+ *
+ * When no configured file exists, `backpass` (the default run) bootstraps one; every
+ * other command fails with a pointer to that.
+ */
+export function primaryMemoryFile(repo, config) {
+  const resolved = resolveMemoryFiles(repo.root, config.memoryFiles);
+  if (!resolved.primary) {
+    throw new UserError(
+      `no memory file found (looked for ${config.memoryFiles.join(", ")})`,
+      "run `backpass` to bootstrap an AGENTS.md, or set memoryFiles in .backpassrc.json",
+    );
+  }
+  for (const other of resolved.separate) {
+    warn(
+      `${other.path} is a separate memory file and will NOT be updated - only ${resolved.primary.path} is optimized. ` +
+        `To cover both, consolidate: move its content into ${resolved.primary.path} and make ${other.path} a pointer ` +
+        `(a single line: @${resolved.primary.path}).`,
+    );
+  }
+  return { file: resolved.primary, all: resolved.all, hash: resolved.hash, resolved };
+}
+
+export async function runAnalysis(ctx) {
+  const { repo, config } = ctx;
+  const { file, hash } = primaryMemoryFile(repo, config);
+  // Deterministic by design: tokens and units come from parsing the file, no model.
+  emitProgress("memory", {
+    path: file.path,
+    tokens: file.tokens,
+    budget: config.budgetTokens,
+    units: file.units.length,
+  });
+  // The cap bounds the expensive per-transcript calls; cached evidence is reused as usual.
+  const { transcripts, perHarness } = capTranscripts(await discoverForRun(ctx), config);
+
+  if (!transcripts.length) {
+    info(`${color.yellow("·")} no transcripts associated with this repo`);
+    return { file, hash, transcripts, perHarness, summary: null };
+  }
+
+  const summary = await analyzeTranscripts({
+    transcripts,
+    memoryFile: file,
+    config,
+    repo,
+    memoryHash: hash,
+    force: Boolean(ctx.flags.force),
+  });
+
+  return { file, hash, transcripts, perHarness, summary };
+}
+
+export async function cmdAnalyze(ctx) {
+  const { file, transcripts, summary } = await runAnalysis(ctx);
+
+  if (ctx.flags.json) {
+    json({ memoryFile: file.path, transcripts: transcripts.length, summary });
+    return 0;
+  }
+
+  if (!summary) return 0;
+
+  out("");
+  out(`analyzed against ${file.path} (${file.units.length} instructions, ${file.tokens} tok)`);
+  out(
+    `  ${summary.analyzed} newly analyzed · ${summary.cached} cached · ` +
+      `${summary.skipped} skipped (too short) · ${summary.failed} failed`,
+  );
+  if (summary.failed) {
+    out(color.dim("  failed transcripts are listed by `backpass status` and retried next run"));
+  }
+  printUsage({ tier1: summary.usage });
+  return 0;
+}

package/src/commands/apply.js

@@ -0,0 +1,103 @@
+import { UserError, color, info, json, out, warn } from "../logger.js";
+import { applyDecisions } from "../apply/writer.js";
+import { closeApplySurface, openApplySurface, pollDecisions, renderApplySurface } from "../apply/lavish.js";
+import { reviewInTerminal } from "../apply/terminal.js";
+import { budgetBar, formatTokens } from "../tokens.js";
+
+/**
+ * The human gate. `backpass apply` is the only command that writes to the repo.
+ *
+ * By default it serves the shipped static template through lavish-axi and waits for one
+ * structured decision vector; `--no-ui` keeps the same ACCEPT/REJECT decision in the
+ * terminal.
+ */
+export async function cmdApply(ctx) {
+  const { config, repo } = ctx;
+  const proposal = config.state.readProposal();
+
+  if (!proposal) {
+    throw new UserError("no proposal to apply", "run `backpass` first to produce one");
+  }
+  if (proposal.violations?.length) {
+    throw new UserError(
+      "the saved proposal failed its mechanical gates and was never approved for apply",
+      "run `backpass propose` again",
+    );
+  }
+  if (proposal.appliedAt) {
+    throw new UserError(
+      `the last proposal was already applied by ${proposal.appliedBy || "a previous apply"} (${proposal.appliedAt})`,
+      "run `backpass` again to produce a fresh one",
+    );
+  }
+  if (!proposal.edits.length) {
+    out("The last run proposed no edits. Nothing to apply.");
+    return 0;
+  }
+
+  const editIds = proposal.edits.map((e) => e.id);
+  let decisions;
+  let surfaceFile = null;
+
+  if (ctx.flags["no-ui"]) {
+    decisions = await reviewInTerminal(proposal);
+  } else {
+    surfaceFile = renderApplySurface(proposal, config.state, ctx.version);
+    const url = await openApplySurface(surfaceFile);
+    info(`${color.cyan("·")} review surface: ${url || surfaceFile}`);
+    decisions = await pollDecisions(surfaceFile, editIds);
+  }
+
+  if (!decisions) {
+    out("No decisions received - nothing was written.");
+    return 0;
+  }
+
+  // Anything the reviewer never touched stays untouched.
+  for (const id of editIds) if (!decisions[id]) decisions[id] = "skipped";
+
+  const results = applyDecisions({
+    proposal,
+    decisions,
+    repo,
+    state: config.state,
+    config,
+    dryRun: Boolean(ctx.flags["dry-run"]),
+  });
+
+  if (surfaceFile) await closeApplySurface(surfaceFile);
+
+  if (ctx.flags.json) {
+    json({ decisions, results });
+    return results.failed.length ? 1 : 0;
+  }
+
+  out("");
+  const prefix = ctx.flags["dry-run"] ? color.yellow("[dry-run] ") : "";
+  out(`${prefix}${results.accepted} accepted · ${results.rejected} rejected`);
+
+  for (const written of results.written) {
+    out(`  ${color.green("wrote")} ${written.file} (${written.edits.join(", ")})`);
+    if (written.budget) {
+      out(
+        `    budget ${budgetBar(written.budget)} ${formatTokens(written.budget.current)} -> ` +
+          `${formatTokens(written.budget.projected)} / ${formatTokens(written.budget.capTokens)} tok`,
+      );
+    }
+  }
+  for (const skill of results.skills) {
+    out(`  ${color.green("wrote")} ${skill.path} (new skill)`);
+    for (const created of skill.created || []) out(color.dim(`    created ${created}`));
+  }
+  for (const warning of results.warnings || []) warn(warning);
+  for (const failure of results.failed) {
+    out(`  ${color.red("failed")} ${failure.file}${failure.edit ? ` (${failure.edit})` : ""}: ${failure.error}`);
+  }
+
+  if (results.rejected) {
+    out(color.dim("  rejections recorded - they will not be re-proposed without new evidence"));
+  }
+  if (!results.written.length && !results.skills.length) out("  nothing written");
+
+  return results.failed.length ? 1 : 0;
+}

package/src/commands/bootstrap.js

@@ -0,0 +1,172 @@
+import { analyzeTranscripts } from "../analyze.js";
+import { applyDecisions, writeBootstrapFiles } from "../apply/writer.js";
+import { bootstrapTargets, renderPointer, starterMemoryFile } from "../bootstrap.js";
+import { color, info, json, out, warn } from "../logger.js";
+import { emitProgress } from "../progress.js";
+import { ProposalViolation } from "../proposal.js";
+import { synthesizeProposal } from "../synthesize.js";
+import { budgetBar, formatTokens } from "../tokens.js";
+import { discoverForRun } from "./scan.js";
+import { foldForRun, printProposal } from "./propose.js";
+
+/**
+ * Bootstrap: the default run when the repo has no memory file at all.
+ *
+ * Instead of failing, backpass seeds a starter AGENTS.md (a minimal skeleton, see
+ * `src/bootstrap.js`) plus a CLAUDE.md pointer, then runs the ordinary backward pass with
+ * the starter as the current weights: the transcripts' gaps and recurring mistakes
+ * become the first evidence-backed instructions. Every edit of that first proposal is
+ * applied directly - the file is brand new, so there is nothing to protect with the
+ * human gate and `git diff` is the review. Later runs go through the normal
+ * propose -> apply flow.
+ *
+ * Safety: files are only ever created, never overwritten, and a failure anywhere after
+ * the seed still leaves a valid defaults-only memory file behind.
+ */
+
+const BOOTSTRAP_RUN_NOTE =
+  "This memory file was just seeded from generic defaults and has never steered a session, " +
+  "so the evidence is gaps and mistakes only. Turn recurring gaps into concrete instructions " +
+  "(`add` under `## Learnings`, replacing the placeholder bullet there; never create a new " +
+  "section for them) and `rewrite` any default the evidence contradicts. " +
+  "Skip anything a single session suggests.";
+
+/**
+ * `deps` exists so the flow is testable offline: the three model/disk-facing stages
+ * default to the real pipeline and can be swapped for fakes.
+ */
+export async function bootstrapRun(ctx, deps = {}) {
+  const { repo, config } = ctx;
+  const discover = deps.discover || discoverForRun;
+  const analyze = deps.analyze || analyzeTranscripts;
+  const synthesize = deps.synthesize || synthesizeProposal;
+  const { canonical, pointer } = bootstrapTargets(config.memoryFiles);
+
+  const { transcripts, perHarness } = await discover(ctx);
+  info(
+    `${color.yellow("·")} no memory file found (looked for ${config.memoryFiles.join(", ")}) - ` +
+      `bootstrapping ${canonical} from ${transcripts.length} transcript(s) + defaults`,
+  );
+
+  const starter = starterMemoryFile(repo, canonical);
+  const seed = [{ path: canonical, text: starter.text }];
+  if (pointer) seed.push({ path: pointer, text: renderPointer(canonical) });
+  const seeded = writeBootstrapFiles(repo.root, seed);
+  for (const w of seeded.written) info(`${color.green("·")} wrote ${w.file}`);
+  for (const s of seeded.skipped) warn(`${s.file} ${s.reason} - left untouched`);
+
+  emitProgress("memory", {
+    path: starter.path,
+    tokens: starter.tokens,
+    budget: config.budgetTokens,
+    units: starter.units.length,
+  });
+
+  const result = {
+    bootstrap: true,
+    seededFrom: "defaults",
+    files: seeded,
+    memoryFile: canonical,
+    transcripts: transcripts.length,
+    perHarness,
+    summary: null,
+    proposal: null,
+    applied: null,
+  };
+
+  if (!transcripts.length) return result;
+
+  result.summary = await analyze({
+    transcripts,
+    memoryFile: starter,
+    config,
+    repo,
+    memoryHash: starter.hash,
+    force: Boolean(ctx.flags.force),
+  });
+  info(
+    `${color.cyan("·")} evidence: ${result.summary.analyzed} new · ${result.summary.cached} cached · ` +
+      `${result.summary.skipped} too short · ${result.summary.failed} failed`,
+  );
+
+  const folded = await foldForRun(ctx, starter);
+  config.state.writeSummary(folded);
+  emitProgress("fold:done", {
+    instructions: folded.instructions.length,
+    clustersFound: folded.totals.gapClusters + folded.totals.droppedGapSingletons,
+    clustersKept: folded.totals.gapClusters,
+    minGapEvidence: config.minGapEvidence,
+    ms: 0,
+  });
+  if (!folded.analyzedSessions) return result;
+
+  try {
+    const { proposal } = await synthesize({
+      memoryFile: starter,
+      summary: folded,
+      config,
+      repo,
+      transcripts,
+      runNote: BOOTSTRAP_RUN_NOTE,
+    });
+    const decisions = Object.fromEntries(proposal.edits.map((e) => [e.id, "accepted"]));
+    const applied = applyDecisions({ proposal, decisions, repo, state: config.state, config });
+    proposal.appliedAt = new Date().toISOString();
+    proposal.appliedBy = "bootstrap";
+    config.state.writeProposal(proposal);
+    result.proposal = proposal;
+    result.applied = applied;
+    if (proposal.edits.length) result.seededFrom = "transcripts + defaults";
+  } catch (err) {
+    if (!(err instanceof ProposalViolation)) throw err;
+    // The seed is already on disk, so a bad synthesis degrades to defaults-only.
+    for (const violation of err.violations) warn(violation);
+    warn("gradient descent failed its gates; the memory file stays defaults-only this run");
+  }
+  return result;
+}
+
+export function printBootstrap(result, config) {
+  out("");
+  const files = result.files.written.map((w) => w.file).join(" + ");
+  out(`${color.bold("bootstrapped")} ${files || "nothing"} ${color.dim(`(seeded from ${result.seededFrom})`)}`);
+  for (const s of result.files.skipped) out(`  ${color.yellow("kept")} ${s.file} (${s.reason})`);
+
+  if (!result.transcripts) {
+    out("  no transcripts associated with this repo yet - the defaults stand until later runs find some");
+    out(color.dim("  `backpass scan --since all` widens the time window"));
+  } else if (!result.proposal) {
+    out(`  ${result.transcripts} transcript(s) found, but none produced usable evidence; defaults stand`);
+  } else {
+    printProposal(result.proposal, { applied: true });
+    for (const w of result.applied.written) {
+      out(`  ${color.green("wrote")} ${w.file} (${w.edits.join(", ")})`);
+      if (w.budget) {
+        out(
+          `    budget ${budgetBar(w.budget)} ${formatTokens(w.budget.current)} -> ` +
+            `${formatTokens(w.budget.projected)} / ${formatTokens(w.budget.capTokens)} tok`,
+        );
+      }
+    }
+    for (const s of result.applied.skills) out(`  ${color.green("wrote")} ${s.path} (new skill)`);
+    for (const f of result.applied.failed) {
+      out(`  ${color.red("failed")} ${f.file}${f.edit ? ` (${f.edit})` : ""}: ${f.error}`);
+    }
+  }
+  out("");
+  out(
+    `Review with \`git diff\`; later runs keep refining under the ${formatTokens(config.budgetTokens)}-token budget.`,
+  );
+}
+
+export function bootstrapJson(result) {
+  json({
+    bootstrap: true,
+    seededFrom: result.seededFrom,
+    memoryFile: result.memoryFile,
+    files: result.files,
+    transcripts: result.transcripts,
+    proposal: result.proposal,
+    applied: result.applied,
+  });
+}

package/src/commands/init.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONFIG_FILENAME, initialConfig, repoConfigPath } from "../config.js";
+import { color, info, out, warn } from "../logger.js";
+import { loadMemoryFiles } from "../memory.js";
+import { ensureLocalExclude } from "../repo.js";
+import { STATE_EXCLUDE_LINE as EXCLUDE_LINE } from "../state.js";
+import { budgetBar, budgetStatus, formatTokens } from "../tokens.js";
+
+export async function cmdInit({ repo, config, flags }) {
+  const target = repoConfigPath(repo.root);
+  const existing = fs.existsSync(target);
+
+  const seed = initialConfig();
+  // Seed memoryFiles with what this repo actually has, so the first run is correct.
+  const present = config.memoryFiles.filter((f) => fs.existsSync(path.join(repo.root, f)));
+  if (present.length) seed.memoryFiles = present;
+
+  if (existing && !flags.force) {
+    info(`${color.yellow("·")} ${CONFIG_FILENAME} already exists - leaving it alone (use --force to overwrite)`);
+  } else {
+    fs.writeFileSync(target, `${JSON.stringify(seed, null, 2)}\n`);
+    info(`${color.green("·")} wrote ${CONFIG_FILENAME}`);
+  }
+
+  const exclude = ensureLocalExclude(repo.root, EXCLUDE_LINE);
+  if (exclude.status === "added") {
+    info(`${color.green("·")} added ${EXCLUDE_LINE} to .git/info/exclude (local, never committed)`);
+  } else if (exclude.status === "no-git") {
+    info(`${color.yellow("·")} no git dir found - skipped excluding ${EXCLUDE_LINE}`);
+  }
+
+  const gitignore = path.join(repo.root, ".gitignore");
+  const gitignoreLines = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf8").split("\n") : [];
+  if (gitignoreLines.some((l) => l.trim() === EXCLUDE_LINE)) {
+    warn(`.gitignore already lists ${EXCLUDE_LINE} from an older backpass - remove it any time, it's redundant now`);
+  }
+
+  const files = loadMemoryFiles(repo.root, seed.memoryFiles);
+  out("");
+  if (!files.length) {
+    out(
+      `No memory file found yet. \`backpass\` will bootstrap ${seed.memoryFiles[0]} (+ a CLAUDE.md pointer) from your transcripts and defaults.`,
+    );
+    return 0;
+  }
+  for (const file of files) {
+    const status = budgetStatus(file.text, null, seed.budgetTokens);
+    out(
+      `${file.path.padEnd(14)} ${budgetBar(status)} ${formatTokens(status.current)} / ${formatTokens(
+        status.capTokens,
+      )} tok · ${file.units.length} instructions`,
+    );
+  }
+  out("");
+  out("Next: `backpass` to run a backward pass, or `backpass scan` to see what it would read.");
+  return 0;
+}

package/src/commands/propose.js

@@ -0,0 +1,136 @@
+import { foldEvidence } from "../fold.js";
+import { ledgerGapObservations, pruneGapLedger, recordGapObservations } from "../gap-ledger.js";
+import { synthesizeProposal } from "../synthesize.js";
+import { ProposalViolation } from "../proposal.js";
+import { UserError, color, info, json, out } from "../logger.js";
+import { budgetBar, formatTokens } from "../tokens.js";
+import { emitProgress } from "../progress.js";
+import { primaryMemoryFile } from "./analyze.js";
+import { printUsage } from "./usage.js";
+import { discoverForRun } from "./scan.js";
+
+/**
+ * Fold on-disk evidence for the memory file. Gap corroboration is counted through the
+ * persisted ledger so sessions accumulate across runs: record this run's observations,
+ * prune what the current file now covers or what aged out (after recording, because the
+ * evidence files that fed an expired sighting are still on disk and would re-add it),
+ * then cluster from the ledger.
+ */
+export async function foldForRun(ctx, memoryFile) {
+  const { state, minGapEvidence, gapLedgerMaxAge } = ctx.config;
+  const evidence = state.listEvidence();
+  const relevant = evidence.filter((e) => e.memoryPath === memoryFile.path);
+
+  const ledger = state.readGapLedger();
+  recordGapObservations(ledger, relevant);
+  pruneGapLedger(ledger, { memoryFile, memoryPath: memoryFile.path, maxAge: gapLedgerMaxAge });
+  state.writeGapLedger(ledger);
+
+  return foldEvidence(relevant, {
+    minGapEvidence,
+    memoryFile,
+    gapObservations: ledgerGapObservations(ledger, memoryFile.path),
+  });
+}
+
+export async function runProposal(ctx, precomputed = null) {
+  const { repo, config } = ctx;
+  const { file } = precomputed || primaryMemoryFile(repo, config);
+  const transcripts = precomputed?.transcripts || (await discoverForRun(ctx)).transcripts;
+
+  const foldStarted = Date.now();
+  const summary = await foldForRun(ctx, file);
+  config.state.writeSummary(summary);
+  emitProgress("fold:done", {
+    instructions: summary.instructions.length,
+    clustersFound: summary.totals.gapClusters + summary.totals.droppedGapSingletons,
+    clustersKept: summary.totals.gapClusters,
+    minGapEvidence: config.minGapEvidence,
+    ms: Date.now() - foldStarted,
+  });
+
+  if (!summary.analyzedSessions) {
+    throw new UserError(
+      "no loss calculated yet: nothing to run gradient descent on",
+      "run `backpass analyze` first, or `backpass` for the full pass",
+    );
+  }
+
+  const { proposal } = await synthesizeProposal({
+    memoryFile: file,
+    summary,
+    config,
+    repo,
+    transcripts,
+  });
+
+  config.state.writeProposal(proposal);
+  return { proposal, summary, memoryFile: file };
+}
+
+/**
+ * @param {object} proposal
+ * @param {{ applied?: boolean, analysisUsage?: import("../acpx.js").UsageRecord[] }} [options]
+ *   `analysisUsage` is the tier-1 accounting of the same run, when the caller ran it.
+ */
+export function printProposal(proposal, { applied = false, analysisUsage = [] } = {}) {
+  out("");
+  out(
+    `${color.bold("proposal")} · ${proposal.repo.name} · ${proposal.memoryFile.path} · ` +
+      `${proposal.edits.length} edit(s) from ${proposal.stats.transcripts} session(s)`,
+  );
+  out(
+    `  budget ${budgetBar(proposal.budget)} ${formatTokens(proposal.budget.current)} -> ` +
+      `${formatTokens(proposal.budget.projected)} / ${formatTokens(proposal.budget.capTokens)} tok` +
+      (proposal.budget.mode === "shrink"
+        ? color.dim(`  [shrink plan: ${formatTokens(proposal.budget.over)} still over]`)
+        : ""),
+  );
+  out(
+    `  evidence: ${proposal.stats.positive} positive · ${proposal.stats.negative} negative · ` +
+      `${proposal.stats.gapClusters} gap clusters`,
+  );
+  out("");
+
+  if (!proposal.edits.length) {
+    out("  no edits proposed - the evidence did not clear the thresholds this run");
+  }
+
+  for (const edit of proposal.edits) {
+    const kind = edit.kind === "extract" ? "EXTRACT" : edit.kind.toUpperCase();
+    const delta = edit.deltaTokens || 0;
+    out(
+      `  ${color.cyan(edit.id)} ${kind.padEnd(8)} ${edit.title} ` +
+        color.dim(`(${delta > 0 ? "+" : ""}${delta} tok, ${edit.transcripts} transcript(s))`),
+    );
+  }
+
+  for (const note of proposal.notes || []) out(color.dim(`  note: ${note}`));
+
+  printUsage({ tier1: analysisUsage, tier2: proposal.usage || [] });
+  if (applied) return;
+  out("");
+  out("Review and apply with `backpass apply` (nothing has been written).");
+}
+
+export async function cmdPropose(ctx) {
+  try {
+    const { proposal } = await runProposal(ctx);
+    if (ctx.flags.json) {
+      json(proposal);
+      return 0;
+    }
+    printProposal(proposal);
+    return 0;
+  } catch (err) {
+    if (err instanceof ProposalViolation) {
+      // Loud failure, never silent truncation (design section 6).
+      info("");
+      for (const violation of err.violations) info(`  ${color.red("x")} ${violation}`);
+      info("");
+      info(color.dim(`  the rejected proposal was saved to ${ctx.config.state.proposalPath}`));
+      throw new UserError(err.message, "try a stronger synthesis model, or raise --budget / --max-edits");
+    }
+    throw err;
+  }
+}

package/src/commands/run.js

@@ -0,0 +1,95 @@
+import { UserError, color, info, json, out } from "../logger.js";
+import { ProposalViolation } from "../proposal.js";
+import { runAnalysis } from "./analyze.js";
+import { bootstrapJson, bootstrapRun, printBootstrap } from "./bootstrap.js";
+import { printProposal, runProposal } from "./propose.js";
+import { budgetBar, formatTokens } from "../tokens.js";
+import { startTui } from "../tui/index.js";
+import { resolveMemoryFiles } from "../memory.js";
+
+/**
+ * The default command: one full backward pass.
+ *
+ *   discover -> distill -> analyze (cheap, fanned out) -> fold -> synthesize (one big call)
+ *
+ * It never writes - with one exception: a repo with no memory file at all is
+ * bootstrapped (`./bootstrap.js`), which only ever creates files. Otherwise applying
+ * is a separate, human-gated step.
+ *
+ * On an eligible terminal a live progress view renders the run on stderr; it
+ * collapses back into the plain lines below before anything is printed to
+ * stdout, so piped and logged output is unchanged.
+ */
+export async function cmdRun(ctx) {
+  const { repo, config } = ctx;
+  const tui = await startTui(ctx);
+
+  try {
+    info(
+      `${color.bold("backpass")} ${color.dim(
+        `v${ctx.version} · ${repo.name} · budget ${formatTokens(config.budgetTokens)} tok · since ${config.discovery.since}`,
+      )}`,
+    );
+
+    if (!resolveMemoryFiles(repo.root, config.memoryFiles).primary) {
+      const result = await bootstrapRun(ctx);
+      tui?.stop();
+      if (ctx.flags.json) bootstrapJson(result);
+      else printBootstrap(result, config);
+      return 0;
+    }
+
+    const analysis = await runAnalysis(ctx);
+
+    if (!analysis.transcripts.length) {
+      tui?.stop();
+      out("");
+      out("No agent transcripts are associated with this repo yet.");
+      out(
+        color.dim(
+          "  `backpass scan --since all` widens the time window; --include-cursor-ide adds the Cursor IDE store.",
+        ),
+      );
+      return 0;
+    }
+
+    const budget = budgetBar({
+      utilization: analysis.file.tokens / config.budgetTokens,
+      withinBudget: analysis.file.tokens <= config.budgetTokens,
+    });
+    info(
+      `${color.cyan("·")} ${analysis.file.path}: ${budget} ${formatTokens(analysis.file.tokens)} / ` +
+        `${formatTokens(config.budgetTokens)} tok · ${analysis.file.units.length} instructions`,
+    );
+
+    if (analysis.summary) {
+      info(
+        `${color.cyan("·")} evidence: ${analysis.summary.analyzed} new · ${analysis.summary.cached} cached · ` +
+          `${analysis.summary.skipped} too short · ${analysis.summary.failed} failed`,
+      );
+    }
+
+    const { proposal } = await runProposal(ctx, analysis);
+    tui?.stop();
+
+    if (ctx.flags.json) {
+      json(proposal);
+      return 0;
+    }
+
+    printProposal(proposal, { analysisUsage: analysis.summary?.usage || [] });
+    return 0;
+  } catch (err) {
+    tui?.stop();
+    if (err instanceof ProposalViolation) {
+      info("");
+      for (const violation of err.violations) info(`  ${color.red("x")} ${violation}`);
+      info("");
+      info(color.dim(`  the rejected proposal was saved to ${config.state.proposalPath}`));
+      throw new UserError(err.message, "try a stronger synthesis model, or raise --budget / --max-edits");
+    }
+    throw err;
+  } finally {
+    tui?.stop();
+  }
+}