@hegemonart/get-design-done 1.19.0 → 1.19.6

package/scripts/lib/design-search.cjs

@@ -0,0 +1,206 @@
+'use strict';
+/**
+ * design-search.cjs — cross-cycle recall search backend.
+ *
+ * Priority chain:
+ *   1. FTS5 via better-sqlite3 (fast, ranked)  — when module is available
+ *   2. ripgrep                                  — when rg is on PATH
+ *   3. Node fs line scan                        — universal fallback
+ *
+ * Public API:
+ *   search(query, projectRoot, opts?) → [{file, line, text}]
+ *   reindex(projectRoot)              → void  (rebuilds FTS5 DB; no-op on grep path)
+ *   backendName()                     → 'fts5' | 'ripgrep' | 'node-grep'
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { probeOptional } = require('./probe-optional.cjs');
+
+// ---------------------------------------------------------------------------
+// Backend selection (evaluated once at module load)
+// ---------------------------------------------------------------------------
+
+const Database = probeOptional('better-sqlite3');
+
+let _fts5Supported = false;
+if (Database) {
+  try {
+    const probe = new Database(':memory:');
+    probe.exec('CREATE VIRTUAL TABLE _p USING fts5(t)');
+    probe.close();
+    _fts5Supported = true;
+  } catch { /* fts5 extension not compiled in */ }
+}
+
+function _rgAvailable() {
+  try {
+    const r = spawnSync('rg', ['--version'], { encoding: 'utf8', windowsHide: true });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+const _hasRg = _rgAvailable();
+
+function backendName() {
+  if (_fts5Supported) return 'fts5';
+  if (_hasRg) return 'ripgrep';
+  return 'node-grep';
+}
+
+// ---------------------------------------------------------------------------
+// Index paths
+// ---------------------------------------------------------------------------
+
+const INDEXED_GLOBS = [
+  '.design/archive/**/*.md',
+  '.design/learnings/LEARNINGS.md',
+  '.design/CYCLES.md',
+];
+
+function _dbPath(projectRoot) {
+  return path.join(projectRoot, '.design', 'search.db');
+}
+
+function _collectFiles(projectRoot) {
+  const results = [];
+  function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(full); continue; }
+      if (e.name.endsWith('.md')) results.push(full);
+    }
+  }
+  walk(path.join(projectRoot, '.design', 'archive'));
+  for (const rel of [
+    path.join('.design', 'learnings', 'LEARNINGS.md'),
+    path.join('.design', 'CYCLES.md'),
+  ]) {
+    const full = path.join(projectRoot, rel);
+    if (fs.existsSync(full)) results.push(full);
+  }
+  // STATE.md decision blocks
+  const state = path.join(projectRoot, '.design', 'STATE.md');
+  if (fs.existsSync(state)) results.push(state);
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// FTS5 backend
+// ---------------------------------------------------------------------------
+
+function _openDb(projectRoot) {
+  const dbPath = _dbPath(projectRoot);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(
+      file UNINDEXED, line UNINDEXED, text, tokenize='trigram'
+    );
+  `);
+  return db;
+}
+
+function reindex(projectRoot) {
+  if (!_fts5Supported) return;
+  const db = _openDb(projectRoot);
+  db.exec('DELETE FROM docs');
+  const insert = db.prepare('INSERT INTO docs(file, line, text) VALUES (?,?,?)');
+  const txn = db.transaction((files) => {
+    for (const file of files) {
+      let content;
+      try { content = fs.readFileSync(file, 'utf8'); } catch { continue; }
+      const lines = content.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (t) insert.run(file, i + 1, t);
+      }
+    }
+  });
+  txn(_collectFiles(projectRoot));
+  db.close();
+}
+
+function _searchFts5(query, projectRoot, limit) {
+  const dbPath = _dbPath(projectRoot);
+  if (!fs.existsSync(dbPath)) reindex(projectRoot);
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const rows = db.prepare(
+      `SELECT file, line, text FROM docs WHERE docs MATCH ? ORDER BY rank LIMIT ?`
+    ).all(query, limit);
+    return rows.map(r => ({ file: r.file, line: r.line, text: r.text }));
+  } finally {
+    db.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ripgrep backend
+// ---------------------------------------------------------------------------
+
+function _escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function _searchRg(query, projectRoot, limit) {
+  const terms = query.split(/\s+/).filter(Boolean);
+  const pattern = terms.map(_escapeRe).join('|');
+  const targets = _collectFiles(projectRoot);
+  if (!targets.length || !pattern) return [];
+  const r = spawnSync('rg', ['-n', '--no-heading', '-i', '-S', pattern, ...targets], {
+    encoding: 'utf8', windowsHide: true,
+  });
+  const results = [];
+  for (const line of (r.stdout || '').split(/\r?\n/)) {
+    const m = line.match(/^(.+?):(\d+):(.*)$/);
+    if (m) results.push({ file: m[1], line: Number(m[2]), text: m[3].trim() });
+    if (results.length >= limit) break;
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Node fs fallback backend
+// ---------------------------------------------------------------------------
+
+function _searchNode(query, projectRoot, limit) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const files = _collectFiles(projectRoot);
+  const results = [];
+  for (const file of files) {
+    let content;
+    try { content = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const lower = lines[i].toLowerCase();
+      if (terms.every(t => lower.includes(t))) {
+        results.push({ file, line: i + 1, text: lines[i].trim() });
+        if (results.length >= limit) return results;
+      }
+    }
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Public search
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} query
+ * @param {string} projectRoot  absolute path to the project (contains .design/)
+ * @param {{ limit?: number }} [opts]
+ * @returns {{ file: string, line: number, text: string }[]}
+ */
+function search(query, projectRoot, opts = {}) {
+  const limit = opts.limit ?? 20;
+  if (_fts5Supported) return _searchFts5(query, projectRoot, limit);
+  if (_hasRg) return _searchRg(query, projectRoot, limit);
+  return _searchNode(query, projectRoot, limit);
+}
+
+module.exports = { search, reindex, backendName };

package/scripts/lib/probe-optional.cjs

@@ -0,0 +1,29 @@
+'use strict';
+/**
+ * probe-optional.cjs — safely require optional native dependencies.
+ *
+ * Usage:
+ *   const { probeOptional } = require('./probe-optional.cjs');
+ *   const Database = probeOptional('better-sqlite3');
+ *   if (Database) { ... } else { // fallback }
+ *
+ * Returns the module if available and natively compatible, null otherwise.
+ * Swallows MODULE_NOT_FOUND and native binding errors silently — callers
+ * must implement their own fallback path.
+ */
+function probeOptional(name) {
+  try {
+    return require(name);
+  } catch (e) {
+    if (
+      e.code === 'MODULE_NOT_FOUND' ||
+      e.message?.includes('was compiled against a different Node.js version') ||
+      e.message?.includes('NODE_MODULE_VERSION')
+    ) {
+      return null;
+    }
+    throw e;
+  }
+}
+
+module.exports = { probeOptional };

package/scripts/lib/relevance-counter.cjs

@@ -0,0 +1,121 @@
+'use strict';
+/**
+ * relevance-counter.cjs — tracks per-learning signal counts.
+ *
+ * Signals: 'cited' | 'surfaced' | 'dismissed'
+ *
+ * Writes to `.design/learnings/.relevance.json` under an atomic-write
+ * pattern (write tmp → rename) guarded by a `.relevance.lock` file so
+ * concurrent agents don't clobber each other.
+ *
+ * Public API:
+ *   record(id, signal, designDir)  → void
+ *   load(designDir)                → { [id]: { cited, surfaced, dismissed, last_used } }
+ *   shouldPromote(id, designDir)   → boolean  (cited >= 8)
+ *   shouldPrune(id, age, designDir) → boolean (cited === 0 and age >= 4 cycles)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SIGNALS = new Set(['cited', 'surfaced', 'dismissed']);
+const PROMOTE_THRESHOLD = 8;
+
+function _counterPath(designDir) {
+  return path.join(designDir, 'learnings', '.relevance.json');
+}
+
+function _lockPath(designDir) {
+  return path.join(designDir, 'learnings', '.relevance.lock');
+}
+
+function _acquireLock(lockPath, timeout = 5000) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    try {
+      fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      return true;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Check for stale lock (> 30s old)
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > 30000) {
+          fs.unlinkSync(lockPath);
+          continue;
+        }
+      } catch { /* lock was removed between our check and unlink */ }
+      // Brief spin
+      const end = Date.now() + 50;
+      while (Date.now() < end) { /* spin */ }
+    }
+  }
+  return false;
+}
+
+function _releaseLock(lockPath) {
+  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+}
+
+function load(designDir) {
+  const p = _counterPath(designDir);
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Record a signal for a learning entry id.
+ * @param {string} id      Learning ID (e.g. "L-01")
+ * @param {'cited'|'surfaced'|'dismissed'} signal
+ * @param {string} designDir  Path to the .design/ directory
+ */
+function record(id, signal, designDir) {
+  if (!SIGNALS.has(signal)) throw new Error(`Unknown signal: ${signal}`);
+  fs.mkdirSync(path.join(designDir, 'learnings'), { recursive: true });
+
+  const lockPath = _lockPath(designDir);
+  if (!_acquireLock(lockPath)) {
+    // Non-fatal — skip the update rather than corrupting the store
+    return;
+  }
+
+  try {
+    const data = load(designDir);
+    if (!data[id]) {
+      data[id] = { cited: 0, surfaced: 0, dismissed: 0, last_used: null };
+    }
+    data[id][signal]++;
+    data[id].last_used = new Date().toISOString();
+
+    // Atomic write: tmp → rename
+    const counterPath = _counterPath(designDir);
+    const tmp = counterPath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, counterPath);
+  } finally {
+    _releaseLock(lockPath);
+  }
+}
+
+function shouldPromote(id, designDir) {
+  const data = load(designDir);
+  return (data[id]?.cited ?? 0) >= PROMOTE_THRESHOLD;
+}
+
+/**
+ * @param {string} id
+ * @param {number} ageCycles  number of cycles since last_used (or since created)
+ * @param {string} designDir
+ */
+function shouldPrune(id, ageCycles, designDir) {
+  const data = load(designDir);
+  const entry = data[id];
+  if (!entry) return false;
+  return entry.cited === 0 && ageCycles >= 4;
+}
+
+module.exports = { record, load, shouldPromote, shouldPrune };

package/skills/complete-cycle/SKILL.md

@@ -22,8 +22,46 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
    - `DESIGN-AUDIT.md`
    - `DESIGN-SUMMARY.md`
    Mark originals with a `<!-- archived to .design/archive/cycle-N/ -->` note at top (do not delete — next cycle will overwrite).
-5. **Clear STATE.md**: Set `cycle:` to empty string, reset `<decisions>` to a fresh empty section, reset `stage:` to `brief`.
-6. Print: "Cycle <N> archived. Run `/gdd:new-cycle` to start the next cycle."
+5. **Generate EXPERIENCE.md** (Haiku-tier writer step): Read cycle STATE decisions + `.design/DESIGN-VERIFICATION.md` (if present) + any `.design/reflections/*.md` from this cycle. Write `.design/archive/cycle-N/EXPERIENCE.md` using this structure (~100–200 lines, declarative-fact framing, prepend `reference/cycle-handoff-preamble.md` content):
+
+   ```markdown
+   <!-- archived cycle experience — reference, not current requests -->
+   # Cycle N — Experience
+
+   **Goal**: <one-line goal from STATE.md or CYCLES.md>
+   **Opened**: <start date>
+   **Ended**: <today>
+
+   ## Decisions Made
+
+   <list all D-XX decisions from STATE.md <decisions> block — one per line>
+
+   ## Learnings Graduated
+
+   <list all L-NN learnings surfaced or promoted this cycle>
+
+   ## What Died
+
+   <designs, approaches, or tasks that were started but abandoned — and why>
+
+   ## Surprises
+
+   <what was unexpected during this cycle>
+
+   ## Handoff to Next Cycle
+
+   <what the next cycle should know: active sketches, deferred tasks, unresolved questions>
+   ```
+
+   This file becomes the highest-priority source for the decision-injector hook in future sessions.
+
+6. **Trigger reindex**: if `.design/search.db` exists, rebuild the search index:
+   ```bash
+   node -e "require('./scripts/lib/design-search.cjs').reindex(process.cwd())" 2>/dev/null || true
+   ```
+
+7. **Clear STATE.md**: Set `cycle:` to empty string, reset `<decisions>` to a fresh empty section, reset `stage:` to `brief`.
+8. Print: "Cycle <N> archived. Run `/gdd:new-cycle` to start the next cycle."
 
 ## Do Not
 

package/skills/continue/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: gdd-continue
+description: "Alias for /gdd:resume — restore session context from the most recent checkpoint."
+argument-hint: "[<checkpoint-N>]"
+tools: Read, Write, Bash, Glob
+---
+
+@reference/retrieval-contract.md
+
+# /gdd:continue
+
+Alias for `/gdd:resume`. Delegates immediately to the resume skill with the same argument.
+
+This alias exists for discoverability — users familiar with `git continue` or similar conventions find `/gdd:continue` more intuitive than `/gdd:resume` after a pause.
+
+## Steps
+
+1. Forward the argument (if any) to the `/gdd:resume` skill logic.
+2. Execute all `/gdd:resume` steps exactly as documented in `skills/resume/SKILL.md`.
+
+The two commands are functionally identical. `/gdd:resume` is the canonical form; `/gdd:continue` is the convenience alias.
+
+## CONTINUE COMPLETE

package/skills/pause/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: gdd-pause
-description: "Write session handoff so work can resume in a new session without re-running completed stages."
+description: "Write a numbered checkpoint so work can resume in a new session without re-running completed stages."
 argument-hint: "[context note]"
-tools: Read, Write, AskUserQuestion
+tools: Read, Write, Bash, AskUserQuestion
 ---
 
 @reference/retrieval-contract.md
@@ -10,35 +10,61 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:pause
 
-Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume`.
+Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume` or `/gdd:continue`.
+
+Each invocation writes an **immutable numbered checkpoint** — it does not overwrite previous pauses. This enables branched cycles: you can pause, take a detour via `/gdd:sketch`, compare, and resume an older snapshot via `/gdd:resume N`.
 
 ## Steps
 
-1. Read `.design/STATE.md`. Extract:
-   - Current `stage:` and `cycle:`
+1. **Read `.design/STATE.md`**. Extract:
+   - `stage:` and `cycle:`
    - Last activity timestamp
    - Completed tasks in the current pipeline run
-   - Open todos (from `.design/TODO.md` if present)
+   - Open todos (scan `.design/TODO.md` if present)
    - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
-2. If no context argument was passed, ask (AskUserQuestion): "What are you in the middle of? (optional context to capture)"
-3. Write `.design/HANDOFF.md`:
+
+2. **Determine checkpoint number**: run
+   ```bash
+   ls .design/checkpoints/ 2>/dev/null | grep -E '^[0-9]+' | sort -n | tail -1
+   ```
+   Next checkpoint = last number + 1 (or `01` if none exist).
+
+3. **Collect context**: if no context argument was passed, ask (AskUserQuestion):
+   "What are you in the middle of? (optional context to capture)"
+
+4. **Write numbered checkpoint**: create `.design/checkpoints/` with `mkdir -p`, then write:
+   ```
+   .design/checkpoints/NN-<stage>-<ISO-date>.md
+   ```
+   e.g. `01-design-2026-04-24.md`
+
+   Content:
    ```markdown
-   # Session Handoff
-   **Paused**: <ISO timestamp>
+   # Checkpoint NN
+   **Saved**: <ISO timestamp>
    **Stage**: <stage>
-   **Cycle**: <cycle-N>
+   **Cycle**: <cycle>
    **In progress**: <task description + wave/index>
    **Next**: <next step>
-   **Context**: <user note>
+   **Context**: <user note or "none">
    **Active sketch**: <path or none>
    **Open todos**: <N items (see .design/TODO.md)>
    **Completed this session**: <list>
    ```
-4. Print: "Session paused. Run `/gdd:resume` to pick back up."
+
+5. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
+   ```markdown
+   # Session Handoff (pointer)
+   Latest checkpoint: `.design/checkpoints/NN-<stage>-<ISO-date>.md`
+   Run `/gdd:resume` to restore, or `/gdd:resume N` for a specific checkpoint.
+   ```
+
+6. Print: "Checkpoint NN saved. Run `/gdd:resume` or `/gdd:continue` to pick back up."
 
 ## Do Not
 
-- Do not modify STATE.md itself — HANDOFF.md is the only write.
+- Do not modify STATE.md — checkpoints are the only write.
 - Do not abort in-progress sketches; just record them.
+- Do not delete previous checkpoint files.
 
 ## PAUSE COMPLETE

package/skills/recall/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gdd-recall
+description: "Search cross-cycle memory: decisions, learnings, experience archives. Returns ranked matches."
+argument-hint: "<query> [--reindex]"
+tools: Read, Write, Bash
+---
+
+@reference/retrieval-contract.md
+
+# /gdd:recall
+
+Searches `.design/archive/`, `.design/learnings/LEARNINGS.md`, `.design/CYCLES.md`, and `STATE.md` decision blocks for the given query and returns ranked matches. Uses FTS5 when `better-sqlite3` is available, ripgrep next, Node fs scan as universal fallback.
+
+## Steps
+
+1. **Parse argument**: extract `<query>` and optional `--reindex` flag.
+   - If no query and no `--reindex`: print usage and exit.
+   - If `--reindex` only: rebuild the index (see step 3), then exit.
+
+2. **Check backend**: run
+   ```bash
+   node -e "const {backendName}=require('./scripts/lib/design-search.cjs');console.log(backendName())"
+   ```
+   Print a one-line notice: `Search backend: fts5 | ripgrep | node-grep`.
+
+3. **Reindex if requested**: run
+   ```bash
+   node -e "require('./scripts/lib/design-search.cjs').reindex(process.cwd())"
+   ```
+   Print: "Index rebuilt."
+
+4. **Search**: run
+   ```bash
+   node -e "
+   const s=require('./scripts/lib/design-search.cjs');
+   const r=s.search(process.argv[1], process.cwd(), {limit:20});
+   console.log(JSON.stringify(r));
+   " -- "<query>"
+   ```
+   Parse the JSON array of `{file, line, text}` objects.
+
+5. **Format results**: print in this shape:
+   ```
+   ## Recall: "<query>"  (N matches, backend: fts5)
+
+   ### 1. .design/archive/cycle-2/EXPERIENCE.md:42
+   > Decided to skip dark-mode token layer in cycle 2 — cost–benefit did not clear threshold
+
+   ### 2. .design/learnings/LEARNINGS.md:18
+   > L-03 · color · cited:4 · Color contrast failures cluster around interactive states, not surfaces
+   ```
+   Group by file. Truncate text at 120 chars. Cap at 20 results.
+
+6. **Signal relevance**: for every result whose text contains an `L-NN` learning ID, record a `surfaced` signal:
+   ```bash
+   node -e "
+   const rc=require('./scripts/lib/relevance-counter.cjs');
+   rc.record('L-NN','surfaced','.design');
+   "
+   ```
+
+7. **Empty result**: if no matches, print:
+   ```
+   No matches for "<query>" in cross-cycle memory.
+   Tip: run /gdd:recall --reindex if the archive has been updated since last index build.
+   ```
+
+## Do Not
+
+- Do not modify any source file.
+- Do not run git commands.
+- Do not write `.design/STATE.md`.
+
+## RECALL COMPLETE

package/skills/resume/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: gdd-resume
-description: "Restore session context from .design/HANDOFF.md and route to where work left off."
-argument-hint: ""
-tools: Read, Write, Bash, Glob
+description: "Restore session context from a numbered checkpoint. Lists available checkpoints when no argument given."
+argument-hint: "[<N>]"
+tools: Read, Write, Bash, Glob, AskUserQuestion
 ---
 
 @reference/retrieval-contract.md
@@ -10,31 +10,49 @@ tools: Read, Write, Bash, Glob
 
 # /gdd:resume
 
-Inverse of `/gdd:pause`. Reads the handoff file, prints a clear "you were here" summary, and routes to the next command.
+Inverse of `/gdd:pause`. Reads a checkpoint file, prints a clear "you were here" summary, and routes to the next command.
 
 ## Steps
 
-1. Try to read `.design/HANDOFF.md`. If missing, read `.design/STATE.md` and infer position from the `stage:` and `cycle:` fields.
-2. Print a summary in this exact shape:
+1. **Parse argument**:
+   - If argument is a number N → restore checkpoint N.
+   - If no argument → list available checkpoints and ask which to restore (see step 2).
+
+2. **List mode** (no argument):
+   ```bash
+   ls .design/checkpoints/ 2>/dev/null | sort -n
+   ```
+   If empty, fall back to reading `.design/HANDOFF.md` (legacy single-slot format).
+   If checkpoints exist, present the list and ask (AskUserQuestion):
+   "Which checkpoint would you like to restore? (enter number, or press Enter for the latest)"
+   Use the answer (or latest if Enter pressed) as N.
+
+3. **Read checkpoint**: load `.design/checkpoints/NN-*.md`. If not found, try `.design/HANDOFF.md` as legacy fallback.
+
+4. **Print summary** in this exact shape:
    ```
-   Last paused: <timestamp>
+   Checkpoint NN restored.
+   Saved: <timestamp>
    You were: <in-progress description>
    Next step: <next>
    Active sketch: <path or none>
    Open todos: <N>
    ```
-3. **Staleness check** — compare mtime of `.design/` artifacts vs `src/` (via Glob + Bash `stat` when available). If `src/` has commits/changes newer than the last pipeline artifact, warn: "Source has changed since last pipeline run — consider re-running explore or verify."
-4. **Route recommendation** based on stage:
-   - `brief` → "Run `@get-design-done brief`"
-   - `explore` → "Run `@get-design-done explore`"
-   - `plan` → "Run `@get-design-done plan`"
-   - `design` → "Run `@get-design-done design` to continue"
-   - `verify` → "Run `@get-design-done verify`"
-5. Do not auto-execute the next command — just recommend.
+
+5. **Staleness check**: compare mtime of `.design/` artifacts vs `src/` via Bash `stat` when available. If `src/` has commits newer than the checkpoint timestamp, warn:
+   "Source has changed since checkpoint NN — consider re-running explore or verify."
+
+6. **Route recommendation** based on checkpoint `Stage:` field:
+   - `brief` → "Run `/gdd:brief`"
+   - `explore` → "Run `/gdd:explore`"
+   - `plan` → "Run `/gdd:plan`"
+   - `design` → "Run `/gdd:design` to continue"
+   - `verify` → "Run `/gdd:verify`"
 
 ## Do Not
 
-- Do not delete HANDOFF.md (leave it; next `/gdd:pause` overwrites it).
+- Do not delete checkpoint files.
 - Do not modify STATE.md.
+- Do not auto-execute the next command — just recommend.
 
 ## RESUME COMPLETE