@theglitchking/persistent-planning 3.5.0 → 3.6.1

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.1"
   },
   "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.1",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "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",
   "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 |
 
@@ -128,7 +128,7 @@ purpose: Navigation hub for all documentation
 
 | Document | Tier | Status | Updated |
 |----------|------|--------|----------|
-| [Plan Completion and Archive](procedures/plan-completion-and-archive.md) | guide | active | 2026-08-31 |
+| [Plan Completion and Archive](procedures/plan-completion-and-archive.md) | guide | active | 2026-10-23 |
 | [Plugin update delivery — what actually runs, and when](procedures/plugin-update-delivery.md) | guide | active | 2026-09-04 |
 
 ---
@@ -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,59 @@
+---
+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:** 3
+
+## 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      |
+| `git-rm-cached-moved-path-drops-staged` | git rm --cached on a path whose files were moved away silently drops staged content           | 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      |
+| `git-rm-cached-moved-path-drops-staged` | git rm --cached on a path whose files were moved away silently drops staged content           | 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/facts/git-rm-cached-moved-path-drops-staged.md

@@ -0,0 +1,56 @@
+---
+title: git rm --cached on a path whose files were moved away silently drops staged content
+tier: fact
+domains:
+  - troubleshooting
+status: active
+last_updated: 2026-10-23
+id: git-rm-cached-moved-path-drops-staged
+confidence: high
+last_verified: 2026-10-23
+verify_command: |
+  #!/usr/bin/env bash
+  set -euo pipefail
+  d=$(mktemp -d); cd "$d"; git init -q; echo a > f; git add f; git -c user.name=t -c user.email=t@t commit -qm a
+  echo staged > f; git add f; echo a > f; mkdir moved; mv f moved/
+  git rm -q --cached f && echo "rm --cached succeeded: staged blob dropped from index"
+  cd /; rm -rf "${d:?}"
+provenance:
+  - .planning/archive-plan-untracks-archived-plans-issue-26/
+sources:
+  - scripts/archive-plan.sh
+tags:
+  - gotcha
+  - git
+invalidated_by:
+  - git rm --cached starts refusing when the index entry differs from HEAD regardless of the worktree
+---
+
+# git rm --cached on a path whose files were moved away silently drops staged content
+
+## Claim
+
+`git rm --cached <path>` refuses ("staged content different from both the file and the HEAD")
+only when it can compare against a **worktree file**. If the files at `<path>` have already been
+moved elsewhere (e.g. `mv .planning/x .planning/.archive/x`), there is nothing to compare, and git
+untracks the path without complaint. Any staged content that differed from the worktree copy is
+then gone from the index. Only a dangling blob is left, which `git fsck` can find.
+
+Found while fixing #26: the first fix moved the plan, then relied on `git rm --cached` refusing to
+protect staged changes. It never refused.
+
+## How to verify
+
+Run `verify_command`. It stages content that differs from the worktree, moves the file away, and
+`git rm --cached` succeeds.
+
+## Instead
+
+Check for staged changes **before** moving: `git diff --cached --quiet -- <path>` (non-zero means
+staged changes). If there are any, don't untrack. Warn and let the user commit or unstage first.
+This is what `scripts/archive-plan.sh` does.
+
+## Consequences
+
+Any "move, then untrack the old path" sequence needs its own staged-change check. Git's built-in
+refusal won't protect it.

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/procedures/INDEX.md

@@ -3,7 +3,7 @@ title: Procedures Documentation Index
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-26'
+last_updated: '2026-10-23'
 version: '1.0.0'
 purpose: Complete listing of procedures documentation
 ---
@@ -25,7 +25,7 @@ purpose: Complete listing of procedures documentation
 
 | Document | Status | Updated | Words |
 |----------|--------|---------|-------|
-| [Plan Completion and Archive](plan-completion-and-archive.md) | active | 2026-08-31 | 812 |
+| [Plan Completion and Archive](plan-completion-and-archive.md) | active | 2026-10-23 | 812 |
 | [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md) | active | 2026-09-04 | 539 |
 
 ## Keywords
