Address savepoint doc review

Author: dd3ok

README.ko.md

@@ -36,7 +36,7 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git
 
 - file mode는 `.savepoint/SAVEPOINT.md`를 씁니다.
 - artifact는 repo/Git snapshot, `## Resume Prompt`, 마지막 `SAVEPOINT_V1` marker block을 포함합니다.
-- `REDACTION_CHECKED: yes` 전에 생성된 artifact의 secret-like 값을 스캔합니다.
+- `REDACTION_CHECKED: yes` 전에 generated artifact를 pattern-based secret-like scan으로 검사합니다.
 - bundled validator가 marker shape와 safe-resume 필드를 검사합니다.
 - load 시 현재 disk state가 savepoint text보다 우선합니다.
 

README.md

@@ -36,7 +36,7 @@ If a client does not pass custom slash prompts through, use the natural-language
 
 - File mode writes `.savepoint/SAVEPOINT.md`.
 - The artifact includes a repo/Git snapshot, `## Resume Prompt`, and one final `SAVEPOINT_V1` marker block.
-- Generated artifacts are scanned for secret-like values before `REDACTION_CHECKED: yes`.
+- Generated artifacts receive pattern-based secret-like scans before `REDACTION_CHECKED: yes`.
 - The bundled validator checks marker shape and safe-resume fields.
 - On load, current disk state wins over savepoint text.
 

scripts/validate-repo.py

@@ -292,24 +292,30 @@ def validate_references(self) -> None:
             "SAVEPOINT_V1",
             "RESUME_READY: yes",
             "Run the bundled CLI; do not inspect implementation source during normal use.",
+            "Resolve `<savepoint-skill-dir>` before running commands",
             "python3 <savepoint-skill-dir>/scripts/savepoint.py save",
+            "inspect <path> --json",
             "append `--force` only when",
             "generated, untracked, valid default artifact",
             "`validation.project.status`",
             "`not-run-justified`",
             "`failed-expected`",
             "`no-file`, `no files`, `in-response`, or `in the response`",
+            "Prepare `.savepoint/input.json` as in Save, then run",
             "## Load / Resume",
             "For inspect-only requests, do not clean up by default.",
             "Continue only when the user requested continuation and `RESUME_READY` is `yes`",
-            "Read `references/contract.md` only when",
+            "Read references only when normal CLI use is insufficient",
+            "`references/contract.md`",
+            "`references/safety.md`",
+            "`references/template.md`",
         ]
         for phrase in required_skill_phrases:
             if phrase not in skill_text:
                 self.fail(f"SKILL.md missing required policy: {phrase}")
         skill_line_count = len(skill_text.splitlines())
-        if not 55 <= skill_line_count <= 65:
-            self.fail(f"SKILL.md should stay concise at 55-65 lines, got {skill_line_count}")
+        if skill_line_count > 65:
+            self.fail(f"SKILL.md should stay concise at <=65 lines, got {skill_line_count}")
         for phrase in [
             "direct flags such as",
             "do not combine direct flags",
@@ -394,6 +400,7 @@ def validate_readme_format(self) -> None:
             "AGENTS.md",
             "docs/reference/savepoint-contract.md",
             "Savepoint is not a lightweight conversation summary.",
+            "pattern-based secret-like scans",
         ]:
             if phrase not in readme_text:
                 self.fail(f"README.md missing entry: {phrase}")
@@ -410,6 +417,7 @@ def validate_readme_format(self) -> None:
             "AGENTS.md",
             "docs/reference/savepoint-contract.md",
             "Savepoint는 가벼운 대화 요약이 아닙니다.",
+            "pattern-based secret-like scan",
         ]:
             if phrase not in readme_ko_text:
                 self.fail(f"README.ko.md missing entry: {phrase}")

skills/savepoint/SKILL.md

@@ -6,7 +6,7 @@ argument-hint: "[save|load|text] [next-session focus]"
 
 # Savepoint
 
-Create or load a recoverable repo/Git checkpoint without relying on prior chat context.
+Create/load a recoverable repo/Git checkpoint without prior chat context.
 
 Modes:
 - default or `save`: create or refresh `.savepoint/SAVEPOINT.md`
@@ -17,31 +17,31 @@ If slash prompts are unavailable, treat natural-language `$savepoint` requests t
 
 ## Rules
 
-- During save/load verification, stay in savepoint scope and do not edit application code.
+- During save/load verification, stay in savepoint scope; do not edit application code.
+- Resolve `<savepoint-skill-dir>` before running commands; Claude Code: `${CLAUDE_SKILL_DIR}`.
 - Do not run `/new`, `/status`, PTY/session rotation, threshold policy, or background process control.
 - Run the bundled CLI; do not inspect implementation source during normal use.
