backpass 0.1.0

package/src/progress.js

@@ -0,0 +1,29 @@
+/**
+ * Progress event bus between the pipeline and the live progress view.
+ *
+ * Pipeline stages emit structured events through `emitProgress`; they are dropped
+ * unless a renderer registered a sink. This keeps every stage free of rendering
+ * concerns and guarantees that runs without a TTY behave exactly as before -
+ * the events simply go nowhere.
+ */
+
+let sink = null;
+
+/** Register the single active sink (the TUI controller). */
+export function setProgressSink(fn) {
+  sink = fn;
+}
+
+export function clearProgressSink() {
+  sink = null;
+}
+
+/** Emit one progress event. A throwing sink must never break the pipeline. */
+export function emitProgress(event, data = {}) {
+  if (!sink) return;
+  try {
+    sink(event, data);
+  } catch {
+    // Rendering is best-effort; the run itself is what matters.
+  }
+}

package/src/prompts/analysis.md

@@ -0,0 +1,48 @@
+You are auditing one past agent session against the repository's agent memory file.
+
+Your job is NOT to review the code. It is to measure how well the memory file's
+instructions actually steered this session, and to spot mistakes an instruction could
+have prevented. This is the loss signal for a backward pass over the memory file.
+
+## The memory file under audit: {{MEMORY_PATH}}
+
+Each instruction has a stable id in [brackets]. Refer to instructions ONLY by these ids.
+
+{{INSTRUCTION_INDEX}}
+
+## The distilled session trace
+
+Tool calls are one-line summaries and tool output is truncated. The raw transcript path
+is at the end of the trace: open it ONLY if a specific claim you want to make cannot be
+verified from the distilled trace. Reading it is allowed but costs time, so do not do it
+by default. Set `usedRawTranscript` accordingly.
+
+{{TRACE}}
+
+## What to report
+
+Return ONE JSON object and nothing else. No prose before or after, no markdown fence.
+
+```
+{
+  "positive":  [{"instruction": "AG-042", "moment": "turn 12", "effect": "what following it achieved", "quote": "verbatim text from the trace"}],
+  "negative":  [{"instruction": "AG-017", "moment": "turn 3",  "effect": "what going against it cost", "quote": "verbatim text from the trace"}],
+  "gaps":      [{"mistake": "what went wrong", "proposedInstruction": "one sentence that would have prevented it", "recurrenceRisk": "high|medium|low", "quote": "verbatim text from the trace"}],
+  "usedRawTranscript": false
+}
+```
+
+Rules, in order of importance:
+
+1. **Every item needs a verbatim `quote` copied exactly from the trace.** Items without
+   a real quote are discarded downstream, so an unquotable claim is wasted work.
+2. **Negative evidence is the most valuable.** A visible violation, misreading, or
+   ignored instruction outranks a dozen "it went fine" observations.
+3. **Do not confabulate influence.** Only call something positive when the trace shows
+   the agent doing the specific thing the instruction asks for. An outcome that would
+   have happened anyway is not evidence.
+4. `gaps` are mistakes NOT covered by any current instruction. If an instruction exists
+   and was ignored, that is `negative`, not a gap.
+5. `proposedInstruction` must be one imperative sentence, specific enough to act on and
+   general enough to apply beyond this one session.
+6. An empty array is a valid and useful answer. Report nothing rather than something weak.

package/src/prompts/annotate.md

