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

package/.claude-plugin/plugin.json

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

package/.documentation/INDEX.md

@@ -3,7 +3,7 @@ title: Documentation Index
 tier: reference
 domains: [root]
 status: active
-last_updated: '2026-09-04'
+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-04
+- **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/REGISTRY.md

@@ -3,7 +3,7 @@ title: Documentation Registry
 tier: reference
 domains: [root]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for all documentation domains
 ---
@@ -77,4 +77,4 @@ purpose: Quick reference for all documentation domains
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/agents/INDEX.md

@@ -3,7 +3,7 @@ title: Agents Documentation Index
 tier: reference
 domains: [agents]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of agents documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: agent, agents, ai, assistant, expert, specialist, llm, langc
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/agents/REGISTRY.md

@@ -3,7 +3,7 @@ title: Agents Registry
 tier: reference
 domains: [agents]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for agents documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for agents documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/api/INDEX.md

@@ -3,7 +3,7 @@ title: API Documentation Index
 tier: reference
 domains: [api]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of api documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: api, endpoint, endpoints, route, routes, rest, restful, grap
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/api/REGISTRY.md

@@ -3,7 +3,7 @@ title: API Registry
 tier: reference
 domains: [api]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for api documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for api documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/architecture/INDEX.md

@@ -3,7 +3,7 @@ title: Architecture Documentation Index
 tier: reference
 domains: [architecture]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of architecture documentation
 ---
@@ -47,4 +47,4 @@ This domain covers: architecture, design, system, system-design, pattern, patter
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/architecture/REGISTRY.md

@@ -3,7 +3,7 @@ title: Architecture Registry
 tier: reference
 domains: [architecture]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for architecture documentation
 ---
@@ -54,4 +54,4 @@ purpose: Quick reference for architecture documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/architecture/lg-plan-artifact-lifecycle.md

@@ -57,17 +57,18 @@ It **anchors on the MANDATORY marker, never on line numbers.** The list is a
 human-editable surface; positions do not survive contact with editing. This is tested
 against a hand-reordered, partially-checked, annotated list.
 
-## The two closers
+## The three closers
 
-Every phase is scaffolded with both closing tasks as real directories:
+Every phase is scaffolded with all three closing tasks as real directories, in this order:
 
 ```
+<phase>/cleanup-remove-junk-and-unused-code/
 <phase>/validate-success-through-comprehensive-testing/
 <phase>/documentation-pass-create-update-deprecate-docs/
 ```
 
 Each gets `task.md` (with `mandatory: true`, `parallelizable: false`), `notes.md`,
-`atoms/`, and seeded atoms — not empty placeholders. They were previously two lines
+`atoms/`, and seeded atoms — not empty placeholders. The original two were previously lines
 of prose in `phase.md`, which made the most important tasks in every plan the only
 ones with no artifact a subagent could read and nowhere to record decisions.
 

package/.documentation/backups/INDEX.md

@@ -3,7 +3,7 @@ title: Backups Documentation Index
 tier: reference
 domains: [backups]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of backups documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: backup, backups, restore, recovery, disaster, disaster-recov
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/backups/REGISTRY.md

@@ -3,7 +3,7 @@ title: Backups Registry
 tier: reference
 domains: [backups]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for backups documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for backups documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/database/INDEX.md

@@ -3,7 +3,7 @@ title: Database Documentation Index
 tier: reference
 domains: [database]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of database documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: database, db, postgres, postgresql, mysql, sql, schema, migr
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/database/REGISTRY.md

@@ -3,7 +3,7 @@ title: Database Registry
 tier: reference
 domains: [database]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for database documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for database documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/devops/INDEX.md

@@ -3,7 +3,7 @@ title: DevOps Documentation Index
 tier: reference
 domains: [devops]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of devops documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: devops, deployment, deploy, ci, cd, ci/cd, pipeline, docker,
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/devops/REGISTRY.md

@@ -3,7 +3,7 @@ title: DevOps Registry
 tier: reference
 domains: [devops]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for devops documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for devops documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/features/INDEX.md

@@ -3,7 +3,7 @@ title: Features Documentation Index
 tier: reference
 domains: [features]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of features documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: feature, features, implementation, guide, how-to, tutorial,
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/features/REGISTRY.md

@@ -3,7 +3,7 @@ title: Features Registry
 tier: reference
 domains: [features]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for features documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for features documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

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

@@ -3,7 +3,7 @@ title: Plans Documentation Index
 tier: reference
 domains: [plans]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of plans documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: plan, plans, planning, roadmap, proposal, proposals, rfc, de
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/plans/REGISTRY.md

@@ -3,7 +3,7 @@ title: Plans Registry
 tier: reference
 domains: [plans]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for plans documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for plans documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/procedures/INDEX.md

@@ -3,7 +3,7 @@ title: Procedures Documentation Index
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of procedures documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: procedure, procedures, sop, standard-operating-procedure, st
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/procedures/REGISTRY.md

@@ -3,7 +3,7 @@ title: Procedures Registry
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for procedures documentation
 ---
@@ -50,4 +50,4 @@ purpose: Quick reference for procedures documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/quickstart/INDEX.md

@@ -3,7 +3,7 @@ title: Quickstart Documentation Index
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of quickstart documentation
 ---
@@ -39,4 +39,4 @@ This domain covers: quickstart, quick-start, getting-started, setup, install, in
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/quickstart/REGISTRY.md

@@ -3,7 +3,7 @@ title: Quickstart Registry
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for quickstart documentation
 ---
@@ -48,4 +48,4 @@ purpose: Quick reference for quickstart documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/reference/INDEX.md

@@ -3,7 +3,7 @@ title: Reference Documentation Index
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Complete listing of reference documentation
 ---
@@ -46,4 +46,4 @@ This domain covers: schema, frontmatter, workspace.json, field, enum, cli, flags
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*

package/.documentation/reference/REGISTRY.md

@@ -3,7 +3,7 @@ title: Reference Registry
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-09-04'
+last_updated: '2026-09-26'
 version: '1.0.0'
 purpose: Quick reference for reference documentation
 ---
@@ -52,4 +52,4 @@ purpose: Quick reference for reference documentation
 
 ---
 
-*Last updated: 2026-09-04*
+*Last updated: 2026-09-26*