@theglitchking/persistent-planning 3.4.2 → 3.6.0

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-10-23'
 version: '1.0.0'
 purpose: Complete listing of standards documentation
 ---
@@ -26,7 +26,7 @@ purpose: Complete listing of standards documentation
 | Document | Status | Updated | Words |
 |----------|--------|---------|-------|
 | [Atom Granularity (anti-pattern guide)](atom-granularity.md) | active | 2026-05-07 | 556 |
-| [Mandatory Closing Phases](mandatory-closing-phases.md) | active | 2026-08-31 | 770 |
+| [Mandatory Closing Phases](mandatory-closing-phases.md) | active | 2026-10-23 | 770 |
 
 ## Keywords
 
@@ -40,4 +40,4 @@ This domain covers: standard, standards, convention, conventions, pattern, patte
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-10-23*

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-10-23'
 version: '1.0.0'
 purpose: Quick reference for standards documentation
 ---
@@ -27,7 +27,7 @@ purpose: Quick reference for standards documentation
 
 ## Recently Updated
 
-- [Mandatory Closing Phases](mandatory-closing-phases.md) - 2026-08-31
+- [Mandatory Closing Phases](mandatory-closing-phases.md) - 2026-10-23
 - [Atom Granularity (anti-pattern guide)](atom-granularity.md) - 2026-05-07
 
 ## By Status
@@ -50,4 +50,4 @@ purpose: Quick reference for standards documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-10-23*

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

@@ -8,11 +8,11 @@ audience:
 tags:
   - testing
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-10-23'
 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
@@ -92,21 +105,62 @@ change validates nothing. For this repository that means adding assertions to
 command is. Mutation-check the assertion at least once: break the thing on
 purpose, confirm the test goes red, put it back.
 
+The templates carry the sentence "we need to validate success thoroughly through
+comprehensive testing of our changes" plus an instruction to write the concrete
+checks into the plan *when the plan is written*. sm: under Phase 6. lg: as atoms of
+the validation task. Without that, a plan got a one-line testing phase and the
+user had to say the sentence afterwards to get real tests planned. The
+`persistent-planning.md` rule repeats it so it is in context every session.
+
 **Documentation pass.** Create, update, or deprecate every doc the change
 touches, answering: what it is, where it lives, how to fix it, how to operate it,
 and why it matters. Deprecation counts — a doc made wrong by the change is worse
 than a missing one. If [hit-em-with-the-docs](https://github.com/TheGlitchKing/hit-em-with-the-docs)
 is installed, this pass **must** go through it (`hewtd integrate`, `hewtd
 archive`, `hewtd maintain`) rather than hand-managed markdown, so the doc lands
-in a domain and the indexes stay honest.
+in a domain and the indexes stay honest. Every variant also says to capture new
+procedures, tools, troubleshooting steps, gotchas and KB articles, and **never**
+to include secrets or passwords.
+
+Like validation, the docs step asks to be filled in when the plan is written,
+naming each doc, by file, that the work creates, changes or makes stale. sm: in the
+note under the phase list. lg: the docs closer's first atom and the `phase.md`
+note. A behaviour test showed why: without that instruction, a planner filled
+the validation closer with specific checks and left the docs closer generic. It
+missed the project's own feature doc, which the change made wrong.
+
+When the project uses hit-em-with-the-docs, the init scripts word this step for
+it rather than leaving "if installed" for Claude to work out. A project counts if
+it has a `.documentation/` tree or `.claude/hit-em-with-the-docs.json`
+(`planning_uses_hewtd`; sm has its own copy). hewtd being installed for the whole
+machine does not count.
+
+- **sm:** Phase 7 reads "Documentation pass -- a full hit-em-with-the-docs pass to
+  create/update/deprecate as many docs as needed to capture all our changes: new
+  procedures, tools, troubleshooting steps, gotchas, KB articles, etc. Never
+  include secrets or passwords".
+- **lg:** the docs closer's list line in `phase.md` says the same thing (the
+  `DOCS_CLOSER_PLACEHOLDER` slot). Its task is titled "Documentation pass — full
+  hit-em-with-the-docs pass", and its atoms cover `hewtd integrate`/`archive`,
+  procedures and tools, troubleshooting, gotchas as knowledge-base facts tagged
+  `gotcha`, KB articles, never secrets, and `hewtd maintain --quick` + `hewtd
+  audit`.
+
+Elsewhere the wording is unchanged, and lg plans no longer get the
+`npx hewtd archive`/`npx hewtd audit` atoms they used to receive unconditionally.
+The slug `documentation-pass-create-update-deprecate-docs` is the same in both
+variants, because the completion gate and existing plans key on it. The choice is
+made once, when the plan is written. A project that adopts hewtd later keeps its
+existing plans' wording; new plans pick it up. See
+[docs step has no hewtd steps](../troubleshooting/docs-closer-missing-hewtd-steps.md).
 
 ## How to operate it
 
 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 +173,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-10-23'
 version: '1.0.0'
 purpose: Complete listing of troubleshooting documentation
 ---
