@theglitchking/persistent-planning 3.1.0 → 3.4.1

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;
+}

package/scripts/link-skills.js

@@ -1,12 +1,40 @@
 #!/usr/bin/env node
 // Postinstall — delegates to @theglitchking/claude-plugin-runtime.
 // See https://github.com/TheGlitchKing/claude-plugin-runtime/blob/main/docs/PLUGIN_AUTHORING_SCAFFOLD.md
+//
+// One thing runs before the delegation: reclaimStaleSkillDirs(). The runtime's linker
+// skips a destination that is a real directory rather than a symlink, and skips it
+// forever — so v1 leftovers never heal. Renaming the real dir aside first leaves a
+// clean destination the runtime then links normally.
 
 import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reclaimStaleSkillDirs, writeVersionMarkers, ENV_PREFIX } from "./lib/skill-link.js";
+import { createRequire } from "node:module";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const consumerRoot = process.env.INIT_CWD || process.cwd();
+
+try {
+  // Skip when the runtime itself would skip: dev-in-place, or linking disabled.
+  const devInPlace = resolve(consumerRoot) === resolve(packageRoot);
+  if (!devInPlace && process.env[`${ENV_PREFIX}_SKIP_LINK`] !== "1") {
+    const r = reclaimStaleSkillDirs(consumerRoot, packageRoot, {
+      skillsSubdir: "skills",
+      log: (m) => console.log(m),
+    });
+    if (r.reclaimed.length) {
+      console.log(
+        `[persistent-planning] reclaimed ${r.reclaimed.length} stale skill dir(s); ` +
+        `originals kept alongside as .bak-* — delete them once you are satisfied.`
+      );
+    }
+  }
+} catch (err) {
+  // Reclaim is best-effort. A failure here must never block the install.
+  console.warn(`[persistent-planning] skill reclaim skipped: ${err?.message || err}`);
+}
 
 try {
   runPostinstall({
@@ -21,3 +49,13 @@ try {
 } catch (err) {
   console.warn(`[persistent-planning] postinstall failed: ${err?.message || err}`);
 }
+
+try {
+  // Stamp the artifact that actually executes, so drift is detectable at all.
+  // Only healthy symlinks are stamped — never a real dir, which would mark stale
+  // code as current.
+  const { version } = createRequire(import.meta.url)("../package.json");
+  writeVersionMarkers(consumerRoot, packageRoot, version, { skillsSubdir: "skills" });
+} catch {
+  // Marker is a diagnostic aid, not a dependency. Absent is a valid state.
+}

package/scripts/plan-status.sh

@@ -45,22 +45,91 @@ plan_root_artifact() {
   done
 }
 
+# frontmatter_field <file> <key> -> value of `<key>:` inside the leading --- block
+#
+# Scoped to the frontmatter on purpose. Grepping a whole file for a frontmatter field
+# matches it in prose, tables and fenced examples too — a notes.md documenting the
+# contract then reads as an artifact that declares it (issue #14).
+frontmatter_field() {
+  [[ -f "$1" ]] || return
+  awk -v key="$2" '
+    NR==1 && $0 != "---" { exit }
+    NR>1 && $0 == "---" { exit }
+    index($0, key ":") == 1 {
+      sub("^" key ":[[:space:]]*", "")
+      gsub(/["\047]/, "")
+      sub(/[[:space:]]+$/, "")
+      print; exit
+    }' "$1"
+}
+
 # frontmatter_status <file> -> value of `status:` inside the leading --- block
 frontmatter_status() {
-  [[ -f "$1" ]] || return
-  awk 'NR==1 && $0 != "---" { exit }
-       NR>1 && $0 == "---" { exit }
-       /^status:[[:space:]]*/ { sub(/^status:[[:space:]]*/, ""); gsub(/["\047]/, ""); print; exit }' "$1"
+  frontmatter_field "$1" "status"
 }
 
 # Emits "<total> <checked>" for every markdown file under a plan directory.
+#
+# Checkboxes inside fenced code blocks are examples, not work. A plan whose notes.md
+# quotes markdown — which is what notes.md is for — used to have those quoted boxes
+# counted against it, and a quoted `- [ ]` inflates only the denominator, so the plan
+# became permanently uncompletable with no visible reason (issue #14).
+#
+# An unterminated fence swallows the rest of the file. That is the safe direction:
+# ambiguous content is not counted as outstanding work.
 count_boxes() {
-  local total checked
-  total=$(grep -rhoE '^[[:space:]]*- \[[ xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
-  checked=$(grep -rhoE '^[[:space:]]*- \[[xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
+  local total=0 checked=0 f out
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    out=$(awk '
+      # Fence open/close: ``` or ~~~, optionally indented, optional info string.
+      # A fence closes only on the same character.
+      /^[[:space:]]*(```|~~~)/ {
+        line = $0
+        sub(/^[[:space:]]*/, "", line)
+        ch = substr(line, 1, 1)
+        if (!infence) { infence = 1; fencechar = ch }
+        else if (ch == fencechar) { infence = 0 }
+        next
+      }
+      infence { next }
+      /^[[:space:]]*- \[[ xX]\] / { t++ }
+      /^[[:space:]]*- \[[xX]\] /  { c++ }
+      END { print t + 0, c + 0 }
+    ' "$f" 2>/dev/null) || continue
+    total=$((total + ${out%% *}))
+    checked=$((checked + ${out##* }))
+  done < <(find "$1" -type f -name '*.md' 2>/dev/null)
   echo "$total $checked"
 }
 
+# Files under a plan whose FRONTMATTER declares <key>: <value>.
+frontmatter_files_with() {
+  local dir="$1" key="$2" want="$3" f
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    [[ "$(frontmatter_field "$f" "$key")" == "$want" ]] && echo "$f"
+  done < <(find "$dir" -type f -name '*.md' 2>/dev/null)
+}
+
+# Counts mandatory tasks under a plan that are not yet done.
+#
+# The two closing tasks carry `mandatory: true`. A plan cannot be COMPLETE while one
+# of them is unfinished, however the boxes happen to add up — that gate was stated in
+# the templates and enforced nowhere (issue #12).
+#
+# Additive by design: a plan with no `mandatory: true` artifacts behaves exactly as it
+# did before. Retroactively reopening finished plans would be worse than the bug.
+unfinished_mandatory() {
+  local n=0 f st
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    st=$(frontmatter_status "$f")
+    [[ "$st" == "done" || "$st" == "archived" ]] || n=$((n + 1))
+  done < <(frontmatter_files_with "$1" "mandatory" "true")
+  echo "$n"
+}
+
 COMPLETE=()
 ROWS=()
 
@@ -74,13 +143,19 @@ for plan_path in "$PLANNING"/*/; do
 
   read -r total checked <<<"$(count_boxes "${plan_path%/}")"
   status=$(frontmatter_status "$root")
-  blocked=$(grep -rl '^status: blocked' --include='*.md' "${plan_path%/}" 2>/dev/null | wc -l | tr -d ' ')
+  blocked=$(frontmatter_files_with "${plan_path%/}" "status" "blocked" | wc -l | tr -d ' ')
+  pending_mandatory=$(unfinished_mandatory "${plan_path%/}")
 
   if [[ "$status" == "archived" ]]; then
     verdict="archived"
   elif [[ "$status" == "done" ]] || { [[ "$total" -gt 0 ]] && [[ "$checked" -eq "$total" ]]; }; then
-    verdict="COMPLETE"
-    COMPLETE+=("$slug")
+    if [[ "$pending_mandatory" -gt 0 ]]; then
+      # Every box ticked, but a mandatory closer is not done. Not complete.
+      verdict="in progress"
+    else
+      verdict="COMPLETE"
+      COMPLETE+=("$slug")
+    fi
   elif [[ "$blocked" -gt 0 ]]; then
     verdict="blocked"
   elif [[ "$total" -eq 0 ]]; then

package/skills/persistent-planning/SKILL.md

@@ -161,7 +161,7 @@ Create this file FIRST for any complex task:
 - [ ] 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.
@@ -169,7 +169,10 @@ Create this file FIRST for any complex task:
 > - **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]

package/templates/lg/phase.md

@@ -20,9 +20,9 @@ Each task is a bounded deliverable. Tasks default to dependencies-first scheduli
 Tasks with no inter-dependencies can be marked `parallelizable: true` in their frontmatter
 so subagent teams can pick them up concurrently.]
 
-- [ ] (no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)
-- [ ] **Validate success through comprehensive testing** (MANDATORY — second-to-last)
-- [ ] **Documentation pass — create/update/deprecate docs** (MANDATORY — last)
+_(no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)_
+- [ ] **Validate success through comprehensive testing** (`validate-success-through-comprehensive-testing`) (MANDATORY — second-to-last)
+- [ ] **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..** (`documentation-pass-create-update-deprecate-docs`) (MANDATORY — last)
 
 > The two mandatory closing tasks above MUST remain the last two tasks of this phase.
 > Add new tasks above them; never after. A phase cannot be marked `done` until both are
@@ -31,7 +31,10 @@ so subagent teams can pick them up concurrently.]
 > - **Validate success**: prove the phase's work with tests that fail if it breaks.
 > - **Documentation pass**: create/update/deprecate every doc this phase 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.
 
 ## Decisions Made
 [Phase-level decisions that affect multiple tasks. Format: `**Decision**: rationale`.]

package/templates/lg/task.md

@@ -9,6 +9,7 @@ plan_kind: task
 parent: PHASE_SLUG_PLACEHOLDER
 depends_on: []
 parallelizable: false
+mandatory: false
 ---
 
 # Task: TASK_TITLE_PLACEHOLDER
@@ -29,8 +30,8 @@ under `atoms/` that subagents read via the planning MCP.
 Inline checkbox vs. standalone atom file — see anti-pattern doc:
 .documentation/standards/atom-granularity.md.]
 
-- [ ] (no atoms yet — add inline checkboxes here for simple atoms,
-      or run `/start-atom "Atom name" --parent TASK_SLUG_PLACEHOLDER` for complex ones)
+_(no atoms yet — add inline checkboxes here for simple atoms,
+or run `/start-atom "Atom name" --parent TASK_SLUG_PLACEHOLDER` for complex ones)_
 
 ## Decisions Made
 [Task-level decisions. Format: `**Decision**: rationale`.]