@thedecipherist/mdd 1.5.12 → 1.6.1

package/commands/mdd-audit.md

@@ -31,10 +31,18 @@ A completed audit exists from <date>.
 
   [F] Full audit — regenerate manifest from all source files
       Use when: significant new code added, want a clean baseline, or last audit was >2 weeks ago
-  [I] Incremental — manifest contains only files modified since <date>
+  [I] Incremental — manifest contains only files whose content changed since last audit
       Use when: applied fixes and want to verify them, or auditing only a new feature
 ```
 
+For incremental scope, use git to detect truly changed files — not mtime, which is unreliable:
+```bash
+git diff --name-only <last-audit-commit>   # files changed since audit commit
+git ls-files --others --exclude-standard   # untracked new files
+```
+If no audit commit is recorded, fall back to files modified after `audits/MANIFEST-<date>.md` mtime.
+Store the current HEAD commit in the job folder (`job-commit.txt`) so future incremental audits have an exact reference point. Files modified and then reverted will NOT appear in the diff — correct behaviour.
+
 **Agent scaling:**
 
 | Files in scope | Agents |
@@ -129,6 +137,9 @@ Manifest:    .mdd/jobs/audit-<date>/MANIFEST.md
 - 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
+- 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
+- Silent error swallow: catch block returns empty/undefined without pushing to warnings array
 
 ### P4 Low
 - Code style inconsistencies
@@ -263,11 +274,22 @@ Fix all now? (yes / review report first / fix only P1+P2)
 
 If user says yes (or selects a subset):
 
-**Fix loop:** Read the findings report. For each finding to fix:
-1. Read the specific source files
+**Fix loop:**
+
+Detect test runner once from `package.json` scripts (look for `test:unit`, `test`, `vitest`, `jest`, `pytest`, `go test`). Identify the file-scope flag for that runner:
+- Vitest / Jest: `pnpm test:unit -- <path/to/file.test.ts>`
+- pytest: `pytest <path/to/test_file.py>`
+- Go: `go test ./<package>/...`
+
+For each finding to fix:
+1. Read the specific source file(s)
 2. Apply the fix
-3. Write or update tests
-4. Run tests after each fix group
+3. Write or update the corresponding test file(s)
+4. Run ONLY the test file(s) that cover the changed source — not the full suite.
+   Derive test path from source path by convention (e.g. `src/foo/bar.ts` → `tests/unit/foo/bar.test.ts`).
+   If the mapping is ambiguous, grep for imports of the changed file to find the right test.
+
+After ALL findings are fixed: run the full test suite once as a regression check.
 
 Report progress per finding. Update documentation `known_issues` to remove fixed items. Update `mdd_version` to current on every `.mdd/docs/*.md` file that is edited during fixes.
 

package/commands/mdd-build.md

@@ -638,6 +638,18 @@ Quality gates passing does not mean the feature works. This phase verifies actua
 □ Confirm no unintended side effects on unrelated files or state
 ```
 
+**Spec invariants — applies when the feature doc references spec language like "cannot be overridden", "always blocked", "immutable", "confinement", or "required":**
+```
+□ Every spec-stated invariant must be verifiably enforced in code:
+    "cannot be overridden" → Object.freeze() on arrays/objects + readonly type
+    "always blocked" → the block path runs BEFORE any allow logic
+    "confinement" → an actual path check exists at every entry point, not just a gate module
+    "required" → ParseError or equivalent thrown for missing values (no silent empty string)
+□ Run grep for the invariant keyword in source — verify it appears in a test assertion, not just prose
+□ If the spec says module X enforces Y, verify X is actually CALLED at the relevant call site
+    (building a security module is not the same as wiring it)
+```
+
 **Ownership Default — applies to ALL feature types:**
 
 ```

package/commands/mdd-plan.md

@@ -278,8 +278,20 @@ For each feature in the wave's feature table, in dependency order, skipping `com
 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.
-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.
+6. **PE3 Completion Gate** — run these checks BEFORE marking `[x]`. This is a hard gate, not advisory.
+
+   **a. source_files existence check** — read `source_files` from the feature doc. For each file listed, verify it exists on disk:
+   ```bash
+   # For each file in source_files:
+   test -f <path> && echo "OK: <path>" || echo "MISSING: <path>"
+   ```
+   If any file is missing: mark the feature `[!]` in MANIFEST with the list of missing files. Do NOT proceed to step 7 — implement the missing files or explicitly document them as deferred in `known_issues`.
+
+   **b. satisfies_contracts verification** — read `satisfies_contracts` from the feature doc. If any entry is still `status: pending`, the security/integration contract was never wired. Find the call site, wire it, update to `verified: <file>:<line>`. A feature cannot be `[x]` with pending contracts.
+
+   **c. Doc status write** — confirm `status: complete` is in the feature doc frontmatter. Phase 7c should have written this. If it is missing (still `draft` or `in_progress`), write it now along with `last_synced: <today>` and `phase: all`. This is NOT optional — a missing status write means the doc audit will flag the feature as incomplete on the next run.
+
+7. Mark the feature `[x]` in `MANIFEST.md`. If the completion gate blocked (step 6a or 6b failed), mark `[!]` with a one-line note listing what was missing.
 8. Ask: *"Feature N done ✓. Start Feature N+1? (yes / pause here)"*
 
 **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.

package/package.json

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