-- Prefer current files, Git state, and durable state files over chat memory.
-- Do not paste transcripts, full diffs, long logs, shell history, PRDs, ADRs, issues, or commits.
-- Reference existing artifacts by path, URL, branch, or commit.
-- Redact API keys, tokens, cookies, credentials, private keys, passwords, `.env` values, and PII as `<redacted>`; do not place raw secrets in semantic input files.
+- Prefer current disk/Git/durable state over chat memory.
+- Do not paste transcripts, diffs, logs, shell history, PRDs, ADRs, issues, or commits; cite paths, URLs, branches, or commits.
+- Redact API keys, tokens, cookies, credentials, private keys, passwords, `.env` values, and PII as `<redacted>`; never put raw secrets in input.
 - File savepoints must end with exactly one `SAVEPOINT_V1` marker block.
-- Keep top-level `SAVEPOINT.md` compact. Use generated `details/*.md` only when needed for recovery.
+- Keep top-level `SAVEPOINT.md` compact; use generated `details/*.md` only when needed.
 
 ## Create / Save
 
-1. Treat provided focus text, if any, only as next-session focus.
-2. Capture repo/Git state and write compact input JSON with `goal`, `current_state`, `next_action`, `files_to_inspect_first`, and `unresolved_blockers`; start with `python3 <savepoint-skill-dir>/scripts/savepoint.py init-input --output .savepoint/input.json` if blank.
-3. Set `validation.project.status` to one of `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, or `not-run-unknown`. For `failed-expected`, include failed command/result/summary evidence, an explicit reason, and next validation command. For `not-run-justified`, include a reason and next validation command.
-4. Run `python3 <savepoint-skill-dir>/scripts/savepoint.py save --input .savepoint/input.json --output .savepoint/SAVEPOINT.md --assert-no-active-commands --scan-redaction --validate`. Inside this repository, `python3 scripts/savepoint.py save ...` also works.
+1. Treat any focus text only as next-session focus.
+2. Capture repo/Git state in compact input JSON with `goal`, `current_state`, `next_action`, `files_to_inspect_first`, and `unresolved_blockers`; if blank, start with `python3 <savepoint-skill-dir>/scripts/savepoint.py init-input --output .savepoint/input.json`.
+3. Set `validation.project.status` to `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, or `not-run-unknown`. `failed-expected` needs failed command/result/summary evidence, reason, and next validation command. `not-run-justified` needs reason and next validation command.
+4. Run `python3 <savepoint-skill-dir>/scripts/savepoint.py save --input .savepoint/input.json --output .savepoint/SAVEPOINT.md --assert-no-active-commands --scan-redaction --validate`; in this repo, `python3 scripts/savepoint.py save ...` also works.
 5. Inspect only the generated `.savepoint/SAVEPOINT.md`.
 6. Report exact path, `RESUME_READY`, blockers if any, and the first next action.
 
-`savepoint.py save` exit code `2` can still mean a not-ready `SAVEPOINT.md` was written. Inspect the file, report blockers, and do not continue unless `RESUME_READY: yes`.
+Exit code `2` may still write a not-ready `SAVEPOINT.md`; inspect it, report blockers, and do not continue unless `RESUME_READY: yes`.
 
 ## Load / Resume
 
-1. Read the selected savepoint: user path first, then `.savepoint/SAVEPOINT.md`.
-2. Verify cwd, Git root, branch, short HEAD, status, and diff against current disk state.
+1. Select the user path first, otherwise `.savepoint/SAVEPOINT.md`; run `python3 <savepoint-skill-dir>/scripts/savepoint.py inspect <path> --json`.
+2. Verify cwd, Git root, branch, short HEAD, status, and diff against disk state.
 3. Disk state wins over savepoint text. Report drift before edits.
 4. Continue only when the user requested continuation and `RESUME_READY` is `yes`, with no blocking drift or missing required file.
 5. For inspect-only requests, do not clean up by default.
@@ -50,16 +50,12 @@ If slash prompts are unavailable, treat natural-language `$savepoint` requests t
 
 Use text mode only when the user explicitly asks for copy-paste, text-only, `no-file`, `no files`, `in-response`, or `in the response`.
 
-Run `python3 <savepoint-skill-dir>/scripts/savepoint.py text --input .savepoint/input.json`.
+Prepare `.savepoint/input.json` as in Save, then run `python3 <savepoint-skill-dir>/scripts/savepoint.py text --input .savepoint/input.json`.
 
-Text mode must not claim `.savepoint/SAVEPOINT.md` was written, repo recovery is guaranteed, or `RESUME_READY: yes`.
+Text mode must not claim `.savepoint/SAVEPOINT.md` was written, recovery is guaranteed, or `RESUME_READY: yes`.
 
 ## Advanced Cases
 
-Read `references/contract.md` only when marker semantics, cleanup, stale savepoints, detail spillover, overwrite adoption, or safe-resume edge cases are unclear.
+Read references only when normal CLI use is insufficient: `references/contract.md` for marker/safe-resume/cleanup/staleness/detail/overwrite edge cases, `references/safety.md` for secret-like paths, and `references/template.md` when the renderer is unavailable.
 
 For refresh, append `--force` only when the existing file is the generated, untracked, valid default artifact `.savepoint/SAVEPOINT.md` and the user did not ask to preserve history; otherwise preserve or ask.
-
-Read `references/safety.md` only when secret redaction or secret-like paths are involved.
-
-Read `references/template.md` only when the renderer is unavailable and a manual artifact is unavoidable.