@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/.documentation/plans/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Plans Documentation Index
+tier: reference
+domains: [plans]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of plans documentation
+---
+
+# Plans Documentation
+
+> Planning documents, roadmaps, proposals
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `plans/`
+- **Category:** advanced
+- **Load Priority:** 3/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: plan, plans, planning, roadmap, proposal, proposals, rfc, design-doc, specification, spec
+
+## Related Domains
+
+- [Agents](../agents/) - Expert agent documentation, specialty matrix
+- [Backups](../backups/) - Backup/restore guides, disaster recovery
+- [Troubleshooting](../troubleshooting/) - Debug guides, common issues, solutions
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/plans/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Plans Registry
+tier: reference
+domains: [plans]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for plans documentation
+---
+
+# Plans Registry
+
+> Quick reference for planning documents, roadmaps, proposals.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | advanced |
+| Load Priority | 3/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`plan` `plans` `planning` `roadmap` `proposal` `proposals` `rfc` `design-doc` `specification` `spec` `milestone` `timeline` `schedule` `project` `initiative`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/procedures/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Procedures Documentation Index
+tier: reference
+domains: [procedures]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of procedures documentation
+---
+
+# Procedures Documentation
+
+> Step-by-step operational procedures (SOP)
+
+## Overview
+
+- **Total Documents:** 2
+- **Domain:** `procedures/`
+- **Category:** features
+- **Load Priority:** 6/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Plan Completion and Archive](plan-completion-and-archive.md) | active | 2026-08-31 | 812 |
+| [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md) | active | 2026-09-04 | 539 |
+
+## Keywords
+
+This domain covers: procedure, procedures, sop, standard-operating-procedure, step, steps, operational, operation, operations, runbook
+
+## Related Domains
+
+- [Workflows](../workflows/) - Process documentation, multi-step operations
+- [Features](../features/) - Feature implementation guides, admin docs
+- [Quickstart](../quickstart/) - Setup guides, dev workflow, onboarding
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/procedures/REGISTRY.md

@@ -0,0 +1,53 @@
+---
+title: Procedures Registry
+tier: reference
+domains: [procedures]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for procedures documentation
+---
+
+# Procedures Registry
+
+> Quick reference for step-by-step operational procedures (sop).
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 2 |
+| Category | features |
+| Load Priority | 6/10 |
+
+## Active Documents
+
+- [Plan Completion and Archive](plan-completion-and-archive.md)
+- [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md)
+
+## Recently Updated
+
+- [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md) - 2026-09-04
+- [Plan Completion and Archive](plan-completion-and-archive.md) - 2026-08-31
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 2 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`procedure` `procedures` `sop` `standard-operating-procedure` `step` `steps` `operational` `operation` `operations` `runbook` `playbook` `checklist` `process` `manual`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/procedures/plan-completion-and-archive.md

