@theglitchking/persistent-planning 3.0.1 → 3.1.0

package/commands/archive-plan.md

@@ -0,0 +1,66 @@
+---
+name: archive-plan
+description: "Retire a completed plan into the gitignored .planning/.archive/ directory. Refuses to archive a plan that still has unchecked boxes unless --force is passed. Works in both sm and lg mode."
+---
+
+# /archive-plan
+
+Move a finished plan out of the active tree so `.planning/` only ever shows work
+that is still live. Nothing is deleted — archiving is a move plus a status stamp,
+and is reversed by moving the directory back.
+
+---
+
+## Usage
+
+```
+/archive-plan <plan-slug>
+/archive-plan --all-complete
+/archive-plan <plan-slug> --force      # archive a plan that is not finished
+/archive-plan <plan-slug> --dry-run
+```
+
+## What To Do
+
+When the user runs `/archive-plan`:
+
+1. Run the script:
+
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/archive-plan.sh" "<plan-slug>"
+```
+
+If the script isn't found at that path, try in order:
+
+```bash
+bash scripts/archive-plan.sh "<plan-slug>"
+bash ~/.claude/skills/persistent-planning/scripts/archive-plan.sh "<plan-slug>"
+```
+
+2. If the script refuses because the plan is incomplete, **do not reach for
+   `--force` on your own.** Run `/plan-status`, tell the user what is still
+   unchecked, and let them decide.
+
+## What it does
+
+1. Verifies the plan is complete (every checkbox checked, or `status: done`).
+2. Ensures `.planning/.archive/` exists and is listed in `.gitignore` — completed
+   plans are local history, not something every clone carries.
+3. Moves `.planning/<slug>/` to `.planning/.archive/<slug>/`, using `git mv` when
+   the plan is tracked so history follows it.
+4. Stamps the plan's top-level artifact: `status: archived` plus `archived_on`
+   (frontmatter), or a dated footer for sm plans that have no frontmatter.
+
+## Restoring
+
+```bash
+mv .planning/.archive/<slug> .planning/<slug>
+```
+
+Then set `status:` back to `active` and drop the `archived_on` stamp.
+
+## See also
+
+- `/plan-status` — see which plans are complete
+- `.documentation/procedures/plan-completion-and-archive.md` — the full completion protocol

package/commands/plan-status.md

@@ -0,0 +1,62 @@
+---
+name: plan-status
+description: "Show completion status for every plan under .planning/ — which are in progress, blocked, or complete and ready to archive. Works in both sm and lg mode."
+---
+
+# /plan-status
+
+Report where every plan stands. Completion is derived from the plan artifacts
+themselves (checkbox state + frontmatter `status:`), so it cannot drift away from
+what the plan actually says.
+
+---
+
+## Usage
+
+```
+/plan-status
+```
+
+## What To Do
+
+Run the status script:
+
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/plan-status.sh"
+```
+
+If the script isn't found at that path, try in order:
+
+```bash
+bash scripts/plan-status.sh
+bash ~/.claude/skills/persistent-planning/scripts/plan-status.sh
+```
+
+Then read the table back to the user. If any plan is listed `COMPLETE`, offer to
+archive it with `/archive-plan <slug>`.
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `in progress` | Unchecked boxes remain |
+| `blocked` | An atom in the plan carries `status: blocked` |
+| `COMPLETE` | Every box checked, or the top-level artifact says `status: done` — ready to archive |
+| `empty` | Plan artifact exists but has no checkboxes yet |
+| `archived` | Already retired (only visible if left in the active tree) |
+
+## Machine-readable forms
+
+```bash
+bash scripts/plan-status.sh --complete   # one complete plan slug per line
+bash scripts/plan-status.sh --nudge      # one-line notice, or silence
+```
+
+`--nudge` is what the SessionStart hook uses, so a finished plan gets mentioned
+at the top of the next session rather than being rediscovered later.
+
+## See also
+
+- `/archive-plan` — retire a completed plan into `.planning/.archive/`
+- `.documentation/procedures/plan-completion-and-archive.md` — the full completion protocol

package/commands/start-atom.md

