@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/.documentation/testing/test-suite.md

@@ -0,0 +1,126 @@
+---
+title: Test Suite
+tier: guide
+domains:
+  - testing
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: What tests/run.sh covers, how to run it, how to add an assertion, and
+  why the suite is plain bash rather than a framework.
+estimated_read_time: 3 minutes
+word_count: 450
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Test Suite
+
+`tests/run.sh` is the whole test suite. It is plain bash with assert helpers —
+no framework, no fixtures, no dependencies beyond what the scripts under test
+already need.
+
+## Why bash and not a framework
+
+Everything under test *is* bash. `init-planning.sh`, `init-phase.sh`,
+`init-task.sh`, `init-atom.sh`, and `detect-mode.sh` are shell scripts whose
+observable behavior is "what landed on disk." A JS test runner would add a
+dependency, a config file, and a translation layer between the runner and the
+thing being run, to assert the same `grep`s. The suite stays in the language of
+its subject.
+
+The suite is also the thing that makes the
+[mandatory closing phases](../standards/mandatory-closing-phases.md) enforceable rather than
+aspirational: a template edit that pushes a checkbox below the closing pair turns
+the suite red.
+
+## How to run it
+
+```bash
+npm test           # preferred
+bash tests/run.sh  # identical, no npm needed
+```
+
+Output is one line per assertion and a `N passed, M failed` summary. Exit status
+is non-zero if anything failed, so it drops into CI unchanged.
+
+## What it covers
+
+| Group | Asserts |
+|---|---|
+| sm mode | `task_plan.md` + `notes.md` land at the slugified path; the plan seeds 6 phases; validation is second-to-last and documentation is last; the ordering rule text is present; the task name is substituted; re-running does not clobber an edited plan |
+| lg mode | `detect-mode.sh` honors the `workspace.json` override; `phase.md` + `notes.md` are created; the two closing tasks are last and in order; HEWTD `tier: plan` frontmatter is present; no `PLACEHOLDER` tokens survive rendering; `task.md` is created with the right `parent:`; atom `sequence:` auto-increments 1 → 2 |
+| mode guards | `init-phase.sh` exits non-zero in sm mode |
+
+Every test runs the real script against a throwaway `CLAUDE_PROJECT_DIR` created
+with `mktemp -d`, then removes it. Nothing touches the repository's own
+`.planning/` tree.
+
+## How to add an assertion
+
+Use the helpers already in the file — `assert_eq`, `assert_contains`,
+`assert_file`, and `checkbox_lines` (which extracts the checkbox lines of a named
+markdown section). A new case looks like:
+
+```bash
+WS=$(new_workspace)
+CLAUDE_PROJECT_DIR="$WS" bash "$REPO_DIR/scripts/init-planning.sh" "Some Task" >/dev/null
+assert_contains "$WS/.planning/some-task/task_plan.md" "## Goal" "plan has a Goal section"
+rm -rf "$WS"
+```
+
+**Then prove the assertion can fail.** Break the template on purpose, run
+`npm test`, confirm the new line goes red, and restore it. An assertion that has
+never failed is not known to test anything.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `no unsubstituted placeholders remain` fails | A template gained a `*_PLACEHOLDER` token with no matching substitution arg | Add the `KEY=value` pair to the matching `planning_render_and_log` call |
+| `init-phase.sh refuses to run in sm mode` fails | The lg-mode guard was dropped from an init script | Restore the `planning_mode` check |
+| Every lg assertion fails at once | `templates/lg/` not resolvable from the script directory | Check the `TEMPLATE_DIR` fallback chain in the init scripts |
+| Tests pass locally, lg mode broken for installed users | `templates/` or `scripts/` missing from the `files` array in `package.json` | Add them, verify with `npm pack` before publishing |
+
+That last row is not hypothetical — it is exactly how v3.0.0 shipped broken.
+
+
+## The marketplace-shaped fixture
+
+The skill-reclaim tests (issue #10) build a consumer workspace with **no
+`node_modules`**, mirroring a Claude Code marketplace install — the shape that never
+runs npm postinstall, and the shape that was actually broken. Driving the SessionStart
+hook against it proves a repair lands with no `npm install` anywhere in the path.
+
+A test that only passes under `npm install` proves nothing about that population. See
+[Plugin update delivery](../procedures/plugin-update-delivery.md).
+
+## Assert by diff, not by feature-grep
+
+When checking that generated output matches a template, `diff` it. During triage of
+issue #10 a keyword count (`phases: 6 | closers: 2`) reported two known-stale copies as
+healthy; only `diff` exposed the 23-line gap, including an entirely missing
+`## On Completion` block.
+
+Likewise, assertions against the SessionStart payload parse it as JSON rather than
+string-matching. The failure being guarded is an invalid second response line — a
+substring check would pass on malformed output.
+
+
+## Assert after mutation, not at render
+
+The ordering rule for the mandatory closers went unenforced for a long time while a
+test claimed to cover it. That test asserted the order of two checkbox lines in a
+*freshly rendered template* — which can never be wrong, because nothing had happened to
+it yet.
+
+Assertions about an invariant must mutate the plan first: create a phase, add several
+tasks, then check the closers are still last. The issue #12 block does this throughout,
+including against a hand-reordered, partially-checked, annotated list.
+
+The same instinct applies elsewhere in this suite: verify generated output by `diff`
+rather than keyword count, and parse the SessionStart payload as JSON rather than
+string-matching it.

package/.documentation/troubleshooting/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Troubleshooting Documentation Index
+tier: reference
+domains: [troubleshooting]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of troubleshooting documentation
+---
+
+# Troubleshooting Documentation
+
+> Debug guides, common issues, solutions
+
+## Overview
+
+- **Total Documents:** 2
+- **Domain:** `troubleshooting/`
+- **Category:** advanced
+- **Load Priority:** 6/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [A plan won't read COMPLETE](plan-never-reads-complete.md) | active | 2026-09-04 | 264 |
+| [Stale skill directory — commands run frozen code](stale-skill-dir-drift.md) | active | 2026-09-04 | 403 |
+
+## Keywords
+
+This domain covers: troubleshooting, troubleshoot, debug, debugging, issue, issues, problem, problems, error, errors
+
+## Related Domains
+
+- [Agents](../agents/) - Expert agent documentation, specialty matrix
+- [Backups](../backups/) - Backup/restore guides, disaster recovery
+- [Plans](../plans/) - Planning documents, roadmaps, proposals
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/troubleshooting/REGISTRY.md

@@ -0,0 +1,53 @@
+---
+title: Troubleshooting Registry
+tier: reference
+domains: [troubleshooting]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for troubleshooting documentation
+---
+
+# Troubleshooting Registry
+
+> Quick reference for debug guides, common issues, solutions.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 2 |
+| Category | advanced |
+| Load Priority | 6/10 |
+
+## Active Documents
+
+- [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
+
+`troubleshooting` `troubleshoot` `debug` `debugging` `issue` `issues` `problem` `problems` `error` `errors` `fix` `solution` `solutions` `resolve` `diagnose` `diagnosis` `log` `logs` `faq`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*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

@@ -0,0 +1,43 @@
+---
+title: Workflows Documentation Index
+tier: reference
+domains: [workflows]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of workflows documentation
+---
+
+# Workflows Documentation
+
+> Process documentation, multi-step operations
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `workflows/`
+- **Category:** features
+- **Load Priority:** 5/10
+
+## Documents
+
+*No documents in this domain yet.*
+
+To add a document:
+
+1. Create a markdown file in this directory
+2. Add YAML frontmatter with required metadata
+3. Run `npx hit-em-with-the-docs integrate <file>`
+## Keywords
+
+This domain covers: workflow, workflows, process, processes, flow, flowchart, sequence, pipeline, automation, automated
+
+## Related Domains
+
+- [Procedures](../procedures/) - Step-by-step operational procedures (SOP)
+- [Quickstart](../quickstart/) - Setup guides, dev workflow, onboarding
+- [Features](../features/) - Feature implementation guides, admin docs
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/workflows/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Workflows Registry
+tier: reference
+domains: [workflows]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for workflows documentation
+---
+
+# Workflows Registry
+
+> Quick reference for process documentation, multi-step operations.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | features |
+| Load Priority | 5/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`workflow` `workflows` `process` `processes` `flow` `flowchart` `sequence` `pipeline` `automation` `automated` `multi-step` `orchestration` `state-machine`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*