@nforma.ai/nforma 0.2.1

package/bin/sensitivity-report.cjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+'use strict';
+// bin/sensitivity-report.cjs
+// Reads .planning/formal/sensitivity-report.ndjson, ranks parameters by outcome-flip count,
+// and generates .planning/formal/sensitivity-report.md with annotated code paths, test cases,
+// and monitoring metrics.
+// Requirements: SENS-03
+
+const fs   = require('fs');
+const path = require('path');
+
+const TAG = '[sensitivity-report]';
+
+const REPORT_NDJSON_PATH = process.env.SENSITIVITY_REPORT_PATH ||
+  path.join(__dirname, '..', '.planning', 'formal', 'sensitivity-report.ndjson');
+
+const REPORT_MD_PATH = process.env.SENSITIVITY_MD_PATH ||
+  path.join(__dirname, '..', '.planning', 'formal', 'sensitivity-report.md');
+
+// ── Hardcoded annotations (code paths known from codebase analysis) ──────────
+// Maps parameter name → { codePath, testCases[], monitoring[] }
+
+const PARAM_ANNOTATIONS = {
+  MaxSize: {
+    codePath: 'hooks/qgsd-prompt.js FAN_OUT_COUNT; .planning/formal/tla/MCsafety.cfg MaxSize',
+    testCases: [
+      'Test quorum at N=2 boundary: set FAN_OUT_COUNT=2 in providers.json and run quorum round',
+      'Test quorum at N=1 (no quorum): verify workflow rejects insufficient available slots',
+    ],
+    monitoring: [
+      'Track FAN_OUT_COUNT per planning session in quorum-scoreboard.json',
+      'Alert if available slot count drops below MaxSize threshold for 2+ consecutive sessions',
+    ],
+  },
+  tp_rate: {
+    codePath: 'bin/export-prism-constants.cjs TP_PRIOR=0.85; .planning/formal/prism/quorum.pm tp_rate const',
+    testCases: [
+      'Test quorum with 2/4 slots returning APPROVE (tp_rate≈0.5) — verify inconclusive behavior',
+      'Test quorum with all slots UNAVAILABLE — verify graceful degradation exits 0',
+    ],
+    monitoring: [
+      'Track per-slot APPROVE rate in quorum-scoreboard.json rounds array',
+      'Alert if any slot tp_rate falls below 0.6 for 5+ consecutive quorum rounds',
+    ],
+  },
+  MaxDeliberation: {
+    codePath: '.planning/formal/tla/MCsafety.cfg MaxDeliberation=7; src/machines/qgsd-workflow.machine.ts MaxDeliberation guard',
+    testCases: [
+      'Test quorum workflow with max deliberation rounds reached — verify DECIDED fallback',
+      'Test rapid-fire slot responses (all within 1 deliberation round)',
+    ],
+    monitoring: [
+      'Track deliberation round count per quorum session in quorum-scoreboard.json',
+      'Alert if any session reaches MaxDeliberation-1 rounds (approaching timeout)',
+    ],
+  },
+  unavail: {
+    codePath: 'bin/export-prism-constants.cjs UNAVAIL_PRIOR=0.15; .planning/formal/prism/quorum.pm unavail const',
+    testCases: [
+      'Test quorum with 2/4 slots UNAVAILABLE — verify 2-of-2 quorum still reaches DECIDED',
+      'Test quorum with 3/4 slots UNAVAILABLE — verify graceful INCONCLUSIVE result',
+    ],
+    monitoring: [
+      'Track per-slot UNAVAIL rate in quorum-scoreboard.json',
+      'Alert if aggregate unavail rate exceeds 0.3 (less than MIN_QUORUM slots reliably available)',
+    ],
+  },
+};
+
+// ── NDJSON parser (fail-open) ─────────────────────────────────────────────────
+
+function parseNDJSON(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    return [];
+  }
+  const records = [];
+  for (const line of content.trim().split('\n')) {
+    if (!line.trim()) continue;
+    try { records.push(JSON.parse(line)); } catch (_) {}
+  }
+  return records;
+}
+
+// ── Report generation ─────────────────────────────────────────────────────────
+
+function generateReport(records) {
+  const now = new Date().toISOString();
+  const lines = [
+    '# Sensitivity Report — QGSD v0.20',
+    '',
+    'Generated: ' + now,
+    'Source: .planning/formal/sensitivity-report.ndjson (' + records.length + ' records)',
+    '',
+  ];
+
+  if (records.length === 0) {
+    lines.push('## No Data Available');
+    lines.push('');
+    lines.push('Run `node bin/run-sensitivity-sweep.cjs` to generate sweep data.');
+    return lines.join('\n');
+  }
+
+  // Group by parameter and count outcome flips
+  const paramData = {};
+  for (const r of records) {
+    const p = r.metadata && r.metadata.parameter;
+    if (!p) continue;
+    if (!paramData[p]) {
+      paramData[p] = {
+        description: r.property || ('Sweep of ' + p),
+        records: [],
+        flips: [],
+        stable: [],
+        inconclusive: [],
+      };
+    }
+    paramData[p].records.push(r);
+    const delta = r.metadata && r.metadata.delta;
+    if (delta && delta.startsWith('flip-to-')) {
+      paramData[p].flips.push({ value: r.metadata.value, result: r.result });
+    } else if (delta === 'stable') {
+      paramData[p].stable.push(r.metadata.value);
+    } else {
+      paramData[p].inconclusive.push(r.metadata.value);
+    }
+  }
+
+  // Rank parameters by flip count (descending)
+  const ranked = Object.entries(paramData)
+    .sort((a, b) => b[1].flips.length - a[1].flips.length);
+
+  const hasAnyFlips = ranked.some(([, d]) => d.flips.length > 0);
+
+  if (!hasAnyFlips) {
+    lines.push('## No Outcome Flips Detected');
+    lines.push('');
+    lines.push(
+      'All sweep results were inconclusive (tools not installed) or stable. ' +
+      'Install TLC and PRISM to run a live sensitivity sweep.'
+    );
+    lines.push('');
+    lines.push('### Parameter Summary');
+    lines.push('');
+    for (const [param, data] of ranked) {
+      lines.push('- **' + param + '**: ' + data.records.length + ' records — ' +
+        (data.inconclusive.length > 0
+          ? 'all inconclusive (tools not installed)'
+          : 'all stable'));
+    }
+    return lines.join('\n');
+  }
+
+  lines.push('## High-Sensitivity Parameters (ranked by outcome-flip count)');
+  lines.push('');
+
+  let rank = 1;
+  for (const [param, data] of ranked) {
+    const ann = PARAM_ANNOTATIONS[param] || {
+      codePath: '(unknown — add to PARAM_ANNOTATIONS in sensitivity-report.cjs)',
+      testCases: ['Review ' + param + ' at boundary values'],
+      monitoring: ['Track ' + param + ' over time'],
+    };
+
+    const flipSummary = data.flips.length > 0
+      ? data.flips.map(f => f.value + '→' + f.result).join(', ')
+      : 'none';
+
+    lines.push('### ' + rank + '. ' + param + ' — ' + data.flips.length + ' flip(s)');
+    lines.push('**Description:** ' + data.description);
+    lines.push('**Flip values:** ' + (data.flips.length > 0 ? flipSummary : 'none detected'));
+    if (data.inconclusive.length > 0) {
+      lines.push('**Inconclusive at:** ' + data.inconclusive.join(', ') + ' (tools not installed)');
+    }
+    lines.push('**Code path:** `' + ann.codePath + '`');
+    lines.push('');
+    lines.push('**Recommended test cases:**');
+    for (const tc of ann.testCases) {
+      lines.push('- ' + tc);
+    }
+    lines.push('');
+    lines.push('**Recommended monitoring:**');
+    for (const m of ann.monitoring) {
+      lines.push('- ' + m);
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    rank++;
+  }
+
+  return lines.join('\n');
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+function main() {
+  const records = parseNDJSON(REPORT_NDJSON_PATH);
+
+  if (records.length === 0) {
+    process.stderr.write(
+      TAG + ' No records found in: ' + REPORT_NDJSON_PATH + '\n' +
+      TAG + ' Run `node bin/run-sensitivity-sweep.cjs` first.\n'
+    );
+  } else {
+    process.stderr.write(TAG + ' Loaded ' + records.length + ' records from: ' + REPORT_NDJSON_PATH + '\n');
+  }
+
+  const markdown = generateReport(records);
+
+  fs.mkdirSync(path.dirname(REPORT_MD_PATH), { recursive: true });
+  fs.writeFileSync(REPORT_MD_PATH, markdown + '\n', 'utf8');
+
+  process.stderr.write(TAG + ' Report written to: ' + REPORT_MD_PATH + '\n');
+}
+
+main();

package/bin/sensitivity-sweep-feedback.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+// bin/sensitivity-sweep-feedback.cjs
+// LOOP-03 (v0.21-03): Read sensitivity sweep report, compare empirical TP rate,
+// re-run PRISM if deviation detected. Exits 0 unless a NEW threshold violation is found.
+// Usage: node bin/sensitivity-sweep-feedback.cjs
+
+const { spawnSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+
+// ── Named constant ─────────────────────────────────────────────────────────────
+const DEVIATION_THRESHOLD = 0.05;
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/**
+ * Read .planning/formal/sensitivity-report.ndjson from cwd.
+ * Returns array of parsed NDJSON records, or null if file absent/malformed.
+ */
+function readSweepRecords(cwd) {
+  const reportPath = path.join(cwd, '.planning', 'formal', 'sensitivity-report.ndjson');
+  if (!fs.existsSync(reportPath)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(reportPath, 'utf8');
+    return raw.trim().split('\n').filter(l => l.length > 0).map(l => JSON.parse(l));
+  } catch (e) {
+    process.stderr.write('[sensitivity-sweep-feedback] Warning: failed to parse sensitivity-report.ndjson: ' + e.message + '\n');
+    return null;
+  }
+}
+
+/**
+ * Compute empirical TP rate from quorum-scoreboard.md in cwd.
+ * Format: | Slot | Wins | Losses |
+ * Returns a number (0..1) or null if absent/empty.
+ */
+function readEmpiricalRate(cwd) {
+  const sbPath = path.join(cwd, 'quorum-scoreboard.md');
+  if (!fs.existsSync(sbPath)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(sbPath, 'utf8');
+    const rows = raw.split('\n');
+    let totalWins = 0;
+    let totalLosses = 0;
+    const rowRe = /\|\s*\S+\s*\|\s*(\d+)\s*\|\s*(\d+)\s*\|/g;
+    for (const row of rows) {
+      let m;
+      rowRe.lastIndex = 0;
+      while ((m = rowRe.exec(row)) !== null) {
+        totalWins   += parseInt(m[1], 10);
+        totalLosses += parseInt(m[2], 10);
+      }
+    }
+    const total = totalWins + totalLosses;
+    if (total === 0) return null;
+    return totalWins / total;
+  } catch (e) {
+    process.stderr.write('[sensitivity-sweep-feedback] Warning: failed to parse quorum-scoreboard.md: ' + e.message + '\n');
+    return null;
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+
+// 1. Read sensitivity report
+const allRecords = readSweepRecords(cwd);
+if (allRecords === null) {
+  process.stdout.write('[sensitivity-sweep-feedback] Warning: .planning/formal/sensitivity-report.ndjson not found — no feedback to process.\n');
+  process.exit(0);
+}
+
+// 2. Filter to PRISM tp_rate records
+const prismTpRecords = allRecords.filter(r =>
+  r.formalism === 'prism' &&
+  r.metadata &&
+  r.metadata.parameter === 'tp_rate'
+);
+
+// 3. If all inconclusive — no actionable data
+const actionableRecords = prismTpRecords.filter(r => r.result !== 'inconclusive');
+if (actionableRecords.length === 0) {
+  process.stdout.write('[sensitivity-sweep-feedback] Warning: all PRISM tp_rate sweep records are inconclusive — PRISM not available, skipping feedback.\n');
+  process.exit(0);
+}
+
+// 4. Compute empirical TP rate
+const empiricalRate = readEmpiricalRate(cwd);
+if (empiricalRate === null) {
+  process.stdout.write('[sensitivity-sweep-feedback] Warning: quorum-scoreboard.md not found or empty — cannot compute empirical rate.\n');
+  process.exit(0);
+}
+
+// 5. Find nearest tested value (from actionable records)
+const testedValues = actionableRecords.map(r => r.metadata.value);
+const nearestTestedValue = testedValues.reduce((nearest, v) =>
+  Math.abs(empiricalRate - v) < Math.abs(empiricalRate - nearest) ? v : nearest
+, testedValues[0]);
+
+const deviation = Math.abs(empiricalRate - nearestTestedValue);
+
+// 6. No deviation — exit 0
+if (deviation <= DEVIATION_THRESHOLD) {
+  process.stdout.write(
+    '[sensitivity-sweep-feedback] No deviation detected: empirical rate=' + empiricalRate.toFixed(4) +
+    ' nearest tested=' + nearestTestedValue + ' deviation=' + deviation.toFixed(4) +
+    ' (threshold=' + DEVIATION_THRESHOLD + ').\n'
+  );
+  process.exit(0);
+}
+
+// 7. Deviation detected — check for flip-to-fail records near the empirical rate
+process.stdout.write(
+  '[sensitivity-sweep-feedback] Deviation detected: empirical rate=' + empiricalRate.toFixed(4) +
+  ' nearest tested=' + nearestTestedValue + ' deviation=' + deviation.toFixed(4) +
+  ' (threshold=' + DEVIATION_THRESHOLD + ').\n'
+);
+
+// 7a. Check if any flip-to-fail record is near the empirical rate (within 2x threshold)
+// If so, this is a NEW threshold violation — exit 1 immediately (conservative, no PRISM run required)
+const flipToFailRecords = actionableRecords.filter(r =>
+  r.result === 'fail' &&
+  r.metadata.delta === 'flip-to-fail' &&
+  Math.abs(empiricalRate - r.metadata.value) <= DEVIATION_THRESHOLD * 2
+);
+
+if (flipToFailRecords.length > 0) {
+  process.stdout.write(
+    '[sensitivity-sweep-feedback] NEW THRESHOLD VIOLATION DETECTED: empirical rate=' + empiricalRate.toFixed(4) +
+    ' is near flip-to-fail boundary (value=' + flipToFailRecords[0].metadata.value + ').\n'
+  );
+
+  // 7b. Update rates.const and re-run PRISM to confirm (fail-open: proceed to exit 1 regardless)
+  const exportScript = path.join(__dirname, 'export-prism-constants.cjs');
+  const exportResult = spawnSync(process.execPath, [exportScript], {
+    encoding: 'utf8',
+    cwd: cwd,
+    timeout: 10000,
+  });
+  if (exportResult.status !== 0 || exportResult.error) {
+    process.stderr.write(
+      '[sensitivity-sweep-feedback] Warning: export-prism-constants pre-step failed — rates.const may be stale.\n' +
+      (exportResult.stderr || '') + '\n'
+    );
+  }
+
+  const runPrismScript = path.join(__dirname, 'run-prism.cjs');
+  const prismResult = spawnSync(process.execPath, [runPrismScript], {
+    encoding: 'utf8',
+    cwd: cwd,
+    timeout: 60000,
+  });
+  process.stdout.write(
+    '[sensitivity-sweep-feedback] PRISM re-run exit=' + prismResult.status + '. Exiting 1 (threshold violation).\n'
+  );
+  process.exit(1);
+}
+
+// 7c. Deviation but no flip-to-fail records nearby — update rates.const and re-run PRISM
+process.stdout.write('[sensitivity-sweep-feedback] No flip-to-fail boundary near empirical rate. Re-running PRISM with updated rates...\n');
+
+const exportScript = path.join(__dirname, 'export-prism-constants.cjs');
+const exportResult = spawnSync(process.execPath, [exportScript], {
+  encoding: 'utf8',
+  cwd: cwd,
+  timeout: 10000,
+});
+if (exportResult.status !== 0 || exportResult.error) {
+  process.stderr.write(
+    '[sensitivity-sweep-feedback] Warning: export-prism-constants pre-step failed — rates.const may be stale.\n' +
+    (exportResult.stderr || '') + '\n'
+  );
+}
+
+const runPrismScript = path.join(__dirname, 'run-prism.cjs');
+const prismResult = spawnSync(process.execPath, [runPrismScript], {
+  encoding: 'utf8',
+  cwd: cwd,
+  timeout: 60000,
+});
+
+if (prismResult.status !== 0) {
+  process.stdout.write('[sensitivity-sweep-feedback] PRISM re-run failed after rate update (non-flip-to-fail deviation).\n');
+  process.exit(0); // Not a new flip-to-fail violation
+}
+
+process.stdout.write('[sensitivity-sweep-feedback] PRISM re-run passed after rate update.\n');
+process.exit(0);

package/bin/set-secret.cjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * set-secret.cjs
+ * Usage: node bin/set-secret.cjs <KEY_NAME> <value>
+ *
+ * Stores KEY_NAME=value in the OS keychain under service "qgsd",
+ * then syncs all qgsd secrets into ~/.claude.json mcpServers env blocks.
+ */
+const { set, syncToClaudeJson, SERVICE } = require('./secrets.cjs');
+
+const [,, keyName, ...valueParts] = process.argv;
+if (!keyName || valueParts.length === 0) {
+  console.error('Usage: node bin/set-secret.cjs <KEY_NAME> <value>');
+  process.exit(1);
+}
+const value = valueParts.join(' ');
+
+(async () => {
+  try {
+    await set(SERVICE, keyName, value);
+    console.log(`[qgsd] Stored ${keyName} in keychain (service: ${SERVICE})`);
+    await syncToClaudeJson(SERVICE);
+    console.log('[qgsd] Synced keychain secrets to ~/.claude.json');
+  } catch (e) {
+    console.error('[qgsd] Error:', e.message);
+    process.exit(1);
+  }
+})();

package/bin/setup-telemetry-cron.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# setup-telemetry-cron.sh
+#
+# Installs an hourly cron entry that runs telemetry-collector.cjs + issue-classifier.cjs.
+# Safe to run multiple times — idempotent.
+#
+# Usage:
+#   bash bin/setup-telemetry-cron.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NODE_BIN="$(command -v node)"
+
+if [ -z "$NODE_BIN" ]; then
+  echo "ERROR: node not found in PATH. Install Node.js first."
+  exit 1
+fi
+
+CRON_CMD="$NODE_BIN $SCRIPT_DIR/telemetry-collector.cjs && $NODE_BIN $SCRIPT_DIR/issue-classifier.cjs"
+
+# Idempotency check
+if crontab -l 2>/dev/null | grep -q "telemetry-collector"; then
+  echo "Telemetry cron already installed."
+  exit 0
+fi
+
+# Install cron entry: top of every hour
+(crontab -l 2>/dev/null; echo "0 * * * * $CRON_CMD >> /tmp/qgsd-telemetry.log 2>&1") | crontab -
+
+echo "Telemetry cron installed."
+
+# Windows: use Task Scheduler. Create a Basic Task that runs:
+#   node C:\path\to\qgsd\bin\telemetry-collector.cjs
+# followed by: node C:\path\to\qgsd\bin\issue-classifier.cjs
+# Trigger: Daily, repeat every 1 hour indefinitely.

package/bin/sweepPtoF.cjs

@@ -0,0 +1,63 @@
+/**
+ * P->F residual sweep function
+ * Reads acknowledged debt entries, compares production measurements against
+ * formal model thresholds, and returns a residual count with detail.
+ *
+ * Requirements: PF-01, PF-02, PF-03
+ */
+
+'use strict';
+
+const path = require('node:path');
+const { readDebtLedger } = require('./debt-ledger.cjs');
+const { compareDrift } = require('./compareDrift.cjs');
+const { extractFormalExpected } = require('./extractFormalExpected.cjs');
+
+/**
+ * Sweep Production-to-Formal layer for divergent debt entries
+ * @param {object} [options]
+ * @param {string} [options.ledgerPath] - Override path to debt.json
+ * @param {string} [options.specDir] - Override path to spec directory
+ * @returns {{ residual: number, detail: object }}
+ */
+function sweepPtoF(options = {}) {
+  const ROOT = options.root || process.cwd();
+  const ledgerPath = options.ledgerPath || path.join(ROOT, '.planning/formal/debt.json');
+  const specDir = options.specDir || path.join(ROOT, '.planning/formal/spec');
+
+  // 1. Read ledger (fail-open: empty on error)
+  const ledger = readDebtLedger(ledgerPath);
+
+  // 2. Filter for acknowledged entries only (PF-03)
+  const acknowledged = (ledger.debt_entries || []).filter(e => e.status === 'acknowledged');
+
+  // 3. Separate linked vs unlinked
+  const withRef = acknowledged.filter(e => e.formal_ref != null);
+  const unlinked = acknowledged.filter(e => e.formal_ref == null);
+
+  // 4. Detect divergence for linked entries
+  const divergent = [];
+  for (const entry of withRef) {
+    const expected = extractFormalExpected(entry.formal_ref, { specDir });
+    if (compareDrift(entry, expected)) {
+      divergent.push({
+        id: entry.id,
+        formal_ref: entry.formal_ref,
+        measured: entry.meta?.measured_value,
+        expected,
+        issue_type: entry.issue_type,
+      });
+    }
+  }
+
+  return {
+    residual: divergent.length,
+    detail: {
+      divergent_entries: divergent,
+      skipped_unlinked: unlinked.length,
+      skipped_unlinked_ids: unlinked.map(e => e.id),
+    },
+  };
+}
+
+module.exports = { sweepPtoF };