From cd2834068fee5bb8d59966d36a43580cc4c4a479 Mon Sep 17 00:00:00 2001 From: Michael Gardner Date: Tue, 14 Apr 2026 21:18:57 -0700 Subject: [PATCH] chore(backup): adopt backup/sessions/ convention via migrate tool Mechanical migration from migrate_to_backup_sessions in the shared scripts submodule. Creates backup/sessions/, adds exports/ to .gitignore, bumps submodule pointer 4976849 -> cf36a0f. No source code, build system, or formal-doc changes. (Alire auto-generated tzif_config files in config/ are deliberately left out of this commit.) --- .gitignore | 8 ++++++ backup/sessions/README.md | 50 ++++++++++++++++++++++++++++++++++ backup/sessions/raw/.gitignore | 12 ++++++++ scripts/python/shared | 2 +- 4 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 backup/sessions/README.md create mode 100644 backup/sessions/raw/.gitignore diff --git a/.gitignore b/.gitignore index da29eea..f926b1a 100644 --- a/.gitignore +++ b/.gitignore @@ -198,3 +198,11 @@ env/ ENV/ # Temporary *.tgz +# Claude Code session exports / ephemeral scratch space. +# The CLI /export command has been broken for some time (writes +# 0-byte stubs); durable session artifacts now live in +# backup/sessions/ via the session_snapshot tool in +# scripts/python/shared. The exports/ directory is kept as a local +# scratch path for cross-project context bouncing, but its contents +# are not git-tracked. See backup/sessions/README.md. +exports/ diff --git a/backup/sessions/README.md b/backup/sessions/README.md new file mode 100644 index 0000000..1a76ceb --- /dev/null +++ b/backup/sessions/README.md @@ -0,0 +1,50 @@ +# backup/sessions/ + +Durable, git-tracked archive of session artifacts for this project. + +## What lives here + +Three kinds of files, all using the same filename convention so +chronological sort works across kinds: + +``` +__ +``` + +| Kind | How it gets here | Source of the content | +|---|---|---| +| `*_alignment_note.md` | Written directly by the assistant when a slice opens with a design decision. Committed with the slice's first commit. | The assistant's pre-coding review of the frozen docs + GPT check. | +| `*_pr_review_package.md` | Written directly by the assistant before a PR is opened. Committed with the slice's PR. | The assistant's self-contained review document for GPT. | +| `*` (time-driven snapshots) | Mirrored here by `scripts/python/shared/session_snapshot`, typically via the `/snapshot` custom slash command. | A Claude Code memory file from `~/.claude/projects//memory/`, preserved verbatim after the `__` prefix. | + +Filenames sort naturally by UTC timestamp regardless of how many +different kinds coexist in the directory. Recovery of any file is a +plain `cp` with prefix strip (see +`scripts/python/shared/session_snapshot/README.md` for the +`--restore` tool or the manual procedure). + +## Relationship to `backup/sessions/raw/` + +`raw/` is **gitignored** and holds compressed full-session `.jsonl` +backups produced by `scripts/python/shared/jsonl_snapshot`. Those +files are large (~10 MB per snapshot) and intended for external +storage. Git-tracked files stay up here in `backup/sessions/`. + +See `scripts/python/shared/jsonl_snapshot/README.md` for the full +forensic-tier workflow. + +## What this is NOT + +- **Not the Claude Code `/export` command output.** The CLI + `/export` has been broken for some time; this directory is the + workflow that replaces it. +- **Not a full conversation transcript.** Memory files are + curated recap summaries written by the assistant at key + workflow points. Use `jsonl_snapshot` and the raw session + `.jsonl` under `~/.claude/projects/.../.jsonl` for + forensic recovery of verbatim conversation content. +- **Not a replacement for the Claude Code memory system.** + Memory files in `~/.claude/projects/.../memory/` remain the + auto-loaded source of strategic context at session start. + This directory is the off-machine-durable backup copy that + survives a local-state loss. diff --git a/backup/sessions/raw/.gitignore b/backup/sessions/raw/.gitignore new file mode 100644 index 0000000..f348f72 --- /dev/null +++ b/backup/sessions/raw/.gitignore @@ -0,0 +1,12 @@ +# Everything in this directory is gitignored on purpose: compressed +# session jsonls are large binary blobs that belong on external +# storage, not in git history. The directory itself is tracked +# (via this .gitignore file being the only tracked file) so fresh +# clones get a usable target for jsonl_snapshot without needing to +# run mkdir. +# +# See ../README.md and scripts/python/shared/jsonl_snapshot/README.md +# for the workflow that targets this directory. + +* +!.gitignore diff --git a/scripts/python/shared b/scripts/python/shared index 4976849..cf36a0f 160000 --- a/scripts/python/shared +++ b/scripts/python/shared @@ -1 +1 @@ -Subproject commit 4976849bdad8eea988ba4420004c9cd3ca37f351 +Subproject commit cf36a0f38b407a3f3c65ea622c42ef6eeca3c795