@@ -69,7 +69,7 @@ Not every step needs a standalone atom file. The rule of thumb:
 - **Inline checkbox in `task.md`**: simple, self-contained step that doesn't need its own context file. The user (or the active agent) handles it directly.
 - **Standalone atom file via `/start-atom`**: a step that will be **handed off to a subagent**. Atoms get their own files because subagents need explicit inputs / outputs / acceptance criteria they can read structured rather than parse from prose.
 
-See `docs/atom-granularity.md` for full anti-pattern guidance with examples.
+See `.documentation/standards/atom-granularity.md` for full anti-pattern guidance with examples.
 
 ## Sequence semantics
 
@@ -89,5 +89,5 @@ This command refuses to run if the project is in sm mode. To switch:
 
 - `/start-planning` — initialize the planning structure (phase in lg)
 - `/start-task` — add a task under a phase
-- `docs/lg-mode.md` — full lg-mode layer model
-- `docs/atom-granularity.md` — when to spawn an atom file vs. inline checkbox
+- `.documentation/architecture/lg-mode.md` — full lg-mode layer model
+- `.documentation/standards/atom-granularity.md` — when to spawn an atom file vs. inline checkbox

package/commands/start-planning.md

@@ -111,5 +111,5 @@ Names are converted to URL-friendly slugs:
 
 - `/start-task` — add a task under a phase (lg mode only)
 - `/start-atom` — add an atom (subagent hand-off unit) under a task (lg mode only)
-- `docs/workspace-json.md` — workspace.json schema reference
-- `docs/lg-mode.md` — full lg-mode guide (phase / task / atom / notes layer model)
+- `.documentation/reference/workspace-json.md` — workspace.json schema reference
+- `.documentation/architecture/lg-mode.md` — full lg-mode guide (phase / task / atom / notes layer model)

package/commands/start-task.md

@@ -79,5 +79,5 @@ That writes `.planning/.meta/workspace.json` with `mode: "lg"` and creates the f
 
 - `/start-planning` — initialize the planning structure (phase in lg, task in sm)
 - `/start-atom` — add an atom under a task
-- `docs/lg-mode.md` — full lg-mode layer model
-- `docs/atom-granularity.md` — when to spawn an atom file vs. add an inline checkbox
+- `.documentation/architecture/lg-mode.md` — full lg-mode layer model
+- `.documentation/standards/atom-granularity.md` — when to spawn an atom file vs. add an inline checkbox

package/hooks/session-start.js

@@ -1,13 +1,84 @@
 #!/usr/bin/env node
 // persistent-planning SessionStart hook.