@@ -0,0 +1,185 @@
+---
+title: Plan Completion and Archive
+tier: guide
+domains:
+  - procedures
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: How persistent-planning decides a plan is finished, how that reaches
+  the agent automatically, and the procedure for retiring a completed plan into
+  the gitignored .planning/.archive/ directory.
+estimated_read_time: 5 minutes
+word_count: 812
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Plan Completion and Archive
+
+## What it is
+
+Two things that only make sense together:
+
+- **Status tracking** — a plan's completion is *derived from the plan artifacts*,
+  not stored anywhere else.
+- **Archive** — a completed plan is moved out of the active `.planning/` tree into
+  a gitignored `.planning/.archive/`, so what remains under `.planning/` is only
+  ever live work.
+
+## Why it matters
+
+The failure this prevents is a finished plan that nobody retires. It sits in
+`.planning/`, and every future session — human or agent — re-reads it, re-reasons
+about whether it is still relevant, and burns context deciding it isn't. Multiply
+by a dozen plans and the working-memory directory becomes the thing you have to
+work around.
+
+The reason completion is *derived* rather than *declared* is drift. A `done: true`
+flag someone has to remember to set is wrong the moment they forget, and nothing
+detects that. Checkbox state cannot drift from the plan, because it **is** the
+plan. Checking the last box is the completion signal; there is no second step to
+forget.
+
+## Where it lives
+
+| Piece | Path |
+|---|---|
+| Status scan (single implementation) | `scripts/plan-status.sh` |
+| Archive operation | `scripts/archive-plan.sh` |
+| Session-start nudge | `hooks/session-start.js` (shells out to `plan-status.sh --nudge`) |
+| Slash commands | `commands/plan-status.md`, `commands/archive-plan.md` |
+| Archived plans | `.planning/.archive/<slug>/` (gitignored) |
+
+## The completion rule
+
+A plan is **COMPLETE** when either holds:
+
+1. Every checkbox in every markdown file under the plan directory is checked, or
+2. The plan's top-level artifact (`phase.md`, `task_plan.md`, or `task.md`)
+   declares `status: done` in frontmatter.
+
+Other verdicts: `blocked` (an atom carries `status: blocked`), `empty` (no
+checkboxes yet), `in progress` (anything else), `archived` (already stamped).
+
+Because plans are seeded with [mandatory closing phases](../standards/mandatory-closing-phases.md),
+a plan cannot read COMPLETE until its work has been tested *and* documented. The
+two features are deliberately coupled: completion means finished, not "the fun
+part is finished."
+
+## How the agent finds out
+
+Three escalating surfaces, cheapest first:
+
+1. **SessionStart hook.** On every session, the hook runs `plan-status.sh --nudge`
+   and merges any result into the session's context: *"persistent-planning: 1
+   plan(s) complete but not archived — <slug>."* Silent when there is nothing to
+   say, so it costs nothing in the normal case.
+2. **`/plan-status`.** The full table, on demand.
+3. **The plan artifact itself.** Both templates carry an `## On Completion`
+   section stating the rule and the archive command, so an agent reading only the
+   plan still learns the protocol.
+
+## How to operate it
+
+```bash
+/plan-status                     # what is in progress, blocked, complete
+/archive-plan <slug>             # retire one completed plan
+/archive-plan --all-complete     # retire every completed plan
+/archive-plan <slug> --dry-run   # show the move without making it
+/archive-plan <slug> --force     # retire an unfinished plan (deliberate)
+```
+
+Machine-readable forms for scripts and subagents:
+
+```bash
+bash scripts/plan-status.sh --complete   # one complete plan slug per line
+bash scripts/plan-status.sh --nudge      # one line, or nothing
+```
+
+Archiving performs four steps:
+
+1. Verifies completion (skipped under `--force`).
+2. Ensures `.planning/.archive/` exists and is in `.gitignore`.
+3. Moves `.planning/<slug>/` → `.planning/.archive/<slug>/`, preferring `git mv`
+   when the plan is tracked so history follows it.
+4. Stamps the top-level artifact: `status: archived` + `archived_on` in
+   frontmatter, or a dated footer for sm plans that have none.
+
+**Nothing is ever deleted.** Archiving is a move plus a stamp.
+
+## Restoring an archived plan
+
+```bash
+mv .planning/.archive/<slug> .planning/<slug>
+```
+
+Then set `status:` back to `active` and remove the `archived_on` stamp. The plan
+resumes reading as in-progress the moment a box is unchecked.
+
+## How to fix it
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Finished plan never reads COMPLETE | A checkbox is still unchecked somewhere in the tree — often in a nested atom file | `bash scripts/plan-status.sh` shows `checked/total`; grep the plan for `- [ ]` |
+| A brand-new plan reads COMPLETE | Its template checkboxes were checked without doing the work, or the plan has no checkboxes and `status: done` was set by hand | Uncheck, or correct the frontmatter |
+| `archive-plan.sh` refuses | The plan is genuinely incomplete | Finish it. `--force` exists for deliberate abandonment, not for impatience |
+| "Already archived: … exists" | A plan with that slug was archived before | Rename or move the existing entry under `.planning/.archive/` first |
+| Nudge never appears | No `.planning/` directory, or no plan is complete, or the hook is not registered | `npx persistent-planning status` reports hook registration |
+| Archived plans show up in `git status` | `.planning/` is tracked in this repo and the ignore line was added after the fact | Ensure `.gitignore` has `.planning/.archive/`; `git rm -r --cached .planning/.archive` if already tracked |
+
+## Design notes
+
+**One implementation of the scan.** The hook, the slash command, and
+`archive-plan.sh`'s completion check all shell out to `plan-status.sh`. A second
+copy of the "is this done?" rule in JavaScript would be a second copy that could
+disagree.
+
+**The hook merges rather than appends.** `@theglitchking/claude-plugin-runtime`
+owns the single `SessionStart` JSON response and exposes no hook for adding to it,
+and emitting a second response line would be invalid. `hooks/session-start.js`
+intercepts that one write and merges the nudge into the same payload, failing
+open — if the payload is not the shape it expects, it is written through
+untouched and the update check still works.
+
+**Archive is gitignored on purpose.** A completed plan is a record of how *this
+machine* got somewhere. Sharing it with every clone would grow the repository
+with reasoning nobody reads. If a particular plan is worth keeping, promote its
+findings into a real doc — which is what the mandatory documentation phase is for.
+
+
+## Completion also gates on mandatory tasks (3.3.0+)
+
+"Every checkbox checked" is necessary but no longer sufficient. A plan containing any
+task with `mandatory: true` whose `status:` is not `done` (or `archived`) reads
+`in progress` however the boxes add up, and `archive-plan.sh` refuses it through the
+same pre-flight — there is still exactly one implementation of the rule.
+
+Plans with no `mandatory:` frontmatter are unaffected.
+
+Symptoms and fixes: [Plan never reads complete](../troubleshooting/plan-never-reads-complete.md).
+
+
+## What counts, and what does not (3.3.1+)
+
+- **Checkboxes** are body content and are counted anywhere *except* inside a fenced code
+  block. A quoted example is documentation, not work. An unterminated fence swallows the
+  rest of the file — the safe direction, since ambiguous content is not counted as
+  outstanding.
+- **`status:` and `mandatory:`** are frontmatter fields and are read *only* from the
+  leading `---` block. They are never matched in prose, tables or fenced examples, which
+  is stricter than fence-stripping alone.
+
+
+## What is tracked (3.4.0+)
+
+Active plans are committed; only `.planning/.archive/` is gitignored. v1.0.0 ignored the
+whole `.planning/` tree, which contradicted this procedure, `CLAUDE.md`, and the archive
+rationale itself — and in lg mode, chosen because a team exists, it guaranteed no
+teammate ever received the plans.
+
+Repos carrying the old blanket line keep it: the init scripts warn once and never rewrite
+a user's `.gitignore`. Replace `.planning/` with `.planning/.archive/` to start sharing.

