@thedecipherist/mdd 1.7.1 → 1.8.0

package/commands/mdd-plan.md

@@ -1,23 +1,13 @@
-## Phase Logging
-
-At the **start** of every phase (before any action) and the **end** of every phase (after all actions), run the command below. Substitute:
-- `PHASE` with the phase identifier **and the initiative or wave slug** from `$ARGUMENTS` — e.g., `Phase PI1 (my-initiative)`, `Phase PW3 (wave-auth)`, `Phase PE2 (wave-checkout)`
-- `EVENT` with `start` or `end`
-
-```bash
-bash -c 'D=$(date +%Y-%m-%d); T=$(date +%H:%M:%S); K=$(compressmcp --status 2>/dev/null | grep -oE "[0-9]+K/[0-9]+K" | head -1 || echo "-"); mkdir -p ~/.claude/mdd; printf "| %s | mdd-plan | PHASE | EVENT | %s | %s |\n" "$D" "$T" "$K" >> ~/.claude/mdd/log.md' 2>/dev/null || true
-```
-
-Log file: `~/.claude/mdd/log.md`
-
----
-
 ## PLAN-INITIATIVE MODE — `/mdd plan-initiative`
 
 Triggered when arguments start with `plan-initiative`. Creates a new initiative doc.
 
 ### Phase PI0 — Branch Guard
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI0" start "$PLAN_TARGET"
+```
+
 Run before any file creation:
 
 ```bash
@@ -30,8 +20,16 @@ DIRTY=$(git status --porcelain)
 - **On a feature branch** → working dirty is fine. Proceed — initiative planning docs belong on whatever branch is current.
 - **Never proceed on main.** Hard block.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI0" end "$PLAN_TARGET"
+```
 ### Phase PI1 — Mode choice
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI1" start "$PLAN_TARGET"
+```
+
 Ask the user:
 ```
 How do you want to create this initiative?
@@ -52,8 +50,16 @@ How do you want to create this initiative?
 
 **If (a) Guide me:** proceed to Phase PI2.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI1" end "$PLAN_TARGET"
+```
 ### Phase PI2 — Questions
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI2" start "$PLAN_TARGET"
+```
+
 Ask all questions in a single interaction:
 1. "What is the title of this initiative?"
 2. "Describe it — what does it deliver and why does it exist?"
@@ -61,8 +67,16 @@ Ask all questions in a single interaction:
 4. For each wave: "Wave N — name and one-sentence demo-state (what can the user DO when this wave is done?)"
 5. "What's still undecided that could affect architecture?" → these become open product questions (unchecked `- [ ]` items)
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI2" end "$PLAN_TARGET"
+```
 ### Phase PI3 — Write initiative doc
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI3" start "$PLAN_TARGET"
+```
+
 **Slug format:** lowercase, hyphens, no special characters. "Auth System" → `auth-system`.
 
 **Collision check:** same as template mode above.
@@ -99,8 +113,16 @@ Compute and write `hash:` field after writing (hash of file content excluding th
 
 Rebuild `.mdd/.startup.md`.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI3" end "$PLAN_TARGET"
+```
 ### Phase PI4 — Chain to plan-wave
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI4" start "$PLAN_TARGET"
+```
+
 Show the created doc to the user. Ask:
 *"Want to plan Wave 1 now? (yes / no — I'll run /mdd plan-wave <slug>-wave-1 later)"*
 
@@ -108,12 +130,24 @@ If yes → run Phase PW1 inline for `<slug>-wave-1`.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PI4" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```
 ## PLAN-WAVE MODE — `/mdd plan-wave <wave-slug>`
 
 Triggered when arguments start with `plan-wave`. Takes a wave slug (e.g. `auth-system-wave-2`), resolves the parent initiative from it.
 
 ### Phase PW1 — Load and validate
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW1" start "$PLAN_TARGET"
+```
+
 **Step 0 — Branch guard:**
 
 ```bash