@@ -0,0 +1,48 @@
+backpass measured the changes you made in the staging copy. Every change below is
+identified by an id; annotate each one so a human can review it with its evidence.
+
+## Measured changes
+
+{{CHANGES}}
+
+## What to produce
+
+Return ONE JSON object and nothing else. No prose, no markdown fence.
+
+```
+{
+  "edits": [
+    {
+      "changes": ["H1"],
+      "kind": "add" | "remove" | "rewrite" | "extract",
+      "title": "one line a human can decide on",
+      "rationale": "why the evidence supports this",
+      "instructions": ["AG-017"],
+      "evidence": [{"polarity": "negative", "text": "the verbatim quote", "source": "claude · abc123 · turn 12"}],
+      "transcripts": 3
+    }
+  ],
+  "verdicts": [
+    {"instruction": "AG-042", "verdict": "keep" | "strengthen" | "weaken" | "remove", "positive": 6, "negative": 1, "note": "one line"}
+  ],
+  "notes": ["anything a human should know that is not an edit"]
+}
+```
+
+Hard rules - a violation fails the whole proposal:
+
+1. **Every measured change belongs to exactly one edit.** Group the changes that make up
+   one decision (an extraction is the new `SKILL.md` plus the removal it pays for); do
+   not leave a change out. If a change should not ship, revert it in the file first.
+2. **At most {{MAX_EDITS}} edits** - the learning rate. Regroup or revert if you are over.
+3. **Every edit carries at least one verbatim quote in `evidence`**, with its source.
+4. **New instructions need evidence from at least {{MIN_GAP_EVIDENCE}} distinct
+   sessions.** `transcripts` is how many distinct sessions back the edit; an edit that
+   only adds text is a new instruction whatever its `kind` says.
+5. `kind: "extract"` is exactly an edit whose changes include one created `SKILL.md`
+   and at least one change to `{{MEMORY_PATH}}`. Any other edit must not include a
+   created file, and an edit changes one file only.
+6. **Budget:** {{BUDGET_RULE}}
+
+If you still need to change the files, do that first and then answer; backpass
+re-measures after this reply and shows you the new ids if anything moved.

package/src/prompts/synthesis.md

@@ -0,0 +1,98 @@
+You are performing the synthesis step of a backward pass over a repository's agent
+memory file. Evidence from many past agent sessions has already been gathered and
+folded. Your job is to turn that evidence into a small set of concrete, budget-aware
+edits - one gradient step on the weights, not a rewrite - by editing the file directly.
+
+## Repository
+
+{{REPO_NAME}} - {{TRANSCRIPT_COUNT}} sessions analyzed across {{HARNESS_SUMMARY}}.
+{{RUN_NOTE}}
+
+## Where you are
+
+Your working directory is a staging copy, not the repository. It holds exactly two
+things: the memory file at `./{{MEMORY_PATH}}` and the skills directory at
+`./{{SKILLS_DIR}}/`. The repository itself is at `{{REPO_ROOT}}` - open any file there
+to ground or verify an edit against the real code, but NEVER write there. Nothing you
+change in the staging copy reaches the repository until a human reviews each change.
+
+**Make your edits by editing `./{{MEMORY_PATH}}` in place with your file tools.** Do not
+paste the edited text into your reply; backpass measures what you changed in the file.
+
+## Current memory file: {{MEMORY_PATH}}
+
+Budget: {{CURRENT_TOKENS}} / {{BUDGET_TOKENS}} estimated tokens ({{BUDGET_STATE}}).
+
+Every token in this file is paid on every future session, forever, and instruction
+following dilutes as the file grows. The budget is the constraint you optimize under.
+
+The index below is a lookup table, not the file: it names each instruction (`AG-nnn`),
+its always-loaded cost, and the lines it occupies in `./{{MEMORY_PATH}}`. The evidence
+refers to instructions by these ids.
+
+{{INSTRUCTION_INDEX}}
+
+## Existing skills (load-on-trigger, in {{SKILLS_DIR}})
+
+{{SKILL_INDEX}}
+
+To extract a section into a skill, create `./{{SKILLS_DIR}}/<skill-name>/SKILL.md` with
+this exact shape, then remove the extracted detail from `./{{MEMORY_PATH}}`
+(optionally leaving a one-line pointer):
+
+```
+---
+name: <skill-name>
+description: <one line - this IS the trigger condition>
+---
+
+<the full markdown body of the skill>
+```
+
+To tune an existing skill's trigger, edit its `description:` line under `./{{SKILLS_DIR}}/`.
+
+## Folded evidence
+
+`sessions` is how many distinct sessions produced the item. `relevance` is the share of
+analyzed sessions in which an instruction drew any evidence at all.
+
+{{EVIDENCE}}
+
+## Previously rejected edits - do not re-propose these
+
+{{REJECTIONS}}
+
+## Hard rules - a violation fails the whole proposal
+
+1. **At most {{MAX_EDITS}} edits.** This is the learning rate. An edit is one change a
+   human can decide on; pick the highest-signal ones. A small correct step beats a large
+   speculative one.
+2. **New instructions need evidence from at least {{MIN_GAP_EVIDENCE}} distinct
+   sessions.** One bad session never rewrites the weights.
+3. **Every edit must be backed by at least one verbatim quote** from the evidence. You
+   will attach the quotes in the next step, so only make changes you can back.
+4. **Budget:** {{BUDGET_RULE}}
+5. Prefer removing a dead instruction over adding a new one. Instructions with high
+   token cost and zero positive evidence across many sessions are the best removals.
+6. Change only `./{{MEMORY_PATH}}` and files under `./{{SKILLS_DIR}}/`. Never delete a
+   file. Do not create notes, scripts, or scratch files.
+
+## Where an instruction belongs
+
+|                          | Trigger fits in one description line | Trigger not detectable |
+|--------------------------|--------------------------------------|------------------------|
+| Broad (>= 20% of sessions, or safety-critical) | memory file | memory file |
+| Conditional / narrow     | **skill** (the description is the condition) | deletion candidate |
+
+A skill's description is always loaded and its body is free until triggered, so moving a
+long, narrow, crisply-triggered section into a skill is nearly pure budget profit.
+
+**Skill descriptions are weights too.** If the evidence shows an agent lacked knowledge
+an existing skill already contains, that is a failed trigger: rewrite that skill's
+description line instead of duplicating content in the memory file.
+
+## When you are done
+
+Reply with a short plain-text summary of what you changed and why (a few lines). No
+JSON yet - backpass will measure the changes and ask you to annotate each one next.
+If the evidence does not justify any change, change nothing and say so.

