@theglitchking/persistent-planning 3.0.0 → 3.1.0

package/.documentation/procedures/plan-completion-and-archive.md

@@ -0,0 +1,151 @@
+---
+title: Plan Completion and Archive
+tier: guide
+domains:
+  - procedures
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: How persistent-planning decides a plan is finished, how that reaches
+  the agent automatically, and the procedure for retiring a completed plan into
+  the gitignored .planning/.archive/ directory.
+estimated_read_time: 5 minutes
+word_count: 812
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Plan Completion and Archive
+
+## What it is
+
+Two things that only make sense together:
+
+- **Status tracking** — a plan's completion is *derived from the plan artifacts*,
+  not stored anywhere else.
+- **Archive** — a completed plan is moved out of the active `.planning/` tree into
+  a gitignored `.planning/.archive/`, so what remains under `.planning/` is only
+  ever live work.
+
+## Why it matters
+
+The failure this prevents is a finished plan that nobody retires. It sits in
+`.planning/`, and every future session — human or agent — re-reads it, re-reasons
+about whether it is still relevant, and burns context deciding it isn't. Multiply
+by a dozen plans and the working-memory directory becomes the thing you have to
+work around.
+
+The reason completion is *derived* rather than *declared* is drift. A `done: true`
+flag someone has to remember to set is wrong the moment they forget, and nothing
+detects that. Checkbox state cannot drift from the plan, because it **is** the
+plan. Checking the last box is the completion signal; there is no second step to
+forget.
+
+## Where it lives
+
+| Piece | Path |
+|---|---|
+| Status scan (single implementation) | `scripts/plan-status.sh` |
+| Archive operation | `scripts/archive-plan.sh` |
+| Session-start nudge | `hooks/session-start.js` (shells out to `plan-status.sh --nudge`) |
+| Slash commands | `commands/plan-status.md`, `commands/archive-plan.md` |
+| Archived plans | `.planning/.archive/<slug>/` (gitignored) |
+
+## The completion rule
+
+A plan is **COMPLETE** when either holds:
+
+1. Every checkbox in every markdown file under the plan directory is checked, or
+2. The plan's top-level artifact (`phase.md`, `task_plan.md`, or `task.md`)
+   declares `status: done` in frontmatter.
+
+Other verdicts: `blocked` (an atom carries `status: blocked`), `empty` (no
+checkboxes yet), `in progress` (anything else), `archived` (already stamped).
+
+Because plans are seeded with [mandatory closing phases](../standards/mandatory-closing-phases.md),
+a plan cannot read COMPLETE until its work has been tested *and* documented. The
+two features are deliberately coupled: completion means finished, not "the fun
+part is finished."
+
+## How the agent finds out
+
+Three escalating surfaces, cheapest first:
+
+1. **SessionStart hook.** On every session, the hook runs `plan-status.sh --nudge`
+   and merges any result into the session's context: *"persistent-planning: 1
+   plan(s) complete but not archived — <slug>."* Silent when there is nothing to
+   say, so it costs nothing in the normal case.
+2. **`/plan-status`.** The full table, on demand.
+3. **The plan artifact itself.** Both templates carry an `## On Completion`
+   section stating the rule and the archive command, so an agent reading only the
+   plan still learns the protocol.
+
+## How to operate it
+
+```bash
+/plan-status                     # what is in progress, blocked, complete
+/archive-plan <slug>             # retire one completed plan
+/archive-plan --all-complete     # retire every completed plan
+/archive-plan <slug> --dry-run   # show the move without making it
+/archive-plan <slug> --force     # retire an unfinished plan (deliberate)
+```
+
+Machine-readable forms for scripts and subagents:
+
+```bash
+bash scripts/plan-status.sh --complete   # one complete plan slug per line
+bash scripts/plan-status.sh --nudge      # one line, or nothing
+```
+
+Archiving performs four steps:
+
+1. Verifies completion (skipped under `--force`).
+2. Ensures `.planning/.archive/` exists and is in `.gitignore`.
+3. Moves `.planning/<slug>/` → `.planning/.archive/<slug>/`, preferring `git mv`
+   when the plan is tracked so history follows it.
+4. Stamps the top-level artifact: `status: archived` + `archived_on` in
+   frontmatter, or a dated footer for sm plans that have none.
+
+**Nothing is ever deleted.** Archiving is a move plus a stamp.
+
+## Restoring an archived plan
+
+```bash
+mv .planning/.archive/<slug> .planning/<slug>
+```
+
+Then set `status:` back to `active` and remove the `archived_on` stamp. The plan
+resumes reading as in-progress the moment a box is unchecked.
+
+## How to fix it
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Finished plan never reads COMPLETE | A checkbox is still unchecked somewhere in the tree — often in a nested atom file | `bash scripts/plan-status.sh` shows `checked/total`; grep the plan for `- [ ]` |
+| A brand-new plan reads COMPLETE | Its template checkboxes were checked without doing the work, or the plan has no checkboxes and `status: done` was set by hand | Uncheck, or correct the frontmatter |
+| `archive-plan.sh` refuses | The plan is genuinely incomplete | Finish it. `--force` exists for deliberate abandonment, not for impatience |
+| "Already archived: … exists" | A plan with that slug was archived before | Rename or move the existing entry under `.planning/.archive/` first |
+| Nudge never appears | No `.planning/` directory, or no plan is complete, or the hook is not registered | `npx persistent-planning status` reports hook registration |
+| Archived plans show up in `git status` | `.planning/` is tracked in this repo and the ignore line was added after the fact | Ensure `.gitignore` has `.planning/.archive/`; `git rm -r --cached .planning/.archive` if already tracked |
+
+## Design notes
+
+**One implementation of the scan.** The hook, the slash command, and
+`archive-plan.sh`'s completion check all shell out to `plan-status.sh`. A second
+copy of the "is this done?" rule in JavaScript would be a second copy that could
+disagree.
+
+**The hook merges rather than appends.** `@theglitchking/claude-plugin-runtime`
+owns the single `SessionStart` JSON response and exposes no hook for adding to it,
+and emitting a second response line would be invalid. `hooks/session-start.js`
+intercepts that one write and merges the nudge into the same payload, failing
+open — if the payload is not the shape it expects, it is written through
+untouched and the update check still works.
+
+**Archive is gitignored on purpose.** A completed plan is a record of how *this
+machine* got somewhere. Sharing it with every clone would grow the repository
+with reasoning nobody reads. If a particular plan is worth keeping, promote its
+findings into a real doc — which is what the mandatory documentation phase is for.

