@theglitchking/persistent-planning 3.5.0 → 3.6.1

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,68 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.6.1] - 2026-10-23
+
+### Fixed — archived plans stayed tracked in git (#26)
+
+`archive-plan.sh` moved tracked plans with `git mv`, so they stayed tracked
+inside the gitignored `.planning/.archive/`, because ignore rules never apply to
+tracked files. It now moves the plan and untracks it (`git rm -r --cached`).
+The files stay on disk and the next commit shows the plan as deleted. A plan
+with staged changes stays tracked with a warning rather than losing content
+only the index holds. Repos with plans archived earlier:
+`git rm -r --cached .planning/.archive`.
+
+## [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.1",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {

package/scripts/archive-plan.sh

@@ -12,8 +12,8 @@
 #   1. Refuses unless the plan is complete (every checkbox checked, or the
 #      top-level artifact declares `status: done`) -- override with --force.
 #   2. Ensures .planning/.archive/ exists and is gitignored.
-#   3. Moves .planning/<slug>/ to .planning/.archive/<slug>/ (git mv when the
-#      plan is tracked, so history follows it).
+#   3. Moves .planning/<slug>/ to .planning/.archive/<slug>/. A tracked plan is
+#      also removed from git's index (files stay on disk): archives are local.
 #   4. Stamps the plan's top-level artifact with status: archived + archived_on.
 #
 # Nothing is ever deleted. Restore by moving the directory back out.
@@ -111,18 +111,32 @@ archive_one() {
   fi
 
   if [[ $DRY_RUN -eq 1 ]]; then
-    planning_log "[dry-run] would archive .planning/${slug}/ -> .planning/.archive/${slug}/"
+    planning_log "[dry-run] would archive .planning/${slug}/ -> .planning/.archive/${slug}/ (untracked from git if tracked)"
     return 0
   fi
 
   ensure_gitignored
   mkdir -p "$ARCHIVE"
 
+  local tracked=0 staged=0
   if git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1 \
      && [[ -n "$(git -C "$ROOT" ls-files ".planning/${slug}" 2>/dev/null)" ]]; then
-    git -C "$ROOT" mv ".planning/${slug}" ".planning/.archive/${slug}"
-  else
-    mv "$src" "$dest"
+    tracked=1
+    git -C "$ROOT" diff --cached --quiet -- ".planning/${slug}" 2>/dev/null || staged=1
+  fi
+
+  mv "$src" "$dest"
+
+  # A tracked plan leaves the index: archived plans are local history (issue #26).
+  # git mv kept them tracked inside the gitignored .archive/, since ignore rules
+  # never apply to tracked files. Staged changes are checked first, because once
+  # the files have moved git rm --cached no longer refuses and would drop them.
+  if [[ $tracked -eq 1 && $staged -eq 1 ]]; then
+    planning_warn "Archived on disk, but git still tracks .planning/${slug}/ (it has staged changes)."
+    echo "  Commit or unstage them, then untrack with: git rm -r --cached .planning/${slug}" >&2
+  elif [[ $tracked -eq 1 ]]; then
+    git -C "$ROOT" rm -r -q --cached ".planning/${slug}" >/dev/null 2>&1 \
+      || planning_warn "Archived on disk, but could not untrack .planning/${slug}/: git rm -r --cached .planning/${slug}"
   fi
 
   stamp_archived "$(plan_root_artifact "$dest")"

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.