qualia-framework 6.14.0 → 7.0.0

package/bin/verify-panel.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// verify-panel.js — deterministic aggregator for the verifier panel + skeptics.
+//
+// WHY: a single LLM judge is adversarially fragile — a lone stray token can
+// swing it (~35% false positives in the lit). R8 replaces single-pass verify
+// with (a) a PANEL of verifiers each scoring one lens (correctness / security /
+// performance / design) and (b) per-finding adversarial SKEPTICS that vote on
+// whether each finding is real. This module is the part that must NOT be a vibe:
+// it dedupes the panel's findings, applies majority-survives over the skeptic
+// votes, and computes the verdict + scores with the rules/grounding.md formula.
+// Same inputs → same verdict.
+//
+// Input (panel JSON the skill assembles from agent outputs):
+//   {
+//     "phase": 2,
+//     "lenses": ["correctness","security","performance","design"],
+//     "findings": [
+//       { "lens":"security", "file":"lib/auth.ts", "line":42,
+//         "severity":"CRITICAL", "title":"service_role reachable client-side",
+//         "votes": { "real": 2, "notReal": 1 } }
+//     ]
+//   }
+//
+// Exit 0 = PASS, 1 = FAIL, 2 = invocation error.
+// Zero npm dependencies. Library + CLI.
+
+const fs = require("fs");
+const path = require("path");
+
+const SEVERITY_WEIGHT = { CRITICAL: 8, HIGH: 4, MEDIUM: 2, LOW: 1 };
+const SEVERITY_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+
+function normSeverity(s) {
+  const up = String(s || "").toUpperCase();
+  return SEVERITY_WEIGHT[up] != null ? up : "LOW";
+}
+
+function slug(title) {
+  return String(title || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().slice(0, 48);
+}
+
+function findingKey(f) {
+  const file = String(f.file || "").replace(/\\/g, "/");
+  const line = f.line != null ? f.line : "";
+  return `${file}:${line}:${slug(f.title)}`;
+}
+
+// Merge findings that point at the same file:line:title (e.g. the correctness
+// AND security lens both flagged it). Keep the highest severity, union the
+// lenses, and sum the skeptic votes so the merged finding is judged once.
+function dedupeFindings(findings) {
+  const byKey = new Map();
+  for (const raw of findings || []) {
+    const f = {
+      file: raw.file || null,
+      line: raw.line != null ? raw.line : null,
+      title: raw.title || "",
+      severity: normSeverity(raw.severity),
+      lenses: raw.lens ? [raw.lens] : (Array.isArray(raw.lenses) ? raw.lenses.slice() : []),
+      votes: {
+        real: Number((raw.votes && raw.votes.real) || 0),
+        notReal: Number((raw.votes && raw.votes.notReal) || 0),
+      },
+    };
+    const key = findingKey(f);
+    const prev = byKey.get(key);
+    if (!prev) { byKey.set(key, f); continue; }
+    if (SEVERITY_RANK[f.severity] > SEVERITY_RANK[prev.severity]) prev.severity = f.severity;
+    for (const l of f.lenses) if (!prev.lenses.includes(l)) prev.lenses.push(l);
+    prev.votes.real += f.votes.real;
+    prev.votes.notReal += f.votes.notReal;
+  }
+  return [...byKey.values()];
+}
+
+// Majority-survives: a finding is KILLED only when the skeptics who voted are a
+// strict majority calling it not-real. With no votes recorded it survives
+// (unverified ≠ disproven — verification stays conservative).
+function survives(finding) {
+  const r = finding.votes.real;
+  const n = finding.votes.notReal;
+  if (r + n === 0) return true;
+  return !(n > r);
+}
+
+function scoreFromCounts(counts) {
+  const ws =
+    counts.CRITICAL * SEVERITY_WEIGHT.CRITICAL +
+    counts.HIGH * SEVERITY_WEIGHT.HIGH +
+    counts.MEDIUM * SEVERITY_WEIGHT.MEDIUM +
+    counts.LOW * SEVERITY_WEIGHT.LOW;
+  return Math.max(1, 5 - Math.floor(ws / 8));
+}
+
+function emptyCounts() {
+  return { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+}
+
+function aggregate(panel) {
+  const deduped = dedupeFindings(panel.findings || []);
+  const surviving = [];
+  const killed = [];
+  for (const f of deduped) {
+    (survives(f) ? surviving : killed).push({ ...f, verified: f.votes.real + f.votes.notReal > 0 });
+  }
+
+  const counts = emptyCounts();
+  const perLens = {};
+  for (const lens of panel.lenses || []) perLens[lens] = emptyCounts();
+  for (const f of surviving) {
+    counts[f.severity]++;
+    for (const lens of f.lenses) {
+      if (!perLens[lens]) perLens[lens] = emptyCounts();
+      perLens[lens][f.severity]++;
+    }
+  }
+
+  // A surviving CRITICAL or HIGH fails the phase (rules/grounding.md severity).
+  const verdict = counts.CRITICAL === 0 && counts.HIGH === 0 ? "PASS" : "FAIL";
+  const perLensScores = {};
+  for (const [lens, c] of Object.entries(perLens)) perLensScores[lens] = scoreFromCounts(c);
+
+  return {
+    ok: verdict === "PASS",
+    verdict,
+    phase: panel.phase != null ? panel.phase : null,
+    counts,
+    score: scoreFromCounts(counts),
+    per_lens_scores: perLensScores,
+    surviving,
+    killed,
+    totals: { findings: deduped.length, surviving: surviving.length, killed: killed.length },
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--write") args.write = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  verify-panel.js <panel.json> [--json] [--write] [--cwd DIR]",
+    "",
+    "Aggregates panel findings + skeptic votes → deterministic verdict.",
+    "Exit 0 = PASS, 1 = FAIL, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function toMarkdown(r) {
+  const lines = [];
+  lines.push(`# Verifier Panel — phase ${r.phase}`);
+  lines.push("");
+  lines.push(`result: ${r.verdict}`);
+  lines.push(`score: ${r.score}/5`);
+  lines.push(`findings: ${r.totals.surviving} surviving / ${r.totals.killed} killed by skeptics`);
+  lines.push("");
+  lines.push(`Severity (surviving): CRITICAL ${r.counts.CRITICAL} · HIGH ${r.counts.HIGH} · MEDIUM ${r.counts.MEDIUM} · LOW ${r.counts.LOW}`);
+  lines.push("");
+  if (r.surviving.length) {
+    lines.push("## Surviving findings");
+    for (const f of r.surviving) {
+      const where = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "(no location)";
+      lines.push(`- **[${f.severity}]** ${f.title} — ${where} _(lens: ${f.lenses.join(", ") || "?"}; votes ${f.votes.real}✓/${f.votes.notReal}✗)_`);
+    }
+    lines.push("");
+  }
+  if (r.killed.length) {
+    lines.push("## Killed by skeptics (majority not-real)");
+    for (const f of r.killed) {
+      const where = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "(no location)";
+      lines.push(`- ~~[${f.severity}] ${f.title}~~ — ${where} _(votes ${f.votes.real}✓/${f.votes.notReal}✗)_`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+// Assemble per-lens finding files (.planning/phase-{N}-panel-{lens}.json, each
+// an array of {file,line,severity,title}) into one panel.json — findings tagged
+// with their lens, votes zeroed for the skeptic pass to fill. Deterministic so
+// the orchestrator never hand-builds the panel skeleton.
+function assemble(root, phase) {
+  const dir = path.join(root, ".planning");
+  const re = new RegExp(`^phase-${phase}-panel-([a-z]+)\\.json$`);
+  const lenses = [];
+  const findings = [];
+  let files = [];
+  try { files = fs.readdirSync(dir); } catch { files = []; }
+  for (const f of files.sort()) {
+    const m = f.match(re);
+    if (!m) continue;
+    const lens = m[1];
+    let arr;
+    try { arr = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); } catch { continue; }
+    if (!Array.isArray(arr)) continue;
+    lenses.push(lens);
+    for (const item of arr) {
+      findings.push({
+        lens,
+        file: item.file || null,
+        line: item.line != null ? item.line : null,
+        severity: item.severity || "LOW",
+        title: item.title || "",
+        votes: { real: 0, notReal: 0 },
+      });
+    }
+  }
+  return { phase: Number(phase), lenses, findings };
+}
+
+function main(argv) {
+  // assemble subcommand: verify-panel.js assemble <phase> [--cwd DIR]
+  if (argv[2] === "assemble") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    if (phase == null) { usage(); return 2; }
+    const root = path.resolve(sub.cwd || process.cwd());
+    const panel = assemble(root, phase);
+    const out = path.join(root, ".planning", `phase-${phase}-panel.json`);
+    try {
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, JSON.stringify(panel, null, 2) + "\n");
+    } catch (e) {
+      console.error(`ERROR: could not write ${out}: ${e.message}`);
+      return 2;
+    }
+    console.log(`assembled ${panel.findings.length} finding(s) from ${panel.lenses.length} lens file(s) → ${path.relative(root, out)}`);
+    return 0;
+  }
+
+  const args = parseArgs(argv);
+  const panelPath = args._[0];
+  if (!panelPath || panelPath === "-h" || panelPath === "--help") { usage(); return 2; }
+  const root = path.resolve(args.cwd || process.cwd());
+
+  let panel;
+  try {
+    panel = JSON.parse(fs.readFileSync(path.resolve(root, panelPath), "utf8"));
+  } catch (e) {
+    console.error(`ERROR: cannot read panel JSON: ${e.message}`);
+    return 2;
+  }
+
+  const result = aggregate(panel);
+
+  if (args.write && result.phase != null) {
+    const dir = path.join(root, ".planning");
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, `phase-${result.phase}-verification-panel.json`), JSON.stringify(result, null, 2) + "\n");
+      fs.writeFileSync(path.join(dir, `phase-${result.phase}-verification-panel.md`), toMarkdown(result));
+    } catch (e) {
+      console.error(`WARN: could not write panel artifacts: ${e.message}`);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`PANEL ${result.verdict} phase ${result.phase}: ` +
+      `${result.totals.surviving} surviving (${result.counts.CRITICAL}C/${result.counts.HIGH}H/${result.counts.MEDIUM}M/${result.counts.LOW}L), ` +
+      `${result.totals.killed} killed by skeptics, score ${result.score}/5`);
+    if (!result.ok) for (const f of result.surviving) {
+      if (f.severity === "CRITICAL" || f.severity === "HIGH") {
+        console.log(`  [${f.severity}] ${f.title} — ${f.file || "?"}${f.line != null ? `:${f.line}` : ""}`);
+      }
+    }
+  }
+  return result.ok ? 0 : 1;
+}
+
+module.exports = {
+  dedupeFindings,
+  survives,
+  scoreFromCounts,
+  aggregate,
+  assemble,
+  SEVERITY_WEIGHT,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/wave-plan.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// wave-plan.js — derive a deterministic build schedule from the task DAG.
+//
+// WHY: /qualia-build spawned EVERY task in a contract "wave" concurrently, with
+// no cap. That's two failure modes at once:
+//   1. Over-serialization — the planner's hand-numbered waves can be deeper than
+//      the dependency graph requires (tasks that COULD run together placed in
+//      separate waves), so the build is slower than necessary.
+//   2. Over-parallelization — a wide wave (say 9 independent tasks) spawns 9
+//      concurrent builders, past the 3–5 sweet spot where coordination +
+//      context cost overwhelms the gain (the LangGraph max_concurrency lesson).
+//
+// This recomputes waves from `depends_on` (minimal-depth topological levels —
+// maximal safe parallelism) and splits each level into batches capped at
+// max_concurrency. Output is an ordered list of batches the orchestrator spawns
+// one at a time. Deterministic: same contract + same cap → same schedule.
+//
+// max_concurrency:
+//   --parallel N  → exactly N (N ≥ 1)
+//   auto (default)→ 1 if < 3 total tasks ("don't parallelize tiny phases"),
+//                   else SWEET (5).
+//
+// Zero npm dependencies. Library + CLI. Exit 0 ok, 1 cycle, 2 invocation error.
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("./plan-contract.js");
+
+const SWEET = 5;
+
+function numericId(id) {
+  const m = String(id).match(/\d+/);
+  return m ? Number(m[0]) : 0;
+}
+
+// Minimal-depth level for each task: level = 1 + max(level(deps)); roots = 1.
+// Returns { levels: Map<id,level>, cycle: [...] | null }.
+function deriveLevels(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const levels = new Map();
+  const visiting = new Set();
+
+  function depth(id, trail) {
+    if (levels.has(id)) return levels.get(id);
+    if (visiting.has(id)) {
+      const err = new Error("cycle");
+      err.cycle = [...trail, id];
+      throw err;
+    }
+    const t = byId.get(id);
+    const deps = (t && t.depends_on) || [];
+    visiting.add(id);
+    let max = 0;
+    for (const d of deps) {
+      if (!byId.has(d)) continue; // unknown dep — plan-contract validates this separately
+      max = Math.max(max, depth(d, [...trail, id]));
+    }
+    visiting.delete(id);
+    const lvl = max + 1;
+    levels.set(id, lvl);
+    return lvl;
+  }
+
+  try {
+    for (const t of tasks) depth(t.id, []);
+  } catch (e) {
+    if (e.cycle) return { levels: null, cycle: e.cycle };
+    throw e;
+  }
+  return { levels, cycle: null };
+}
+
+function resolveConcurrency(taskCount, parallel) {
+  if (parallel != null) {
+    const n = Number(parallel);
+    if (!Number.isFinite(n) || n < 1) throw new Error(`--parallel must be an integer ≥ 1 (got ${parallel})`);
+    return Math.floor(n);
+  }
+  return taskCount < 3 ? 1 : SWEET;
+}
+
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+function plan(contract, opts = {}) {
+  const tasks = (contract.tasks || []).slice();
+  const { levels, cycle } = deriveLevels(tasks);
+  if (cycle) return { ok: false, error: "CYCLE", cycle: cycle.join(" → ") };
+
+  const maxConcurrency = resolveConcurrency(tasks.length, opts.parallel);
+
+  // Group task ids by derived level, ordered numerically within a level.
+  const byLevel = new Map();
+  for (const t of tasks) {
+    const lvl = levels.get(t.id);
+    if (!byLevel.has(lvl)) byLevel.set(lvl, []);
+    byLevel.get(lvl).push(t.id);
+  }
+  const sortedLevels = [...byLevel.keys()].sort((a, b) => a - b);
+
+  // Emit batches: each derived level split into ≤ maxConcurrency chunks.
+  const batches = [];
+  for (const lvl of sortedLevels) {
+    const ids = byLevel.get(lvl).sort((a, b) => numericId(a) - numericId(b));
+    for (const group of chunk(ids, maxConcurrency)) {
+      batches.push({ wave: lvl, batch: batches.length + 1, tasks: group });
+    }
+  }
+
+  // Note where the planner's declared wave is deeper than necessary (the DAG
+  // permits more parallelism than the contract used).
+  const notes = [];
+  const declared = new Map(tasks.map((t) => [t.id, t.wave]));
+  let overSerialized = 0;
+  for (const t of tasks) {
+    const d = declared.get(t.id);
+    const derived = levels.get(t.id);
+    if (typeof d === "number" && d > derived) overSerialized++;
+  }
+  if (overSerialized > 0) {
+    notes.push(`${overSerialized} task(s) declared a deeper wave than the dependency graph requires — the schedule below runs them earlier (more parallel).`);
+  }
+  const widest = Math.max(0, ...sortedLevels.map((l) => byLevel.get(l).length));
+  if (widest > maxConcurrency) {
+    notes.push(`widest level has ${widest} independent tasks; capped to batches of ${maxConcurrency}.`);
+  }
+
+  return {
+    ok: true,
+    phase: contract.phase != null ? contract.phase : null,
+    task_count: tasks.length,
+    max_concurrency: maxConcurrency,
+    derived_levels: sortedLevels.length,
+    batch_count: batches.length,
+    batches,
+    notes,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--parallel") args.parallel = argv[++i];
+    else if (a.startsWith("--parallel=")) args.parallel = a.slice(11);
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  wave-plan.js <contract.json> [--parallel N] [--json] [--cwd DIR]",
+    "",
+    "Derives a dependency-ordered, concurrency-capped build schedule.",
+    "Exit 0 = ok, 1 = cycle in DAG, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const contractPath = args._[0];
+  if (!contractPath || contractPath === "-h" || contractPath === "--help") { usage(); return 2; }
+  const root = path.resolve(args.cwd || process.cwd());
+
+  const loaded = pc.readContractFile(path.resolve(root, contractPath));
+  if (!loaded.ok) {
+    if (args.json) console.log(JSON.stringify({ ok: false, ...loaded }));
+    else console.error(`${loaded.error}: ${loaded.message}`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = plan(loaded.contract, { parallel: args.parallel });
+  } catch (e) {
+    if (args.json) console.log(JSON.stringify({ ok: false, error: "BAD_ARG", message: e.message }));
+    else console.error(`ERROR: ${e.message}`);
+    return 2;
+  }
+
+  if (!result.ok) {
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    else console.error(`${result.error}: ${result.cycle || ""}`);
+    return result.error === "CYCLE" ? 1 : 2;
+  }
+
+  if (args.json) { console.log(JSON.stringify(result, null, 2)); return 0; }
+
+  console.log(`Build schedule — phase ${result.phase}: ${result.task_count} task(s), ` +
+    `${result.batch_count} batch(es), max ${result.max_concurrency} concurrent`);
+  for (const b of result.batches) {
+    console.log(`  wave ${b.wave} · batch ${b.batch}: ${b.tasks.join(", ")}`);
+  }
+  for (const n of result.notes) console.log(`  note: ${n}`);
+  return 0;
+}
+
+module.exports = { deriveLevels, resolveConcurrency, plan, SWEET };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}