@thedecipherist/mdd 1.5.3 → 1.5.5

package/commands/mdd-import-spec.md

@@ -8,6 +8,21 @@ Reads one or more large spec or prompt documents — the kind produced by extend
 
 ### Phase IS1 — Read Spec Files
 
+**Stale job detection (runs first):** Check `.mdd/jobs/` for any existing `import-*/` folder.
+- If found: read its `MANIFEST.md` and count written vs total files. Present to user:
+  ```
+  Found interrupted import job from <date>.
+  MANIFEST shows <done>/<total> files written.
+  Written: <list of [x] paths>
+  Remaining: <list of [ ] paths>
+
+    [R] Resume — skip already-written files, continue from where it left off
+    [D] Discard — delete job, start the full import from scratch
+  ```
+  - **Resume:** skip IS1–IS3, go directly to IS4 writing only the `[ ]` entries. IS5 runs normally after.
+  - **Discard:** delete the `import-<date>/` folder, proceed normally.
+- If no stale job: proceed normally.
+
 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:
@@ -72,45 +87,131 @@ For each identified feature, determine its `path` value:
 - 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 — Build-order classification
+#### Step IS2c — Project type detection + wave ordering
+
+This is the most important step. Features are numbered in the order a developer would actually build them — not the order they appear in the spec. The correct order depends entirely on what type of project is being built.
+
+**Step 1 — Detect project type from the spec.**
+
+Read the spec for these signals:
+
+| Project type | Signals |
+|---|---|
+| **Language / Toolchain** | Has a Parser, AST, or grammar section. Describes directives, syntax, or a runtime. Has a CLI section. Describes an interpreter, compiler, or processing pipeline. |
+| **Web API / Backend** | Describes endpoints, routes, REST, or GraphQL. Has auth/authorization sections. Describes DB models and migrations. |
+| **Frontend / UI App** | Describes components, pages, or routing. Describes user interactions, forms, and layouts. Has a state management section. |
+| **Library / SDK** | Describes a public API surface with exported types. Has integration or plugin sections. No server or UI sections. |
+| **Extension / Plugin** | Spec is adding features to an existing product. Most features assume a host system already exists. |
+
+If signals from multiple types appear, pick the dominant one and note the mix.
+
+**Step 2 — Apply the wave ordering template for the detected type.**
+
+**Language / Toolchain:**
+```
+Wave 1 — Infrastructure Skeleton
+  Goal: a working program that can accept input and produce output, even if incomplete.
+  Build: Parser + AST types + core shared types + minimal CLI entry point
+  Demo-state: "can parse a source file and print the AST to stdout"
+
+Wave 2 — First Shippable Artifact
+  Goal: the first thing an end user can actually use.
+  Build: Stripper / Renderer / Compiler — whatever produces the first real output
+  Demo-state: "can take a source file and produce correct output for the simplest case"
+
+Wave 3 — Language Features
+  Goal: full language coverage. All directives, all syntax, all semantics.
+  Build: SPEC docs for every language feature + the Template Engine / Resolver that implements them
+  Demo-state: "all static features work correctly end to end"
+
+Wave 4 — Dynamic / Live Features
+  Goal: features that require external connections (DB, HTTP, shell, AI client).
+  Build: MCP Server, Hook, live directive execution
+  Demo-state: "live data directives execute and return real results"
+
+Wave 5 — Security, Hardening, Extras
+  Goal: production-safe. Sandboxed execution, audit logging, edge case handling.
+  Build: Security system, caching, graceful degradation
+  Demo-state: "untrusted documents are safe to run; audit log captures all executions"
+
+Wave 6 — CLI, Distribution, Packaging
+  Goal: installable and usable by someone who has never seen the codebase.
+  Build: Full CLI, npm package, CI integration, documentation
+  Demo-state: "npm install -g, run against a real file, get correct output"
+```
+
+**Web API / Backend:**
+```
+Wave 1 — Project scaffold + DB + core models
+  Demo-state: "server starts, DB connects, migrations run"
+
+Wave 2 — Auth
+  Demo-state: "can register, login, receive a JWT, access a protected route"
+
+Wave 3 — Core endpoints
+  Demo-state: "core CRUD for the main resource works end to end"
 
-This is the most important step. Features are numbered in the order a developer would actually build them — not the order they appear in the spec.
+Wave 4 — Business logic features
+  Demo-state: "main product workflow works end to end"
 
-**Classify every feature as one of two types:**
+Wave 5 — Integrations, webhooks, external APIs
+  Demo-state: "third-party integrations work in staging"
 
-**COMPONENT** — Something that results in code: a module, class, package, service, server, or runtime. The thing you sit down and write. Examples: Parser, Template Engine, Renderer, MCP Server, CLI.
+Wave 6 — Admin, analytics, hardening
+  Demo-state: "production-ready: rate limiting, logging, admin panel live"
+```
+
+**Frontend / UI App:**
+```
+Wave 1 — Routing + layout shell
+  Demo-state: "app loads, all routes navigate without error"
 
-**SPEC** — Something that describes behaviour a COMPONENT must implement: a directive definition, an API contract, a security rule, a caching rule, a language feature. You consult a SPEC doc while building the COMPONENT that implements it. Examples: `@include` directive spec, Security Config spec, Cache Modes spec.
+Wave 2 — Auth + core state
+  Demo-state: "can log in and see the main dashboard"
 
-**Order COMPONENT features by build dependency:**
+Wave 3 — Core features
+  Demo-state: "primary user workflow works end to end"
 
-Start from the foundation (the component everything else depends on) and work outward. Ask: "What must exist before I can build this?" The component with no dependencies comes first. The component that depends on everything comes last.
+Wave 4 — Secondary features + integrations
+  Demo-state: "all documented features work"
 
-Example for a language toolchain:
+Wave 5 — Polish, performance, accessibility
+  Demo-state: "passes lighthouse audit, all a11y checks green"
 ```
