mempalace-code 1.1.0__tar.gz → 1.2.0__tar.gz

mempalace_code-1.2.0/.claude/prompts/codex-hardening-review.md

@@ -0,0 +1,48 @@
+Round __ROUND__: targeted Codex verification for feature "__FEATURE_NAME__" in "__FEATURE_SCOPE__".
+
+Task slug: __TASK_SLUG__
+Evidence output path: __OUTPUT_FILE__
+Scope source: __SCOPE_SOURCE__
+Scoped diff artifact: __SCOPED_DIFF_FILE__
+Scoped files manifest: __SCOPED_FILES_FILE__
+
+Goal:
+Find high-impact issues in the task-scoped diff without modifying files.
+Prioritize signal over volume.
+
+Scope discipline:
+- Read first:
+  1. scoped diff artifact: `__SCOPED_DIFF_FILE__`
+  2. scoped files manifest: `__SCOPED_FILES_FILE__`
+  3. previous round report: `docs/audits/__TASK_SLUG__-round-__PREVIOUS_ROUND__.md` if it exists
+  4. backlog context: __KNOWN_ISSUES_SCOPE__
+- Treat the scoped diff artifact and scoped files manifest as authoritative for this review.
+- This review runs in an isolated snapshot that mirrors only scoped files and task-local context. Ignore unrelated repo changes outside that scope.
+- __ROUND_FOCUS__
+- Stay inside "__FEATURE_SCOPE__" and directly affected dependencies.
+- Start from the scoped diff and expand only to code paths it can realistically break.
+- Do NOT scan unrelated repo areas or turn this into repo-wide cleanup.
+
+Review bar:
+- Report only concrete, current, bounded issues.
+- Prioritize user-visible breakage, data/security issues, contract drift, race conditions, and missing regression tests on bug-prone touched paths.
+- Do not report formatting, naming, cleanup-only refactors, speculative guards, weak polish nits, or pre-existing out-of-scope issues unless they are P0/P1 or directly causal.
+- Zero findings is normal.
+
+Output format:
+1. New Findings
+2. Known Issues Map Status
+3. Evidence Reviewed
+4. Residual Risks
+5. Convergence Recommendation
+6. Suggested Claude Follow-Up
+
+Rules:
+- Search strategy: use `rg -l` (list matching files) first to identify
+  relevant files, then read or search within specific files. Never run
+  unbounded content searches across broad directory trees.
+- At most 3 findings unless the feature is clearly unstable.
+- Include severity (`P0`-`P3`), confidence (`High` / `Medium` / `Low`), and file:line for each surviving finding.
+- Suppress duplicate findings using the previous audit and matching backlog items.
+- Keep findings concise and high-signal.
+- Do not edit files. Claude will act on your report.

mempalace_code-1.2.0/.claude/prompts/codex-plan-review.md

@@ -0,0 +1,45 @@
+You are an independent second-pass reviewer for planning artifacts in this repository.
+
+Task slug: __TASK_SLUG__
+Plan file under review: __PLAN_FILE__
+Evidence output path: __OUTPUT_FILE__
+
+Goal:
+Review the current implementation plan for execution readiness before coding begins.
+Do not modify repository files. Produce a concise report that Claude can act on.
+
+Required workflow:
+1. Read `AGENTS.md`, `CLAUDE.md`, `.memory-bank/README.md`, and `__PLAN_FILE__`.
+2. Read the smallest relevant canonical docs/rules/templates referenced by the plan.
+3. Use semantic navigation tools first for symbol lookups when available (`definition`, `references`, `hover`). Use grep/read for string searches, markdown, shell, JSON, or when semantic tools are unavailable.
+4. Search the codebase for affected files, existing patterns, accepted dependencies, prior plans, and relevant subsystem boundaries before judging the plan.
+5. Use repository evidence first. Do not rely on unsupported assumptions.
+6. Stay scoped to this task. Do not turn this into repo-wide cleanup.
+
+Check for:
+- missing affected files or subsystems
+- missing schema/data, backend, frontend, API, state, auth, cache/event, docs, or cleanup work
+- blockers hidden as `TBD`, "investigate later", or deferred design work
+- acceptance criteria that are not observable
+- verification map gaps or manual-only verification for behavior changes
+- conflicts with architecture, repo rules, or accepted patterns
+- unnecessary complexity or unjustified new dependencies
+- assumptions that should be called out explicitly
+
+Output format:
+1. Verdict: `READY` or `NEEDS_CHANGES`
+2. Critical Gaps
+3. Non-blocking Improvements
+4. Missing Evidence To Gather
+5. Suggested Plan Deltas
+6. Blocking Open Questions
+7. Recommended Next Step
+
+Rules:
+- Search strategy: use `rg -l` (list matching files) first to identify
+  relevant files, then read or search within specific files. Never run
+  unbounded content searches across broad directory trees.
+- Report only evidence-backed issues.
+- Prefer no finding over weak finding.
+- If no blocking issues remain, say so explicitly.
+- Do not edit files.

