@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,204 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0] - 2026-09-04
+
+### Changed — only completed plans are gitignored (#15)
+
+Both init scripts blanket-ignored the entire `.planning/` tree, a v1.0.0 behavior
+(`fb35f19`) that 3.1.0 implicitly reversed and never removed. `archive-plan.sh` had
+already decided only completed plans are local history, and four shipped docs —
+`SKILL.md`, `lg-mode.md` (twice), `README.md` — described `.planning/.archive/` as *the*
+gitignored path. The code did the opposite.
+
+In lg mode the contradiction was sharpest: that mode is selected because ≥2 git authors
+exist, plans are what subagents read via the planning MCP, and the first thing
+`init-phase.sh` did was guarantee no teammate would ever receive them. The blanket entry
+also suppressed `archive-plan.sh`'s narrow one — its first guard returns early when the
+whole tree is ignored — so the narrow entry could never appear in a repo where
+`/start-planning` had run, which is every repo.
+
+- **Active plans are tracked; only `.planning/.archive/` is ignored.** One rule, shared by
+  both lg init and `archive-plan.sh` via `planning_ensure_archive_gitignored`;
+  `init-planning.sh` keeps its own copy since it is deliberately self-contained.
+- **An existing blanket `.planning/` line is never rewritten.** It is the user's file. The
+  tool says once how to narrow it and moves on — otherwise the plans someone is about to
+  create are invisible to their team and nothing tells them.
+- **Init still never creates a `.gitignore`** where none exists. `archive-plan.sh` does,
+  because it has just moved files into `.archive/` and that path must be ignored for the
+  move to mean anything.
+
+sm plan output remains byte-identical. Test suite grows to 119 assertions.
+
+## [3.3.1] - 2026-09-04
+
+### Fixed — a plan that documented markdown could not complete (#14)
+
+`plan-status.sh` had one correct frontmatter reader and three that scanned whole files:
+the checkbox counter, the mandatory gate, and blocked detection. A `notes.md` that merely
+*documented* the contract — which is what notes.md is for — tripped all three:
+
+- a fenced `- [ ]` example inflated the denominator, so the plan could never reach
+  COMPLETE. A quoted `- [x]` cancelled out; a quoted `- [ ]` did not.
+- a fenced `mandatory: true` held the plan open with the box count showing a perfect
+  `1/1` — **no visible signal at all**, and the documented triage steps pointed at a
+  notes file that was pure prose. Regression from #13.
+- a fenced `status: blocked` produced a false `blocked` verdict, masked whenever the plan
+  was otherwise COMPLETE, so it surfaced only intermittently.
+
+`archive-plan.sh` inherited all three through its pre-flight and refused to archive,
+advising `--force` — wrong advice for a miscount.
+
+The fix splits in two, because these are not the same defect:
+
+- **Checkboxes are body content**, so counting is now fence-aware — backtick and tilde
+  fences, tagged or not, indented, closing only on their own character. An unterminated
+  fence swallows the rest of the file: ambiguous content is not counted as outstanding.
+- **`status:` and `mandatory:` are frontmatter fields**, so they are read from the leading
+  `---` block via the existing scoped reader, generalised as `frontmatter_field`. That is
+  strictly stronger than fence-stripping — it also rejects the field appearing in prose or
+  a table.
+
+All consumers — `archive-plan.sh`, `/plan-status`, the SessionStart hook — shell out to
+`plan-status.sh` and needed no change. Test suite grows to 109 assertions.
+
+## [3.3.0] - 2026-09-04
+
+### Fixed — lg task lists were maintained by hand, and the mandatory closers were unenforceable (#12)
+
+`init-task.sh` never wrote to `phase.md` — it referenced the file only in an existence
+check — and `init-atom.sh` never wrote the atom into its task. So **every lg task list was
+maintained by hand**: create six task directories and the phase still reported
+`(no tasks yet)`. The "closers must stay last" rule therefore governed a list no tool
+produced, and the test that claimed to cover it only ever inspected a freshly rendered
+template, which can never be wrong.
+
+- **Creating a child writes it into its parent's list.** `planning_insert_list_item` in
+  `scripts/lib/planning.sh` inserts above the first `MANDATORY` entry — so the closers stay
+  last *by construction* — appends after the last item in sections with no MANDATORY
+  entries, drops the placeholder on first use, is idempotent under `PLANNING_FORCE=1`, and
+  is section-scoped. It anchors on the MANDATORY marker, never on line numbers, because the
+  list is a human-editable surface.
+- **The closers are real task directories now.** `init-phase.sh` scaffolds
+  `validate-success-through-comprehensive-testing/` and
+  `documentation-pass-create-update-deprecate-docs/` with `task.md` (`mandatory: true`,
+  `parallelizable: false`), `notes.md`, `atoms/`, and seeded atoms. Previously the two most
+  important tasks in every plan were the only ones with no artifact a subagent could read.
+- **Placeholders stopped counting as work.** `(no tasks yet …)` and `(no atoms yet …)`
+  shipped as real checkboxes, and `plan-status.sh` counts every box under a plan — a fresh
+  phase with two tasks reported `0/5`, a plan could reach 100% by ticking lines asserting
+  nothing existed, and a finished phase stayed open until someone ticked "no tasks yet".
+  They are italic text now; `plan-status.sh` needed no change.
+- **The completion gate is real.** `plan-status.sh` refuses `COMPLETE` while any
+  `mandatory: true` task's own `status:` is not `done`. Ticking its checkbox is not enough.
+  `archive-plan.sh` inherits this through its existing pre-flight rather than duplicating
+  the rule. Strictly additive: plans with no `mandatory:` frontmatter behave exactly as
+  before.
+
+Test suite grows to 99 assertions, every new one mutating the plan before asserting.
+sm mode verified byte-identical against the pre-change render. New docs:
+`.documentation/architecture/lg-plan-artifact-lifecycle.md`,
+`.documentation/reference/mandatory-frontmatter.md`,
+`.documentation/troubleshooting/plan-never-reads-complete.md`.
+
+## [3.2.0] - 2026-09-04
+
+### Fixed — Stale skill directories run frozen code (#10)
+
+A consumer repo could run a **pre-3.1.0 copy** of the skill indefinitely while the update
+check reported the current version — no nudge, no warning, exit 0 everywhere. Plans
+generated that way silently omitted the mandatory validate and documentation phases and
+the entire `## On Completion` archive block: precisely the guarantees 3.1.0 was released
+to make.
+
+**Cause.** v1's `persistent-planning install` (removed in 2.0.0) *copied*
+`skills/persistent-planning/` into `.claude/skills/`. The v2+ linker only symlinks, and
+when it finds a real directory at the destination it warns and skips — permanently. So
+`installedVersion()` reported the plugin's version while `/start-planning` executed the
+skill dir's frozen copy. Two artifacts, nothing reconciling them. (The linker was never
+copying, as first reported; it was refusing to reclaim what v1 left behind.)
+
+- **Reclaim instead of skip** — `scripts/lib/skill-link.js` renames a real directory to
+  `<name>.bak-<ISO8601>` before the runtime's linker runs, leaving a clean destination it
+  then symlinks normally. Nothing is ever deleted; a failed rename falls through to the
+  old skip but says so loudly and names the fix. Idempotent — a healthy symlink is left
+  alone, so a second run makes no second backup. Opt out with
+  `PERSISTENT_PLANNING_NO_RECLAIM=1`.
+- **The drift is detectable now.** The primary signal is structural: a real directory at
+  `.claude/skills/<name>` is *always* drift, because nothing in the current system creates
+  one. A `.version` marker beside `SKILL.md` is the secondary signal — how far behind a
+  drifted copy is, and the only signal available where symlinks are impossible. Only
+  healthy symlinks are stamped; stamping a stale copy would mark it current.
+- **SessionStart reports it**, naming the path, the running vs installed version, the
+  user-visible consequence, and `npx persistent-planning relink`. Merged into the existing
+  single JSON response; fails open; silent under `updatePolicy: off`.
+- **SessionStart repairs it under `updatePolicy: auto`**, once per plugin version. This is
+  the part that reaches the installs that are actually broken: a marketplace install has
+  no `node_modules` in the plugin cache and **never runs npm postinstall**, so a fix
+  shipped only through postinstall would reach nobody affected. The hook is the one thing
+  that runs every session in that shape. `nudge` warns without touching the filesystem;
+  `off` does nothing at all.
+- **No more clean exits for no-ops.** `update` with no managed install exits 1 and lists
+  every path probed, instead of printing `(not installed)` twice and exiting 0. `relink`
+  gained `CLAUDE_PLUGIN_ROOT/scripts/` and self-package probes — it previously could not
+  run at all in a marketplace-only install, the shape that needs it most — and no longer
+  swallows the linker's exit code.
+
+Test suite grows to 74 assertions, including a marketplace-shaped fixture with no
+`node_modules`. New docs: `.documentation/troubleshooting/stale-skill-dir-drift.md`,
+`.documentation/architecture/skill-linking-and-reclaim.md`,
+`.documentation/reference/skill-version-marker.md`,
+`.documentation/procedures/plugin-update-delivery.md`.
+
+## [3.1.0] - 2026-08-31
+
+### Added — Status tracking and completion archive (#4)
+
+Plans now report their own completion, and completed plans get retired out of the active tree.
+
+**Completion is derived, not declared.** A plan is COMPLETE when every checkbox under it is checked, or when its top-level artifact (`phase.md` / `task_plan.md` / `task.md`) declares `status: done`. Nothing has to be remembered or kept in sync — checking the last box *is* the signal. Combined with the mandatory closing phases above, a plan cannot read COMPLETE until its work has been tested and documented.
+
+- `scripts/plan-status.sh` — the single implementation of the scan. Default output is a table (`in progress` / `blocked` / `COMPLETE` / `empty` / `archived` with a checked/total count); `--complete` prints one complete slug per line; `--nudge` prints a one-line notice or nothing.
+- `scripts/archive-plan.sh` — moves `.planning/<slug>/` to `.planning/.archive/<slug>/`, ensures that path is gitignored, and stamps the top-level artifact `status: archived` + `archived_on` (or a dated footer for sm plans without frontmatter). Prefers `git mv` when the plan is tracked. Refuses incomplete plans unless `--force`; also supports `--all-complete` and `--dry-run`. Nothing is ever deleted.
+- `hooks/session-start.js` — now surfaces complete-but-unarchived plans in the session's context. It merges the notice into the runtime's single `SessionStart` response by intercepting that one stdout write, since the runtime exposes no append hook and a second response line would be invalid; it fails open, so the update check is unaffected if the payload isn't the expected shape.
+- `/plan-status` and `/archive-plan` slash commands.
+- Both plan templates gained an `## On Completion` section stating the rule and the archive command, so an agent reading only the plan still learns the protocol.
+
+`.planning/.archive/` is gitignored on purpose: a completed plan is local history. Anything worth sharing gets promoted into a real doc by the mandatory documentation phase.
+
+Test suite grows to 42 assertions. New doc: `.documentation/procedures/plan-completion-and-archive.md`.
+
+### Added — Mandatory closing phases (#5)
+
+Every plan now ends with the same two units of work, seeded by the templates so an agent never has to remember them:
+
+1. **Validate success through comprehensive testing**
+2. **Documentation pass — create/update/deprecate docs**
+
+- **sm mode**: `task_plan.md` seeds 6 phases instead of 4; phases 5 and 6 are the mandatory pair, marked `MANDATORY`.
+- **lg mode**: `templates/lg/phase.md` seeds the pair as the last two task checkboxes. A phase cannot be marked `done` until both are `done`, and neither may be `parallelizable`.
+- Both templates carry the ordering rule inline: new work is inserted **above** the pair, never after it.
+
+### Added — Test suite
+
+`tests/run.sh` — plain bash asserts (no framework), wired to `npm test`. 21 assertions covering sm/lg init, the closing-phase ordering, slug conversion, template placeholder substitution, atom sequence auto-increment, idempotent re-runs, and the lg-mode guard on `init-phase.sh`.
+
+### Changed — Documentation moved to hit-em-with-the-docs
+
+`docs/` is gone; documentation now lives in a hewtd-managed `.documentation/` tree, split by domain:
+
+| Was | Now |
+|---|---|
+| `docs/lg-mode.md` | `.documentation/architecture/lg-mode.md` |
+| `docs/reference.md` | `.documentation/architecture/context-engineering-principles.md` |
+| `docs/atom-granularity.md` | `.documentation/standards/atom-granularity.md` |
+| `docs/workspace-json.md` | `.documentation/reference/workspace-json.md` |
+| `docs/examples.md` | `.documentation/quickstart/examples.md` |
+
+New docs: `.documentation/standards/mandatory-closing-phases.md` and `.documentation/testing/test-suite.md`. A custom `reference` domain is registered in `.claude/hit-em-with-the-docs.json`. The npm `files` array now ships `.documentation/` in place of `docs/`.
+
+Links in older CHANGELOG entries still point at the old `docs/` paths; they are left as written, since they describe the layout as it was at those releases.
+
 ## [3.0.1] - 2026-05-08
 
 ### Fixed