package/.documentation/quickstart/INDEX.md

@@ -0,0 +1,42 @@
+---
+title: Quickstart Documentation Index
+tier: reference
+domains: [quickstart]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of quickstart documentation
+---
+
+# Quickstart Documentation
+
+> Setup guides, dev workflow, onboarding
+
+## Overview
+
+- **Total Documents:** 1
+- **Domain:** `quickstart/`
+- **Category:** features
+- **Load Priority:** 9/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Examples: Persistent Planning in Action](examples.md) | active | 2026-08-31 | 136 |
+
+## Keywords
+
+This domain covers: quickstart, quick-start, getting-started, setup, install, installation, onboarding, developer, dev, workflow
+
+## Related Domains
+
+- [Workflows](../workflows/) - Process documentation, multi-step operations
+- [Features](../features/) - Feature implementation guides, admin docs
+- [Procedures](../procedures/) - Step-by-step operational procedures (SOP)
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/quickstart/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Quickstart Registry
+tier: reference
+domains: [quickstart]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for quickstart documentation
+---
+
+# Quickstart Registry
+
+> Quick reference for setup guides, dev workflow, onboarding.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 1 |
+| Category | features |
+| Load Priority | 9/10 |
+
+## Active Documents
+
+- [Examples: Persistent Planning in Action](examples.md)
+
+## Recently Updated
+
+- [Examples: Persistent Planning in Action](examples.md) - 2026-08-31
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 1 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`quickstart` `quick-start` `getting-started` `setup` `install` `installation` `onboarding` `developer` `dev` `workflow` `start` `begin` `intro` `introduction` `new-developer`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/{docs → .documentation/quickstart}/examples.md

@@ -1,3 +1,23 @@
+---
+title: 'Examples: Persistent Planning in Action'
+tier: plan
+domains:
+  - quickstart
+audience:
+  - all
+tags:
+  - authentication
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: '**User Request:** "Research the benefits of morning exercise and write
+  a summary"'
+estimated_read_time: 1 minute
+word_count: 136
+last_validated: '2026-08-31'
+backlinks: []
+---
+
 # Examples: Persistent Planning in Action
 
 ## Example 1: Research Task

package/.documentation/reference/INDEX.md

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

package/.documentation/reference/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Reference Registry
+tier: reference
+domains: [reference]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for reference documentation
+---
+
+# Reference Registry
+
+> Quick reference for schema, frontmatter, and cli reference material for the planning artifacts.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 1 |
+| Category | development |
+| Load Priority | 7/10 |
+
+## Active Documents
+
+- [workspace.json schema](workspace-json.md)
+
+## Recently Updated
+
+- [workspace.json schema](workspace-json.md) - 2026-05-07
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 1 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`schema` `frontmatter` `workspace.json` `field` `enum` `cli` `flags` `reference` `contract`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/{docs → .documentation/reference}/workspace-json.md

