@theglitchking/persistent-planning 3.4.1 → 3.5.0

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for persistent-planning - Persistent markdown-based planning for Claude Code. Context engineering pattern with task directories, progress tracking, and working memory that persists across sessions.",
-    "version": "3.4.1"
+    "version": "3.5.0"
   },
   "plugins": [
     {
       "name": "persistent-planning",
       "description": "Persistent markdown-based planning for Claude Code. Uses on-disk markdown files as working memory for planning, progress tracking, and knowledge storage. Plans persist across sessions and support multiple concurrent tasks.",
-      "version": "3.4.1",
+      "version": "3.5.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "author": {
     "name": "TheGlitchKing"

package/.documentation/INDEX.md

@@ -3,7 +3,7 @@ title: Documentation Index
 tier: reference
 domains: [root]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Navigation hub for all documentation
 ---
@@ -219,6 +219,6 @@ purpose: Navigation hub for all documentation
 
 ## Maintenance
 
-- **Last generated:** 2026-09-04
+- **Last generated:** 2026-09-26
 - **Run maintenance:** `npx hit-em-with-the-docs maintain`
 - **Regenerate index:** `npx hit-em-with-the-docs index`

package/.documentation/REGISTRY.md

@@ -3,7 +3,7 @@ title: Documentation Registry
 tier: reference
 domains: [root]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for all documentation domains
 ---
@@ -77,4 +77,4 @@ purpose: Quick reference for all documentation domains
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/agents/INDEX.md

@@ -3,7 +3,7 @@ title: Agents Documentation Index
 tier: reference
 domains: [agents]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of agents documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: agent, agents, ai, assistant, expert, specialist, llm, langc
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/agents/REGISTRY.md

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

package/.documentation/api/INDEX.md

@@ -3,7 +3,7 @@ title: API Documentation Index
 tier: reference
 domains: [api]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of api documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: api, endpoint, endpoints, route, routes, rest, restful, grap
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/api/REGISTRY.md

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

package/.documentation/architecture/INDEX.md

@@ -3,7 +3,7 @@ title: Architecture Documentation Index
 tier: reference
 domains: [architecture]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of architecture documentation
 ---
@@ -47,4 +47,4 @@ This domain covers: architecture, design, system, system-design, pattern, patter
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/architecture/REGISTRY.md

@@ -3,7 +3,7 @@ title: Architecture Registry
 tier: reference
 domains: [architecture]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for architecture documentation
 ---
@@ -54,4 +54,4 @@ purpose: Quick reference for architecture documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/architecture/lg-plan-artifact-lifecycle.md

@@ -57,17 +57,18 @@ It **anchors on the MANDATORY marker, never on line numbers.** The list is a
 human-editable surface; positions do not survive contact with editing. This is tested
 against a hand-reordered, partially-checked, annotated list.
 
-## The two closers
+## The three closers
 
-Every phase is scaffolded with both closing tasks as real directories:
+Every phase is scaffolded with all three closing tasks as real directories, in this order:
 
 ```
+<phase>/cleanup-remove-junk-and-unused-code/
 <phase>/validate-success-through-comprehensive-testing/
 <phase>/documentation-pass-create-update-deprecate-docs/
 ```
 
 Each gets `task.md` (with `mandatory: true`, `parallelizable: false`), `notes.md`,
-`atoms/`, and seeded atoms — not empty placeholders. They were previously two lines
+`atoms/`, and seeded atoms — not empty placeholders. The original two were previously lines
 of prose in `phase.md`, which made the most important tasks in every plan the only
 ones with no artifact a subagent could read and nowhere to record decisions.
 

package/.documentation/backups/INDEX.md

@@ -3,7 +3,7 @@ title: Backups Documentation Index
 tier: reference
 domains: [backups]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of backups documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: backup, backups, restore, recovery, disaster, disaster-recov
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/backups/REGISTRY.md

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

package/.documentation/database/INDEX.md

@@ -3,7 +3,7 @@ title: Database Documentation Index
 tier: reference
 domains: [database]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of database documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: database, db, postgres, postgresql, mysql, sql, schema, migr
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/database/REGISTRY.md

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

package/.documentation/devops/INDEX.md

@@ -3,7 +3,7 @@ title: DevOps Documentation Index
 tier: reference
 domains: [devops]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of devops documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: devops, deployment, deploy, ci, cd, ci/cd, pipeline, docker,
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/devops/REGISTRY.md

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

package/.documentation/features/INDEX.md

@@ -3,7 +3,7 @@ title: Features Documentation Index
 tier: reference
 domains: [features]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of features documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: feature, features, implementation, guide, how-to, tutorial,
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/features/REGISTRY.md

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

package/.documentation/plans/INDEX.md

@@ -3,7 +3,7 @@ title: Plans Documentation Index
 tier: reference
 domains: [plans]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of plans documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: plan, plans, planning, roadmap, proposal, proposals, rfc, de
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/plans/REGISTRY.md

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

package/.documentation/procedures/INDEX.md

@@ -3,7 +3,7 @@ title: Procedures Documentation Index
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of procedures documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: procedure, procedures, sop, standard-operating-procedure, st
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/procedures/REGISTRY.md

@@ -3,7 +3,7 @@ title: Procedures Registry
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for procedures documentation
 ---
@@ -50,4 +50,4 @@ purpose: Quick reference for procedures documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/quickstart/INDEX.md

@@ -3,7 +3,7 @@ title: Quickstart Documentation Index
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of quickstart documentation
 ---
@@ -39,4 +39,4 @@ This domain covers: quickstart, quick-start, getting-started, setup, install, in
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/quickstart/REGISTRY.md

@@ -3,7 +3,7 @@ title: Quickstart Registry
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for quickstart documentation
 ---
@@ -48,4 +48,4 @@ purpose: Quick reference for quickstart documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/reference/INDEX.md

@@ -3,7 +3,7 @@ title: Reference Documentation Index
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of reference documentation
 ---
@@ -46,4 +46,4 @@ This domain covers: schema, frontmatter, workspace.json, field, enum, cli, flags
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/reference/REGISTRY.md

@@ -3,7 +3,7 @@ title: Reference Registry
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for reference documentation
 ---
@@ -52,4 +52,4 @@ purpose: Quick reference for reference documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/security/INDEX.md

@@ -3,7 +3,7 @@ title: Security Documentation Index
 tier: reference
 domains: [security]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of security documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: security, auth, authentication, authorization, oauth, jwt, k
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/security/REGISTRY.md

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

package/.documentation/standards/INDEX.md

@@ -3,7 +3,7 @@ title: Standards Documentation Index
 tier: reference
 domains: [standards]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of standards documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: standard, standards, convention, conventions, pattern, patte
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/standards/REGISTRY.md

@@ -3,7 +3,7 @@ title: Standards Registry
 tier: reference
 domains: [standards]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for standards documentation
 ---
@@ -50,4 +50,4 @@ purpose: Quick reference for standards documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/standards/mandatory-closing-phases.md

@@ -10,9 +10,9 @@ tags:
 status: active
 last_updated: '2026-08-31'
 version: 1.0.0
-purpose: The two phases every persistent-planning plan must end with — validate
-  success through comprehensive testing, then a documentation pass — why they
-  exist, how they are seeded, and how to keep them last.
+purpose: The three phases every persistent-planning plan must end with — cleanup,
+  then validate success through comprehensive testing, then a documentation pass —
+  why they exist, how they are seeded, and how to keep them last.
 estimated_read_time: 4 minutes
 word_count: 770
 last_validated: '2026-08-31'
@@ -21,11 +21,12 @@ backlinks: []
 
 # Mandatory Closing Phases
 
-Every plan this plugin creates ends with the same two units of work, in the same
+Every plan this plugin creates ends with the same three units of work, in the same
 order, no exceptions:
 
-1. **Validate success through comprehensive testing**
-2. **Documentation pass — create / update / deprecate as many docs as needed to capture what was done, where it lives, how to troubleshoot it**
+1. **Cleanup — remove junk and unused code this work created**
+2. **Validate success through comprehensive testing**
+3. **Documentation pass — create / update / deprecate as many docs as needed to capture what was done, where it lives, how to troubleshoot it**
 
 They are seeded into the templates so an agent never has to remember them, and
 they are marked `MANDATORY` in the artifact itself so an agent re-reading the
@@ -53,30 +54,30 @@ filesystem-as-working-memory reasoning behind the plan artifacts themselves —
 
 | Mode | Artifact | Section | Seeded as |
 |---|---|---|---|
-| sm | `.planning/<slug>/task_plan.md` | `## Phases` | Phase 5 and Phase 6 of 6 |
-| lg | `.planning/<phase-slug>/phase.md` | `## Tasks` | The last two task checkboxes |
+| sm | `.planning/<slug>/task_plan.md` | `## Phases` | Phases 5, 6 and 7 of 7 |
+| lg | `.planning/<phase-slug>/phase.md` | `## Tasks` | The last three task checkboxes |
 
-In **sm mode** the plan is a single file, so the two phases are literally the
-last two checkboxes under `## Phases`.
+In **sm mode** the plan is a single file, so the three phases are literally the
+last three checkboxes under `## Phases`.
 
 In **lg mode** the plan is a tree (phase → task → atom, see
-[Lg-Mode Layered Planning Guide](../architecture/lg-mode.md)). The closing pair is seeded at the
+[Lg-Mode Layered Planning Guide](../architecture/lg-mode.md)). The closing group is seeded at the
 **phase** level, because a phase is the strategic unit that actually ships. Every
 phase validates its own work and documents its own work; a phase cannot be marked
-`done` until both closing tasks are `done`. Individual tasks and atoms do **not**
-each carry the pair — that would produce a documentation pass per atom, which is
+`done` until all three closing tasks are `done`. Individual tasks and atoms do **not**
+each carry the group — that would produce a documentation pass per atom, which is
 noise.
 
-Neither closing task may be marked `parallelizable: true`. They gate on
+No closing task may be marked `parallelizable: true`. They gate on
 everything before them by definition.
 
 ## The ordering rule
 
-> New work is inserted **above** the closing pair, never after it.
+> New work is inserted **above** the closing group, never after it.
 
-An agent adding phases to an sm plan renumbers the closing pair so they remain
-last (Phase 5/6 becomes Phase 7/8, and so on). An agent adding tasks to an lg
-phase appends them above the two closing checkboxes. The template states this
+An agent adding phases to an sm plan renumbers the closing group so it remains
+last (Phase 5/6/7 becomes Phase 6/7/8, and so on). An agent adding tasks to an lg
+phase appends them above the three closing checkboxes. The template states this
 rule inline, directly beneath the checkboxes, so it survives the plan being read
 in isolation without this document.
 
@@ -85,6 +86,18 @@ enforceable — see [how it is tested](../testing/test-suite.md).
 
 ## What each phase actually requires
 
+**Cleanup.** Remove what the work left behind: scratch and test scripts, temp
+output and backups, debug and probe logging, one-off test functions, commented-out
+code, and code, helpers, imports or dependencies left unused by abandoned
+approaches. None of it fails a test and none of it is a doc, so neither of the
+other closers catches it. Scope is only what this work created or changed — diff
+against where it started — and never a refactor of code it did not touch. When
+unsure whether something is used, record it in `notes.md` instead of deleting it.
+
+Cleanup runs **first** of the three on purpose. It deletes things, so validation
+has to come after it: the tests then prove every deletion safe against the code
+that actually ships. Documentation stays last so it describes that final state.
+
 **Validate success through comprehensive testing.** Prove the work with a check
 that *fails if the change breaks*. A test that passes both before and after the
 change validates nothing. For this repository that means adding assertions to
@@ -105,8 +118,8 @@ in a domain and the indexes stay honest.
 Nothing to run — the phases arrive with the plan:
 
 ```bash
-/start-planning "Refactor auth"          # sm: task_plan.md seeded with 6 phases
-/start-planning "Foundation" --mode lg   # lg: phase.md seeded with 2 closing tasks
+/start-planning "Refactor auth"          # sm: task_plan.md seeded with 7 phases
+/start-planning "Foundation" --mode lg   # lg: phase.md seeded with 3 closing tasks
 ```
 
 To confirm the templates still seed them correctly after editing:
@@ -119,15 +132,16 @@ npm test
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| A new plan has only 4 phases | Plan created by persistent-planning < 3.1.0 | Append the two closing phases by hand; upgrade the plugin |
-| Closing phases are no longer last | Work appended below them | Move the new phases above the pair and renumber |
-| `npm test` fails on "documentation phase is last" | A template edit added a checkbox after the pair, or reworded the pair | Restore the ordering in `scripts/init-planning.sh` / `templates/lg/phase.md` |
-| Phase marked `done` with closing tasks unchecked | Skipped the gate | Not done — finish both, then mark the phase |
+| A new plan has only 4 phases | Plan created by persistent-planning < 3.1.0 | Append the closing phases by hand; upgrade the plugin |
+| Closing phases are no longer last | Work appended below them | Move the new phases above the group and renumber |
+| A plan has validate/docs closers but no cleanup | Plan created by persistent-planning < 3.5.0 | Add a cleanup phase or task above validate by hand, or leave it — the gate is additive |
+| `npm test` fails on "documentation phase is last" | A template edit added a checkbox after the group, or reworded it | Restore the ordering in `scripts/init-planning.sh` / `templates/lg/phase.md` |
+| Phase marked `done` with closing tasks unchecked | Skipped the gate | Not done — finish all three, then mark the phase |
 
 
 ## How they are enforced (3.3.0+)
 
-In lg mode the two closers are no longer only checkbox lines. `init-phase.sh` scaffolds
+In lg mode the closers are no longer only checkbox lines. `init-phase.sh` scaffolds
 each as a real task directory — `task.md` with `mandatory: true`, `notes.md`, `atoms/`,
 and seeded atoms — so they are addressable artifacts like every other task.
 

package/.documentation/testing/INDEX.md

@@ -3,7 +3,7 @@ title: Testing Documentation Index
 tier: reference
 domains: [testing]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of testing documentation
 ---
@@ -39,4 +39,4 @@ This domain covers: test, testing, tests, unit, unit-test, integration, integrat
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/testing/REGISTRY.md

@@ -3,7 +3,7 @@ title: Testing Registry
 tier: reference
 domains: [testing]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for testing documentation
 ---
@@ -48,4 +48,4 @@ purpose: Quick reference for testing documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

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

@@ -34,7 +34,7 @@ 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
+aspirational: a template edit that pushes a checkbox below the closing group turns
 the suite red.
 
 ## How to run it
@@ -51,8 +51,8 @@ is non-zero if anything failed, so it drops into CI unchanged.
 
 | 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 |
+| sm mode | `task_plan.md` + `notes.md` land at the slugified path; the plan seeds 7 phases; cleanup is third-to-last, validation second-to-last, documentation 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 three 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

package/.documentation/troubleshooting/INDEX.md

@@ -3,7 +3,7 @@ title: Troubleshooting Documentation Index
 tier: reference
 domains: [troubleshooting]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of troubleshooting documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: troubleshooting, troubleshoot, debug, debugging, issue, issu
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/troubleshooting/REGISTRY.md

@@ -3,7 +3,7 @@ title: Troubleshooting Registry
 tier: reference
 domains: [troubleshooting]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for troubleshooting documentation
 ---
@@ -50,4 +50,4 @@ purpose: Quick reference for troubleshooting documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

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

@@ -32,8 +32,9 @@ fixed in 3.2.0.
 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)