-Parser         — foundation, no deps, must exist first
-Stripper       — depends on Parser AST
-Renderer       — depends on Parser AST, no connection deps
-Template Engine — depends on Parser + Renderer
-MCP Server     — depends on Template Engine
-Hook           — depends on MCP Server
-CLI            — depends on all of the above
+
+**Library / SDK:**
 ```
+Wave 1 — Core types + core algorithm
+  Demo-state: "library installs, core function produces correct output"
+
+Wave 2 — Full public API
+  Demo-state: "all documented methods work, test suite passes"
 
-**Assign SPEC features to waves:** A SPEC feature belongs in the wave of the COMPONENT that implements it. The SPEC doc gets created alongside its implementing COMPONENT's wave so that both exist when building begins. The COMPONENT doc lists SPEC docs in its `depends_on`.
+Wave 3 — Extensions, plugins, advanced options
+  Demo-state: "extension points work, plugin example runs"
 
-**Determine wave breakdown:** Group COMPONENTs (and their associated SPECs) into waves by build phase. Each wave should have a clear demo-state — a thing you can actually demonstrate when the wave is done.
+Wave 4 — Distribution, docs, examples
+  Demo-state: "published to registry, README example runs from a fresh install"
+```
 
-Example wave structure for a language toolchain:
+**Extension / Plugin:**
 ```
-Wave 1 — Foundation:    Parser + all language directive SPECs
-Wave 2 — Static Output: Stripper + Renderer
-Wave 3 — Engine:        Template Engine + Caching SPECs
-Wave 4 — Live Data:     MCP Server + Hook + Security SPECs
-Wave 5 — CLI:           CLI + Distribution
+Order by user-facing value — the most impactful feature first. Each wave should be independently usable without later waves. Infrastructure last.
 ```
 
