@thedecipherist/mdd 1.5.5 → 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.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.5",
+  "version": "1.5.6",
   "description": "MDD — Manual-Driven Development workflow for Claude Code",
   "type": "module",
   "bin": {