@thedecipherist/mdd 1.7.2 → 1.8.1

package/README.md

@@ -943,6 +943,7 @@ All MDD artifacts live in one place:
 │       ├── agent-N-config.md
 │       └── agent-N-notes.md
 ├── .startup.md                   # Auto-generated session context (read by Claude on start)
+├── settings.json                 # Stack config — auto-populated by discovery, committed to git
 └── connections.md                # Pre-computed relationship map (path tree + Mermaid graph)
 ```
 
@@ -982,6 +983,91 @@ The auto-generated section above the `---` is rebuilt each time. The Notes secti
 
 ---
 
+## Stack Settings
+
+MDD creates `.mdd/settings.json` on first run. It controls which rule files load during audit and build phases, whether stack detection runs automatically, and a few other session behaviours.
+
+```json
+{
+  "autoDiscovery": true,
+  "stack": {
+    "language": ["typescript"],
+    "runtime": ["node"],
+    "frameworks": ["express"],
+    "orm": ["prisma"],
+    "auth": ["jwt"]
+  },
+  "overrides": {},
+  "phaseLogging": true,
+  "securityScan": false
+}
+```
+
+**`autoDiscovery: true` (default)** - MDD scans your manifest files once at session start and writes the detected stack into `settings.json`. It checks `package.json`, `go.mod`, `pyproject.toml`, and `composer.json`. The `stack` field is owned by discovery when this is on; `overrides` is always yours to edit.
+
+**`autoDiscovery: false`** - MDD reads `settings.json` as-is. You control the stack manually. Useful when your dependencies don't reflect the full picture (custom implementations, monorepos, unusual setups).
+
+**`overrides`** - Merged on top of `stack` at phase time. Add anything discovery misses - custom auth implementations, internal frameworks, or anything else that needs stack-specific rules.
+
+**`phaseLogging: true` (default)** - Controls whether MDD writes phase timing data via `mdd-log-phase.sh`. Set to `false` to suppress all phase log output.
+
+**`securityScan: false` (default)** - Enables the security rule generator. See the section below.
+
+### Stack-Specific Rule Files
+
+Once MDD knows your stack, it loads matching rule files at the start of each audit and build phase. These files live in `~/.claude/mdd/` alongside the other mode files and are installed with `mdd install`.
+
+```
+mdd-rules-typescript.md   # TypeScript-specific audit criteria and build checklists
+mdd-rules-express.md      # Express error handling, middleware, route validation rules
+mdd-rules-jwt.md          # JWT decode safety, expiry checks, secret validation
+mdd-rules-prisma.md       # Prisma query safety, transaction patterns, migration checks
+```
+
+Rules are additive - they append criteria to the existing phase rather than replacing anything. If a rule file doesn't exist for a stack entry, MDD warns once and continues. A misconfigured or missing `settings.json` never halts a session.
+
+### Security Rule Generator
+
+When `securityScan: true`, MDD runs a vulnerability scan against your declared stack and generates new audit rules for any patterns not already covered.
+
+```bash
+# Runs automatically during /mdd audit when securityScan: true
+# Or run directly:
+/mdd security-rules
+```
+
+**How it works:**
+
+1. Scans your dependencies using free tools - `npm audit` for Node projects, `osv-scanner` for multi-language, Snyk CLI free tier if installed. No API keys required.
+2. Reads all existing `mdd-rules-{stack}.md` files and extracts the current rule set.
+3. For each vulnerability found: checks whether the attack vector is already covered by an existing rule.
+4. If a gap exists: generates a new rule targeting the vulnerability *class*, not just the specific CVE. A rule about "prototype pollution via unvalidated query parameters" will catch future variants, not just the package version that triggered it.
+5. Appends new rules to the relevant `mdd-rules-{stack}.md` file with the source CVE as a reference.
+
+```
+Security rule generator - 2026-05-20
+
+Sources: npm audit, osv-scanner
+Findings reviewed: 12
+Already covered by existing rules: 9
+Gaps found: 3
+
+New rules generated:
+  mdd-rules-express.md  +2 rules
+    - [P2] Prototype pollution via req.query or req.body merge — use structuredClone() or
+      a safe merge utility. Reference: CVE-2024-29041
+    - [P2] res.redirect() called with user-supplied path without allowlist validation.
+      Reference: CVE-2024-43796
+
+  mdd-rules-jwt.md  +1 rule
+    - [P2] jwt.decode() used instead of jwt.verify() — decode skips signature check.
+      Reference: CVE-2022-21449 (class)
+```
+
+The gap check uses semantic comparison, not string matching, so rules generated in a previous run are not duplicated even if they use different wording. Each generated rule includes the CVE ID so you can trace where it came from and review or remove it if needed.
+
+---
+
 ## MDD Versioning
 
 Every file created by MDD is stamped with `mdd_version: N` in its frontmatter. This tracks which version of the workflow created or last updated each doc.

package/commands/mdd-audit.md

@@ -2,6 +2,24 @@
 
 Triggered when arguments start with `audit`.
 
+### Stack Rule Loading (runs before Phase A1)
+
+After Step 0c in `mdd.md` sets `$MDD_STACK` and `$MDD_DIR`, load any matching stack rule files. This runs silently — no output unless a problem occurs.
+
+```
+For each entry in $MDD_STACK:
+  If $MDD_DIR/mdd-rules-{entry}.md exists:
+    Read the file — append all rules found to the active audit criteria for this session
+  Else:
+    Emit one line: ⚠ No rule file for '{entry}' — skipping
+    Continue (never halt)
+```
+
+Stack rules are **additive only** — they extend the P1/P2/P3/P4 criteria lists used in Phase A3. They never replace or gate core audit behaviour.
+
+If `$MDD_SECURITY_SCAN` is `true`, run the security rule generator before loading rules:
+**Read `$MDD_DIR/mdd-security-rules.md` and follow its SECURITY RULES MODE instructions.** New rules it writes to `mdd-rules-{stack}.md` files will be picked up by the loading step above.
+
 ### Phase A1 — Scope
 
 ```bash

