backpass AGENTS.md

Project agent memory

backpass is an npm CLI that runs a "backward pass" over a repo's agent memory files: it discovers past agent-session transcripts tied to the repo, analyzes them, and proposes evidence-backed edits to AGENTS.md / CLAUDE.md under a token budget.

Orientation

• VISION.md is the acceptance policy: what a change must be true to, and its closing accept/resist tests. VISION-ANSWERS.md records the hypotheticals the author ruled on and why, so a change that argues one of those calls should go the other way starts there.
• README.md documents the user-facing surface; src/cli.js is the authoritative flag list.
• The pipeline is one stage per module, in order: src/discovery/ -> src/sample.js (cap) -> src/distill.js -> src/analyze.js -> src/consolidate.js (gap-identity merge, inside foldForRun) -> src/fold.js -> src/synthesize.js (with src/workspace.js + src/diff.js) -> src/proposal.js -> src/apply/. Each module's header comment explains its role; read those before changing a stage.
• User-facing step names are the training-loop terms, not the module names: discover = "collect samples", analyze = "calculate loss", fold = "aggregate gradients", synthesize = "gradient descent" (STAGE_LABELS in src/tui/render.js). Internal keys, event names, and the typed subcommands (scan, analyze, propose) keep their short names; only what the user reads changes. Never introduce a multi-word subcommand.
• Zero runtime dependencies, ESM, no build step. Node >= 22.5 (for node:sqlite).
• pnpm is the package manager; pnpm run check runs lint, format:check, typecheck, and tests. All tests are offline and use fixtures under test/fixtures/. Supply-chain settings (release-age cooldown, build-script deny) live in pnpm-workspace.yaml.
• Releases are automated by release-please (.github/workflows/release-please.yml, npm trusted publishing). Never hand-edit CHANGELOG.md or .release-please-manifest.json; CI guards reject PRs that touch them.
• .github/workflows/no-mistakes-required.yml is a thin caller of the shared kunchenguid/no-mistakes/.github/actions/require-no-mistakes composite action, pinned to an immutable commit SHA and never @main. Enforcement logic and tests live upstream in the no-mistakes repository; change enforcement there, never by copying it locally, and bump the pin in a deliberate separate PR. This repo still owns the on:, concurrency, permissions, job name, and author-exemption if:. The action binds the attestation to the head SHA, so a PR whose body no-mistakes did not rewrite for the current head goes red by contract: push through git push no-mistakes.