mempalace_code-1.2.0/.claude/settings.json

@@ -0,0 +1,73 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'git commit'; then echo '[pre-commit] Running verify gate...'; _s=$(mktemp); _u=$(mktemp); git diff --name-only --cached | sort >\"$_s\"; git diff --name-only | sort >\"$_u\"; MIXED=$(comm -12 \"$_s\" \"$_u\"); rm -f \"$_s\" \"$_u\"; if [ -n \"$MIXED\" ]; then echo '[warn] Staged files have unstaged changes (CI will not see them):'; echo \"$MIXED\" | sed 's/^/  /'; echo ''; fi; _tf=$(mktemp); if python -m pytest tests/ -x -q >\"$_tf\" 2>&1; then echo '[ok] pytest passed'; rm -f \"$_tf\"; else echo '[fail] pytest failed:'; tail -40 \"$_tf\"; rm -f \"$_tf\"; exit 1; fi; _tf=$(mktemp); if ruff check mempalace/ tests/ >\"$_tf\" 2>&1; then echo '[ok] ruff check passed'; rm -f \"$_tf\"; else echo '[fail] ruff check failed:'; cat \"$_tf\"; rm -f \"$_tf\"; exit 1; fi; _tf=$(mktemp); if ruff format --check mempalace/ tests/ >\"$_tf\" 2>&1; then echo '[ok] ruff format passed'; rm -f \"$_tf\"; else echo '[fail] ruff format failed:'; cat \"$_tf\"; rm -f \"$_tf\"; exit 1; fi; if git diff --name-only --cached | grep -q 'BACKLOG.yaml'; then if ! backlog validate --file docs/BACKLOG.yaml >/dev/null 2>&1; then echo '[fail] backlog validate failed'; exit 1; else echo '[ok] backlog validate passed'; fi; fi; fi",
+            "timeout": 300000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'git commit'; then if git diff --name-only --cached | grep -qE '^mempalace/mcp_server\\.py$' && ! git diff --name-only --cached | grep -qE '^docs/AGENT_INSTALL\\.md$'; then echo '[warn] MCP server changed without AGENT_INSTALL.md update'; fi; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'git commit'; then if git diff --name-only --cached | grep -qE '^mempalace/storage\\.py$' && ! git diff --name-only --cached | grep -qE '^docs/STORAGE\\.md$'; then echo '[warn] storage.py changed without STORAGE.md update'; fi; fi",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | grep -oE '\"file_path\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' | head -1 | sed 's/.*\"\\([^\"]*\\)\"$/\\1/'); if [ -n \"$FILE\" ]; then echo \"[$(date +%H:%M:%S)] Modified: $FILE\" >> /tmp/claude-edits.log 2>/dev/null || true; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'BACKLOG\\.yaml'; then backlog validate --file docs/BACKLOG.yaml 2>&1 || true; fi",
+            "timeout": 10000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'mempalace/mcp_server\\.py'; then echo '[info] MCP server edited - update docs/AGENT_INSTALL.md if tool signatures changed'; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'mempalace/storage\\.py'; then echo '[info] storage.py edited - run tests: python -m pytest tests/test_storage.py -v'; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'mempalace/miner\\.py'; then echo '[info] miner.py edited - run tests: python -m pytest tests/test_miner.py -v'; fi",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'mempalace/lang_detect\\.py|mempalace/chunker\\.py'; then echo '[info] Language support edited - run: python -m pytest tests/test_lang_detect.py tests/test_chunker.py -v'; fi",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'mempalace (mine|health|repair|restore)'; then if echo \"$CLAUDE_TOOL_OUTPUT\" 2>/dev/null | grep -qiE 'error|fail|corrupt|missing'; then echo '[alert] Palace operation may have failed - consider running /palace-health'; fi; fi",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

