@thedecipherist/mdd 1.0.0

package/commands/mdd-lifecycle.md

@@ -0,0 +1,350 @@
+## REVERSE-ENGINEER MODE — `/mdd reverse-engineer [path or feature-id]`
+
+Triggered when arguments start with `reverse-engineer` or `reverse`. Generates or regenerates MDD documentation from existing source code.
+
+### Phase R1 — Determine scope
+
+**If a path or feature-id is given:**
+- If it matches an existing `.mdd/docs/*.md` — load that doc as the "existing doc" for comparison (regenerate mode).
+- If it's a file path — read that file as the only source (new doc mode).
+
+**If no argument is given:**
+- Scan `src/` for all TypeScript/source files.
+- Cross-reference against `source_files` fields in all `.mdd/docs/*.md`.
+- List files not registered in any doc. Ask the user which ones to document.
+
+### Phase R2 — Read source files (parallelized for multi-file scope)
+
+**Threshold rule:**
+- ≤ 3 source files: read directly in the main conversation — no agent overhead
+- 4+ source files: batch into parallel Explore agents (max 3), each reading a subset
+
+**When parallelism applies:** Primarily the no-argument case — scanning `src/` for undocumented files can surface many files at once. A single feature with many source files (e.g., a large module) also qualifies.
+
+#### Agent instructions (self-contained)
+
+Each agent receives:
+- Its assigned file paths
+- The inference checklist below
+- Explicit instruction: read the files and return structured inference output — do NOT write any files
+
+For each assigned file, infer:
+- **Purpose:** What does this file do? What problem does it solve?
+- **Data models:** TypeScript interfaces, types, Zod schemas
+- **API routes:** Express/Fastify/etc. route definitions and their handlers
+- **Business rules:** Conditional logic, validation, state transitions
+- **Dependencies:** What other modules does it import?
+- **Edge cases:** Error handling patterns, guard clauses
+
+#### What each agent returns
+
+One block per assigned file:
+```
+File: <path>
+Purpose: <1–2 sentences>
+Data models: <list of types/interfaces with key fields>
+API routes: <list of routes with method + path>
+Business rules: <key validation, state logic>
+Dependencies: <imports from other project modules>
+Edge cases: <error handlers, guard clauses>
+```
+
+#### Main conversation: synthesize
+
+After all agents return, synthesize their output into Phase R3 (draft the doc). The main conversation is the only one that writes files.
+
+**Fallback:** If any agent fails, read that batch of files directly in the main conversation.
+
+### Phase R3 — Draft the doc
+
+Draft a complete feature doc following the Phase 3 template. Set:
+- `last_synced: <today>`
+- `status: draft` (since business intent may be incomplete)
+- `phase: reverse-engineered`
+
+**In regenerate mode:** Show the existing doc alongside the new draft:
+```
+📋 Regeneration Comparison: <NN>-<feature-name>
+
+Existing doc sections:     New draft sections:
+  Purpose: ...               Purpose: ... (updated)
+  Architecture: ...          Architecture: ... (same)
+  API Endpoints: ...         API Endpoints: ... (3 new routes found)
+  Business Rules: ...        Business Rules: ... (changed)
+
+Changes: 2 sections updated, 1 section unchanged, 1 section added
+```
+
+Ask: "Merge new draft into existing doc? (yes / keep existing / show full diff)"
+
+**In new doc mode:** Show the full draft and ask: "Does this accurately describe the feature? Anything to add or change?"
+
+### Phase R4 — Save and optionally generate test skeletons
+
+After user confirmation, write the doc. Then ask:
+"Generate test skeletons from the inferred endpoints and business rules? (yes / no)"
+
+If yes, follow Phase 4 logic using the newly written doc.
+
+**Always disclose limitations before saving:**
+```
+⚠️  Reverse-engineer limitations:
+   - "Purpose" section is inferred — review business intent carefully
+   - Implicit constraints (SLAs, compliance, product decisions) are not captured
+   - Confirm accuracy before treating this doc as the source of truth
+```
+
+---
+
+## GRAPH MODE — `/mdd graph`
+
+Triggered when arguments start with `graph`. Shows the cross-feature dependency map, plus initiative/wave structure if present.
+
+### Phase G1 — Build dependency graph
+
+Read all `.mdd/docs/*.md` (including `archive/`). For each doc, extract `id`, `title`, `status`, and `depends_on`.
+
+Build a directed graph: edge A → B means "A depends on B" (B must exist for A to work).
+
+**Initiative/wave graph** (only shown if `.mdd/initiatives/` exists): Also read all initiative and wave files. Build a second graph showing the initiative → wave → feature doc hierarchy.
+
+### Phase G2 — Detect issues
+
+**Broken dependency:** A doc lists a deprecated or archived feature in `depends_on`.
+
+**Risky dependency:** A `status: complete` feature depends on a `status: in_progress` or `status: draft` feature.
+
+**Task dependency:** A feature doc lists a task doc (`type: task`) in `depends_on`. Tasks are one-off and frozen — they carry no ongoing contract. Remove the task ID from `depends_on` and reference the relationship in Architecture or Dependencies prose instead.
+
+**Orphan:** A feature with no `depends_on` and no other feature depending on it.
+
+**Wave/initiative issues:**
+- A wave's `docPath` points to a feature doc that does not exist → broken link
+- A wave references a `dependsOn` wave that is not in the same initiative → invalid (cross-initiative deps not supported)
+- A feature doc whose slug appears in a wave but has no `docPath` set and status is `complete` → doc missing for completed feature
+
+### Phase G3 — Render
+
+```
+📊 MDD Dependency Graph
+
+Dependencies (A depends on → B):
+
+  06-command-system ──────────────────► 01-project-scaffolding
+  09-integrations ────────────────────► 06-command-system
+  04-content-builder ─────────────────► 03-database-layer
+  05-testing-framework ───────────────► 03-database-layer
+
+Orphans (no dependencies, no dependents):
+  07-github-pages
+  08-quality-gates
+
+Issues:
+  ⚠️  09-integrations depends on 06-command-system (status: in_progress) — risky
+  ❌  05-testing-framework depends on 10-mdd-refinements (deprecated) — broken
+```
+
+**Initiative/wave section** (appended when initiatives exist):
+
+```
+📋 Initiative / Wave Hierarchy
+
+  auth-system (active, v2)
+    ├─ wave-1: Auth Foundation [complete] ✓ 3/3 features
+    └─ wave-2: Auth Hardening [active]    ● 1/2 features
+         ├─ auth-2fa       → docs/18-auth-2fa.md        ✅
+         └─ auth-rate-limit → (no doc yet)              ❓
+
+Issues:
+  ❓  auth-system / wave-2 / auth-rate-limit — complete in wave but no doc path set
+```
+
+**Ops Runbooks section** (appended when `.mdd/ops/` has files):
+
+```
+📦 Ops Runbooks
+
+  swarmk-dokploy      — 4 services, 2 regions (eu-west canary → us-east primary)
+  rulecatch-dokploy   — 10 services, 2 regions (eu-west canary → us-east primary)
+
+Service health (last runop):
+  swarmk-dokploy:     all healthy ✓ (2026-04-17)
+  rulecatch-dokploy:  api ✗ failing in eu-west (2026-04-16) → run /mdd runop rulecatch-dokploy
+```
+
+Save the graph to `.mdd/audits/graph-<date>.md`.
+
+---
+
+## UPGRADE MODE — `/mdd upgrade`
+
+Triggered when arguments start with `upgrade`.
+
+Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) across ALL `.mdd/docs/*.md` files without touching doc content. Safe to run multiple times — already-present fields are never overwritten.
+
+**Use case:** projects that used MDD before these fields were introduced, or after importing docs from another project. Running `/mdd upgrade` converts all UNTRACKED docs to IN SYNC in one pass.
+
+---
+
+### Phase UP1 — Inventory
+
+1. Glob `.mdd/docs/*.md` (and `.mdd/docs/archive/*.md` if it exists). Collect all paths.
+2. For each doc, read its frontmatter only (up to the closing `---` line).
+3. Build an inventory table:
+
+```
+📋 Upgrade Inventory
+
+Doc                              | last_synced | status | phase
+─────────────────────────────────|─────────────|────────|──────────────
+01-project-scaffolding           | ❌ missing  | ❌     | ❌
+02-profile-system                | ❌ missing  | ✅     | ❌
+03-database-layer                | ✅ present  | ✅     | ✅
+...
+
+Docs needing upgrade: <N> of <total>
+Fields to add:
+  last_synced — <N> docs
+  status      — <N> docs
+  phase       — <N> docs
+```
+
+4. If 0 docs need upgrade → report "All docs are up to date. Nothing to patch." and stop.
+
+---
+
+### Phase UP2 — Infer Defaults (per doc)
+
+For each doc that needs patching, infer sensible defaults. **Do NOT ask the user for each doc** — infer silently, then show the plan for confirmation.
+
+**`last_synced` inference:**
+
+The goal is the date the doc was last meaningfully worked on. Try in order:
+
+1. Check `git log --format="%as" --follow -- ".mdd/docs/<doc-file>.md" | head -1`  
+   → Use the most recent commit date for that doc file.
+2. If no git history (brand-new file not yet committed), use today's date.
+3. If git is unavailable, use today's date.
+
+**`status` inference:**
+
+1. Check the `phase` field (if it already exists):
+   - phase contains `all` → `complete`
+   - phase contains `implementation` or `6` → `in_progress`
+   - phase contains `draft` or `1`–`3` → `draft`
+2. No existing phase → check the doc title/purpose section for keywords:
+   - Contains "reverse-engineered" → `complete`
+   - File is in `archive/` → `deprecated`
+   - Otherwise → `complete` (most pre-existing docs represent finished features)
+3. Default: `complete`
+
+**`phase` inference:**
+
+1. If `status` resolved to `complete` → `all`
+2. If `status` resolved to `in_progress` → `implementation`
+3. If `status` resolved to `draft` → `documentation`
+4. If `status` resolved to `deprecated` → `deprecated`
+
+---
+
+### Phase UP3 — Show Plan + Confirm
+
+Present the inferred patches to the user before writing anything:
+
+```
+🔧 MDD Upgrade Plan
+
+<N> docs will be patched. Fields shown are ADDITIONS only — existing fields are untouched.
+
+  01-project-scaffolding.md
+    + last_synced: 2025-11-14   (from git: last commit on this doc)
+    + status: complete          (inferred: pre-existing doc, no phase field)
+    + phase: all                (inferred: status → complete)
+
+  02-profile-system.md
+    + last_synced: 2025-12-03   (from git: last commit on this doc)
+    + phase: all                (inferred: status already 'complete')
+
+  09-integrations.md
+    + last_synced: 2026-01-17   (from git: last commit on this doc)
+    + status: complete
+    + phase: all
+
+  ... (<N> more)
+
+Proceed? (yes / review each individually / cancel)
+```
+
+If the user says **"review each individually"**: walk through each doc one at a time, showing the inferred values and asking "Accept / Edit / Skip" before patching.
+
+If the user says **"yes"**: proceed to Phase UP4 with all inferred values.
+
+---
+
+### Phase UP4 — Patch Docs
+
+For each doc in the plan, patch the frontmatter block **non-destructively**:
+
+**Rules:**
+- Read the full file
+- Locate the opening `---` line and the closing `---` line
+- Parse all existing frontmatter key-value pairs
+- Add ONLY the missing fields — never modify existing ones
+- Write the patched frontmatter back, preserving all existing fields and the doc body exactly
+
+**Frontmatter field order** (when inserting):
+```yaml
+---
+id: ...
+title: ...
+edition: ...
+depends_on: [...]
+source_files: [...]
+routes: [...]
+models: [...]
+test_files: [...]
+data_flow: ...
+last_synced: <new>    ← insert here if missing
+status: <new>         ← insert here if missing
+phase: <new>          ← insert here if missing
+known_issues: []
+---
+```
+
+Insert new fields **before** `known_issues` to keep the canonical order.
+
+Report progress as you go:
+```
+Patching...
+  ✅ 01-project-scaffolding.md — added last_synced, status, phase
+  ✅ 02-profile-system.md — added last_synced, phase
+  ✅ 03-database-layer.md — skipped (all fields present)
+  ...
+```
+
+---
+
+### Phase UP5 — Verify + Rebuild Startup
+
+After all patches are applied:
+
+1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced`
+2. Trigger the `.mdd/.startup.md` rebuild (same logic as Status Mode)
+3. Report:
+
+```
+✅ MDD Upgrade Complete
+
+Docs patched:     <N>
+Fields added:
+  last_synced — <N> docs
+  status      — <N> docs
+  phase       — <N> docs
+Docs skipped:     <N> (all fields already present)
+
+Run `/mdd scan` to see current drift status across all docs.
+```
+
+---
+
+---

package/commands/mdd-manage.md

@@ -0,0 +1,340 @@
+## STATUS MODE — `/mdd status`
+
+Quick overview of MDD state for the project:
+
+1. **Scan `.mdd/docs/`** — count feature docs
+2. **Scan `.mdd/audits/`** — find latest audit report
+3. **Scan `.mdd/jobs/`** — detect any active audit job (see below)
+4. **Count tests** — `pnpm test:unit --reporter=json 2>/dev/null | jq '.numTotalTests'`
+5. **Count known issues** — grep `known_issues` across all docs
+6. **Read current mdd_version** — from `mdd.md` frontmatter (or `~/.claude/commands/mdd.md` if not local)
+7. **Scan all `.mdd/` files** — grep `mdd_version` from each, group by version number
+8. **Scan `.mdd/initiatives/`** — count initiative files, group by status
+9. **Scan `.mdd/waves/`** — count wave files, group by status; for each active wave count complete vs total features
+
+**Audit in progress detection:** If any `jobs/audit-*/` folder exists, count manifest entries by state (`[ ]`, `[~]`, `[x]`, `[!]`, `[e]`) from its `MANIFEST.md`. Show as a warning line in the status output.
+
+Present:
+```
+📊 MDD Status
+
+⚠️  Audit in progress: .mdd/jobs/audit-<date>/ (<done>/<total> files complete)
+   Run /mdd audit to resume or discard.
+   (omit this line entirely if no jobs/audit-*/ folder exists)
+
+Feature docs:     <N> files in .mdd/docs/
+Ops runbooks:     <N> files in .mdd/ops/
+Last audit:       <date> (<N> findings, <N> fixed, <N> open)
+Test coverage:    <N> unit tests, <N> E2E tests
+Known issues:     <N> tracked across <N> features
+Quality gates:    <N> files over 300 lines
+
+Initiatives:      <N> total (<N> active, <N> planned, <N> complete, <N> cancelled)
+  Active waves:   <wave-title> [<done>/<total> features complete]  (one line per active wave)
+  (shown only if .mdd/initiatives/ exists and has files; omit section entirely if directory is absent)
+
+MDD version:      v<N> (current)
+  v<N>: <N> files — up to date
+  v<N-1>: <N> files — run /install-mdd to update the command, then /mdd audit to refresh docs
+  v0 (unversioned): <N> files — created before versioning was introduced
+
+Drift check:
+  <N> features in sync
+  <N> features possibly drifted  ← run /mdd scan for details
+  <N> features untracked         ← no last_synced field yet
+
+Run `/mdd audit` to refresh, `/mdd scan` to see drift details, `/mdd plan-initiative` to start an initiative, `/mdd ops <description>` to create a deployment runbook, or `/mdd <feature>` to build something new.
+```
+
+If all files are on the current `mdd_version`, omit the version breakdown and just show: `MDD version: v<N> — all files up to date`
+
+**Drift check logic** (lightweight — no full git log, just a quick presence check):
+1. For each `.mdd/docs/*.md`, read `last_synced` from frontmatter.
+2. If `last_synced` is missing → untracked.
+3. If `last_synced` exists: run `git log --oneline --after="<last_synced>" -- <source_files>` for the first source file only (quick check). If output is non-empty → possibly drifted.
+4. Count each category and show totals. Full details go in SCAN MODE.
+
+### Rebuild `.mdd/.startup.md`
+
+After collecting status, rebuild the auto-generated zone of `.mdd/.startup.md`:
+
+1. Read the current `.mdd/.startup.md` (if it exists) and extract the **Notes section** — everything after the `---` divider line. This is the user's append-only zone and must be preserved exactly.
+2. Rebuild the **auto-generated section** (everything above `---`) with fresh data:
+   - `Generated: <YYYY-MM-DD>` (date only, no time)
+   - `Branch:` from `git branch --show-current`
+   - `Stack:` from `CLAUDE.md` or `claude-mastery-project.conf` if detectable, otherwise `(unknown)`
+   - `Features Documented:` sorted list of `.mdd/docs/*.md` filenames with status if detectable from frontmatter
+   - `Ops Runbooks:` sorted list of `.mdd/ops/*.md` filenames with status — omit section entirely if `.mdd/ops/` is empty
+   - `Last Audit:` from the most recent `.mdd/audits/report-*.md` — extract findings/fixed/open counts
+   - `Rules Summary:` static block (does not change)
+3. Write the rebuilt auto-generated section + `---` divider + preserved Notes section back to `.mdd/.startup.md`. Update `mdd_version` in the file's frontmatter to current.
+4. If no `.mdd/.startup.md` exists yet, create it fresh using the template with an empty Notes section, stamped with current `mdd_version`.
+
+---
+
+## NOTE MODE — `/mdd note`
+
+Triggered when arguments start with `note`. Three subcommands:
+
+```
+/mdd note "your note here"    -- append a timestamped note to .startup.md
+/mdd note list                -- print only the Notes section
+/mdd note clear               -- wipe the Notes section (asks for confirmation)
+```
+
+### `/mdd note "your note here"` — Append
+
+1. Read `.mdd/.startup.md`. If it does not exist, create it first using the startup template (same as generated by `/mdd status` with placeholder values), then continue.
+2. Find the `---` divider line.
+3. Append below the divider: `- [YYYY-MM-DD] your note here` (use today's date).
+4. Write the file back.
+5. Print: `Note added to .mdd/.startup.md`
+
+### `/mdd note list` — List Notes
+
+1. Read `.mdd/.startup.md`.
+2. Print everything after the `---` divider (the Notes section).
+3. If the Notes section is empty or contains only the placeholder text, print: `(no notes yet)`
+
+### `/mdd note clear` — Clear Notes
+
+1. Ask the user: `Clear all notes in .mdd/.startup.md? This cannot be undone. (yes/no)`
+2. If yes: rewrite the Notes section (everything after `---`) as `(no notes)`
+3. If no: abort with `Cancelled.`
+
+---
+
+---
+
+## SCAN MODE — `/mdd scan`
+
+Triggered when arguments start with `scan`. Detects features whose source files have changed since the last MDD session, and checks for initiative/wave drift.
+
+### Phase SC1 — Read all feature docs, ops runbooks, and initiative/wave files
+
+Read every `.mdd/docs/*.md` (excluding `archive/`) and every `.mdd/ops/*.md` (excluding `archive/`). For each, extract:
+- `last_synced` from frontmatter
+- `source_files` list from frontmatter (feature docs) or the ops doc slug for ops runbooks
+
+### Phase SC2 — Check each feature for drift (parallelized)
+
+After Phase SC1 has the full feature list (IDs, `last_synced`, `source_files`), delegate all git log checks to a **single Explore agent** rather than running them sequentially in the main conversation.
+
+**Why a single agent (not multiple):** `git log` commands are individually fast — the bottleneck is issuing them one at a time in the main conversation. One agent can run all of them in quick succession and return a complete classification table.
+
+#### Agent instructions (self-contained)
+
+The agent receives:
+- Complete feature list: each feature's ID, `last_synced` date, and `source_files`
+- Classification rules (below)
+- Explicit instruction: run the git checks and return a structured table — do NOT write any files
+
+For each feature, the agent runs:
+```bash
+# Check file existence
+ls <source_file> 2>/dev/null
+
+# Check for commits after last_synced (only if files exist)
+git log --oneline --after="<last_synced>" -- <source_file>
+```
+
+#### What the agent returns
+
+A classification table — one row per feature:
+
+```
+| Feature ID | Classification | Detail |
+|---|---|---|
+| 01-project-scaffolding | in_sync | last synced: 2026-03-15, no commits after |
+| 04-content-builder | drifted | 3 commits since 2026-03-01, latest: "fix: heading parser" |
+| 07-github-pages | broken | docs/index.html not found on disk |
+| 09-integrations | untracked | no last_synced field |
+```
+
+**Classifications:**
+- **untracked** — `last_synced` missing from frontmatter
+- **broken** — one or more `source_files` not found on disk
+- **drifted** — `last_synced` exists, files exist, commits found after `last_synced`
+- **in_sync** — `last_synced` exists, all files exist, no commits after `last_synced`
+
+#### Main conversation: build drift report
+
+After the agent returns its table, the main conversation writes the drift report. No file writes happen inside the agent.
+
+**Fallback:** If the agent fails, run git checks sequentially in the main conversation using the same logic.
+
+### Phase SC3 — Present drift report
+
+```
+🔍 MDD Scan — Drift Report
+Generated: <YYYY-MM-DD>
+
+  ✅ 01-project-scaffolding   — in sync (last synced: 2026-03-15)
+  ⚠️  04-content-builder       — DRIFTED (3 commits since 2026-03-01)
+                                  Latest: "fix: markdown heading parser"
+  ❌  07-github-pages           — broken reference (docs/index.html not found)
+  ❓  09-integrations           — untracked (no last_synced field)
+
+Summary: 1 in sync · 1 drifted · 1 broken · 1 untracked
+
+Recommended actions:
+  /mdd update 04   — re-sync content-builder doc with code
+  /mdd update 07   — fix broken file reference
+  /mdd update 09   — add last_synced by running update mode
+```
+
+**Initiative/wave drift check** (only shown if `.mdd/initiatives/` exists):
+
+For each initiative in `.mdd/initiatives/`:
+- Read its `version` field from frontmatter
+- For each of its waves (in `.mdd/waves/`), check that the wave's `initiativeVersion` matches the initiative's current `version`
+- If a wave's `initiativeVersion` is older → flag as stale (run `/mdd plan-sync <initiative-id>` to refresh)
+
+```
+Initiatives:
+  ✅ auth-system (v2) — all waves in sync
+  ⚠️  payment-flow (v3) — 1 stale wave
+       payment-flow-wave-2 (initiativeVersion: 2, initiative now: 3) → run /mdd plan-sync payment-flow
+```
+
+**Ops runbook drift check** (appended when `.mdd/ops/` has files):
+
+For each ops runbook, check `last_synced` against the last git commit on the runbook file itself. Since ops runbooks track live service state (not source files), drift means the runbook file hasn't been touched since the last `runop`.
+
+```
+Ops Runbooks:
+  ✅ swarmk-dokploy   — last runop: 2026-04-17
+  ⚠️  rulecatch-dokploy — runbook edited 3 days ago but no runop since → run /mdd runop rulecatch-dokploy
+```
+
+Save the full report to `.mdd/audits/scan-<date>.md`.
+
+---
+
+## UPDATE MODE — `/mdd update <feature-id>`
+
+Triggered when arguments start with `update`. Updates an existing feature doc to reflect code that has changed since the last MDD session.
+
+### Phase U1 — Load the feature
+
+Parse `<feature-id>` from arguments (e.g., `04` or `04-content-builder`). Find the matching `.mdd/docs/*.md` file. Read it fully.
+
+If the feature-id is not found, list all available docs and ask the user to pick one.
+
+### Phase U2 — Read current source files
+
+Read every file listed in `source_files` frontmatter. If a file is missing, note it as a broken reference — ask the user for the new path before continuing.
+
+### Phase U3 — Diff doc vs code
+
+Compare what the doc says against what the code actually does:
+- New functions, endpoints, or exports not in the doc
+- Removed or renamed functions that the doc still mentions
+- Data model fields that changed
+- Business rules that changed (different validation, new states)
+- New edge cases visible in error handling
+
+Write findings to `.mdd/audits/update-notes-<feature-id>-<date>.md`.
+
+### Phase U4 — Present changes
+
+```
+📝 Update Review: <NN>-<feature-name>
+
+Changes detected since <last_synced>:
+  + Added:   <new thing>
+  - Removed: <removed thing>
+  ~ Changed: <changed thing>
+
+Doc sections needing update:
+  - API Endpoints (new route: POST /api/v1/...)
+  - Business Rules (validation logic changed)
+
+Proceed with doc update? (yes / review findings first / cancel)
+```
+
+Wait for user confirmation.
+
+### Phase U5 — Rewrite affected sections
+
+Rewrite ONLY the sections that changed. Preserve:
+- `known_issues` section (don't remove existing issues)
+- `depends_on` list (only add, never remove without asking)
+- Any manually written prose that is still accurate
+
+After rewriting, update frontmatter:
+- `last_synced: <today's date>`
+- `status:` — ask the user if they want to update the status (e.g., draft → complete)
+- `phase:` — update to reflect current state
+
+### Phase U6 — Regenerate test skeletons for new behaviors
+
+For any NEW documented behaviors (not previously in the doc), generate test skeleton entries and append them to the existing test file. Do NOT modify existing test implementations.
+
+Report:
+```
+✅ Update Complete: <NN>-<feature-name>
+
+Doc updated: .mdd/docs/<NN>-<feature-name>.md
+last_synced: <today>
+Sections rewritten: <list>
+New test skeletons: <N> appended to tests/unit/<feature-name>.test.ts
+
+Branch: <current branch>
+```
+
+---
+
+## DEPRECATE MODE — `/mdd deprecate <feature-id>`
+
+Triggered when arguments start with `deprecate`. Archives a feature cleanly.
+
+### Phase D1 — Load + impact check
+
+Find and read the target feature doc. Then scan all other `.mdd/docs/*.md` for any that list this feature in `depends_on`. Build the impact list.
+
+### Phase D2 — Present impact
+
+```
+🗑️  Deprecate: <NN>-<feature-name>
+
+This will:
+  - Set status: deprecated in the doc frontmatter
+  - Move doc to .mdd/docs/archive/<NN>-<feature-name>.md
+
+Dependents (docs that depend on this feature):
+  - 05-testing-framework (depends_on includes this)
+  - 09-integrations (depends_on includes this)
+
+Source files registered:
+  - src/handlers/content.ts
+  - scripts/build-content.ts
+
+Test files registered:
+  - tests/unit/content-builder.test.ts
+
+Deprecate? (yes / review dependents first / cancel)
+```
+
+If user says yes:
+
+### Phase D3 — Archive
+
+1. Set `status: deprecated` and `last_synced: <today>` in the doc frontmatter.
+2. Create `.mdd/docs/archive/` directory if it doesn't exist.
+3. Move the doc file to `.mdd/docs/archive/`.
+4. For each dependent doc, add an entry to its `known_issues`: `<NN>-<feature-name> has been deprecated — review this feature's dependency.`
+5. Ask the user separately: "Delete source files? (yes / no)" and "Delete test files? (yes / no)" — never auto-delete.
+6. Rebuild `.mdd/.startup.md`.
+
+Report:
+```
+✅ Deprecated: <NN>-<feature-name>
+
+Doc archived: .mdd/docs/archive/<NN>-<feature-name>.md
+Dependents flagged: <N> docs updated with known_issues warning
+Source files: <kept/deleted per user choice>
+Test files: <kept/deleted per user choice>
+```
+
+---