package/README.md

@@ -7,6 +7,13 @@ A Claude Code plugin that uses on-disk markdown files as "working memory" for pl
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://github.com/TheGlitchKing/persistent-planning)
 
+> [!NOTE]
+> **New in 3.0.0 — sm/lg modes + layered planning.** Solo work and quick spikes still get the original single-task flow (now called **sm mode**). Multi-week projects with multiple contributors get a new **lg mode** with layered phase / task / atom / notes artifacts that subagents can pick up via [semantic-memory](https://github.com/TheGlitchKing/semantic-sidekick)'s MCP. Mode is auto-detected from 90-day git author count; sm preserved bit-for-bit from v2. See [`.documentation/architecture/lg-mode.md`](./.documentation/architecture/lg-mode.md) for the layered model + [`.documentation/standards/atom-granularity.md`](./.documentation/standards/atom-granularity.md) for the inline-checkbox-vs-standalone-atom decision rule.
+>
+> Two new slash commands ship in 3.0: `/start-task "Name" --parent <phase>` and `/start-atom "Name" --parent <task>` (lg-mode only). `/start-planning` now dispatches to either flow based on detected mode (with `--mode sm|lg` override).
+>
+> All lg-mode artifacts carry [HEWTD](https://github.com/TheGlitchKing/hit-em-with-the-docs) 2.2.0+ frontmatter (`tier: "plan"`).
+
 ---
 
 ## Why This Plugin?
@@ -161,6 +168,8 @@ persistent-planning/
 │   └── persistent-planning.js  # CLI (update/policy/status/relink)
 ├── commands/
 │   ├── start-planning.md    # /start-planning slash command
+│   ├── plan-status.md       # /plan-status
+│   ├── archive-plan.md      # /archive-plan
 │   ├── update.md            # /persistent-planning:update
 │   ├── policy.md            # /persistent-planning:policy
 │   ├── status.md            # /persistent-planning:status
@@ -169,26 +178,77 @@ persistent-planning/
 │   ├── hooks.json           # SessionStart hook manifest
 │   └── session-start.js     # Runtime-delegated hook
 ├── scripts/
+│   ├── init-*.sh            # planning artifact creation (sm + lg)
+│   ├── plan-status.sh       # completion scan (single implementation)
+│   ├── archive-plan.sh      # retire a completed plan
 │   └── link-skills.js       # Postinstall (runtime-delegated)
 ├── skills/
 │   └── persistent-planning/
 │       └── SKILL.md         # Core skill definition
-├── docs/
-│   ├── reference.md         # Manus context engineering principles
-│   └── examples.md          # Worked examples
+├── templates/lg/            # phase / task / atom / notes templates (lg mode)
+├── tests/
+│   └── run.sh               # bash smoke tests (npm test)
+├── .documentation/          # hewtd-managed docs — start at INDEX.md
+│   ├── architecture/        # lg-mode layer model, context-engineering rationale
+│   ├── standards/           # mandatory closing phases, atom granularity
+│   ├── reference/           # workspace.json schema
+│   ├── testing/             # test suite guide
+│   └── quickstart/          # worked examples
 ├── README.md
 ├── LICENSE
 └── CHANGELOG.md
 ```
 
+## Status tracking and archive
+
+A plan is **complete** when every checkbox in it is checked (or its top-level artifact says `status: done`). Completion is derived from the artifacts, so it cannot drift from what the plan actually says — checking the last box *is* the signal.
+
+```
+/plan-status                  # what's in progress, blocked, or complete
+/archive-plan <slug>          # retire a completed plan
+/archive-plan --all-complete  # retire all of them
+```
+
+Archiving moves `.planning/<slug>/` to the gitignored `.planning/.archive/<slug>/` and stamps it `status: archived` + `archived_on`. Nothing is deleted — restore by moving the directory back out.
+
+The SessionStart hook mentions complete-but-unarchived plans at the top of the next session, so a finished plan gets retired instead of rediscovered. Full protocol: [Plan Completion and Archive](./.documentation/procedures/plan-completion-and-archive.md).
+
+## Documentation
+
+Docs are managed by [hit-em-with-the-docs](https://github.com/TheGlitchKing/hit-em-with-the-docs) and live in `.documentation/`, split by domain. Start at [`.documentation/INDEX.md`](./.documentation/INDEX.md).
+
+| Doc | What it covers |
+|---|---|
+| [Lg-Mode Layered Planning Guide](./.documentation/architecture/lg-mode.md) | phase / task / atom / notes layer model, scheduling, subagent contract |
+| [Manus Context Engineering Principles](./.documentation/architecture/context-engineering-principles.md) | the rationale the whole plugin is built on |
+| [Mandatory Closing Phases](./.documentation/standards/mandatory-closing-phases.md) | the two phases every plan must end with, and why |
+| [Atom Granularity](./.documentation/standards/atom-granularity.md) | inline checkbox vs. standalone atom file |
+| [workspace.json Reference](./.documentation/reference/workspace-json.md) | mode tracker schema |
+| [Plan Completion and Archive](./.documentation/procedures/plan-completion-and-archive.md) | how completion is detected and how plans are retired |
+| [Test Suite](./.documentation/testing/test-suite.md) | what `npm test` covers, how to add a case |
+| [Worked Examples](./.documentation/quickstart/examples.md) | end-to-end planning walkthroughs |
+
+`INDEX.md` and `REGISTRY.md` are generated — change the documents, then run `npx hewtd maintain --quick`.
+
+## Testing
+
+```bash
+npm test          # bash smoke tests over the init scripts (tests/run.sh)
+```
+
 ## Cleanup
 
+Prefer archiving — it keeps the record of what was done:
+
 ```bash
-# Remove a single task's planning files
-rm -rf .planning/[task-name]/
+/archive-plan [task-name]
+```
 
-# Remove all planning files
-rm -rf .planning/
+Hard deletion still works, but throws that record away:
+
+```bash
+rm -rf .planning/[task-name]/   # one plan
+rm -rf .planning/               # everything, archive included
 ```
 
 ## Acknowledgments

package/bin/persistent-planning.js

@@ -5,25 +5,49 @@ import { registerUpdateCommands } from "@theglitchking/claude-plugin-runtime";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const require_ = createRequire(import.meta.url);
 const { version } = require_("../package.json");
 
 const PKG = "@theglitchking/persistent-planning";
 
+// Where the linker can live, most specific first. The third probe matters: in a
+// marketplace-only install there is no node_modules and cwd is the consumer repo,
+// so the first two both miss and relink -- the one command that repairs a stale
+// skill dir -- could not run at all in exactly the shape that needs it.
+function linkerCandidates(cwd) {
+  const out = [
+    join(cwd, "node_modules", "@theglitchking", "persistent-planning", "scripts", "link-skills.js"),
+    resolve(process.cwd(), "scripts", "link-skills.js"),
+  ];
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    out.push(join(process.env.CLAUDE_PLUGIN_ROOT, "scripts", "link-skills.js"));
+  }
+  // The package this CLI is itself running from — correct for `npx <pkg> relink`.
+  out.push(resolve(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "link-skills.js"));
+  return out;
+}
+
 function runRelink(cwd) {
-  const linker = join(cwd, "node_modules", "@theglitchking", "persistent-planning", "scripts", "link-skills.js");
-  const script = existsSync(linker) ? linker : resolve(process.cwd(), "scripts", "link-skills.js");
-  if (!existsSync(script)) {
-    console.error("link-skills.js not found — is the package installed?");
+  const candidates = linkerCandidates(cwd);
+  const script = candidates.find((p) => existsSync(p));
+  if (!script) {
+    // ponytail: never exit 0 after doing nothing — a clean success for a no-op is
+    // how the stale-skill-dir bug stayed invisible for five months (issue #10).
+    console.error("relink failed: link-skills.js not found. Looked in:");
+    for (const p of candidates) console.error(`  ${p}`);
+    console.error("\nIs @theglitchking/persistent-planning installed, or CLAUDE_PLUGIN_ROOT set?");
+    process.exitCode = 1;
     return;
   }
-  spawnSync(process.execPath, [script], {
+  const r = spawnSync(process.execPath, [script], {
     cwd,
     env: { ...process.env, INIT_CWD: cwd },
     stdio: "inherit",
   });
+  if (r.status !== 0) process.exitCode = r.status ?? 1;
 }
 
 program
@@ -31,6 +55,32 @@ program
   .description("Persistent markdown-based planning for Claude Code.")
   .version(version);
 
+// The runtime's `update` resolves the installed version, finds none in a
+// marketplace-only install, prints "Current: (not installed) / Now: (not installed)"
+// and exits 0 -- a clean success for a no-op. Fail before it gets that far, and say
+// where we looked. Same defect as runRelink's missing third probe (issue #10, fix #4).
+// Deliberately NOT including the package this CLI runs from: under
+// `npx --no @theglitchking/persistent-planning update` that copy always exists, which
+// is what let the original bug report see a clean exit 0 for a no-op. Only a *managed*
+// install -- a project dependency or a marketplace plugin root -- is updatable.
+function installCandidates(cwd) {
+  const out = [join(cwd, "node_modules", "@theglitchking", "persistent-planning", "package.json")];
+  if (process.env.CLAUDE_PLUGIN_ROOT) out.push(join(process.env.CLAUDE_PLUGIN_ROOT, "package.json"));
+  return out;
+}
+
+program.hook("preAction", (_thisCmd, actionCmd) => {
+  if (actionCmd.name() !== "update") return;
+  const candidates = installCandidates(process.cwd());
+  if (candidates.some((p) => existsSync(p))) return;
+  console.error("update failed: no managed install of @theglitchking/persistent-planning found.");
+  console.error("Looked in:");
+  for (const p of candidates) console.error(`  ${p}`);
+  console.error("\nInstall it with `npm i -D @theglitchking/persistent-planning`,");
+  console.error("or update the marketplace plugin with `/plugin` inside Claude Code.");
+  process.exit(1);
+});
+
 registerUpdateCommands(program, {
   packageName: PKG,
   pluginName: "persistent-planning",

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