+- [ ] Phase 5: Cleanup -- remove junk and unused code this work created: scratch/test scripts, debug files, probe logging, one-off test functions, commented-out code, dead code from abandoned approaches (MANDATORY)
+- [ ] Phase 6: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 7: 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`.

package/.documentation/workflows/INDEX.md

@@ -3,7 +3,7 @@ title: Workflows Documentation Index
 tier: reference
 domains: [workflows]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 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-09-04*
+*Last updated: 2026-09-26*

package/.documentation/workflows/REGISTRY.md

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

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.5.0] - 2026-09-26
+
+### Added — a mandatory cleanup closer at the end of every phase (#20)
+
+Every plan now ends with three mandatory closers instead of two:
+
+1. **Cleanup — remove junk and unused code** (new)
+2. Validate success through comprehensive testing
+3. Documentation pass
+
+Agent-driven work reliably leaves debris: scratch and test scripts, temp
+output, probe logging, one-off test functions, commented-out code, and code or
+imports left unused by abandoned approaches. None of it fails a test and none
+of it is a doc, so neither existing closer caught it.
+
+Cleanup runs *first* of the three so validation proves every deletion safe, and
+docs describe the final state. Its scope is only what the phase created or
+changed; uncertain items go in `notes.md` instead of being deleted.
+
+- **lg**: `init-phase.sh` scaffolds `cleanup-remove-junk-and-unused-code/` as a
+  real task dir with `mandatory: true` and seeded atoms, third-to-last in
+  `phase.md`. Insertion and the completion gate needed no change — new tasks
+  already land above the first `MANDATORY` entry, and `plan-status.sh` already
+  gates on every `mandatory: true` task.
+- **sm**: `task_plan.md` gains Phase 5 Cleanup; validate and docs renumber to 6
+  and 7. This is a deliberate change to the v2 sm template, as #5 was.
+
+Existing plans are untouched; they simply lack the third closer.
+
+## [3.4.2] - 2026-09-05
+
+### Changed — the local `update` guard moves upstream into the runtime
+
+3.4.0 added a `preAction` guard in `bin/persistent-planning.js` because the
+runtime's `update` resolved installation state from `<cwd>/node_modules` and
+`CLAUDE_PLUGIN_ROOT` only, found neither in a marketplace-only install, and
+exited 0 after an `npm update` that touched nothing. The guard worked, but it
+was a workaround living in one plugin while every sibling stayed broken —
+babel-fish#17 was the same defect reported against babel-fish.
+
+Fixed properly in `@theglitchking/claude-plugin-runtime` 0.1.1, which this
+release requires. `resolveInstall()` there probes npm dep → `CLAUDE_PLUGIN_ROOT`
+→ the marketplace record in `~/.claude/plugins/installed_plugins.json`, so the
+26-line guard is deleted rather than reimplemented.
+
+The result is strictly better than the guard it replaces. Previously a
+marketplace install satisfied the guard and fell through to a no-op `npm update`
+that exited 0; now it is recognised, named by path, and refused with a pointer
+at `/plugin` — the only thing that can actually update a plugin-cache copy.
+
+The dependency floor is `^0.1.1`, not `^0.1.0`: the shared plugin dep tree at
+`~/.claude/plugins/npm-cache` pins the runtime at 0.1.0 in its lockfile, and
+0.1.0 still satisfies `^0.1.0`, so the broken copy would have survived.
+
+### Fixed — the CLI test depended on the developer's own machine
+
+`tests/run.sh` ran `update` in a temp workspace but inherited the real `$HOME`,
+so once the runtime learned to read `~/.claude/plugins/installed_plugins.json`
+the assertion passed or failed depending on whether the person running it
+happened to have the plugin installed. `HOME` is now overridden, and the
+marketplace branch is asserted against a fixture rather than a machine.
+
 ## [3.4.1] - 2026-09-04
 
 ### Fixed — the SessionStart hook could not survive a missing runtime (#18)

package/bin/persistent-planning.js

@@ -55,32 +55,6 @@ 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
@@ -55,7 +55,7 @@
   },
   "homepage": "https://github.com/TheGlitchKing/persistent-planning#readme",
   "dependencies": {
-    "@theglitchking/claude-plugin-runtime": "^0.1.0",
+    "@theglitchking/claude-plugin-runtime": "^0.1.1",
     "commander": "^14.0.0"
   },
   "devDependencies": {

package/scripts/init-phase.sh

@@ -125,7 +125,7 @@ planning_render_and_log \
   "NOTES_SCOPE_PLACEHOLDER=${PHASE_SLUG}" \
   "NOTES_DATE_PLACEHOLDER=${TODAY}"
 
-# Scaffold the two mandatory closing tasks as real task directories.
+# Scaffold the three mandatory closing tasks as real task directories.
 #
 # They used to exist only as two checkbox lines in phase.md, so the most important
 # tasks in every plan were the only ones with no artifact for a subagent to read and
@@ -162,6 +162,16 @@ scaffold_closer() { # <slug> <title> <atom>...
   done
 }
 
+# Cleanup comes first so validation proves every deletion safe.
+scaffold_closer \
+  "cleanup-remove-junk-and-unused-code" \
+  "Cleanup — remove junk and unused code" \
+  "Scope it: diff against where this phase started — only what this phase created or changed is in scope" \
+  "Remove scratch/test scripts, debug files, temp output and backups this phase created" \
+  "Remove probe logging, one-off test functions and commented-out code" \
+  "Remove code, helpers, imports and dependencies left unused by abandoned approaches" \
+  "Never refactor code this phase did not touch; when unsure, record it in notes.md instead of deleting"
+
 scaffold_closer \
   "validate-success-through-comprehensive-testing" \
   "Validate success through comprehensive testing" \

package/scripts/init-planning.sh

@@ -105,12 +105,18 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 - [ ] Phase 2: Research/gather information
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
-- [ ] 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)
+- [ ] Phase 5: Cleanup -- remove junk and unused code this work created: scratch/test scripts, debug files, probe logging, one-off test functions, commented-out code, dead code from abandoned approaches (MANDATORY)
+- [ ] Phase 6: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 7: 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.
+> Phases 5, 6 and 7 are mandatory and MUST stay the last three phases of this plan.
 > Insert new work above them; never after. Renumber them if you add phases.
 >
+> - **Cleanup**: remove what this work left behind -- scratch and test scripts, temp
+>   output, debug logging, one-off test functions, commented-out code, and code,
+>   imports or dependencies left unused by abandoned approaches. Only what this work
+>   changed; never refactor code it did not touch. When unsure, note it -- don't delete.
+>   Cleanup runs before validation so every deletion is proven safe by the tests.
 > - **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.

package/skills/persistent-planning/SKILL.md

@@ -160,12 +160,18 @@ Create this file FIRST for any complex task:
 - [ ] Phase 2: Research/gather information
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
-- [ ] 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)
+- [ ] Phase 5: Cleanup -- remove junk and unused code this work created: scratch/test scripts, debug files, probe logging, one-off test functions, commented-out code, dead code from abandoned approaches (MANDATORY)
+- [ ] Phase 6: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 7: 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.
+> Phases 5, 6 and 7 are mandatory and MUST stay the last three phases of this plan.
 > Insert new work above them; never after. Renumber them if you add phases.
 >
+> - **Cleanup**: remove what this work left behind -- scratch and test scripts, temp
+>   output, debug logging, one-off test functions, commented-out code, and code,
+>   imports or dependencies left unused by abandoned approaches. Only what this work
+>   changed; never refactor code it did not touch. When unsure, note it -- don't delete.
+>   Cleanup runs before validation so every deletion is proven safe by the tests.
 > - **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.

package/templates/lg/phase.md

@@ -21,13 +21,19 @@ Tasks with no inter-dependencies can be marked `parallelizable: true` in their f
 so subagent teams can pick them up concurrently.]
 
 _(no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)_
+- [ ] **Cleanup — remove junk and unused code** (`cleanup-remove-junk-and-unused-code`) (MANDATORY — third-to-last)
 - [ ] **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
-> `done`, and neither may be `parallelizable` — they gate on everything before them.
+> The three mandatory closing tasks above MUST remain the last three tasks of this phase.
+> Add new tasks above them; never after. A phase cannot be marked `done` until all three
+> are `done`, and none may be `parallelizable` — they gate on everything before them.
 >
+> - **Cleanup**: remove what this phase left behind — scratch and test scripts, temp
+>   output, debug logging, one-off test functions, commented-out code, and code, imports
+>   or dependencies left unused by abandoned approaches. Only what this phase changed;
+>   never refactor code it did not touch. It runs before validation so the tests prove
+>   every deletion safe.
 > - **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.