package/src/prompts.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROMPT_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "prompts");
+
+const cache = new Map();
+
+export function loadPrompt(name) {
+  if (!cache.has(name)) {
+    cache.set(name, fs.readFileSync(path.join(PROMPT_DIR, `${name}.md`), "utf8"));
+  }
+  return cache.get(name);
+}
+
+/** Simple, explicit {{TOKEN}} substitution - no template engine, no surprises. */
+export function render(template, values) {
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (match, key) =>
+    Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match,
+  );
+}
+
+/**
+ * Every prompt backpass sends to a harness starts with this line. The harness records
+ * the prompt as the session's first user message in its own store - the very store
+ * discovery reads - so without a marker backpass's analysis and synthesis runs would
+ * be discovered as ordinary sessions on the next pass and the loop would analyze
+ * itself. Discovery (`src/discovery/self.js`) drops any transcript whose first user
+ * message begins with it. It keys on content backpass owns, so it survives harness
+ * format drift and needs nothing from acpx.
+ */
+export const SELF_SESSION_SENTINEL = "<!-- backpass:self-session -->";
+
+export function renderPrompt(name, values) {
+  return `${SELF_SESSION_SENTINEL}\n${render(loadPrompt(name), values)}`;
+}

package/src/proposal.js

@@ -0,0 +1,430 @@
+import { renderHunkLines } from "./diff.js";
+import { budgetStatus, estimateTokens } from "./tokens.js";
+
+/**
+ * The proposal model: what a synthesis pass is allowed to produce, and the mechanical
+ * gates it must clear before a human ever sees it (design sections 3, 6, 7).
+ *
+ * The synthesis agent edits a staging copy of the memory file natively
+ * (`src/workspace.js`); backpass measures the result as anchored hunks (`src/diff.js`)
+ * and the agent annotates them - kind, title, rationale, evidence - by id. An edit is
+ * therefore a group of measured changes against one file:
+ *
+ *   add      only inserts text                  (gated like a new instruction)
+ *   remove   only deletes text
+ *   rewrite  replaces text
+ *   extract  memory-file change(s) + one created SKILL.md
+ *
+ * Each hunk carries a `find`/`replace` pair copied out of the original file by
+ * construction; `find` occurs exactly once there. That is what the writer applies later,
+ * against whatever the file is by then: anything that no longer matches is rejected
+ * rather than guessed at - a memory file is not something to fuzzy-patch.
+ */
+
+export const EDIT_KINDS = ["add", "remove", "rewrite", "extract"];
+
+/**
+ * The per-run edit cap is adaptive (design section 6). Near or under budget it is the
+ * gentle learning rate: DEFAULT_MAX_EDITS small, reviewable steps. A file that is over
+ * budget needs a shrink plan, and a flat cap would stretch that plan across many runs,
+ * so the allowance scales with the overage: one edit per SHRINK_EDIT_TOKENS of overage,
+ * never below the default and never above SHRINK_MAX_EDITS, which keeps a single apply
+ * review manageable. An explicit `maxEditsPerRun` (flag or config) always wins.
+ */
+export const DEFAULT_MAX_EDITS = 5;
+export const SHRINK_MAX_EDITS = 20;
+/** A typical memory-file instruction removal or tightening trims about this many tokens. */
+export const SHRINK_EDIT_TOKENS = 40;
+
+export function effectiveMaxEdits(memoryFile, config) {
+  if (Number.isInteger(config.maxEditsPerRun) && config.maxEditsPerRun > 0) return config.maxEditsPerRun;
+  const overage = memoryFile.tokens - config.budgetTokens;
+  if (overage <= 0) return DEFAULT_MAX_EDITS;
+  return Math.min(SHRINK_MAX_EDITS, Math.max(DEFAULT_MAX_EDITS, Math.ceil(overage / SHRINK_EDIT_TOKENS)));
+}
+
+export class ProposalViolation extends Error {
+  constructor(message, violations) {
+    super(message);
+    this.name = "ProposalViolation";
+    this.violations = violations;
+  }
+}
+
+function normalizeEdit(raw, index) {
+  const kind = String(raw?.kind || "").toLowerCase();
+  const refs = Array.isArray(raw?.changes) ? raw.changes : Array.isArray(raw?.hunks) ? raw.hunks : [];
+  return {
+    id: `e${index + 1}`,
+    kind,
+    changeIds: refs.map((c) => String(c).trim().toUpperCase()).filter(Boolean),
+    title: String(raw?.title || "").trim() || "(untitled edit)",
+    rationale: String(raw?.rationale || "").trim(),
+    instructions: Array.isArray(raw?.instructions) ? raw.instructions.map(String) : [],
+    evidence: normalizeEvidence(raw?.evidence),
+    transcripts: Number.isFinite(raw?.transcripts) ? Number(raw.transcripts) : countSources(raw?.evidence),
+  };
+}
+
+function normalizeEvidence(evidence) {
+  if (!Array.isArray(evidence)) return [];
+  return evidence
+    .filter((e) => e && typeof e.text === "string" && e.text.trim())
+    .map((e) => ({
+      polarity: e.polarity === "positive" ? "positive" : e.polarity === "neutral" ? "neutral" : "negative",
+      text: String(e.text).trim().slice(0, 600),
+      source: String(e.source || "unknown source").slice(0, 120),
+    }));
+}
+
+function countSources(evidence) {
+  if (!Array.isArray(evidence)) return 0;
+  return new Set(evidence.map((e) => e?.source).filter(Boolean)).size;
+}
+
+/** Overlapping count: a run of identical lines must not pass as unique. */
+function occurrences(haystack, needle) {
+  if (!needle) return 0;
+  let count = 0;
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    count += 1;
+    index = haystack.indexOf(needle, index + 1);
+  }
+  return count;
+}
+
+function replaceOnce(text, find, replace, label, file) {
+  const found = occurrences(text, find);
+  if (found === 0) throw new Error(`${label}: "find" text does not appear in ${file}`);
+  if (found > 1) throw new Error(`${label}: "find" text appears ${found} times in ${file}; must be unique`);
+  return text.replace(find, () => replace);
+}
+
+/**
+ * Apply one edit to file text. Returns the new text, or throws with a precise reason.
+ *
+ * A measured edit applies each of its hunks; the hunks' windows never overlap, so they
+ * apply in any order and any subset. The legacy single `find`/`replace`/`anchor` shape
+ * is still honored so a proposal saved by an earlier version stays applicable.
+ */
+export function applyEdit(text, edit) {
+  if (Array.isArray(edit.hunks)) {
+    let current = text;
+    for (const hunk of edit.hunks) {
+      const label = `edit ${edit.id} (${hunk.id || "hunk"})`;
+      if (!hunk.find) {
+        if (current !== "") throw new Error(`${label}: ${edit.file} is no longer empty`);
+        current = hunk.replace;
+        continue;
+      }
+      current = replaceOnce(current, hunk.find, hunk.replace, label, edit.file);
+    }
+    return current;
+  }
+
+  if (edit.find) return replaceOnce(text, edit.find, edit.replace, `edit ${edit.id}`, edit.file);
+
+  if (!edit.replace) throw new Error(`edit ${edit.id}: nothing to add and nothing to remove`);
+
+  if (!edit.anchor) {
+    const separator = text.endsWith("\n") ? "" : "\n";
+    return `${text}${separator}\n${edit.replace}\n`;
+  }
+
+  const found = occurrences(text, edit.anchor);
+  if (found === 0) throw new Error(`edit ${edit.id}: "anchor" text does not appear in ${edit.file}`);
+  if (found > 1)
+    throw new Error(`edit ${edit.id}: "anchor" text appears ${found} times in ${edit.file}; must be unique`);
+  const at = text.indexOf(edit.anchor) + edit.anchor.length;
+  return `${text.slice(0, at)}\n\n${edit.replace}${text.slice(at)}`;
+}
+
+/** Apply a set of edits to one file, in order. */
+export function applyEdits(text, edits) {
+  return edits.reduce((current, edit) => applyEdit(current, edit), text);
+}
+
+/** One-line label for a measured change, used in gate messages and the annotate prompt. */
+export function describeChange(change) {
+  if (change.kind === "created") return `${change.id}: new file ${change.file}`;
+  if (change.kind === "deleted") return `${change.id}: deletes ${change.file}`;
+  const where = change.removed
+    ? change.oldStart === change.oldEnd
+      ? `line ${change.oldStart}`
+      : `lines ${change.oldStart}-${change.oldEnd}`
+    : `after line ${change.oldStart - 1}`;
+  return `${change.id}: ${change.file} ${where} (-${change.removed}/+${change.added})`;
+}
+
+/** The measured changes as the annotate prompt shows them. */
+export function renderChangesForPrompt(measured, memoryFile) {
+  if (!measured.changes.length) return "(no changes - the staging copy is identical to the original)";
+  const unitsAt = (change) => {
+    if (change.file !== memoryFile.path || change.kind !== "hunk") return "";
+    const from = change.oldStart;
+    const to = change.removed ? change.oldEnd : change.oldStart;
+    const ids = memoryFile.units.filter((u) => u.startLine <= to && u.endLine >= from).map((u) => u.id);
+    return ids.length ? ` · ${ids.join(", ")}` : "";
+  };
+  return measured.changes
+    .map((change) => {
+      const head = `[${describeChange(change)}${unitsAt(change)}]`;
+      if (change.kind === "deleted") return head;
+      if (change.kind === "created") {
+        return `${head}\n${renderHunkLines(
+          change.text.split("\n").map((text) => ({ type: "ins", text })),
+          { maxLines: 80 },
+        )}`;
+      }
+      return `${head}\n${renderHunkLines(change.lines)}`;
+    })
+    .join("\n\n");
+}
+
+/**
+ * Validate the annotated, measured changes against the mechanical gates. Returns
+ * `{ proposal, violations }`; the caller decides whether to re-prompt or fail loudly.
+ *
+ * `context.measured` is the workspace measurement (`measureWorkspace`); `rawResult` is
+ * the model's annotation. Nothing textual is taken from the model: the hunks, their
+ * deltas, the projected budget, and even whether an edit is an addition are measured.
+ */
+export function buildProposal(rawResult, context) {
+  const {
+    memoryFile,
+    config,
+    repo,
+    summary,
+    measured = { changes: [], stray: [] },
+    harnessCounts = {},
+    rejections = { entries: {} },
+    isSuppressed = () => false,
+  } = context;
+
+  const violations = [];
+  const notes = Array.isArray(rawResult?.notes) ? rawResult.notes.map(String) : [];
+  const rawEdits = Array.isArray(rawResult?.edits) ? rawResult.edits : [];
+  const edits = rawEdits.map((raw, i) => normalizeEdit(raw, i));
+  const changesById = new Map(measured.changes.map((c) => [c.id, c]));
+
+  const maxEdits = effectiveMaxEdits(memoryFile, config);
+  if (edits.length > maxEdits) {
+    violations.push(`proposed ${edits.length} edits but the per-run cap is ${maxEdits} (the learning rate)`);
+  }
+
+  // Every measured change must be claimed exactly once.
+  const claimedBy = new Map();
+  for (const edit of edits) {
+    for (const id of edit.changeIds) {
+      if (!changesById.has(id)) {
+        violations.push(`edit ${edit.id} refers to ${id}, which is not a measured change`);
+        continue;
+      }
+      if (claimedBy.has(id)) {
+        violations.push(`${id} is claimed by both edit ${claimedBy.get(id)} and edit ${edit.id}`);
+        continue;
+      }
+      claimedBy.set(id, edit.id);
+    }
+  }
+  for (const change of measured.changes) {
+    if (change.kind === "deleted") {
+      violations.push(`${describeChange(change)}; backpass cannot propose deletions - restore the file`);
+      continue;
+    }
+    if (!claimedBy.has(change.id)) {
+      violations.push(
+        `${describeChange(change)} is not part of any edit; every change needs an edit with evidence, or revert it`,
+      );
+    }
+  }
+
+  const accepted = [];
+  for (const edit of edits) {
+    const changes = edit.changeIds.map((id) => changesById.get(id)).filter(Boolean);
+    const created = changes.filter((c) => c.kind === "created");
+    const hunks = changes.filter((c) => c.kind === "hunk");
+    const files = [...new Set(hunks.map((h) => h.file))];
+
+    if (!EDIT_KINDS.includes(edit.kind)) {
+      violations.push(`edit ${edit.id}: unknown kind "${edit.kind}"`);
+      continue;
+    }
+    if (!changes.length) {
+      violations.push(`edit ${edit.id} ("${edit.title}") names no measured change`);
+      continue;
+    }
+    if (files.length > 1) {
+      violations.push(`edit ${edit.id} ("${edit.title}") changes ${files.join(" and ")}; an edit changes one file`);
+      continue;
+    }
+    if (!edit.evidence.length) {
+      violations.push(`edit ${edit.id} ("${edit.title}") carries no verbatim evidence quote`);
+      continue;
+    }
+    if (edit.kind === "extract") {
+      if (created.length !== 1 || !hunks.length || files[0] !== memoryFile.path) {
+        violations.push(
+          `edit ${edit.id}: kind "extract" must group exactly one created SKILL.md with change(s) to ${memoryFile.path}`,
+        );
+        continue;
+      }
+      if (!created[0].skill) {
+        violations.push(
+          `edit ${edit.id}: ${created[0].file} needs YAML frontmatter with \`name:\` and \`description:\``,
+        );
+        continue;
+      }
+    } else if (created.length) {
+      violations.push(`edit ${edit.id}: only kind "extract" may include a created file (${created[0].id})`);
+      continue;
+    }
+
+    // An addition is measured, not declared: text that only goes in is a new instruction.
+    const onlyAdds = hunks.every((h) => h.removed === 0);
+    if (edit.kind !== "extract" && onlyAdds && edit.transcripts < config.minGapEvidence) {
+      violations.push(
+        `edit ${edit.id} ("${edit.title}") adds a new instruction backed by ${edit.transcripts} session(s); ` +
+          `${config.minGapEvidence} are required`,
+      );
+      continue;
+    }
+
+    const file = files[0];
+    const proposed = {
+      id: edit.id,
+      kind: edit.kind,
+      file,
+      title: edit.title,
+      rationale: edit.rationale,
+      instructions: edit.instructions,
+      evidence: edit.evidence,
+      transcripts: edit.transcripts,
+      skill: created[0]?.skill || null,
+      hunks: hunks.map((h) => ({
+        id: h.id,
+        find: h.find,
+        replace: h.replace,
+        oldStart: h.oldStart,
+        oldEnd: h.oldEnd,
+        removed: h.removed,
+        added: h.added,
+        lines: h.lines,
+      })),
+      targetsMemoryFile: file === memoryFile.path,
+    };
+
+    if (isSuppressed(proposed, rejections)) {
+      // Rejections are respected until materially new evidence arrives (captain tweak 3).
+      continue;
+    }
+    accepted.push(proposed);
+  }
+
+  // Deltas are measured here, never taken from the model.
+  const running = new Map();
+  for (const edit of accepted) {
+    const before =
+      running.get(edit.file) ?? (edit.targetsMemoryFile ? memoryFile.text : (measured.originals?.get(edit.file) ?? ""));
+    let next;
+    try {
+      next = applyEdit(before, edit);
+    } catch (err) {
+      violations.push(err.message);
+      edit.applicable = false;
+      edit.deltaTokens = 0;
+      continue;
+    }
+    edit.applicable = true;
+    edit.deltaTokens = estimateTokens(next) - estimateTokens(before);
+    running.set(edit.file, next);
+  }
+
+  const projectedText = running.get(memoryFile.path) ?? memoryFile.text;
+  const budget = budgetStatus(memoryFile.text, projectedText, config.budgetTokens);
+
+  /**
+   * The budget gate has two modes (design section 6).
+   *
+   * Normally the post-edit file must fit the budget. But a file that is ALREADY over
+   * budget cannot be brought under it in one capped step - demanding that would fail
+   * every run on exactly the repos that need backpass most. There, the run is a shrink
+   * plan and the gate is progress: the edit set must be strictly net-negative.
+   */
+  budget.mode = memoryFile.tokens > config.budgetTokens ? "shrink" : "cap";
+  budget.startedOverBudget = budget.mode === "shrink";
+
+  if (budget.mode === "cap" && !budget.withinBudget) {
+    violations.push(
+      `applying every proposed edit leaves ${memoryFile.path} at ${budget.projected} tokens, ` +
+        `${budget.over} over the ${config.budgetTokens}-token budget`,
+    );
+  } else if (budget.mode === "shrink" && budget.delta >= 0) {
+    violations.push(
+      `${memoryFile.path} is already ${budget.current - config.budgetTokens} tokens over the ` +
+        `${config.budgetTokens}-token budget, so this run must shrink it, but the proposed edits ` +
+        `change it by ${budget.delta >= 0 ? "+" : ""}${budget.delta} tokens`,
+    );
+  }
+
+  for (const file of measured.stray || [])
+    notes.push(`ignored ${file}: synthesis wrote it outside the memory file and skills`);
+
+  const proposal = {
+    version: 2,
+    tool: "backpass",
+    generatedAt: new Date().toISOString(),
+    repo: { name: repo.name, root: repo.root },
+    memoryFile: { path: memoryFile.path, hash: memoryFile.hash, tokens: memoryFile.tokens },
+    budget,
+    config: {
+      budgetTokens: config.budgetTokens,
+      maxEditsPerRun: maxEdits,
+      minGapEvidence: config.minGapEvidence,
+      skillsDir: config.skillsDir,
+      analysis: config.analysis,
+      synthesis: config.synthesis,
+    },
+    stats: {
+      transcripts: summary?.analyzedSessions ?? 0,
+      harnessCounts,
+      positive: summary?.totals?.positive ?? 0,
+      negative: summary?.totals?.negative ?? 0,
+      gapClusters: summary?.totals?.gapClusters ?? 0,
+      skillExtractions: accepted.filter((e) => e.kind === "extract").length,
+    },
+    edits: accepted,
+    verdicts: Array.isArray(rawResult?.verdicts) ? rawResult.verdicts : [],
+    notes,
+  };
+
+  return { proposal, violations };
+}
+
+export function slug(text) {
+  return (
+    String(text)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60) || "skill"
+  );
+}
+
+/**
+ * Project the memory file forward under a specific set of accepted edit ids - used by
+ * both the apply surface's live budget gauge and the actual writer.
+ */
+export function projectWithDecisions(memoryText, edits, acceptedIds, capTokens) {
+  const chosen = edits.filter((e) => acceptedIds.includes(e.id) && e.targetsMemoryFile && e.applicable !== false);
+  let text = memoryText;
+  for (const edit of chosen) {
+    try {
+      text = applyEdit(text, edit);
+    } catch {
+      // Skip an edit that no longer applies; the writer reports it.
+    }
+  }
+  return { text, budget: budgetStatus(memoryText, text, capTokens) };
+}