mempalace_code-1.2.0/.claude/skills/_shared/commit-checkpoint.md

@@ -0,0 +1,121 @@
+# Commit Checkpoint — Shared Procedure
+
+Shared commit procedure for all skills that commit.
+Referenced by `/task-plan`, `/task-hardening`, `/ship`, and any future committing skill.
+
+**Purpose:** Prevent missed files, wrong staging, and lost work by cross-referencing the edit log against git state before every commit.
+
+## Procedure
+
+### Step 1: Collect modified files from all sources
+
+Cross-reference three sources to build the complete file list:
+
+**Source A — edit log** (hook-populated, most complete):
+```bash
+cat /tmp/claude-edits.log 2>/dev/null | grep "Modified:" | sed 's/.*Modified: //' | sort -u
+```
+
+**Source B — task state** (skill-populated, survives log rotation):
+```bash
+cat "${AUTOPILOT_TASK_STATE:-/tmp/claude-task-state-${task_slug:-unknown}.json}" 2>/dev/null | grep -oP '"[^"]+\.(py|md|json|yaml)"' | tr -d '"' | sort -u
+```
+
+**Source C — git diff** (ground truth):
+```bash
+git diff --name-only && git diff --name-only --cached
+```
+
+If sources A and B are both empty or missing, source C is sufficient. If any source lists a file the others don't, investigate before proceeding.
+
+### Step 2: Cross-reference with git status
+
+```bash
+git status --porcelain
+```
+
+Compare the two lists. Flag discrepancies:
+
+- **Edited but unstaged** (`M` or `?? ` in git status, present in edit log): these MUST be staged or explicitly excluded with a reason.
+- **Staged but not in edit log** (in git status `M ` or `A ` index column, absent from edit log): warn — this may be another agent's work or a stale change. Verify before committing.
+- **Untracked task artifacts** (`?? .tasks/` or `?? .protocols/`): these MUST be staged if they belong to the current task.
+
+If any discrepancy is found, list it explicitly before proceeding. Do not silently skip mismatched files.
+
+### Step 3: Stage explicitly
+
+Stage ONLY the files that belong to this commit, by name:
+
+```bash
+git add <file1> <file2> ...
+```
+
+**NEVER** use `git add .` or `git add -A`. If the edit log shows files you did not intend to modify, investigate before staging.
+
+### Step 4: Review staged diff
+
+```bash
+git diff --cached --stat
+```
+
+Verify the staged file count and names match expectations. If a file is unexpectedly large or unexpected, investigate.
+
+### Step 5: Commit
+
+```bash
+git commit -m "<message>"
+```
+
+Use the calling skill's commit message format (e.g., `docs(plan):`, `chore(<slug>):`, `fix:`, etc.).
+
+**Git trailers (optional but encouraged):** When the task involved rejecting alternatives or discovering constraints, append trailers to the commit message body. These help future sessions avoid re-exploring dead ends:
+
+```
+Rejected: <approach> — <reason>
+Constraint: <invariant discovered during this task>
+Scope-risk: <boundary that future changes should be careful about>
+```
+
+Queryable later via `git log --grep="Rejected:"` or `git log --grep="Constraint:"`.
+
+### Step 6: Post-commit verification
+
+```bash
+git status --short | grep -E "^\?\? \.(tasks|protocols)/TASK-" && echo "ERROR: task artifacts left unstaged — amend now" || echo "ok: no orphaned task artifacts"
+```
+
+If task artifacts remain unstaged:
+1. Stage them: `git add .tasks/TASK-<slug>/ .protocols/TASK-<slug>/`
+2. Amend: `git commit --amend --no-edit`
+3. Re-run the check.
+
+### Step 7: Clear session state
+
+```bash
+: > /tmp/claude-edits.log
+: > "${AUTOPILOT_TASK_STATE:-/tmp/claude-task-state-${task_slug:-unknown}.json}"
+```
+
+This prevents the next commit checkpoint from seeing stale entries from a previous task unit.
+
+## Agent File Coordination
+
+Before editing a file in a multi-agent session, check for another agent's uncommitted changes:
+
+```bash
+grep "Modified:.*<target-file>" /tmp/claude-edits.log 2>/dev/null
+```
+
+If the file appears in the edit log but is not yet committed (present in `git status --porcelain` output), another agent may have uncommitted work on it. In that case:
+- **Warn** in chat: "File `<path>` has uncommitted changes from another agent."
+- **Do not overwrite** — either wait for the other agent to commit, or coordinate with the user.
+- If you must edit the file, note the conflict potential in the task state file.
+
+This is a cheap coordination mechanism that works on a single branch without requiring multi-branch isolation.
+
+## Rules
+
+- Every committing skill MUST follow this procedure instead of writing ad-hoc commit logic.
+- If Step 2 reveals files from another agent's uncommitted work, do NOT stage them. Warn and proceed with only your own files.
+- If the edit log contains files outside the task scope, investigate — they may be side effects from a shared hook or linter auto-fix.
+- The edit log is the primary record. Task state is the secondary record. Git status is the ground truth. All three should agree before committing.

