@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/.documentation/reference/mandatory-frontmatter.md

@@ -0,0 +1,71 @@
+---
+title: '`mandatory:` task frontmatter'
+tier: reference
+domains:
+  - reference
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: >-
+  Contract for the mandatory: task frontmatter field — who sets it, what reads it, and
+  why absent must mean no enforcement for legacy plans.
+estimated_read_time: 2 minutes
+word_count: 270
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# `mandatory:` task frontmatter
+
+A boolean in an lg task's frontmatter marking it as one of the phase's mandatory
+closing tasks. It is what turns "a phase cannot be done until both closers are done"
+from a sentence in a template into something `plan-status.sh` enforces.
+
+```yaml
+---
+title: Validate success through comprehensive testing
+plan_kind: task
+status: draft
+depends_on: []
+parallelizable: false
+mandatory: true
+---
+```
+
+## Contract
+
+| | |
+|---|---|
+| **Lives in** | `<phase>/<task>/task.md` frontmatter |
+| **Default** | `false` — `templates/lg/task.md` ships it explicitly |
+| **Set to `true` by** | `init-phase.sh`, on the two scaffolded closers only |
+| **Read by** | `scripts/plan-status.sh` (`unfinished_mandatory()`) |
+| **Effect** | a plan with any `mandatory: true` task whose `status` is neither `done` nor `archived` cannot read `COMPLETE`, however the checkboxes add up |
+| **Absent means** | no enforcement — legacy behavior, exactly as before |
+
+## Why absent must mean "no enforcement"
+
+Plans created before 3.3.0 have no closer directories and no `mandatory:` frontmatter.
+Treating absence as `true`, or inferring closers by title, would retroactively reopen
+finished plans — worse than the bug this field fixes. The gate is strictly additive and
+the test suite asserts a legacy plan still reads `COMPLETE`.
+
+## Where it is enforced — once
+
+`plan-status.sh` is the single implementation of "is this plan done?" per `CLAUDE.md`.
+`archive-plan.sh` inherits the gate through its existing pre-flight call rather than
+carrying a second copy of the rule, and `--complete` / `--nudge` — which the
+SessionStart hook and `archive-plan.sh` consume — honour it too.
+
+Ticking a checkbox is **not** sufficient for a mandatory task. The task's own `status:`
+must be `done`. That distinction is the whole point: a closer that was ticked but never
+performed is exactly the failure this guards.
+
+## Related
+
+- [lg plan artifact lifecycle](../architecture/lg-plan-artifact-lifecycle.md)
+- [Plan completion and archive](../procedures/plan-completion-and-archive.md)
+- [Plan never reads complete](../troubleshooting/plan-never-reads-complete.md)

package/.documentation/reference/skill-version-marker.md

@@ -0,0 +1,70 @@
+---
+title: Skill version marker (`.version`)
+tier: reference
+domains:
+  - reference
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: >-
+  Contract for the .version marker written beside SKILL.md — who writes it, when it
+  is deliberately not written, and why it is the secondary drift signal.
+estimated_read_time: 2 minutes
+word_count: 295
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# Skill version marker (`.version`)
+
+A one-line file beside `SKILL.md` recording which package version a linked skill came
+from. Written by `scripts/link-skills.js`, read by `scripts/lib/skill-link.js`.
+
+```
+.claude/skills/persistent-planning/.version   ->   "3.2.0\n"
+```
+
+## Contract
+
+| | |
+|---|---|
+| **Path** | `.claude/skills/<skill-name>/.version` |
+| **Contents** | the package's `version`, plus a trailing newline |
+| **Written by** | `writeVersionMarkers()`, after the linker runs |
+| **Read by** | `readSkillVersion(consumerRoot, name)` — returns the string, or `null` |
+| **Written when** | the skill resolves to `symlink-ok` |
+| **Never written when** | the destination is a real directory |
+| **Absent means** | unknown — never "current" |
+
+## Why only healthy symlinks are stamped
+
+Stamping a real directory would write "3.2.0" into a frozen pre-3.1.0 copy and mark
+stale code as current — defeating the check it exists to support. A real directory is
+left unstamped precisely so it reads as unknown.
+
+Because a healthy skill dir is a symlink into the package, the marker written through
+it lands in the package and is correct for free.
+
+## Why not `package.json`
+
+A `package.json` inside a skill directory invites npm to treat that directory as a
+package and changes module resolution underneath it. A plain `.version` file cannot.
+`skills/*/.version` is gitignored so a local install cannot commit a stray marker.
+
+## This is the secondary signal
+
+The **primary** drift signal is structural: is `.claude/skills/<name>` a symlink into
+this package? A real directory is always drift, because nothing in the current system
+creates one. That check needs no marker and cannot itself go stale.
+
+The marker answers the follow-up question — *how far behind is it* — and is the only
+signal available on install shapes where a symlink is impossible (Windows without
+developer mode, some CI checkouts). Treat a missing marker as unknown, never as fine.
+
+## Related
+
+- [Skill linking and reclaim](../architecture/skill-linking-and-reclaim.md)
+- [Stale skill directory](../troubleshooting/stale-skill-dir-drift.md)

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-09-04'
+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-09-04*

package/.documentation/security/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Security Registry
+tier: reference
+domains: [security]
+status: active
+last_updated: '2026-09-04'
+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-09-04*

package/.documentation/standards/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Standards Documentation Index
+tier: reference
+domains: [standards]
+status: active
+last_updated: '2026-09-04'
+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-09-04*

package/.documentation/standards/REGISTRY.md

@@ -0,0 +1,53 @@
+---
+title: Standards Registry
+tier: reference
+domains: [standards]
+status: active
+last_updated: '2026-09-04'
+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-09-04*

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

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

@@ -0,0 +1,145 @@
+---
+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 as many docs as needed to capture what was done, where it lives, how to troubleshoot it**
+
+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 |
+
+
+## How they are enforced (3.3.0+)
+
+In lg mode the two closers are no longer only checkbox lines. `init-phase.sh` scaffolds
+each as a real task directory — `task.md` with `mandatory: true`, `notes.md`, `atoms/`,
+and seeded atoms — so they are addressable artifacts like every other task.
+
+Two mechanisms keep the rule true rather than advisory:
+
+- **Ordering by construction.** `init-task.sh` inserts every new task *above* the first
+  MANDATORY entry, so the closers cannot be pushed out of last place by adding work.
+- **Completion gated on status.** `plan-status.sh` refuses `COMPLETE` while any
+  `mandatory: true` task's own `status:` is not `done`. Ticking its checkbox is not
+  enough — a closer that was ticked but never performed is exactly the failure being
+  guarded.
+
+Legacy plans without `mandatory:` frontmatter keep their previous behavior; the gate is
+strictly additive. See [`mandatory:` frontmatter](../reference/mandatory-frontmatter.md)
+and [lg plan artifact lifecycle](../architecture/lg-plan-artifact-lifecycle.md).

package/.documentation/testing/INDEX.md

@@ -0,0 +1,42 @@
+---
+title: Testing Documentation Index
+tier: reference
+domains: [testing]
+status: active
+last_updated: '2026-09-04'
+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-09-04*

package/.documentation/testing/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Testing Registry
+tier: reference
+domains: [testing]
+status: active
+last_updated: '2026-09-04'
+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-09-04*