@@ -40,4 +40,4 @@ This domain covers: procedure, procedures, sop, standard-operating-procedure, st
 
 ---
 
-*Last updated: 2026-09-26*
+*Last updated: 2026-10-23*

package/.documentation/procedures/REGISTRY.md

@@ -3,7 +3,7 @@ title: Procedures Registry
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-26'
+last_updated: '2026-10-23'
 version: '1.0.0'
 purpose: Quick reference for procedures documentation
 ---
@@ -27,8 +27,8 @@ purpose: Quick reference for procedures documentation
 
 ## Recently Updated
 
+- [Plan Completion and Archive](plan-completion-and-archive.md) - 2026-10-23
 - [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md) - 2026-09-04
-- [Plan Completion and Archive](plan-completion-and-archive.md) - 2026-08-31
 
 ## By Status
 
@@ -50,4 +50,4 @@ purpose: Quick reference for procedures documentation
 
 ---
 
-*Last updated: 2026-09-26*
+*Last updated: 2026-10-23*

package/.documentation/procedures/plan-completion-and-archive.md

@@ -7,7 +7,7 @@ audience:
   - developers
 tags: []
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-10-23'
 version: 1.0.0
 purpose: How persistent-planning decides a plan is finished, how that reaches
   the agent automatically, and the procedure for retiring a completed plan into
@@ -104,17 +104,22 @@ Archiving performs four steps:
 
 1. Verifies completion (skipped under `--force`).
 2. Ensures `.planning/.archive/` exists and is in `.gitignore`.
-3. Moves `.planning/<slug>/` → `.planning/.archive/<slug>/`, preferring `git mv`
-   when the plan is tracked so history follows it.
+3. Moves `.planning/<slug>/` → `.planning/.archive/<slug>/`. If the plan is tracked,
+   it is also removed from git's index (`git rm -r --cached`; the files stay on
+   disk), so the archive is local history and the next commit shows the plan as
+   deleted. Its history stays in git. A plan with **staged** changes stays tracked
+   with a warning, because untracking would drop content that only the index holds.
+   Commit or unstage, then run `git rm -r --cached .planning/<slug>`.
 4. Stamps the top-level artifact: `status: archived` + `archived_on` in
    frontmatter, or a dated footer for sm plans that have none.
 
-**Nothing is ever deleted.** Archiving is a move plus a stamp.
+**Nothing is ever deleted.** Archiving is a move plus a stamp; the git side is an untrack, not a delete.
 
 ## Restoring an archived plan
 
 ```bash
 mv .planning/.archive/<slug> .planning/<slug>
+git add .planning/<slug>          # it was untracked when archived
 ```
 
 Then set `status:` back to `active` and remove the `archived_on` stamp. The plan
@@ -129,7 +134,8 @@ resumes reading as in-progress the moment a box is unchecked.
 | `archive-plan.sh` refuses | The plan is genuinely incomplete | Finish it. `--force` exists for deliberate abandonment, not for impatience |
 | "Already archived: … exists" | A plan with that slug was archived before | Rename or move the existing entry under `.planning/.archive/` first |
 | Nudge never appears | No `.planning/` directory, or no plan is complete, or the hook is not registered | `npx persistent-planning status` reports hook registration |
-| Archived plans show up in `git status` | `.planning/` is tracked in this repo and the ignore line was added after the fact | Ensure `.gitignore` has `.planning/.archive/`; `git rm -r --cached .planning/.archive` if already tracked |
+| Archived plans show up in `git status` / are tracked under `.archive/` | Archived before the fix for #26: `archive-plan.sh` used `git mv` and kept them tracked ([#26](https://github.com/the-glitch-kingdom/persistent-planning/issues/26)); or the ignore line was added after the fact | Ensure `.gitignore` has `.planning/.archive/`, then `git rm -r --cached .planning/.archive` (stage any pending stamp first: `git add -f .planning/.archive/*/phase.md`). Files stay on disk |
+| "Archived on disk, but git still tracks …" warning | The plan had staged changes; untracking would have dropped them | Commit or unstage them, then `git rm -r --cached .planning/<slug>` |
 
 ## Design notes
 

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*