mempalace_code-1.2.0/.claude/skills/_shared/mode-classification.md

@@ -0,0 +1,25 @@
+# Mode Classification — 5-Axis Triage
+
+Shared procedure for classifying a task as `lite`, `standard`, or `strict`.
+Referenced by `/task-plan` and `/task-hardening`.
+
+## Axes
+
+Judge these five axes from repo evidence (not user-supplied size labels):
+
+- **boundary risk**: storage operations, schema migrations, embedding model changes, MCP tool contracts, CLI breaking changes, backup/restore paths
+- **ambiguity**: multiple plausible implementations, unclear API design, unresolved contract decisions, or (for hardening) ambiguity still remaining in the behavior
+- **blast radius**: number of subsystems/files likely affected and coupling to shared helpers (storage.py, mcp_server.py, miner.py)
+- **verification difficulty**: whether the change needs non-trivial regression coverage or multi-step validation
+- **failure cost**: user data loss, palace corruption, embedding drift, hard-to-reverse regressions
+
+## Decision Rule
+
+- `lite` only if all five axes are low and the implementation path looks obvious
+- `strict` if any sensitive boundary is touched or any axis is clearly high
+- otherwise `standard`
+- if still uncertain, choose `standard`
+
+## Size Labels
+
+Do not trust user-provided size markers like `[S]`, `[M]`, `XS`, or `low` as authoritative. Treat them as weak hints only. A user-supplied size estimate never overrides repo-evidenced risk.

mempalace_code-1.2.0/.claude/skills/_shared/task-state.md