@@ -134,24 +168,48 @@ DIRTY=$(git status --porcelain)
 6. **Depends-on gate:** read existing wave docs for this initiative. If the new wave's `depends_on` wave exists and is not `complete` → hard stop.
 7. Surface context summary to user: initiative title, overview, wave count, which waves are done.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW1" end "$PLAN_TARGET"
+```
 ### Phase PW2 — Mode choice
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW2" start "$PLAN_TARGET"
+```
+
 Same as PI1: ask "(a) Guide me / (b) Template".
 
 **If (b) Template:** create `waves/<wave-slug>.md` with blank template, tell user to fill it out and run `/mdd plan-sync` then `/mdd plan-execute <wave-slug>`.
 
 **If (a) Guide me:** proceed to Phase PW3.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW2" end "$PLAN_TARGET"
+```
 ### Phase PW3 — Questions
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW3" start "$PLAN_TARGET"
+```
+
 Ask in a single interaction:
 1. "Here's the demo-state from the initiative: [X]. Does this need sharpening for this wave?"
 2. "List the features needed to reach that demo-state — name + one-line description each."
 3. "Do any features depend on other features within this wave?"
 4. "Any open research questions before building? Or none?"
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW3" end "$PLAN_TARGET"
+```
 ### Phase PW4 — Write wave doc
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW4" start "$PLAN_TARGET"
+```
+
 Create `waves/<wave-slug>.md`:
 
 ```markdown
@@ -187,19 +245,39 @@ Compute and write `hash:` field. Update the Waves table in `initiatives/<slug>.m
 
 Rebuild `.mdd/.startup.md`.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW4" end "$PLAN_TARGET"
+```
 ### Phase PW5 — Chain
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW5" start "$PLAN_TARGET"
+```
+
 Ask: *"Want to plan Wave N+1 now? (yes / no)"*
 If yes → run Phase PW1 inline for the next wave slug.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PW5" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```
 ## PLAN-EXECUTE MODE — `/mdd plan-execute <wave-slug>`
 
 Triggered when arguments start with `plan-execute`. Runs the full MDD build flow for each feature in the wave.
 
 ### Phase PE1 — Load and validate
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE1" start "$PLAN_TARGET"
+```
+
 **Step 0 — Branch guard (runs before everything else):**
 
 ```bash
@@ -245,8 +323,16 @@ DIRTY=$(git status --porcelain)
    - **Discard:** delete the `wave-<wave-slug>/` folder, proceed to PE2 normally.
    - If no stale job exists: proceed to PE2 normally.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE1" end "$PLAN_TARGET"
+```
 ### Phase PE2 — Interaction mode + Job Setup
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE2" start "$PLAN_TARGET"
+```
+
 Ask:
 ```
 How do you want to run this wave?
@@ -282,8 +368,16 @@ Create `.mdd/jobs/wave-<wave-slug>/MANIFEST.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.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE2" end "$PLAN_TARGET"
+```
 ### Phase PE3 — Execute features
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE3" start "$PLAN_TARGET"
+```
+
 For each feature in the wave's feature table, in dependency order, skipping `complete` features:
 
 1. Tell user: *"Starting Feature N: <feature-slug>"*
@@ -310,8 +404,16 @@ For each feature in the wave's feature table, in dependency order, skipping `com
 
 **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.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE3" end "$PLAN_TARGET"
+```
 ### Phase PE4 — Wave completion
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE4" start "$PLAN_TARGET"
+```
+
 When all features are `complete`:
 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?"*
