backpass 0.1.8 → 0.1.9

package/README.md

@@ -148,9 +148,14 @@ instruction covers.
 most important defence against a model confabulating influence. Negative evidence (a
 visible violation) is weighted highest.
 
-Results are cached per transcript, keyed to both the transcript's content _and_ the memory
-file's hash: edit the weights and the evidence correctly re-computes; change nothing and
-the next run is free.
+Results are cached per transcript, keyed to both the transcript's content _and_ the effective
+memory-file set hash: edit the weights and the evidence correctly re-computes; change nothing
+and the next run is free. A memory-file edit therefore reanalyzes without `--force` - that is
+not a cache miss, it is the cache doing its job - and the run says so on stderr, naming the
+old and new hash, so a "0 reused" line reads as "the file changed" rather than "reuse is
+broken." Evidence files that are not refreshed remain on disk but are excluded while their
+hash is stale. They become eligible again if the memory-file set returns to that hash;
+evidence for transcripts included in the new analysis is replaced with fresh judgments.
 
 ### 4. Aggregate gradients - deterministic, no model
 
@@ -159,6 +164,13 @@ Evidence is grouped by instruction, giving each one a positive/negative count an
 gaps across sessions are clustered, and clusters seen in fewer than `minGapEvidence`
 sessions (default 2) are dropped. One bad session never rewrites the weights.
 
+Only evidence judged against the _current_ memory-file set hash is folded into a proposal. A
+transcript that fell out of this run's sample - the time window, `maxTranscripts`, or the
+transcript itself being gone - can leave an older evidence file on disk under a hash the
+memory-file set no longer has; that file is left untouched, but it does not count toward this
+run's session total or instruction scores, or add a gap observation, until it is current
+again.
+
 Those sessions are counted across runs, not per run: every gap sighting is kept in
 `.backpass/gap-ledger.json` by gap and session, so a gap seen in one session today and in
 another session next week graduates on the later run. The same session never counts twice,
@@ -277,8 +289,10 @@ Apply preflights every accepted edit before writing. The proposal was measured a
 exact version of your memory file, so apply first checks the file still exists and is still
 that version. If it was removed or changed since - you pulled, edited it by hand, or another
 agent did - the edits no longer describe what is on disk, so nothing is written and you are
-told to run `backpass` again to re-propose against the current file. Within a run every file
-is composed from one version: it takes every accepted edit or none of them. Apply also
+told to run `backpass` again to re-propose against the current file. That rerun reanalyzes
+transcripts against the file that exists now; it does not reuse the stale judgments behind
+the refused proposal. Within a run every file is composed from one version: it takes every
+accepted edit or none of them. Apply also
 refuses the whole write if any created skill target already exists or two accepted paths
 resolve to the same file.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/analyze.js

@@ -185,7 +185,16 @@ async function pool(items, limit, worker) {
 export async function analyzeTranscripts({ transcripts, memoryFile, config, repo, memoryHash, force = false }) {
   const state = config.state;
   const pending = [];
-  const summary = { total: transcripts.length, cached: 0, analyzed: 0, skipped: 0, failed: 0, usage: [] };
+  const summary = {
+    total: transcripts.length,
+    cached: 0,
+    analyzed: 0,
+    skipped: 0,
+    failed: 0,
+    usage: [],
+    staleMemoryHash: 0,
+  };
+  const priorHashes = new Set();
 
   for (const transcript of transcripts) {
     const existing = state.readEvidence(transcript.id);
@@ -193,9 +202,23 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
       summary.cached += 1;
       continue;
     }
+    // Distinguish "no prior evidence" from "prior evidence exists, but it was judged
+    // against a memory-file set that no longer matches" - a re-analysis here, not a miss.
+    if (existing?.status === "ok" && existing.memoryHash && existing.memoryHash !== memoryHash) {
+      summary.staleMemoryHash += 1;
+      priorHashes.add(existing.memoryHash);
+    }
     pending.push(transcript);
   }
 
+  if (summary.staleMemoryHash) {
+    info(
+      `${color.yellow("·")} ${summary.staleMemoryHash} transcript(s) have evidence from a previous ` +
+        `memory-file set (${[...priorHashes].join(", ")} -> ${memoryHash}); that evidence is stale, not ` +
+        `missing, and reuse resumes once this pass re-judges it against the current memory-file set`,
+    );
+  }
+
   if (!pending.length) {
     emitProgress("analyze:start", { pending: 0, cached: summary.cached, total: transcripts.length, jobs: config.jobs });
     emitProgress("analyze:done", summary);

package/src/apply/writer.js

@@ -76,7 +76,8 @@ function memoryFileSnapshot(proposal, repo) {
         file: relative,
         error:
           `${relative} no longer exists, so its edits no longer describe the file on disk; nothing was written. ` +
-          `Run \`backpass\` to re-propose against the current repository.`,
+          `Run \`backpass\` to re-propose against the current repository - that pass reanalyzes transcripts ` +
+          `against the file that exists now, it does not reuse the judgments behind this proposal.`,
       },
     };
   }
