@theglitchking/persistent-planning 3.1.0 → 3.4.1

package/.documentation/procedures/REGISTRY.md

@@ -3,7 +3,7 @@ title: Procedures Registry
 tier: reference
 domains: [procedures]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for procedures documentation
 ---
@@ -16,23 +16,25 @@ purpose: Quick reference for procedures documentation
 
 | Metric | Value |
 |--------|-------|
-| Documents | 1 |
+| Documents | 2 |
 | Category | features |
 | Load Priority | 6/10 |
 
 ## Active Documents
 
 - [Plan Completion and Archive](plan-completion-and-archive.md)
+- [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md)
 
 ## Recently Updated
 
+- [Plugin update delivery — what actually runs, and when](plugin-update-delivery.md) - 2026-09-04
 - [Plan Completion and Archive](plan-completion-and-archive.md) - 2026-08-31
 
 ## By Status
 
 | Status | Count |
 |--------|-------|
-| active | 1 |
+| active | 2 |
 | draft | 0 |
 | deprecated | 0 |
 | archived | 0 |
@@ -48,4 +50,4 @@ purpose: Quick reference for procedures documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

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

@@ -149,3 +149,37 @@ untouched and the update check still works.
 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.
+
+
+## Completion also gates on mandatory tasks (3.3.0+)
+
+"Every checkbox checked" is necessary but no longer sufficient. A plan containing any
+task with `mandatory: true` whose `status:` is not `done` (or `archived`) reads
+`in progress` however the boxes add up, and `archive-plan.sh` refuses it through the
+same pre-flight — there is still exactly one implementation of the rule.
+
+Plans with no `mandatory:` frontmatter are unaffected.
+
+Symptoms and fixes: [Plan never reads complete](../troubleshooting/plan-never-reads-complete.md).
+
+
+## What counts, and what does not (3.3.1+)
+
+- **Checkboxes** are body content and are counted anywhere *except* inside a fenced code
+  block. A quoted example is documentation, not work. An unterminated fence swallows the
+  rest of the file — the safe direction, since ambiguous content is not counted as
+  outstanding.
+- **`status:` and `mandatory:`** are frontmatter fields and are read *only* from the
+  leading `---` block. They are never matched in prose, tables or fenced examples, which
+  is stricter than fence-stripping alone.
+
+
+## What is tracked (3.4.0+)
+
+Active plans are committed; only `.planning/.archive/` is gitignored. v1.0.0 ignored the
+whole `.planning/` tree, which contradicted this procedure, `CLAUDE.md`, and the archive
+rationale itself — and in lg mode, chosen because a team exists, it guaranteed no
+teammate ever received the plans.
+
+Repos carrying the old blanket line keep it: the init scripts warn once and never rewrite
+a user's `.gitignore`. Replace `.planning/` with `.planning/.archive/` to start sharing.

package/.documentation/procedures/plugin-update-delivery.md

