@theglitchking/persistent-planning 3.0.1 → 3.1.0

package/.documentation/standards/mandatory-closing-phases.md

@@ -0,0 +1,125 @@
+---
+title: Mandatory Closing Phases
+tier: standard
+domains:
+  - standards
+audience:
+  - developers
+tags:
+  - testing
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: The two phases every persistent-planning plan must end with — validate
+  success through comprehensive testing, then a documentation pass — why they
+  exist, how they are seeded, and how to keep them last.
+estimated_read_time: 4 minutes
+word_count: 770
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Mandatory Closing Phases
+
+Every plan this plugin creates ends with the same two units of work, in the same
+order, no exceptions:
+
+1. **Validate success through comprehensive testing**
+2. **Documentation pass — create / update / deprecate docs**
+
+They are seeded into the templates so an agent never has to remember them, and
+they are marked `MANDATORY` in the artifact itself so an agent re-reading the
+plan mid-run can see they are not optional filler.
+
+## Why they exist
+
+A plan that stops at "execute/build" produces work nobody has proven and nobody
+can operate. Both failures are invisible at the moment they happen and expensive
+later:
+
+- **Without the validation phase**, "done" means "the agent believes it works."
+  The next change silently breaks it, because nothing fails when it does.
+- **Without the documentation phase**, the knowledge of what changed lives only
+  in a chat transcript that is discarded at the end of the session. The next
+  contributor — human or agent — re-derives it from source, or gets it wrong.
+
+Putting them *in the template* rather than in a style guide is the whole point.
+Guidance in a style guide is read once; a checkbox in the plan the agent re-reads
+before every decision stays in the attention window. This is the same
+filesystem-as-working-memory reasoning behind the plan artifacts themselves — see
+[Manus Context Engineering Principles](../architecture/context-engineering-principles.md).
+
+## Where they live
+
+| Mode | Artifact | Section | Seeded as |
+|---|---|---|---|
+| sm | `.planning/<slug>/task_plan.md` | `## Phases` | Phase 5 and Phase 6 of 6 |
+| lg | `.planning/<phase-slug>/phase.md` | `## Tasks` | The last two task checkboxes |
+
+In **sm mode** the plan is a single file, so the two phases are literally the
+last two checkboxes under `## Phases`.
+
+In **lg mode** the plan is a tree (phase → task → atom, see
+[Lg-Mode Layered Planning Guide](../architecture/lg-mode.md)). The closing pair is seeded at the
+**phase** level, because a phase is the strategic unit that actually ships. Every
+phase validates its own work and documents its own work; a phase cannot be marked
+`done` until both closing tasks are `done`. Individual tasks and atoms do **not**
+each carry the pair — that would produce a documentation pass per atom, which is
+noise.
+
+Neither closing task may be marked `parallelizable: true`. They gate on
+everything before them by definition.
+
+## The ordering rule
+
+> New work is inserted **above** the closing pair, never after it.
+
+An agent adding phases to an sm plan renumbers the closing pair so they remain
+last (Phase 5/6 becomes Phase 7/8, and so on). An agent adding tasks to an lg
+phase appends them above the two closing checkboxes. The template states this
+rule inline, directly beneath the checkboxes, so it survives the plan being read
+in isolation without this document.
+
+The rule is mechanical rather than a judgment call precisely so that it is
+enforceable — see [how it is tested](../testing/test-suite.md).
+
+## What each phase actually requires
+
+**Validate success through comprehensive testing.** Prove the work with a check
+that *fails if the change breaks*. A test that passes both before and after the
+change validates nothing. For this repository that means adding assertions to
+`tests/run.sh`; for a consuming project it means whatever that project's test
+command is. Mutation-check the assertion at least once: break the thing on
+purpose, confirm the test goes red, put it back.
+
+**Documentation pass.** Create, update, or deprecate every doc the change
+touches, answering: what it is, where it lives, how to fix it, how to operate it,
+and why it matters. Deprecation counts — a doc made wrong by the change is worse
+than a missing one. If [hit-em-with-the-docs](https://github.com/TheGlitchKing/hit-em-with-the-docs)
+is installed, this pass **must** go through it (`hewtd integrate`, `hewtd
+archive`, `hewtd maintain`) rather than hand-managed markdown, so the doc lands
+in a domain and the indexes stay honest.
+
+## How to operate it
+
+Nothing to run — the phases arrive with the plan:
+
+```bash
+/start-planning "Refactor auth"          # sm: task_plan.md seeded with 6 phases
+/start-planning "Foundation" --mode lg   # lg: phase.md seeded with 2 closing tasks
+```
+
+To confirm the templates still seed them correctly after editing:
+
+```bash
+npm test
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A new plan has only 4 phases | Plan created by persistent-planning < 3.1.0 | Append the two closing phases by hand; upgrade the plugin |
+| Closing phases are no longer last | Work appended below them | Move the new phases above the pair and renumber |
+| `npm test` fails on "documentation phase is last" | A template edit added a checkbox after the pair, or reworded the pair | Restore the ordering in `scripts/init-planning.sh` / `templates/lg/phase.md` |
+| Phase marked `done` with closing tasks unchecked | Skipped the gate | Not done — finish both, then mark the phase |

package/.documentation/testing/INDEX.md

@@ -0,0 +1,42 @@
+---
+title: Testing Documentation Index
+tier: reference
+domains: [testing]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of testing documentation
+---
+
+# Testing Documentation
+
+> Test strategies, fixtures, patterns, integration/e2e
+
+## Overview
+
+- **Total Documents:** 1
+- **Domain:** `testing/`
+- **Category:** development
+- **Load Priority:** 7/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Test Suite](test-suite.md) | active | 2026-08-31 | 450 |
+
+## Keywords
+
+This domain covers: test, testing, tests, unit, unit-test, integration, integration-test, e2e, end-to-end, fixture
+
+## Related Domains
+
+- [Architecture](../architecture/) - System design, AI coach, project registry, patterns
+- [Standards](../standards/) - Coding standards (backend, frontend, database, devops, security)
+- [Reference](../reference/) - Schema, frontmatter, and CLI reference material for the planning artifacts
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/testing/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Testing Registry
+tier: reference
+domains: [testing]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for testing documentation
+---
+
+# Testing Registry
+
+> Quick reference for test strategies, fixtures, patterns, integration/e2e.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 1 |
+| Category | development |
+| Load Priority | 7/10 |
+
+## Active Documents
+
+- [Test Suite](test-suite.md)
+
+## Recently Updated
+
+- [Test Suite](test-suite.md) - 2026-08-31
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 1 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`test` `testing` `tests` `unit` `unit-test` `integration` `integration-test` `e2e` `end-to-end` `fixture` `fixtures` `mock` `mocking` `stub` `pytest` `jest` `vitest` `playwright` `cypress` `coverage` `tdd` `bdd`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/testing/test-suite.md

@@ -0,0 +1,88 @@
+---
+title: Test Suite
+tier: guide
+domains:
+  - testing
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: What tests/run.sh covers, how to run it, how to add an assertion, and
+  why the suite is plain bash rather than a framework.
+estimated_read_time: 3 minutes
+word_count: 450
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Test Suite
+
+`tests/run.sh` is the whole test suite. It is plain bash with assert helpers —
+no framework, no fixtures, no dependencies beyond what the scripts under test
+already need.
+
+## Why bash and not a framework
+
+Everything under test *is* bash. `init-planning.sh`, `init-phase.sh`,
+`init-task.sh`, `init-atom.sh`, and `detect-mode.sh` are shell scripts whose
+observable behavior is "what landed on disk." A JS test runner would add a
+dependency, a config file, and a translation layer between the runner and the
+thing being run, to assert the same `grep`s. The suite stays in the language of
+its subject.
+
+The suite is also the thing that makes the
+[mandatory closing phases](../standards/mandatory-closing-phases.md) enforceable rather than
+aspirational: a template edit that pushes a checkbox below the closing pair turns
+the suite red.
+
+## How to run it
+
+```bash
+npm test           # preferred
+bash tests/run.sh  # identical, no npm needed
+```
+
+Output is one line per assertion and a `N passed, M failed` summary. Exit status
+is non-zero if anything failed, so it drops into CI unchanged.
+
+## What it covers
+
+| Group | Asserts |
+|---|---|
+| sm mode | `task_plan.md` + `notes.md` land at the slugified path; the plan seeds 6 phases; validation is second-to-last and documentation is last; the ordering rule text is present; the task name is substituted; re-running does not clobber an edited plan |
+| lg mode | `detect-mode.sh` honors the `workspace.json` override; `phase.md` + `notes.md` are created; the two closing tasks are last and in order; HEWTD `tier: plan` frontmatter is present; no `PLACEHOLDER` tokens survive rendering; `task.md` is created with the right `parent:`; atom `sequence:` auto-increments 1 → 2 |
+| mode guards | `init-phase.sh` exits non-zero in sm mode |
+
+Every test runs the real script against a throwaway `CLAUDE_PROJECT_DIR` created
+with `mktemp -d`, then removes it. Nothing touches the repository's own
+`.planning/` tree.
+
+## How to add an assertion
+
+Use the helpers already in the file — `assert_eq`, `assert_contains`,
+`assert_file`, and `checkbox_lines` (which extracts the checkbox lines of a named
+markdown section). A new case looks like:
+
+```bash
+WS=$(new_workspace)
+CLAUDE_PROJECT_DIR="$WS" bash "$REPO_DIR/scripts/init-planning.sh" "Some Task" >/dev/null
+assert_contains "$WS/.planning/some-task/task_plan.md" "## Goal" "plan has a Goal section"
+rm -rf "$WS"
+```
+
+**Then prove the assertion can fail.** Break the template on purpose, run
+`npm test`, confirm the new line goes red, and restore it. An assertion that has
+never failed is not known to test anything.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `no unsubstituted placeholders remain` fails | A template gained a `*_PLACEHOLDER` token with no matching substitution arg | Add the `KEY=value` pair to the matching `planning_render_and_log` call |
+| `init-phase.sh refuses to run in sm mode` fails | The lg-mode guard was dropped from an init script | Restore the `planning_mode` check |
+| Every lg assertion fails at once | `templates/lg/` not resolvable from the script directory | Check the `TEMPLATE_DIR` fallback chain in the init scripts |
+| Tests pass locally, lg mode broken for installed users | `templates/` or `scripts/` missing from the `files` array in `package.json` | Add them, verify with `npm pack` before publishing |
+
+That last row is not hypothetical — it is exactly how v3.0.0 shipped broken.

package/.documentation/troubleshooting/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Troubleshooting Documentation Index
+tier: reference
+domains: [troubleshooting]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of troubleshooting documentation
+---
+
+# Troubleshooting Documentation
+
+> Debug guides, common issues, solutions
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `troubleshooting/`
+- **Category:** advanced
+- **Load Priority:** 6/10
+
+## Documents
+
+*No documents in this domain yet.*
+
+To add a document:
+
+1. Create a markdown file in this directory
+2. Add YAML frontmatter with required metadata
+3. Run `npx hit-em-with-the-docs integrate <file>`
+## Keywords
+
+This domain covers: troubleshooting, troubleshoot, debug, debugging, issue, issues, problem, problems, error, errors
+
+## Related Domains
+
+- [Agents](../agents/) - Expert agent documentation, specialty matrix
+- [Backups](../backups/) - Backup/restore guides, disaster recovery
+- [Plans](../plans/) - Planning documents, roadmaps, proposals
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/troubleshooting/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Troubleshooting Registry
+tier: reference
+domains: [troubleshooting]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for troubleshooting documentation
+---
+
+# Troubleshooting Registry
+
+> Quick reference for debug guides, common issues, solutions.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | advanced |
+| Load Priority | 6/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`troubleshooting` `troubleshoot` `debug` `debugging` `issue` `issues` `problem` `problems` `error` `errors` `fix` `solution` `solutions` `resolve` `diagnose` `diagnosis` `log` `logs` `faq`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/workflows/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Workflows Documentation Index
+tier: reference
+domains: [workflows]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of workflows documentation
+---
+
+# Workflows Documentation
+
+> Process documentation, multi-step operations
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `workflows/`
+- **Category:** features
+- **Load Priority:** 5/10
+
+## Documents
+
+*No documents in this domain yet.*
+
+To add a document:
+
+1. Create a markdown file in this directory
+2. Add YAML frontmatter with required metadata
+3. Run `npx hit-em-with-the-docs integrate <file>`
+## Keywords
+
+This domain covers: workflow, workflows, process, processes, flow, flowchart, sequence, pipeline, automation, automated
+
+## Related Domains
+
+- [Procedures](../procedures/) - Step-by-step operational procedures (SOP)
+- [Quickstart](../quickstart/) - Setup guides, dev workflow, onboarding
+- [Features](../features/) - Feature implementation guides, admin docs
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/workflows/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Workflows Registry
+tier: reference
+domains: [workflows]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for workflows documentation
+---
+
+# Workflows Registry
+
+> Quick reference for process documentation, multi-step operations.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | features |
+| Load Priority | 5/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`workflow` `workflows` `process` `processes` `flow` `flowchart` `sequence` `pipeline` `automation` `automated` `multi-step` `orchestration` `state-machine`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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