@@ -94,7 +95,8 @@ function memoryFileSnapshot(proposal, repo) {
       error:
         `${relative} changed after this proposal was made (${expected} -> ${observed}), so its edits ` +
         `no longer describe the file on disk; nothing was written. Run \`backpass\` to re-propose ` +
-        `against the current ${relative}.`,
+        `against the current ${relative} - that pass reanalyzes transcripts against the new file, it does ` +
+        `not reuse the stale judgments behind this proposal.`,
     },
   };
 }

package/src/commands/bootstrap.js

@@ -1,7 +1,8 @@
 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 { UserError, color, info, json, out, warn } from "../logger.js";
+import { resolveMemoryFiles } from "../memory.js";
 import { emitProgress } from "../progress.js";
 import { ProposalViolation } from "../proposal.js";
 import { synthesizeProposal } from "../synthesize.js";
@@ -52,14 +53,25 @@ export async function bootstrapRun(ctx, deps = {}) {
   const seed = [{ path: canonical, text: starter.text }];
   if (pointer) seed.push({ path: pointer, text: renderPointer(canonical) });
   const seeded = writeBootstrapFiles(repo.root, seed);
+  const resolved = resolveMemoryFiles(repo.root, config.memoryFiles);
   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`);
 
+  const canonicalSkipped = seeded.skipped.some((entry) => entry.file === canonical);
+  if (canonicalSkipped || resolved.primary?.path !== starter.path || resolved.primary?.text !== starter.text) {
+    throw new UserError(
+      `${canonical} changed while backpass was bootstrapping it`,
+      "run `backpass` again to analyze the memory file that now exists",
+    );
+  }
+  const memoryFile = resolved.primary;
+  const memoryHash = resolved.hash;
+
   emitProgress("memory", {
-    path: starter.path,
-    tokens: starter.tokens,
+    path: memoryFile.path,
+    tokens: memoryFile.tokens,
     budget: config.budgetTokens,
-    units: starter.units.length,
+    units: memoryFile.units.length,
   });
 
   const result = {
@@ -78,10 +90,10 @@ export async function bootstrapRun(ctx, deps = {}) {
 
   result.summary = await analyze({
     transcripts,
-    memoryFile: starter,
+    memoryFile,
     config,
     repo,
-    memoryHash: starter.hash,
+    memoryHash,
     force: Boolean(ctx.flags.force),
   });
   info(
@@ -89,7 +101,7 @@ export async function bootstrapRun(ctx, deps = {}) {
       `${result.summary.skipped} too short · ${result.summary.failed} failed`,
   );
 
-  const folded = await foldForRun(ctx, starter);
+  const folded = await foldForRun(ctx, memoryFile, memoryHash);
   config.state.writeSummary(folded);
   emitProgress("fold:done", {
     instructions: folded.instructions.length,
@@ -102,7 +114,7 @@ export async function bootstrapRun(ctx, deps = {}) {
 
   try {
     const { proposal } = await synthesize({
-      memoryFile: starter,
+      memoryFile,
       summary: folded,
       config,
       repo,

package/src/commands/propose.js

@@ -15,11 +15,21 @@ import { discoverForRun } from "./scan.js";
  * 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.
+ *
+ * Evidence is also filtered to `memoryHash`: a transcript's evidence file is rewritten
+ * every time it is re-analyzed against a changed memory file, but a transcript that fell
+ * out of this run's sample (window, cap, or discovery drift) leaves its last evidence file
+ * on disk under whatever hash it was last judged against. That leftover file is real and
+ * reusable the moment its transcript is re-analyzed - or immediately, if the memory file's
+ * bytes return to that hash - but folding it into *this* proposal would score it against
+ * an instruction index it was never judged against (aliases are positional) and inflate
+ * `analyzedSessions` with a session this run never touched. Nothing is migrated, rewritten,
+ * or deleted here - only excluded from this run's fold.
  */
-export async function foldForRun(ctx, memoryFile) {
+export async function foldForRun(ctx, memoryFile, memoryHash) {
   const { state, minGapEvidence, gapLedgerMaxAge } = ctx.config;
   const evidence = state.listEvidence();
-  const relevant = evidence.filter((e) => e.memoryPath === memoryFile.path);
+  const relevant = evidence.filter((e) => e.memoryPath === memoryFile.path && e.memoryHash === memoryHash);
 
   const ledger = state.readGapLedger();
   recordGapObservations(ledger, relevant);
@@ -39,11 +49,11 @@ export async function runProposal(ctx, precomputed = null) {
   // folding, and agent resolution can all fail before synthesis starts; none of those
   // failures may leave an older proposal available to apply as if it came from this run.
   config.state.clearProposal();
-  const { file } = precomputed || primaryMemoryFile(repo, config);
+  const { file, hash } = precomputed || primaryMemoryFile(repo, config);
   const transcripts = precomputed?.transcripts || (await discoverForRun(ctx)).transcripts;
 
   const foldStarted = Date.now();
-  const summary = await foldForRun(ctx, file);
+  const summary = await foldForRun(ctx, file, hash);
   config.state.writeSummary(summary);
   emitProgress("fold:done", {
     instructions: summary.instructions.length,