@@ -0,0 +1,106 @@
+---
+title: Plugin update delivery — what actually runs, and when
+tier: guide
+domains:
+  - procedures
+audience:
+  - developers
+tags:
+  - migration
+status: active
+last_updated: '2026-09-04'
+version: 1.0.0
+purpose: What actually executes on each of the two distribution paths, why a marketplace
+  install never runs npm postinstall, and how to ship a fix that repairs existing installs.
+estimated_read_time: 3 minutes
+word_count: 539
+last_validated: '2026-09-04'
+backlinks: []
+---
+
+# Plugin update delivery — what actually runs, and when
+
+This package ships down two paths. They execute **different code at different times**,
+and a fix delivered through the wrong one reaches nobody. Read this before shipping any
+change that has to repair or migrate an existing install.
+
+## The two paths
+
+| | npm package | Claude Code marketplace plugin |
+|---|---|---|
+| Installed at | `node_modules/@theglitchking/persistent-planning` | `~/.claude/plugins/cache/persistent-planning-marketplace/persistent-planning/<version>/` |
+| Runs `postinstall`? | **yes** | **no** |
+| `node_modules` present? | yes | **no — the plugin cache has none** |
+| Runtime resolved from | local `node_modules` | shared `~/.claude/plugins/npm-cache/node_modules/` |
+| Runs every session | SessionStart hook | SessionStart hook |
+
+## The constraint
+
+**A marketplace install never runs npm postinstall.**
+
+So `runPostinstall()` — and therefore the skill linker, the reclaim, and the version
+marker — never execute on a marketplace update. A repair wired only into postinstall
+ships to npm consumers and silently misses every marketplace consumer.
+
+That is not a corner case. In issue #10 the broken population *was* the marketplace
+consumers, precisely because they were the ones postinstall could never reach.
+
+`runPostinstall()` also returns `null` when `INIT_CWD` equals the package root
+(dev-in-place), which is why this repo has no `.claude/skills/persistent-planning` of
+its own.
+
+## The rule
+
+> **Anything that must reach an existing install goes through the SessionStart hook.**
+> It is the only code that runs every session in both shapes.
+
+`hooks/session-start.js` `autoRepair()` is the reference implementation:
+
+- **Fast path first.** Two `lstat`s settle the common "nothing to do" case before any
+  work happens. Never make a healthy install pay.
+- **Once per plugin version.** Stamped as `repairedSkillsForVersion` in
+  `.claude/persistent-planning.json`. Stamped *regardless of outcome*, so a repair that
+  cannot succeed does not retry every session; a later release moves the version and
+  gets one fresh attempt.
+- **Policy-gated.** `auto` repairs, `nudge` warns only, `off` does nothing. A user who
+  turned updates off did not consent to filesystem mutation.
+- **Spawned, not imported.** The migration runs in a child process with a timeout, so a
+  failure is contained.
+- **Fails open.** Every path is wrapped. A broken migration must never cost someone
+  their session start.
+- **Never let a dependency be fatal.** Load the runtime with `await import()` in a
+  try/catch. A static import makes an unresolvable dependency fatal for the whole hook,
+  including the repair — the delivery path must survive what it is delivering a fix for
+  (#18). Only the update check genuinely needs the runtime.
+- **Stamp on success, never on failure.** Marking a version done after a failed attempt
+  turns a transient problem into a permanent one: the repair never runs again, even once
+  the cause is gone. Retrying costs one spawn per session while genuinely drifted.
+- **One stdout write.** The runtime owns the single `SessionStart` JSON response and
+  exposes no append hook; a second response line is invalid. Merge into the existing
+  intercept.
+
+## Release checklist addendum
+
+The version appears in **three** places that must match — `package.json`,
+`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (both `metadata.version`
+and the plugin entry). See `CLAUDE.md`.
+
+Two more things to verify for a migration release:
+
+1. **The `files` array actually ships the new code.** v3.0.0 shipped broken because
+   `scripts/` and `templates/` were missing from it. Check with `npm pack --dry-run` and
+   grep the listing for the files you added.
+2. **Test from a marketplace-shaped fixture** — no `node_modules`, no postinstall — not
+   from `npm install`. A test that passes under `npm install` proves nothing about the
+   population that is actually broken. `tests/run.sh` builds exactly this fixture.
+
+If a fix depends on a new `@theglitchking/claude-plugin-runtime`, it needs a runtime
+publish, a dependency-range bump here, and a coordinated rollout — marketplace consumers
+resolve the runtime from a shared cache, not a vendored copy. Preferring a change that
+keeps the runtime unchanged is usually worth real effort; the issue #10 reclaim is
+deliberately ordered *before* the runtime's linker for that reason.
+
+## Related
+
+- [Skill linking and reclaim](../architecture/skill-linking-and-reclaim.md)
+- [Stale skill directory](../troubleshooting/stale-skill-dir-drift.md)

package/.documentation/quickstart/INDEX.md

@@ -3,7 +3,7 @@ title: Quickstart Documentation Index
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of quickstart documentation
 ---
@@ -39,4 +39,4 @@ This domain covers: quickstart, quick-start, getting-started, setup, install, in
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/quickstart/REGISTRY.md

@@ -3,7 +3,7 @@ title: Quickstart Registry
 tier: reference
 domains: [quickstart]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for quickstart documentation
 ---
@@ -48,4 +48,4 @@ purpose: Quick reference for quickstart documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/reference/INDEX.md

@@ -3,7 +3,7 @@ title: Reference Documentation Index
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of reference documentation
 ---
@@ -14,7 +14,7 @@ purpose: Complete listing of reference documentation
 
 ## Overview
 
-- **Total Documents:** 1
+- **Total Documents:** 3
 - **Domain:** `reference/`
 - **Category:** development
 - **Load Priority:** 7/10
@@ -27,6 +27,13 @@ purpose: Complete listing of reference documentation
 |----------|--------|---------|-------|
 | [workspace.json schema](workspace-json.md) | active | 2026-05-07 | 358 |
 
+### References
+
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [`mandatory:` task frontmatter](mandatory-frontmatter.md) | active | 2026-09-04 | 270 |
+| [Skill version marker (`.version`)](skill-version-marker.md) | active | 2026-09-04 | 295 |
+
 ## Keywords
 
 This domain covers: schema, frontmatter, workspace.json, field, enum, cli, flags, reference, contract
@@ -39,4 +46,4 @@ This domain covers: schema, frontmatter, workspace.json, field, enum, cli, flags
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/reference/REGISTRY.md

@@ -3,7 +3,7 @@ title: Reference Registry
 tier: reference
 domains: [reference]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for reference documentation
 ---
@@ -16,23 +16,27 @@ purpose: Quick reference for reference documentation
 
 | Metric | Value |
 |--------|-------|
-| Documents | 1 |
+| Documents | 3 |
 | Category | development |
 | Load Priority | 7/10 |
 
 ## Active Documents
 
+- [`mandatory:` task frontmatter](mandatory-frontmatter.md)
+- [Skill version marker (`.version`)](skill-version-marker.md)
 - [workspace.json schema](workspace-json.md)
 
 ## Recently Updated
 
+- [`mandatory:` task frontmatter](mandatory-frontmatter.md) - 2026-09-04
+- [Skill version marker (`.version`)](skill-version-marker.md) - 2026-09-04
 - [workspace.json schema](workspace-json.md) - 2026-05-07
 
 ## By Status
 
 | Status | Count |
 |--------|-------|
-| active | 1 |
+| active | 3 |
 | draft | 0 |
 | deprecated | 0 |
 | archived | 0 |
@@ -48,4 +52,4 @@ purpose: Quick reference for reference documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

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/.documentation/security/INDEX.md

@@ -3,7 +3,7 @@ title: Security Documentation Index
 tier: reference
 domains: [security]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of security documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: security, auth, authentication, authorization, oauth, jwt, k
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/security/REGISTRY.md

@@ -3,7 +3,7 @@ title: Security Registry
 tier: reference
 domains: [security]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for security documentation
 ---
@@ -35,4 +35,4 @@ purpose: Quick reference for security documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/standards/INDEX.md

@@ -3,7 +3,7 @@ title: Standards Documentation Index
 tier: reference
 domains: [standards]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of standards documentation
 ---
@@ -40,4 +40,4 @@ This domain covers: standard, standards, convention, conventions, pattern, patte
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/standards/REGISTRY.md

@@ -3,7 +3,7 @@ title: Standards Registry
 tier: reference
 domains: [standards]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for standards documentation
 ---
@@ -50,4 +50,4 @@ purpose: Quick reference for standards documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

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

@@ -25,7 +25,7 @@ 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**
+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
@@ -123,3 +123,23 @@ npm test
 | 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

@@ -3,7 +3,7 @@ title: Testing Documentation Index
 tier: reference
 domains: [testing]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of testing documentation
 ---
@@ -39,4 +39,4 @@ This domain covers: test, testing, tests, unit, unit-test, integration, integrat
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

package/.documentation/testing/REGISTRY.md

@@ -3,7 +3,7 @@ title: Testing Registry
 tier: reference
 domains: [testing]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Quick reference for testing documentation
 ---
@@ -48,4 +48,4 @@ purpose: Quick reference for testing documentation
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*

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

@@ -86,3 +86,41 @@ never failed is not known to test anything.
 | 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.
+
+
+## The marketplace-shaped fixture
+
+The skill-reclaim tests (issue #10) build a consumer workspace with **no
+`node_modules`**, mirroring a Claude Code marketplace install — the shape that never
+runs npm postinstall, and the shape that was actually broken. Driving the SessionStart
+hook against it proves a repair lands with no `npm install` anywhere in the path.
+
+A test that only passes under `npm install` proves nothing about that population. See
+[Plugin update delivery](../procedures/plugin-update-delivery.md).
+
+## Assert by diff, not by feature-grep
+
+When checking that generated output matches a template, `diff` it. During triage of
+issue #10 a keyword count (`phases: 6 | closers: 2`) reported two known-stale copies as
+healthy; only `diff` exposed the 23-line gap, including an entirely missing
+`## On Completion` block.
+
+Likewise, assertions against the SessionStart payload parse it as JSON rather than
+string-matching. The failure being guarded is an invalid second response line — a
+substring check would pass on malformed output.
+
+
+## Assert after mutation, not at render
+
+The ordering rule for the mandatory closers went unenforced for a long time while a
+test claimed to cover it. That test asserted the order of two checkbox lines in a
+*freshly rendered template* — which can never be wrong, because nothing had happened to
+it yet.
+
+Assertions about an invariant must mutate the plan first: create a phase, add several
+tasks, then check the closers are still last. The issue #12 block does this throughout,
+including against a hand-reordered, partially-checked, annotated list.
+
+The same instinct applies elsewhere in this suite: verify generated output by `diff`
+rather than keyword count, and parse the SessionStart payload as JSON rather than
+string-matching it.

package/.documentation/troubleshooting/INDEX.md

@@ -3,7 +3,7 @@ title: Troubleshooting Documentation Index
 tier: reference
 domains: [troubleshooting]
 status: active
-last_updated: '2026-08-31'
+last_updated: '2026-09-04'
 version: '1.0.0'
 purpose: Complete listing of troubleshooting documentation
 ---
@@ -14,20 +14,20 @@ purpose: Complete listing of troubleshooting documentation
 
 ## Overview
 
-- **Total Documents:** 0
+- **Total Documents:** 2
 - **Domain:** `troubleshooting/`
 - **Category:** advanced
 - **Load Priority:** 6/10
 
 ## Documents
 
-*No documents in this domain yet.*
+### Guides
 
-To add a document:
+| Document | Status | Updated | Words |
+|----------|--------|---------|-------|
+| [A plan won't read COMPLETE](plan-never-reads-complete.md) | active | 2026-09-04 | 264 |
+| [Stale skill directory — commands run frozen code](stale-skill-dir-drift.md) | active | 2026-09-04 | 403 |
 
-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
@@ -40,4 +40,4 @@ This domain covers: troubleshooting, troubleshoot, debug, debugging, issue, issu
 
 ---
 
-*Last updated: 2026-08-31*
+*Last updated: 2026-09-04*