@@ -14,7 +14,7 @@ purpose: Complete listing of troubleshooting documentation
 
 ## Overview
 
-- **Total Documents:** 2
+- **Total Documents:** 3
 - **Domain:** `troubleshooting/`
 - **Category:** advanced
 - **Load Priority:** 6/10
@@ -25,6 +25,7 @@ purpose: Complete listing of troubleshooting documentation
 
 | Document | Status | Updated | Words |
 |----------|--------|---------|-------|
+| [A plan's docs step has no hit-em-with-the-docs steps](docs-closer-missing-hewtd-steps.md) | active | 2026-10-23 | 224 |
 | [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 |
 
@@ -40,4 +41,4 @@ This domain covers: troubleshooting, troubleshoot, debug, debugging, issue, issu
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-10-23*

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-10-23'
 version: '1.0.0'
 purpose: Quick reference for troubleshooting documentation
 ---
@@ -16,17 +16,19 @@ purpose: Quick reference for troubleshooting documentation
 
 | Metric | Value |
 |--------|-------|
-| Documents | 2 |
+| Documents | 3 |
 | Category | advanced |
 | Load Priority | 6/10 |
 
 ## Active Documents
 
+- [A plan's docs step has no hit-em-with-the-docs steps](docs-closer-missing-hewtd-steps.md)
 - [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's docs step has no hit-em-with-the-docs steps](docs-closer-missing-hewtd-steps.md) - 2026-10-23
 - [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
 
@@ -34,7 +36,7 @@ purpose: Quick reference for troubleshooting documentation
 
 | Status | Count |
 |--------|-------|
-| active | 2 |
+| active | 3 |
 | draft | 0 |
 | deprecated | 0 |
 | archived | 0 |
@@ -50,4 +52,4 @@ purpose: Quick reference for troubleshooting documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-10-23*

package/.documentation/troubleshooting/docs-closer-missing-hewtd-steps.md

@@ -0,0 +1,57 @@
+---
+title: A plan's docs step has no hit-em-with-the-docs steps
+tier: guide
+domains:
+  - troubleshooting
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-10-23'
+version: 1.0.0
+purpose: Why a new plan in a hit-em-with-the-docs project got the generic docs step, and how to fix it.
+estimated_read_time: 2 minutes
+word_count: 224
+last_validated: '2026-10-23'
+backlinks: []
+---
+
+# A plan's docs step has no hit-em-with-the-docs steps
+
+## Symptom
+
+The project uses hit-em-with-the-docs, but a new plan's last step is the generic
+one. sm: `Phase 7: Documentation pass -- create/update/deprecate as many docs as
+needed to capture what was done…`. lg: the docs closer has no `hewtd audit`,
+gotcha or KB-article atoms. The full hit-em-with-the-docs pass wording is missing.
+
+## Cause
+
+The init scripts choose the wording once, when the plan is written. They use the
+hewtd variant only when the **project** has a `.documentation/` tree or
+`.claude/hit-em-with-the-docs.json`. Common reasons it wasn't chosen:
+
+- **hewtd is only installed for the machine** (e.g. a marketplace install).
+  That's deliberate: otherwise every repo you plan in would get hewtd steps.
+- **The plan predates the docs tree.** The project adopted hewtd after the plan
+  was written. Existing plans are never rewritten.
+- **`CLAUDE_PROJECT_DIR` points somewhere else.** The scripts look in
+  `CLAUDE_PROJECT_DIR`, falling back to the current directory, not the git root.
+
+## Fix
+
+1. Check what the scripts see:
+   ```bash
+   ls -d "${CLAUDE_PROJECT_DIR:-$PWD}/.documentation" \
+         "${CLAUDE_PROJECT_DIR:-$PWD}/.claude/hit-em-with-the-docs.json"
+   ```
+2. If neither exists, set the project up with hit-em-with-the-docs (that creates
+   `.documentation/`), then start the plan again.
+3. For a plan that already exists, edit its last step by hand. sm: the Phase 7
+   line. lg: the docs closer's line in `phase.md` and its atoms. Or re-create it with
+   `PLANNING_FORCE=1` if nothing in it is worth keeping. Keep the lg slug
+   `documentation-pass-create-update-deprecate-docs`, because the completion gate
+   depends on it.
+
+See [mandatory closing phases](../standards/mandatory-closing-phases.md) for the
+two variants.

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

@@ -32,11 +32,14 @@ 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 -- we need to validate success thoroughly through comprehensive testing of our changes (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`.
+(In a project that uses hit-em-with-the-docs, Phase 7 reads as a full hit-em-with-the-docs pass instead —
+see [mandatory closing phases](../standards/mandatory-closing-phases.md).) It also
+carries an `## On Completion` section naming `/plan-status` and `/archive-plan`.
 
 ## Cause
 

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,85 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.6.0] - 2026-10-23
+
+### Added — a full hit-em-with-the-docs pass as the last step, when the project uses it
+
+When the project has `.documentation/` or `.claude/hit-em-with-the-docs.json`, the
+plan's last step reads "Documentation pass -- a full hit-em-with-the-docs pass to
+create/update/deprecate as many docs as needed to capture all our changes: new
+procedures, tools, troubleshooting steps, gotchas, KB articles, etc. Never include
+secrets or passwords". lg's docs closer also gets hewtd atoms: integrate/archive,
+gotchas as KB facts, KB articles, never secrets, `maintain --quick` + `audit`.
+A machine-wide hewtd install does not count.
+
+- **Fixed:** lg plans in projects without hewtd no longer get the unconditional
+  `npx hewtd archive` / `npx hewtd audit` atoms.
+- Every variant's note now says to capture procedures, tools, troubleshooting,
+  gotchas and KB articles, and never secrets or passwords.
+- The docs step asks to be filled in when the plan is written, naming each doc
+  the work creates, changes or makes stale (lg: the closer's first atom). In a
+  behaviour test, the docs closer was otherwise left generic.
+- Projects without hewtd: the sm Phase 7 line and the lg closer line are
+  byte-identical to before. The slug is unchanged.
+
+### Changed — the validation closer asks for the tests when the plan is written
+
+The validate step now reads "we need to validate success thoroughly through
+comprehensive testing of our changes". It also tells Claude to write the
+concrete checks into the plan up front, without being asked: unit,
+integration/end-to-end, regression, edge cases and failure paths, and the full
+suite. sm: Phase 6 line and note. lg: `phase.md` note plus two new leading atoms
+on the validation task. The `persistent-planning.md` rule and SKILL.md carry it
+too. Titles and slugs are unchanged, so existing plans and the completion gate
+are unaffected.
+
+### Added — init scripts seed `.claude/rules/`
+
+Every init script (`init-planning.sh`, `init-phase.sh`, `init-task.sh`,
+`init-atom.sh`) copies each `templates/rules/*.md` into the project's
+`.claude/rules/` when that file is absent, so Claude Code loads the planning
+workflow every session instead of only when the skill triggers. Ships one rule,
+`persistent-planning.md`. A rule is written once and never overwritten — not even
+under `PLANNING_FORCE` — so a repo's edits stick; delete it and the next init
+restores it. Adding a rule is adding a file to `templates/rules/`.
+
+The same step adds a **Persistent plans** section of hard git requirements — sync
+`main`, cut a branch, implement through to completion, commit at the end of each
+phase, finish with a single PR. It is appended to the repo's existing git workflow
+rule (any `.claude/rules/` file named like `git-workflow.md` or `gitflow.md`,
+including babel-fish's) or, if there is none, creates `git-workflow.md`. A marker
+comment keeps it to one copy.
+
+## [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

package/commands/start-planning.md

@@ -100,6 +100,18 @@ bash ~/.claude/skills/persistent-planning/scripts/init-planning.sh "<name>"
 
 Add tasks under a phase with `/start-task "<name>" --parent <phase-slug>`.
 
+### Both modes
+In a project that uses hit-em-with-the-docs (it has `.documentation/`), the last step
+is worded as a full hit-em-with-the-docs pass: capture all changes, including procedures,
+tools, troubleshooting, gotchas and KB articles, and never secrets.
+
+`.claude/rules/persistent-planning.md` is added if the project does not already have
+it. It is never overwritten, so edit it freely.
+
+A "Persistent plans" git section (sync main, branch, commit per phase, one PR) is
+appended once to the project's existing git workflow rule, or `.claude/rules/git-workflow.md`
+is created to hold it.
+
 ## Slug conversion
 
 Names are converted to URL-friendly slugs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.4.2",
+  "version": "3.6.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {

package/scripts/init-atom.sh

@@ -137,6 +137,8 @@ planning_insert_list_item \
   "## Atoms" \
   "- [ ] **${ATOM_NAME}** (\`atoms/${ATOM_SLUG}.md\`, sequence: ${NEXT_SEQUENCE})"
 
+planning_seed_rules "${ROOT}"
+
 echo ""
 planning_ok "Atom '${ATOM_NAME}' ready"
 echo ""