package/commands/mdd-build.md

@@ -1,5 +1,21 @@
 ## BUILD MODE — New Feature Development
 
+### Stack Rule Loading (runs before Phase 0)
+
+After Step 0c in `mdd.md` sets `$MDD_STACK` and `$MDD_DIR`, load any matching stack rule files. This runs silently — no output unless a problem occurs.
+
+```
+For each entry in $MDD_STACK:
+  If $MDD_DIR/mdd-rules-{entry}.md exists:
+    Read the file — append all build checklist items to Phase 6 implementation steps
+    Append any additional audit criteria to Phase 7b verification checks
+  Else:
+    Emit one line: ⚠ No rule file for '{entry}' — skipping
+    Continue (never halt)
+```
+
+Stack rules are **additive only** — they extend Phase 6 checklists and Phase 7b verification. They never replace or gate core build behaviour.
+
 ### Phase 0 — Branch Safety Check
 
 ```bash

package/commands/mdd-rules-express.md

@@ -0,0 +1,23 @@
+## MDD Rules — Express
+
+Rules loaded when `stack.frameworks` includes `express`. Applied additively to audit criteria and build checklists.
+
+### Audit Criteria
+
+#### P2 — Error Handler 5xx Leakage
+- Express (or equivalent HTTP framework) error handler forwards raw `Error.message` to the client without differentiating expected errors (4xx) from unexpected errors (5xx). For responses with status >= 500, always return a generic message (`'Internal server error'`) — never the raw exception message. Exposing Prisma connection errors, stack traces, or internal paths to clients is a P2 finding.
+
+#### P2 — Open Redirect
+- `res.redirect()` called with a user-supplied path (from `req.query`, `req.body`, `req.params`) without allowlist validation. Any redirect target that an attacker can control is a P2 finding.
+
+#### P2 — Prototype Pollution via Body/Query Merge
+- `req.query` or `req.body` merged into a plain object using spread, `Object.assign`, or similar without sanitisation. Use `structuredClone()` or a safe merge utility. Reference: CVE-2024-29041 class.
+
+#### P2 — Middleware Order
+- Authentication or authorisation middleware registered after route handlers it is meant to protect — P2. Middleware order in Express is execution order; a route registered before `app.use(authMiddleware)` is unprotected.
+
+### Build Checklist (Phase 6)
+
+- **Error handler shape:** Error handler must differentiate 4xx vs 5xx. Never forward `err.message` for status >= 500.
+- **Redirect validation:** Any `res.redirect()` that uses request-supplied data must validate against an explicit allowlist before redirecting.
+- **Middleware order:** Register global middleware (auth, rate limiting, body parsing) before route handlers, not after.

package/commands/mdd-rules-jwt.md

@@ -0,0 +1,23 @@
+## MDD Rules — JWT
+
+Rules loaded when `stack.auth` includes `jwt`. Applied additively to audit criteria and build checklists.
+
+### Audit Criteria
+
+#### P2 — decode() Instead of verify()
+- `jwt.decode()` used instead of `jwt.verify()` to process an incoming token — P2. `decode()` skips signature verification entirely. Any token, including a forged one, will appear valid. Always use `jwt.verify()` with the secret/public key.
+
+#### P2 — Unsafe Type Assertion After verify()
+- `jwt.verify()` result cast with a type assertion (`as JwtPayload`) without runtime narrowing on required fields — P2. `verify()` returns `string | JwtPayload`; casting directly sets fields to `undefined as string` when the payload shape doesn't match. Required fields (`sub`, `email`, `id`, etc.) must be checked with `typeof field === 'string'` before use.
+
+#### P2 — Empty-String Secret Fallback
+- JWT signing or verification called with an empty-string fallback for the secret (e.g. `process.env.JWT_SECRET || ''`) — P2. A server that signs tokens with `''` is equivalent to having no secret. Secret must be validated at startup.
+
+#### P3 — Missing Token Expiry Check
+- Token payload used without checking `exp` field when the library does not enforce it automatically — P3. Always pass `{ ignoreExpiration: false }` explicitly or verify the library's default behaviour.
+
+### Build Checklist (Phase 6)
+
+- **Always use verify(), never decode():** `jwt.decode()` is for inspecting token structure only — never for authentication.
+- **Runtime narrowing after verify():** After `jwt.verify()`, check that all required payload fields exist and are the expected type before using them.
+- **Secret at startup:** Add JWT secret(s) to `required_env` in the feature doc and add a startup validation block.

package/commands/mdd-rules-prisma.md

@@ -0,0 +1,23 @@
+## MDD Rules — Prisma
+
+Rules loaded when `stack.orm` includes `prisma`. Applied additively to audit criteria and build checklists.
+
+### Audit Criteria
+
+#### P2 — Raw Query Without Parameterisation
+- `prisma.$queryRaw` or `prisma.$executeRaw` used with string interpolation (`` `SELECT ... WHERE id = ${userId}` ``) instead of tagged template literals or `Prisma.sql` — P2. Raw string interpolation bypasses Prisma's parameterisation and is vulnerable to SQL injection.
+
+#### P2 — Missing Transaction for Multi-Step Writes
+- Multiple `prisma.model.create/update/delete` calls in a single handler without wrapping in `prisma.$transaction()` — P2 when the operations must be atomic (e.g. deducting balance and creating a record).
+
+#### P3 — PrismaClient Instantiated Per Request
+- `new PrismaClient()` called inside a request handler or per-import in multiple files — P3. A single shared client instance should be created once (e.g. `src/lib/prisma.ts`) and imported everywhere. Multiple instances exhaust the connection pool.
+
+#### P3 — Unhandled PrismaClientKnownRequestError
+- Prisma operations in request handlers without catching `PrismaClientKnownRequestError` — P3. Uncaught Prisma errors surface as 500s with internal schema details in the default Express error handler.
+
+### Build Checklist (Phase 6)
+
+- **Single shared client:** Create `src/lib/prisma.ts` exporting one `PrismaClient` instance. Import it everywhere — never instantiate in handlers.
+- **Transactions for atomic operations:** Any handler that writes to multiple tables must use `prisma.$transaction()`.
+- **Catch Prisma errors:** Wrap Prisma calls in try/catch and handle `PrismaClientKnownRequestError` with appropriate HTTP responses.

package/commands/mdd-rules-typescript.md

@@ -0,0 +1,30 @@
+## MDD Rules — TypeScript
+
+Rules loaded when `stack.language` includes `typescript`. Applied additively to audit criteria and build checklists.
+
+### Audit Criteria
+
+#### P2 — Switch Exhaustiveness
+- Switch statement on a string-union type or operation enum has no `default:` case — P2.
+- Switch `default:` returns any value (`''`, `undefined`, a node, etc.) instead of throwing with `satisfies never` — P2. Correct pattern: `default: throw new Error(\`unhandled: \${x satisfies never}\`)`.
+
+#### P2 — Type Assertion Safety
+- Type assertion (`as T`) used on the result of an external decode operation (`jwt.verify`, `JSON.parse`, schema validation output) without runtime narrowing on required fields — P2. Required fields must be checked with `typeof field === 'string'` (or equivalent) before use.
+
+#### P2 — Environment Startup Validation
+- Required environment variable accessed with an empty-string or falsy fallback (e.g. `process.env.SECRET || ''`) instead of throwing at startup when absent — P2. A server that boots silently with a missing secret is a latent vulnerability.
+
+#### P3 — Pattern Coverage in File
+- When a finding of type X is found in a file, grep the entire file for all other instances of the same pattern before marking the finding complete. A single finding does not imply the rest of the file is clean — P3 if additional instances are present and unflagged.
+
+### Build Checklist (Phase 6)
+
+- **Env validation block:** If `required_env` is non-empty in the feature doc, add a startup validation block to the server entry point before any route registration:
+  ```typescript
+  const REQUIRED_ENV = ['SECRET_KEY', 'DB_URL'];
+  for (const key of REQUIRED_ENV) {
+    if (!process.env[key]) throw new Error(`Missing required env var: ${key}`);
+  }
+  ```
+- **Switch exhaustiveness:** Every switch on a string-union or enum type must have a `default: throw new Error(\`unhandled: \${x satisfies never}\`)` branch.
+- **Shared utilities:** If `depends_on` is non-empty, scan the dependency's source files for shared infrastructure (error types, DB clients, utility functions). If the new feature would duplicate them, extract to a shared module before implementing.

package/commands/mdd-security-rules.md

@@ -0,0 +1,303 @@
+## SECURITY RULES MODE — `/mdd security-rules`
+
+Triggered when arguments start with `security-rules`. Also triggered automatically by AUDIT MODE when `$MDD_SECURITY_SCAN` is `true` (set via `securityScan: true` in `.mdd/settings.json`).
+
+This mode scans the project's declared stack for known vulnerabilities using free, locally-available tools, then compares each finding against existing MDD stack rule files. Any vulnerability pattern not already covered by an existing rule becomes a new rule, appended to the relevant `mdd-rules-{stack}.md` file. The goal is to keep rule files current without manual maintenance.
+
+**No API keys or paid accounts required.** All scanners used are free-tier or open tools.
+
+**This mode only generates audit rules.** It does not patch dependencies, modify source code, or install anything.
+
+---
+
+### Phase SS0 — Read Current Rules
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS0" start "$MDD_STACK"
+```
+
+Load all existing MDD stack rule files so the gap analysis in Phase SS2 has something to compare against.
+
+**Step 1 — Locate rule files:**
+
+For each entry in `$MDD_STACK`, check whether `$MDD_DIR/mdd-rules-{entry}.md` exists. Build two lists:
+
+- `$RULE_FILES_FOUND` — entries that have a rule file
+- `$RULE_FILES_MISSING` — entries with no rule file yet (a new file will be created in Phase SS3 if needed)
+
+**Step 2 — Extract existing rule descriptions:**
+
+For each file in `$RULE_FILES_FOUND`, read every bullet line that matches the MDD rule format:
+```
+- [P{N}] {description}
+```
+
+Extract the description text from each rule into a comparison set. Also extract any `Reference: CVE-XXXX-XXXXX` tokens present — these are the dedup keys used in Phase SS2.
+
+Store the full set in memory as `$EXISTING_RULES` — a list of objects:
+```
+{
+  stack_entry: "express",
+  priority: "P2",
+  description: "...",
+  cve_refs: ["CVE-2024-12345"]   // empty array if no Reference tag
+}
+```
+
+If no rule files exist at all, `$EXISTING_RULES` is empty and every finding in Phase SS1 will be treated as a gap.
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS0" end "$MDD_STACK"
+```
+
+---
+
+### Phase SS1 — Scan
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS1" start "$MDD_STACK"
+```
+
+Run vulnerability scanners against the project. Scanners are tried in priority order. Each failure is a one-line warning — never a halt.
+
+**Scanner priority order:**
+
+1. `npm audit` — Node/JS projects. Available if `package.json` or `package-lock.json` exists in the project root.
+2. `osv-scanner` — multi-language (Node, Go, Python, PHP, Ruby). Available if installed (`which osv-scanner`).
+3. `snyk` — multi-language, free CLI tier. Available if installed (`which snyk`).
+
+**Running each scanner:**
+
+For `npm audit`:
+```bash
+npm audit --json 2>/dev/null
+```
+Parse the JSON output. For each finding extract: `name` (package), `severity`, `via[].title` or `via[].url` for the vulnerability description, `via[].cve` or the advisory ID as the CVE ref, and the `fixAvailable` field.
+
+For `osv-scanner`:
+```bash
+osv-scanner --format json . 2>/dev/null
+```
+Parse the JSON output. For each result entry extract: `packages[].package.name`, `packages[].package.ecosystem`, `vulnerabilities[].id` (the CVE or OSV ID), `vulnerabilities[].summary`, `vulnerabilities[].database_specific.severity`.
+
+For `snyk`:
+```bash
+snyk test --json 2>/dev/null
+```
+Parse the JSON output. For each vulnerability in `vulnerabilities[]` extract: `packageName`, `severity`, `title`, `identifiers.CVE[0]` as the CVE ref, and `description`.
+
+**Failure handling for each scanner:**
+
+If a scanner is not installed, outputs non-JSON, exits with a parse error, or times out after 30 seconds:
+- Emit one line: `⚠ {scanner-name} skipped: {reason}`
+- Continue with remaining scanners
+
+If zero scanners are applicable to the declared stack (e.g., Go-only project with no `osv-scanner` installed), emit:
+```
+⚠ No scanners available for stack: {$MDD_STACK}
+  Install osv-scanner (https://google.github.io/osv-scanner/) for multi-language support.
+```
+Then skip to Phase SS4 with zero findings.
+
+**Aggregate all findings** from all successful scanners into `$SCAN_FINDINGS`:
+```
+{
+  scanner: "npm-audit",
+  package: "express",
+  ecosystem: "npm",
+  severity: "high",          // critical | high | medium | low
+  cve_id: "CVE-2024-29041",
+  title: "Open redirect in express",
+  description: "...",
+  attack_vector: "open redirect via unvalidated Location header"
+}
+```
+
+Deduplicate by `cve_id` — if two scanners report the same CVE, keep one entry (prefer the one with the richer description).
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS1" end "$MDD_STACK"
+```
+
+---
+
+### Phase SS2 — Gap Analysis
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS2" start "$MDD_STACK"
+```
+
+For each finding in `$SCAN_FINDINGS`, determine whether the vulnerability pattern is already covered by an existing rule.
+
+**How the gap check works:**
+
+This is a semantic comparison, not a string match. A finding is covered if an existing rule already addresses the same vulnerability *class* — even if the rule was written in different words or references a different CVE.
+
+Apply the following two-step check in order:
+
+**Step 1 — CVE dedup (exact match):**
+If any rule in `$EXISTING_RULES` contains `Reference: {cve_id}` where `cve_id` matches the finding's CVE ID exactly — the finding is already covered. Skip it. This prevents regenerating rules that were added by a previous security scan.
+
+**Step 2 — Semantic coverage check:**
+Read the finding's `attack_vector` and `title`. Then ask: does any existing rule in `$EXISTING_RULES` address the same vulnerability class?
+
+Examples of semantic coverage (do NOT regenerate):
+- Finding: "prototype pollution via `req.query`" — covered by any rule mentioning prototype pollution on user-supplied input
+- Finding: "ReDoS via malformed email input" — covered by any rule about regex denial-of-service or unbounded regex on user input
+- Finding: "path traversal in static file serving" — covered by any rule requiring path confinement or jailRoot validation
+
+Examples where a new rule IS needed (not semantically covered):
+- Finding: "open redirect via unvalidated Location header" — NOT covered by a rule about SSRF (different class)
+- Finding: "timing attack on HMAC comparison" — NOT covered by a generic input validation rule
+
+If the finding passes both checks with no coverage match, it is a **gap** — add it to `$RULE_GAPS`.
+
+**Classify each gap by stack entry:**
+
+Map the gap's `package` or `ecosystem` back to the most relevant stack entry in `$MDD_STACK`. If no entry matches directly, use the ecosystem name as a fallback stack label (e.g., `npm`, `pypi`).
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS2" end "$MDD_STACK"
+```
+
+---
+
+### Phase SS3 — Rule Generation
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS3" start "$MDD_STACK"
+```
+
+For each gap in `$RULE_GAPS`, generate a new MDD audit rule and append it to the relevant rule file.
+
+**Severity mapping (CVSS → MDD priority):**
+
+| CVSS severity | MDD priority |
+|---|---|
+| critical | P2 |
+| high | P2 |
+| medium | P3 |
+| low | P4 |
+
+P1 is reserved for MDD's own hardcoded security invariants and is **never auto-generated** by this mode.
+
+**Rule format:**
+
+```markdown
+- [P{N}] {attack_vector_description} - {what to check for}. Reference: {CVE_ID}.
+```
+
+**Writing a good generated rule:**
+
+The rule must target the vulnerability *class*, not the specific package version or CVE instance. A good rule catches the pattern in new code and in dependency updates before they appear in future vulnerability databases.
+
+Guidelines:
+- Describe the attack vector in general terms (e.g., "unvalidated redirect destination", "prototype pollution via query parameters", "timing-unsafe string comparison for secrets")
+- State what the audit should check for — a concrete, actionable thing to look at in code review
+- Include the CVE ID as a `Reference:` tag so the dedup check in future scans can identify it
+- Write the rule in the same imperative style as existing rules in the file
+
+Good example:
+```markdown
+- [P2] Unvalidated redirect destination allows open redirect attacks - check that redirect targets are validated against an allowlist or are relative paths only. Reference: CVE-2024-29041.
+```
+
+Bad example (too CVE-specific, won't catch future variants):
+```markdown
+- [P2] express 4.x open redirect via res.location() - upgrade to 4.19.2. Reference: CVE-2024-29041.
+```
+
+**Appending to rule files:**
+
+For each stack entry with new rules:
+1. Check whether `$MDD_DIR/mdd-rules-{stack-entry}.md` exists.
+   - If yes: append the new rules to the end of the file.
+   - If no: create the file with a minimal header and the new rules:
+     ```markdown
+     # MDD Rules — {stack-entry}
+     
+     Stack-specific audit rules for {stack-entry}. Auto-generated from vulnerability scan results.
+     
+     ```
+2. Append each new rule as a bullet line under a `## Security (auto-generated)` section header.
+   - If that section already exists in the file: append to it.
+   - If it does not exist yet: add it before appending rules.
+
+Track how many rules were added per file for the Phase SS4 summary.
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS3" end "$MDD_STACK"
+```
+
+---
+
+### Phase SS4 — Report
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS4" start "$MDD_STACK"
+```
+
+Write the scan summary to `.mdd/audits/security-scan-{YYYY-MM-DD}.md` (date from current date).
+
+**Summary file format:**
+
+```markdown
+# Security Scan — {YYYY-MM-DD}
+
+## Sources
+
+| Scanner | Status | Findings |
+|---------|--------|----------|
+| npm audit | ok | {N} |
+| osv-scanner | skipped: not installed | - |
+| snyk | ok | {N} |
+
+## Results
+
+Findings reviewed:   {N}
+Already covered:     {N}
+New gaps found:      {N}
+New rules generated: {N}
+
+### Rules Added
+
+- mdd-rules-{stack-entry}.md: +{N} rules
+- mdd-rules-{stack-entry}.md: +{N} rules
+
+### New Rules (full text)
+
+{list each generated rule with its target file}
+```
+
+If zero findings were returned across all scanners (clean bill of health):
+
+```markdown
+# Security Scan — {YYYY-MM-DD}
+
+All scanners returned zero findings. No new rules generated.
+
+Scanners run: {list}
+Stack checked: {$MDD_STACK}
+```
+
+**Present to the user:**
+
+```
+Security scan complete — {YYYY-MM-DD}
+
+Scanners:    {list of scanners that ran} ({N} skipped)
+Findings:    {N} total, {N} new gaps
+Rules added: {N} ({list of files updated})
+
+Full report: .mdd/audits/security-scan-{YYYY-MM-DD}.md
+```
+
+If running as a sub-task of AUDIT MODE (triggered via `$MDD_SECURITY_SCAN`), suppress the user-facing output above — just write the file and return. AUDIT MODE's own output will surface the result.
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "Phase SS4" end "$MDD_STACK"
+```
+
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh "mdd-security-rules" "-" "complete" "$MDD_STACK"
+```

package/commands/mdd.md

@@ -98,6 +98,85 @@ Read CLAUDE.md for the full rulebook. Key rules:
 
 This bootstrap runs for **all modes** — build, audit, scan, update, and every other mode — so no mode ever fails due to a missing `.mdd/` structure.
 
+## Step 0c — Settings Bootstrap (silent, automatic)
+
+After the directory structure is confirmed, load project settings. This also runs for every mode and never prompts the user.
+
+**Read or create `.mdd/settings.json`:**
+
+If the file does not exist, create it with this default and report one line:
+
+```json
+{
+  "autoDiscovery": true,
+  "stack": {
+    "language": [],
+    "runtime": [],
+    "frameworks": [],
+    "orm": [],
+    "auth": []
+  },
+  "overrides": {},
+  "phaseLogging": true,
+  "securityScan": false
+}
+```
+
+```
+📋 MDD settings initialised: .mdd/settings.json
+```
+
+If the file exists but cannot be read or is not valid JSON: emit one warning (`⚠ settings.json unreadable — running without stack rules`) and proceed with all defaults. Never halt.
+
+**Set session variables from settings:**
+
+- `$MDD_PHASE_LOGGING` = `settings.phaseLogging` (default: `true`)
+- `$MDD_SECURITY_SCAN` = `settings.securityScan` (default: `false`)
+
+**If `autoDiscovery: true`, run stack detection** — check manifest files in the project root:
+
+| File | What to detect |
+|------|----------------|
+| `package.json` | language (`typescript` if typescript in deps, else `javascript`), runtime (`node`), plus frameworks/orm/auth from dep names below |
+| `go.mod` | language: `go` |
+| `pyproject.toml` or `requirements.txt` | language: `python` |
+| `composer.json` | language: `php` |
+
+For `package.json`, scan both `dependencies` and `devDependencies` for these known packages:
+
+| Package(s) | Category | Stack value |
+|-----------|----------|-------------|
+| `typescript` | language | `typescript` |
+| `express` | frameworks | `express` |
+| `fastify` | frameworks | `fastify` |
+| `koa` | frameworks | `koa` |
+| `hono` | frameworks | `hono` |
+| `next` | frameworks | `nextjs` |
+| `react` | frameworks | `react` |
+| `vue` | frameworks | `vue` |
+| `@prisma/client` | orm | `prisma` |
+| `drizzle-orm` | orm | `drizzle` |
+| `typeorm` | orm | `typeorm` |
+| `mongoose` | orm | `mongoose` |
+| `jsonwebtoken`, `jose` | auth | `jwt` |
+| `passport` | auth | `passport` |
+
+Write detected entries back into `settings.json` under `stack` (non-destructive — only updates `stack`, never touches `overrides`, `phaseLogging`, `autoDiscovery`, or `securityScan`).
+
+If `autoDiscovery: false`, read `settings.json` as-is — no scan runs.
+
+**Build `$MDD_STACK`** by merging `stack` + `overrides` into a flat deduplicated array of all values across all categories.
+
+If the stack was newly detected or changed, report one line:
+```
+📋 Stack: typescript, node, express, prisma, jwt  |  phase logging: on  |  security scan: off
+```
+
+**Phase logging gate:** All `mdd-log-phase.sh` calls throughout every mode file must be wrapped:
+```bash
+[ "$MDD_PHASE_LOGGING" = "false" ] || bash ~/.claude/hooks/mdd-log-phase.sh ...
+```
+
 ## Step 0b — Detect Mode
 
 The user's full arguments are: **$ARGUMENTS**
@@ -136,6 +215,9 @@ Use whichever path contains `mdd-audit.md`. Store it as `$MDD_DIR` and use it fo
 - If arguments start with `bug` →
   **Read `$MDD_DIR/mdd-bug.md` then follow BUG MODE instructions.**
 
+- If arguments start with `security-rules` →
+  **Read `$MDD_DIR/mdd-security-rules.md` then follow SECURITY RULES MODE instructions.**
+
 - If arguments are empty → ask the user what they want to do (build a feature, run an audit, check status, etc.)
 
 - Otherwise → **Read `$MDD_DIR/mdd-build.md` then follow BUILD MODE instructions.**

package/package.json

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