@theglitchking/persistent-planning 3.5.0 → 3.6.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.5.0"
+    "version": "3.6.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.5.0",
+      "version": "3.6.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.5.0",
+  "version": "3.6.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-26'
+last_updated: '2026-10-23'
 version: '1.0.0'
 purpose: Navigation hub for all documentation
 ---
@@ -29,7 +29,7 @@ purpose: Navigation hub for all documentation
 | [Security](#security) | 0 | Security, auth, Vault, Keycloak, RLS |
 | [Standards](#standards) | 2 | Coding standards (backend, frontend, database, devops, security) |
 | [Testing](#testing) | 1 | Test strategies, fixtures, patterns, integration/e2e |
-| [Troubleshooting](#troubleshooting) | 2 | Debug guides, common issues, solutions |
+| [Troubleshooting](#troubleshooting) | 3 | Debug guides, common issues, solutions |
 | [Workflows](#workflows) | 0 | Process documentation, multi-step operations |
 | [Reference](#reference) | 3 | Schema, frontmatter, and CLI reference material for the planning artifacts |
 
@@ -164,7 +164,7 @@ purpose: Navigation hub for all documentation
 | Document | Tier | Status | Updated |
 |----------|------|--------|----------|
 | [Atom Granularity (anti-pattern guide)](standards/atom-granularity.md) | standard | active | 2026-05-07 |
-| [Mandatory Closing Phases](standards/mandatory-closing-phases.md) | standard | active | 2026-08-31 |
+| [Mandatory Closing Phases](standards/mandatory-closing-phases.md) | standard | active | 2026-10-23 |
 
 ---
 
@@ -188,6 +188,7 @@ purpose: Navigation hub for all documentation
 
 | Document | Tier | Status | Updated |
 |----------|------|--------|----------|
+| [A plan's docs step has no hit-em-with-the-docs steps](troubleshooting/docs-closer-missing-hewtd-steps.md) | guide | active | 2026-10-23 |
 | [A plan won't read COMPLETE](troubleshooting/plan-never-reads-complete.md) | guide | active | 2026-09-04 |
 | [Stale skill directory — commands run frozen code](troubleshooting/stale-skill-dir-drift.md) | guide | active | 2026-09-04 |
 
@@ -219,6 +220,6 @@ purpose: Navigation hub for all documentation
 
 ## Maintenance
 
-- **Last generated:** 2026-09-26
+- **Last generated:** 2026-10-23
 - **Run maintenance:** `npx hit-em-with-the-docs maintain`
 - **Regenerate index:** `npx hit-em-with-the-docs index`

package/.documentation/knowledge-base/facts/INDEX.md

@@ -0,0 +1,57 @@
+---
+title: Facts Index
+tier: reference
+domains:
+  - knowledge-base
+status: active
+last_updated: '0000-00-00'
+version: '1.0.0'
+purpose: Auto-generated index of all facts in the knowledge base, grouped by tag then confidence.
+---
+
+# Facts Index
+
+<!-- Auto-generated by `hewtd maintain`. Do not edit by hand — changes will be overwritten. -->
+
+**Total facts:** 2
+
+## babel-fish
+
+### confidence: high
+
+| ID                                   | Title                                                                                         | Last verified | Citers |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|---------------|--------|
+| `babel-fish-hook-adds-untracked-map` | babel-fish's pre-commit hook commits an untracked project map into the next qualifying commit | 2026-10-23    | 0      |
+
+## claude-code
+
+### confidence: high
+
+| ID                               | Title                                                             | Last verified | Citers |
+|----------------------------------|-------------------------------------------------------------------|---------------|--------|
+| `claude-code-grep-v-exit-status` | In Claude Code's Bash tool, grep -v exits 1 when any line matches | 2026-10-23    | 0      |
+
+## git
+
+### confidence: high
+
+| ID                                   | Title                                                                                         | Last verified | Citers |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|---------------|--------|
+| `babel-fish-hook-adds-untracked-map` | babel-fish's pre-commit hook commits an untracked project map into the next qualifying commit | 2026-10-23    | 0      |
+
+## gotcha
+
+### confidence: high
+
+| ID                                   | Title                                                                                         | Last verified | Citers |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|---------------|--------|
+| `babel-fish-hook-adds-untracked-map` | babel-fish's pre-commit hook commits an untracked project map into the next qualifying commit | 2026-10-23    | 0      |
+| `claude-code-grep-v-exit-status`     | In Claude Code's Bash tool, grep -v exits 1 when any line matches                             | 2026-10-23    | 0      |
+
+## shell
+
+### confidence: high
+
+| ID                               | Title                                                             | Last verified | Citers |
+|----------------------------------|-------------------------------------------------------------------|---------------|--------|
+| `claude-code-grep-v-exit-status` | In Claude Code's Bash tool, grep -v exits 1 when any line matches | 2026-10-23    | 0      |

package/.documentation/knowledge-base/facts/babel-fish-hook-adds-untracked-map.md

@@ -0,0 +1,56 @@
+---
+title: babel-fish's pre-commit hook commits an untracked project map into the next qualifying commit
+tier: fact
+domains:
+  - troubleshooting
+status: active
+last_updated: 2026-10-23
+id: babel-fish-hook-adds-untracked-map
+confidence: high
+last_verified: 2026-10-23
+verify_command: |
+  command grep -n "git add .claude/project-map" .githooks/pre-commit
+provenance:
+  - .planning/hewtd-aware-documentation-closer/
+sources:
+  - .githooks/pre-commit
+tags:
+  - gotcha
+  - babel-fish
+  - git
+invalidated_by:
+  - babel-fish's hook stops running git add on the map, or only re-adds files that are already tracked
+---
+
+# babel-fish's pre-commit hook commits an untracked project map into the next qualifying commit
+
+## Claim
+
+Once the babel-fish installer has run (`core.hooksPath=.githooks`), any commit that stages a
+`.py`, `.ts`, `.js`, `.go`, `.java`, `.yaml`/`.yml`, `package.json`, `Cargo.toml`, `go.mod` or
+docker-compose file runs the codebase mapper. The mapper then runs
+`git add .claude/project-map/...`. If the map has never been committed, this stages the whole
+map (about 25 files) into that commit. Nothing reports it beyond the generator's progress lines.
+
+It happened on the 3.6.0 release commit: bumping `package.json` brought in the entire map,
+and it was pushed before anyone noticed.
+
+## How to verify
+
+`.githooks/pre-commit` contains `git add .claude/project-map/PROJECT_MAP.md ...` inside the
+"Codebase Mapper" block. After a commit touching one of those file types, run
+`git show --stat HEAD`, which lists `.claude/project-map/` files you didn't stage.
+
+## Instead
+
+Right after installing babel-fish, commit its output on its own: `.claude/project-map/`,
+`.claude/rules/`, `.claude/CLAUDE.md`, `.githooks/` and the generated developer skill.
+After that the hook only stages real map changes. To keep the map out of git, gitignore
+`.claude/project-map/`, which turns the hook's `git add` into a no-op. Removing the map from a commit the hook
+already touched means re-committing, and the hook re-adds it. So commit the map first and
+rebuild the branch on top, rather than amending past the hook with `--no-verify`.
+
+## Consequences
+
+Release and feature commits pick up unrelated generated files. Check
+`git show --stat HEAD` after the first commit in a repo where babel-fish was just installed.

package/.documentation/knowledge-base/facts/claude-code-grep-v-exit-status.md

@@ -0,0 +1,55 @@
+---
+title: In Claude Code's Bash tool, grep -v exits 1 when any line matches
+tier: fact
+domains:
+  - troubleshooting
+status: active
+last_updated: 2026-10-23
+id: claude-code-grep-v-exit-status
+confidence: high
+last_verified: 2026-10-23
+verify_command: |
+  printf 'abc\nxyz\n' | command grep -v xyz >/dev/null; echo "GNU grep: $? (expect 0)"; type -t grep
+provenance:
+  - .planning/hewtd-aware-documentation-closer/
+tags:
+  - gotcha
+  - claude-code
+  - shell
+invalidated_by:
+  - Claude Code stops wrapping grep in a shell function, or its ugrep matches GNU grep's -v exit status
+---
+
+# In Claude Code's Bash tool, grep -v exits 1 when any line matches
+
+## Claim
+
+In Claude Code's Bash tool, `grep` is a shell function that runs Claude Code's bundled ugrep.
+With `-v`, it prints the right (non-matching) lines but **exits 1 whenever any input line
+matches the pattern**. GNU grep exits 0 as long as some line was selected. So
+`if … | grep -vq PATTERN` reads "nothing selected" when lines were selected. That includes
+`-vqE`, `-v -q -E` and `-vE`.
+
+Observed while filtering date-only `hewtd index` churn: a loop meant to keep index files
+with real changes (`grep -vqE "last_updated|Last updated"`) reverted every file, including
+the new doc's index entry.
+
+## How to verify
+
+In the Claude Code Bash tool: `type -t grep` prints `function`. Then
+`printf 'abc\nxyz\n' | grep -v xyz >/dev/null; echo $?` prints `1`. The same line with
+`command grep` prints `0`. The `verify_command` above checks the GNU side. The ugrep
+side only reproduces inside Claude Code's Bash tool.
+
+## Instead
+
+Use `command grep` whenever the **exit status** of `grep -v` matters (`if`, `&&`, `||`, `-q`).
+Scripts run as child processes (`bash script.sh`, `npm test`) are unaffected, because the
+function isn't exported, so `tests/run.sh` and the init scripts use GNU grep. Only commands
+typed straight into the tool are affected.
+
+## Consequences
+
+A silent wrong branch, not an error. Here it discarded generated index changes that should
+have been committed. Anywhere `grep -v` is used as a test, the "some lines selected" case is
+read as "none selected".

package/.documentation/knowledge-base/incidents/INDEX.md

@@ -0,0 +1,17 @@
+---
+title: Incidents Index
+tier: reference
+domains:
+  - knowledge-base
+  - incidents
+status: active
+last_updated: '0000-00-00'
+version: '1.0.0'
+purpose: Auto-generated chronological index of all incidents in the knowledge base.
+---
+
+# Incidents Index
+
+<!-- Auto-generated by `hewtd maintain`. Do not edit by hand — changes will be overwritten. -->
+
+_No incidents yet. Create one with the `templates/knowledge-base/incident-narrative.template.md` template._

package/.documentation/knowledge-base/symptoms/INDEX.md

@@ -0,0 +1,17 @@
+---
+title: Symptoms Index
+tier: reference
+domains:
+  - knowledge-base
+  - operations
+status: active
+last_updated: '0000-00-00'
+version: '1.0.0'
+purpose: Auto-generated mapping of symptom keys (alert names, user phrases, error patterns) to playbook anchors and their fact citations.
+---
+
+# Symptoms Index
+
+<!-- Auto-generated by `hewtd maintain`. Do not edit by hand — changes will be overwritten. -->
+
+_No symptoms blocks found in scanned playbooks. Add a `symptoms:` block to any playbook frontmatter to populate this index._

package/.documentation/standards/INDEX.md

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

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

@@ -8,7 +8,7 @@ audience:
 tags:
   - testing
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-10-23'
 version: 1.0.0
 purpose: The three phases every persistent-planning plan must end with — cleanup,
   then validate success through comprehensive testing, then a documentation pass —
@@ -105,13 +105,54 @@ 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
 

package/.documentation/troubleshooting/INDEX.md

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

@@ -33,11 +33,13 @@ A generated `task_plan.md` ends at Phase 4. A correct one ends:
 
 ```
 - [ ] 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 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/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 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)

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.5.0",
+  "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 ""

package/scripts/init-phase.sh

@@ -107,6 +107,41 @@ fi
 # Create phase directory
 mkdir -p "$PHASE_DIR"
 
+# The docs closer's wording depends on whether this project uses hit-em-with-the-docs.
+# Its slug never changes: the completion gate and existing plans key on it.
+# Both variants open by asking the planner to name the docs — the generic atoms alone
+# left the closer unfilled while the validation closer, which asks, got filled.
+DOCS_PLAN_ATOM="As this phase's tasks are written, add an atom here for each doc they create, change or make stale, naming the file — check the existing docs for ones this work makes wrong"
+if planning_uses_hewtd "$ROOT"; then
+  DOCS_CLOSER="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"
+  DOCS_TITLE="Documentation pass — full hit-em-with-the-docs pass"
+  DOCS_ATOMS=(
+    "$DOCS_PLAN_ATOM"
+    "Full hit-em-with-the-docs pass: create/update/deprecate as many docs as needed to capture all our changes"
+    "Create docs with \`npx hewtd integrate <file> -a\`; retire superseded ones with \`npx hewtd archive <file>\` — never by deleting"
+    "Capture every new procedure and tool: what it is, where it lives, how to run it"
+    "Add a troubleshooting entry for the symptom someone will actually search for"
+    "Record each gotcha (a non-obvious failure with an observed fix) as a knowledge-base fact tagged \`gotcha\`, with an \`## Instead\` section"
+    "Write KB articles for anything operational under \`.documentation/knowledge-base/\`"
+    "Update every existing doc this phase made wrong — a stale doc is worse than a missing one"
+    "Never include secrets, passwords, tokens or keys in any doc"
+    "Run \`npx hewtd maintain --quick\` and \`npx hewtd audit\`; resolve every error"
+    "Never hand-edit INDEX.md or REGISTRY.md — they are generated"
+  )
+else
+  DOCS_CLOSER="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.."
+  DOCS_TITLE="Documentation pass — create/update/deprecate docs"
+  DOCS_ATOMS=(
+    "$DOCS_PLAN_ATOM"
+    "Create docs for what was built: what it is, where it lives, how it works"
+    "Capture new procedures, tools, troubleshooting steps and gotchas — add a troubleshooting entry for the symptom someone will actually search for"
+    "Update every existing doc this phase made wrong — a stale doc is worse than a missing one"
+    "Retire superseded docs rather than leaving them wrong"
+    "Never include secrets, passwords, tokens or keys in any doc"
+    "If hit-em-with-the-docs is installed you MUST use it: \`npx hewtd integrate <file> -a\` to create, \`npx hewtd archive <file>\` to retire, \`npx hewtd maintain --quick\` to regenerate indexes"
+  )
+fi
+
 # Render phase.md
 planning_render_and_log \
   "${TEMPLATE_DIR}/phase.md" \
@@ -114,7 +149,8 @@ planning_render_and_log \
   "phase.md at ${PHASE_DIR}/phase.md" \
   "PHASE_TITLE_PLACEHOLDER=${PHASE_NAME}" \
   "PHASE_SLUG_PLACEHOLDER=${PHASE_SLUG}" \
-  "PHASE_DATE_PLACEHOLDER=${TODAY}"
+  "PHASE_DATE_PLACEHOLDER=${TODAY}" \
+  "DOCS_CLOSER_PLACEHOLDER=${DOCS_CLOSER}"
 
 # Render notes.md (scoped to the phase)
 planning_render_and_log \
@@ -175,6 +211,8 @@ scaffold_closer \
 scaffold_closer \
   "validate-success-through-comprehensive-testing" \
   "Validate success through comprehensive testing" \
+  "We need to validate success thoroughly through comprehensive testing of our changes: as this phase's tasks are written, add an atom here for each check they need" \
+  "Cover every kind that applies: unit tests for new and changed logic, integration and end-to-end runs through the real entry points, edge cases and failure paths" \
   "Prove every claim this phase makes with a test that fails if it breaks" \
   "Test the invariant after mutation, not the shape of a freshly rendered template" \
   "Cover the failure mode that prompted the work, not just the happy path" \
@@ -182,17 +220,12 @@ scaffold_closer \
 
 scaffold_closer \
   "documentation-pass-create-update-deprecate-docs" \
-  "Documentation pass — create/update/deprecate docs" \
-  "Create docs for what was built: what it is, where it lives, how it works" \
-  "Add a troubleshooting entry for the symptom someone will actually search for" \
-  "Update every existing doc this phase made wrong — a stale doc is worse than a missing one" \
-  "Retire superseded docs with \`npx hewtd archive <file>\` — never by deleting" \
-  "If hit-em-with-the-docs is installed you MUST use it: \`npx hewtd integrate <file> -a\` to create, \`npx hewtd maintain --quick\` to regenerate indexes" \
-  "Run \`npx hewtd audit\` and resolve every error" \
-  "Never hand-edit INDEX.md or REGISTRY.md — they are generated"
+  "$DOCS_TITLE" \
+  "${DOCS_ATOMS[@]}"
 
 # Only completed plans are local history — see planning_ensure_archive_gitignored.
 planning_ensure_archive_gitignored "${ROOT}"
+planning_seed_rules "${ROOT}"
 
 echo ""
 planning_ok "Phase '${PHASE_NAME}' ready at .planning/${PHASE_SLUG}/"

package/scripts/init-planning.sh

@@ -15,7 +15,8 @@
 #   2. Creates task_plan.md with templates
 #   3. Creates notes.md with templates
 #   4. Adds .planning/ to .gitignore (optional)
-#   5. Confirms creation and provides next steps
+#   5. Copies templates/rules/*.md into .claude/rules/ (only files not already there)
+#   6. Confirms creation and provides next steps
 #
 # Multiple tasks example:
 #   /start-planning "Refactor auth"      -> .planning/refactor-auth/
@@ -65,6 +66,14 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 PLANNING_DIR="${PROJECT_ROOT}/.planning"
 TASK_DIR="${PLANNING_DIR}/${TASK_SLUG}"
 
+# Does this project use hit-em-with-the-docs? Self-contained copy of
+# planning_uses_hewtd in scripts/lib/planning.sh: a .documentation/ tree or hewtd's
+# project config. A machine-wide install does not count.
+USES_HEWTD=0
+if [ -d "${PROJECT_ROOT}/.documentation" ] || [ -f "${PROJECT_ROOT}/.claude/hit-em-with-the-docs.json" ]; then
+    USES_HEWTD=1
+fi
+
 # Color codes
 GREEN='\033[0;32m'
 BLUE='\033[0;34m'
@@ -106,8 +115,8 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
 - [ ] 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)
+- [ ] Phase 6: Validate success through comprehensive testing -- we need to validate success thoroughly through comprehensive testing of our changes (MANDATORY)
+- [ ] Phase 7: DOCS_PHASE_PLACEHOLDER (MANDATORY)
 
 > 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.
@@ -117,9 +126,19 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 >   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.
+> - **Validate success**: we need to validate success thoroughly through comprehensive
+>   testing of our changes. Write the tests into this plan when you write the plan --
+>   don't wait to be asked. List each check under Phase 6, every kind that applies:
+>   unit tests for new and changed logic, integration and end-to-end runs through the
+>   real entry points, a regression test for the problem that prompted the work, edge
+>   cases and failure paths, and the full existing suite. Each must 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.
+>   Capture new procedures, tools, troubleshooting steps, gotchas and KB articles too.
+>   Never include secrets or passwords. Write the docs work into this plan when you
+>   write the plan -- don't wait to be asked. List each doc under Phase 7 by file:
+>   every doc this work creates, changes or makes stale.
 >   If hit-em-with-the-docs is installed, you MUST use it for this pass --
 >   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
 >   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or
@@ -161,6 +180,13 @@ EOF
 
     sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$TASK_PLAN_FILE"
     sed -i "s/TASK_SLUG_PLACEHOLDER/${TASK_SLUG}/g" "$TASK_PLAN_FILE"
+    # Both texts contain '/', hence the '|' delimiter; neither may contain '|' or '&'.
+    if [ "$USES_HEWTD" = "1" ]; then
+        DOCS_PHASE="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"
+    else
+        DOCS_PHASE="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.."
+    fi
+    sed -i "s|DOCS_PHASE_PLACEHOLDER|${DOCS_PHASE}|g" "$TASK_PLAN_FILE"
     echo -e "${GREEN}+${NC} Created task_plan.md"
 else
     echo -e "${YELLOW}*${NC} task_plan.md already exists (not overwritten)"
@@ -234,6 +260,36 @@ else
     echo -e "${YELLOW}*${NC} No .gitignore found (not added)"
 fi
 
+# Step 5b: Seed .claude/rules/
+#
+# Each templates/rules/*.md is copied once, when absent; after that the repo owns it.
+# The git-workflow section is appended once (by marker) to an existing git workflow
+# rule, or creates git-workflow.md. Self-contained copy of planning_seed_rules in
+# scripts/lib/planning.sh. A legacy install with no templates/ beside scripts/ just
+# gets no rules.
+TEMPLATES_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../templates"
+RULES_DIR="${PROJECT_ROOT}/.claude/rules"
+for src in "$TEMPLATES_SRC"/rules/*.md; do
+    [ -f "$src" ] || continue
+    dest="${RULES_DIR}/$(basename "$src")"
+    [ -e "$dest" ] && continue
+    if mkdir -p "$RULES_DIR" && cp "$src" "$dest"; then
+        echo -e "${GREEN}+${NC} Added .claude/rules/$(basename "$src")"
+    fi
+done
+GIT_SECTION="${TEMPLATES_SRC}/git-workflow-section.md"
+if [ -f "$GIT_SECTION" ]; then
+    GIT_RULE=$(ls "$RULES_DIR" 2>/dev/null | grep -iE 'git.?(work)?flow.*\.md$' | head -1)
+    if [ -n "$GIT_RULE" ]; then
+        if ! grep -qF "$(head -1 "$GIT_SECTION")" "${RULES_DIR}/${GIT_RULE}"; then
+            { printf '\n'; cat "$GIT_SECTION"; } >> "${RULES_DIR}/${GIT_RULE}"
+            echo -e "${GREEN}+${NC} Added persistent-plan requirements to .claude/rules/${GIT_RULE}"
+        fi
+    elif mkdir -p "$RULES_DIR" && { printf '# Git Workflow\n\n'; cat "$GIT_SECTION"; } > "${RULES_DIR}/git-workflow.md"; then
+        echo -e "${GREEN}+${NC} Added .claude/rules/git-workflow.md"
+    fi
+fi
+
 # Step 6: List other active tasks
 OTHER_TASKS=$(find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" 2>/dev/null | wc -l)
 if [ "$OTHER_TASKS" -gt 0 ]; then

package/scripts/init-task.sh

@@ -116,6 +116,8 @@ planning_insert_list_item \
   "## Tasks" \
   "- [ ] **${TASK_NAME}** (\`${TASK_SLUG}\`)"
 
+planning_seed_rules "${ROOT}"
+
 echo ""
 planning_ok "Task '${TASK_NAME}' ready at .planning/${PARENT_PHASE}/${TASK_SLUG}/"
 echo ""

package/scripts/lib/planning.sh

@@ -23,6 +23,10 @@
 #   - planning_render_template "<src>" "<dest>" "PLACEHOLDER1=value1" "PLACEHOLDER2=value2" ...
 #       Renders a template file by sed-substituting PLACEHOLDER tokens.
 #       Refuses to overwrite existing dest unless PLANNING_FORCE=1 in env.
+#   - planning_uses_hewtd "<root>"   →  exit 0 when the project uses hit-em-with-the-docs
+#   - planning_seed_rules "<root>"   →  copies templates/rules/*.md into <root>/.claude/rules/
+#       when absent; never overwrites. Appends templates/git-workflow-section.md once to
+#       the repo's git workflow rule, or creates git-workflow.md
 #   - planning_color_<name>          →  ANSI color codes (green, blue, yellow, cyan, red, reset)
 #                                       (only set when stdout is a tty; empty otherwise)
 #   - Color-coded log helpers: planning_log, planning_ok, planning_warn, planning_err
@@ -281,3 +285,60 @@ planning_ensure_archive_gitignored() {
   printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "$gitignore"
   planning_ok "Added .planning/.archive/ to .gitignore (active plans stay shareable)"
 }
+
+# planning_uses_hewtd <repo-root>
+#
+# True when this project uses hit-em-with-the-docs: it has a .documentation/ tree or
+# hewtd's project config. A machine-wide hewtd install does not count — it would put
+# hewtd steps into plans for repos that have no docs tree. init-planning.sh (sm) keeps
+# a self-contained copy of this check.
+planning_uses_hewtd() {
+  [[ -d "${1}/.documentation" || -f "${1}/.claude/hit-em-with-the-docs.json" ]]
+}
+
+# planning_seed_rules <repo-root>
+#
+# Copies each templates/rules/*.md into <root>/.claude/rules/ when that file is absent.
+# Written once: after that the rule is the repo's, so an existing file is never
+# overwritten — not even under PLANNING_FORCE, which is for plan artifacts.
+#
+# The git-workflow section is the exception: it is appended to the repo's existing git
+# workflow rule (babel-fish writes git-workflow.md) or creates one. Its first line is a
+# marker, so it is added once and a repo's edits to it stick.
+#
+# Reads only the plugin's own templates, never <root>/templates: that name is generic
+# enough that a project could have one, and its files are not ours to load.
+# init-planning.sh (sm) keeps a self-contained copy of this function.
+planning_seed_rules() {
+  local root="$1" src dest target
+  local tpl_dir rules="${1}/.claude/rules"
+  tpl_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../../templates"
+  for src in "$tpl_dir"/rules/*.md; do
+    [[ -f "$src" ]] || continue
+    dest="${rules}/$(basename "$src")"
+    [[ -e "$dest" ]] && continue
+    if mkdir -p "$rules" && cp "$src" "$dest"; then
+      planning_ok "Added .claude/rules/$(basename "$src")"
+    else
+      planning_warn "Could not write ${dest} (skipped)"
+    fi
+  done
+
+  local section="${tpl_dir}/git-workflow-section.md"
+  [[ -f "$section" ]] || return 0
+  target=$(ls "$rules" 2>/dev/null | grep -iE 'git.?(work)?flow.*\.md$' | head -1)
+  if [[ -n "$target" ]]; then
+    target="${rules}/${target}"
+    grep -qF "$(head -1 "$section")" "$target" && return 0
+    if { printf '\n'; cat "$section"; } >> "$target"; then
+      planning_ok "Added persistent-plan requirements to .claude/rules/$(basename "$target")"
+    else
+      planning_warn "Could not update ${target} (skipped)"
+    fi
+  elif mkdir -p "$rules" && { printf '# Git Workflow\n\n'; cat "$section"; } > "${rules}/git-workflow.md"; then
+    planning_ok "Added .claude/rules/git-workflow.md"
+  else
+    planning_warn "Could not write ${rules}/git-workflow.md (skipped)"
+  fi
+  return 0
+}

package/skills/persistent-planning/SKILL.md

@@ -147,7 +147,10 @@ Both tasks coexist independently. Switch between them as needed.
 
 ## task_plan.md Template
 
-Create this file FIRST for any complex task:
+Create this file FIRST for any complex task. In a project that uses hit-em-with-the-docs
+(it has `.documentation/`), the init scripts word the last phase as a full
+hit-em-with-the-docs pass capturing all changes (procedures, tools, troubleshooting,
+gotchas, KB articles), never secrets; lg's docs closer gets matching atoms.
 
 ```markdown
 # Task Plan: [Brief Description]
@@ -161,7 +164,7 @@ Create this file FIRST for any complex task:
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
 - [ ] 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 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)
 
 > Phases 5, 6 and 7 are mandatory and MUST stay the last three phases of this plan.
@@ -172,9 +175,19 @@ Create this file FIRST for any complex task:
 >   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.
+> - **Validate success**: we need to validate success thoroughly through comprehensive
+>   testing of our changes. Write the tests into this plan when you write the plan --
+>   don't wait to be asked. List each check under Phase 6, every kind that applies:
+>   unit tests for new and changed logic, integration and end-to-end runs through the
+>   real entry points, a regression test for the problem that prompted the work, edge
+>   cases and failure paths, and the full existing suite. Each must 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.
+>   Capture new procedures, tools, troubleshooting steps, gotchas and KB articles too.
+>   Never include secrets or passwords. Write the docs work into this plan when you
+>   write the plan -- don't wait to be asked. List each doc under Phase 7 by file:
+>   every doc this work creates, changes or makes stale.
 >   If hit-em-with-the-docs is installed, you MUST use it for this pass --
 >   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
 >   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or

package/templates/git-workflow-section.md

@@ -0,0 +1,11 @@
+<!-- persistent-planning:git-workflow -->
+## Persistent plans
+
+These are hard requirements on every plan under `.planning/`:
+
+1. **Sync `main` first.** `git checkout main && git fetch origin main && git merge --ff-only origin/main`.
+2. **Cut a new branch** for the plan before changing anything: `git checkout -b <type>/<plan-slug>`.
+3. **Implement the plan through to completion**: every phase, including the mandatory cleanup,
+   validation and documentation steps, until `/plan-status` reads COMPLETE.
+4. **Commit at the end of each phase** (sm: each item under `## Phases`; lg: each task).
+5. **Finish with a single PR** for the whole plan, against `main`.

package/templates/lg/phase.md

@@ -23,7 +23,7 @@ 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)
+- [ ] **DOCS_CLOSER_PLACEHOLDER** (`documentation-pass-create-update-deprecate-docs`) (MANDATORY — last)
 
 > 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
@@ -34,9 +34,19 @@ _(no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`
 >   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.
+> - **Validate success**: we need to validate success thoroughly through comprehensive
+>   testing of our changes. Write the tests into this phase as you write its tasks --
+>   don't wait to be asked. Add each check as an atom of the validation task, every kind
+>   that applies: unit tests for new and changed logic, integration and end-to-end runs
+>   through the real entry points, a regression test for the problem that prompted the
+>   work, edge cases and failure paths, and the full existing suite. Each must fail if
+>   the change 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.
+>   Capture new procedures, tools, troubleshooting steps, gotchas and KB articles too.
+>   Never include secrets or passwords. Write the docs work into this phase as you write
+>   its tasks -- don't wait to be asked. Add an atom to the documentation task for each
+>   doc they create, change or make stale, naming the file.
 >   If hit-em-with-the-docs is installed, you MUST use it for this pass --
 >   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
 >   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or

package/templates/rules/persistent-planning.md

@@ -0,0 +1,35 @@
+# Persistent Planning
+
+> Auto-loaded every session. Written once by persistent-planning's init scripts and never
+> overwritten: edit it to fit this repo.
+
+Plans live in `.planning/`, on disk, so they survive context resets and can be handed to
+teammates and subagents. The files are the working memory: read them, keep them current.
+
+## Working a plan
+
+- **Before starting work**, run `/plan-status` and read the active plan. Re-read it before any
+  major decision.
+- **Create plans with the commands**, never by hand: `/start-planning`, then (team mode)
+  `/start-task --parent <phase>` and `/start-atom --parent <task>`. They keep each parent's list
+  in order and the closing steps last.
+- **Write the testing into the plan when you write the plan**: we need to validate success
+  thoroughly through comprehensive testing of our changes. Fill the validation step with the
+  specific checks this work needs (unit, integration, end-to-end, regression, edge cases and
+  failure paths, the full suite) before starting work, without being asked.
+- **Write the docs work into the plan too**: under the documentation step, name each doc this
+  work creates, changes or makes stale, by file.
+- **Update as you go**: tick each box when it is done, record decisions and errors as they
+  happen, and put research in `notes.md` instead of the conversation.
+- The layers are **phase → task → atom**, plus **notes** for context at phase or task level.
+  Use those words. Do work in dependency order first; mark work `parallelizable: true` only
+  when nothing it depends on is unfinished.
+
+## Finishing a plan
+
+- Every plan ends with three **mandatory** steps, always last, in this order: cleanup of junk
+  and unused code, validation by testing, a documentation pass. Add new work above them, never
+  after, and never skip them.
+- **A plan is done when `/plan-status` says COMPLETE.** Don't mark it done any other way.
+- Retire a finished plan with `/archive-plan <slug>`. Never delete a plan.
+- Active plans are committed to git; only `.planning/.archive/` is ignored.