@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/{qgsd-solve.cjs → nf-solve.cjs}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 'use strict';
-// bin/qgsd-solve.cjs
+// bin/nf-solve.cjs
 // Consistency solver orchestrator: sweeps Requirements->Formal->Tests->Code->Docs,
 // computes a residual vector per layer transition, and auto-closes gaps.
 //
-// Layer transitions (8 forward + 3 reverse):
+// Layer transitions (8 forward + 3 reverse + 3 layer alignment):
 //   R->F: Requirements without formal model coverage
 //   F->T: Formal invariants without test backing
 //   C->F: Code constants diverging from formal specs
@@ -17,22 +17,27 @@
 //   C->R: Source modules in bin/hooks/ with no requirement tracing
 //   T->R: Test files with no @req annotation or formal-test-sync mapping
 //   D->R: Doc capability claims without requirement backing
+// Layer alignment (cross-layer gate checks):
+//   L1->L2: Gate A grounding alignment score
+//   L2->L3: Gate B traceability alignment score
+//   L3->TC: Gate C validation alignment score
 //
 // Usage:
-//   node bin/qgsd-solve.cjs                  # full sync, up to 3 iterations
-//   node bin/qgsd-solve.cjs --report-only    # single sweep, no mutations
-//   node bin/qgsd-solve.cjs --max-iterations=1
-//   node bin/qgsd-solve.cjs --json           # machine-readable output
-//   node bin/qgsd-solve.cjs --verbose        # pipe child stderr to parent stderr
-//   node bin/qgsd-solve.cjs --fast           # skip F->C and T->C layers for sub-second iteration
+//   node bin/nf-solve.cjs                  # full sync, up to 3 iterations
+//   node bin/nf-solve.cjs --report-only    # single sweep, no mutations
+//   node bin/nf-solve.cjs --max-iterations=1
+//   node bin/nf-solve.cjs --json           # machine-readable output
+//   node bin/nf-solve.cjs --verbose        # pipe child stderr to parent stderr
+//   node bin/nf-solve.cjs --fast           # skip F->C and T->C layers for sub-second iteration
 //
 // Requirements: QUICK-140
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { spawnSync } = require('child_process');
 
-const TAG = '[qgsd-solve]';
+const TAG = '[nf-solve]';
 let ROOT = process.cwd();
 const SCRIPT_DIR = __dirname;
 const DEFAULT_MAX_ITERATIONS = 3;
@@ -249,7 +254,7 @@ function discoverDocFiles() {
       const subWarnings = detectUninitializedSubmodules(marker.docs);
       for (const w of subWarnings) {
         console.error(
-          `[qgsd-solve] WARNING: docs.${w.docKey} overlaps submodule "${w.name}" ` +
+          `[nf-solve] WARNING: docs.${w.docKey} overlaps submodule "${w.name}" ` +
           `(${w.submodule}) which is not initialized. Run: git submodule update --init ${w.submodule}`
         );
       }
@@ -748,6 +753,15 @@ function sweepTtoC() {
   }
 
   // Runner mode: node-test (default)
+  // V8 coverage collection: create temp dir and set NODE_V8_COVERAGE env var
+  let covDir = null;
+  try {
+    covDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nf-solve-cov-'));
+    spawnOpts.env = Object.assign({}, process.env, { NODE_V8_COVERAGE: covDir });
+  } catch (e) {
+    covDir = null; // fail-open: continue without coverage
+  }
+
   let result;
   try {
     result = spawnSync(process.execPath, ['--test'], spawnOpts);
@@ -789,6 +803,26 @@ function sweepTtoC() {
     todoCount = 0;
   }
 
+  // Collect V8 coverage data from temp directory (fail-open)
+  let coverageData = null;
+  try {
+    if (covDir && fs.existsSync(covDir)) {
+      const covFiles = fs.readdirSync(covDir).filter(f => f.endsWith('.json'));
+      coverageData = [];
+      for (const cf of covFiles) {
+        const raw = fs.readFileSync(path.join(covDir, cf), 'utf8');
+        coverageData.push(JSON.parse(raw));
+      }
+      if (coverageData.length === 0) coverageData = null;
+    }
+  } catch (e) {
+    coverageData = null; // fail-open
+  } finally {
+    try {
+      if (covDir) fs.rmSync(covDir, { recursive: true, force: true });
+    } catch (e) { /* ignore cleanup errors */ }
+  }
+
   // Scope-based auto-detection: if scope is "generated-stubs-only", check if all failures
   // are outside .planning/formal/generated-stubs/
   if (tToCConfig.runner === 'node-test' && tToCConfig.scope === 'generated-stubs-only' && failCount > 0) {
@@ -805,6 +839,7 @@ function sweepTtoC() {
           todo: todoCount,
           runner_mismatch: true,
           warning: 'All ' + failLines.length + ' failures are outside generated-stubs scope — likely runner mismatch',
+          v8_coverage: coverageData,
         },
       };
     }
@@ -818,10 +853,93 @@ function sweepTtoC() {
       failed: failCount,
       skipped: skipCount,
       todo: todoCount,
+      v8_coverage: coverageData,
     },
   };
 }
 
