@thedecipherist/mdd 1.5.4 → 1.5.6

package/commands/mdd-audit.md

@@ -101,6 +101,40 @@ Manifest:    .mdd/jobs/audit-<date>/MANIFEST.md
 - Clear context after every single file — no exceptions.
 - On every startup (including post-clear): follow STARTUP SEQUENCE below.
 
+## Standard Audit Criteria (apply to every file)
+
+### P1 Critical
+- `eval()` used anywhere — only `vm.runInNewContext` is permitted
+- Cloud metadata endpoints (169.254.169.254, 169.254.170.2, fd00:ec2::254, metadata.google.internal) reachable without block
+- Secrets, API keys, or credentials hardcoded in source
+- Security enforcement function exists in a dependency but is NOT called at this call site (check dependency docs for `integration_contracts`)
+- "Immutable" rule arrays exported as plain mutable arrays — not `Object.freeze()` + `readonly`
+- Untrusted MCP/API/CLI input used without validation or sanitization
+- Data cached or stored without masking applied first
+- `satisfies_contracts` entry is `status: pending` — contract was acknowledged but never wired
+
+### P2 High
+- TypeScript `any` used — must use `unknown` with narrowing
+- Missing `.js` extension on ESM imports in src/ files (NodeNext resolution)
+- `console.log` in library code (should use logger)
+- File exceeds 300 lines
+- Function exceeds 50 lines
+- Feature's `source_files` lists a file that does not exist on disk
+- Transformation/substitution function handles some but not all AST/domain types (silent fallthrough for unhandled types)
+- MCP-exposed function accepts untrusted params with no explicit validation
+
+### P3 Medium
+- TypeScript strict mode not enabled in tsconfig
+- Missing error handling at system/user-input boundaries
+- Feature has `depends_on` entries with `integration_contracts` but `satisfies_contracts` is empty
+- Security module's `integration_contracts` specifies a caller that has no `satisfies_contracts` entry
+- Missing test cases for documented business rules
+
+### P4 Low
+- Code style inconsistencies
+- Dead code / unused imports
+- Minor spec divergences
+
 ## Startup Sequence
 1. Read this config file
 2. Read shard-<N>.md to know your file list
