@thedecipherist/mdd 1.6.11 → 1.6.13

package/commands/mdd-audit.md

@@ -158,6 +158,8 @@ Integration context:   .mdd/jobs/audit-<date>/integration-context.md
 - "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
+- Local reimplementation of security logic — any function named `isConfined`, `isAllowed`, `isSafe`, `isBlocked`, or similar that replicates what a documented security module already provides. Require replacement with the canonical security module function.
+- Contract function undefined — if `integration_contracts` specifies a function name, grep the entire package for that name as an export. If the function does not exist anywhere, flag P1 regardless of whether call sites are present.
 
 **Note:** `satisfies_contracts status: pending` is checked by main in Phase A1, not here — agents cannot read feature docs.
 
@@ -168,7 +170,9 @@ Integration context:   .mdd/jobs/audit-<date>/integration-context.md
 - File exceeds 300 lines
 - Function exceeds 50 lines
 - Transformation/substitution function handles some but not all AST/domain types (silent fallthrough for unhandled types)
+- Switch on a string-union type or operation enum with no `default:` case, or where `default:` returns a value rather than throwing. Check all `switch` statements in execution, adapter, and transformation code. Approved pattern: `default: throw new Error(\`unhandled type: \${x satisfies never}\`)` — the `satisfies never` check produces a compile error when a new variant is added without updating the switch.
 - MCP-exposed function accepts untrusted params with no explicit validation
+- Security parameter never passed — if a function accepts a policy param (allowedKeys, blockedDomains, securityConfig, etc.) that must come from a caller, verify the caller passes a non-empty, non-null value. If the parameter always arrives as `undefined`, `null`, or `[]`, the enforcement is a no-op.
 
 ### P3 Medium
 - TypeScript strict mode not enabled in tsconfig
@@ -176,6 +180,8 @@ Integration context:   .mdd/jobs/audit-<date>/integration-context.md
 - Missing test cases for documented business rules
 - CLI command missing any of the universal flags (--env, --cwd, --verbose, --strict, --silent) — check all commands against the CLI feature doc's universal flags requirement
 - `file.*` filesystem helpers or path-resolving functions accept arbitrary paths without confinement to a documented jailRoot
+- Code that constructs a `SecurityConfig` or equivalent security object sets `jailRoot: null`. A null jailRoot disables filesystem confinement — the default should be the document's directory (`dirname(resolvedPath)`), not `null`, unless the caller explicitly provides an override.
+- `String.replace()` uses a captured group reference (`$1`, `$2`, etc.) in the replacement argument where the captured value originates from untrusted input. Values containing `$1`, `$&`, `$'`, etc. are silently mangled by JavaScript's substitution semantics. Sanitize with `.replace(/\$/g, '$$$$')` before interpolating into a replacement string.
 - Silent error swallow: catch block returns empty/undefined without pushing to warnings array
 - Template/substitution function matches `{{varname}}` without spaces but not `{{ varname }}` with spaces — spec uses spaced form; use regex `\s*` not exact string
 

package/commands/mdd-build.md

@@ -262,11 +262,14 @@ 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
+    status: pending      # change to done during Phase 6
+    verified_at: ""      # set to "path/to/file.ts:lineN" when status is done
 ```
 
 **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.
 
+**Before marking any `satisfies_contracts` entry `status: done`:** run `grep -rn '<function-name>'` across the entire package. Every call site must invoke the contract function — not just the one currently in focus. If the function is only wired in one layer (e.g. dispatcher) but not another (e.g. executor), the contract is not satisfied. Set `verified_at` to the confirmed call site before updating status.
+
 **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`
