fix(memory): recognize CLAUDE.md symlinks as pointers

[SomSamantray]

Intent

Fix GitHub issue #50: backpass warns that a CLAUDE.md symlink to AGENTS.md is a separate memory file even though both paths resolve to the same file. Analyze the root cause, implement the fix, add regression coverage, run the full project checks, and open a pull request. Before changes, confirm the issue is unassigned, has no PR in any state, and no commenter says they are working on it or asks to take it; stop without changes if any condition fails. Start from clean, updated main on a brand-new branch; do not reuse any prior fix branch, including docs/57-quick-start-lavish-axi. Read and follow CONTRIBUTING.md and PR guidelines, use main as the PR base, use the required no-mistakes process, do not include a Compound Engineering badge, disclose AI assistance in the PR, and double-check every file pushed. If pushing upstream is denied, fork under SomSamantray and open the PR against kunchenguid/backpass. Track the PR until checks and reviews are settled; do not clear repo-blocked reviews, labels, CLA, merge protection, or first-time workflow approval.

AI disclosure for the PR: Implemented and tested with assistance from OpenAI Codex.

What Changed

• Treat a CLAUDE.md symlink resolving to the primary memory file as a pointer, so it no longer triggers a separate-file warning.
• Document symlink pointers and add regression coverage confirming only AGENTS.md is written.

Risk Assessment

✅ Low: The change recognizes a CLAUDE.md symlink that resolves to the configured primary file, with focused regression coverage and no material issues found.

Testing

Ran the real CLI against isolated repos: a CLAUDE.md symlink to AGENTS.md produced no consolidation warning, while distinct files still produced one. Ran the focused memory-resolution regression test. The disposable runtime and repos were removed; no full-suite checks were run in this test phase.

• Live validation: ✅ go - 2 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Run backpass in a repo where CLAUDE.md symlinks to AGENTS.md; it completes without a separate-memory warning.	✅ pass	live	Live CLI: symlinked memory files
Run backpass in a repo with distinct AGENTS.md and CLAUDE.md files; it still warns that CLAUDE.md is separate and will not be updated.	✅ pass	live	Live CLI: separate memory files

Evidence: Live CLI: symlinked memory files

backpass v0.1.34 · symlink · budget 5,000 tok · since all
· no transcripts associated with this repo

No agent transcripts are associated with this repo yet.
  `backpass scan --since all` widens the time window; --include-cursor-ide adds the Cursor IDE store.

Evidence: Live CLI: separate memory files

backpass v0.1.34 · separate · budget 5,000 tok · since all
warn CLAUDE.md is a separate memory file and will NOT be updated - only AGENTS.md is optimized. To cover both, consolidate: move its content into AGENTS.md and make CLAUDE.md a pointer (a single line: @AGENTS.md).
· no transcripts associated with this repo

No agent transcripts are associated with this repo yet.
  `backpass scan --since all` widens the time window; --include-cursor-ide adds the Cursor IDE store.

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 2 of 2 scenarios driven live against the product

Scenario	Result	Live	Evidence
Run backpass in a repo where CLAUDE.md symlinks to AGENTS.md; it completes without a separate-memory warning.	✅ pass	live	Live CLI: symlinked memory files
Run backpass in a repo with distinct AGENTS.md and CLAUDE.md files; it still warns that CLAUDE.md is separate and will not be updated.	✅ pass	live	Live CLI: separate memory files

• node bin/backpass.js --since all --no-ui in disposable repos with symlinked and separate memory files, using Node v22.14.0
• node --import ./test/helpers/hermetic-config.js --test test/memory-resolution.test.js

✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → no changes applied ✅

• ⚠️ Could not run the configured lint, formatter, or typecheck checks: pnpm failed while creating its Corepack cache under /usr/local/share/corepack, and the available global ESLint is v6.4.0, which cannot read this repository’s configuration. Prettier and tsc are not available on PATH, and project-local dependencies are absent.

🔧 No changes applied.
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.

Issues

Closes #50

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

_{Reviews (1) · Last reviewed commit: "no-mistakes(document): Document canonica..." · Reviewed by Greptile}

[kunchenguid]

Speaking as Kun's firstmate:

I reviewed the diff against main (9255906), approved the first-time fork CI, and everything came back green: CI on both OSes (pnpm run check runs the lint your local no-mistakes lint step couldn't), the generated-files guard, and the no-mistakes check, whose attestation is bound to this head (6694fd5). The live CLI evidence covers both the symlink case and the two-separate-files case.

contract-class: restore. A CLAUDE.md symlinked to AGENTS.md is one file. On main it was wrongly warned about as a separate memory file (#50). Now it's classified like the documented @AGENTS.md pointer. Writes still go only to AGENTS.md (the new test checks that the symlink is left alone), and two genuinely separate files still warn.

VISION (per rule):

1. Evidence is the only currency: n/a (no evidence or corroboration change).
2. The human owns the weights: aligns (the write target is unchanged and nothing new is written).
3. Nothing the model says is taken on faith: aligns (what's shown to a person now matches the filesystem, because the old warning described a separate file that didn't exist).
4. The budget is the constraint, not a setting: n/a.
5. It reads what you already have and owns nothing: aligns (a local realpath check, fail-soft on error).
6. Failure is loud and named: aligns (the real divergence warning stays; only the false one goes away). The root fix is in resolveMemoryFiles, and the regression test fails without it.
7. Scope / align-resist: aligns (doesn't widen writes or silently widen a named run's scope).

[kunchenguid]

Speaking as Kun's firstmate: this is merged. Thank you @SomSamantray — really appreciate you taking the time on this.