@theglitchking/persistent-planning 3.6.0 → 3.6.2

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.6.0"
+    "version": "3.6.2"
   },
   "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.6.0",
+      "version": "3.6.2",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "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

@@ -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 |
 
 ---

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

@@ -13,7 +13,7 @@ purpose: Auto-generated index of all facts in the knowledge base, grouped by tag
 
 <!-- Auto-generated by `hewtd maintain`. Do not edit by hand — changes will be overwritten. -->
 
-**Total facts:** 2
+**Total facts:** 3
 
 ## babel-fish
 
@@ -35,18 +35,20 @@ purpose: Auto-generated index of all facts in the knowledge base, grouped by tag
 
 ### 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      |
+| 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      |
+| 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
 

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/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/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.6.2] - 2026-11-09
+
+### Changed
+
+- **A plan's branch is cut from `main`.** Step 2 of the git-workflow section read
+  "Cut a new branch" and only implied `main` through step 1's sync. It now reads
+  "Cut a branch from `main`", with the base in the command
+  (`git checkout -b <type>/<plan-slug> main`). The section is appended once, so a
+  repo that already has it keeps the old wording until edited.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "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/templates/git-workflow-section.md

@@ -4,7 +4,7 @@
 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>`.
+2. **Cut a branch from `main`** for the plan before changing anything: `git checkout -b <type>/<plan-slug> main`.
 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).