@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/scripts/lib/planning.sh

@@ -159,3 +159,125 @@ planning_render_and_log() {
       ;;
   esac
 }
+
+###############################################################################
+# List maintenance
+#
+# A phase's task list and a task's atom list are stored markdown checkboxes,
+# not derived views — plan-status.sh counts them, and humans edit them. So the
+# init scripts have to write them. Before this existed, init-task.sh never
+# touched phase.md at all and every list was maintained by hand (issue #12).
+###############################################################################
+
+# planning_insert_list_item <file> <section-heading> <line>
+#
+# Inserts <line> into the checkbox list under <section-heading> in <file>:
+#   - above the first item marked MANDATORY, so closers stay last by
+#     construction rather than by anyone remembering;
+#   - after the last item when the section has no MANDATORY entries;
+#   - dropping a "(no ... yet" placeholder, checkbox or italic, including its
+#     continuation lines, the first time a real item lands.
+#
+# Idempotent: an identical line already in the section is left alone, so
+# re-running with PLANNING_FORCE=1 cannot double-insert.
+#
+# Anchors on the MANDATORY marker, never on line numbers — the list is a
+# human-editable surface and positions do not survive contact with editing.
+planning_insert_list_item() {
+  local file="$1" heading="$2" line="$3" tmp
+  [[ -f "$file" ]] || return 0
+
+  tmp="${file}.pp-tmp.$$"
+  awk -v heading="$heading" -v newline="$line" '
+    { L[NR] = $0; if ($0 == newline) seen = 1 }
+    END {
+      if (seen) { for (i = 1; i <= NR; i++) print L[i]; exit }
+
+      # Section bounds: heading .. next "## " heading (or EOF).
+      s = 0
+      for (i = 1; i <= NR; i++) {
+        if (L[i] == heading) { s = i; continue }
+        if (s && L[i] ~ /^## /) { e = i - 1; break }
+      }
+      if (!s) { for (i = 1; i <= NR; i++) print L[i]; exit }
+      if (!e) e = NR
+
+      # Drop the "(no ... yet" placeholder and its indented continuation lines.
+      for (i = s; i <= e; i++) {
+        if (L[i] ~ /^- \[[ xX]\] \(no / || L[i] ~ /^_\(no /) {
+          drop[i] = 1
+          for (j = i + 1; j <= e; j++) {
+            if (L[j] ~ /^[[:space:]]+[^[:space:]]/) drop[j] = 1; else break
+          }
+        }
+      }
+
+      # Anchor: first MANDATORY item, else after the last surviving list item,
+      # else at the end of the section.
+      at = 0
+      for (i = s; i <= e; i++)
+        if (!drop[i] && L[i] ~ /^- \[[ xX]\] .*MANDATORY/) { at = i; break }
+      if (!at) {
+        last = 0
+        for (i = s; i <= e; i++) if (!drop[i] && L[i] ~ /^- \[[ xX]\] /) last = i
+        if (last) {
+          for (j = last + 1; j <= e; j++) {
+            if (L[j] ~ /^[[:space:]]+[^[:space:]]/) last = j; else break
+          }
+          at = last + 1
+        }
+      }
+      if (!at) { at = e + 1; while (at > s && L[at-1] == "") at-- }
+
+      for (i = 1; i <= NR; i++) {
+        if (i == at) print newline
+        if (!drop[i]) print L[i]
+      }
+      if (at == NR + 1) print newline
+    }
+  ' "$file" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+
+  if [[ -s "$tmp" ]]; then mv "$tmp" "$file"; else rm -f "$tmp"; fi
+}
+
+###############################################################################
+# .gitignore scope
+#
+# Only completed plans are local history. Active plans are the artifact a team
+# coordinates around and that subagents read via the planning MCP — in lg mode,
+# selected precisely because there IS a team, ignoring them defeats the point.
+#
+# v1.0.0 blanket-ignored .planning/; 3.1.0's archive-plan.sh introduced the narrow
+# entry with the reasoning above but never displaced the old rule, leaving four
+# shipped docs describing a behavior the code did not have (issue #15).
+###############################################################################
+
+# planning_ensure_archive_gitignored <repo-root> [create-if-missing]
+#
+# Adds `.planning/.archive/` when absent. Never rewrites an existing blanket
+# `.planning/` entry — that is the user's file and their call — but says once how to
+# narrow it, because otherwise the plans they are about to create are invisible to
+# everyone else and nothing tells them.
+#
+# The init scripts pass no second argument: creating a .gitignore in a repo that has
+# none is not their business. archive-plan.sh passes 1 — it has just moved files into
+# .archive/ and that path has to be ignored for the move to mean anything.
+planning_ensure_archive_gitignored() {
+  local gitignore="${1}/.gitignore" create="${2:-}"
+  if [[ ! -f "$gitignore" ]]; then
+    [[ "$create" == "1" ]] || return 0
+    touch "$gitignore" 2>/dev/null || return 0
+  fi
+
+  if grep -qE '^\.planning/?$' "$gitignore" 2>/dev/null; then
+    planning_warn ".gitignore ignores all of .planning/ — plans will not be shared."
+    echo "           Active plans are what teammates and subagents read. To share them," >&2
+    echo "           replace the '.planning/' line with '.planning/.archive/'." >&2
+    return 0
+  fi
+
+  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 (active plans stay shareable)"
+}

package/scripts/lib/skill-link.js

@@ -0,0 +1,177 @@
+// Skill-dir reclaim + drift detection.
+//
+// Why this exists: v1's `persistent-planning install` (removed in v2.0.0) COPIED
+// skills/persistent-planning/ into a consumer's .claude/skills/. The v2+ linker in
+// claude-plugin-runtime only symlinks, and when it finds a real directory at the
+// destination it warns and skips — forever. So v1 leftovers keep executing a frozen
+// copy while the update check reports the (correct, current) plugin version. Two
+// artifacts, nothing reconciling them.
+//
+// The fix is to reclaim the real directory BEFORE the runtime's linker runs: rename
+// it aside, which leaves a clean destination the linker then symlinks normally. That
+// needs no upstream change — see the phase notes for why this lives here for now.
+//
+// Nothing here ever deletes. A reclaimed directory is renamed to
+// <name>.bak-<ISO8601>, and a failure to rename falls through to the old skip.
+
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, renameSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+
+export const ENV_PREFIX = "PERSISTENT_PLANNING";
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+/** Skill directory names shipped by this package. Mirrors the runtime's filter. */
+export function packagedSkillNames(packageRoot, skillsSubdir = "skills") {
+  const dir = join(packageRoot, skillsSubdir);
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.endsWith("-workspace"))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * What is actually sitting at .claude/skills/<name>, and is it ours?
+ *
+ * Returns one of:
+ *   absent          — nothing there; the linker will create the symlink
+ *   symlink-ok      — symlink pointing at this package's copy; healthy
+ *   symlink-foreign — symlink pointing somewhere else; another install owns it
+ *   real-dir        — a real directory; v1 debris or a hand-managed copy. This is
+ *                     the drift state: nothing in the current system creates one.
+ */
+export function describeSkill(consumerRoot, packageRoot, name, skillsSubdir = "skills") {
+  const dest = join(consumerRoot, ".claude", "skills", name);
+  const src = join(packageRoot, skillsSubdir, name);
+  const st = lstatSafe(dest);
+  if (!st) return { name, dest, src, state: "absent" };
+  if (st.isSymbolicLink()) {
+    let target = null;
+    try { target = readlinkSync(dest); } catch { /* unreadable link */ }
+    const expected = relative(dirname(dest), src);
+    if (target === expected) return { name, dest, src, state: "symlink-ok", target };
+    // A different-but-equivalent path still resolves to us; treat that as healthy.
+    try {
+      if (target && resolve(dirname(dest), target) === resolve(src)) {
+        return { name, dest, src, state: "symlink-ok", target };
+      }
+    } catch { /* fall through */ }
+    return { name, dest, src, state: "symlink-foreign", target };
+  }
+  return { name, dest, src, state: "real-dir" };
+}
+
+/** Every packaged skill's current state in a consumer repo. */
+export function surveySkills(consumerRoot, packageRoot, skillsSubdir = "skills") {
+  return packagedSkillNames(packageRoot, skillsSubdir)
+    .map((n) => describeSkill(consumerRoot, packageRoot, n, skillsSubdir));
+}
+
+function backupPath(dest) {
+  // ISO8601, filesystem-safe. Collisions only within the same second on the same
+  // dir, which a suffix resolves.
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  let candidate = `${dest}.bak-${stamp}`;
+  let n = 1;
+  while (existsSync(candidate)) candidate = `${dest}.bak-${stamp}-${n++}`;
+  return candidate;
+}
+
+/**
+ * Rename any real directory at .claude/skills/<name> aside so the linker can symlink.
+ *
+ * Idempotent: a healthy symlink is left completely alone, so a second run is a no-op
+ * and produces no second backup.
+ *
+ * Returns { reclaimed: [{name, from, to}], failed: [{name, dest, error}], healthy: n }.
+ */
+export function reclaimStaleSkillDirs(consumerRoot, packageRoot, opts = {}) {
+  const { skillsSubdir = "skills", log = () => {} } = opts;
+  const result = { reclaimed: [], failed: [], healthy: 0 };
+
+  if (process.env[`${ENV_PREFIX}_NO_RECLAIM`] === "1") {
+    log(`[persistent-planning] ${ENV_PREFIX}_NO_RECLAIM=1 — leaving existing skill dirs alone.`);
+    return result;
+  }
+
+  for (const info of surveySkills(consumerRoot, packageRoot, skillsSubdir)) {
+    if (info.state !== "real-dir") {
+      if (info.state === "symlink-ok") result.healthy++;
+      continue;
+    }
+    const to = backupPath(info.dest);
+    try {
+      renameSync(info.dest, to);
+      result.reclaimed.push({ name: info.name, from: info.dest, to });
+      log(`[persistent-planning] reclaimed stale skill dir ${info.dest} -> ${to}`);
+    } catch (err) {
+      // ponytail: never rm -rf a directory a user may have hand-edited. If we cannot
+      // move it, say so loudly and leave it — the old skip, but no longer silent.
+      result.failed.push({ name: info.name, dest: info.dest, error: err?.message || String(err) });
+      log(
+        `[persistent-planning] WARNING: ${info.dest} is a real directory, not a symlink,\n` +
+        `  so it will keep running a frozen copy of the skill. Could not move it aside:\n` +
+        `  ${err?.message || err}\n` +
+        `  Move or remove it, then run:  npx persistent-planning relink`
+      );
+    }
+  }
+  return result;
+}
+
+/** Skills still drifted after a reclaim attempt — what SessionStart should warn about. */
+export function driftedSkills(consumerRoot, packageRoot, skillsSubdir = "skills") {
+  return surveySkills(consumerRoot, packageRoot, skillsSubdir)
+    .filter((s) => s.state === "real-dir" || s.state === "symlink-foreign");
+}
+
+// ── Version marker ──────────────────────────────────────────────────────────
+//
+// The drift that started issue #10 was invisible because the update check read the
+// plugin's version while /start-planning executed the skill dir's copy — same number,
+// different artifact. The primary signal is structural (describeSkill: a real dir is
+// always suspect, because nothing in the current system creates one). This marker is
+// the secondary signal: it says how far behind a drifted copy actually is, and it is
+// the only signal available on install shapes where a symlink is impossible.
+
+export const MARKER = ".version";
+
+/** Version of the skill copy that would actually execute, or null. */
+export function readSkillVersion(consumerRoot, name) {
+  try {
+    const raw = readFileSync(join(consumerRoot, ".claude", "skills", name, MARKER), "utf8");
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stamp linked skills with the version they came from.
+ *
+ * Only ever stamps a healthy symlink — never a real directory. Stamping a real dir
+ * would mark stale code as current and defeat the whole check. Best-effort: a
+ * read-only package dir (npm cache, plugin cache) just leaves the marker absent,
+ * which the drift check treats as "unknown", not "fine".
+ */
+export function writeVersionMarkers(consumerRoot, packageRoot, version, opts = {}) {
+  const { skillsSubdir = "skills" } = opts;
+  if (!version) return { stamped: [], skipped: [] };
+  const out = { stamped: [], skipped: [] };
+  for (const info of surveySkills(consumerRoot, packageRoot, skillsSubdir)) {
+    if (info.state !== "symlink-ok") { out.skipped.push(info.name); continue; }
+    try {
+      writeFileSync(join(info.dest, MARKER), `${version}\n`, "utf8");
+      out.stamped.push(info.name);
+    } catch {
+      out.skipped.push(info.name);
+    }
+  }
+  return out;
+}

package/scripts/link-skills.js

@@ -1,12 +1,40 @@
 #!/usr/bin/env node
 // Postinstall — delegates to @theglitchking/claude-plugin-runtime.
 // See https://github.com/TheGlitchKing/claude-plugin-runtime/blob/main/docs/PLUGIN_AUTHORING_SCAFFOLD.md
+//
+// One thing runs before the delegation: reclaimStaleSkillDirs(). The runtime's linker
+// skips a destination that is a real directory rather than a symlink, and skips it
+// forever — so v1 leftovers never heal. Renaming the real dir aside first leaves a
+// clean destination the runtime then links normally.
 
 import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reclaimStaleSkillDirs, writeVersionMarkers, ENV_PREFIX } from "./lib/skill-link.js";
+import { createRequire } from "node:module";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const consumerRoot = process.env.INIT_CWD || process.cwd();
+
+try {
+  // Skip when the runtime itself would skip: dev-in-place, or linking disabled.
+  const devInPlace = resolve(consumerRoot) === resolve(packageRoot);
+  if (!devInPlace && process.env[`${ENV_PREFIX}_SKIP_LINK`] !== "1") {
+    const r = reclaimStaleSkillDirs(consumerRoot, packageRoot, {
+      skillsSubdir: "skills",
+      log: (m) => console.log(m),
+    });
+    if (r.reclaimed.length) {
+      console.log(
+        `[persistent-planning] reclaimed ${r.reclaimed.length} stale skill dir(s); ` +
+        `originals kept alongside as .bak-* — delete them once you are satisfied.`
+      );
+    }
+  }
+} catch (err) {
+  // Reclaim is best-effort. A failure here must never block the install.
+  console.warn(`[persistent-planning] skill reclaim skipped: ${err?.message || err}`);
+}
 
 try {
   runPostinstall({
@@ -21,3 +49,13 @@ try {
 } catch (err) {
   console.warn(`[persistent-planning] postinstall failed: ${err?.message || err}`);
 }
+
+try {
+  // Stamp the artifact that actually executes, so drift is detectable at all.
+  // Only healthy symlinks are stamped — never a real dir, which would mark stale
+  // code as current.
+  const { version } = createRequire(import.meta.url)("../package.json");
+  writeVersionMarkers(consumerRoot, packageRoot, version, { skillsSubdir: "skills" });
+} catch {
+  // Marker is a diagnostic aid, not a dependency. Absent is a valid state.
+}

package/scripts/plan-status.sh

@@ -0,0 +1,196 @@
+#!/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_field <file> <key> -> value of `<key>:` inside the leading --- block
+#
+# Scoped to the frontmatter on purpose. Grepping a whole file for a frontmatter field
+# matches it in prose, tables and fenced examples too — a notes.md documenting the
+# contract then reads as an artifact that declares it (issue #14).
+frontmatter_field() {
+  [[ -f "$1" ]] || return
+  awk -v key="$2" '
+    NR==1 && $0 != "---" { exit }
+    NR>1 && $0 == "---" { exit }
+    index($0, key ":") == 1 {
+      sub("^" key ":[[:space:]]*", "")
+      gsub(/["\047]/, "")
+      sub(/[[:space:]]+$/, "")
+      print; exit
+    }' "$1"
+}
+
+# frontmatter_status <file> -> value of `status:` inside the leading --- block
+frontmatter_status() {
+  frontmatter_field "$1" "status"
+}
+
+# Emits "<total> <checked>" for every markdown file under a plan directory.
+#
+# Checkboxes inside fenced code blocks are examples, not work. A plan whose notes.md
+# quotes markdown — which is what notes.md is for — used to have those quoted boxes
+# counted against it, and a quoted `- [ ]` inflates only the denominator, so the plan
+# became permanently uncompletable with no visible reason (issue #14).
+#
+# An unterminated fence swallows the rest of the file. That is the safe direction:
+# ambiguous content is not counted as outstanding work.
+count_boxes() {
+  local total=0 checked=0 f out
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    out=$(awk '
+      # Fence open/close: ``` or ~~~, optionally indented, optional info string.
+      # A fence closes only on the same character.
+      /^[[:space:]]*(```|~~~)/ {
+        line = $0
+        sub(/^[[:space:]]*/, "", line)
+        ch = substr(line, 1, 1)
+        if (!infence) { infence = 1; fencechar = ch }
+        else if (ch == fencechar) { infence = 0 }
+        next
+      }
+      infence { next }
+      /^[[:space:]]*- \[[ xX]\] / { t++ }
+      /^[[:space:]]*- \[[xX]\] /  { c++ }
+      END { print t + 0, c + 0 }
+    ' "$f" 2>/dev/null) || continue
+    total=$((total + ${out%% *}))
+    checked=$((checked + ${out##* }))
+  done < <(find "$1" -type f -name '*.md' 2>/dev/null)
+  echo "$total $checked"
+}
+
+# Files under a plan whose FRONTMATTER declares <key>: <value>.
+frontmatter_files_with() {
+  local dir="$1" key="$2" want="$3" f
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    [[ "$(frontmatter_field "$f" "$key")" == "$want" ]] && echo "$f"
+  done < <(find "$dir" -type f -name '*.md' 2>/dev/null)
+}
+
+# Counts mandatory tasks under a plan that are not yet done.
+#
+# The two closing tasks carry `mandatory: true`. A plan cannot be COMPLETE while one
+# of them is unfinished, however the boxes happen to add up — that gate was stated in
+# the templates and enforced nowhere (issue #12).
+#
+# Additive by design: a plan with no `mandatory: true` artifacts behaves exactly as it
+# did before. Retroactively reopening finished plans would be worse than the bug.
+unfinished_mandatory() {
+  local n=0 f st
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    st=$(frontmatter_status "$f")
+    [[ "$st" == "done" || "$st" == "archived" ]] || n=$((n + 1))
+  done < <(frontmatter_files_with "$1" "mandatory" "true")
+  echo "$n"
+}
+
+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=$(frontmatter_files_with "${plan_path%/}" "status" "blocked" | wc -l | tr -d ' ')
+  pending_mandatory=$(unfinished_mandatory "${plan_path%/}")
+
+  if [[ "$status" == "archived" ]]; then
+    verdict="archived"
+  elif [[ "$status" == "done" ]] || { [[ "$total" -gt 0 ]] && [[ "$checked" -eq "$total" ]]; }; then
+    if [[ "$pending_mandatory" -gt 0 ]]; then
+      # Every box ticked, but a mandatory closer is not done. Not complete.
+      verdict="in progress"
+    else
+      verdict="COMPLETE"
+      COMPLETE+=("$slug")
+    fi
+  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,19 @@ 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 as many docs as needed to capture what was done, where it lives, how to troubleshoot it, etc. etc.. etc.. (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, you MUST use it for this pass --
+>   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
+>   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or
+>   REGISTRY.md; they are generated.
 
 ## Key Questions
 1. [Question to answer]
@@ -217,17 +230,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 +279,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

package/templates/lg/phase.md

@@ -20,7 +20,21 @@ Each task is a bounded deliverable. Tasks default to dependencies-first scheduli
 Tasks with no inter-dependencies can be marked `parallelizable: true` in their frontmatter
 so subagent teams can pick them up concurrently.]
 
-- [ ] (no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)
+_(no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)_
+- [ ] **Validate success through comprehensive testing** (`validate-success-through-comprehensive-testing`) (MANDATORY — second-to-last)
+- [ ] **Documentation pass — create/update/deprecate as many docs as needed to capture what was done, where it lives, how to troubleshoot it, etc. etc.. etc..** (`documentation-pass-create-update-deprecate-docs`) (MANDATORY — last)
+
+> The two mandatory closing tasks above MUST remain the last two tasks of this phase.
+> Add new tasks above them; never after. A phase cannot be marked `done` until both are
+> `done`, and neither may be `parallelizable` — they gate on everything before them.
+>
+> - **Validate success**: prove the phase's work with tests that fail if it breaks.
+> - **Documentation pass**: create/update/deprecate every doc this phase touches —
+>   what it is, where it lives, how to fix it, how to operate it, why it matters.
+>   If hit-em-with-the-docs is installed, you MUST use it for this pass --
+>   `npx hewtd integrate <file> -a` to create, `npx hewtd archive <file>` to retire,
+>   `npx hewtd maintain --quick` to regenerate indexes. Never hand-edit INDEX.md or
+>   REGISTRY.md; they are generated.
 
 ## Decisions Made
 [Phase-level decisions that affect multiple tasks. Format: `**Decision**: rationale`.]
@@ -30,8 +44,13 @@ so subagent teams can pick them up concurrently.]
 
 Status enum: `draft | active | paused | done | archived`
 
-When all tasks are `done`, mark this phase `done`. When archived, this directory and
-its tasks/atoms move to `.planning/archive/PHASE_SLUG_PLACEHOLDER/`.
+When all tasks are `done`, mark this phase `done`. Checking every box in this phase
+IS the completion signal — `/plan-status` reads it straight off the artifacts.
+
+When complete, retire it with `/archive-plan PHASE_SLUG_PLACEHOLDER`: the whole
+directory (tasks and atoms with it) moves to the gitignored
+`.planning/.archive/PHASE_SLUG_PLACEHOLDER/` and the frontmatter above is stamped
+`status: archived` + `archived_on`. Nothing is destroyed.
 
 ---