@theglitchking/persistent-planning 3.1.0 → 3.4.0

package/hooks/session-start.js

@@ -1,17 +1,25 @@
 #!/usr/bin/env node
 // persistent-planning SessionStart hook.
 //
-// Two jobs:
+// Three jobs:
 //   1. The update check, delegated entirely to @theglitchking/claude-plugin-runtime.
 //   2. A completion nudge: if any plan under .planning/ has every box checked
 //      but is still sitting in the active tree, say so, so the agent archives it
 //      instead of rediscovering a finished plan next session.
+//   3. A drift warning: if .claude/skills/persistent-planning is a real directory
+//      rather than a symlink into this package, it is a frozen v1 copy and every
+//      /start-planning is running stale code. See issue #10.
+//   4. Under updatePolicy: auto, actually repair that drift. This hook is the only
+//      code that runs every session in a marketplace install -- that shape has no
+//      node_modules in the plugin cache and never runs npm postinstall -- so it is
+//      the only delivery path a fix can reach existing broken installs through.
 
 import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { driftedSkills, readSkillVersion } from "../scripts/lib/skill-link.js";
 
 const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -33,7 +41,111 @@ function planNudge() {
   }
 }
 
-const notice = planNudge();
+function updatePolicy() {
+  try {
+    const raw = readFileSync(join(projectRoot, ".claude", "persistent-planning.json"), "utf8");
+    return JSON.parse(raw)?.updatePolicy || "nudge";
+  } catch {
+    return "nudge";
+  }
+}
+
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version || null;
+  } catch {
+    return null;
+  }
+}
+
+const CONFIG = join(projectRoot, ".claude", "persistent-planning.json");
+
+function readConfig() {
+  try { return JSON.parse(readFileSync(CONFIG, "utf8")) || {}; } catch { return {}; }
+}
+
+/**
+ * Repair a drifted skill dir, at most once per plugin version.
+ *
+ * Runs the package's own linker, which reclaims the stale dir, symlinks, and stamps
+ * the version marker. Spawned rather than imported so a failure is contained in a
+ * child process and cannot take the hook down with it.
+ *
+ * Returns a one-line summary to fold into the session notice, or "".
+ */
+function autoRepair() {
+  try {
+    const policy = updatePolicy();
+    if (policy !== "auto") return "";                       // nudge/off: warn only
+
+    // Fast path first — two lstats, and the overwhelmingly common answer is "nothing
+    // to do". Never pay for the migration on a healthy install.
+    if (!driftedSkills(projectRoot, packageRoot, "skills").length) return "";
+
+    const version = packageVersion();
+    const cfg = readConfig();
+    if (version && cfg.repairedSkillsForVersion === version) return "";  // once per version
+
+    const linker = join(packageRoot, "scripts", "link-skills.js");
+    if (!existsSync(linker)) return "";
+
+    const r = spawnSync(process.execPath, [linker], {
+      cwd: projectRoot,
+      env: { ...process.env, INIT_CWD: projectRoot },
+      encoding: "utf8",
+      timeout: 10000,
+    });
+
+    // Stamp regardless of outcome: a repair that cannot succeed must not retry every
+    // session. A later release moves the version and gets one fresh attempt.
+    try {
+      writeFileSync(CONFIG, JSON.stringify({ ...cfg, repairedSkillsForVersion: version }, null, 2) + "\n", "utf8");
+    } catch { /* config unwritable — the drift warning still fires every session */ }
+
+    const remaining = driftedSkills(projectRoot, packageRoot, "skills");
+    if (remaining.length || r.status !== 0) return "";      // let driftNudge() report it
+    return "[persistent-planning] repaired a stale skill directory (originals kept as .bak-*).";
+  } catch {
+    return "";
+  }
+}
+
+function driftNudge() {
+  try {
+    // A user who turned updates off did not ask to be nagged about them either.
+    if (updatePolicy() === "off") return "";
+    const drifted = driftedSkills(projectRoot, packageRoot, "skills");
+    if (!drifted.length) return "";
+
+    let pkgVersion = "unknown";
+    try {
+      pkgVersion = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
+    } catch { /* keep "unknown" */ }
+
+    const lines = drifted.map((d) => {
+      const found = readSkillVersion(projectRoot, d.name) || "unversioned (pre-3.1.0 copy)";
+      const why = d.state === "real-dir"
+        ? "is a real directory, not a symlink into the installed package"
+        : `is a symlink to ${d.target}, which is not this package`;
+      return `  - ${d.dest}\n    ${why}\n    running: ${found} | installed: ${pkgVersion}`;
+    });
+
+    return [
+      "[persistent-planning] STALE SKILL DIRECTORY — commands are running frozen code.",
+      ...lines,
+      "  Plans generated from a pre-3.1.0 copy silently omit the mandatory validate and",
+      "  documentation phases and the whole 'On Completion' archive block.",
+      "  Fix:  npx persistent-planning relink",
+    ].join("\n");
+  } catch {
+    // Fail open. A broken drift check must never cost anyone their session start.
+    return "";
+  }
+}
+
+// Repair before reporting, so a successful auto-repair does not also warn.
+const repaired = autoRepair();
+const notice = [planNudge(), repaired, driftNudge()].filter(Boolean).join("\n\n");
 
 if (!notice) {
   await runSessionStart({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.1.0",
+  "version": "3.4.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {

package/scripts/archive-plan.sh

@@ -51,13 +51,10 @@ ARCHIVE="${PLANNING}/.archive"
 TODAY=$(planning_today)
 
 # .planning/.archive/ must be gitignored: completed plans are local history, not
-# something every clone should carry. Idempotent.
+# something every clone should carry. Shared with the init scripts so there is one
+# rule, not two — it also warns when a blanket .planning/ entry is hiding everything.
 ensure_gitignored() {
-  local gitignore="${ROOT}/.gitignore"
-  grep -qE '^\.planning/?$' "$gitignore" 2>/dev/null && return 0   # whole tree already ignored
-  grep -qE '^\.planning/\.archive/?$' "$gitignore" 2>/dev/null && return 0
-  printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "$gitignore"
-  planning_ok "Added .planning/.archive/ to .gitignore"
+  planning_ensure_archive_gitignored "${ROOT}" 1
 }
 
 plan_root_artifact() {

package/scripts/init-atom.sh

@@ -130,6 +130,13 @@ planning_render_and_log \
   "ATOM_DATE_PLACEHOLDER=${TODAY}" \
   "ATOM_SEQUENCE_PLACEHOLDER=${NEXT_SEQUENCE}"
 
+# Write the atom into its task's list. Same gap as init-task.sh had with
+# phase.md: the atom file was created and never referenced anywhere (#12).
+planning_insert_list_item \
+  "${TASK_DIR}/task.md" \
+  "## Atoms" \
+  "- [ ] **${ATOM_NAME}** (\`atoms/${ATOM_SLUG}.md\`, sequence: ${NEXT_SEQUENCE})"
+
 echo ""
 planning_ok "Atom '${ATOM_NAME}' ready"
 echo ""

package/scripts/init-phase.sh

@@ -125,12 +125,64 @@ planning_render_and_log \
   "NOTES_SCOPE_PLACEHOLDER=${PHASE_SLUG}" \
   "NOTES_DATE_PLACEHOLDER=${TODAY}"
 
-# Add .planning/ to .gitignore if missing (preserve existing behavior)
-GITIGNORE="${ROOT}/.gitignore"
-if [[ -f "$GITIGNORE" ]] && ! grep -q "^\.planning/" "$GITIGNORE"; then
-  echo ".planning/" >> "$GITIGNORE"
-  planning_ok "Added .planning/ to .gitignore"
-fi
+# Scaffold the two mandatory closing tasks as real task directories.
+#
+# They used to exist only as two checkbox lines in phase.md, so the most important
+# tasks in every plan were the only ones with no artifact for a subagent to read and
+# nowhere to record decisions — and every real plan hand-built them (issue #12).
+scaffold_closer() { # <slug> <title> <atom>...
+  local slug="$1" title="$2"; shift 2
+  local dir="${PHASE_DIR}/${slug}"
+  mkdir -p "${dir}/atoms"
+
+  planning_render_and_log \
+    "${TEMPLATE_DIR}/task.md" \
+    "${dir}/task.md" \
+    "closer task at ${dir}/task.md" \
+    "TASK_TITLE_PLACEHOLDER=${title}" \
+    "TASK_SLUG_PLACEHOLDER=${slug}" \
+    "PHASE_SLUG_PLACEHOLDER=${PHASE_SLUG}" \
+    "TASK_DATE_PLACEHOLDER=${TODAY}"
+
+  planning_render_and_log \
+    "${TEMPLATE_DIR}/notes.md" \
+    "${dir}/notes.md" \
+    "closer notes at ${dir}/notes.md" \
+    "NOTES_TITLE_PLACEHOLDER=${title} — Notes" \
+    "NOTES_SCOPE_PLACEHOLDER=${PHASE_SLUG}/${slug}" \
+    "NOTES_DATE_PLACEHOLDER=${TODAY}"
+
+  # mandatory: true is what plan-status.sh gates on. parallelizable stays false —
+  # a closer gates on everything before it.
+  [[ -f "${dir}/task.md" ]] && sed -i 's/^mandatory: false$/mandatory: true/' "${dir}/task.md"
+
+  local atom
+  for atom in "$@"; do
+    planning_insert_list_item "${dir}/task.md" "## Atoms" "- [ ] ${atom}"
+  done
+}
+
+scaffold_closer \
+  "validate-success-through-comprehensive-testing" \
+  "Validate success through comprehensive testing" \
+  "Prove every claim this phase makes with a test that fails if it breaks" \
+  "Test the invariant after mutation, not the shape of a freshly rendered template" \
+  "Cover the failure mode that prompted the work, not just the happy path" \
+  "Run the full suite green before closing this task"
+
+scaffold_closer \
+  "documentation-pass-create-update-deprecate-docs" \
+  "Documentation pass — create/update/deprecate docs" \
+  "Create docs for what was built: what it is, where it lives, how it works" \
+  "Add a troubleshooting entry for the symptom someone will actually search for" \
+  "Update every existing doc this phase made wrong — a stale doc is worse than a missing one" \
+  "Retire superseded docs with \`npx hewtd archive <file>\` — never by deleting" \
+  "If hit-em-with-the-docs is installed you MUST use it: \`npx hewtd integrate <file> -a\` to create, \`npx hewtd maintain --quick\` to regenerate indexes" \
+  "Run \`npx hewtd audit\` and resolve every error" \
+  "Never hand-edit INDEX.md or REGISTRY.md — they are generated"
+
+# Only completed plans are local history — see planning_ensure_archive_gitignored.
+planning_ensure_archive_gitignored "${ROOT}"
 
 echo ""
 planning_ok "Phase '${PHASE_NAME}' ready at .planning/${PHASE_SLUG}/"

package/scripts/init-planning.sh

@@ -106,7 +106,7 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
 - [ ] Phase 5: Validate success through comprehensive testing (MANDATORY)
-- [ ] Phase 6: Documentation pass -- create/update/deprecate docs (MANDATORY)
+- [ ] Phase 6: Documentation pass -- create/update/deprecate as many docs as needed to capture what was done, where it lives, how to troubleshoot it, etc. etc.. etc.. (MANDATORY)
 
 > Phases 5 and 6 are mandatory and MUST stay the last two phases of this plan.
 > Insert new work above them; never after. Renumber them if you add phases.
@@ -114,7 +114,10 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 > - **Validate success**: prove the work with tests that fail if the change breaks.
 > - **Documentation pass**: create/update/deprecate every doc this change touches --
 >   what it is, where it lives, how to fix it, how to operate it, why it matters.
->   If hit-em-with-the-docs is installed, use it for this pass.
+>   If hit-em-with-the-docs is installed, you MUST use it for this pass --
+>   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
+>   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or
+>   REGISTRY.md; they are generated.
 
 ## Key Questions
 1. [Question to answer]
@@ -205,12 +208,21 @@ else
 fi
 
 # Step 5: Update .gitignore
+#
+# Only completed plans are local history. Active plans are what a teammate or a
+# subagent reads, so they stay shareable (issue #15). This script is deliberately
+# self-contained -- no lib/planning.sh -- so the rule is duplicated here rather than
+# sourced; scripts/lib/planning.sh has the lg-mode copy.
 if [ -f "${PROJECT_ROOT}/.gitignore" ]; then
-    if ! grep -q "^\.planning/" "${PROJECT_ROOT}/.gitignore"; then
-        echo ".planning/" >> "${PROJECT_ROOT}/.gitignore"
-        echo -e "${GREEN}+${NC} Added .planning/ to .gitignore"
+    if grep -qE "^\.planning/?$" "${PROJECT_ROOT}/.gitignore"; then
+        echo -e "${YELLOW}*${NC} .gitignore ignores all of .planning/ -- plans will not be shared."
+        echo -e "  Active plans are what teammates and subagents read. To share them,"
+        echo -e "  replace the '.planning/' line with '.planning/.archive/'."
+    elif grep -qE "^\.planning/\.archive/?$" "${PROJECT_ROOT}/.gitignore"; then
+        echo -e "${YELLOW}*${NC} .planning/.archive/ already in .gitignore"
     else
-        echo -e "${YELLOW}*${NC} .planning/ already in .gitignore"
+        printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "${PROJECT_ROOT}/.gitignore"
+        echo -e "${GREEN}+${NC} Added .planning/.archive/ to .gitignore (active plans stay shareable)"
     fi
 else
     echo -e "${YELLOW}*${NC} No .gitignore found (not added)"

package/scripts/init-task.sh

@@ -109,6 +109,13 @@ planning_render_and_log \
   "NOTES_SCOPE_PLACEHOLDER=${PARENT_PHASE}/${TASK_SLUG}" \
   "NOTES_DATE_PLACEHOLDER=${TODAY}"
 
+# Write the task into its phase's list, above the mandatory closers. Before this,
+# init-task.sh never touched phase.md and every list was maintained by hand (#12).
+planning_insert_list_item \
+  "${PHASE_DIR}/phase.md" \
+  "## Tasks" \
+  "- [ ] **${TASK_NAME}** (\`${TASK_SLUG}\`)"
+
 echo ""
 planning_ok "Task '${TASK_NAME}' ready at .planning/${PARENT_PHASE}/${TASK_SLUG}/"
 echo ""

package/scripts/lib/planning.sh

@@ -159,3 +159,125 @@ planning_render_and_log() {
       ;;
   esac
 }
+
+###############################################################################
+# List maintenance
+#
+# A phase's task list and a task's atom list are stored markdown checkboxes,
+# not derived views — plan-status.sh counts them, and humans edit them. So the
+# init scripts have to write them. Before this existed, init-task.sh never
+# touched phase.md at all and every list was maintained by hand (issue #12).
+###############################################################################
+
+# planning_insert_list_item <file> <section-heading> <line>
+#
+# Inserts <line> into the checkbox list under <section-heading> in <file>:
+#   - above the first item marked MANDATORY, so closers stay last by
+#     construction rather than by anyone remembering;
+#   - after the last item when the section has no MANDATORY entries;
+#   - dropping a "(no ... yet" placeholder, checkbox or italic, including its
+#     continuation lines, the first time a real item lands.
+#
+# Idempotent: an identical line already in the section is left alone, so
+# re-running with PLANNING_FORCE=1 cannot double-insert.
+#
+# Anchors on the MANDATORY marker, never on line numbers — the list is a
+# human-editable surface and positions do not survive contact with editing.
+planning_insert_list_item() {
+  local file="$1" heading="$2" line="$3" tmp
+  [[ -f "$file" ]] || return 0
+
+  tmp="${file}.pp-tmp.$$"
+  awk -v heading="$heading" -v newline="$line" '
+    { L[NR] = $0; if ($0 == newline) seen = 1 }
+    END {
+      if (seen) { for (i = 1; i <= NR; i++) print L[i]; exit }
+
+      # Section bounds: heading .. next "## " heading (or EOF).
+      s = 0
+      for (i = 1; i <= NR; i++) {
+        if (L[i] == heading) { s = i; continue }
+        if (s && L[i] ~ /^## /) { e = i - 1; break }
+      }
+      if (!s) { for (i = 1; i <= NR; i++) print L[i]; exit }
+      if (!e) e = NR
+
+      # Drop the "(no ... yet" placeholder and its indented continuation lines.
+      for (i = s; i <= e; i++) {
+        if (L[i] ~ /^- \[[ xX]\] \(no / || L[i] ~ /^_\(no /) {
+          drop[i] = 1
+          for (j = i + 1; j <= e; j++) {
+            if (L[j] ~ /^[[:space:]]+[^[:space:]]/) drop[j] = 1; else break
+          }
+        }
+      }
+
+      # Anchor: first MANDATORY item, else after the last surviving list item,
+      # else at the end of the section.
+      at = 0
+      for (i = s; i <= e; i++)
+        if (!drop[i] && L[i] ~ /^- \[[ xX]\] .*MANDATORY/) { at = i; break }
+      if (!at) {
+        last = 0
+        for (i = s; i <= e; i++) if (!drop[i] && L[i] ~ /^- \[[ xX]\] /) last = i
+        if (last) {
+          for (j = last + 1; j <= e; j++) {
+            if (L[j] ~ /^[[:space:]]+[^[:space:]]/) last = j; else break
+          }
+          at = last + 1
+        }
+      }
+      if (!at) { at = e + 1; while (at > s && L[at-1] == "") at-- }
+
+      for (i = 1; i <= NR; i++) {
+        if (i == at) print newline
+        if (!drop[i]) print L[i]
+      }
+      if (at == NR + 1) print newline
+    }
+  ' "$file" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+
+  if [[ -s "$tmp" ]]; then mv "$tmp" "$file"; else rm -f "$tmp"; fi
+}
+
+###############################################################################
+# .gitignore scope
+#
+# Only completed plans are local history. Active plans are the artifact a team
+# coordinates around and that subagents read via the planning MCP — in lg mode,
+# selected precisely because there IS a team, ignoring them defeats the point.
+#
+# v1.0.0 blanket-ignored .planning/; 3.1.0's archive-plan.sh introduced the narrow
+# entry with the reasoning above but never displaced the old rule, leaving four
+# shipped docs describing a behavior the code did not have (issue #15).
+###############################################################################
+
+# planning_ensure_archive_gitignored <repo-root> [create-if-missing]
+#
+# Adds `.planning/.archive/` when absent. Never rewrites an existing blanket
+# `.planning/` entry — that is the user's file and their call — but says once how to
+# narrow it, because otherwise the plans they are about to create are invisible to
+# everyone else and nothing tells them.
+#
+# The init scripts pass no second argument: creating a .gitignore in a repo that has
+# none is not their business. archive-plan.sh passes 1 — it has just moved files into
+# .archive/ and that path has to be ignored for the move to mean anything.
+planning_ensure_archive_gitignored() {
+  local gitignore="${1}/.gitignore" create="${2:-}"
+  if [[ ! -f "$gitignore" ]]; then
+    [[ "$create" == "1" ]] || return 0
+    touch "$gitignore" 2>/dev/null || return 0
+  fi
+
+  if grep -qE '^\.planning/?$' "$gitignore" 2>/dev/null; then
+    planning_warn ".gitignore ignores all of .planning/ — plans will not be shared."
+    echo "           Active plans are what teammates and subagents read. To share them," >&2
+    echo "           replace the '.planning/' line with '.planning/.archive/'." >&2
+    return 0
+  fi
+
+  grep -qE '^\.planning/\.archive/?$' "$gitignore" 2>/dev/null && return 0
+
+  printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "$gitignore"
+  planning_ok "Added .planning/.archive/ to .gitignore (active plans stay shareable)"
+}

package/scripts/lib/skill-link.js

@@ -0,0 +1,177 @@
+// Skill-dir reclaim + drift detection.
+//
+// Why this exists: v1's `persistent-planning install` (removed in v2.0.0) COPIED
+// skills/persistent-planning/ into a consumer's .claude/skills/. The v2+ linker in
+// claude-plugin-runtime only symlinks, and when it finds a real directory at the
+// destination it warns and skips — forever. So v1 leftovers keep executing a frozen
+// copy while the update check reports the (correct, current) plugin version. Two
+// artifacts, nothing reconciling them.
+//
+// The fix is to reclaim the real directory BEFORE the runtime's linker runs: rename
+// it aside, which leaves a clean destination the linker then symlinks normally. That
+// needs no upstream change — see the phase notes for why this lives here for now.
+//
+// Nothing here ever deletes. A reclaimed directory is renamed to
+// <name>.bak-<ISO8601>, and a failure to rename falls through to the old skip.
+
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, renameSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+
+export const ENV_PREFIX = "PERSISTENT_PLANNING";
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+/** Skill directory names shipped by this package. Mirrors the runtime's filter. */
+export function packagedSkillNames(packageRoot, skillsSubdir = "skills") {
+  const dir = join(packageRoot, skillsSubdir);
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.endsWith("-workspace"))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * What is actually sitting at .claude/skills/<name>, and is it ours?
+ *
+ * Returns one of:
+ *   absent          — nothing there; the linker will create the symlink
+ *   symlink-ok      — symlink pointing at this package's copy; healthy
+ *   symlink-foreign — symlink pointing somewhere else; another install owns it
+ *   real-dir        — a real directory; v1 debris or a hand-managed copy. This is
+ *                     the drift state: nothing in the current system creates one.
+ */
+export function describeSkill(consumerRoot, packageRoot, name, skillsSubdir = "skills") {
+  const dest = join(consumerRoot, ".claude", "skills", name);
+  const src = join(packageRoot, skillsSubdir, name);
+  const st = lstatSafe(dest);
+  if (!st) return { name, dest, src, state: "absent" };
+  if (st.isSymbolicLink()) {
+    let target = null;
+    try { target = readlinkSync(dest); } catch { /* unreadable link */ }
+    const expected = relative(dirname(dest), src);
+    if (target === expected) return { name, dest, src, state: "symlink-ok", target };
+    // A different-but-equivalent path still resolves to us; treat that as healthy.
+    try {
+      if (target && resolve(dirname(dest), target) === resolve(src)) {
+        return { name, dest, src, state: "symlink-ok", target };
+      }
+    } catch { /* fall through */ }
+    return { name, dest, src, state: "symlink-foreign", target };
+  }
+  return { name, dest, src, state: "real-dir" };
+}
+
+/** Every packaged skill's current state in a consumer repo. */
+export function surveySkills(consumerRoot, packageRoot, skillsSubdir = "skills") {
+  return packagedSkillNames(packageRoot, skillsSubdir)
+    .map((n) => describeSkill(consumerRoot, packageRoot, n, skillsSubdir));
+}
+
+function backupPath(dest) {
+  // ISO8601, filesystem-safe. Collisions only within the same second on the same
+  // dir, which a suffix resolves.
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  let candidate = `${dest}.bak-${stamp}`;
+  let n = 1;
+  while (existsSync(candidate)) candidate = `${dest}.bak-${stamp}-${n++}`;
+  return candidate;
+}
+
+/**
+ * Rename any real directory at .claude/skills/<name> aside so the linker can symlink.
+ *
+ * Idempotent: a healthy symlink is left completely alone, so a second run is a no-op
+ * and produces no second backup.
+ *
+ * Returns { reclaimed: [{name, from, to}], failed: [{name, dest, error}], healthy: n }.
+ */
+export function reclaimStaleSkillDirs(consumerRoot, packageRoot, opts = {}) {
+  const { skillsSubdir = "skills", log = () => {} } = opts;
+  const result = { reclaimed: [], failed: [], healthy: 0 };
+
+  if (process.env[`${ENV_PREFIX}_NO_RECLAIM`] === "1") {
+    log(`[persistent-planning] ${ENV_PREFIX}_NO_RECLAIM=1 — leaving existing skill dirs alone.`);
+    return result;
+  }
+
+  for (const info of surveySkills(consumerRoot, packageRoot, skillsSubdir)) {
+    if (info.state !== "real-dir") {
+      if (info.state === "symlink-ok") result.healthy++;
+      continue;
+    }
+    const to = backupPath(info.dest);
+    try {
+      renameSync(info.dest, to);
+      result.reclaimed.push({ name: info.name, from: info.dest, to });
+      log(`[persistent-planning] reclaimed stale skill dir ${info.dest} -> ${to}`);
+    } catch (err) {
+      // ponytail: never rm -rf a directory a user may have hand-edited. If we cannot
+      // move it, say so loudly and leave it — the old skip, but no longer silent.
+      result.failed.push({ name: info.name, dest: info.dest, error: err?.message || String(err) });
+      log(
+        `[persistent-planning] WARNING: ${info.dest} is a real directory, not a symlink,\n` +
+        `  so it will keep running a frozen copy of the skill. Could not move it aside:\n` +
+        `  ${err?.message || err}\n` +
+        `  Move or remove it, then run:  npx persistent-planning relink`
+      );
+    }
+  }
+  return result;
+}
+
+/** Skills still drifted after a reclaim attempt — what SessionStart should warn about. */
+export function driftedSkills(consumerRoot, packageRoot, skillsSubdir = "skills") {
+  return surveySkills(consumerRoot, packageRoot, skillsSubdir)
+    .filter((s) => s.state === "real-dir" || s.state === "symlink-foreign");
+}
+
+// ── Version marker ──────────────────────────────────────────────────────────
+//
+// The drift that started issue #10 was invisible because the update check read the
+// plugin's version while /start-planning executed the skill dir's copy — same number,
+// different artifact. The primary signal is structural (describeSkill: a real dir is
+// always suspect, because nothing in the current system creates one). This marker is
+// the secondary signal: it says how far behind a drifted copy actually is, and it is
+// the only signal available on install shapes where a symlink is impossible.
+
+export const MARKER = ".version";
+
+/** Version of the skill copy that would actually execute, or null. */
+export function readSkillVersion(consumerRoot, name) {
+  try {
+    const raw = readFileSync(join(consumerRoot, ".claude", "skills", name, MARKER), "utf8");
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stamp linked skills with the version they came from.
+ *
+ * Only ever stamps a healthy symlink — never a real directory. Stamping a real dir
+ * would mark stale code as current and defeat the whole check. Best-effort: a
+ * read-only package dir (npm cache, plugin cache) just leaves the marker absent,
+ * which the drift check treats as "unknown", not "fine".
+ */
+export function writeVersionMarkers(consumerRoot, packageRoot, version, opts = {}) {
+  const { skillsSubdir = "skills" } = opts;
+  if (!version) return { stamped: [], skipped: [] };
+  const out = { stamped: [], skipped: [] };
+  for (const info of surveySkills(consumerRoot, packageRoot, skillsSubdir)) {
+    if (info.state !== "symlink-ok") { out.skipped.push(info.name); continue; }
+    try {
+      writeFileSync(join(info.dest, MARKER), `${version}\n`, "utf8");
+      out.stamped.push(info.name);
+    } catch {
+      out.skipped.push(info.name);
+    }
+  }
+  return out;
+}