+/**
+ * Cross-reference V8 coverage data against formal-test-sync recipe source_files.
+ * Identifies "false green" properties: tests pass but exercise none of the implementing source files.
+ * Returns { available: false } when coverage data is null/undefined.
+ */
+function crossReferenceFormalCoverage(v8CoverageData) {
+  if (!v8CoverageData) return { available: false };
+
+  try {
+    const syncData = loadFormalTestSync();
+    const recipes = (syncData && syncData.recipes) ? syncData.recipes : [];
+
+    // Build set of covered absolute file paths from V8 data
+    const coveredFiles = new Set();
+    for (const entry of v8CoverageData) {
+      const results = entry.result || [];
+      for (const r of results) {
+        if (!r.url) continue;
+        const filePath = r.url.startsWith('file://') ? r.url.slice(7) : r.url;
+        const resolved = path.resolve(filePath);
+        // A file is "covered" if ANY function range has count > 0
+        const hasCoverage = (r.functions || []).some(fn =>
+          (fn.ranges || []).some(range => range.count > 0)
+        );
+        if (hasCoverage) coveredFiles.add(resolved);
+      }
+    }
+
+    const coverageRatios = [];
+    const falseGreens = [];
+    let propertiesWithTests = 0;
+    let fullyCovered = 0;
+    let partiallyCovered = 0;
+    let uncovered = 0;
+
+    for (const recipe of recipes) {
+      const sourceFiles = recipe.source_files_absolute || [];
+      if (sourceFiles.length === 0) continue;
+      const hasTest = !!(recipe.test_file || recipe.test_files);
+      if (hasTest) propertiesWithTests++;
+
+      let coveredCount = 0;
+      for (const sf of sourceFiles) {
+        if (coveredFiles.has(path.resolve(sf))) coveredCount++;
+      }
+      const ratio = coveredCount / sourceFiles.length;
+      const propName = recipe.property || recipe.invariant || recipe.id || 'unknown';
+
+      coverageRatios.push({ property: propName, ratio: ratio });
+
+      if (ratio === 0 && hasTest) {
+        falseGreens.push({
+          property: propName,
+          test_file: recipe.test_file || (recipe.test_files || [])[0] || 'unknown',
+          source_files: sourceFiles,
+          covered: 0,
+        });
+        uncovered++;
+      } else if (ratio < 1) {
+        partiallyCovered++;
+      } else {
+        fullyCovered++;
+      }
+    }
+
+    return {
+      available: true,
+      total_properties: recipes.length,
+      properties_with_tests: propertiesWithTests,
+      false_greens: falseGreens,
+      coverage_ratios: coverageRatios,
+      summary: {
+        fully_covered: fullyCovered,
+        partially_covered: partiallyCovered,
+        uncovered: uncovered,
+      },
+    };
+  } catch (e) {
+    return { available: false };
+  }
+}
+
 /**
  * F->C: Formal verification to Code.
  * Returns { residual: N, detail: {...} }
@@ -1818,11 +1936,147 @@ function assembleReverseCandidates(c_to_r, t_to_r, d_to_r) {
   };
 }
 
+// ── Layer alignment sweeps ────────────────────────────────────────────────────
+
+/**
+ * L1->L2: Gate A grounding alignment score.
+ * Spawns gate-a-grounding.cjs --json and computes normalized 0-10 residual.
+ * Returns { residual: N, detail: {...} }
+ */
+function sweepL1toL2() {
+  if (fastMode) {
+    return { residual: -1, detail: { skipped: true, reason: 'fast mode' } };
+  }
+
+  const result = spawnTool('bin/gate-a-grounding.cjs', ['--json']);
+
+  // Gate scripts exit 1 when target_met is false but still produce valid JSON.
+  // Only bail on spawn errors (no stdout to parse).
+  if (!result.ok && !result.stdout) {
+    return { residual: -1, detail: { error: true, stderr: (result.stderr || '').slice(0, 500) } };
+  }
+
+  try {
+    const data = JSON.parse(result.stdout);
+    const score = data.grounding_score || 0;
+    const residual = Math.ceil((1 - score) * 10);
+    return {
+      residual: residual,
+      detail: {
+        grounding_score: score,
+        target: 0.8,
+        gap: 0.8 - score,
+        unexplained_breakdown: {
+          instrumentation_bug: (data.unexplained_counts && data.unexplained_counts.instrumentation_bug) || 0,
+          model_gap: (data.unexplained_counts && data.unexplained_counts.model_gap) || 0,
+          genuine_violation: (data.unexplained_counts && data.unexplained_counts.genuine_violation) || 0,
+        },
+      },
+    };
+  } catch (err) {
+    return { residual: -1, detail: { error: true, stderr: 'JSON parse failed: ' + err.message } };
+  }
+}
+
+/**
+ * L2->L3: Gate B traceability alignment score.
+ * Spawns gate-b-abstraction.cjs --json and computes normalized 0-10 residual.
+ * Returns { residual: N, detail: {...} }
+ */
+function sweepL2toL3() {
+  if (fastMode) {
+    return { residual: -1, detail: { skipped: true, reason: 'fast mode' } };
+  }
+
+  const result = spawnTool('bin/gate-b-abstraction.cjs', ['--json']);
+
+  // Gate scripts exit 1 when target_met is false but still produce valid JSON.
+  // Only bail on spawn errors (no stdout to parse).
+  if (!result.ok && !result.stdout) {
+    return { residual: -1, detail: { error: true } };
+  }
+
+  try {
+    const data = JSON.parse(result.stdout);
+    const score = data.gate_b_score || 0;
+    const orphanedCount = data.orphaned_entries || 0;
+    const rawResidual = Math.ceil((1 - score) * 10) + orphanedCount;
+    const residual = Math.min(rawResidual, 10);
+    return {
+      residual: residual,
+      detail: {
+        gate_b_score: score,
+        orphaned_count: orphanedCount,
+        residual_capped: rawResidual > 10,
+      },
+    };
+  } catch (err) {
+    return { residual: -1, detail: { error: true } };
+  }
+}
+
+/**
+ * L3->TC: Gate C validation alignment score.
+ * Spawns gate-c-validation.cjs --json and computes normalized 0-10 residual.
+ * Checks test-recipes.json staleness before scoring.
+ * Returns { residual: N, detail: {...} }
+ */
+function sweepL3toTC() {
+  if (fastMode) {
+    return { residual: -1, detail: { skipped: true, reason: 'fast mode' } };
+  }
+
+  // Check if test-recipes.json exists and staleness
+  const recipesPath = path.join(ROOT, '.planning', 'formal', 'test-recipes', 'test-recipes.json');
+  const catalogPath = path.join(ROOT, '.planning', 'formal', 'reasoning', 'failure-mode-catalog.json');
+
+  if (fs.existsSync(recipesPath) && fs.existsSync(catalogPath)) {
+    try {
+      const recipesMtime = fs.statSync(recipesPath).mtimeMs;
+      const catalogMtime = fs.statSync(catalogPath).mtimeMs;
+      if (recipesMtime < catalogMtime) {
+        if (reportOnly) {
+          process.stderr.write(TAG + ' WARNING: test-recipes.json is stale; run test-recipe-gen.cjs to update\n');
+        } else {
+          spawnTool('bin/test-recipe-gen.cjs', []);
+        }
+      }
+    } catch (e) {
+      // fail-open: skip staleness check
+    }
+  }
+
+  const result = spawnTool('bin/gate-c-validation.cjs', ['--json']);
+
+  // Gate scripts exit 1 when target_met is false but still produce valid JSON.
+  // Only bail on spawn errors (no stdout to parse).
+  if (!result.ok && !result.stdout) {
+    return { residual: -1, detail: { error: true, stderr: (result.stderr || '').slice(0, 500) } };
+  }
+
+  try {
+    const data = JSON.parse(result.stdout);
+    const score = data.gate_c_score || 0;
+    const residual = Math.ceil((1 - score) * 10);
+    return {
+      residual: residual,
+      detail: {
+        gate_c_score: score,
+        unvalidated_count: data.unvalidated_entries || 0,
+        total_failure_modes: data.total_entries || 0,
+        total_recipes: data.validated_entries || 0,
+      },
+    };
+  } catch (err) {
+    return { residual: -1, detail: { error: true, stderr: 'JSON parse failed: ' + err.message } };
+  }
+}
+
 // ── Residual computation ─────────────────────────────────────────────────────
 
 /**
- * Computes residual vector for all layer transitions (8 forward + 3 reverse).
- * Returns residual object with forward layers + reverse discovery layers.
+ * Computes residual vector for all layer transitions (8 forward + 3 reverse + 3 layer alignment).
+ * Returns residual object with forward layers + reverse discovery layers + layer alignment.
  */
 function computeResidual() {
   const r_to_f = sweepRtoF();
@@ -1831,6 +2085,12 @@ function computeResidual() {
   const t_to_c = fastMode
     ? { residual: -1, detail: { skipped: true, reason: 'fast mode' } }
     : sweepTtoC();
+
+  // Cross-reference V8 coverage against formal-test-sync recipe source_files
+  if (t_to_c.detail && t_to_c.detail.v8_coverage) {
+    t_to_c.detail.formal_coverage = crossReferenceFormalCoverage(t_to_c.detail.v8_coverage);
+  }
+
   const f_to_c = fastMode
     ? { residual: -1, detail: { skipped: true, reason: 'fast mode' } }
     : sweepFtoC();
@@ -1861,6 +2121,17 @@ function computeResidual() {
   // Assemble deduplicated reverse candidates
   const assembled_candidates = assembleReverseCandidates(c_to_r, t_to_r, d_to_r);
 
+  // Layer alignment sweeps (cross-layer gate checks) — skip in fast mode
+  const skipLayer = { residual: -1, detail: { skipped: true, reason: 'fast mode' } };
+  const l1_to_l2 = fastMode ? skipLayer : sweepL1toL2();
+  const l2_to_l3 = fastMode ? skipLayer : sweepL2toL3();
+  const l3_to_tc = fastMode ? skipLayer : sweepL3toTC();
+
+  const layer_total =
+    (l1_to_l2.residual >= 0 ? l1_to_l2.residual : 0) +
+    (l2_to_l3.residual >= 0 ? l2_to_l3.residual : 0) +
+    (l3_to_tc.residual >= 0 ? l3_to_tc.residual : 0);
+
   return {
     r_to_f,
     f_to_t,
@@ -1873,8 +2144,12 @@ function computeResidual() {
     c_to_r,
     t_to_r,
     d_to_r,
+    l1_to_l2,
+    l2_to_l3,
+    l3_to_tc,
     assembled_candidates,
     total,
+    layer_total,
     reverse_discovery_total,
     timestamp: new Date().toISOString(),
   };
@@ -1999,7 +2274,7 @@ function healthIndicator(residual) {
 function formatReport(iterations, finalResidual, converged) {
   const lines = [];
 
-  lines.push('[qgsd-solve] Consistency Solver Report');
+  lines.push('[nf-solve] Consistency Solver Report');
   lines.push('');
   lines.push(
     'Iterations: ' +
@@ -2097,6 +2372,30 @@ function formatReport(iterations, finalResidual, converged) {
       }
     }
   }
+
+  // Layer Alignment section
+  if (finalResidual.l1_to_l2 || finalResidual.l2_to_l3 || finalResidual.l3_to_tc) {
+    lines.push('');
+    lines.push('Layer Alignment (cross-layer gate checks):');
+    lines.push('─────────────────────────────────────────────');
+
+    const layerRows = [
+      { label: 'L1 -> L2 (Gate A)', residual: finalResidual.l1_to_l2 ? finalResidual.l1_to_l2.residual : -1 },
+      { label: 'L2 -> L3 (Gate B)', residual: finalResidual.l2_to_l3 ? finalResidual.l2_to_l3.residual : -1 },
+      { label: 'L3 -> TC (Gate C)', residual: finalResidual.l3_to_tc ? finalResidual.l3_to_tc.residual : -1 },
+    ];
+
+    for (const row of layerRows) {
+      const res = row.residual >= 0 ? row.residual : '?';
+      const health = healthIndicator(row.residual);
+      const line = row.label.padEnd(28) + String(res).padStart(4) + '    ' + health;
+      lines.push(line);
+    }
+
+    const layerTotal = finalResidual.layer_total || 0;
+    lines.push('─────────────────────────────────────────────');
+    lines.push('Layer total:             ' + layerTotal);
+  }
   lines.push('');
 
   // Per-layer detail sections (only non-zero)
@@ -2161,6 +2460,16 @@ function formatReport(iterations, finalResidual, converged) {
     lines.push('');
   }
 
+  // F->T->C coverage summary (shown regardless of T->C residual)
+  if (finalResidual.t_to_c.detail && finalResidual.t_to_c.detail.formal_coverage &&
+      finalResidual.t_to_c.detail.formal_coverage.available === true) {
+    const fc = finalResidual.t_to_c.detail.formal_coverage;
+    lines.push('  F->T->C coverage: ' + fc.summary.fully_covered + '/' +
+      fc.total_properties + ' properties fully traced (' +
+      fc.false_greens.length + ' false greens)');
+    lines.push('');
+  }
+
   if (finalResidual.f_to_c.residual > 0 || (finalResidual.f_to_c.detail && finalResidual.f_to_c.detail.inconclusive > 0)) {
     lines.push('## F -> C (Formal -> Code)');
     const detail = finalResidual.f_to_c.detail;
@@ -2324,7 +2633,7 @@ function truncateResidualDetail(residual) {
  */
 function formatJSON(iterations, finalResidual, converged) {
   const health = {};
-  for (const key of ['r_to_f', 'f_to_t', 'c_to_f', 't_to_c', 'f_to_c', 'r_to_d', 'd_to_c', 'p_to_f', 'c_to_r', 't_to_r', 'd_to_r']) {
+  for (const key of ['r_to_f', 'f_to_t', 'c_to_f', 't_to_c', 'f_to_c', 'r_to_d', 'd_to_c', 'p_to_f', 'c_to_r', 't_to_r', 'd_to_r', 'l1_to_l2', 'l2_to_l3', 'l3_to_tc']) {
     const res = finalResidual[key] ? finalResidual[key].residual : -1;
     health[key] = healthIndicator(res).split(/\s+/)[1]; // Extract GREEN/YELLOW/RED/UNKNOWN
   }
@@ -2466,8 +2775,12 @@ module.exports = {
   sweepCtoR,
   sweepTtoR,
   sweepDtoR,
+  sweepL1toL2,
+  sweepL2toL3,
+  sweepL3toTC,
   assembleReverseCandidates,
   classifyCandidate,
+  crossReferenceFormalCoverage,
 };
 
 // ── Entry point ──────────────────────────────────────────────────────────────

package/bin/observe-config.cjs

@@ -11,6 +11,10 @@ const path = require('node:path');
 const ISSUE_TYPES = ['github', 'sentry', 'sentry-feedback', 'bash'];
 // Source types that default to "drift"
 const DRIFT_TYPES = ['prometheus', 'grafana', 'logstash'];
+// Source types that default to "upstream"
+const UPSTREAM_TYPES = ['upstream'];
+// Source types that default to "deps"
+const DEPS_TYPES = ['deps'];
 
 /**
  * Parse a YAML value string into appropriate JS type
@@ -324,6 +328,10 @@ function loadObserveConfig(configPath, basePath) {
         source.issue_type = 'issue';
       } else if (DRIFT_TYPES.includes(source.type)) {
         source.issue_type = 'drift';
+      } else if (UPSTREAM_TYPES.includes(source.type)) {
+        source.issue_type = 'upstream';
+      } else if (DEPS_TYPES.includes(source.type)) {
+        source.issue_type = 'deps';
       }
     }
 

package/bin/observe-debt-writer.cjs

@@ -1,5 +1,5 @@
 /**
- * Debt ledger write-through for /qgsd:observe
+ * Debt ledger write-through for /nf:observe
  * Upserts observations to .planning/formal/debt.json by fingerprint using v0.27-01 functions
  * Then runs dedup engine and formal reference linker (v0.27-03)
  *