@@ -0,0 +1,83 @@
+# Task State Handoff — Shared Procedure
+
+Shared state persistence for skills running multi-step workflows.
+Referenced by `/task-plan`, `/task-hardening`, and any future multi-step skill.
+
+**Purpose:** Survive context compaction by writing task state to disk. After compaction, the agent reads this file instead of relying on degraded context memory to recall which files were modified, what phase it's in, and what decisions were made.
+
+## State File
+
+Location: `/tmp/claude-task-state-<SLUG>.json` (e.g., `/tmp/claude-task-state-MINE-CSHARP.json`)
+
+Use the task slug in the filename to avoid collisions when multiple sessions or autopilot instances run in parallel. If `AUTOPILOT_TASK_STATE` env var is set, use that path instead.
+
+Structure:
+
+```json
+{
+  "task_slug": "MINE-CSHARP",
+  "skill": "/task-hardening",
+  "phase": "triage",
+  "started_at": "2026-04-17T14:30:00Z",
+  "modified_files": [
+    "mempalace/miner.py",
+    "mempalace/lang_detect.py",
+    "docs/BACKLOG.yaml"
+  ],
+  "decisions": [
+    "F1: missing .cs extension — fix (score 3/3)",
+    "F2: symbol extraction regex — fix (score 2/3)",
+    "F3: benchmark dataset — backlog only (score 1/3)"
+  ],
+  "pending_actions": [
+    "write round report to docs/audits/",
+    "update BACKLOG.yaml",
+    "commit via commit-checkpoint"
+  ]
+}
+```
+
+## When to Write
+
+- **At skill start**: initialize with task slug, skill name, phase = "started", empty arrays.
+- **After each file edit**: append the file path to `modified_files`.
+- **After each decision**: append a one-line summary to `decisions`.
+- **At phase transitions**: update `phase` (e.g., "research" -> "triage" -> "implementing" -> "committing").
+- **After commit**: clear the file (`: > /tmp/claude-task-state-<SLUG>.json`).
+
+## When to Read
+
+- **After context compaction**: if `/start` is invoked mid-task, read the state file to recover task context.
+- **At commit time**: the commit checkpoint (`.claude/skills/_shared/commit-checkpoint.md`) uses `modified_files` as a secondary source alongside the edit log.
+- **On skill resume**: if the user re-invokes a skill after interruption, read the state file to determine where to resume.
+
+## Integration with Commit Checkpoint
+
+The commit checkpoint Step 1 should cross-reference three sources:
+1. `/tmp/claude-edits.log` (hook-populated, most complete)
+2. `/tmp/claude-task-state-<SLUG>.json` -> `modified_files` (skill-populated, survives log rotation)
+3. `git diff --name-only` + `git diff --name-only --cached` (ground truth)
+
+All three should agree. Discrepancies indicate missed files or stale state.
+
+## Results Ledger (optional)
+
+For tasks with experimentation (hardening, debugging, performance tuning), maintain a results log:
+
+Location: `/tmp/claude-task-results-<SLUG>.tsv`
+
+```tsv
+timestamp	action	status	description
+2026-04-17T14:30	try tree-sitter C#	keep	AST-based chunking for .cs files
+2026-04-17T14:35	try regex fallback	discard	misses nested classes
+2026-04-17T14:40	add symbol metadata	keep	extracts class/method/property names
+```
+
+This separates "what worked" (git history) from "what was attempted" (ledger). Useful for post-mortems and preventing re-exploration of dead ends. Not committed — lives in `/tmp/` only.
+
+## Rules
+
+- The state file and results ledger are ephemeral — do NOT commit them. They exist only in `/tmp/`.
+- One task at a time per state file. If starting a new task, overwrite the previous state.
+- Keep entries short — one line per decision, one path per file. This is a recovery aid, not a log.
+- If the state file is missing or corrupt, fall back to the edit log and git status (no hard failure).

