@theglitchking/persistent-planning 3.0.1 → 3.4.0

package/{docs/reference.md → .documentation/architecture/context-engineering-principles.md}

@@ -1,4 +1,23 @@
-# Reference: Manus Context Engineering Principles
+---
+title: Manus Context Engineering Principles
+tier: reference
+domains:
+  - architecture
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-08-31'
+version: 1.0.0
+purpose: Based on the context engineering principles from Manus, the AI agent
+  company acquired by Meta for $2 billion in December 2025.
+estimated_read_time: 3 minutes
+word_count: 428
+last_validated: '2026-08-31'
+backlinks: []
+---
+
+# Manus Context Engineering Principles
 
 Based on the context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
 

package/{docs → .documentation/architecture}/lg-mode.md

@@ -2,13 +2,20 @@
 title: Lg-Mode Layered Planning Guide
 tier: guide
 domains:
-  - planning
-status: active
-last_updated: 2026-05-07
-version: 1.0.0
+  - architecture
 audience:
   - developers
-purpose: Full guide to lg-mode (large/team) persistent-planning — phase / task / atom / notes layered model, scheduling defaults, subagent contract, and integration with semantic-memory MCP.
+tags: []
+status: active
+last_updated: '2026-05-07'
+version: 1.0.0
+purpose: Full guide to lg-mode (large/team) persistent-planning — phase / task /
+  atom / notes layered model, scheduling defaults, subagent contract, and
+  integration with semantic-memory MCP.
+estimated_read_time: 4 minutes
+word_count: 720
+last_validated: '2026-08-31'
+backlinks: []
 ---
 
 # Lg-Mode (Layered Planning)
@@ -41,8 +48,8 @@ Notes are scoped to either a phase or a task (or both). Notes are NOT part of th
 .planning/
 ├── .meta/
 │   └── workspace.json              # {mode: "lg", auto_detected: true, ...}
-├── archive/
-│   └── <archived-phase-slug>/      # phases moved here on status: archived
+├── .archive/                       # gitignored; completed plans retired here
+│   └── <archived-phase-slug>/      # moved by /archive-plan
 └── <phase-slug>/
     ├── phase.md                    # the phase
     ├── notes.md                    # phase-scoped notes
@@ -66,7 +73,9 @@ Each layer has a status enum tracked in frontmatter:
 
 Status transitions are explicit. Atoms additionally support **reopen** (`done → in_progress`) with a `reopened_at: <iso-timestamp>` audit field for legitimate post-completion fixes.
 
-When a phase is marked `archived`, the entire `<phase-slug>/` directory moves to `archive/<phase-slug>/`. Atoms and tasks within move with it.
+A phase is **complete** when every checkbox under it is checked, or when `phase.md` declares `status: done`. That is derived from the artifacts, so there is no separate state to keep in sync — see [Plan Completion and Archive](../procedures/plan-completion-and-archive.md).
+
+When a phase is retired with `/archive-plan <phase-slug>`, the entire `<phase-slug>/` directory moves to `.planning/.archive/<phase-slug>/` — tasks and atoms with it — and `phase.md` is stamped `status: archived` plus `archived_on`. `.planning/.archive/` is gitignored: a completed plan is local history, not something every clone carries.
 
 ## Scheduling: dependencies-first, then parallelism
 
@@ -133,3 +142,19 @@ To explicitly migrate a v2 plan to lg, manually:
 - `templates/lg/{phase,task,atom,notes}.md` — frontmatter shapes
 - `scripts/detect-mode.sh` — mode resolution logic
 - `scripts/init-{phase,task,atom}.sh` — init script implementations
+
+
+## How the skill reaches a consumer repo
+
+`.claude/skills/persistent-planning` is a **symlink** into the installed package, created
+by `scripts/link-skills.js`. A real directory there is stale v1 debris and means commands
+are running frozen code — see
+[Skill linking and reclaim](skill-linking-and-reclaim.md) and
+[Stale skill directory](../troubleshooting/stale-skill-dir-drift.md).
+
+
+## Who writes which artifact
+
+Creating a task writes it into its phase's list; creating an atom writes it into its
+task's list. Full ownership table and the insertion rule:
+[lg plan artifact lifecycle](lg-plan-artifact-lifecycle.md).

package/.documentation/architecture/lg-plan-artifact-lifecycle.md