@@ -343,12 +445,24 @@ Read all `.mdd/docs/*.md` (excluding `archive/`) — frontmatter only (id, title
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PE4" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```
 ## PLAN-SYNC MODE — `/mdd plan-sync`
 
 Triggered when arguments start with `plan-sync`. Detects manual edits to initiative/wave files via hash comparison and reconciles them.
 
 ### Phase PS1 — Scan all files
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS1" start "$PLAN_TARGET"
+```
+
 Read every file in `.mdd/initiatives/` and `.mdd/waves/` (including `archive/`). For each, compute the hash of the file content (excluding the `hash:` line). Compare against stored `hash:` field.
 
 Build a change table:
@@ -359,8 +473,16 @@ auth-system-wave-1.md            | def456      | abc999        | YES
 billing-module.md                | (empty)     | xyz111        | YES (new — no hash yet)
 ```
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS1" end "$PLAN_TARGET"
+```
 ### Phase PS2 — Present changes + confirm
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS2" start "$PLAN_TARGET"
+```
+
 Show the full change table. Tell the user what will happen:
 
 - **Initiative changed:** version incremented, hash updated, completed waves with old `initiative_version` flagged for review
@@ -369,8 +491,16 @@ Show the full change table. Tell the user what will happen:
 
 Ask: *"Apply these updates? (yes / review each / cancel)"*
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS2" end "$PLAN_TARGET"
+```
 ### Phase PS3 — Apply
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS3" start "$PLAN_TARGET"
+```
+
 For each changed file, in initiative-first order:
 
 **Initiative changed:**
@@ -403,19 +533,39 @@ Report:
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PS3" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```
 ## PLAN-REMOVE-FEATURE MODE — `/mdd plan-remove-feature <wave-slug> <feature-slug>`
 
 Triggered when arguments start with `plan-remove-feature`.
 
 ### Phase PRF1 — Load and validate
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PRF1" start "$PLAN_TARGET"
+```
+
 1. Parse `<wave-slug>` and `<feature-slug>` from arguments.
 2. Read wave doc — hard stop *"Wave does not exist"* if not found.
 3. Find the feature row — hard stop *"Feature `<slug>` does not exist in wave `<wave-slug>`"* if not found.
 4. **Dependency guard:** check if any other feature in the wave lists `<feature-slug>` in its `Depends on` column. If so → hard stop: *"`<other-feature>` depends on `<feature-slug>`. Remove or reassign that dependency first."*
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PRF1" end "$PLAN_TARGET"
+```
 ### Phase PRF2 — Confirm and remove
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PRF2" start "$PLAN_TARGET"
+```
+
 Show summary:
 ```
 Remove feature from wave?
@@ -441,17 +591,37 @@ Rebuild `.mdd/.startup.md`.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PRF2" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```
 ## PLAN-CANCEL-INITIATIVE MODE — `/mdd plan-cancel-initiative <slug>`
 
 Triggered when arguments start with `plan-cancel-initiative`.
 
 ### Phase PCI1 — Load
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI1" start "$PLAN_TARGET"
+```
+
 1. Parse `<slug>` — hard stop *"Initiative does not exist"* if `initiatives/<slug>.md` not found.
 2. Read initiative doc. Count: waves, wave statuses, associated feature docs (those with `initiative: <slug>` frontmatter).
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI1" end "$PLAN_TARGET"
+```
 ### Phase PCI2 — Confirm
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI2" start "$PLAN_TARGET"
+```
+
 Show summary:
 ```
 Cancel initiative: Auth System
@@ -465,8 +635,16 @@ Cancel this initiative? (yes/no)
 
 If yes:
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI2" end "$PLAN_TARGET"
+```
 ### Phase PCI3 — Cancel
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI3" start "$PLAN_TARGET"
+```
+
 1. Set `status: cancelled` in initiative frontmatter. Recompute hash.
 2. Ask: *"Archive wave docs? (yes/no)"* — if yes, move all wave files to `.mdd/waves/archive/`
 3. Ask: *"Flag feature docs with a warning? (yes/no)"* — if yes, add to each associated feature doc's `known_issues`: `"Initiative <slug> was cancelled — review whether this feature is still needed."`
@@ -483,3 +661,12 @@ Report:
 ```
 
 ---
+
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "Phase PCI3" end "$PLAN_TARGET"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-plan" "-" "complete" "$PLAN_TARGET"
+```

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.