mempalace_code-1.2.0/.claude/skills/bench/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: bench
+description: Run embedding benchmarks — R@5 code retrieval, timing, model comparison
+disable-model-invocation: false
+---
+
+# Embedding Benchmarks
+
+Run retrieval quality and performance benchmarks.
+
+## When to Use
+
+- Evaluating embedding model changes
+- Performance regression testing
+- Comparing model candidates
+- User says "benchmark", "bench", "test embeddings"
+
+## Steps
+
+### Step 1: Check Prerequisites
+
+```bash
+# Verify benchmark data exists
+ls benchmarks/data/ 2>/dev/null || echo "No benchmark data"
+
+# Verify current model
+python -c "from mempalace.embeddings import get_embedder; e=get_embedder(); print(f'Model: {e.model_name}')"
+```
+
+### Step 2: Code Retrieval Benchmark
+
+Run the standard code retrieval benchmark:
+
+```bash
+python benchmarks/code_retrieval_bench.py --output benchmarks/results_$(date +%Y%m%d).json
+```
+
+Metrics collected:
+- **R@5**: Recall at 5 (target: >= 0.95)
+- **R@10**: Recall at 10 (target: 1.0)
+- **Embed time**: Seconds to embed all chunks
+- **Query time**: Milliseconds per query
+- **Index size**: MB on disk
+
+### Step 3: Category Breakdown
+
+If benchmark supports categories:
+
+| Category | Description |
+|----------|-------------|
+| architecture | High-level design questions |
+| class_lookup | Find specific class definitions |
+| cross_file | References spanning multiple files |
+| function_lookup | Find specific functions |
+
+### Step 4: Compare Models (optional)
+
+If comparing multiple models:
+
+```bash
+# Test each candidate
+for model in "all-MiniLM-L6-v2" "all-mpnet-base-v2"; do
+  MEMPALACE_EMBED_MODEL=$model python benchmarks/code_retrieval_bench.py --output benchmarks/results_${model}_$(date +%Y%m%d).json
+done
+```
+
+### Step 5: Text Retrieval Gate (if changing models)
+
+Per project policy, any embedding model change must also pass text retrieval benchmarks:
+
+```bash
+python benchmarks/text_retrieval_bench.py --dataset longmemeval
+```
+
+Target: Match or beat current model on LongMemEval R@5.
+
+## Output Format
+
+```
+## Benchmark Results
+
+Model: all-MiniLM-L6-v2
+Dataset: mempalace code retrieval (20 queries, N chunks)
+
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| R@5 | 0.950 | >= 0.95 | PASS |
+| R@10 | 1.000 | 1.0 | PASS |
+| Embed time | 15.2s | < 60s | PASS |
+| Query time | 15.9ms | < 100ms | PASS |
+| Index size | 17.0 MB | < 50 MB | PASS |
+
+Category R@5:
+- architecture: 0.800
+- class_lookup: 1.000
+- cross_file: 1.000
+- function_lookup: 1.000
+
+**Verdict: PASS** — Model meets all targets.
+```
+
+## Model Comparison Table
+
+When comparing models, produce:
+
+```
+| Model | R@5 | R@10 | Embed(s) | Query(ms) | Index(MB) |
+|-------|-----|------|----------|-----------|-----------|
+| all-MiniLM-L6-v2 | 0.950 | 1.000 | 15.2 | 15.9 | 17.0 |
+| all-mpnet-base-v2 | 0.900 | 1.000 | 47.5 | 30.5 | 17.7 |
+
+**Recommendation:** minilm remains default (better R@5, 3x faster).
+```

mempalace_code-1.2.0/.claude/skills/doc-refresh/INSTRUCTIONS.md

