@hegemonart/get-design-done 1.18.0 → 1.19.5

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

package/skills/timeline/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: gdd-timeline
+description: "Narrative retrospective across cycles: reads EXPERIENCE.md files and git log to produce a timeline view."
+argument-hint: "[<cycle-N> | <from>-<to> | all]"
+tools: Read, Bash, Glob
+---
+
+@reference/retrieval-contract.md
+@reference/cycle-handoff-preamble.md
+
+# /gdd:timeline
+
+Generates a narrative retrospective across one or more completed cycles by reading `.design/archive/cycle-N/EXPERIENCE.md` files and correlating with `git log`.
+
+## Steps
+
+1. **Parse argument**: accepted forms:
+   - `cycle-N` or `N` — single cycle
+   - `N-M` — inclusive range
+   - `all` or no argument — all archived cycles
+
+2. **Discover archives**: glob `.design/archive/cycle-*/EXPERIENCE.md`. Sort by cycle number. Filter to requested range.
+
+3. **For each cycle archive**:
+   a. Read `EXPERIENCE.md` — extract sections: Goal, Decisions made, Learnings graduated, What died, Handoff to next cycle.
+   b. Read `DESIGN-SUMMARY.md` (if present) for shipped artifacts list.
+   c. Run:
+      ```bash
+      git log --oneline --after="<cycle start date>" --before="<cycle end date>" -- .design/ 2>/dev/null | head -10
+      ```
+      to correlate with commits. Use dates from `EXPERIENCE.md` Opened/Ended headers if present.
+
+4. **Print timeline** in this shape:
+
+   ```
+   ## Timeline: Cycle 1 → Cycle 3
+
+   ---
+
+   ### Cycle 1 — <goal headline>
+
+   **Opened with**: <first meaningful action>
+   **Key decisions**: <D-XX summary>, <D-XX summary>
+   **Surprises**: <what was unexpected>
+   **What we'd do differently**: <retrospective note>
+   **Shipped**: <artifact list or "see DESIGN-SUMMARY.md">
+
+   ---
+
+   ### Cycle 2 — <goal headline>
+   ...
+   ```
+
+5. **No archives found**: print
+   ```
+   No archived cycles found in .design/archive/.
+   Complete a cycle first with /gdd:complete-cycle.
+   ```
+
+## Do Not
+
+- Do not modify any file.
+- Do not run git commands that write or stage (only `git log` for read).
+
+## TIMELINE COMPLETE