@theglitchking/persistent-planning 3.0.1 → 3.1.0

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
 

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-08-31'
+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-08-31*

package/.documentation/backups/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Backups Registry
+tier: reference
+domains: [backups]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

package/.documentation/database/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Database Documentation Index
+tier: reference
+domains: [database]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

package/.documentation/database/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Database Registry
+tier: reference
+domains: [database]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

package/.documentation/devops/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: DevOps Documentation Index
+tier: reference
+domains: [devops]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

package/.documentation/devops/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: DevOps Registry
+tier: reference
+domains: [devops]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

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-08-31'
+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-08-31*

package/.documentation/features/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Features Registry
+tier: reference
+domains: [features]
+status: active
+last_updated: '2026-08-31'
+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-08-31*

package/.documentation/plans/INDEX.md

@@ -0,0 +1,43 @@
+---
+title: Plans Documentation Index
+tier: reference
+domains: [plans]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of plans documentation
+---
+
+# Plans Documentation
+
+> Planning documents, roadmaps, proposals
+
+## Overview
+
+- **Total Documents:** 0
+- **Domain:** `plans/`
+- **Category:** advanced
+- **Load Priority:** 3/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: plan, plans, planning, roadmap, proposal, proposals, rfc, design-doc, specification, spec
+
+## Related Domains
+
+- [Agents](../agents/) - Expert agent documentation, specialty matrix
+- [Backups](../backups/) - Backup/restore guides, disaster recovery
+- [Troubleshooting](../troubleshooting/) - Debug guides, common issues, solutions
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/plans/REGISTRY.md

@@ -0,0 +1,38 @@
+---
+title: Plans Registry
+tier: reference
+domains: [plans]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for plans documentation
+---
+
+# Plans Registry
+
+> Quick reference for planning documents, roadmaps, proposals.
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 0 |
+| Category | advanced |
+| Load Priority | 3/10 |
+
+## Documents
+
+*No documents in this domain yet.*
+
+## Keywords
+
+`plan` `plans` `planning` `roadmap` `proposal` `proposals` `rfc` `design-doc` `specification` `spec` `milestone` `timeline` `schedule` `project` `initiative`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/procedures/INDEX.md

@@ -0,0 +1,42 @@
+---
+title: Procedures Documentation Index
+tier: reference
+domains: [procedures]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Complete listing of procedures documentation
+---
+
+# Procedures Documentation
+
+> Step-by-step operational procedures (SOP)
+
+## Overview
+
+- **Total Documents:** 1
+- **Domain:** `procedures/`
+- **Category:** features
+- **Load Priority:** 6/10
+
+## Documents
+
+### Guides
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [Plan Completion and Archive](plan-completion-and-archive.md) | active | 2026-08-31 | 812 |
+
+## Keywords
+
+This domain covers: procedure, procedures, sop, standard-operating-procedure, step, steps, operational, operation, operations, runbook
+
+## Related Domains
+
+- [Workflows](../workflows/) - Process documentation, multi-step operations
+- [Features](../features/) - Feature implementation guides, admin docs
+- [Quickstart](../quickstart/) - Setup guides, dev workflow, onboarding
+
+---
+
+*Last updated: 2026-08-31*

package/.documentation/procedures/REGISTRY.md

@@ -0,0 +1,51 @@
+---
+title: Procedures Registry
+tier: reference
+domains: [procedures]
+status: active
+last_updated: '2026-08-31'
+version: '1.0.0'
+purpose: Quick reference for procedures documentation
+---
+
+# Procedures Registry
+
+> Quick reference for step-by-step operational procedures (sop).
+
+## At a Glance
+
+| Metric | Value |
+|--------|-------|
+| Documents | 1 |
+| Category | features |
+| Load Priority | 6/10 |
+
+## Active Documents
+
+- [Plan Completion and Archive](plan-completion-and-archive.md)
+
+## Recently Updated
+
+- [Plan Completion and Archive](plan-completion-and-archive.md) - 2026-08-31
+
+## By Status
+
+| Status | Count |
+|--------|-------|
+| active | 1 |
+| draft | 0 |
+| deprecated | 0 |
+| archived | 0 |
+
+## Keywords
+
+`procedure` `procedures` `sop` `standard-operating-procedure` `step` `steps` `operational` `operation` `operations` `runbook` `playbook` `checklist` `process` `manual`
+
+## See Also
+
+- [Full Index](INDEX.md) - Complete document listing
+- [Root Index](../INDEX.md) - All domains
+
+---
+
+*Last updated: 2026-08-31*