mirror of https://github.com/OthmanAdi/planning-with-files.git synced 2026-09-14 16:09:40 +08:00

Files

T

OthmanAdi b49ea488fb feat: make the Stop hook and session recovery fire everywhere, add long-run injection controls

The Stop scalar never dispatched on macOS or Linux (the PowerShell branch
was always selected because check-complete.ps1 ships on every platform)
and was a silent no-op anywhere CLAUDE_SKILL_DIR was unset (the :- install
path fallback can never substitute because the probed variable is always a
non-empty string). Both the legacy completion advisory and the v3
completion gate were dead in those environments. The scalar now selects
targets by file existence and dispatches by platform, PowerShell only
under MINGW/MSYS/CYGWIN, sh elsewhere. Windows output is unchanged.
Patched in all 14 SKILL.md variants that carry the scalar.

session-catchup probed a ~/.claude/projects name that Claude Code never
writes for POSIX paths (leading dash stripped) or paths containing an
underscore (replaced with a dash), so recovery after /clear silently
found nothing there. The mapper now probes the exact spelling first,
keeps both legacy spellings for stores created by older versions, and
settles ambiguity via the cwd recorded in the newest session file.
Propagated to every shipped copy including the older-generation root,
.hermes, and .mastracode scripts.

Also: the attestation SHA cache is keyed on the absolute plan path so two
projects can no longer share a slot and report a false PLAN TAMPERED;
resolve-plan-dir.ps1 reaches parity with the sh resolver (slug filter,
task_plan.md requirement in the newest-dir scan, fail-closed containment);
ledger-append.sh no longer truncates summaries mid-codepoint (UTF-8-safe
trim via iconv with a pure-sh fallback).

New long-run features, all opt-in or additive: structure-aware injection
(PWF_INJECT=smart or an inject-smart .mode token) keeps the active phase,
phase counts, and the last three decisions in the window late in long
plans; a Next Step section in both plan templates plus a sixth reboot
question; session-catchup annotates tool results (ok or FAILED with the
first error line) instead of only listing attempts.

Infrastructure: macos-latest joins the CI matrix, a BSD-userland
simulation harness runs the script fleet without realpath, readlink,
flock, or sha256sum on the Linux leg, and .gitattributes pins LF for
scripts. SEO surfaces: llms.txt rewritten as a Q&A page, three
problem-query docs pages, plugin.json and CITATION.cff keyword hygiene.

Suite grows from 217 to 301 passed, 11 skipped, on Windows and both
existing CI legs; default hook output stays byte-identical to v2.43
(legacy invariant proven by the existing invariant tests).

2026-07-21 21:17:19 +02:00

4.5 KiB

Raw Permalink Blame History

Claude Code lost context after compaction: how to recover and prevent it

Compaction replaces your conversation with a summary. The summary keeps the broad strokes and drops the working state: which phase you were in, which fixes were already applied, which approaches already failed. If Claude Code seems to have amnesia after /compact or an automatic compaction, that is what happened. This page explains why it happens, how to recover the current task, and how to make the next compaction a non-event.

The mechanism described here is planning-with-files, a skill that keeps the plan on disk in three markdown files and re-injects it into context every turn. Overview: README.

Why did Claude Code forget my plan after /compact?

Because the plan lived only in the context window. Compaction, whether manual /compact or autoCompact when the window fills, summarizes the transcript to free space. Summaries compress, and exact phase status, error history, and decisions are the first details to go. Afterwards the model knows roughly what the task was, but not where you were in it.

The context window is volatile memory. Anything that exists only there is equally lost to /clear, crashes, and compaction. The durable fix is the same for all three: write the working state to disk and read it back mechanically.

The 3-file pattern

For every complex task, the skill maintains three files in your project root:

task_plan.md      → phases and checkboxes; the resume point
findings.md       → research notes and decisions
progress.md       → session log and test results

Plain markdown, gitignored by default. Because the files live on the filesystem and not in the transcript, compaction cannot touch them. Claude Code runs 5 lifecycle hooks around them: UserPromptSubmit, PreToolUse, PostToolUse, Stop, and PreCompact.

The PreCompact flush hook

The skill registers a PreCompact hook with matcher *, so it fires on both manual /compact and autoCompact. When task_plan.md is present, the hook:

reminds the agent to flush in-context progress to progress.md before compaction completes
prints the active Plan-SHA256 when the plan is attested, so the post-compaction session can verify it resumes the approved plan
stays silent when no plan exists, and always exits 0, so it never blocks compaction

The protection model is deliberate: the plan does not survive compaction unchanged inside the context. The plan is on disk, and it is re-read after compaction. On the next turn the UserPromptSubmit hook re-injects the current plan between ===BEGIN PLAN DATA=== and ===END PLAN DATA=== markers, so the compacted session starts anchored to the same phases.

How do I recover context after compaction or /clear?

If the planning files were on disk before the wipe, recovery is mechanical rather than conversational:

Session catchup checks the IDE session store for the previous session (~/.claude/projects/ for Claude Code).
It finds when the planning files were last updated and extracts the conversation that happened after that point, the part most likely lost.
It shows a catchup report. Then run git diff --stat, read the three files, update them, and continue.

Scope note: session catchup replays transcript and points at the files; the durable phase state itself comes from reading task_plan.md. In the project's internal recovery benchmark (v1, author-run), a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent. Method and disclosed limits: docs/evals.md.

Can I reduce how often compaction happens?

Yes. Disable auto-compact in Claude Code settings and compact or /clear on your own schedule:

{ "autoCompact": false }

With the planning files on disk this is a safe default, because clearing stops being fatal.

Install

Claude Code, plugin route (ships the skill, hooks, and slash commands):

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Every other agent, one line via the Agent Skills standard:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Full route matrix and verification: README and docs/installation.md.

4.5 KiB Raw Permalink Blame History