@thedecipherist/mdd 1.3.9 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 # MDD - Manual-Driven Development for Claude Code
 
-> **One command. Twenty-one 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,10 +245,12 @@ 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)
 /mdd deprecate <feature-id>                Archive a feature and flag all dependents
+/mdd import-spec <file> [file...]           Convert a spec doc into MDD feature docs
 /mdd reverse-engineer [path|feature-id]   Generate MDD docs from existing source code
 /mdd graph                                 Render the full cross-feature dependency map
 /mdd upgrade                               Batch-patch missing frontmatter across all docs
@@ -584,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 |
 |---|---|
@@ -624,6 +626,39 @@ Re-syncs a feature doc after its code has changed:
 
 ---
 
+## Import Spec Mode
+
+### `/mdd import-spec <file> [file...]`
+
+Converts one or more large spec or prompt documents — the kind produced by extended brainstorming sessions — into properly structured MDD feature docs. Nothing from the original spec is lost.
+
+```bash
+/mdd import-spec ~/specs/my-app-prompt.md
+/mdd import-spec spec-v1.md spec-v2.md spec-notes.md
+```
+
+**How it works:**
+
+1. **Read** — loads all spec files, merges content if multiple are provided
+2. **Extract + Group** — identifies distinct features and assigns each a `path` value (e.g. `Auth/Login`, `E-commerce/Cart`) before anything else
+3. **Auto-detect structure** — decides whether to create initiatives + waves + docs, waves + docs, or flat feature docs, based on path diversity and feature count:
+
+| Signal | Output |
+|--------|--------|
+| 3+ distinct root path areas AND 8+ features | Initiative → Waves → Feature docs |
+| 4–7 features in a coherent domain | Waves → Feature docs |
+| 1–3 focused features | Flat feature docs only |
+
+4. **Dry-run preview** — shows the complete proposed tree (paths, slugs, titles, content mapping, merge summary) before writing a single file. You can adjust or abort.
+5. **Write docs** — creates all feature docs with full frontmatter, populated sections, tags, and `path` fields
+6. **Rebuild** — updates `.mdd/.startup.md` to reflect the new docs
+
+**Content preservation:** Every decision, constraint, and edge case in the spec maps somewhere in the output. If something doesn't fit cleanly into a standard section, it goes into Business Rules or a Known Constraints note.
+
+**Duplicate handling:** Specs often revisit the same topic multiple times. Import-spec detects overlapping sections semantically, merges them into the best doc, and shows you exactly what was merged and why in the dry-run summary.
+
+---
+
 ## Feature Lifecycle
 
 ### `/mdd deprecate <feature-id>`
@@ -677,9 +712,9 @@ Saved to `.mdd/audits/graph-<date>.md`.
 
 ### `/mdd upgrade`
 
-Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) across all `.mdd/docs/*.md` files. Safe to run multiple times - already-present fields are never overwritten.
+Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`, `tags`, `path`) across all `.mdd/docs/*.md` files. Safe to run multiple times — already-present fields are never overwritten.
 
-Infers sensible defaults from git history, existing field values, and archive status. Shows a plan before writing anything.
+Infers sensible defaults from git history, existing field values, and archive status. For the `path` field, Claude reads each doc's title and purpose to propose a value — always shows a plan for confirmation before writing. After upgrade, run `/mdd rebuild-tags` to populate any empty `tags` fields.
 
 ---
 
@@ -793,6 +828,7 @@ Every `.mdd/docs/<NN>-<feature-name>.md` file uses this YAML frontmatter:
 | `phase` | Last completed phase name |
 | `mdd_version` | Version of MDD that created/last updated this doc |
 | `tags` | 4–8 domain-concept keywords surfaced in `.startup.md` so Claude can detect when a prompt relates to this feature (e.g. `[auth, jwt, login, sessions]`) |
+| `path` | Slash-delimited breadcrumb showing where this feature lives in the product (e.g. `Auth/Login`, `E-commerce/Cart/Checkout`). Used by dashboards and listing tools to group docs into a human-readable tree. Distinct from `depends_on` — this is for navigation, not build order. |
 | `known_issues` | Issues discovered during audits or implementation |
 
 **`depends_on` rules:**
@@ -800,6 +836,51 @@ Every `.mdd/docs/<NN>-<feature-name>.md` file uses this YAML frontmatter:
 - IDs must reference existing docs - `/mdd graph` detects broken references
 - Only add, never remove without discussion - removing breaks the dependency chain
 
+**`path` rules:**
+- Format: `Area/Section` or `Area/Section/Detail` — Title Case, slash-separated, 1–3 levels
+- Use product vocabulary, not code paths: `Auth/Login` not `src/handlers/auth`
+- Siblings must use identical parent spelling: if `Auth/Login` exists, new auth docs use `Auth` not `Authentication`
+- Set automatically by Claude in Build Mode Phase 3 (inferred from context, confirmed by user if ambiguous)
+- Missing `path` fields are detected by `/mdd scan` and batch-fixed by `/mdd upgrade`
+- Dashboards and listing tools use `path` to group docs into a human-readable tree view
+
+---
+
+## 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
@@ -827,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

@@ -192,6 +192,7 @@ status: draft
 phase: <last completed phase name, or "all" when fully built>
 mdd_version: <read from mdd.md frontmatter mdd_version field>
 tags: [<4-8 domain-concept keywords — systems touched, technology, feature names. NOT file paths>]
+path: <Area/Section>
 known_issues: []
 ---
 
@@ -234,6 +235,8 @@ known_issues: []
 
 **Always set `last_synced` to today's date** when writing or updating a feature doc. This is what SCAN MODE uses to detect drift. Set `status: draft` for new docs; update to `in_progress` when implementation begins, `complete` when Phase 7 is done.
 
+**Determine the `path` field** before writing the doc. Read the `path` values of all existing docs in `.mdd/docs/` to understand established product vocabulary and category names. Then ask: "What would a user navigate to in order to reach this feature?" — answer in their mental model of the product, not the code structure. Use 1–3 segments, Title Case, product vocabulary (e.g. `Auth/Login`, `E-commerce/Cart`, `Dashboard/Analytics`). Siblings must use identical parent spelling — if `Auth/Login` exists, use `Auth` not `Authentication`. If you can infer the path from context with confidence, set it and show the user. If genuinely ambiguous (feature could belong in 2+ places), ask: "Where does this feature live in the product? (e.g. `Auth/Login` or `Dashboard/Reports`)"
+
 **After writing the feature doc**, trigger the `.mdd/.startup.md` rebuild (same logic as in Status Mode — rebuild auto-generated zone, preserve Notes zone) so the Features list stays current.
 
 Show the completed doc to the user and ask: **"Does this accurately describe what you want to build? Anything to add or change?"**
@@ -607,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>
 
@@ -618,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

@@ -0,0 +1,216 @@
+## IMPORT SPEC MODE — `/mdd import-spec`
+
+Triggered when arguments start with `import-spec`.
+
+Reads one or more large spec or prompt documents — the kind produced by extended brainstorming sessions with Claude — and converts them into properly structured MDD feature docs. Every decision in the spec is preserved. Duplicate or overlapping topics are merged intelligently. Path grouping determines whether to create initiative/waves or flat docs.
+
+---
+
+### Phase IS1 — Read Spec Files
+
+Parse file path(s) from the arguments following `import-spec`. Multiple files may be space-separated or specified as a glob.
+
+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.
+
+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.
+
+---
+
+### Phase IS2 — Feature Extraction + Path Grouping
+
+This phase runs in two steps. Path grouping always runs before complexity determination because the number of distinct top-level path areas is the primary signal for initiative-scale scope.
+
+#### Step IS2a — Extract features
+
+Read the entire merged spec. Identify every distinct feature, system, subsystem, or bounded capability described. A "feature" is any topic that could become a standalone MDD doc — something with a purpose, decisions, constraints, and a clear scope.
+
+For each identified feature:
+- Name / title
+- Core purpose (1–2 sentences distilled from the spec)
+- All key decisions, constraints, business rules, and edge cases mentioned in the spec
+- Dependencies on other features identified in the same spec
+
+Track which spec sections contribute to each feature. When multiple spec sections cover the same concept (same feature re-discussed with refinements), **merge them** — do not create duplicate docs. When versions of the same decision conflict, keep the most specific or most recent version and note the discarded variant.
+
+#### Step IS2b — Assign paths
+
+Read all existing `.mdd/docs/*.md` `path` fields (if any exist) to learn the project's established vocabulary and casing conventions.
+
+For each identified feature, determine its `path` value:
+- Use the user's product vocabulary, not code module names
+- Title Case, 1–3 levels, `/`-separated
+- Siblings must use identical parent spelling (if `Auth/Login` exists, new auth docs use `Auth`, not `Authentication`)
+
+#### Step IS2c — Determine output structure
+
+Count distinct root-level path segments (top-level areas):
+
+| Signal | Structure |
+|--------|-----------|
+| 3+ distinct root areas AND 8+ features | Initiative + Waves + Feature docs |
+| 1–2 root areas AND 4–7 features | Waves + Feature docs (no initiative wrapper) |
+| Any root area count AND 1–3 features | Flat feature docs only |
+
+These thresholds are guidelines — apply judgment. A 3-feature spec spanning radically different domains can still warrant waves.
+
+---
+
+### Phase IS3 — Dry-Run Preview (mandatory gate)
+
+Before writing any files, display the complete proposed structure and wait for explicit user approval.
+
+```
+📋 Import Spec — Dry Run
+
+Source: <filename(s)>
+Features identified: <N>   Merged: <N> duplicate/overlapping topics
+
+Proposed structure: <Flat docs | Waves | Initiative: "<name>" → Waves>
+
+Path Tree:
+  <Root Area 1>
+    ├── <Section>              → <NN>-<slug>    (draft)
+    └── <Section>
+         └── <Sub-section>    → <NN>-<slug>    (draft)
+  <Root Area 2>
+    └── <Section>              → <NN>-<slug>    (draft)
+
+IDs assigned: <NN>–<NN> (continuing from existing <prev>)
+
+Merge summary:
+  "<path>" ← merged from: §<Spec Section A>, §<Spec Section B>
+  (one line per merged feature — omit if no merges)
+
+Content mapping:
+  <NN>-<slug>:   §<Spec Section> + §<Spec Section>
+  <NN>-<slug>:   §<Spec Section>
+
+Adjust paths, titles, or grouping? (approve / adjust / abort)
+```
+
+**If the user says "adjust":** accept their description of changes, re-run IS2 with that feedback applied, then show the preview again. Repeat until the user approves.
+
+**If the user says "abort":** stop. Write nothing.
+
+**Do not proceed to IS4 until the user explicitly approves.**
+
+---
+
+### Phase IS4 — Write Files
+
+**If initiative-scale was detected:** Create `.mdd/initiative.md` with:
+- `id`, `title`, `status: planning`, `created: <today>`
+- A brief initiative description derived from the spec's overall theme
+- Wave breakdown: one wave per major root path area or logical phase, each listing its feature doc slugs
+
+**For each feature doc in the approved plan:**
+
+1. Auto-number continuing from the highest existing doc number in `.mdd/docs/`
+2. Write a complete MDD feature doc at `.mdd/docs/<NN>-<slug>.md` using the canonical frontmatter structure:
+
+```markdown
+---
+id: <NN>-<slug>
+title: <Feature Title>
+edition: <project name or "Both">
+depends_on: [<IDs of other imported features this one depends on>]
+source_files: []
+routes: []
+models: []
+test_files: []
+data_flow: greenfield
+last_synced: <today YYYY-MM-DD>
+status: draft
+phase: documentation
+mdd_version: <read from mdd.md frontmatter>
+tags: [<4–8 domain-concept keywords>]
+path: <Area/Section>
+known_issues: []
+---
+
+# <NN> — <Feature Title>
+
+## Purpose
+
+<2–3 sentences from the merged spec content>
+
+## Architecture
+
+<How this feature fits into the system, derived from spec decisions>
+
+## Data Model
+
+<If the spec describes data structures — omit section if truly not applicable>
+
+## API Endpoints
+
+<If the spec describes endpoints — omit section if truly not applicable>
+
+## Business Rules
+
+<All decisions, constraints, validation rules, edge cases from the spec>
+
+## Dependencies
+
+<Other features this one requires, by doc ID>
+
+## Known Issues
+
+(none — imported from spec)
+```
+
+3. Tags: 4–8 domain-concept keywords. NOT file paths or spec section names.
+4. `depends_on`: if feature A was described in the spec as depending on feature B (also imported), use the IDs assigned in this run.
+
+**Progress report as you write:**
+```
+Writing docs...
+  ✅ <NN>-<slug>.md   (<path>)
+  ✅ <NN>-<slug>.md   (<path>)
+  ...
+```
+
+---
+
+### Phase IS5 — Rebuild .startup.md
+
+Trigger the `.mdd/.startup.md` rebuild:
+- Rebuild the auto-generated zone (Project Snapshot, Features Documented list with IDs, status, and tags)
+- 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:
+
+```
+✅ Import Spec Complete
+
+Source:    <filename(s)>
+Created:   <N> feature docs
+Structure: <Flat | Waves | Initiative + Waves>
+
+Docs created:
+  <NN>-<slug>   <path>   draft
+  <NN>-<slug>   <path>   draft
+  ...
+
+Startup:   .mdd/.startup.md rebuilt
+Connections: .mdd/connections.md updated
+
+Next steps:
+  /mdd <NN>         — start building any imported feature
+  /mdd audit        — run a full audit across all imported docs
+  /mdd upgrade      — add path fields to any pre-existing docs that are missing them
+  /mdd rebuild-tags — regenerate tags if any look thin
+```

package/commands/mdd-lifecycle.md

@@ -181,7 +181,7 @@ Save the graph to `.mdd/audits/graph-<date>.md`.
 
 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.
+Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`, `tags`, `path`) 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.
 
@@ -196,11 +196,11 @@ Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) acro
 ```
 📋 Upgrade Inventory
 
-Doc                              | last_synced | status | phase | tags
-─────────────────────────────────|─────────────|────────|───────|──────
-01-project-scaffolding           | ❌ missing  | ❌     | ❌    | ❌
-02-profile-system                | ❌ missing  | ✅     | ❌    | ✅
-03-database-layer                | ✅ present  | ✅     | ✅    | ❌
+Doc                              | last_synced | status | phase | tags | path
+─────────────────────────────────|─────────────|────────|───────|──────|──────
+01-project-scaffolding           | ❌ missing  | ❌     | ❌    | ❌   | ❌
+02-profile-system                | ❌ missing  | ✅     | ❌    | ✅   | ❌
+03-database-layer                | ✅ present  | ✅     | ✅    | ❌   | ✅
 ...
 
 Docs needing upgrade: <N> of <total>
@@ -209,6 +209,7 @@ Fields to add:
   status      — <N> docs
   phase       — <N> docs
   tags        — <N> docs (run /mdd rebuild-tags after upgrade to populate)
+  path        — <N> docs (Claude reads each doc's title + purpose to infer the value)
 ```
 
 4. If 0 docs need upgrade → report "All docs are up to date. Nothing to patch." and stop.
@@ -247,6 +248,17 @@ The goal is the date the doc was last meaningfully worked on. Try in order:
 3. If `status` resolved to `draft` → `documentation`
 4. If `status` resolved to `deprecated` → `deprecated`
 
+**`path` inference:**
+
+Unlike other fields, `path` cannot be inferred from git history or status — it requires reading the doc's content.
+
+For each doc missing `path`:
+1. Read its `title` frontmatter field and `## Purpose` section body
+2. Read all other docs' existing `path` fields to understand the project's established vocabulary and casing conventions
+3. Propose a `path` value (`Area/Section`, Title Case, 1–3 levels) that reflects where this feature lives in the product — use product terminology, not code module names
+
+**Do not silently write `path` values** — always include the proposed values in the Phase UP3 plan for user review. The user may adjust any proposed path before writing.
+
 ---
 
 ### Phase UP3 — Show Plan + Confirm
@@ -271,6 +283,7 @@ Present the inferred patches to the user before writing anything:
     + last_synced: 2026-01-17   (from git: last commit on this doc)
     + status: complete
     + phase: all
+    + path: Auth/Login           (inferred from purpose: "handles user login flow")
 
   ... (<N> more)
 
@@ -311,11 +324,12 @@ status: <new>         ← insert here if missing
 phase: <new>          ← insert here if missing
 mdd_version: <new>    ← insert here if missing
 tags: <new>           ← insert here if missing (do not generate tags in upgrade — run /mdd rebuild-tags after)
+path: <new>           ← insert here if missing (value inferred from doc content in UP2, confirmed by user in UP3)
 known_issues: []
 ---
 ```
 
-Insert new fields **before** `known_issues` to keep the canonical order. **Do not attempt to generate tag values during upgrade** — tags require reading doc content to produce meaningful keywords. After running upgrade, run `/mdd rebuild-tags` to populate tags on any docs that need them.
+Insert new fields **before** `known_issues` to keep the canonical order. **Do not attempt to generate tag values during upgrade** — tags require reading doc content to produce meaningful keywords; after running upgrade, run `/mdd rebuild-tags` to populate them. **For `path` values**: these ARE inferred by reading doc content during UP2 and confirmed in UP3 — write the user-confirmed values directly.
 
 Report progress as you go:
 ```
@@ -332,9 +346,16 @@ Patching...
 
 After all patches are applied:
 
-1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced`
+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
@@ -345,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`
@@ -153,6 +162,7 @@ A classification table — one row per feature:
 
 **Classifications:**
 - **untracked** — `last_synced` missing from frontmatter
+- **no-path** — `path` field missing from frontmatter (run `/mdd upgrade` to add)
 - **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`
@@ -176,11 +186,14 @@ Generated: <YYYY-MM-DD>
   ❓  09-integrations           — untracked (no last_synced field)
 
 Summary: 1 in sync · 1 drifted · 1 broken · 1 untracked
+Missing path: <N> docs — run /mdd upgrade to populate  ← omit this line when N = 0
 
 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
+  /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):
@@ -207,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`.
 
 ---
@@ -266,6 +286,7 @@ 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
+- `path:` — if the doc is missing a `path` field, offer to add it: "This doc is missing a `path` field. Where does this feature live in the product? (e.g. `Auth/Login`)" — if the user provides a value, write it between `tags` and `known_issues` in the frontmatter.
 
 ### Phase U6 — Regenerate test skeletons for new behaviors
 
@@ -283,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>`
@@ -327,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>
@@ -385,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
 
 ```
@@ -404,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,9 +115,12 @@ 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` →
+  **Read `$MDD_DIR/mdd-import-spec.md` then follow its IMPORT SPEC MODE instructions.**
+
 - If arguments start with `reverse-engineer`, `reverse`, `graph`, or `upgrade` →
   **Read `$MDD_DIR/mdd-lifecycle.md` then follow the relevant mode instructions.**
 

package/package.json

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