@atlashub/smartstack-cli 4.26.0 → 4.28.0

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -191,6 +191,129 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
 }
 ```
 
+## Entity-Level File Completeness Check (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** Artifact verification checked "at least one file per category"
+> but never reconciled against the **handoff contract** (`prd.implementation.filesToCreate`).
+> Result: 4/17 API endpoints were missing but the category showed "complete" because *some* controllers existed.
+
+```javascript
+// BLOCKING: Verify EVERY file from prd.implementation.filesToCreate exists on disk
+const filesToCreate = prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  const handoffMissing = [];
+  const handoffPresent = [];
+
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      const filePath = file.path || file;
+      if (fileExists(filePath)) {
+        handoffPresent.push({ category, path: filePath });
+      } else {
+        handoffMissing.push({ category, path: filePath });
+      }
+    }
+  }
+
+  const totalHandoff = handoffPresent.length + handoffMissing.length;
+  const coveragePct = totalHandoff > 0 ? Math.round((handoffPresent.length / totalHandoff) * 100) : 100;
+  console.log(`Handoff file coverage: ${handoffPresent.length}/${totalHandoff} (${coveragePct}%)`);
+
+  if (handoffMissing.length > 0) {
+    console.error(`BLOCKING: ${handoffMissing.length} files from handoff contract missing on disk`);
+
+    // Group missing files by category for targeted remediation
+    const missingByCategory = {};
+    for (const m of handoffMissing) {
+      if (!missingByCategory[m.category]) missingByCategory[m.category] = [];
+      missingByCategory[m.category].push(m.path);
+    }
+
+    // Inject remediation tasks for each missing file
+    let maxIdNum = Math.max(...prd.tasks.map(t => {
+      const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
+      return isNaN(num) ? 0 : num;
+    }), 0);
+    const prefix = prd.tasks[0]?.id?.replace(/[0-9]+$/, '') || 'HNDOFF-';
+
+    for (const [cat, paths] of Object.entries(missingByCategory)) {
+      for (const p of paths) {
+        // Skip if a remediation task already exists for this file
+        const alreadyExists = prd.tasks.some(t =>
+          t.description.includes(p) && t.description.includes('[HANDOFF-REMEDIATION]')
+        );
+        if (alreadyExists) continue;
+
+        maxIdNum++;
+        prd.tasks.push({
+          id: `${prefix}${String(maxIdNum).padStart(3, '0')}`,
+          description: `[HANDOFF-REMEDIATION] Create missing file: ${p}`,
+          status: 'pending',
+          category: cat,
+          dependencies: [],
+          acceptance_criteria: `File ${p} exists on disk and compiles`,
+          started_at: null, completed_at: null, iteration: null,
+          commit_hash: null, files_changed: [], validation: null, error: null
+        });
+      }
+      console.error(`  ${cat}: ${paths.length} missing — ${paths.map(p => p.split('/').pop()).join(', ')}`);
+    }
+
+    writeJSON(currentPrdPath, prd);
+  }
+} // end filesToCreate check
+```
+
+## Type Reference Verification (Cross-File Integrity)
+
+> **LESSON LEARNED (audit ba-002):** Artifact verification counted files but didn't check
+> that types referenced in code actually exist. `EmployeeListDto` was used in services
+> but the file was missing — a "phantom reference" that artifact file-counting missed.
+
+```javascript
+// After artifact checks, verify cross-file type references for completed categories
+if (completedCats.has('application') && completedCats.has('api')) {
+  const serviceFiles = glob('src/**/Services/**/*Service.cs');
+  const dtoFiles = glob('src/**/DTOs/**/*.cs');
+  const entityFiles = glob('src/**/Domain/**/*.cs');
+
+  // Extract all DTO type names from actual files
+  const existingTypes = new Set();
+  for (const f of [...dtoFiles, ...entityFiles]) {
+    const content = readFile(f);
+    const typeMatches = content.matchAll(/(?:class|record|struct|enum|interface)\s+(\w+)/g);
+    for (const m of typeMatches) existingTypes.add(m[1]);
+  }
+
+  // Check service files for references to types that don't exist
+  const phantomRefs = [];
+  for (const f of serviceFiles) {
+    const content = readFile(f);
+    // Look for Dto/Entity type references in return types and method params
+    const typeRefs = content.matchAll(/(?:<|,\s*|\(|new\s+)(\w+(?:Dto|Entity|Exception))\b/g);
+    for (const m of typeRefs) {
+      if (!existingTypes.has(m[1]) && !m[1].startsWith('I')) {
+        phantomRefs.push({ file: f, type: m[1] });
+      }
+    }
+  }
+
+  if (phantomRefs.length > 0) {
+    console.error(`PHANTOM TYPE REFERENCES DETECTED (${phantomRefs.length}):`);
+    phantomRefs.forEach(r => console.error(`  ${r.file}: references ${r.type} — TYPE DOES NOT EXIST`));
+
+    // Reset application category tasks to pending — code references non-existent types
+    prd.tasks.filter(t => t.category === 'application' && t.status === 'completed')
+      .forEach(t => {
+        t.status = 'pending';
+        t.error = `Phantom type references: ${phantomRefs.map(r=>r.type).join(', ')}`;
+        t.completed_at = null;
+      });
+    writeJSON(currentPrdPath, prd);
+  }
+}
+```
+
 ---
 
 ## Key Rules
@@ -198,4 +321,6 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
 - **Inject EVERY iteration:** Not just once during load
 - **Frontend depends on seedData:** Not just API
 - **Check artifacts:** Mark tasks pending if files don't exist
+- **Check type references:** Verify types used in code actually exist (phantom reference detection)
+- **Check handoff files:** Verify EVERY file from `prd.implementation.filesToCreate` exists on disk
 - **Never skip:** This is the blocker for "missing frontend/test" failures

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -289,6 +289,35 @@ if (pending > 0) {
 console.log(`Apex completed: ${completed}/${batchIds.length} tasks`);
 ```
 
+### B3b. Post-Batch Build Verification (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** Without build checks between batches, compilation
+> errors from early batches propagate silently through all subsequent batches.
+> The final "Build PASS" was never actually verified.
+
+```bash
+# Quick build check after each batch — BLOCKING if fails
+dotnet build --no-restore --verbosity quiet
+if [ $? -ne 0 ]; then
+  echo "BLOCKING: Build fails after batch [${firstCategory}]"
+  # Inject immediate fix task — will be picked up next iteration
+fi
+```
+
+```javascript
+if (BUILD_FAILED) {
+  const maxId = Math.max(...updatedPrd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+  updatedPrd.tasks.push({
+    id: `FIX-${maxId+1}`,
+    description: `BLOCKING: Fix build regression after ${firstCategory} batch`,
+    status: 'pending', category: 'validation', dependencies: [],
+    acceptance_criteria: 'dotnet build passes with 0 errors'
+  });
+  writeJSON(currentPrdPath, updatedPrd);
+  // Continue to section C (commit) then D (loop) — fix task will be picked up next iteration
+}
+```
+
 ---
 
 ## C. Commit PRD State
@@ -306,7 +335,65 @@ appendFile('.ralph/progress.txt',
 );
 ```
 
-### C2. Increment Iteration
+### C2. Skipped Task Audit
+
+After apex returns, check for newly skipped tasks:
+
+> **LESSON LEARNED (audit ba-002):** Individual skips in critical categories (api, test, domain,
+> infrastructure) allowed 4/17 endpoints and 74% stub tests to pass undetected. The old logic
+> only blocked when ALL tasks in a category were skipped — individual skips slipped through.
+
+```javascript
+const CRITICAL_CATEGORIES = ['api', 'test', 'domain', 'infrastructure'];
+const MAX_SKIP_RETRIES = 3;
+
+const newlySkipped = prdCheck.tasks.filter(t =>
+  batchIds.includes(t.id) && t.status === 'skipped'
+);
+if (newlySkipped.length > 0) {
+  console.warn(`⚠ ${newlySkipped.length} tasks were SKIPPED by apex:`);
+  newlySkipped.forEach(t => console.warn(`  - ${t.id}: ${t.description} [${t.category}]`));
+
+  const skippedCategories = [...new Set(newlySkipped.map(t => t.category))];
+  for (const cat of skippedCategories) {
+    const isCritical = CRITICAL_CATEGORIES.includes(cat);
+    const allInCat = prdCheck.tasks.filter(t => t.category === cat);
+    const allSkipped = allInCat.every(t => t.status === 'skipped');
+
+    if (isCritical) {
+      // CRITICAL CATEGORY: Block on INDIVIDUAL skips (not just when ALL are skipped)
+      const skippedInCat = newlySkipped.filter(t => t.category === cat);
+      for (const t of skippedInCat) {
+        const retryCount = t._skipRetryCount || 0;
+        if (retryCount < MAX_SKIP_RETRIES) {
+          console.error(`BLOCKING: Task ${t.id} skipped in critical category "${cat}" — reset to pending (retry ${retryCount + 1}/${MAX_SKIP_RETRIES})`);
+          t.status = 'pending';
+          t._skipRetryCount = retryCount + 1;
+          t._retryCount = (t._retryCount || 0) + 1;
+          t.error = `Skipped in critical category "${cat}" — auto-retry ${retryCount + 1}/${MAX_SKIP_RETRIES}`;
+        } else {
+          console.error(`FAILED: Task ${t.id} skipped ${MAX_SKIP_RETRIES} times in critical category "${cat}" — marking failed`);
+          t.status = 'failed';
+          t.error = `Skipped ${MAX_SKIP_RETRIES} times in critical category "${cat}" — max retries exhausted`;
+        }
+      }
+    } else {
+      // NON-CRITICAL CATEGORY: Block only when ALL tasks in category are skipped (existing behavior)
+      if (allSkipped) {
+        console.error(`BLOCKING: ALL tasks in category "${cat}" were skipped — investigate root cause`);
+        allInCat.forEach(t => {
+          t.status = 'pending';
+          t._retryCount = (t._retryCount || 0) + 1;
+          t.error = `All tasks in category "${cat}" skipped — auto-retry`;
+        });
+      }
+    }
+  }
+  writeJSON(currentPrdPath, prdCheck);
+}
+```
+
+### C3. Increment Iteration
 
 ```javascript
 prdCheck.config.current_iteration++;
@@ -314,7 +401,7 @@ prdCheck.updated_at = new Date().toISOString();
 writeJSON(currentPrdPath, prdCheck);
 ```
 
-### C3. Git Commit (PRD state only — apex already committed code)
+### C4. Git Commit (PRD state only — apex already committed code)
 
 ```bash
 git add {currentPrdPath} .ralph/progress.txt
@@ -331,7 +418,7 @@ EOF
 )"
 ```
 
-### C4. PRD Sync Verification (HARD CHECK)
+### C5. PRD Sync Verification (HARD CHECK)
 
 > **Note:** `prdCheck` (read in C1) is the authoritative post-apex snapshot.
 > `completed` (from B3) was computed on a DIFFERENT read — do NOT mix the two.

package/templates/skills/ralph-loop/references/module-transition.md

@@ -27,6 +27,27 @@ if (fileExists(queuePath)) {
 
   // All categories present — module is complete
   // Continue below...
+
+  // HANDOFF FILE GATE (double-security — step-04 §1.8 is primary, this is defense-in-depth)
+  // The build gate does NOT detect missing files if nothing references them (no compile error).
+  const ftc = prd.implementation?.filesToCreate;
+  if (ftc) {
+    let ftcMissing = 0;
+    const ftcDetails = [];
+    for (const [cat, files] of Object.entries(ftc)) {
+      for (const file of (files || [])) {
+        if (!fileExists(file.path || file)) {
+          ftcMissing++;
+          ftcDetails.push(`${cat}: ${(file.path || file).split('/').pop()}`);
+        }
+      }
+    }
+    if (ftcMissing > 0) {
+      console.error(`BLOCKING: ${ftcMissing} handoff files missing — cannot advance module`);
+      ftcDetails.forEach(d => console.error(`  ${d}`));
+      return; // Back to compact loop — remediation tasks already injected by category-completeness
+    }
+  }
 }
 ```
 
