@theglitchking/persistent-planning 3.1.0 → 3.4.0

package/.documentation/troubleshooting/REGISTRY.md

@@ -3,7 +3,7 @@ title: Troubleshooting Registry
 tier: reference
 domains: [troubleshooting]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for troubleshooting documentation
 ---
@@ -16,13 +16,28 @@ purpose: Quick reference for troubleshooting documentation
 
 | Metric | Value |
 |--------|-------|
-| Documents | 0 |
+| Documents | 2 |
 | Category | advanced |
 | Load Priority | 6/10 |
 
-## Documents
+## Active Documents
 
-*No documents in this domain yet.*
+- [A plan won't read COMPLETE](plan-never-reads-complete.md)
+- [Stale skill directory — commands run frozen code](stale-skill-dir-drift.md)
+
+## Recently Updated
+
+- [A plan won't read COMPLETE](plan-never-reads-complete.md) - 2026-09-04
+- [Stale skill directory — commands run frozen code](stale-skill-dir-drift.md) - 2026-09-04
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 2 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
 
 ## Keywords
 
@@ -35,4 +50,4 @@ purpose: Quick reference for troubleshooting documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/troubleshooting/plan-never-reads-complete.md

@@ -0,0 +1,109 @@
+---
+title: A plan won't read COMPLETE
+tier: guide
+domains:
+  - troubleshooting
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: >-
+  Three reasons a plan will not read COMPLETE — an unfinished mandatory closer, a
+  placeholder counted as work, or a blocked artifact — and the fix for each.
+estimated_read_time: 2 minutes
+word_count: 264
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# A plan won't read COMPLETE
+
+`/plan-status` shows a plan stuck below 100%, or at `100%` but still `in progress`,
+and it is not obvious what is outstanding. There are three causes with three
+different fixes.
+
+## 1. Every box is ticked but it still says `in progress`
+
+```
+my-phase        in progress   13/13 boxes
+```
+
+A **mandatory closing task is not done.** Ticking its checkbox in `phase.md` is not
+enough — the closer's own `task.md` must carry `status: done`.
+
+```bash
+grep -l '^mandatory: true' .planning/my-phase/*/task.md | xargs grep -H '^status:'
+```
+
+Anything not `done` or `archived` is what is holding the plan open. Finish the work,
+then set `status: done` in that task's frontmatter.
+
+This is deliberate. A closer that was ticked but never performed is precisely the
+failure the gate exists to catch — see
+[`mandatory:` frontmatter](../reference/mandatory-frontmatter.md).
+
+## 2. The count includes a box that isn't work
+
+```
+my-phase        in progress   0/5 boxes     # but only 2 real tasks exist
+```
+
+Older plans carry the placeholder lines as **checkboxes**:
+
+```markdown
+- [ ] (no tasks yet — run `/start-task …`)
+- [ ] (no atoms yet — add inline checkboxes here for simple atoms,
+      or run `/start-atom …` for complex ones)
+```
+
+`plan-status.sh` counts every `- [ ]` under a plan, so those inflate the total and the
+plan cannot finish until someone ticks a line that says nothing exists.
+
+**Fix:** delete the placeholder line, or add a real task/atom — from 3.3.0 the init
+scripts remove it automatically on first insert. New plans ship the placeholders as
+italic text, which is not counted.
+
+## 2b. Quoted markdown used to count (fixed in 3.3.1)
+
+Before 3.3.1, three readers scanned whole files: the checkbox counter, the mandatory
+gate, and blocked detection. A `notes.md` that merely *documented* the contract tripped
+all three — a fenced `- [ ]` example inflated the denominator, a fenced `mandatory: true`
+held the plan open with the box count reading a perfect `n/n`, and a fenced
+`status: blocked` produced a false `blocked` verdict.
+
+Frontmatter fields are now read from frontmatter only, and checkbox counting skips fenced
+code blocks. If you are on an older version, move the example out of the plan or upgrade.
+
+## 3. Something under the plan is `status: blocked`
+
+```
+my-phase        blocked       7/20 boxes
+```
+
+`plan-status.sh` reports `blocked` when any artifact under the plan has
+`status: blocked`. Find it:
+
+```bash
+grep -rl '^status: blocked' .planning/my-phase/
+```
+
+That is a report, not a defect — the plan is telling you what it is waiting on.
+
+## Checking the whole picture
+
+```bash
+bash scripts/plan-status.sh            # table: in progress / blocked / COMPLETE / empty
+bash scripts/plan-status.sh --complete # one complete slug per line, for scripts
+```
+
+`archive-plan.sh` refuses an incomplete plan using the same check, so anything above
+that blocks COMPLETE also blocks archiving. `--force` overrides it; nothing is ever
+deleted either way.
+
+## Related
+
+- [Plan completion and archive](../procedures/plan-completion-and-archive.md)
+- [lg plan artifact lifecycle](../architecture/lg-plan-artifact-lifecycle.md)
+- [Mandatory closing phases](../standards/mandatory-closing-phases.md)

package/.documentation/troubleshooting/stale-skill-dir-drift.md

@@ -0,0 +1,115 @@
+---
+title: Stale skill directory — commands run frozen code
+tier: guide
+domains:
+  - troubleshooting
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: Symptom, cause, detection and repair for a stale .claude/skills/persistent-planning
+  directory that makes commands run frozen pre-3.1.0 code (issue #10).
+estimated_read_time: 3 minutes
+word_count: 403
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# Stale skill directory — commands run frozen code
+
+`/start-planning` produces a plan that is missing the mandatory validate and
+documentation phases, and has no `## On Completion` archive block. No warning is
+shown. `npx persistent-planning status` reports the current version. Everything
+exits 0.
+
+This is the failure mode from [issue #10](https://github.com/the-glitch-kingdom/persistent-planning/issues/10),
+fixed in 3.2.0.
+
+## Symptom
+
+A generated `task_plan.md` ends at Phase 4. A correct one ends:
+
+```
+- [ ] Phase 5: Validate success through comprehensive testing (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)
+```
+
+and carries an `## On Completion` section naming `/plan-status` and `/archive-plan`.
+
+## Cause
+
+`.claude/skills/persistent-planning/` is a **real directory** instead of a symlink
+into the installed package. v1's `persistent-planning install` (removed in 2.0.0)
+copied the skill dir. The v2+ linker only symlinks, and when it found a real
+directory at the destination it warned once during `npm install` and skipped —
+permanently.
+
+The result: the update check read the *plugin's* version while `/start-planning`
+executed the *skill dir's* frozen copy. Same version number, different artifact,
+nothing reconciling them. `commands/start-planning.md` lists
+`~/.claude/skills/persistent-planning/scripts/init-planning.sh` among its fallback
+paths, and in a v1-era skill dir that file exists — so the stale copy wins.
+
+## Detect
+
+**Check the shape, not the contents:**
+
+```bash
+ls -ld .claude/skills/persistent-planning
+```
+
+A symlink is healthy. A real directory is drift — nothing in the current system
+creates one.
+
+**Confirm how far behind, by diff:**
+
+```bash
+diff <path-to-package>/scripts/init-planning.sh \
+     .claude/skills/persistent-planning/scripts/init-planning.sh
+```
+
+> **Do not verify by keyword grep.** Counting `Phase` or `MANDATORY` occurrences
+> reported the known-stale copies as healthy during triage; only `diff` exposed the
+> 23-line gap. See [Skill version marker](../reference/skill-version-marker.md) for
+> the version signal.
+
+From 3.2.0 the SessionStart hook detects this for you and prints the path, the
+running version vs the installed one, and the fix.
+
+## Fix
+
+On 3.2.0 or later, with `updatePolicy: auto`, the next session repairs it by itself
+— once per plugin version. Otherwise:
+
+```bash
+npx persistent-planning relink
+```
+
+Either way the original is renamed to `.claude/skills/persistent-planning.bak-<timestamp>`.
+**Nothing is deleted.** Delete the backup yourself once you are satisfied.
+
+If the directory is tracked in git — v1's installer sometimes committed it — the
+repair shows up as deleted files plus a new symlink. That is a real commit for that
+repo to take, and a prompt to decide whether a skill dir belongs in version control
+at all.
+
+## When repair cannot run
+
+`relink` reports a rename failure and leaves the directory alone rather than
+deleting anything. Move it aside by hand and re-run. To manage the directory
+yourself and silence the machinery:
+
+```bash
+PERSISTENT_PLANNING_NO_RECLAIM=1   # never reclaim
+PERSISTENT_PLANNING_SKIP_LINK=1    # never link at all
+```
+
+`updatePolicy: off` also suppresses both the warning and the repair.
+
+## Related
+
+- [Skill linking and reclaim](../architecture/skill-linking-and-reclaim.md) — how it works
+- [Plugin update delivery](../procedures/plugin-update-delivery.md) — why the hook, not postinstall
+- [Skill version marker](../reference/skill-version-marker.md) — the `.version` contract

package/.documentation/workflows/INDEX.md

@@ -3,7 +3,7 @@ title: Workflows Documentation Index
 tier: reference
 domains: [workflows]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of workflows documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: workflow, workflows, process, processes, flow, flowchart, se
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/workflows/REGISTRY.md

@@ -3,7 +3,7 @@ title: Workflows Registry
 tier: reference
 domains: [workflows]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for workflows documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for workflows documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/CHANGELOG.md

@@ -2,6 +2,155 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0] - 2026-09-04
+
+### Changed — only completed plans are gitignored (#15)
+
+Both init scripts blanket-ignored the entire `.planning/` tree, a v1.0.0 behavior
+(`fb35f19`) that 3.1.0 implicitly reversed and never removed. `archive-plan.sh` had
+already decided only completed plans are local history, and four shipped docs —
+`SKILL.md`, `lg-mode.md` (twice), `README.md` — described `.planning/.archive/` as *the*
+gitignored path. The code did the opposite.
+
+In lg mode the contradiction was sharpest: that mode is selected because ≥2 git authors
+exist, plans are what subagents read via the planning MCP, and the first thing
+`init-phase.sh` did was guarantee no teammate would ever receive them. The blanket entry
+also suppressed `archive-plan.sh`'s narrow one — its first guard returns early when the
+whole tree is ignored — so the narrow entry could never appear in a repo where
+`/start-planning` had run, which is every repo.
+
+- **Active plans are tracked; only `.planning/.archive/` is ignored.** One rule, shared by
+  both lg init and `archive-plan.sh` via `planning_ensure_archive_gitignored`;
+  `init-planning.sh` keeps its own copy since it is deliberately self-contained.
+- **An existing blanket `.planning/` line is never rewritten.** It is the user's file. The
+  tool says once how to narrow it and moves on — otherwise the plans someone is about to
+  create are invisible to their team and nothing tells them.
+- **Init still never creates a `.gitignore`** where none exists. `archive-plan.sh` does,
+  because it has just moved files into `.archive/` and that path must be ignored for the
+  move to mean anything.
+
+sm plan output remains byte-identical. Test suite grows to 119 assertions.
+
+## [3.3.1] - 2026-09-04
+
+### Fixed — a plan that documented markdown could not complete (#14)
+
+`plan-status.sh` had one correct frontmatter reader and three that scanned whole files:
+the checkbox counter, the mandatory gate, and blocked detection. A `notes.md` that merely
+*documented* the contract — which is what notes.md is for — tripped all three:
+
+- a fenced `- [ ]` example inflated the denominator, so the plan could never reach
+  COMPLETE. A quoted `- [x]` cancelled out; a quoted `- [ ]` did not.
+- a fenced `mandatory: true` held the plan open with the box count showing a perfect
+  `1/1` — **no visible signal at all**, and the documented triage steps pointed at a
+  notes file that was pure prose. Regression from #13.
+- a fenced `status: blocked` produced a false `blocked` verdict, masked whenever the plan
+  was otherwise COMPLETE, so it surfaced only intermittently.
+
+`archive-plan.sh` inherited all three through its pre-flight and refused to archive,
+advising `--force` — wrong advice for a miscount.
+
+The fix splits in two, because these are not the same defect:
+
+- **Checkboxes are body content**, so counting is now fence-aware — backtick and tilde
+  fences, tagged or not, indented, closing only on their own character. An unterminated
+  fence swallows the rest of the file: ambiguous content is not counted as outstanding.
+- **`status:` and `mandatory:` are frontmatter fields**, so they are read from the leading
+  `---` block via the existing scoped reader, generalised as `frontmatter_field`. That is
+  strictly stronger than fence-stripping — it also rejects the field appearing in prose or
+  a table.
+
+All consumers — `archive-plan.sh`, `/plan-status`, the SessionStart hook — shell out to
+`plan-status.sh` and needed no change. Test suite grows to 109 assertions.
+
+## [3.3.0] - 2026-09-04
+
+### Fixed — lg task lists were maintained by hand, and the mandatory closers were unenforceable (#12)
+
+`init-task.sh` never wrote to `phase.md` — it referenced the file only in an existence
+check — and `init-atom.sh` never wrote the atom into its task. So **every lg task list was
+maintained by hand**: create six task directories and the phase still reported
+`(no tasks yet)`. The "closers must stay last" rule therefore governed a list no tool
+produced, and the test that claimed to cover it only ever inspected a freshly rendered
+template, which can never be wrong.
+
+- **Creating a child writes it into its parent's list.** `planning_insert_list_item` in
+  `scripts/lib/planning.sh` inserts above the first `MANDATORY` entry — so the closers stay
+  last *by construction* — appends after the last item in sections with no MANDATORY
+  entries, drops the placeholder on first use, is idempotent under `PLANNING_FORCE=1`, and
+  is section-scoped. It anchors on the MANDATORY marker, never on line numbers, because the
+  list is a human-editable surface.
+- **The closers are real task directories now.** `init-phase.sh` scaffolds
+  `validate-success-through-comprehensive-testing/` and
+  `documentation-pass-create-update-deprecate-docs/` with `task.md` (`mandatory: true`,
+  `parallelizable: false`), `notes.md`, `atoms/`, and seeded atoms. Previously the two most
+  important tasks in every plan were the only ones with no artifact a subagent could read.
+- **Placeholders stopped counting as work.** `(no tasks yet …)` and `(no atoms yet …)`
+  shipped as real checkboxes, and `plan-status.sh` counts every box under a plan — a fresh
+  phase with two tasks reported `0/5`, a plan could reach 100% by ticking lines asserting
+  nothing existed, and a finished phase stayed open until someone ticked "no tasks yet".
+  They are italic text now; `plan-status.sh` needed no change.
+- **The completion gate is real.** `plan-status.sh` refuses `COMPLETE` while any
+  `mandatory: true` task's own `status:` is not `done`. Ticking its checkbox is not enough.
+  `archive-plan.sh` inherits this through its existing pre-flight rather than duplicating
+  the rule. Strictly additive: plans with no `mandatory:` frontmatter behave exactly as
+  before.
+
+Test suite grows to 99 assertions, every new one mutating the plan before asserting.
+sm mode verified byte-identical against the pre-change render. New docs:
+`.documentation/architecture/lg-plan-artifact-lifecycle.md`,
+`.documentation/reference/mandatory-frontmatter.md`,
+`.documentation/troubleshooting/plan-never-reads-complete.md`.
+
+## [3.2.0] - 2026-09-04
+
+### Fixed — Stale skill directories run frozen code (#10)
+
+A consumer repo could run a **pre-3.1.0 copy** of the skill indefinitely while the update
+check reported the current version — no nudge, no warning, exit 0 everywhere. Plans
+generated that way silently omitted the mandatory validate and documentation phases and
+the entire `## On Completion` archive block: precisely the guarantees 3.1.0 was released
+to make.
+
+**Cause.** v1's `persistent-planning install` (removed in 2.0.0) *copied*
+`skills/persistent-planning/` into `.claude/skills/`. The v2+ linker only symlinks, and
+when it finds a real directory at the destination it warns and skips — permanently. So
+`installedVersion()` reported the plugin's version while `/start-planning` executed the
+skill dir's frozen copy. Two artifacts, nothing reconciling them. (The linker was never
+copying, as first reported; it was refusing to reclaim what v1 left behind.)
+
+- **Reclaim instead of skip** — `scripts/lib/skill-link.js` renames a real directory to
+  `<name>.bak-<ISO8601>` before the runtime's linker runs, leaving a clean destination it
+  then symlinks normally. Nothing is ever deleted; a failed rename falls through to the
+  old skip but says so loudly and names the fix. Idempotent — a healthy symlink is left
+  alone, so a second run makes no second backup. Opt out with
+  `PERSISTENT_PLANNING_NO_RECLAIM=1`.
+- **The drift is detectable now.** The primary signal is structural: a real directory at
+  `.claude/skills/<name>` is *always* drift, because nothing in the current system creates
+  one. A `.version` marker beside `SKILL.md` is the secondary signal — how far behind a
+  drifted copy is, and the only signal available where symlinks are impossible. Only
+  healthy symlinks are stamped; stamping a stale copy would mark it current.
+- **SessionStart reports it**, naming the path, the running vs installed version, the
+  user-visible consequence, and `npx persistent-planning relink`. Merged into the existing
+  single JSON response; fails open; silent under `updatePolicy: off`.
+- **SessionStart repairs it under `updatePolicy: auto`**, once per plugin version. This is
+  the part that reaches the installs that are actually broken: a marketplace install has
+  no `node_modules` in the plugin cache and **never runs npm postinstall**, so a fix
+  shipped only through postinstall would reach nobody affected. The hook is the one thing
+  that runs every session in that shape. `nudge` warns without touching the filesystem;
+  `off` does nothing at all.
+- **No more clean exits for no-ops.** `update` with no managed install exits 1 and lists
+  every path probed, instead of printing `(not installed)` twice and exiting 0. `relink`
+  gained `CLAUDE_PLUGIN_ROOT/scripts/` and self-package probes — it previously could not
+  run at all in a marketplace-only install, the shape that needs it most — and no longer
+  swallows the linker's exit code.
+
+Test suite grows to 74 assertions, including a marketplace-shaped fixture with no
+`node_modules`. New docs: `.documentation/troubleshooting/stale-skill-dir-drift.md`,
+`.documentation/architecture/skill-linking-and-reclaim.md`,
+`.documentation/reference/skill-version-marker.md`,
+`.documentation/procedures/plugin-update-delivery.md`.
+
 ## [3.1.0] - 2026-08-31
 
 ### Added — Status tracking and completion archive (#4)

package/bin/persistent-planning.js

@@ -5,25 +5,49 @@ import { registerUpdateCommands } from "@theglitchking/claude-plugin-runtime";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const require_ = createRequire(import.meta.url);
 const { version } = require_("../package.json");
 
 const PKG = "@theglitchking/persistent-planning";
 
+// Where the linker can live, most specific first. The third probe matters: in a
+// marketplace-only install there is no node_modules and cwd is the consumer repo,
+// so the first two both miss and relink -- the one command that repairs a stale
+// skill dir -- could not run at all in exactly the shape that needs it.
+function linkerCandidates(cwd) {
+  const out = [
+    join(cwd, "node_modules", "@theglitchking", "persistent-planning", "scripts", "link-skills.js"),
+    resolve(process.cwd(), "scripts", "link-skills.js"),
+  ];
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    out.push(join(process.env.CLAUDE_PLUGIN_ROOT, "scripts", "link-skills.js"));
+  }
+  // The package this CLI is itself running from — correct for `npx <pkg> relink`.
+  out.push(resolve(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "link-skills.js"));
+  return out;
+}
+
 function runRelink(cwd) {
-  const linker = join(cwd, "node_modules", "@theglitchking", "persistent-planning", "scripts", "link-skills.js");
-  const script = existsSync(linker) ? linker : resolve(process.cwd(), "scripts", "link-skills.js");
-  if (!existsSync(script)) {
-    console.error("link-skills.js not found — is the package installed?");
+  const candidates = linkerCandidates(cwd);
+  const script = candidates.find((p) => existsSync(p));
+  if (!script) {
+    // ponytail: never exit 0 after doing nothing — a clean success for a no-op is
+    // how the stale-skill-dir bug stayed invisible for five months (issue #10).
+    console.error("relink failed: link-skills.js not found. Looked in:");
+    for (const p of candidates) console.error(`  ${p}`);
+    console.error("\nIs @theglitchking/persistent-planning installed, or CLAUDE_PLUGIN_ROOT set?");
+    process.exitCode = 1;
     return;
   }
-  spawnSync(process.execPath, [script], {
+  const r = spawnSync(process.execPath, [script], {
     cwd,
     env: { ...process.env, INIT_CWD: cwd },
     stdio: "inherit",
   });
+  if (r.status !== 0) process.exitCode = r.status ?? 1;
 }
 
 program
@@ -31,6 +55,32 @@ program
   .description("Persistent markdown-based planning for Claude Code.")
   .version(version);
 
+// The runtime's `update` resolves the installed version, finds none in a
+// marketplace-only install, prints "Current: (not installed) / Now: (not installed)"
+// and exits 0 -- a clean success for a no-op. Fail before it gets that far, and say
+// where we looked. Same defect as runRelink's missing third probe (issue #10, fix #4).
+// Deliberately NOT including the package this CLI runs from: under
+// `npx --no @theglitchking/persistent-planning update` that copy always exists, which
+// is what let the original bug report see a clean exit 0 for a no-op. Only a *managed*
+// install -- a project dependency or a marketplace plugin root -- is updatable.
+function installCandidates(cwd) {
+  const out = [join(cwd, "node_modules", "@theglitchking", "persistent-planning", "package.json")];
+  if (process.env.CLAUDE_PLUGIN_ROOT) out.push(join(process.env.CLAUDE_PLUGIN_ROOT, "package.json"));
+  return out;
+}
+
+program.hook("preAction", (_thisCmd, actionCmd) => {
+  if (actionCmd.name() !== "update") return;
+  const candidates = installCandidates(process.cwd());
+  if (candidates.some((p) => existsSync(p))) return;
+  console.error("update failed: no managed install of @theglitchking/persistent-planning found.");
+  console.error("Looked in:");
+  for (const p of candidates) console.error(`  ${p}`);
+  console.error("\nInstall it with `npm i -D @theglitchking/persistent-planning`,");
+  console.error("or update the marketplace plugin with `/plugin` inside Claude Code.");
+  process.exit(1);
+});
+
 registerUpdateCommands(program, {
   packageName: PKG,
   pluginName: "persistent-planning",