-**If no COMPONENT/SPEC distinction applies** (e.g. a feature-extension spec for an existing product), order features by: user-facing value first, infrastructure last. Earlier features should be shippable without later features.
+**Step 3 — Classify every feature.**
+
+With the wave structure determined, classify each feature:
+
+**COMPONENT** — results in code files: a module, class, package, service, server, or runtime. The thing you sit down and write.
+
+**SPEC** — describes behaviour a COMPONENT must implement: a directive definition, an API contract, a security rule, a protocol. You consult a SPEC while building the COMPONENT. SPEC docs belong in the same wave as their implementing COMPONENT.
+
+**Step 4 — Assign features to waves.**
+
+Place each feature in the wave where it logically gets built. Ask: "At which wave would a developer need this?" Not: "In which section does the spec describe it?"
+
+SPEC docs and their implementing COMPONENT always go in the same wave. The COMPONENT `depends_on` the SPECs it implements.
 
 #### Step IS2d — Determine output structure
 
@@ -230,10 +331,48 @@ Is the build order correct? Does each wave's demo-state make sense?
 
 **Do not proceed to IS4 until the user explicitly approves.**
 
+**After approval — create the job folder and MANIFEST before writing any file:**
+
+Create `.mdd/jobs/import-<YYYY-MM-DD>/MANIFEST.md`:
+
+```markdown
+# Import Spec Job Manifest
+# Job: import-<YYYY-MM-DD>
+# Source: <filename(s)>
+# Started: <ISO timestamp>
+# Files: <N total>
+# Status: IN PROGRESS
+#
+# States: [ ] pending  [~] writing  [x] written  [!] error
+
+## Files to create
+[ ] .mdd/initiatives/<slug>.md
+[ ] .mdd/waves/<slug>-wave-1.md
+[ ] .mdd/waves/<slug>-wave-2.md
+[ ] .mdd/docs/01-<slug>.md
+[ ] .mdd/docs/02-<slug>.md
+...
+```
+
+List every file that will be written in the order it will be written. Nothing proceeds until this file exists on disk.
+
 ---
 
 ### Phase IS4 — Write Files
 
+**First — ensure the MDD directory structure exists.** Run these before writing any file:
+
+```bash
+mkdir -p .mdd/initiatives
+mkdir -p .mdd/waves
+mkdir -p .mdd/docs
+```
+
+These are the exact directories MDD uses. Do not write initiative or wave files anywhere else. Full paths on disk:
+- Initiatives: `.mdd/initiatives/<slug>.md`
+- Waves: `.mdd/waves/<slug>-wave-N.md`
+- Feature docs: `.mdd/docs/<NN>-<slug>.md`
+
 Write in this order: CLAUDE.md (if approved) → initiative → waves → feature docs.
 
 #### CLAUDE.md (if approved in IS2.5)
@@ -319,6 +458,10 @@ Compute and write the `hash:` field after writing.
 
 #### Feature docs
 
+**Critical framing — these are build instructions, not reference documentation.**
+
+When a developer runs `/mdd NN`, Claude reads this doc and uses it to write code. That is the only reader that matters. Write every section as if answering the question: "What exactly do I build, and how do I know when it's done?" Not: "What does this feature do?" — a passive description is useless to a builder.
+
 For each feature in the approved plan, in wave order:
 
 1. Auto-number continuing from the highest existing doc number in `.mdd/docs/`
@@ -375,29 +518,37 @@ known_issues: []
 
 # <NN> — <Feature Title>
 
-## Purpose
+## What to Build
 
-<Full description of what this feature is and does. Include the core design rationale — the "why" behind the decisions. Do not limit this to a sentence count. If the spec says a lot about this feature, capture it all here. A developer reading only this doc should fully understand what they are building.>
+<Answer: "What exactly am I being asked to create?" For a COMPONENT: name the files/modules to create, what they take as input, what they produce as output, and what they must never do. For a SPEC: describe the exact behaviour contract the implementing COMPONENT must satisfy — what inputs it must accept, what output it must produce, what errors it must raise. Be concrete. "A parser that reads .md files" is too vague. "A parser that reads a .md source file and produces an array of ASTNode objects, one per directive" is correct.>
 
 ## Architecture
 
