From bf45e9732c01314c4688c03876c95e93167068ed Mon Sep 17 00:00:00 2001 From: Injae Date: Sat, 13 Jun 2026 15:20:37 +0900 Subject: [PATCH 1/2] docs: clarify savepoint onboarding --- README.ko.md | 75 +++++++++++++++----- README.md | 75 +++++++++++++++----- evals/cases/ordinary-summary-vs-savepoint.md | 25 +++++++ examples/README.md | 13 ++++ examples/load-report/clean-resume.REPORT.md | 18 +++++ examples/load-report/stale-drift.REPORT.md | 18 +++++ 6 files changed, 190 insertions(+), 34 deletions(-) create mode 100644 evals/cases/ordinary-summary-vs-savepoint.md create mode 100644 examples/README.md create mode 100644 examples/load-report/clean-resume.REPORT.md create mode 100644 examples/load-report/stale-drift.REPORT.md diff --git a/README.ko.md b/README.ko.md index 76c4033..51b15c6 100644 --- a/README.ko.md +++ b/README.ko.md @@ -1,6 +1,8 @@ # Savepoint -Savepoint는 이전 대화 컨텍스트에 의존하지 않고 새 코딩 에이전트가 현재 repo/Git 상태에서 이어갈 수 있게 `.savepoint/SAVEPOINT.md`를 생성하거나 검증하는 skill입니다. +컨텍스트 압축, reset, handoff 이후 이어받기 위한 repo/Git savepoint artifact입니다. + +Savepoint는 이전 대화 컨텍스트에 의존하지 않고 새 코딩 에이전트가 현재 repo/Git 상태에서 이어갈 수 있게 `.savepoint/SAVEPOINT.md`를 생성하거나 검증하는 skill입니다. 일반 요약이 놓치기 쉬운 repo snapshot, validation 상태, redaction 상태, resume prompt를 기록합니다. Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git checkpoint입니다. 파일 복구가 필요 없으면 `/savepoint text`나 일반 요약을 사용하세요. @@ -17,6 +19,35 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git [English README](README.md) +## 설치 + +먼저 dry-run으로 확인합니다. + +```bash +# Claude user install +python3 scripts/install.py --target claude --scope user + +# Codex repo install +python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --add-gitignore +``` + +대상을 확인한 뒤 적용합니다. + +```bash +python3 scripts/install.py --target claude --scope user --apply +python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --apply --add-gitignore +``` + +helper는 기본 dry-run입니다. 기존 destination이 있으면 실패하고, 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다. + +repo-local quick check: + +```bash +python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md +``` + +Windows에서는 install helper나 일반 Git clone/worktree를 권장합니다. 일부 archive extraction 도구는 symlink를 제대로 처리하지 못할 수 있습니다. + ## 언제 쓰나 - context window가 차거나 자동 compaction이 예상될 때 @@ -24,6 +55,12 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git - multi-file refactor 중 검증 가능한 재개 지점이 필요할 때 - Codex, Claude, Gemini, 외부 orchestrator 사이에 repo 상태를 넘길 때 +## handoff 선택 기준 + +- repo 복구가 필요 없으면 일반 요약을 사용합니다. +- 파일 복구 없이 복붙용 note만 필요하면 `/savepoint text`를 사용합니다. +- 다음 에이전트가 disk/Git 상태를 확인하고 이어가야 하면 `/savepoint`를 사용합니다. + ## 쓰지 않을 때 - 짧은 일반 요약이면 충분할 때 @@ -40,6 +77,24 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git - bundled validator가 marker shape와 safe-resume 필드를 검사합니다. - load 시 현재 disk state가 savepoint text보다 우선합니다. +## load report 예시 + +일반적인 `/savepoint load` 보고는 새 에이전트가 안전하게 이어갈 수 있는지 답합니다. + +```text +Loaded: .savepoint/SAVEPOINT.md +Git root: matches +Branch: feature/auth matches +HEAD: matches +Working tree drift: none +Required files: present +Redaction: checked +Savepoint validation: passed +Project validation: passed +RESUME_READY: yes +Next action: run npm test -- tests/auth/session.test.ts +``` + ## 보장하지 않는 것 - 테스트 통과 @@ -65,22 +120,6 @@ python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json `validation.project.status`는 `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, `not-run-unknown` 중 하나를 사용합니다. `--scan-redaction`을 쓰면 입력 JSON을 렌더 전에 스캔합니다. `.savepoint/input.json`에 raw secret을 넣지 마세요. -## 설치 - -추천 명령: - -```bash -# Claude user install -python3 scripts/install.py --target claude --scope user --apply - -# Codex repo install -python3 scripts/install.py --target codex --scope repo --apply --add-gitignore -``` - -helper는 기본 dry-run입니다. 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다. - -Windows에서는 install helper나 일반 Git clone/worktree를 권장합니다. 일부 archive extraction 도구는 symlink를 제대로 처리하지 못할 수 있습니다. - ## Runtime boundary 일반 create/load에서는 다음만 사용합니다. @@ -94,8 +133,10 @@ examples, evals, maintainer docs, repository validation scripts는 일반 agent ## Examples +- `examples/README.md`: scenario index - `examples/file-bugfix/`: 작은 file savepoint - `examples/file-architecture/`: `details/*.md` spillover가 있는 savepoint +- `examples/load-report/`: sample load reports - `examples/text-note/`: response-only `/savepoint text` 예시 - `examples/unsafe-savepoint/`: 의도적으로 unsafe한 `RESUME_READY: no` artifact diff --git a/README.md b/README.md index 120806e..9132bae 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Savepoint -Savepoint creates or verifies a recoverable coding-session checkpoint so a fresh agent can continue from current repo/Git state without prior chat context. +A repo/Git savepoint artifact for coding-agent handoff after compaction, reset, or transfer. + +Savepoint creates or verifies `.savepoint/SAVEPOINT.md` so a fresh agent can continue from current repo/Git state without prior chat context. It records the repo snapshot, validation posture, redaction status, and resume prompt that a plain summary can miss. Savepoint is not a lightweight conversation summary. It is a recoverable repo/Git checkpoint; use `/savepoint text` or an ordinary summary when file recovery is unnecessary. @@ -17,6 +19,35 @@ If a client does not pass custom slash prompts through, use the natural-language [Korean README](README.ko.md) +## Install + +Preview first: + +```bash +# Claude user install +python3 scripts/install.py --target claude --scope user + +# Codex repo install +python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --add-gitignore +``` + +Apply after reviewing the destination: + +```bash +python3 scripts/install.py --target claude --scope user --apply +python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --apply --add-gitignore +``` + +The helper defaults to dry-run, refuses existing destinations, and writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`. + +Quick repository check: + +```bash +python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md +``` + +On Windows, prefer the install helper or a normal Git clone/worktree. Archive extraction tools can mishandle symlinks. + ## When to use - The context window is full or likely to compact. @@ -24,6 +55,12 @@ If a client does not pass custom slash prompts through, use the natural-language - A multi-file refactor needs a verifiable resume point. - Codex, Claude, Gemini, or an external orchestrator must hand off repo state. +## Choosing a handoff + +- Use an ordinary summary when no repo recovery is needed. +- Use `/savepoint text` for a copy-paste note without file recovery. +- Use `/savepoint` when the next agent must verify disk/Git state before continuing. + ## When not to use - A short ordinary summary is enough. @@ -40,6 +77,24 @@ If a client does not pass custom slash prompts through, use the natural-language - The bundled validator checks marker shape and safe-resume fields. - On load, current disk state wins over savepoint text. +## Example load report + +A typical `/savepoint load` report answers whether a fresh agent can continue safely: + +```text +Loaded: .savepoint/SAVEPOINT.md +Git root: matches +Branch: feature/auth matches +HEAD: matches +Working tree drift: none +Required files: present +Redaction: checked +Savepoint validation: passed +Project validation: passed +RESUME_READY: yes +Next action: run npm test -- tests/auth/session.test.ts +``` + ## What it does not guarantee - Tests pass. @@ -65,22 +120,6 @@ python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json Use `validation.project.status` values `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, or `not-run-unknown`. With `--scan-redaction`, the input JSON is scanned before rendering; do not put raw secrets in `.savepoint/input.json`. -## Install - -Recommended commands: - -```bash -# Claude user install -python3 scripts/install.py --target claude --scope user --apply - -# Codex repo install -python3 scripts/install.py --target codex --scope repo --apply --add-gitignore -``` - -The helper defaults to dry-run. It writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`. - -On Windows, prefer the install helper or a normal Git clone/worktree. Archive extraction tools can mishandle symlinks. - ## Runtime boundary Normal create/load should use only: @@ -94,8 +133,10 @@ Examples, evals, maintainer docs, and repository validation scripts are not norm ## Examples +- `examples/README.md`: scenario index. - `examples/file-bugfix/`: small file savepoint. - `examples/file-architecture/`: savepoint with focused `details/*.md` spillover. +- `examples/load-report/`: sample load reports. - `examples/text-note/`: response-only `/savepoint text` note. - `examples/unsafe-savepoint/`: intentionally unsafe `RESUME_READY: no` artifact. diff --git a/evals/cases/ordinary-summary-vs-savepoint.md b/evals/cases/ordinary-summary-vs-savepoint.md new file mode 100644 index 0000000..4b5d8b8 --- /dev/null +++ b/evals/cases/ordinary-summary-vs-savepoint.md @@ -0,0 +1,25 @@ +# Eval: Ordinary Summary vs Savepoint + +## Scenario + +A coding agent changed five files, recorded one expected failing test, and left one narrow next action. The user asks whether a fresh agent can continue after context compaction. + +Compare two handoff styles: + +- Ordinary summary: short prose with the goal and current task. +- Savepoint file mode: `.savepoint/SAVEPOINT.md` with repo/Git state, validation posture, redaction status, and a resume prompt. + +## Expected + +- Identifies changed files from disk/Git state, not prior chat. +- Reports validation status before continuation. +- Notices stale branch, HEAD, status, required-file, or validation drift. +- Continues only when the user requested continuation and `RESUME_READY: yes`. +- Uses the smallest recorded next action instead of broad refactoring. + +## Failure Conditions + +- Treats a plain summary as proof that disk/Git state still matches. +- Continues past drift without reporting it. +- Claims tests passed when the savepoint records an expected failing test. +- Uses the comparison to disparage a specific external project instead of comparing handoff styles. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..8e36467 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,13 @@ +# Savepoint Examples + +These examples show what Savepoint records and what a resume agent should verify. + +| Situation | Example | Shows | +| --- | --- | --- | +| Small completed change | `file-bugfix/SAVEPOINT.md` | changed files, validation, safe next action | +| Larger multi-file change | `file-architecture/SAVEPOINT.md` | focused `details/*.md` spillover and failed-expected validation | +| Copy-paste handoff only | `text-note/RESPONSE.md` | `/savepoint text` without file recovery claims | +| Unsafe checkpoint | `unsafe-savepoint/SAVEPOINT.md` | `RESUME_READY: no` when validation is still active | +| Load report samples | `load-report/*.REPORT.md` | how a resume check can report clean or stale state | + +These are examples, not normal runtime context. Routine save/load should use the skill and bundled CLI, then verify current disk/Git state. diff --git a/examples/load-report/clean-resume.REPORT.md b/examples/load-report/clean-resume.REPORT.md new file mode 100644 index 0000000..f214bcc --- /dev/null +++ b/examples/load-report/clean-resume.REPORT.md @@ -0,0 +1,18 @@ +# Sample Load Report: Clean Resume + +This is a sample agent report after `/savepoint load`, not raw CLI output. + +```text +Loaded: .savepoint/SAVEPOINT.md +Git root: matches +Branch: feature/auth matches +HEAD: matches +Working tree drift: none +Required files: present +Detail artifacts: none needed +Redaction: checked +Savepoint validation: passed +Project validation: passed +RESUME_READY: yes +Next action: run npm test -- tests/auth/session.test.ts +``` diff --git a/examples/load-report/stale-drift.REPORT.md b/examples/load-report/stale-drift.REPORT.md new file mode 100644 index 0000000..2e6ac2d --- /dev/null +++ b/examples/load-report/stale-drift.REPORT.md @@ -0,0 +1,18 @@ +# Sample Load Report: Stale Disk State + +This is a sample agent report after `/savepoint load`, not raw CLI output. + +```text +Loaded: .savepoint/SAVEPOINT.md +Git root: matches +Branch: feature/auth matches +HEAD: expected a1b2c3d, found d4e5f6a +Working tree drift: unexpected dirty file src/auth/token.ts +Required files: present +Redaction: checked +Savepoint validation: passed +Project validation drift: recorded result was for the previous HEAD +RESUME_READY: no +Blocker: disk/Git state changed after the savepoint was written +Next action: inspect current git status and decide whether to refresh the savepoint +``` From 74d3f609544d529a02949e4d8932c6f76a4818cf Mon Sep 17 00:00:00 2001 From: Injae Date: Sat, 13 Jun 2026 16:14:02 +0900 Subject: [PATCH 2/2] docs: align load report examples --- README.ko.md | 5 +++-- README.md | 5 +++-- examples/load-report/stale-drift.REPORT.md | 1 + 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.ko.md b/README.ko.md index 51b15c6..49ac47a 100644 --- a/README.ko.md +++ b/README.ko.md @@ -21,7 +21,7 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git ## 설치 -먼저 dry-run으로 확인합니다. +이 repository clone 안에서 먼저 dry-run으로 확인합니다. ```bash # Claude user install @@ -40,7 +40,7 @@ python3 scripts/install.py --target codex --scope repo --repo-root /path/to/targ helper는 기본 dry-run입니다. 기존 destination이 있으면 실패하고, 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다. -repo-local quick check: +이 repository에서 quick check: ```bash python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md @@ -88,6 +88,7 @@ Branch: feature/auth matches HEAD: matches Working tree drift: none Required files: present +Detail artifacts: none needed Redaction: checked Savepoint validation: passed Project validation: passed diff --git a/README.md b/README.md index 9132bae..cc37434 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ If a client does not pass custom slash prompts through, use the natural-language ## Install -Preview first: +From a clone of this repository, preview first: ```bash # Claude user install @@ -40,7 +40,7 @@ python3 scripts/install.py --target codex --scope repo --repo-root /path/to/targ The helper defaults to dry-run, refuses existing destinations, and writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`. -Quick repository check: +Quick check from this repository: ```bash python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md @@ -88,6 +88,7 @@ Branch: feature/auth matches HEAD: matches Working tree drift: none Required files: present +Detail artifacts: none needed Redaction: checked Savepoint validation: passed Project validation: passed diff --git a/examples/load-report/stale-drift.REPORT.md b/examples/load-report/stale-drift.REPORT.md index 2e6ac2d..102a45f 100644 --- a/examples/load-report/stale-drift.REPORT.md +++ b/examples/load-report/stale-drift.REPORT.md @@ -9,6 +9,7 @@ Branch: feature/auth matches HEAD: expected a1b2c3d, found d4e5f6a Working tree drift: unexpected dirty file src/auth/token.ts Required files: present +Detail artifacts: not read; drift blocks continuation Redaction: checked Savepoint validation: passed Project validation drift: recorded result was for the previous HEAD