Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
3986087
fix(acpx): treat a model the adapter turns down as model-unavailable …
dmmdea Oct 20, 2026
c22f2ad
chore(main): release backpass 0.1.37 (#222)
github-actions[bot] Oct 20, 2026
46a2169
fix(workspace): keep VCS internals and binary files out of the stagin…
dmmdea Oct 21, 2026
2125624
chore(main): release backpass 0.1.38 (#223)
github-actions[bot] Oct 21, 2026
3882b86
fix: run first Claude analysis call alone before fan-out (#226)
jadhavgaurav Oct 23, 2026
031523d
chore(main): release backpass 0.1.39 (#228)
github-actions[bot] Oct 24, 2026
9ded619
fix: deduplicate symlinked skills in the analysis index (#231)
FocalFactotum Oct 25, 2026
016e770
chore(main): release backpass 0.1.40 (#232)
github-actions[bot] Oct 26, 2026
1a1a175
fix(synthesize): report a mid-run change to a watched repo file as ob…
jadhavgaurav Oct 26, 2026
bc7bc64
chore(main): release backpass 0.1.41 (#233)
github-actions[bot] Oct 27, 2026
24f8283
fix: redact standalone apikey_ credentials (#147) (#242)
WTF-Am-ID Oct 28, 2026
a2d710b
fix: report prompt size when synthesis fails (#243)
WTF-Am-ID Oct 28, 2026
df9cdce
fix: recognize CLAUDE.md import pointers with leading headings (#240)
WTF-Am-ID Oct 29, 2026
f1015a1
chore(main): release backpass 0.1.42 (#244)
github-actions[bot] Oct 29, 2026
0c864ce
fix: mark successfully applied proposals to prevent replay (#241)
WTF-Am-ID Oct 29, 2026
3e6becc
chore: merge upstream main into house
jazz127 Oct 29, 2026
e8ce638
no-mistakes(review): Fix Claude warm-up and staged snapshot accounting
jazz127 Oct 29, 2026
2435d00
no-mistakes(document): Document Claude warm-up and synthesis change d…
jazz127 Oct 30, 2026
e531422
no-mistakes(lint): Fix formatting and workspace identity type annotation
jazz127 Oct 30, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
".": "0.1.36"
".": "0.1.42"
}
44 changes: 44 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,49 @@
# Changelog

## [0.1.42](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.41...backpass-v0.1.42) (2026-10-29)


### Bug Fixes

* recognize CLAUDE.md import pointers with leading headings ([#240](https://github.com/kunchenguid/backpass/issues/240)) ([df9cdce](https://github.com/kunchenguid/backpass/commit/df9cdcebab3fd4520a2a0d09bc696d9438f3cb24))
* redact standalone apikey_ credentials ([#147](https://github.com/kunchenguid/backpass/issues/147)) ([#242](https://github.com/kunchenguid/backpass/issues/242)) ([24f8283](https://github.com/kunchenguid/backpass/commit/24f8283930119250593dd70e6d62d67f4c8801bc))
* report prompt size when synthesis fails ([#243](https://github.com/kunchenguid/backpass/issues/243)) ([a2d710b](https://github.com/kunchenguid/backpass/commit/a2d710b5c6fe9ba529ebd5c2356a73689a38f28e))

## [0.1.41](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.40...backpass-v0.1.41) (2026-10-26)


### Bug Fixes

* **synthesize:** report a mid-run change to a watched repo file as observed ([#224](https://github.com/kunchenguid/backpass/issues/224)) ([1a1a175](https://github.com/kunchenguid/backpass/commit/1a1a17531de333d8095a944baa884a0896d5672d))

## [0.1.40](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.39...backpass-v0.1.40) (2026-10-25)


### Bug Fixes

* deduplicate symlinked skills in the analysis index ([#231](https://github.com/kunchenguid/backpass/issues/231)) ([9ded619](https://github.com/kunchenguid/backpass/commit/9ded6192cd7eae8c63e40559b7832774b3bac2fb))

## [0.1.39](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.38...backpass-v0.1.39) (2026-10-23)


### Bug Fixes

* run first Claude analysis call alone before fan-out ([#226](https://github.com/kunchenguid/backpass/issues/226)) ([3882b86](https://github.com/kunchenguid/backpass/commit/3882b86d84017bcdbf5e2cbe2e8c1fa9abeb3126))

## [0.1.38](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.37...backpass-v0.1.38) (2026-10-21)


### Bug Fixes

* **workspace:** keep VCS internals and binary files out of the staging copy ([#220](https://github.com/kunchenguid/backpass/issues/220)) ([46a2169](https://github.com/kunchenguid/backpass/commit/46a21696be63197815346d01f6d4e116c16b4c10))

## [0.1.37](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.36...backpass-v0.1.37) (2026-10-20)


### Bug Fixes

* **acpx:** treat a model the adapter turns down as model-unavailable ([#219](https://github.com/kunchenguid/backpass/issues/219)) ([3986087](https://github.com/kunchenguid/backpass/commit/398608764b6a7d40de142eafbf2e568921406fa9))

## [0.1.36](https://github.com/kunchenguid/backpass/compare/backpass-v0.1.35...backpass-v0.1.36) (2026-10-16)


Expand Down
49 changes: 35 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,8 @@ one command only; neither flag changes a config file or harness default.
Harness load paths, verified for v1:

- **Claude Code** loads `CLAUDE.md` from `CLAUDE_CONFIG_DIR` (default `~/.claude`)
and inlines `@` imports, including `~/` and absolute paths. A CLAUDE.md containing
only an import that resolves to the canonical user memory is a valid pointer, such
and inlines `@` imports, including `~/` and absolute paths. A CLAUDE.md
[import pointer](#9-which-file-is-the-weights) must resolve to the canonical user memory, such
as `@~/.agents/AGENTS.md` with the default paths.
- **Codex** loads `AGENTS.md` from `CODEX_HOME` (default `~/.codex`). It follows the
AGENTS.md convention; `@` import is not assumed.
Expand Down Expand Up @@ -213,7 +213,7 @@ whole-surface run (see [Nested memory files](#10-nested-memory-files-in-a-monore
Nothing else resolves - not a basename, a directory, a path to a SKILL.md, or an
existing file the config does not name - and an
unknown name fails, listing the valid ones, instead of falling back to the whole surface. A
configured file that contains only an `@` import is rejected rather than rewritten or silently
configured file using the [import pointer form](#9-which-file-is-the-weights) is rejected rather than rewritten or silently
mapped to its import; the error names the imported memory file, which must itself be configured
to be targeted. A correctly named skill whose file backpass cannot write - one resolving into a
location nothing may write, or in project scope one resolving outside the repository - is refused
Expand Down Expand Up @@ -429,6 +429,9 @@ orchestrating tool) - and the
analysis is shown the ledger's open gaps so it can cite an existing gap id instead of
coining a paraphrase of it.

With `jobs` greater than one, later Claude analysis calls wait for the first actual Claude
invocation to finish, even when analysis falls back to Claude from another agent.

**Every claim must carry a verbatim quote, and the quote must be in the trace.** Quoteless
items are discarded - the single most important defence against a model confabulating
influence - and so are quotes that do not actually appear in the distilled trace they claim
Expand Down Expand Up @@ -520,7 +523,9 @@ A high-reasoning synthesis run turns the aggregated gradients into concrete edit
REMOVE, REWRITE, EXTRACT→SKILL, or MOVE. The agent does not describe edits for backpass to
splice in - it makes them, with its harness's own file tools, in a **staging copy** of the
memory file and project skills under `.backpass/synthesis/` (the repo itself is read-only
to it, for grounding). Named nested files use their own staging copies and do not stage skills
to it, for grounding). Version-control internals (`.git`, `.hg`, `.svn`) and binary files
under a skill directory stay out of the copy and are read-only. Named nested files use
their own staging copies and do not stage skills
(see [Nested memory files](#10-nested-memory-files-in-a-monorepo)). backpass then diffs
against the originals and shows the agent the measured changes by id; the agent annotates each one with a title, rationale, and the
verbatim evidence behind it. Nothing textual is ever taken from the model: every hunk's
Expand Down Expand Up @@ -569,8 +574,10 @@ keeps the merged change rather than guessing.

A malformed answer or gate violation triggers a re-prompt naming the exact breach (at
most two). If those also fail, backpass **fails loudly** and preserves the latest parseable
rejected proposal, if one was produced. It never silently truncates. A harness that writes
past the staging copy into the repo is an error, never an apply.
rejected proposal, if one was produced. It never silently truncates. If a watched repository
file changes during synthesis, backpass stops without a proposal and reports the change.
When the repository file now matches the staging copy, it reports a likely direct harness
write; otherwise, the change may have come from a concurrent editor.

Not every annotate turn is an answer, and the three cases are kept apart because they call
for different things:
Expand All @@ -586,7 +593,9 @@ for different things:

When a run does fail, the advice it prints comes from the condition it ended on. If the
rejected proposal included notes, the failure prints those too instead of hiding useful
diagnostic context. Run `backpass propose` again to start a fresh synthesis.
diagnostic context. A failed synthesis prompt call reports the assembled prompt's measured
UTF-8 byte size without printing its contents. That size is diagnostic context, not a
claim that the prompt was too large. Run `backpass propose` again to start a fresh synthesis.

Token deltas shown to you are measured by backpass from the actual text - never taken from
the model's own arithmetic.
Expand Down Expand Up @@ -639,6 +648,9 @@ every skill's name and trigger line, stamps a gap it judges covered by an existi
with `coveredBySkill`, and the gap ledger corroborates those citations across observers
before synthesis is told to fix the trigger. The same coverage check retires a ledger gap
once a skill's content answers it, so a gap resolved by extraction stops resurfacing.
The analysis index lists each skill file once by realpath, keeping its first loaded path
when symlinks across harness roots share a file. Distinct files remain separate even when
their names match. This does not change [per-copy budget accounting](#6-the-budget---model-size).

Skills are protected by the same floors as the memory file: text deleted from a skill
file is a removal, and since no evidence can attribute to skill text, no deletion there
Expand Down Expand Up @@ -676,6 +688,12 @@ It cannot be combined with `--no-ui`.
The flag is repeatable: all supplied vectors are checked together as one vector, each must name at least one edit, and naming an edit twice is refused, even across flags.
Edits it does not name stay untouched, and every gate below still applies.

After a successful non-dry-run apply with at least one accepted edit, the saved proposal
records `appliedAt` and `appliedBy: "apply"`. A second apply refuses it before opening
review or writing anything. Run `backpass` again to produce a fresh proposal, including
for edits skipped in the completed review. Dry runs and reviews with no accepted edits
leave the proposal unstamped and available to review again.

The live budget gauge is not just a readout. Apply rechecks the accepted subset against
the same budget gate as synthesis: stay under the cap, or shrink if the file is already
over. An incompatible set writes nothing and does not record rejections, so you can pick
Expand All @@ -697,8 +715,9 @@ refuses the whole write if any created skill target already exists or two accept
resolve to the same file.

Skills and non-memory files are written only after every edit has composed, with the memory
file committed last. A later write failure rolls back files, skills, and loading-layout
entries created earlier in that round. If another process changes a committed file before
file committed last. A later write failure, including failure to save the proposal's
applied stamp, leaves the proposal unstamped and rolls back files, skills, and loading-layout
entries created earlier in that round so the apply can be retried. If another process changes a committed file before
rollback reaches it, apply leaves that change untouched and reports the rollback conflict.

For compatibility, proposals created by older backpass versions that do not contain a
Expand All @@ -717,9 +736,11 @@ backpass apply --decisions "e1=accepted e2=rejected:disagree" # decided elsewh
`memoryFiles` is an ordered list (default `["AGENTS.md", "CLAUDE.md"]`); the first one
that exists is the root file a run optimizes, so **AGENTS.md is canonical**. Named
[nested files](#10-nested-memory-files-in-a-monorepo) are additional weights, not
separate root files. A `CLAUDE.md` containing only the `@AGENTS.md` import (apart from
blank lines and HTML comments), or a symlink resolving to the same file, is treated as
a pointer:
separate root files. A `CLAUDE.md` is a pointer when it contains exactly one import
resolving to the primary file, such as `@AGENTS.md` or `@./AGENTS.md`, with optional
leading ATX headings (`#` through `######`), blank lines and HTML comments. Prose,
additional imports, and headings after the import make it a separate file. A symlink
resolving to the primary file is also a pointer:

- Optimizing AGENTS.md covers both harness families and the pointer stays valid. Nothing
to report.
Expand Down Expand Up @@ -800,8 +821,8 @@ weight of its own; a missing file is reported, never created:
`sampledSessions`, `minGapEvidence`, and `belowMinGapEvidence`. The count is
report-only and never gates a run.

Each nested directory keeps the pointer model above: name its canonical file, and a
sibling `AGENTS.md` or `CLAUDE.md` that only imports it needs nothing, while a sibling
Each nested directory keeps the [pointer model above](#9-which-file-is-the-weights): name its canonical file, and a
sibling `CLAUDE.md` that points to it needs nothing, while a sibling
with content of its own is warned about. An entry that is only a pointer is refused. A file listed in both
`memoryFiles` and `nestedMemoryFiles` is nested. `--target` and `--memory-file` name
exactly the files a run trains, so neither trains a nested file.
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "backpass",
"version": "0.1.36",
"version": "0.1.42",
"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",
Expand Down
6 changes: 5 additions & 1 deletion src/acpx.js
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,10 @@ function sessionCreateTimeoutError({ agent, acpxAgentArgs, timeoutMs, result })
);
}

/** What acpx prints when the adapter turns down the requested model after `session/new`. */
const MODEL_REJECTED =
/did not advertise that model|does not support this model|session\/set_(?:config_option|model) for model/i;

/**
* Availability verdicts for a failed acpx call. Only a *classifiable* failure is a
* reason to drop a candidate and fall through to the next one; anything else (a
Expand All @@ -184,7 +188,7 @@ export function classifyAcpxFailure(failure) {
if (failure.spawnError?.code === "ENOENT") return "unreachable";
const text = failure.stderr || "";
if (/AUTH_REQUIRED|authentication required/i.test(text)) return "unauthenticated";
if (/did not advertise that model|does not support this model/i.test(text)) return "model-unavailable";
if (MODEL_REJECTED.test(text)) return "model-unavailable";
if (/\b(ENOENT|command not found|not found on PATH|failed to spawn|spawn .* ENOENT)\b/i.test(text)) {
return "unreachable";
}
Expand Down
2 changes: 1 addition & 1 deletion src/agents.js
Original file line number Diff line number Diff line change
Expand Up @@ -592,7 +592,7 @@ function pinnedFailureError(role, pick, verdict, err) {
} else if (verdict) {
hint = pin;
}
const detail = err?.message ? ` (${String(err.message).split("\n")[0]})` : "";
const detail = err?.message ? ` (${String(err.message)})` : "";
return new UserError(`pinned ${role} agent ${pick.agent}${model} ${label}${detail}`, hint);
}

Expand Down
35 changes: 27 additions & 8 deletions src/analyze.js
Original file line number Diff line number Diff line change
Expand Up @@ -324,6 +324,7 @@ async function analyzeOne({
config,
repo,
modelCwd = null,
invokeAnalysis,
slot = 0,
openGapIndex = "(none yet)",
skillIndex = "(this repo has no skills)",
Expand Down Expand Up @@ -406,9 +407,11 @@ async function analyzeOne({
};
// Route effortful calls through a fresh per-transcript session so each harness's
// invocation-scoped overlay or safe fallback is applied; otherwise one-shot is cheaper.
return runModelCall(call, pick, {
sessionName: () => `backpass-analysis-${process.pid}-${slot}-${++callCounter}`,
});
return invokeAnalysis(pick, () =>
runModelCall(call, pick, {
sessionName: () => `backpass-analysis-${process.pid}-${slot}-${++callCounter}`,
}),
);
});
for (const note of result.notes || []) noteOnce(note);

Expand Down Expand Up @@ -599,11 +602,24 @@ export async function analyzeTranscripts({
path: path.isAbsolute(skill.path) ? skill.path : path.join(repo.root, skill.path),
}))
: skills,
repo.root,
);

let claudeWarmup = null;
const invokeAnalysis = (current, invoke) => {
if (current.agent !== "claude" || config.jobs <= 1) return invoke();
if (claudeWarmup) return claudeWarmup.then(invoke);
const first = invoke();
claudeWarmup = first.then(
() => {},
() => {},
);
return first;
};

let done = 0;
const evidenceTotals = { positive: 0, negative: 0, gaps: 0 };
await pool(pending, config.jobs, async (transcript, _index, slot) => {
const analyzePending = async (transcript, _index, slot) => {
const base = {
transcript: transcriptMetadata(transcript),
memoryHash,
Expand All @@ -627,25 +643,26 @@ export async function analyzeTranscripts({
config,
repo,
modelCwd,
invokeAnalysis,
slot,
openGapIndex,
skillIndex,
alsoLoaded,
});
if (result.status === "skipped") {
summary.skipped += 1;
state.writeEvidence(transcript, { ...base, status: "skipped", reason: result.reason });
summary.skipped += 1;
} else {
base.key = evidenceKey(transcript, memoryHash, result.route);
base.route = result.route;
summary.analyzed += 1;
summary.usage.push(result.usage);
state.writeEvidence(transcript, {
...base,
status: "ok",
stats: result.distilled.stats,
...result.evidence,
});
summary.analyzed += 1;
summary.usage.push(result.usage);
evidenceTotals.positive += result.evidence.positive.length;
evidenceTotals.negative += result.evidence.negative.length;
evidenceTotals.gaps += result.evidence.gaps.length;
Expand All @@ -671,7 +688,9 @@ export async function analyzeTranscripts({
info(`${color.dim(` ${done}/${pending.length} analyzed`)}`);
}
}
});
};

await pool(pending, config.jobs, analyzePending);

if (summary.quotesNotInTrace) {
warn(
Expand Down
37 changes: 29 additions & 8 deletions src/apply/writer.js
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,16 @@ function removeEmptyDirectories(directories) {
* A file is therefore applied all at once or not at all. Skills are written only after
* every accepted edit has composed, and before the files that reference them.
*/
export function applyDecisions({ proposal, decisions, repo, state, config, dryRun = false, rejectReasons = {} }) {
export function applyDecisions({
proposal,
decisions,
repo,
state,
config,
dryRun = false,
rejectReasons = {},
appliedBy = null,
}) {
const accepted = proposal.edits.filter((e) => decisions[e.id] === "accepted");
const rejected = proposal.edits.filter((e) => decisions[e.id] === "rejected");

Expand Down Expand Up @@ -711,7 +720,7 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu

if (!dryRun && canonical) {
try {
const layout = ensureSkillsLayout(repo.root, claudeSkillsLink);
const layout = ensureSkillsLayout(repo.root, claudeSkillsLink, ownedSkillPaths);
const result = results.skills.find(({ path: skillPath }) => skillPath === canonical.skill.path);
result.created = [...new Set([...result.created, ...layout.created])];
for (const w of layout.warnings) if (!results.warnings.includes(w)) results.warnings.push(w);
Expand All @@ -724,12 +733,24 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
}

// Rejections are remembered so the same edit is not re-proposed without new evidence.
if (!dryRun && rejected.length) {
const rejections = state.readRejections();
for (const edit of rejected)
recordRejection(edit, rejections, new Date().toISOString(), rejectReasons[edit.id], proposal.provenance);
state.writeRejections(rejections);
results.rejectionsRecorded = true;
if (!dryRun) {
try {
if (rejected.length) {
const rejections = state.readRejections();
for (const edit of rejected)
recordRejection(edit, rejections, new Date().toISOString(), rejectReasons[edit.id], proposal.provenance);
state.writeRejections(rejections);
results.rejectionsRecorded = true;
}
if (accepted.length && appliedBy) {
state.writeProposal({ ...proposal, appliedAt: new Date().toISOString(), appliedBy }, proposal);
}
} catch (err) {
results.failed.push({ error: err.message });
rollbackCommitted();
rollbackSkills();
return results;
}
}

return results;
Expand Down
1 change: 1 addition & 0 deletions src/commands/apply.js
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,7 @@ export async function cmdApply(ctx) {
config,
dryRun: Boolean(ctx.flags["dry-run"]),
rejectReasons,
appliedBy: "apply",
});

if (surfaceFile) await closeApplySurface(surfaceFile);
Expand Down
Loading
Loading