@@ -2,13 +2,19 @@
 title: workspace.json schema
 tier: standard
 domains:
-  - planning
-status: active
-last_updated: 2026-05-07
-version: 1.0.0
+  - reference
 audience:
   - developers
-purpose: Document the .planning/.meta/workspace.json schema introduced in v3.0 for sm/lg mode tracking
+tags: []
+status: active
+last_updated: '2026-05-07'
+version: 1.0.0
+purpose: Document the .planning/.meta/workspace.json schema introduced in v3.0
+  for sm/lg mode tracking
+estimated_read_time: 2 minutes
+word_count: 358
+last_validated: '2026-08-31'
+backlinks: []
 ---
 
 # `workspace.json` schema (v3.0)

package/.documentation/security/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Security Documentation Index
+tier: reference
+domains: [security]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of security documentation
+---
+
+# Security Documentation
+
+> Security, auth, Vault, Keycloak, RLS
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `security/`
+- **Category:** core
+- **Load Priority:** 9/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: security, auth, authentication, authorization, oauth, jwt, keycloak, vault, secrets, rls
+
+## Related Domains
+
+- [Database](../database/) - Schema, migrations, RLS, queries, procedures
+- [API](../api/) - API endpoints, routes, specifications, contracts
+- [DevOps](../devops/) - Deployment, CI/CD, Docker, environments, infrastructure
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/security/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Security Registry
+tier: reference
+domains: [security]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for security documentation
+---
+
+# Security Registry
+
+> Quick reference for security, auth, vault, keycloak, rls.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | core |
+| Load Priority | 9/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`security` `auth` `authentication` `authorization` `oauth` `jwt` `keycloak` `vault` `secrets` `rls` `row-level-security` `rbac` `permissions` `access-control` `encryption` `ssl` `tls` `certificate`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/standards/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Standards Documentation Index
+tier: reference
+domains: [standards]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of standards documentation
+---
+
+# Standards Documentation
+
+> Coding standards (backend, frontend, database, devops, security)
+
+## Overview
+
+- **Total Documents:** 2
+- **Domain:** `standards/`
+- **Category:** development
+- **Load Priority:** 10/10
+
+## Documents
+
+### Standards
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Atom Granularity (anti-pattern guide)](atom-granularity.md) | active | 2026-05-07 | 556 |
+| [Mandatory Closing Phases](mandatory-closing-phases.md) | active | 2026-08-31 | 770 |
+
+## Keywords
+
+This domain covers: standard, standards, convention, conventions, pattern, patterns, best-practice, best-practices, guideline, guidelines
+
+## Related Domains
+
+- [Architecture](../architecture/) - System design, AI coach, project registry, patterns
+- [Testing](../testing/) - Test strategies, fixtures, patterns, integration/e2e
+- [Reference](../reference/) - Schema, frontmatter, and CLI reference material for the planning artifacts
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/standards/REGISTRY.md

@@ -0,0 +1,53 @@
+---
+title: Standards Registry
+tier: reference
+domains: [standards]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for standards documentation
+---
+
+# Standards Registry
+
+> Quick reference for coding standards (backend, frontend, database, devops, security).
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 2 |
+| Category | development |
+| Load Priority | 10/10 |
+
+## Active Documents
+
+- [Atom Granularity (anti-pattern guide)](atom-granularity.md)
+- [Mandatory Closing Phases](mandatory-closing-phases.md)
+
+## Recently Updated
+
+- [Mandatory Closing Phases](mandatory-closing-phases.md) - 2026-08-31
+- [Atom Granularity (anti-pattern guide)](atom-granularity.md) - 2026-05-07
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 2 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`standard` `standards` `convention` `conventions` `pattern` `patterns` `best-practice` `best-practices` `guideline` `guidelines` `style` `style-guide` `coding` `naming` `formatting` `linting` `rules`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/{docs → .documentation/standards}/atom-granularity.md

@@ -2,13 +2,20 @@
 title: Atom Granularity (anti-pattern guide)
 tier: standard
 domains:
-  - planning
-status: active
-last_updated: 2026-05-07
-version: 1.0.0
+  - standards
 audience:
   - developers
-purpose: When to spawn a standalone atom file vs. add an inline atom checkbox to task.md. The atom layer is load-bearing for subagent hand-off; this doc keeps it from being misused.
+tags: []
+status: active
+last_updated: '2026-05-07'
+version: 1.0.0
+purpose: When to spawn a standalone atom file vs. add an inline atom checkbox to
+  task.md. The atom layer is load-bearing for subagent hand-off; this doc keeps
+  it from being misused.
+estimated_read_time: 3 minutes
+word_count: 556
+last_validated: '2026-08-31'
+backlinks: []
 ---
 
 # Atom Granularity