-// Delegates entirely to @theglitchking/claude-plugin-runtime — this plugin
-// has no mcp.json wiring or project-side reconcile, so only the update
-// check runs.
+//
+// Two jobs:
+//   1. The update check, delegated entirely to @theglitchking/claude-plugin-runtime.
+//   2. A completion nudge: if any plan under .planning/ has every box checked
+//      but is still sitting in the active tree, say so, so the agent archives it
+//      instead of rediscovering a finished plan next session.
 
 import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-await runSessionStart({
-  packageName: "@theglitchking/persistent-planning",
-  pluginName: "persistent-planning",
-  configFile: "persistent-planning.json",
-});
+const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function planNudge() {
+  try {
+    if (!existsSync(join(projectRoot, ".planning"))) return "";
+    const script = join(packageRoot, "scripts", "plan-status.sh");
+    if (!existsSync(script)) return "";
+    const r = spawnSync("bash", [script, "--nudge"], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+const notice = planNudge();
+
+if (!notice) {
+  await runSessionStart({
+    packageName: "@theglitchking/persistent-planning",
+    pluginName: "persistent-planning",
+    configFile: "persistent-planning.json",
+  });
+} else {
+  // ponytail: the runtime owns the one SessionStart JSON response and exposes no
+  // hook for appending to it, and a second response line on stdout is invalid.
+  // So intercept its single write and merge the nudge into that same payload.
+  // Fails open — anything unexpected is written through untouched.
+  const realWrite = process.stdout.write.bind(process.stdout);
+  let merged = false;
+  process.stdout.write = (chunk, ...rest) => {
+    if (!merged) {
+      try {
+        const payload = JSON.parse(String(chunk));
+        const out = payload?.hookSpecificOutput;
+        if (out && out.hookEventName === "SessionStart") {
+          out.additionalContext = out.additionalContext
+            ? `${out.additionalContext}\n${notice}`
+            : notice;
+          merged = true;
+          return realWrite(JSON.stringify(payload) + "\n", ...rest);
+        }
+      } catch {
+        // Not the response payload — fall through and write it as-is.
+      }
+    }
+    return realWrite(chunk, ...rest);
+  };
+
+  await runSessionStart({
+    packageName: "@theglitchking/persistent-planning",
+    pluginName: "persistent-planning",
+    configFile: "persistent-planning.json",
+  });
+
+  // The runtime can return without emitting (e.g. it chdir-failed). Say our piece.
+  if (!merged) {
+    realWrite(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: notice },
+      }) + "\n"
+    );
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
     "persistent-planning": "bin/persistent-planning.js"
   },
   "scripts": {
-    "postinstall": "node scripts/link-skills.js"
+    "postinstall": "node scripts/link-skills.js",
+    "test": "bash tests/run.sh"
   },
   "files": [
     "bin/",
@@ -16,7 +17,8 @@
     "scripts/",
     "templates/",
     "skills/",
-    "docs/",
+    ".documentation/",
+    "!.documentation/reports",
     ".claude-plugin/",
     "README.md",
     "LICENSE",
@@ -57,6 +59,7 @@
     "commander": "^14.0.0"
   },
   "devDependencies": {
+    "@theglitchking/hit-em-with-the-docs": "^2.9.0",
     "@theglitchking/semantic-pages": "^0.10.0"
   }
 }