@@ -185,6 +219,17 @@ Read ONLY `audits/notes-<date>.md` (NOT source code again). Produce `audits/repo
 3. Findings by severity (P1 Critical / P2 High / P3 Medium / P4 Low)
 4. Test coverage summary
 5. Fix plan with effort estimates and affected files per finding
+6. Root Cause Analysis — for each cluster of findings, explain WHY the code writer made the mistake (not just what is wrong). Common root causes: "security module built in isolation without integration contracts," "immutability described in spec but not enforced at the code level," "MCP tool written without a threat model," "node type added after transformation function was written."
+7. Prevention Rules — derive concrete, actionable rules that would have prevented each finding cluster. Format: "When implementing X, always Y. Never Z. Reasoning: [which finding caused this]." These rules are proposed for addition to CLAUDE.md at the end of the audit.
+
+**Integration contract cross-check (in addition to per-file analysis):**
+After per-file analysis is complete, read all `.mdd/docs/*.md` and:
+- For each feature with `integration_contracts` entries: verify that every listed `caller_feature` has a matching `satisfies_contracts` entry referencing back to this feature
+- For each feature with `satisfies_contracts` entries still `status: pending`: flag as P1 — the wiring was documented but never implemented
+- For each feature doc where `satisfies_contracts` is empty but `depends_on` includes a feature with `integration_contracts`: flag as P2 — missing acknowledgment of mandatory contracts
+- For each source file flagged `[!]` where the finding is "security function not called at call site": cross-reference against `integration_contracts` of dependencies — these are contract violations, not just code quality issues
+
+Report these as a separate "Contract Violations" section before the standard findings table.
 
 **Once `audits/report-<date>.md` is confirmed written and non-empty:**
 1. Copy `jobs/audit-<date>/MANIFEST.md` → `audits/MANIFEST-<date>.md`

package/commands/mdd-build.md

@@ -193,6 +193,8 @@ 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>
+integration_contracts: []
+satisfies_contracts: []
 known_issues: []
 ---
 
@@ -226,6 +228,14 @@ known_issues: []
 
 <What this feature requires from other features. List by documentation ID.>
 
+## Security
+
+<Only required when this feature: provides a security enforcement function, accepts external/user/MCP input, stores or caches data, spawns processes, or makes network calls. Leave empty otherwise.>
+
+<For security enforcement features: list integration_contracts — which call sites must invoke which functions.>
+<For input-accepting features: document trusted vs untrusted input boundary, sanitization requirements, and what a malicious caller could attempt.>
+<For caching features: document what masking or sanitization runs before storage.>
+
 ## Known Issues
 
 <Empty for new features. Will be populated by future audits.>
@@ -235,6 +245,50 @@ 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.
 
+#### Phase 3a — Integration Contract Resolution (mandatory when `depends_on` is non-empty)
+
+After writing the feature doc, resolve integration obligations from dependencies:
+
+1. For each feature ID in `depends_on`, read its `.mdd/docs/*.md` file
+2. Check whether it has `integration_contracts` entries
+3. For each contract that applies to the current feature, add it to `satisfies_contracts` as a **placeholder** showing what must be wired:
+
+```yaml
+satisfies_contracts:
+  - from: <dependency-feature-id>
+    function: <function-name>(<args>)
+    when: <condition — e.g. "before any file read in executeInclude">
+    status: pending  ← change to "verified: <file>:<line>" during Phase 6
+```
+
+**Leaving `satisfies_contracts` empty when a dependency has mandatory `integration_contracts` is a build error.** Do not proceed past Phase 3a until all applicable contracts are acknowledged.
+
+**Cross-cutting concerns that always require contract resolution:**
+- Any dependency tagged with `security`, `auth`, `masking`, `filesystem`, `audit`, `immutable` — its contracts are always mandatory
+- Any dependency that provides a "check before X" or "enforce Y" function — that function must be in your `satisfies_contracts`
+
+During Phase 6 implementation, update each `satisfies_contracts` entry from `status: pending` to `verified: <file>:<line>` as each call site is wired. Phase 7c will verify all entries are `verified` before marking the feature complete.
+
+#### Phase 3b — Special Case Rules
+
+These rules apply regardless of what the feature doc says. They are not optional.
+
+**Immutability rule:** Any spec language describing values as "immutable," "cannot be overridden," "always enforced," or "built-in" requires both:
+- `readonly string[]` (or `as const`) TypeScript typing
+- `Object.freeze()` applied at definition
+
+Using a plain `const` array is not sufficient and will fail audit.
+
+**MCP and external-caller threat model:** Any feature that exposes functions to MCP clients, CLI users, API callers, or any untrusted external party must include a Security section in its doc that explicitly:
+- Lists which inputs are untrusted
+- States what a malicious caller could send
+- Specifies validation/sanitization required before use
+- States what the function is NOT permitted to expose (e.g., full `process.env`, raw credentials, unrestricted filesystem paths)
+
+**Node substitution completeness rule:** Any function that transforms, substitutes, or dispatches across AST node types must handle ALL node types defined in `types.ts` — either explicitly or with a documented explicit-skip decision. An unhandled node type that silently falls through is a bug, not a design choice.
+
+**Existence gate for source_files:** When marking `status: complete`, all files listed in `source_files` must exist on disk. Missing files block completion. Add missing files to `known_issues` with a TODO, or implement them before closing the feature.
+
 **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.
@@ -604,7 +658,15 @@ where the agent patches the wrong thing because it accepted an external excuse t
 
 **If integration verified:**
 
-1. **Update the feature doc frontmatter** — write these fields now, before displaying the signal:
+1. **Contract verification gate** — before marking complete, check the feature doc's `satisfies_contracts`:
+   - Any entry still `status: pending` means the integration was never wired
+   - For each pending entry: locate the call site in the implementation, verify it exists, update to `verified: <file>:<line>`
+   - If the call site is missing: implement it now (do not mark complete without it)
+   - **A feature with any `pending` contract cannot be marked `status: complete`**
+
+   Also check that all files in `source_files` exist on disk. Any missing file must be implemented or moved to `known_issues` with explicit documentation of why it was deferred.
+
+2. **Update the feature doc frontmatter** — write these fields now, before displaying the signal:
    - `status: complete`
    - `phase: all`
    - `last_synced: <today>`

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:
@@ -316,6 +331,31 @@ 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
@@ -518,6 +558,8 @@ 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...
@@ -550,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:
 
 ```
@@ -569,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/commands/mdd.md

@@ -3,7 +3,7 @@ description: "MDD workflow — Document → Audit → Fix → Verify. Build feat
 scope: project
 argument-hint: "<feature-description> or audit [section]"
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, Agent
-mdd_version: 9
+mdd_version: 10
 ---
 
 # MDD — Manual-Driven Development Workflow

package/package.json

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