@theglitchking/persistent-planning 3.4.2 → 3.6.0

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 \
@@ -125,7 +161,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,9 +198,21 @@ 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" \
+  "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" \
@@ -172,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'
@@ -105,15 +114,31 @@ 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 -- we need to validate success thoroughly through comprehensive testing of our changes (MANDATORY)
+- [ ] Phase 7: DOCS_PHASE_PLACEHOLDER (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.
 >
-> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **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**: 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
@@ -155,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)"
@@ -228,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]
@@ -160,15 +163,31 @@ 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 -- 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 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.
 >
-> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **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**: 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

@@ -21,16 +21,32 @@ 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)
+- [ ] **DOCS_CLOSER_PLACEHOLDER** (`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.
 >
-> - **Validate success**: prove the phase's work with tests that fail if it breaks.
+> - **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**: 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.