@@ -0,0 +1,118 @@
+# doc-refresh
+
+Weekly documentation refresh + maintenance. All steps mechanical — execute sequentially.
+
+## Constraints
+
+- Only document what exists in code (verify by reading source).
+- Never remove correct content — only update stale entries and add missing ones.
+- CLAUDE.md is context-loaded every session — keep concise.
+- Verify counts by running commands, not from memory.
+- Update "Last updated" dates on modified doc files.
+
+## Step 1 — Audit staleness
+
+Run in parallel:
+
+```bash
+git log --oneline -1 -- docs/BACKUP_RESTORE.md docs/AGENT_INSTALL.md docs/STORAGE.md CLAUDE.md README.md
+```
+```bash
+git log --oneline -30 main
+```
+```bash
+backlog list --status open --file docs/BACKLOG.yaml
+```
+
+For each doc, diff changed source files since last doc commit:
+
+| Doc | Diff scope |
+|-----|-----------|
+| BACKUP_RESTORE.md | `mempalace/backup.py`, `mempalace/storage.py` |
+| AGENT_INSTALL.md | `mempalace/mcp_server.py`, MCP tools |
+| STORAGE.md | `mempalace/storage.py`, schema migrations |
+| CLAUDE.md | `.claude/skills/`, `mempalace/*.py` modules |
+| README.md | CLI commands, MCP tools, installation |
+
+Skip docs where diff is empty or test-only.
+
+## Step 2 — Update stale docs
+
+### README.md
+
+Check: new CLI commands, new MCP tools, installation changes, supported languages list.
+
+### CLAUDE.md
+
+Check: Key Modules table accuracy, new skills tables, architecture principles current.
+
+### AGENT_INSTALL.md
+
+Check: MCP tool list matches `mcp_server.py`, installation steps work.
+
+### BACKUP_RESTORE.md
+
+Check: CLI commands match implementation, filter semantics current.
+
+## Step 3 — Backlog doc gaps
+
+Mark resolved documentation-gap backlog items: `backlog done <SLUG> --summary "summary" --file docs/BACKLOG.yaml`.
+
+## Step 4 — Maintenance
+
+Execute all substeps every run.
+
+### 4a. Backlog validate
+
+```bash
+backlog validate --file docs/BACKLOG.yaml
+```
+
+Fix any schema errors. Dangling links are warnings — ignore.
+
+### 4b. Memory cleanup
+
+Scan `MEMORY.md` per memory-write-policy. Remove:
+- Outdated versions or archived workflows
+- Session-specific notes that should have been removed
+- Duplicates of CLAUDE.md content
+
+### 4c. Verify check
+
+```bash
+BASELINE=$(cat .verify-state 2>/dev/null)
+if [ -n "$BASELINE" ]; then
+  COUNT=$(git log --oneline "$BASELINE"..HEAD 2>/dev/null | wc -l | tr -d ' ')
+  echo "Unverified commits: $COUNT"
+else
+  echo "No verify baseline — run /verify"
+fi
+```
+
+If >= 30 unverified commits: flag prominently, recommend `/verify` before next deploy.
+
+### 4d. Dead doc references
+
+```bash
+grep -rohn 'docs/[a-zA-Z0-9_./-]*\.md' docs/ CLAUDE.md .claude/ | while IFS=: read -r file line path; do
+  [ ! -f "$path" ] && echo "DEAD REF: $file:$line -> $path"
+done
+```
+
+Fix dead refs in CLAUDE.md and `.claude/`. Report count.
+
+### 4e. RTK savings (if rtk installed)
+
+```bash
+rtk discover 2>&1 | head -40 || true
+rtk gain 2>&1 | head -15 || true
+```
+
+## Output
+
+```
+Updated: [files modified]
+Docs: README [N changes] | CLAUDE [N sections] | AGENT_INSTALL [changes] | BACKUP_RESTORE [changes]
+Backlog gaps: [N resolved]
+Maintenance: validate [pass/fail] | memory [clean/N stale] | verify [N unverified] | dead refs [N in key files]
+```

mempalace_code-1.2.0/.claude/skills/doc-refresh/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: doc-refresh
+description: Weekly documentation refresh and maintenance - audit staleness, update docs, validate backlog
+disable-model-invocation: false
+---
+
+When to use: cleanup cadence, "update docs", "refresh documentation".
+Not for: single file edits, general refactoring.
+
+Read `.claude/skills/doc-refresh/INSTRUCTIONS.md` for the full workflow.