@theglitchking/persistent-planning 3.1.0 → 3.4.0

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`.]