@atlashub/smartstack-cli 4.27.0 → 4.28.0

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.
+    }
   }
 }
 ```

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -63,24 +63,136 @@ if (fileExists(queuePath)) {
 }
 ```
 
-### 1d. Artifact Verification (Post-Execution Validation)
+### 1d. Handoff Reconciliation (Post-Execution Validation)
+
+> **LESSON LEARNED (audit ba-002):** Simple "missing files" warnings were ignored.
+> Structured reconciliation tables make gaps impossible to miss.
 
 ```javascript
-// Verify key artifacts exist on disk
-const allFiles = prd.implementation?.filesToCreate || {};
-const missingFiles = [];
-for (const cat of Object.keys(allFiles)) {
-  for (const file of allFiles[cat] || []) {
-    if (!fileExists(file.path)) missingFiles.push(file.path);
+// === RECONCILIATION 1: Handoff File Coverage ===
+const filesToCreate = prd.implementation?.filesToCreate || {};
+const handoffReconciliation = { categories: [], totalDeclared: 0, totalPresent: 0, missingFiles: [] };
+
+for (const [cat, files] of Object.entries(filesToCreate)) {
+  let declared = 0, present = 0;
+  for (const file of (files || [])) {
+    declared++;
+    const filePath = file.path || file;
+    if (fileExists(filePath)) {
+      present++;
+    } else {
+      handoffReconciliation.missingFiles.push({ category: cat, path: filePath });
+    }
   }
+  handoffReconciliation.categories.push({
+    category: cat, declared, present, missing: declared - present,
+    coverage: declared > 0 ? Math.round((present / declared) * 100) : 100
+  });
+  handoffReconciliation.totalDeclared += declared;
+  handoffReconciliation.totalPresent += present;
 }
-if (missingFiles.length > 0) {
-  console.warn(`WARNING: ${missingFiles.length} files declared in PRD but not found on disk`);
-  for (const f of missingFiles.slice(0, 10)) {
-    console.warn(`  MISSING: ${f}`);
+
+const totalHandoffCoverage = handoffReconciliation.totalDeclared > 0
+  ? Math.round((handoffReconciliation.totalPresent / handoffReconciliation.totalDeclared) * 100)
+  : 100;
+
+// === RECONCILIATION 2: Business Rule Coverage ===
+const brMapping = prd.implementation?.brToCodeMapping || [];
+const brReconciliation = { total: brMapping.length, implemented: 0, missing: [], notTested: [] };
+
+for (const br of brMapping) {
+  const componentFile = br.component || br.file;
+  const methodName = br.method || br.function;
+
+  if (!componentFile || !fileExists(componentFile)) {
+    brReconciliation.missing.push({ id: br.id, rule: br.rule, reason: 'file not found' });
+    continue;
+  }
+  if (methodName) {
+    const content = readFile(componentFile);
+    if (!content.includes(methodName)) {
+      brReconciliation.missing.push({ id: br.id, rule: br.rule, reason: `method ${methodName} not found` });
+      continue;
+    }
+  }
+  brReconciliation.implemented++;
+
+  if (br.testFile && !fileExists(br.testFile)) {
+    brReconciliation.notTested.push({ id: br.id, rule: br.rule });
+  }
+}
+
+// === RECONCILIATION 3: API Endpoint Coverage ===
+const apiEndpoints = prd.implementation?.apiEndpointSummary || [];
+const apiReconciliation = { total: apiEndpoints.length, found: 0, missing: [] };
+
+const ctrlFilesForReconciliation = glob('src/**/Controllers/**/*Controller.cs');
+for (const ep of apiEndpoints) {
+  const opName = ep.operation || ep.name;
+  let found = false;
+  for (const f of ctrlFilesForReconciliation) {
+    const content = readFile(f);
+    if (content.includes(opName)) { found = true; break; }
   }
-  if (missingFiles.length > 10) {
-    console.warn(`  ... and ${missingFiles.length - 10} more`);
+  if (found) {
+    apiReconciliation.found++;
+  } else {
+    apiReconciliation.missing.push({ operation: opName, method: ep.method, path: ep.path });
+  }
+}
+
+// Log summary
+console.log(`Handoff files: ${handoffReconciliation.totalPresent}/${handoffReconciliation.totalDeclared} (${totalHandoffCoverage}%)`);
+console.log(`Business rules: ${brReconciliation.implemented}/${brReconciliation.total} implemented`);
+console.log(`API endpoints: ${apiReconciliation.found}/${apiReconciliation.total} found`);
+```
+
+### 1e. Final Build & Test Verification (TRUTH CHECK)
+
+> **LESSON LEARNED (audit ba-002):** "92/92 COMPLETE" + "Build PASS" was reported but the code
+> had compilation errors and critical security flaws. The report MUST reflect actual build/test
+> state, not just PRD task statuses.
+
+```bash
+# REAL build verification — overrides any previous "Build PASS" claim
+dotnet build --no-restore --verbosity quiet
+FINAL_BUILD_RC=$?
+
+FINAL_TEST_RC=-1
+if [ $FINAL_BUILD_RC -eq 0 ]; then
+  dotnet test --no-build --verbosity quiet
+  FINAL_TEST_RC=$?
+fi
+```
+
+```javascript
+// Override PRD-based build/test status with REAL results
+const buildStatus = FINAL_BUILD_RC === 0 ? 'PASS' : 'FAIL';
+const testStatus = FINAL_TEST_RC === 0 ? 'PASS' : (FINAL_TEST_RC === -1 ? 'SKIPPED (build failed)' : 'FAIL');
+
+// CRITICAL: If build fails despite all tasks "completed", flag this prominently
+if (FINAL_BUILD_RC !== 0 && stats.tasks.completed === stats.tasks.total) {
+  console.error('INTEGRITY WARNING: All tasks marked COMPLETE but build FAILS');
+  console.error('This indicates phantom task completion — review code quality');
+  stats.buildIntegrityWarning = true;
+}
+```
+
+### 1f. MCP Security Scan (Final Gate)
+
+```javascript
+// Quick MCP security validation on the final codebase
+const securityScan = await mcp__smartstack__validate_security();
+const conventionScan = await mcp__smartstack__validate_conventions();
+
+// Check for write endpoints with Read permissions (semantic permission check)
+const permissionWarnings = [];
+const ctrlFiles = glob('src/**/Controllers/**/*Controller.cs');
+for (const f of ctrlFiles) {
+  const content = readFile(f);
+  const writeWithRead = content.matchAll(/\[(HttpPost|HttpPut|HttpDelete|HttpPatch)[^\]]*\][^[]*\[RequirePermission\([^\)]*\.Read\)\]/gs);
+  for (const m of writeWithRead) {
+    permissionWarnings.push(`${f}: ${m[1]} uses Read permission`);
   }
 }
 ```
