@thedecipherist/mdd 1.4.0 → 1.5.1

package/README.md

@@ -4,7 +4,7 @@
 
 # MDD - Manual-Driven Development for Claude Code
 
-> **One command. Twenty-three modes. Complete feature lifecycle from documentation to verified deployment.**
+> **One command. Twenty-four modes. Complete feature lifecycle from documentation to verified deployment.**
 
 <p align="center">
   <a href="https://thedecipherist.github.io/mdd">
@@ -42,7 +42,7 @@ Then in Claude Code:
 - [How It Works](#how-it-works)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [All 21 Modes at a Glance](#all-21-modes-at-a-glance)
+- [All 24 Modes at a Glance](#all-24-modes-at-a-glance)
 - [Build Mode - Feature Development](#build-mode--feature-development)
 - [Audit Mode - Code Review](#audit-mode--code-review)
 - [Status & Notes](#status--notes)
@@ -236,7 +236,7 @@ Every feature doc and ops runbook has a `tags:` field (4–8 domain-concept keyw
 
 ---
 
-## All 22 Modes at a Glance
+## All 24 Modes at a Glance
 
 ```
 /mdd <feature description>                 Build Mode - Document, plan, and implement
@@ -245,6 +245,7 @@ Every feature doc and ops runbook has a `tags:` field (4–8 domain-concept keyw
 /mdd scan                                  Detect features whose source files changed
 /mdd update <feature-id>                   Re-sync a feature doc after code changes
 /mdd rebuild-tags [--force]                Generate tags for all docs and rebuild .startup.md
+/mdd connect                               Rebuild the connections map from all docs
 /mdd note "text"                           Append a timestamped note to .mdd/.startup.md
 /mdd note list                             Print the Notes section
 /mdd note clear                            Wipe all notes (asks for confirmation)
@@ -585,7 +586,7 @@ Notes are timestamped and survive session resets.
 
 ### `/mdd scan`
 
-Detects which features have drifted since their last MDD session. Uses a single Explore agent to run all git checks in parallel, then classifies each feature:
+Detects which features have drifted since their last MDD session, and checks whether `connections.md` is stale. Uses a single Explore agent to run all git checks in parallel, then classifies each feature:
 
 | Classification | Meaning |
 |---|---|
@@ -845,6 +846,43 @@ Every `.mdd/docs/<NN>-<feature-name>.md` file uses this YAML frontmatter:
 
 ---
 
+## Connections Map
+
+Every MDD project maintains a committed `.mdd/connections.md` file — a pre-computed relationship map that gives Claude and the dashboard instant access to the full project graph without reading every doc.
+
+```bash
+/mdd connect    # regenerate manually at any time
+```
+
+It contains three sections:
+
+**Path Tree** — all feature docs grouped by their `path` field, sorted alphabetically, ready for dashboard rendering:
+```
+Auth
+  ├── Login     02-auth-login    complete
+  └── OAuth     03-oauth-google  draft
+E-commerce
+  └── Cart      07-cart          in_progress
+```
+
+**Dependency Graph** — a Mermaid diagram of all `depends_on` relationships with status-coded nodes:
+```mermaid
+graph TD
+  A["07-cart"]:::in_progress --> B["02-auth-login"]:::complete
+  classDef complete fill:#00e5cc,color:#000
+  classDef in_progress fill:#ffaa00,color:#000
+  classDef draft fill:#888,color:#fff
+```
+
+**Source File Overlap** — files referenced by 2+ docs (co-change risk):
+```
+src/handlers/auth.ts → 02-auth-login, 03-oauth-google
+```
+
+**Kept in sync automatically** — every MDD operation that creates, modifies, archives, or upgrades a doc regenerates `connections.md` as its final step. `/mdd status` and `/mdd scan` detect and flag staleness. The file is committed to git (not gitignored) so it's always available without re-running any command.
+
+---
+
 ## The `.mdd/` Directory
 
 All MDD artifacts live in one place:
@@ -870,7 +908,8 @@ All MDD artifacts live in one place:
 │       ├── shard-N.md
 │       ├── agent-N-config.md
 │       └── agent-N-notes.md
-└── .startup.md                   # Auto-generated session context (read by Claude on start)
+├── .startup.md                   # Auto-generated session context (read by Claude on start)
+└── connections.md                # Pre-computed relationship map (path tree + Mermaid graph)
 ```
 
 `.mdd/audits/` and `.mdd/jobs/` are automatically added to `.gitignore` on first run. Everything else in `.mdd/` is committed - it's your project's knowledge base.

package/commands/mdd-build.md

@@ -610,7 +610,15 @@ where the agent patches the wrong thing because it accepted an external excuse t
    - `last_synced: <today>`
    - `mdd_version: <current from mdd.md frontmatter>`
 
-2. Display the completion signal:
+2. **Regenerate `.mdd/connections.md`:**
+   Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+   - **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as indented tree using `├──` / `└──` characters. Each leaf: `<path-leaf-segment>  <id>  <status>`.
+   - **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef` block for complete/in_progress/draft/deprecated.
+   - **Source overlap:** map source_file → docs that reference it. Include only files with 2+ docs.
+   - **Warnings:** broken `depends_on` refs, circular deps, docs missing `path`.
+   - **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count`, `connection_count`, `overlap_count`) and four sections: Path Tree, Dependency Graph, Source File Overlap, Warnings.
+
+3. Display the completion signal:
 ```
 ✅ MDD Complete: <Feature Name>
 
@@ -621,6 +629,7 @@ Blocks: <N>/<N> complete
 Tests: <N>/<N> passing
 Integration: verified (<feature type> — real environment)
 Typecheck: clean
+Connections: .mdd/connections.md updated
 
 New patterns established: <any new rules worth adding to CLAUDE.md>
 

package/commands/mdd-import-spec.md

@@ -12,9 +12,34 @@ Parse file path(s) from the arguments following `import-spec`. Multiple files ma
 
 For each file path:
 1. Verify the file exists. If a path does not exist, stop and report clearly: "File not found: `<path>`"
-2. Read the full content.
+2. Count the file's lines: `wc -l <path>`
+3. Read the full content using the strategy below.
 
-If multiple files are provided, merge all content into a single working document. Tag each section internally with its source filename (e.g. `<!-- source: rawpg-prompt-driver.md -->`) for traceability — these tags are used in the merge summary and content mapping display but are never written to output docs.
+**Reading strategy — always read the full file, never stop early:**
+
+Files under 2,000 lines: read in a single call.
+
+Files over 2,000 lines: read in sequential chunks of 2,000 lines each.
+
+```
+chunk 1: offset 0,    limit 2000
+chunk 2: offset 2000, limit 2000
+chunk 3: offset 4000, limit 2000
+... continue until offset >= total line count
+```
+
+After each chunk, append its headings and content to a running working document. Do not begin IS2 analysis until the final chunk has been read and the full working document is assembled. Report progress as you read:
+
+```
+Reading <filename> (<N> lines)...
+  chunk 1/N  (lines 1–2000)   ✓
+  chunk 2/N  (lines 2001–4000) ✓
+  ...
+  chunk N/N  (lines <X>–<end>) ✓
+Full file read. Proceeding to feature extraction.
+```
+
+If multiple files are provided, merge all content into a single working document after all files are fully read. Tag each section internally with its source filename (e.g. `<!-- source: rawpg-prompt-driver.md -->`) for traceability — these tags are used in the merge summary and content mapping display but are never written to output docs.
 
 ---
 
@@ -181,6 +206,16 @@ Trigger the `.mdd/.startup.md` rebuild:
 - Preserve the Notes zone exactly as-is
 - Update the generated date and current branch
 
+Then regenerate connections.md:
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+- **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as indented tree using `├──` / `└──` characters. Each leaf: `<path-leaf-segment>  <id>  <status>`.
+- **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+- **Source overlap:** build map of source_file → docs that reference it. Include only files with 2+ docs.
+- **Warnings:** broken `depends_on` refs (target doesn't exist), circular dependencies, docs missing `path`.
+- **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N>`, `overlap_count: <N>`) and four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
 Then report:
 
 ```
@@ -196,6 +231,7 @@ Docs created:
   ...
 
 Startup:   .mdd/.startup.md rebuilt
+Connections: .mdd/connections.md updated
 
 Next steps:
   /mdd <NN>         — start building any imported feature

package/commands/mdd-lifecycle.md

@@ -348,7 +348,14 @@ After all patches are applied:
 
 1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced` or `path`
 2. Trigger the `.mdd/.startup.md` rebuild (same logic as Status Mode)
-3. Report:
+3. **Regenerate `.mdd/connections.md`:**
+   Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+   - **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as indented tree using `├──` / `└──` characters. Each leaf: `<path-leaf-segment>  <id>  <status>`.
+   - **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef` block for complete/in_progress/draft/deprecated.
+   - **Source overlap:** map source_file → docs that reference it. Include only files with 2+ docs.
+   - **Warnings:** broken `depends_on` refs, circular deps, docs missing `path`.
+   - **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count`, `connection_count`, `overlap_count`) and four sections: Path Tree, Dependency Graph, Source File Overlap, Warnings.
+4. Report:
 
 ```
 ✅ MDD Upgrade Complete
@@ -359,6 +366,7 @@ Fields added:
   status      — <N> docs
   phase       — <N> docs
 Docs skipped:     <N> (all fields already present)
+connections.md: updated (<N> docs, <N> edges)
 
 Run `/mdd scan` to see current drift status across all docs.
 ```

package/commands/mdd-manage.md

@@ -70,6 +70,15 @@ After collecting status, rebuild the auto-generated zone of `.mdd/.startup.md`:
 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`.
 
+### Check `.mdd/connections.md` Freshness
+
+After rebuilding `.startup.md`, check connections.md:
+
+1. If `.mdd/connections.md` does not exist → report: `⚠️  connections.md missing — run /mdd connect to generate`
+2. Read `generated:` date from connections.md frontmatter. Find the most recent `last_synced` date across all docs.
+   - If `generated` < most recent `last_synced` → report: `⚠️  connections.md stale (generated: <X>, newest doc synced: <Y>) — run /mdd connect`
+   - If up to date → report: `✅ connections.md current (generated: <X>, <N> docs, <N> edges)`
+
 ---
 
 ## NOTE MODE — `/mdd note`
@@ -184,6 +193,7 @@ Recommended actions:
   /mdd update 07   — fix broken file reference
   /mdd update 09   — add last_synced by running update mode
   /mdd upgrade     — add path field to <N> docs missing it  ← omit this line when there are no docs missing path
+  /mdd connect     — rebuild connections.md if stale or missing
 ```
 
 **Initiative/wave drift check** (only shown if `.mdd/initiatives/` exists):
@@ -210,6 +220,13 @@ Ops Runbooks:
   ⚠️  rulecatch-dokploy — runbook edited 3 days ago but no runop since → run /mdd runop rulecatch-dokploy
 ```
 
+**Connections map check:**
+
+Check `.mdd/connections.md`:
+- Missing → classify as `broken` and include in findings: `❌  connections.md — missing (run /mdd connect)`
+- `generated:` older than most recent `last_synced` → classify as `drifted`: `⚠️  connections.md — stale (run /mdd connect)`
+- Up to date → `✅ connections.md — current`
+
 Save the full report to `.mdd/audits/scan-<date>.md`.
 
 ---
@@ -287,6 +304,16 @@ New test skeletons: <N> appended to tests/unit/<feature-name>.test.ts
 Branch: <current branch>
 ```
 
+After updating the doc, regenerate connections.md:
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+1. **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as an indented tree using `├──` / `└──` characters. Each leaf line: `<path-leaf-segment>  <id>  <status>`.
+2. **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+3. **Source overlap:** build a map of source_file → docs that reference it. Include only files with 2+ docs.
+4. **Warnings:** flag broken `depends_on` references (target does not exist), circular dependencies, docs missing `path` field.
+5. **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N edges>`, `overlap_count: <N overlap files>`) followed by four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
 ---
 
 ## DEPRECATE MODE — `/mdd deprecate <feature-id>`
@@ -331,6 +358,16 @@ If user says yes:
 5. Ask the user separately: "Delete source files? (yes / no)" and "Delete test files? (yes / no)" — never auto-delete.
 6. Rebuild `.mdd/.startup.md`.
 
+Then regenerate connections.md:
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+1. **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as an indented tree using `├──` / `└──` characters. Each leaf line: `<path-leaf-segment>  <id>  <status>`.
+2. **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+3. **Source overlap:** build a map of source_file → docs that reference it. Include only files with 2+ docs.
+4. **Warnings:** flag broken `depends_on` references (target does not exist), circular dependencies, docs missing `path` field.
+5. **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N edges>`, `overlap_count: <N overlap files>`) followed by four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
 Report:
 ```
 ✅ Deprecated: <NN>-<feature-name>
@@ -389,6 +426,16 @@ For each doc missing `tags:` (or all docs if `--force`):
 
 Trigger the `.mdd/.startup.md` rebuild (same logic as Status Mode — rebuild auto-generated zone, preserve Notes zone). The rebuilt startup now reflects tags on every feature and ops line.
 
+Then regenerate connections.md:
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+1. **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as an indented tree using `├──` / `└──` characters. Each leaf line: `<path-leaf-segment>  <id>  <status>`.
+2. **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+3. **Source overlap:** build a map of source_file → docs that reference it. Include only files with 2+ docs.
+4. **Warnings:** flag broken `depends_on` references (target does not exist), circular dependencies, docs missing `path` field.
+5. **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N edges>`, `overlap_count: <N overlap files>`) followed by four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
 ### Phase RT4 — Report
 
 ```
@@ -408,3 +455,27 @@ Run /mdd status to see the full updated startup snapshot.
 ```
 
 ---
+
+## CONNECT MODE — `/mdd connect`
+
+Triggered when arguments start with `connect`. Performs a full rebuild of `.mdd/connections.md` unconditionally — no staleness check, always regenerates from scratch.
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+1. **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as an indented tree using `├──` / `└──` characters. Each leaf line: `<path-leaf-segment>  <id>  <status>`.
+2. **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+3. **Source overlap:** build a map of source_file → docs that reference it. Include only files with 2+ docs.
+4. **Warnings:** flag broken `depends_on` references (target does not exist), circular dependencies, docs missing `path` field.
+5. **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N edges>`, `overlap_count: <N overlap files>`) followed by four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
+Report when done:
+```
+🔗 connections.md rebuilt
+
+  Docs:            <N>
+  Dependency edges: <N>
+  Source overlaps:  <N files referenced by 2+ docs>
+  Warnings:         <N> (or "none")
+
+✅ .mdd/connections.md updated (<today>)
+```

package/commands/mdd-plan.md

@@ -262,6 +262,16 @@ When all features are `complete`:
      - `mdd_version: <current from mdd.md frontmatter>`
 6. Rebuild `.mdd/.startup.md`.
 
+Then regenerate connections.md:
+
+**Regenerate `.mdd/connections.md`:**
+Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title, status, path, depends_on, source_files). Never read doc bodies. Then:
+- **Path tree:** sort docs by path alphabetically, then by id within the same path. Render as indented tree using `├──` / `└──` characters. Each leaf: `<path-leaf-segment>  <id>  <status>`.
+- **Mermaid graph:** one node per doc (short node ID), one `-->` edge per `depends_on` entry, `:::<status>` suffix on each node. Include `classDef complete fill:#00e5cc,color:#000`, `in_progress fill:#ffaa00,color:#000`, `draft fill:#888,color:#fff`, `deprecated fill:#555,color:#aaa`.
+- **Source overlap:** build map of source_file → docs that reference it. Include only files with 2+ docs.
+- **Warnings:** broken `depends_on` refs (target doesn't exist), circular dependencies, docs missing `path`.
+- **Write** `.mdd/connections.md` with YAML frontmatter (`generated: <today>`, `doc_count: <N>`, `connection_count: <N>`, `overlap_count: <N>`) and four sections: Path Tree, Dependency Graph (Mermaid), Source File Overlap, Warnings.
+
 ---
 
 ## PLAN-SYNC MODE — `/mdd plan-sync`

package/commands/mdd.md

@@ -115,7 +115,7 @@ Use whichever path contains `mdd-audit.md`. Store it as `$MDD_DIR` and use it fo
 - If arguments start with `audit` →
   **Read `$MDD_DIR/mdd-audit.md` then follow its AUDIT MODE instructions.**
 
-- If arguments start with `status`, `note`, `scan`, `update`, `deprecate`, or `rebuild-tags` →
+- If arguments start with `status`, `note`, `scan`, `update`, `deprecate`, `rebuild-tags`, or `connect` →
   **Read `$MDD_DIR/mdd-manage.md` then follow the relevant mode instructions.**
 
 - If arguments start with `import-spec` →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thedecipherist/mdd",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "MDD — Manual-Driven Development workflow for Claude Code",
   "type": "module",
   "bin": {