-<How this feature fits into the system. For a COMPONENT: describe its responsibilities, inputs, outputs, and what it must never do. For a SPEC: describe the behaviour contract the implementing COMPONENT must satisfy. Include TypeScript interfaces, AST node types, and data structures if the spec defines them.>
+<How this feature fits into the system and what it depends on. For a COMPONENT: its place in the pipeline, what calls it, what it calls, what it must never reach into directly. For a SPEC: which COMPONENT implements this spec and how. Include TypeScript interfaces, AST node types, and data structures exactly as defined in the spec — copy them verbatim, do not paraphrase.>
+
+## Implementation Notes
+
+<Key decisions Claude must follow when implementing this feature. This is not boilerplate — write only what is non-obvious or constraining. Examples: "use a single-pass regex scanner, not a recursive descent parser"; "never buffer the full file in memory"; "the AST must be immutable after construction". If the spec gives explicit implementation guidance, it belongs here.>
 
 ## Data Model
 
-<Data structures, schemas, config formats described in the spec. Include the exact field names, types, and constraints. Omit section only if the spec truly defines no data structures for this feature.>
+<Data structures, schemas, config formats. Include exact field names, types, nesting, and defaults. Copy JSON examples from the spec verbatim. Omit only if the spec truly defines no data structures for this feature.>
 
 ## API / Interface
 
-<Public interface this feature exposes: function signatures, tool names, command syntax, config keys. Omit if not applicable.>
+<The exact public interface this feature exposes. Function signatures, exported types, CLI commands and flags, config keys, MCP tool names. Every option, every flag, every subcommand — do not omit rare or advanced ones. A developer should be able to write the module's index.ts exports from this section alone.>
 
 ## Business Rules
 
-<Every decision, constraint, validation rule, edge case, error behaviour, and "never do X" described in the spec for this feature. This section should be exhaustive — if it is in the spec, it is here. Use bullet points or numbered lists for clarity.>
+<Every constraint, validation rule, edge case, error behaviour, platform difference, and "always/never/only valid when" rule from the spec. Exhaustive. If it is in the spec for this feature, it is here. Use a numbered or bulleted list. Include exact error message formats and the conditions that trigger them.>
+
+## Acceptance Criteria
+
+<How do you know this feature is done? Write concrete, verifiable statements. Each criterion should be something Claude can check with a test or a manual run. Examples: "mai strip input.md produces output with zero @ directives remaining"; "parsing a file with a circular @include chain throws CIRCULAR_REFERENCE_ERROR with the full chain in the message"; "all 11 content masking patterns fire correctly on the test fixtures".>
 
 ## Dependencies
 
-<Other feature docs this one requires. List by ID and title. For SPECs, name the COMPONENT that implements this spec.>
+<Other feature docs this one requires, by ID and title. For SPECs, state which COMPONENT implements this spec.>
 
 ## Known Issues
 
@@ -407,16 +558,18 @@ known_issues: []
 3. Tags: 4–8 domain-concept keywords. NOT file paths or spec section names.
 4. `depends_on`: populate from the build order analysis. COMPONENT docs list the SPEC docs they implement. SPEC docs list other SPECs they depend on (e.g. the expression system spec is depended on by the filter spec).
 