@@ -339,6 +342,8 @@ describe('<Feature Name>', () => {
 - If BOTH unit AND E2E tests are needed → launch 2 parallel `general-purpose` agents. Each receives: the full MDD doc content, the skeleton template above, project testing conventions, and the exact output file path. Agent A writes `tests/unit/<feature-name>.test.ts`, Agent B writes `tests/e2e/<feature-name>.spec.ts`. These are different files — no write conflict is possible.
 - If only unit tests needed → generate directly in the main conversation (no agent overhead for a single file).
 
+**CLI feature additional check:** If the feature adds or modifies CLI commands, add a skeleton that invokes each new command with `--help` and asserts all five universal flags (`--env`, `--cwd`, `--verbose`, `--strict`, `--silent`) appear in the output. This catches missing `universalOptions()` wiring before implementation begins.
+
 **E2E skeleton template (if applicable):**
 ```typescript
 import { test, expect } from '@playwright/test';
@@ -530,6 +535,8 @@ Execute blocks in dependency layer order (Layer 1 → 2 → 3 → 4). Within the
 
 **For sequential blocks:** read the MDD doc, read the relevant test skeletons, implement, run the Green Gate loop below.
 
+**Directive/constant change ripple rule:** If this block changes any directive syntax, canonical header string, config key, or other string constant that other parts of the codebase may consume (e.g. language grammars, test fixtures, snippets, detection code), run `grep -rn 'old_string'` across the entire repo before marking the block complete. Update every consumer found — tmLanguage files, E2E fixtures, snippets, and any hardcoded string comparisons — in the same block, not as a follow-up.
+
 #### Step 6b — Green Gate loop (per block)
 
 After each block's implementation (sequential or parallel), run the Green Gate:
@@ -678,7 +685,8 @@ where the agent patches the wrong thing because it accepted an external excuse t
 
 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>`
+   - For each entry: run `grep -rn '<function-name>'` across the entire package. Every call site must invoke the contract function — not just the one originally in scope. If a layer (e.g. executor vs dispatcher) is missing the call, the contract is not satisfied.
+   - Update each confirmed entry to `status: done` and `verified_at: "path/to/file.ts:lineN"` pointing to the confirmed call site.
    - 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`**
 

package/commands/mdd-manual.md

@@ -1,20 +1,20 @@
-## MANUAL MODE — `/mdd manual [--force]`
+## MANUAL MODE - `/mdd manual [--force]`
 
 Triggered when arguments start with `manual`.
 
 Generates a comprehensive, print-ready user manual at `.mdd/manual/manual.md` from all
 MDD feature docs and ops runbooks. Uses content hashes to detect what changed since the
-last run — only stale sections are regenerated.
+last run - only stale sections are regenerated.
 
-Sections are written to disk **immediately after each generation batch completes** — never
+Sections are written to disk **immediately after each generation batch completes** - never
 held in memory until the end. This means compaction mid-run loses at most one batch of
 sections, and the next run can resume from the saved state.
 
 ---
 
-### Phase M1 — Scope & Hash Check
+### Phase M1 - Scope & Hash Check
 
-**Step 1 — Guard against empty projects**
+**Step 1 - Guard against empty projects**
 
 Check `.mdd/docs/`. If it contains zero `.md` files:
 ```
@@ -23,7 +23,7 @@ Run /mdd <feature> to create your first doc, then re-run /mdd manual.
 ```
 Stop here.
 
-**Step 2 — Load stored hashes**
+**Step 2 - Load stored hashes**
 
 Read `.mdd/manual/.hashes.json` if it exists. If absent, treat every doc as new (full
 generation run).
@@ -38,24 +38,24 @@ Stored hash format:
 }
 ```
 
-**Step 3 — Compute current hashes**
+**Step 3 - Compute current hashes**
 
 For every file in `.mdd/docs/*.md` and `.mdd/ops/*.md`, compute SHA256 of file contents:
 ```bash
 sha256sum .mdd/docs/*.md .mdd/ops/*.md 2>/dev/null
 ```
 
-**Step 4 — Classify each doc**
+**Step 4 - Classify each doc**
 
 Compare current vs stored hashes:
-- `unchanged` — hash matches stored value → skip section regeneration
-- `changed` — hash differs → regenerate section
-- `new` — no stored hash → generate section
-- `deleted` — stored hash exists but file no longer present → remove section
+- `unchanged` - hash matches stored value → skip section regeneration
+- `changed` - hash differs → regenerate section
+- `new` - no stored hash → generate section
+- `deleted` - stored hash exists but file no longer present → remove section
 
 If `--force` was passed: treat every doc as `changed` regardless of hashes.
 
-**Step 5 — Report scope**
+**Step 5 - Report scope**
 
 ```
 📖 MDD Manual Generator
@@ -78,24 +78,24 @@ Stop here.
 
 ---
 
-### Phase M2 — Skeleton Init (before generating any sections)
+### Phase M2 - Skeleton Init (before generating any sections)
 
 Before generating any sections, ensure `manual.md` is in a writable state on disk.
-This protects against compaction — each section written to disk is durable.
+This protects against compaction - each section written to disk is durable.
 
-**Step 1 — Ensure output directory exists**
+**Step 1 - Ensure output directory exists**
 ```bash
 mkdir -p .mdd/manual
 ```
 
-**Step 2 — Load existing manual or build skeleton**
+**Step 2 - Load existing manual or build skeleton**
 
 Read `.mdd/manual/manual.md` if it exists. Identify the preface: everything before the
 first `<!-- mdd-section: -->` marker. If the file is new, generate a default preface
 (see Phase M3 Step 2 below for the preface format) and write the skeleton immediately:
 
 ```markdown
-# <Project Name> — User Manual
+# <Project Name> - User Manual
 
 > <tagline>
 
@@ -121,13 +121,13 @@ first `<!-- mdd-section: -->` marker. If the file is new, generate a default pre
 
 ## Features
 
-(sections generating — re-run /mdd manual if interrupted)
+(sections generating - re-run /mdd manual if interrupted)
 
 ---
 
 ## Operations
 
-(sections generating — re-run /mdd manual if interrupted)
+(sections generating - re-run /mdd manual if interrupted)
 
 ---
 
@@ -141,7 +141,7 @@ first `<!-- mdd-section: -->` marker. If the file is new, generate a default pre
 Write this skeleton to `.mdd/manual/manual.md` now, before any agents are launched.
 This ensures the file exists on disk even if compaction occurs mid-generation.
 
-**Step 3 — Remove deleted sections**
+**Step 3 - Remove deleted sections**
 
 For each doc classified as `deleted`: find and remove the entire
 `<!-- mdd-section: <id> -->` … `<!-- /mdd-section: <id> -->` block (including
@@ -150,10 +150,10 @@ each removal.
 
 ---
 
-### Phase M3 — Section Generation (incremental, batch-by-batch)
+### Phase M3 - Section Generation (incremental, batch-by-batch)
 
 For each `changed` or `new` doc, generate a user-friendly manual section. The section
-must be readable by someone who has never seen the source code — focus on WHAT the
+must be readable by someone who has never seen the source code - focus on WHAT the
 feature does and HOW to use it, not implementation details.
 
 **Section structure per feature doc:**
@@ -171,18 +171,18 @@ feature does and HOW to use it, not implementation details.
 <Step-by-step user instructions. Include command syntax, options, examples.>
 
 #### Commands
-<If the feature has CLI commands — table with command, description, flags.>
+<If the feature has CLI commands - table with command, description, flags.>
 | Command | Description | Flags |
 |---------|-------------|-------|
 | `mdd <cmd>` | … | `--flag` |
 
 #### API Endpoints
-<If the feature exposes HTTP endpoints — table with method, path, description.>
+<If the feature exposes HTTP endpoints - table with method, path, description.>
 | Method | Path | Description | Auth |
 |--------|------|-------------|------|
 
 #### Configuration
-<If the feature has configurable options — env vars, settings, flags.>
+<If the feature has configurable options - env vars, settings, flags.>
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 
@@ -209,7 +209,7 @@ For ops runbooks, use a condensed format:
 <!-- /mdd-section: ops/<slug> -->
 ```
 
-**Parallelism and incremental writing — CRITICAL:**
+**Parallelism and incremental writing - CRITICAL:**
 
 - **1–4 changed docs** → generate sequentially in main conversation. After EACH section
   is generated, immediately patch it into `manual.md` on disk (see patching rules below)
@@ -243,44 +243,44 @@ For each returned section:
 
 **Reading source files during generation:**
 When the feature doc lists `source_files`, read those files briefly to verify the section
-accurately reflects what is implemented — do not invent capabilities not present in code.
+accurately reflects what is implemented - do not invent capabilities not present in code.
 If source files don't exist yet (draft feature), note the section as "(planned)" in the
 section header.
 
 ---
 
-### Phase M4 — Final Assembly
+### Phase M4 - Final Assembly
 
 After all sections are on disk, perform final assembly passes on `manual.md`.
 
-**Step 1 — Rebuild aggregated reference sections**
+**Step 1 - Rebuild aggregated reference sections**
 
 Scan every `<!-- mdd-section: -->` block in the current `manual.md` for:
 
-**Command Reference** — find all `#### Commands` tables. Merge into one master table,
+**Command Reference** - find all `#### Commands` tables. Merge into one master table,
 sorted alphabetically by command. Include a "Feature" column. Replace the existing
 `## Command Reference` section (or append if missing).
 
-**API Reference** — find all `#### API Endpoints` tables. Merge into one master table,
+**API Reference** - find all `#### API Endpoints` tables. Merge into one master table,
 sorted by path. Include a "Feature" column. Replace the existing `## API Reference`
 section (or append if missing). Omit this section entirely if no API endpoints were found.
 
-**Configuration** — find all `#### Configuration` tables. Merge into one master table,
+**Configuration** - find all `#### Configuration` tables. Merge into one master table,
 grouped by feature. Replace the existing `## Configuration` section (or append if
 missing). Omit this section entirely if no configuration options were found.
 
-**Step 2 — Regenerate TOC**
+**Step 2 - Regenerate TOC**
 
 Scan the assembled document for all `##` and `###` headings. Build a markdown TOC with
 anchor links. Replace the `<!-- toc -->` … `<!-- /toc -->` block (between
 `## Table of Contents` and the next `---` divider) with the new TOC.
 
-**Step 3 — Final document structure**
+**Step 3 - Final document structure**
 
 The assembled `manual.md` must follow this order:
 
 ```markdown
-# <Project Name> — User Manual        ← preface (preserved or generated)
+# <Project Name> - User Manual        ← preface (preserved or generated)
 > <tagline>
 
 **Version:** … **Generated:** …
@@ -339,7 +339,7 @@ The assembled `manual.md` must follow this order:
 | Option | Type | Default | Description | Feature |
 ```
 
-**Step 2 — Build/update preface** (if generating for the first time)
+**Step 2 - Build/update preface** (if generating for the first time)
 
 If the preface was newly generated in Phase M2, ensure it uses this content:
 
@@ -347,11 +347,11 @@ Read `.mdd/.startup.md` for: project name, stack, tagline. Read `package.json` (
 present) for version. Read `README.md` introduction (first 3 paragraphs, if present).
 
 ```markdown
-# <Project Name> — User Manual
+# <Project Name> - User Manual
 
 > <tagline or one-sentence description>
 
-**Version:** <version from package.json, or "—">
+**Version:** <version from package.json, or "-">
 **Generated:** <date>
 
 <2-3 paragraph project overview synthesized from README and .startup.md>
@@ -363,9 +363,9 @@ Write the final assembled `manual.md` to disk.
 
 ---
 
-### Phase M5 — Write Hashes & Report
+### Phase M5 - Write Hashes & Report
 
-**Step 1 — Update hash store**
+**Step 1 - Update hash store**
 
 Write `.mdd/manual/.hashes.json` with:
 - One entry per doc that now exists on disk (use the current hash)
@@ -374,10 +374,10 @@ Write `.mdd/manual/.hashes.json` with:
 - Set `_manual_version: 1` (or increment if already set)
 
 **Only write this file after manual.md is fully complete.** The hash file is the
-completion marker — if `.hashes.json` is missing or stale, the next run will know
+completion marker - if `.hashes.json` is missing or stale, the next run will know
 to regenerate all sections.
 
-**Step 2 — Report**
+**Step 2 - Report**
 
 ```
 ✅ Manual generated
@@ -395,7 +395,7 @@ Tip: manual.md is print-ready markdown. Open in any markdown viewer,
      export to PDF, or use as source material for blog posts and docs.
 ```
 
-**Step 3 — Gitignore check**
+**Step 3 - Gitignore check**
 
 Check whether `.mdd/manual/` is in `.gitignore`. If not, suggest:
 ```
@@ -409,8 +409,8 @@ Check whether `.mdd/manual/` is in `.gitignore`. If not, suggest:
 
 | Flag | Effect |
 |------|--------|
-| `--force` | Bypass hash check — regenerate all sections |
-| (none) | Default — only regenerate changed/new sections |
+| `--force` | Bypass hash check - regenerate all sections |
+| (none) | Default - only regenerate changed/new sections |
 
 ---
 
@@ -419,12 +419,13 @@ Check whether `.mdd/manual/` is in `.gitignore`. If not, suggest:
 When generating each section, the goal is a document a non-technical user or executive
 can read and understand. Rules for section writers:
 
+- **No em dashes** - never use `-` anywhere in generated content; use a plain hyphen `-` instead
 - **No internal file paths** in body text (they belong in the feature doc, not the manual)
-- **No jargon without definition** — if a term needs explanation, add it
-- **Active voice** — "The auth system validates your token" not "Tokens are validated"
-- **One idea per paragraph** — keep paragraphs to 3–5 sentences
+- **No jargon without definition** - if a term needs explanation, add it
+- **Active voice** - "The auth system validates your token" not "Tokens are validated"
+- **One idea per paragraph** - keep paragraphs to 3-5 sentences
 - **Examples are mandatory** for any command or API endpoint listed
-- **Planned features** are clearly marked `(planned — not yet implemented)`
+- **Planned features** are clearly marked `(planned - not yet implemented)`
 
 ### Recovery from Interrupted Runs
 
@@ -433,7 +434,7 @@ If `/mdd manual` was interrupted mid-generation (context compaction, session end
 1. Re-run `/mdd manual`. The hash check will find that `.hashes.json` is missing or
    incomplete (since it's only written at the very end in Phase M5).
 2. Sections already written to `manual.md` (from completed batches) will be detected as
-   present — but since their hashes aren't in `.hashes.json`, they'll be classified as
+   present - but since their hashes aren't in `.hashes.json`, they'll be classified as
    `new` and regenerated.
 3. The regenerated sections will simply replace what was already there. No data is lost.
 

package/package.json

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