@@ -36,6 +57,36 @@ if (fileExists(queuePath)) {
 
 ```javascript
 if (missing.length === 0) {
+  // MANDATORY BUILD+TEST GATE before advancing module
+  // (audit ba-002: module marked "100% complete" despite build errors and security flaws)
+  const buildOk = execSync('dotnet build --no-restore --verbosity quiet').exitCode === 0;
+  if (!buildOk) {
+    console.error(`BLOCKING: Module ${currentModule.code} build fails — cannot advance to next module`);
+    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+    prd.tasks.push({
+      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix build for module ${currentModule.code}`,
+      status: 'pending', category: 'validation', dependencies: [],
+      acceptance_criteria: 'dotnet build passes with 0 errors'
+    });
+    writeJSON(currentPrdPath, prd);
+    return; // Back to compact loop — do NOT advance
+  }
+
+  const testOk = execSync('dotnet test --no-build --verbosity quiet').exitCode === 0;
+  if (!testOk) {
+    console.error(`BLOCKING: Module ${currentModule.code} tests fail — cannot advance to next module`);
+    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+    prd.tasks.push({
+      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix tests for module ${currentModule.code}`,
+      status: 'pending', category: 'validation', dependencies: [],
+      acceptance_criteria: 'dotnet test passes with 0 failures'
+    });
+    writeJSON(currentPrdPath, prd);
+    return; // Back to compact loop — do NOT advance
+  }
+
+  console.log(`MODULE GATE PASSED: ${currentModule.code} — build OK, tests OK`);
+
   // Mark current module done
   currentModule.status = 'completed';
   queue.completedModules++;
@@ -68,6 +119,15 @@ if (missing.length === 0) {
 
     console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
 
+    // CONTEXT REFRESH: Force /compact between modules to prevent context degradation
+    // (audit ba-002: quality degraded progressively — module 2 had more errors than module 1
+    // because patterns from module 1 were lost during context compaction)
+    console.log('Forcing /compact for fresh context before next module...');
+    // The /compact command clears accumulated tool results and intermediate reasoning,
+    // preserving only key decisions and the current state. This ensures the next module
+    // starts with a clean context window instead of degraded fragments from the previous module.
+    // INVOKE /compact
+
     // Return to step-01 to load next module's tasks
     // (step-01 will detect module-changed.json and load next PRD)
     return GO_TO_STEP_01;

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -33,24 +33,80 @@ const tasksTotal = prd.tasks.length;
 const allDone = (tasksCompleted + tasksSkipped) === tasksTotal;
 ```
 
-### 1.5. Lightweight Sanity Check
+### 1.5. Build & Test Gate (BLOCKING)
 
-> **Note:** Full build verification, POST-CHECKs, and test runs are handled by apex.
-> Ralph only does a lightweight sanity check to detect regressions between apex invocations.
+> **LESSON LEARNED (audit ba-002):** A non-blocking sanity build allowed "92/92 COMPLETE" with
+> code that had compilation errors and security flaws. The build gate MUST be BLOCKING.
 
 ```bash
-# Quick build check (quiet mode)
+# STEP 1: Build gate (BLOCKING — must pass before ANY further iteration)
 dotnet build --no-restore --verbosity quiet
 BUILD_RC=$?
 # Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
 if [ $BUILD_RC -ne 0 ]; then
-  echo "BUILD REGRESSION detected between apex invocations"
-  # Inject fix task — apex will handle the actual fix
-  prd.tasks.push({ id: maxId+1, description: "Fix build regression",
+  echo "BLOCKING: BUILD FAILED — cannot advance until fixed"
+  # Inject fix task with HIGH priority — apex will handle the actual fix
+  prd.tasks.push({ id: maxId+1, description: "BLOCKING: Fix build regression — dotnet build fails",
     status: "pending", category: "validation", dependencies: [],
-    acceptance_criteria: "dotnet build passes" });
+    acceptance_criteria: "dotnet build passes with 0 errors" });
   writeJSON(currentPrdPath, prd);
+  # DO NOT mark module complete — force compact loop to fix first
 fi
+
+# STEP 2: Test gate (BLOCKING — runs only if build passes)
+if [ $BUILD_RC -eq 0 ]; then
+  dotnet test --no-build --verbosity quiet
+  TEST_RC=$?
+  if [ $TEST_RC -ne 0 ]; then
+    echo "BLOCKING: TESTS FAILED — cannot advance until fixed"
+    prd.tasks.push({ id: maxId+2, description: "BLOCKING: Fix test regression — dotnet test fails",
+      status: "pending", category: "validation", dependencies: [],
+      acceptance_criteria: "dotnet test passes with 0 failures" });
+    writeJSON(currentPrdPath, prd);
+  fi
+fi
+```
+
+### 1.6. MCP Security Gate (post-module validation)
+
+> **LESSON LEARNED (audit ba-002):** Apex POST-CHECKs validate structure (TenantId present,
+> [RequirePermission] present) but miss SEMANTIC errors (Read permission on write endpoints,
+> self-approval, cross-tenant FK references). This gate catches those.
+
+```javascript
+// Run ONLY when all tasks for current module are complete (avoid wasting tokens mid-loop)
+const moduleTasksDone = prd.tasks.filter(t => t.status === 'completed').length === prd.tasks.length;
+
+if (moduleTasksDone && BUILD_RC === 0) {
+  // 1. Validate security (catches tenant isolation gaps, permission issues)
+  const securityResult = await mcp__smartstack__validate_security();
+
+  // 2. Review code quality (catches logic errors, exception inconsistencies)
+  const reviewResult = await mcp__smartstack__review_code();
+
+  // 3. SEMANTIC PERMISSION CHECK: write endpoints must not use Read permissions
+  // This check catches the ba-002 bug where Cancel (POST) used Permissions.*.Read
+  const permissionIssues = [];
+  for (const ctrlFile of glob('src/**/Controllers/**/*Controller.cs')) {
+    const content = readFile(ctrlFile);
+    // Find POST/PUT/DELETE endpoints with Read permission
+    const writeEndpoints = content.matchAll(/\[(HttpPost|HttpPut|HttpDelete|HttpPatch)[^\]]*\][^[]*\[RequirePermission\(([^\)]+)\)\]/gs);
+    for (const match of writeEndpoints) {
+      if (match[2].includes('.Read')) {
+        permissionIssues.push(`${ctrlFile}: ${match[1]} endpoint uses Read permission — should be Update/Delete/Create`);
+      }
+    }
+  }
+
+  if (permissionIssues.length > 0) {
+    console.error('BLOCKING: Write endpoints with Read permissions detected:');
+    permissionIssues.forEach(i => console.error(`  ${i}`));
+    prd.tasks.push({ id: maxId+3, description: "BLOCKING: Fix permission mismatch — write endpoints using Read permission",
+      status: "pending", category: "validation", dependencies: [],
+      acceptance_criteria: "All POST/PUT/DELETE endpoints use appropriate write permissions (Create/Update/Delete)" });
+    writeJSON(currentPrdPath, prd);
+  }
+}
 ```
 
 ### 1.7. Category Completeness Check (RUNS EVERY ITERATION)
@@ -71,6 +127,125 @@ if (guardrailsNeeded.length > 0) {
 // Artifact verification is handled inside checkCategoryCompleteness() — see reference file.
 ```
 
+### 1.8. Handoff File Gate (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** Category completeness checked "at least one file per category"
+> but 4/17 API endpoints were missing because individual files were never reconciled against the handoff contract.
+
+```javascript
+// BLOCKING: Reconcile prd.implementation.filesToCreate against disk
+const filesToCreate = prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  let handoffDeclared = 0, handoffPresent = 0;
+  const missingByCategory = {};
+
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      handoffDeclared++;
+      const filePath = file.path || file;
+      if (fileExists(filePath)) {
+        handoffPresent++;
+      } else {
+        if (!missingByCategory[category]) missingByCategory[category] = [];
+        missingByCategory[category].push(filePath);
+      }
+    }
+  }
+
+  const coveragePct = handoffDeclared > 0 ? Math.round((handoffPresent / handoffDeclared) * 100) : 100;
+  console.log(`Handoff file coverage: ${handoffPresent}/${handoffDeclared} (${coveragePct}%)`);
+
+  if (coveragePct < 100) {
+    console.error(`BLOCKING: Handoff coverage ${coveragePct}% — ${handoffDeclared - handoffPresent} files missing`);
+    for (const [cat, paths] of Object.entries(missingByCategory)) {
+      console.error(`  ${cat}: ${paths.length} missing`);
+    }
+    // category-completeness.md injects remediation tasks — do NOT advance module
+  }
+}
+```
+
+### 1.9. Business Rule Coverage Gate (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** 5/22 business rules were not implemented despite all tasks
+> being marked COMPLETE. Task-level tracking ("file created?") missed rule-level coverage
+> ("does the code actually implement BR-007?").
+
+```javascript
+// BLOCKING: Verify each BR from brToCodeMapping has an implementation
+const brMapping = prd.implementation?.brToCodeMapping;
+if (brMapping) {
+  const brMissing = [];
+  const brNotTested = [];
+
+  for (const br of brMapping) {
+    // Check if the component file exists
+    const componentFile = br.component || br.file;
+    const methodName = br.method || br.function;
+
+    if (!componentFile || !fileExists(componentFile)) {
+      brMissing.push({ id: br.id, rule: br.rule, component: componentFile, reason: 'file not found' });
+      continue;
+    }
+
+    // Check if the method exists in the file
+    if (methodName) {
+      const content = readFile(componentFile);
+      if (!content.includes(methodName)) {
+        brMissing.push({ id: br.id, rule: br.rule, component: componentFile, reason: `method ${methodName} not found` });
+        continue;
+      }
+    }
+
+    // Check test coverage (WARNING only — test category handles enforcement)
+    if (br.testFile && !fileExists(br.testFile)) {
+      brNotTested.push({ id: br.id, rule: br.rule, testFile: br.testFile });
+    }
+  }
+
+  if (brMissing.length > 0) {
+    console.error(`BLOCKING: ${brMissing.length}/${brMapping.length} business rules NOT implemented:`);
+    for (const br of brMissing) {
+      console.error(`  ${br.id}: ${br.rule} — ${br.reason}`);
+    }
+
+    // Inject remediation tasks for missing BRs
+    let maxIdNum = Math.max(...prd.tasks.map(t => {
+      const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
+      return isNaN(num) ? 0 : num;
+    }), 0);
+    const prefix = prd.tasks[0]?.id?.replace(/[0-9]+$/, '') || 'BR-';
+
+    for (const br of brMissing) {
+      const alreadyExists = prd.tasks.some(t =>
+        t.description.includes('[BR-REMEDIATION]') && t.description.includes(br.id)
+      );
+      if (alreadyExists) continue;
+
+      maxIdNum++;
+      prd.tasks.push({
+        id: `${prefix}${String(maxIdNum).padStart(3, '0')}`,
+        description: `[BR-REMEDIATION] Implement ${br.id}: ${br.rule}`,
+        status: 'pending',
+        category: 'application',
+        dependencies: [],
+        acceptance_criteria: `Business rule ${br.id} implemented in ${br.component} with method ${br.method || 'TBD'}`,
+        started_at: null, completed_at: null, iteration: null,
+        commit_hash: null, files_changed: [], validation: null, error: null
+      });
+    }
+    writeJSON(currentPrdPath, prd);
+  }
+
+  if (brNotTested.length > 0) {
+    console.warn(`WARNING: ${brNotTested.length}/${brMapping.length} business rules have no test file:`);
+    for (const br of brNotTested) {
+      console.warn(`  ${br.id}: ${br.rule} — expected test: ${br.testFile}`);
+    }
+  }
+}
+```
+
 ## 2. Check Iteration Limit
 
 If `current_iteration > max_iterations`:
@@ -123,10 +298,30 @@ if (fileExists(queuePath)) {
     console.log(`Module ${currentModule.code}: missing categories ${missing.join(', ')} — continuing loop`);
     // Fall through to section 5 (compact loop)
   } else {
-    // All categories complete — advance to next module
-    // (detailed logic in references/module-transition.md)
-    // MANDATORY: If this was the LAST module, ALWAYS proceed to step-05-report.md.
-    // NEVER stop without generating the final report.
+    // All categories complete — verify handoff files before advancing
+    const ftc = prd.implementation?.filesToCreate;
+    if (ftc) {
+      let ftcMissing = 0;
+      for (const [cat, files] of Object.entries(ftc)) {
+        for (const file of (files || [])) {
+          if (!fileExists(file.path || file)) ftcMissing++;
+        }
+      }
+      if (ftcMissing > 0) {
+        console.error(`BLOCKING: ${ftcMissing} handoff files still missing — cannot advance module`);
+        // Fall through to section 5 (compact loop) — remediation tasks injected by 1.8
+      } else {
+        // Handoff 100% + all categories complete — advance to next module
+        // (detailed logic in references/module-transition.md)
+        // MANDATORY: If this was the LAST module, ALWAYS proceed to step-05-report.md.
+        // NEVER stop without generating the final report.
+      }
+    } else {
+      // No handoff contract — advance to next module (manual mode)
+      // (detailed logic in references/module-transition.md)
+      // MANDATORY: If this was the LAST module, ALWAYS proceed to step-05-report.md.
+      // NEVER stop without generating the final report.
+    }
   }
 }
 ```