+**For every file written:** mark it `[~]` in MANIFEST before writing, then `[x]` immediately after. If writing fails, mark `[!]` with a one-line error note. This ensures the MANIFEST is always an accurate snapshot of what exists on disk — a resume after interruption will never re-write a file that was already successfully written.
+
 **Progress report as you write:**
 ```
 Writing files...
   ✅ CLAUDE.md
-  ✅ initiatives/markdownai.md
-  ✅ waves/markdownai-wave-1.md  (Wave 1 — Foundation)
-  ✅ waves/markdownai-wave-2.md  (Wave 2 — Static Pipeline)
+  ✅ .mdd/initiatives/<slug>.md
+  ✅ .mdd/waves/<slug>-wave-1.md  (Wave 1 — <name>)
+  ✅ .mdd/waves/<slug>-wave-2.md  (Wave 2 — <name>)
   ...
-  ✅ docs/01-<slug>.md   [COMPONENT]  <path>
-  ✅ docs/02-<slug>.md   [SPEC]       <path>
+  ✅ .mdd/docs/01-<slug>.md   [COMPONENT]  <path>
+  ✅ .mdd/docs/02-<slug>.md   [SPEC]       <path>
   ...
 ```
 
@@ -439,6 +592,8 @@ Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title
 - **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.
 
+**Clean up job folder:** Delete `.mdd/jobs/import-<date>/` entirely — the written files are the authoritative record.
+
 Then report:
 
 ```
@@ -458,6 +613,7 @@ Structure:
 
 Startup:     .mdd/.startup.md rebuilt
 Connections: .mdd/connections.md updated
+Job:         .mdd/jobs/import-<date>/ deleted
 
 Next steps:
   /mdd plan-execute <slug>-wave-1   — start building Wave 1

package/commands/mdd-plan.md

@@ -210,14 +210,28 @@ DIRTY=$(git status --porcelain)
   Follow the same (a)/(b)/(c) logic as mdd-build.md Phase 0.
 - **Never proceed on main.** This is a hard block regardless of clean/dirty state.
 
-1. Parse `<wave-slug>` — hard stop *"Wave does not exist"* if `waves/<wave-slug>.md` not found.
+1. Parse `<wave-slug>` — hard stop *"Wave does not exist"* if `.mdd/waves/<wave-slug>.md` not found.
 2. Read the wave doc.
 3. Derive and read the parent initiative — hard stop if not found.
 4. **Hash check:** verify both initiative and wave file hashes. Hard stop on any mismatch: *"File has been manually edited since last sync. Run `/mdd plan-sync` first."*
 5. **Depends-on gate:** if wave's `depends_on` is not `none`, verify that wave is `complete`. Hard stop if not.
-6. **Feature ordering check (Gap 4):** build dependency graph of features within the wave. If any ordering violation found → hard stop, explain exact conflict, offer auto-reorder.
-
-### Phase PE2 — Interaction mode
+6. **Feature ordering check:** build dependency graph of features within the wave. If any ordering violation found → hard stop, explain exact conflict, offer auto-reorder.
+7. **Stale job detection:** Check `.mdd/jobs/` for any existing `wave-<wave-slug>/` folder.
+   - If found: read its `MANIFEST.md` and count entries by state (`[ ]`, `[~]`, `[x]`, `[!]`). Present to user:
+     ```
+     Found interrupted wave job from <date>.
+     MANIFEST shows <done>/<total> features complete.
+     Features done: <list of [x] slugs>
+     Remaining:     <list of [ ] and [~] slugs>
+
+       [R] Resume — continue from where it left off
+       [D] Discard — delete job and start wave from scratch
+     ```
+   - **Resume:** skip PE2, skip to PE3 starting from the first `[ ]` or `[~]` entry. Features marked `[x]` are already complete — do not re-run them.
+   - **Discard:** delete the `wave-<wave-slug>/` folder, proceed to PE2 normally.
+   - If no stale job exists: proceed to PE2 normally.
+
+### Phase PE2 — Interaction mode + Job Setup
 
 Ask:
 ```
@@ -230,24 +244,51 @@ How do you want to run this wave?
 
 **Interactive:** full Phase 2 gate, Phase 5 plan confirmation, green gate iteration prompts on every feature.
 