@@ -138,7 +250,86 @@ Write to `.ralph/reports/{feature-slug}.md`:
 
 {end if}
 
-## Test Metrics
+{if handoffReconciliation.totalDeclared > 0:}
+## Handoff Reconciliation
+
+### File Coverage by Category
+| Category | Declared | Present | Missing | Coverage |
+|----------|----------|---------|---------|----------|
+{for each cat in handoffReconciliation.categories:}
+| {category} | {declared} | {present} | {missing} | {coverage}% |
+{end for}
+
+**Total: {totalPresent}/{totalDeclared} ({totalHandoffCoverage}%)**
+
+{if handoffReconciliation.missingFiles.length > 0:}
+### Missing Files
+{for each mf in handoffReconciliation.missingFiles:}
+- **{mf.category}**: `{mf.path}`
+{end for}
+{end if}
+{end if}
+
+{if brReconciliation.total > 0:}
+### Business Rule Coverage
+| Metric | Value |
+|--------|-------|
+| Total Rules | {brReconciliation.total} |
+| Implemented | {brReconciliation.implemented} |
+| Missing | {brReconciliation.missing.length} |
+| Not Tested | {brReconciliation.notTested.length} |
+
+{if brReconciliation.missing.length > 0:}
+**Missing BR implementations:**
+{for each br in brReconciliation.missing:}
+- `{br.id}`: {br.rule} — {br.reason}
+{end for}
+{end if}
+{end if}
+
+{if apiReconciliation.total > 0:}
+### API Endpoint Coverage
+| Metric | Value |
+|--------|-------|
+| Total Endpoints | {apiReconciliation.total} |
+| Found | {apiReconciliation.found} |
+| Missing | {apiReconciliation.missing.length} |
+
+{if apiReconciliation.missing.length > 0:}
+**Missing API endpoints:**
+{for each ep in apiReconciliation.missing:}
+- `{ep.method} {ep.path}` — operation: `{ep.operation}`
+{end for}
+{end if}
+{end if}
+
+## Build & Test Verification (Actual)
+
+> These results come from REAL `dotnet build` and `dotnet test` execution,
+> not from PRD task statuses.
+
+| Check | Result |
+|-------|--------|
+| `dotnet build` | {buildStatus} |
+| `dotnet test` | {testStatus} |
+| MCP validate_security | {securityScan.status} |
+| MCP validate_conventions | {conventionScan.status} |
+| Permission semantic check | {permissionWarnings.length === 0 ? 'PASS' : `${permissionWarnings.length} issues`} |
+
+{if stats.buildIntegrityWarning:}
+> **INTEGRITY WARNING:** All tasks marked COMPLETE but the build FAILS.
+> This means some generated code references types or methods that don't exist.
+> Review the build output and fix before considering this feature done.
+{end if}
+
+{if permissionWarnings.length > 0:}
+> **PERMISSION WARNINGS:** Write endpoints using Read permissions detected:
+{for each warning:}
+> - {warning}
+{end for}
+{end if}
+
+## Test Metrics (PRD-based)
 | Metric | Value |
 |--------|-------|
 | Test Tasks | {testTasks.length} |