@atlashub/smartstack-cli 4.26.0 → 4.28.0

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} |