+**After the interaction mode is chosen — create the job folder and MANIFEST (nothing proceeds until this exists on disk):**
+
+Create `.mdd/jobs/wave-<wave-slug>/MANIFEST.md`:
+
+```markdown
+# Wave Job Manifest
+# Job: wave-<wave-slug>
+# Wave: .mdd/waves/<wave-slug>.md
+# Initiative: <initiative-slug>
+# Started: <ISO timestamp>
+# Mode: <automated | interactive>
+# Features: <N>
+# Status: IN PROGRESS
+#
+# States: [ ] planned  [~] in_progress  [x] complete  [!] error
+
+## Features (in build order)
+[ ] <feature-slug-1>    .mdd/docs/<NN>-<slug>.md
+[ ] <feature-slug-2>    .mdd/docs/<NN>-<slug>.md
+[ ] <feature-slug-3>    .mdd/docs/<NN>-<slug>.md
+```
+
+List every feature from the wave's Features table in order. Features already marked `complete` in the wave doc get `[x]` from the start.
+
 ### Phase PE3 — Execute features
 
 For each feature in the wave's feature table, in dependency order, skipping `complete` features:
 
 1. Tell user: *"Starting Feature N: <feature-slug>"*
-2. Flip `wave_status: active` for this feature in the wave doc immediately.
-3. Update the wave doc's `Doc` column with the feature doc path (once created in MDD Phase 3).
-4. Run full MDD Build Mode (Phases 1–7) for the feature, at the chosen interaction level.
+2. Mark the feature `[~]` in `MANIFEST.md` immediately (before any other work).
+3. Flip `wave_status: active` for this feature in the wave doc immediately.
+4. Update the wave doc's `Doc` column with the feature doc path (once created in MDD Phase 3).
+5. Run full MDD Build Mode (Phases 1–7) for the feature, at the chosen interaction level.
    - Feature doc is auto-numbered from `.mdd/docs/` and gets `initiative`, `wave`, `wave_status` fields added.
-5. After Phase 7 verify: flip `wave_status: complete` in wave doc AND confirm `status: complete` is written to the feature doc frontmatter (Phase 7c should have done this — verify it, write it if missing).
-6. Ask: *"Feature N done ✓. Start Feature N+1? (yes / pause here)"*
+6. After Phase 7 verify: flip `wave_status: complete` in wave doc AND confirm `status: complete` is written to the feature doc frontmatter (Phase 7c should have done this — verify it, write it if missing).
+7. Mark the feature `[x]` in `MANIFEST.md`. If an error occurred that prevented completion, mark `[!]` with a one-line note.
+8. Ask: *"Feature N done ✓. Start Feature N+1? (yes / pause here)"*
 
-**Resume behaviour (Gap 2):** if re-run on a partially complete wave, read each feature's `wave_status`. Skip `complete`. Resume at first `active` or `planned`. If `active` but no doc exists → restart from Phase 1.
+**Resume behaviour:** if re-run on a partially complete wave, stale job detection in PE1 handles resume. MANIFEST is the authoritative progress record — it is always written before and after each feature so an interrupted session can pick up at the exact right point.
 
 ### Phase PE4 — Wave completion
 
 When all features are `complete`:
-1. Show the demo-state: *"Wave complete. Demo-state: '<demo-state>'. Have you verified this?"*
+1. Update `MANIFEST.md` — set `# Status: COMPLETE` in the header.
+2. Show the demo-state: *"Wave complete. Demo-state: '<demo-state>'. Have you verified this?"*
 2. User confirms → flip wave `status: complete` in both `waves/<slug>.md` AND the waves table in `initiatives/<slug>.md`.
 3. **Cascade status to feature docs** — for every feature listed in this wave, read its `.mdd/docs/<NN>-<slug>.md` and check `status:`. For any doc that is NOT already `complete` or `deprecated`, write:
    - `status: complete`
@@ -272,6 +313,8 @@ Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title
 - **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.
 
+**Clean up job folder:** Delete `.mdd/jobs/wave-<wave-slug>/` entirely. The wave doc and feature docs are the authoritative completion record — the job folder is ephemeral tracking only.
+
 ---
 
 ## PLAN-SYNC MODE — `/mdd plan-sync`

package/package.json

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