@@ -0,0 +1,104 @@
+---
+title: lg plan artifact lifecycle — who writes what
+tier: reference
+domains:
+  - architecture
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: >-
+  Which script writes which lg plan artifact, the rule that creating a child writes it
+  into its parent's list, and how insertion keeps the mandatory closers last.
+estimated_read_time: 3 minutes
+word_count: 438
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# lg plan artifact lifecycle — who writes what
+
+In lg mode a plan is a tree of markdown artifacts, and more than one thing writes
+into them. This page states the ownership, because for a long time nothing did —
+and the gap it left is [issue #12](https://github.com/the-glitch-kingdom/persistent-planning/issues/12).
+
+## Ownership
+
+| Artifact | Created by | Its list is written by |
+|---|---|---|
+| `<phase>/phase.md` | `init-phase.sh` | `init-task.sh`, on every new task |
+| `<phase>/notes.md` | `init-phase.sh` | humans |
+| `<phase>/<task>/task.md` | `init-task.sh` (closers: `init-phase.sh`) | `init-atom.sh`, on every new atom |
+| `<phase>/<task>/notes.md` | `init-task.sh` | humans |
+| `<phase>/<task>/atoms/<atom>.md` | `init-atom.sh` | humans |
+
+The rule worth remembering: **creating a child writes it into its parent's list.**
+Before 3.3.0, `init-task.sh` referenced `phase.md` only in an existence check and
+`init-atom.sh` never touched `task.md`, so every list was maintained by hand — and a
+phase could report "no tasks yet" with six task directories on disk.
+
+## The insertion rule
+
+`planning_insert_list_item <file> <section> <line>` in `scripts/lib/planning.sh`:
+
+- inserts **above the first item marked MANDATORY**, so the closers stay last by
+  construction rather than by anyone remembering the rule;
+- appends after the last item when the section has no MANDATORY entries (atom lists);
+- drops the `(no … yet)` placeholder, including indented continuation lines, the
+  first time a real item lands;
+- is idempotent — an identical line already present is left alone, so re-running
+  under `PLANNING_FORCE=1` cannot double-insert;
+- is section-scoped (`## Heading` to the next `## `), so it cannot wander into a
+  neighbouring list.
+
+It **anchors on the MANDATORY marker, never on line numbers.** The list is a
+human-editable surface; positions do not survive contact with editing. This is tested
+against a hand-reordered, partially-checked, annotated list.
+
+## The two closers
+
+Every phase is scaffolded with both closing tasks as real directories:
+
+```
+<phase>/validate-success-through-comprehensive-testing/
+<phase>/documentation-pass-create-update-deprecate-docs/
+```
+
+Each gets `task.md` (with `mandatory: true`, `parallelizable: false`), `notes.md`,
+`atoms/`, and seeded atoms — not empty placeholders. They were previously two lines
+of prose in `phase.md`, which made the most important tasks in every plan the only
+ones with no artifact a subagent could read and nowhere to record decisions.
+
+See [Mandatory frontmatter](../reference/mandatory-frontmatter.md) for what
+`mandatory: true` does, and
+[Mandatory closing phases](../standards/mandatory-closing-phases.md) for why they exist.
+
+## Placeholders are not work
+
+`(no tasks yet …)` and `(no atoms yet …)` are **italic text, not checkboxes**. They
+used to ship as `- [ ]`, and `plan-status.sh` counts every checkbox under a plan — so
+a fresh phase with two tasks reported `0/5 boxes` and a plan could reach 100% by
+ticking lines asserting that nothing existed. See
+[Plan never reads complete](../troubleshooting/plan-never-reads-complete.md).
+
+## What is version-controlled
+
+Active plans are **tracked**. They are the artifact a team coordinates around and that
+subagents read via the planning MCP — and lg mode is selected precisely because there is
+a team (≥2 git authors in 90 days). Ignoring them would defeat the mode's purpose.
+
+Only `.planning/.archive/` is ignored: a completed plan is local history. Both init
+scripts and `archive-plan.sh` write that one entry through
+`planning_ensure_archive_gitignored` (sm keeps its own self-contained copy).
+
+A repo that already carries a blanket `.planning/` line from v1 keeps it — the tool warns
+once and never rewrites a user's `.gitignore`. To start sharing plans, replace that line
+with `.planning/.archive/`.
+
+## sm mode is different, on purpose
+
+`scripts/init-planning.sh` writes a single flat `task_plan.md` where phases-as-checkboxes
+*is* the entire artifact. None of the above applies, and per `CLAUDE.md` its v2 behavior
+is preserved bit-for-bit — the test suite diffs its output against the pre-change render.

package/.documentation/architecture/skill-linking-and-reclaim.md

@@ -0,0 +1,84 @@
+---
+title: Skill linking and reclaim
+tier: reference
+domains:
+  - architecture
+audience:
+  - developers
+tags: []
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: How the skill directory reaches a consumer repo as a symlink, the four states it can
+  be in, and how a stale real directory is reclaimed without ever deleting it.
+estimated_read_time: 2 minutes
+word_count: 348
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# Skill linking and reclaim
+
+How `skills/persistent-planning/` reaches a consumer repo, and how a stale copy is
+reclaimed. Implemented in `scripts/lib/skill-link.js` and `scripts/link-skills.js`.
+
+## The link
+
+`scripts/link-skills.js` runs as npm `postinstall` and delegates to
+`@theglitchking/claude-plugin-runtime`'s `runPostinstall()`, which symlinks each
+directory under `skills/` into the consumer's `.claude/skills/`.
+
+The runtime's linker reconciles a symlink but **skips a real directory** — it warns
+and moves on, every time, forever. That is correct caution (the directory might be
+hand-managed) and it is also how v1 debris survived five months: v1's
+`persistent-planning install`, removed in 2.0.0, *copied* the skill dir, and nothing
+since could reclaim it.
+
+## The reclaim
+
+`reclaimStaleSkillDirs()` runs **before** the delegation. It renames a real directory
+to `<name>.bak-<ISO8601>`, which leaves a clean destination the runtime's linker then
+symlinks normally.
+
+That ordering is the whole trick — it needs no change to `claude-plugin-runtime`, so
+the fix ships as one release of this package rather than a runtime publish plus a
+coordinated rollout. The runtime's skip is still worth fixing upstream; this shim is
+written to be harmless if that ever lands.
+
+Rules the implementation holds to:
+
+- **Never delete.** A failed rename falls through to the runtime's old skip, but says
+  so loudly and names `relink`. The directory may contain hand edits.
+- **Idempotent.** A healthy symlink is left completely alone, so a second run makes no
+  second backup.
+- **Best-effort.** Any failure is caught; a reclaim problem never blocks an install.
+
+## The four states
+
+`describeSkill()` classifies `.claude/skills/<name>`:
+
+| State | Meaning |
+|---|---|
+| `absent` | nothing there; the linker will create the symlink |
+| `symlink-ok` | points at this package (relative or absolute, both accepted) |
+| `symlink-foreign` | points somewhere else — another install owns it |
+| `real-dir` | **drift.** Nothing in the current system creates one |
+
+`real-dir` and `symlink-foreign` are what `driftedSkills()` reports and what the
+SessionStart hook warns about.
+
+## Escape hatches
+
+| Variable | Effect |
+|---|---|
+| `PERSISTENT_PLANNING_SKIP_LINK=1` | no linking at all (runtime convention) |
+| `PERSISTENT_PLANNING_NO_RECLAIM=1` | link, but never move an existing directory aside |
+
+`updatePolicy: off` in `.claude/persistent-planning.json` suppresses the warning and
+the automatic repair.
+
+## Related
+
+- [Plugin update delivery](../procedures/plugin-update-delivery.md)
+- [Skill version marker](../reference/skill-version-marker.md)
+- [Stale skill directory](../troubleshooting/stale-skill-dir-drift.md)

package/.documentation/archive/README.md

@@ -0,0 +1,46 @@
+# Archive
+
+This folder holds **deprecated documentation** — docs that are retired but
+worth keeping (historical reference, superseded guides, old runbooks).
+
+## Don't move files here by hand — use the command
+
+```bash
+hewtd archive <file> --reason "why"     # e.g. hewtd archive api/old-webhooks.md
+```
+
+`hewtd archive` does it properly: it moves the doc into
+`archive/<same-domain-path>/`, preserves git history (`git mv`), stamps
+lifecycle metadata (`status: archived`, `archived_on`, `archived_from`), and
+regenerates the indexes so the doc cleanly leaves the active set. It also
+**refuses if other active docs still link to the doc** (so you don't create
+dead links) — pass `--force` to override after you've reviewed them.
+
+## Reversible
+
+```bash
+hewtd unarchive <file>                  # restores to its original path, status: active
+```
+
+The `archived_from` field records the exact restore path, so un-archiving is
+lossless.
+
+## Finding what to archive
+
+```bash
+hewtd archive-candidates                # advisory list — never moves anything
+```
+
+Suggests docs worth retiring, ranked by signal: `status: deprecated` (strongest),
+`superseded_by:`, orphaned (no inbound links), and age (only when also orphaned).
+Age alone never qualifies a doc — an unchanged doc is often your most important one.
+
+## hewtd ignores this folder
+
+Everything under `archive/` is **excluded from every hewtd scan** — `audit`,
+`link-check`, `metadata-sync`, `integrate` duplicate-detection, the link
+graph, and `search`. Archived docs are not validated, never appear in any
+INDEX.md / REGISTRY.md, and can't break audit/link-check with stale frontmatter.
+
+> Note: `archive/` is a reserved name. You cannot create a custom domain
+> called `archive`.

package/.documentation/backups/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Backups Documentation Index
+tier: reference
+domains: [backups]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of backups documentation
+---
+
+# Backups Documentation
+
+> Backup/restore guides, disaster recovery
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `backups/`
+- **Category:** advanced
+- **Load Priority:** 4/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: backup, backups, restore, recovery, disaster, disaster-recovery, dr, snapshot, archive, retention
+
+## Related Domains
+
+- [Agents](../agents/) - Expert agent documentation, specialty matrix
+- [Plans](../plans/) - Planning documents, roadmaps, proposals
+- [Troubleshooting](../troubleshooting/) - Debug guides, common issues, solutions
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/backups/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Backups Registry
+tier: reference
+domains: [backups]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for backups documentation
+---
+
+# Backups Registry
+
+> Quick reference for backup/restore guides, disaster recovery.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | advanced |
+| Load Priority | 4/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`backup` `backups` `restore` `recovery` `disaster` `disaster-recovery` `dr` `snapshot` `archive` `retention` `replication` `failover`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/database/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Database Documentation Index
+tier: reference
+domains: [database]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of database documentation
+---
+
+# Database Documentation
+
+> Schema, migrations, RLS, queries, procedures
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `database/`
+- **Category:** core
+- **Load Priority:** 8/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: database, db, postgres, postgresql, mysql, sql, schema, migration, migrations, alembic
+
+## Related Domains
+
+- [Security](../security/) - Security, auth, Vault, Keycloak, RLS
+- [API](../api/) - API endpoints, routes, specifications, contracts
+- [DevOps](../devops/) - Deployment, CI/CD, Docker, environments, infrastructure
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/database/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Database Registry
+tier: reference
+domains: [database]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for database documentation
+---
+
+# Database Registry
+
+> Quick reference for schema, migrations, rls, queries, procedures.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | core |
+| Load Priority | 8/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`database` `db` `postgres` `postgresql` `mysql` `sql` `schema` `migration` `migrations` `alembic` `query` `queries` `table` `index` `indexes` `rls` `procedure` `function` `trigger` `transaction` `orm` `sqlalchemy` `prisma`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/devops/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: DevOps Documentation Index
+tier: reference
+domains: [devops]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of devops documentation
+---
+
+# DevOps Documentation
+
+> Deployment, CI/CD, Docker, environments, infrastructure
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `devops/`
+- **Category:** core
+- **Load Priority:** 8/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: devops, deployment, deploy, ci, cd, ci/cd, pipeline, docker, container, kubernetes
+
+## Related Domains
+
+- [API](../api/) - API endpoints, routes, specifications, contracts
+- [Database](../database/) - Schema, migrations, RLS, queries, procedures
+- [Security](../security/) - Security, auth, Vault, Keycloak, RLS
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/devops/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: DevOps Registry
+tier: reference
+domains: [devops]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for devops documentation
+---
+
+# DevOps Registry
+
+> Quick reference for deployment, ci/cd, docker, environments, infrastructure.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | core |
+| Load Priority | 8/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`devops` `deployment` `deploy` `ci` `cd` `ci/cd` `pipeline` `docker` `container` `kubernetes` `k8s` `infrastructure` `terraform` `ansible` `aws` `gcp` `azure` `cloud` `environment` `production` `staging` `development` `nginx` `load-balancer` `monitoring`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/drafts/.gitkeep

@@ -0,0 +1 @@
+# This file ensures the drafts directory is tracked by git

package/.documentation/features/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Features Documentation Index
+tier: reference
+domains: [features]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Complete listing of features documentation
+---
+
+# Features Documentation
+
+> Feature implementation guides, admin docs
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `features/`
+- **Category:** features
+- **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: feature, features, implementation, guide, how-to, tutorial, admin, administration, dashboard, ui
+
+## Related Domains
+
+- [Procedures](../procedures/) - Step-by-step operational procedures (SOP)
+- [Quickstart](../quickstart/) - Setup guides, dev workflow, onboarding
+- [Workflows](../workflows/) - Process documentation, multi-step operations
+
+---
+
+*Last updated: 2026-09-04*

package/.documentation/features/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Features Registry
+tier: reference
+domains: [features]
+status: active
+last_updated: '2026-09-04'
+version: '1.0.0'
+purpose: Quick reference for features documentation
+---
+
+# Features Registry
+
+> Quick reference for feature implementation guides, admin docs.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | features |
+| Load Priority | 6/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`feature` `features` `implementation` `guide` `how-to` `tutorial` `admin` `administration` `dashboard` `ui` `component` `module` `functionality` `capability`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-09-04*