package/scripts/archive-plan.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+###############################################################################
+# archive-plan.sh - Retire a completed plan into .planning/.archive/
+#
+# Usage:
+#   bash scripts/archive-plan.sh <plan-slug>
+#   bash scripts/archive-plan.sh --all-complete
+#   bash scripts/archive-plan.sh <plan-slug> --force     # archive an unfinished plan
+#   bash scripts/archive-plan.sh <plan-slug> --dry-run
+#
+# What it does:
+#   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).
+#   4. Stamps the plan's top-level artifact with status: archived + archived_on.
+#
+# Nothing is ever deleted. Restore by moving the directory back out.
+###############################################################################
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+SLUG=""
+ALL_COMPLETE=0
+FORCE=0
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all-complete) ALL_COMPLETE=1; shift ;;
+    --force)        FORCE=1; shift ;;
+    --dry-run)      DRY_RUN=1; shift ;;
+    -h|--help)      sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -*)             planning_err "Unknown option: $1"; exit 1 ;;
+    *)              [[ -z "$SLUG" ]] && SLUG="$1"; shift ;;
+  esac
+done
+
+if [[ -z "$SLUG" && $ALL_COMPLETE -eq 0 ]]; then
+  planning_err "A plan slug is required (or --all-complete)."
+  echo "Usage: bash scripts/archive-plan.sh <plan-slug> [--force] [--dry-run]"
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+ARCHIVE="${PLANNING}/.archive"
+TODAY=$(planning_today)
+
+# .planning/.archive/ must be gitignored: completed plans are local history, not
+# something every clone should carry. Idempotent.
+ensure_gitignored() {
+  local gitignore="${ROOT}/.gitignore"
+  grep -qE '^\.planning/?$' "$gitignore" 2>/dev/null && return 0   # whole tree already ignored
+  grep -qE '^\.planning/\.archive/?$' "$gitignore" 2>/dev/null && return 0
+  printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "$gitignore"
+  planning_ok "Added .planning/.archive/ to .gitignore"
+}
+
+plan_root_artifact() {
+  for f in "$1/phase.md" "$1/task_plan.md" "$1/task.md"; do
+    [[ -f "$f" ]] && { echo "$f"; return; }
+  done
+}
+
+# Stamp the plan's top-level artifact so an archived plan reads as archived even
+# when someone opens the file directly, with no directory context.
+stamp_archived() {
+  local file="$1"
+  [[ -f "$file" ]] || return 0
+  if head -1 "$file" | grep -q '^---$'; then
+    # Frontmatter: flip status and add archived_on before the closing delimiter.
+    awk -v today="$TODAY" '
+      NR == 1 { print; next }
+      !done_fm && /^status:[[:space:]]*/ { print "status: archived"; seen_status = 1; next }
+      !done_fm && /^---$/ {
+        if (!seen_status) print "status: archived"
+        print "archived_on: \"" today "\""
+        print; done_fm = 1; next
+      }
+      { print }
+    ' "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
+  else
+    printf '\n---\n\n**Archived %s** — retired by `scripts/archive-plan.sh`.\n' "$TODAY" >> "$file"
+  fi
+}
+
+archive_one() {
+  local slug="$1"
+  local src="${PLANNING}/${slug}"
+  local dest="${ARCHIVE}/${slug}"
+
+  if [[ ! -d "$src" ]]; then
+    planning_err "No such plan: .planning/${slug}/"
+    return 1
+  fi
+  if [[ -e "$dest" ]]; then
+    planning_err "Already archived: .planning/.archive/${slug}/ exists. Move or rename it first."
+    return 1
+  fi
+
+  if [[ $FORCE -eq 0 ]]; then
+    local complete
+    complete=$(bash "${SCRIPT_DIR}/plan-status.sh" --complete | grep -Fx "$slug" || true)
+    if [[ -z "$complete" ]]; then
+      planning_err "Plan '${slug}' is not complete — refusing to archive."
+      echo "  Check what is outstanding with: bash scripts/plan-status.sh"
+      echo "  Archive anyway with:            bash scripts/archive-plan.sh ${slug} --force"
+      return 1
+    fi
+  fi
+
+  if [[ $DRY_RUN -eq 1 ]]; then
+    planning_log "[dry-run] would archive .planning/${slug}/ -> .planning/.archive/${slug}/"
+    return 0
+  fi
+
+  ensure_gitignored
+  mkdir -p "$ARCHIVE"
+
+  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"
+  fi
+
+  stamp_archived "$(plan_root_artifact "$dest")"
+  planning_ok "Archived .planning/${slug}/ -> .planning/.archive/${slug}/"
+}
+
+RC=0
+if [[ $ALL_COMPLETE -eq 1 ]]; then
+  mapfile -t SLUGS < <(bash "${SCRIPT_DIR}/plan-status.sh" --complete)
+  if [[ ${#SLUGS[@]} -eq 0 || -z "${SLUGS[0]}" ]]; then
+    planning_log "No complete plans to archive."
+    exit 0
+  fi
+  for s in "${SLUGS[@]}"; do archive_one "$s" || RC=1; done
+else
+  archive_one "$SLUG" || RC=1
+fi
+exit $RC

package/scripts/init-planning.sh

@@ -105,6 +105,16 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 - [ ] Phase 2: Research/gather information
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
+- [ ] Phase 5: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 6: Documentation pass -- create/update/deprecate docs (MANDATORY)
+
+> Phases 5 and 6 are mandatory and MUST stay the last two phases of this plan.
+> Insert new work above them; never after. Renumber them if you add phases.
+>
+> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **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.
+>   If hit-em-with-the-docs is installed, use it for this pass.
 
 ## Key Questions
 1. [Question to answer]
@@ -126,9 +136,22 @@ if [ ! -f "$TASK_PLAN_FILE" ]; then
 - Update status after each phase
 - Mark completed phases with [x]
 - Save research to notes.md instead of stuffing context
+
+## On Completion
+This plan is complete when every checkbox above is checked. That IS the
+completion signal -- there is no separate status to remember to flip.
+
+When complete, archive it instead of deleting it:
+
+    /plan-status                  # confirm this plan reads COMPLETE
+    /archive-plan TASK_SLUG_PLACEHOLDER    # -> .planning/.archive/TASK_SLUG_PLACEHOLDER/
+
+Archiving moves this directory to the gitignored .planning/.archive/ and stamps
+it archived. Nothing is destroyed.
 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"
     echo -e "${GREEN}+${NC} Created task_plan.md"
 else
     echo -e "${YELLOW}*${NC} task_plan.md already exists (not overwritten)"

package/scripts/plan-status.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+###############################################################################
+# plan-status.sh - Report completion status for every plan under .planning/
+#
+# Usage:
+#   bash scripts/plan-status.sh              # table of every active plan
+#   bash scripts/plan-status.sh --nudge      # one line if plans are archivable, else silence
+#   bash scripts/plan-status.sh --complete   # print the slug of each complete plan, one per line
+#
+# A plan is COMPLETE when every checkbox in it is checked, or when its
+# top-level artifact declares `status: done` in frontmatter. Completion is
+# derived from the artifacts themselves so no separate state file can drift
+# away from what the plan actually says.
+#
+# This is the single implementation of the scan: the SessionStart hook and the
+# /plan-status slash command both shell out to it.
+###############################################################################
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+MODE="table"
+case "${1:-}" in
+  --nudge)    MODE="nudge" ;;
+  --complete) MODE="complete" ;;
+  -h|--help)
+    sed -n '2,18p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 0
+    ;;
+  "") ;;
+  *)
+    planning_err "Unknown option: $1 (try --help)"
+    exit 1
+    ;;
+esac
+
+PLANNING="$(planning_dir)"
+[[ -d "$PLANNING" ]] || { [[ "$MODE" == "table" ]] && planning_warn "No .planning/ directory here."; exit 0; }
+
+# plan_root_artifact <plan-dir> -> path of the plan's top-level file, or empty
+plan_root_artifact() {
+  for f in "$1/phase.md" "$1/task_plan.md" "$1/task.md"; do
+    [[ -f "$f" ]] && { echo "$f"; return; }
+  done
+}
+
+# frontmatter_status <file> -> value of `status:` inside the leading --- block
+frontmatter_status() {
+  [[ -f "$1" ]] || return
+  awk 'NR==1 && $0 != "---" { exit }
+       NR>1 && $0 == "---" { exit }
+       /^status:[[:space:]]*/ { sub(/^status:[[:space:]]*/, ""); gsub(/["\047]/, ""); print; exit }' "$1"
+}
+
+# Emits "<total> <checked>" for every markdown file under a plan directory.
+count_boxes() {
+  local total checked
+  total=$(grep -rhoE '^[[:space:]]*- \[[ xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
+  checked=$(grep -rhoE '^[[:space:]]*- \[[xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$total $checked"
+}
+
+COMPLETE=()
+ROWS=()
+
+for plan_path in "$PLANNING"/*/; do
+  [[ -d "$plan_path" ]] || continue
+  slug=$(basename "$plan_path")
+  case "$slug" in .meta|.archive|archive) continue ;; esac
+
+  root=$(plan_root_artifact "${plan_path%/}")
+  [[ -n "$root" ]] || continue
+
+  read -r total checked <<<"$(count_boxes "${plan_path%/}")"
+  status=$(frontmatter_status "$root")
+  blocked=$(grep -rl '^status: blocked' --include='*.md' "${plan_path%/}" 2>/dev/null | wc -l | tr -d ' ')
+
+  if [[ "$status" == "archived" ]]; then
+    verdict="archived"
+  elif [[ "$status" == "done" ]] || { [[ "$total" -gt 0 ]] && [[ "$checked" -eq "$total" ]]; }; then
+    verdict="COMPLETE"
+    COMPLETE+=("$slug")
+  elif [[ "$blocked" -gt 0 ]]; then
+    verdict="blocked"
+  elif [[ "$total" -eq 0 ]]; then
+    verdict="empty"
+  else
+    verdict="in progress"
+  fi
+
+  ROWS+=("$(printf '%-38s %-12s %s/%s boxes' "$slug" "$verdict" "$checked" "$total")")
+done
+
+case "$MODE" in
+  complete)
+    printf '%s\n' "${COMPLETE[@]+"${COMPLETE[@]}"}"
+    ;;
+  nudge)
+    if [[ ${#COMPLETE[@]} -gt 0 ]]; then
+      printf 'persistent-planning: %d plan(s) complete but not archived — %s. Archive with: /archive-plan <slug>\n' \
+        "${#COMPLETE[@]}" "$(IFS=', '; echo "${COMPLETE[*]}")"
+    fi
+    ;;
+  table)
+    if [[ ${#ROWS[@]} -eq 0 ]]; then
+      planning_warn "No plans found under .planning/."
+      exit 0
+    fi
+    planning_log "Plans under .planning/"
+    echo ""
+    printf '  %-38s %-12s %s\n' "PLAN" "STATUS" "PROGRESS"
+    printf '  %s\n' "$(printf '%.0s-' {1..70})"
+    printf '  %s\n' "${ROWS[@]}"
+    echo ""
+    if [[ ${#COMPLETE[@]} -gt 0 ]]; then
+      planning_ok "${#COMPLETE[@]} plan(s) ready to archive:"
+      for s in "${COMPLETE[@]}"; do echo "    bash scripts/archive-plan.sh $s"; done
+    fi
+    ;;
+esac

package/skills/persistent-planning/SKILL.md

@@ -160,6 +160,16 @@ Create this file FIRST for any complex task:
 - [ ] Phase 2: Research/gather information
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
+- [ ] Phase 5: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 6: Documentation pass -- create/update/deprecate docs (MANDATORY)
+
+> Phases 5 and 6 are mandatory and MUST stay the last two phases of this plan.
+> Insert new work above them; never after. Renumber them if you add phases.
+>
+> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **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.
+>   If hit-em-with-the-docs is installed, use it for this pass.
 
 ## Key Questions
 1. [Question to answer]
@@ -217,17 +227,29 @@ Large outputs go to files, not context. Keep only paths in working memory.
 ### 5. Log All Errors
 Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.
 
-### 6. Easy Cleanup
-When a task is complete, delete the task directory:
-```bash
-rm -rf .planning/[task-name]/
-```
+### 6. Archive on Completion, Don't Delete
+A plan is **complete** when every checkbox in it is checked (or its top-level
+artifact declares `status: done`). Completion is derived from the artifacts, so
+checking the last box IS the completion signal -- there is no separate state to
+update and no way for it to drift.
 
-Or clean up everything:
+When a plan is complete, archive it rather than deleting it:
 ```bash
-rm -rf .planning/
+/plan-status                  # which plans are COMPLETE?
+/archive-plan [task-name]     # -> .planning/.archive/[task-name]/
 ```
 
+Archiving moves the plan to the gitignored `.planning/.archive/` and stamps it
+`status: archived` + `archived_on`. The active `.planning/` tree then shows only
+live work. Nothing is destroyed -- restore with
+`mv .planning/.archive/[task-name] .planning/[task-name]`.
+
+The SessionStart hook checks for complete-but-unarchived plans and says so at the
+top of the session, so a finished plan gets retired instead of rediscovered.
+
+Deleting is still available (`rm -rf .planning/[task-name]/`) but throws away the
+record of what was done and why. Prefer the archive.
+
 ## When to Use This Pattern
 
 **Use 3-file pattern for:**
@@ -254,14 +276,17 @@ rm -rf .planning/
 | Overwrite previous plans | Use `/start-planning` (auto-creates unique task dir) |
 | Start executing immediately | Run `/start-planning "task name"` FIRST |
 | Switch tasks without saving | Update task_plan.md before switching |
+| `rm -rf` a finished plan | `/archive-plan <slug>` -- keeps the record, clears the tree |
+| Leave finished plans in `.planning/` | Archive them; the active tree should show only live work |
+| Track completion in your head or in chat | Check the boxes -- the artifact is the status |
 
 ## Advanced Patterns
 
-See [reference.md](../docs/reference.md) for:
+See [Manus Context Engineering Principles](../../.documentation/architecture/context-engineering-principles.md) for:
 - Attention manipulation techniques
 - Error recovery patterns
 - Context optimization principles
 
-See [examples.md](../docs/examples.md) for:
+See [Worked Examples](../../.documentation/quickstart/examples.md) for:
 - Real task examples
 - Complex workflow patterns