package/.documentation/procedures/plugin-update-delivery.md

@@ -0,0 +1,99 @@
+---
+title: Plugin update delivery — what actually runs, and when
+tier: guide
+domains:
+  - procedures
+audience:
+  - developers
+tags:
+  - migration
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: What actually executes on each of the two distribution paths, why a marketplace
+  install never runs npm postinstall, and how to ship a fix that repairs existing installs.
+estimated_read_time: 3 minutes
+word_count: 539
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# Plugin update delivery — what actually runs, and when
+
+This package ships down two paths. They execute **different code at different times**,
+and a fix delivered through the wrong one reaches nobody. Read this before shipping any
+change that has to repair or migrate an existing install.
+
+## The two paths
+
+| | npm package | Claude Code marketplace plugin |
+|---|---|---|
+| Installed at | `node_modules/@theglitchking/persistent-planning` | `~/.claude/plugins/cache/persistent-planning-marketplace/persistent-planning/<version>/` |
+| Runs `postinstall`? | **yes** | **no** |
+| `node_modules` present? | yes | **no — the plugin cache has none** |
+| Runtime resolved from | local `node_modules` | shared `~/.claude/plugins/npm-cache/node_modules/` |
+| Runs every session | SessionStart hook | SessionStart hook |
+
+## The constraint
+
+**A marketplace install never runs npm postinstall.**
+
+So `runPostinstall()` — and therefore the skill linker, the reclaim, and the version
+marker — never execute on a marketplace update. A repair wired only into postinstall
+ships to npm consumers and silently misses every marketplace consumer.
+
+That is not a corner case. In issue #10 the broken population *was* the marketplace
+consumers, precisely because they were the ones postinstall could never reach.
+
+`runPostinstall()` also returns `null` when `INIT_CWD` equals the package root
+(dev-in-place), which is why this repo has no `.claude/skills/persistent-planning` of
+its own.
+
+## The rule
+
+> **Anything that must reach an existing install goes through the SessionStart hook.**
+> It is the only code that runs every session in both shapes.
+
+`hooks/session-start.js` `autoRepair()` is the reference implementation:
+
+- **Fast path first.** Two `lstat`s settle the common "nothing to do" case before any
+  work happens. Never make a healthy install pay.
+- **Once per plugin version.** Stamped as `repairedSkillsForVersion` in
+  `.claude/persistent-planning.json`. Stamped *regardless of outcome*, so a repair that
+  cannot succeed does not retry every session; a later release moves the version and
+  gets one fresh attempt.
+- **Policy-gated.** `auto` repairs, `nudge` warns only, `off` does nothing. A user who
+  turned updates off did not consent to filesystem mutation.
+- **Spawned, not imported.** The migration runs in a child process with a timeout, so a
+  failure is contained.
+- **Fails open.** Every path is wrapped. A broken migration must never cost someone
+  their session start.
+- **One stdout write.** The runtime owns the single `SessionStart` JSON response and
+  exposes no append hook; a second response line is invalid. Merge into the existing
+  intercept.
+
+## Release checklist addendum
+
+The version appears in **three** places that must match — `package.json`,
+`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (both `metadata.version`
+and the plugin entry). See `CLAUDE.md`.
+
+Two more things to verify for a migration release:
+
+1. **The `files` array actually ships the new code.** v3.0.0 shipped broken because
+   `scripts/` and `templates/` were missing from it. Check with `npm pack --dry-run` and
+   grep the listing for the files you added.
+2. **Test from a marketplace-shaped fixture** — no `node_modules`, no postinstall — not
+   from `npm install`. A test that passes under `npm install` proves nothing about the
+   population that is actually broken. `tests/run.sh` builds exactly this fixture.
+
+If a fix depends on a new `@theglitchking/claude-plugin-runtime`, it needs a runtime
+publish, a dependency-range bump here, and a coordinated rollout — marketplace consumers
+resolve the runtime from a shared cache, not a vendored copy. Preferring a change that
+keeps the runtime unchanged is usually worth real effort; the issue #10 reclaim is
+deliberately ordered *before* the runtime's linker for that reason.
+
+## Related
+
+- [Skill linking and reclaim](../architecture/skill-linking-and-reclaim.md)
+- [Stale skill directory](../troubleshooting/stale-skill-dir-drift.md)

package/.documentation/quickstart/INDEX.md

@@ -0,0 +1,42 @@
+---
+title: Quickstart Documentation Index
+tier: reference
+domains: [quickstart]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of quickstart documentation
+---
+
+# Quickstart Documentation
+
+> Setup guides, dev workflow, onboarding
+
+## Overview
+
+- **Total Documents:** 1
+- **Domain:** `quickstart/`
+- **Category:** features
+- **Load Priority:** 9/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Examples: Persistent Planning in Action](examples.md) | active | 2026-08-31 | 136 |
+
+## Keywords
+
+This domain covers: quickstart, quick-start, getting-started, setup, install, installation, onboarding, developer, dev, workflow
+
+## Related Domains
+
+- [Workflows](../workflows/) - Process documentation, multi-step operations
+- [Features](../features/) - Feature implementation guides, admin docs
+- [Procedures](../procedures/) - Step-by-step operational procedures (SOP)
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/quickstart/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Quickstart Registry
+tier: reference
+domains: [quickstart]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for quickstart documentation
+---
+
+# Quickstart Registry
+
+> Quick reference for setup guides, dev workflow, onboarding.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 1 |
+| Category | features |
+| Load Priority | 9/10 |
+
+## Active Documents
+
+- [Examples: Persistent Planning in Action](examples.md)
+
+## Recently Updated
+
+- [Examples: Persistent Planning in Action](examples.md) - 2026-08-31
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 1 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`quickstart` `quick-start` `getting-started` `setup` `install` `installation` `onboarding` `developer` `dev` `workflow` `start` `begin` `intro` `introduction` `new-developer`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/{docs → .documentation/quickstart}/examples.md

@@ -1,3 +1,23 @@
+---
+title: 'Examples: Persistent Planning in Action'
+tier: plan
+domains:
+  - quickstart
+audience:
+  - all
+tags:
+  - authentication
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: '**User Request:** "Research the benefits of morning exercise and write
+  a summary"'
+estimated_read_time: 1 minute
+word_count: 136
+last_validated: '2026-08-31'
+backlinks: []
+---
+
 # Examples: Persistent Planning in Action
 
 ## Example 1: Research Task

package/.documentation/reference/INDEX.md

@@ -0,0 +1,49 @@
+---
+title: Reference Documentation Index
+tier: reference
+domains: [reference]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of reference documentation
+---
+
+# Reference Documentation
+
+> Schema, frontmatter, and CLI reference material for the planning artifacts
+
+## Overview
+
+- **Total Documents:** 3
+- **Domain:** `reference/`
+- **Category:** development
+- **Load Priority:** 7/10
+
+## Documents
+
+### Standards
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [workspace.json schema](workspace-json.md) | active | 2026-05-07 | 358 |
+
+### References
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [`mandatory:` task frontmatter](mandatory-frontmatter.md) | active | 2026-09-04 | 270 |
+| [Skill version marker (`.version`)](skill-version-marker.md) | active | 2026-09-04 | 295 |
+
+## Keywords
+
+This domain covers: schema, frontmatter, workspace.json, field, enum, cli, flags, reference, contract
+
+## Related Domains
+
+- [Architecture](../architecture/) - System design, AI coach, project registry, patterns
+- [Standards](../standards/) - Coding standards (backend, frontend, database, devops, security)
+- [Testing](../testing/) - Test strategies, fixtures, patterns, integration/e2e
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/reference/REGISTRY.md

@@ -0,0 +1,55 @@
+---
+title: Reference Registry
+tier: reference
+domains: [reference]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for reference documentation
+---
+
+# Reference Registry
+
+> Quick reference for schema, frontmatter, and cli reference material for the planning artifacts.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 3 |
+| Category | development |
+| Load Priority | 7/10 |
+
+## Active Documents
+
+- [`mandatory:` task frontmatter](mandatory-frontmatter.md)
+- [Skill version marker (`.version`)](skill-version-marker.md)
+- [workspace.json schema](workspace-json.md)
+
+## Recently Updated
+
+- [`mandatory:` task frontmatter](mandatory-frontmatter.md) - 2026-09-04
+- [Skill version marker (`.version`)](skill-version-marker.md) - 2026-09-04
+- [workspace.json schema](workspace-json.md) - 2026-05-07
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 3 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`schema` `frontmatter` `workspace.json` `field` `enum` `cli` `flags` `reference` `contract`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*