[BUG] Session "resume" / handoff notes get silently treated as the authoritative task list, causing severe compression of open work across session boundaries

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Session-end "resume/handoff" notes — short summaries Claude Code writes into a project file to help the next session pick up where it left off — get silently treated as the complete, authoritative state of open work, when they are actually narrative summaries that can compress or omit most of the real state without any warning.

In a multi-week project, we found a canonical checklist file with 41 open items across 10 sections. At the end of a session, Claude Code wrote a resume block whose headline read: "the §Z swipe walk (8 items) — still the last recorded gate before the prod cutover." That section was simply what the session had been actively focused on and had labeled "highest priority" — but the resume block presented it as the entirety of remaining work. 33 of the 41 open items silently dropped out of the document the next session was instructed to read first.

This was not an isolated slip. An audit of the same project on the same day found ten further independent instances of the same failure shape: a shipped production build never appearing in the deploy history log; a migration range recorded as four different, mutually contradictory values across two documents; a backlog row marked "✅ DONE" whose own body, three lines down, described an unresolved "optional" follow-up obligation still needed for a user-facing promise to actually hold true.

In every one of these eleven instances, the correct, complete information had been recorded correctly somewhere at some point. Nothing was ever undiscovered. The failure was retrieval/reconciliation across the session boundary, not knowledge — which is arguably worse, since the work of surfacing these items had already been paid for once and was lost anyway.

What Should Happen?

A resume/handoff note should never be treated — by the next session, or by the tooling's own read order — as a substitute for the canonical source file(s) it summarizes. At minimum, one of the following:

Claude Code re-derives open-item counts/state from the canonical source file at session start rather than trusting a previously-written summary's stated numbers.
Some structural distinction (even lightweight — a convention, a lint, a warning) between "narrative session summary" and "authoritative tracked state," so a cold session doesn't default to reading the former as the latter.
A built-in check, at the point a resume block is written, that flags when a stated count/scope diverges from the actual current state of the file(s) it claims to summarize — instead of letting an under-scoped summary ship silently.

We ended up building a project-level mitigation ourselves (a single file that claims exclusivity as the source of truth, with a rule that counts must always be re-derived by command, never quoted from memory or from another doc). That fixes our project, but the underlying mechanism seems worth addressing at the tool level, since "resume where I left off" is core to Claude Code's value for any multi-session project.

Error Messages/Logs

None — and that is precisely the bug. No error, warning, or discrepancy notice was ever surfaced, in any of the eleven instances, at the point the information was lost. The only reason it was caught at all was the human operator independently remembering items they'd previously asked to be tracked, and requesting a full manual audit.

The closest thing to a "log" is the divergence itself, reconstructed after the fact from the two versions of the same state:

Canonical checklist file (docs/ios-device-walk-checklist.md), open items by section:
  D3 participant sharing        11
  AA1+AA2+AA3 event request     10
  Z swipe                        8
  B older iOS surface            7
  lightbox / downloads           3
  D2 attribution                 1
  BB upload retry                1
  ---
  TOTAL                         41

Resume block written the same session, headline:
  "1. THE §Z SWIPE WALK (8 items). STILL THE LAST RECORDED GATE
   BEFORE THE PROD CUTOVER"

Notably, the same resume block that lost the 33 items also contained a rule, written by Claude Code in an earlier session, explicitly warning against this exact failure mode ("the written code and the project story are mine to have under control; do not fall back on operator memory to catch a claim I could have checked") — and violated it in the same commit that wrote it.

Steps to Reproduce

This is a structural/behavioral failure rather than a deterministic one-shot repro, but the pattern is consistent and reproducible in shape:

Create a project with a canonical tracked-items file containing many open items spread across several distinct sections/headings (e.g. 40+ items across 8–10 headings).
Set up the project's onboarding chain the way Claude Code itself recommends: a top-level instructions file that tells a fresh session to read a "context" or "resume" file before doing anything else.
Work a full session focused heavily on just one of those sections (e.g. mark it "highest priority" in conversation or in project docs), while the other sections remain untouched but still genuinely open.
At session end, have Claude Code write its usual resume/handoff note summarizing "what to do next."
Diff the resume note's stated scope/count of open work against the actual current state of the canonical tracked-items file from step 1.
Start a new session. Per the onboarding chain from step 2, it reads the resume note as its primary orientation, without independently re-deriving counts from the canonical file.
Observe: the new session's understanding of "what's left to do" matches the resume note's narrowed scope, not the canonical file's actual state — and nothing in the flow surfaces the discrepancy.

In our real-world case, step 5's diff was 8 stated vs. 41 actual, and step 7 went uncaught for roughly 16 hours until the human operator manually flagged missing items from memory, triggering a full audit that found ten more independent instances of the same shape.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

5

Claude Code Version

2.1.259

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

Scale/context. This is a real, multi-week production project (not a synthetic test case), with dozens of sessions across several weeks. The project follows Claude Code's own recommended onboarding pattern (a top-level instructions file pointing to a context/resume file to read first), so this isn't an unusual or misconfigured setup.

The self-contradiction detail. The resume block that lost the 33 items also contains a rule, written by Claude Code itself in an earlier session, that directly warns against this exact failure mode. It was violated in the same commit that wrote it. We think this is useful evidence that the issue isn't a knowledge gap the model can simply "try harder" to avoid — the model can articulate the correct rule and still not have any structural mechanism enforcing it across a session boundary.

Why we suspect this is under-reported. By construction, this failure mode is invisible unless someone happens to independently notice missing work — which is exactly what caught it here (human memory, not tooling). We'd guess this is happening silently in other long-running Claude Code projects without ever surfacing, simply because most divergences are smaller and less likely to be caught by chance the way this one was.

Open question on our own mitigation. Our project-level fix (a single exclusivity-claiming source-of-truth file with mandatory re-derivation) is new and hasn't yet been proven durable across many session boundaries — the real test is a cold session naturally reading that file first, unprompted, every time, rather than defaulting back to whatever handoff note is freshest. We don't have long-term confirmation yet that it holds.

Environment. Claude Code version / OS: [please fill in — happy to add if useful].

Happy to share the exact commit hashes, the full audit trail, or the other ten instances in more detail if that would help.