qualia-framework 6.9.2 → 6.22.0

package/bin/eval-runner.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// eval-runner.js — layered assertion engine for AI features (chat / RAG / voice).
+//
+// WHY: Qualia gates UI and code (contract-runner, slop-detect, verify-panel) but
+// has no equivalent for the AI artifacts it BUILDS. "The chatbot answers refund
+// questions" is not checkable by a grep. This runs a suite of cases against
+// captured AI outputs with LAYERED assertions: cheap deterministic checks first
+// (contains / regex / json_path / length / latency / cost), then llm_rubric for
+// the judgments only a model can make — same shape as contract-runner evidence.
+//
+// Deterministic-first by design: every assertion this module can settle WITHOUT
+// a model, it settles here. `llm_rubric` assertions carry a `verdict`
+// (pass|fail) that the /qualia-eval skill fills by spawning a judge BEFORE
+// calling this runner — exactly how verify-panel consumes skeptic votes. An
+// llm_rubric with no verdict is PENDING and fails the suite (never silently
+// passes an unjudged rubric).
+//
+// Suite (JSON — zero-dependency; no YAML parser pulled in):
+//   {
+//     "feature": "support-chat",
+//     "cases": [
+//       { "name": "refund window",
+//         "input": "what's your refund policy?",
+//         "output": "We refund within 30 days...",   // or "output_file": "path"
+//         "latency_ms": 1200, "cost_usd": 0.008,
+//         "assert": [
+//           { "type": "contains", "value": "30 days" },
+//           { "type": "not_contains", "value": "I cannot help" },
+//           { "type": "max_latency_ms", "value": 2000 },
+//           { "type": "llm_rubric", "rubric": "grounded in policy, no hallucination", "verdict": "pass" }
+//         ] } ] }
+//
+// Exit 0 = all cases pass, 1 = a failure or an unjudged rubric, 2 = bad input.
+// Zero npm dependencies. Library + CLI.
+
+const fs = require("fs");
+const path = require("path");
+
+function getPath(obj, dotted) {
+  const parts = String(dotted).split(".").filter(Boolean);
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null) return undefined;
+    const idx = /^\d+$/.test(p) ? Number(p) : p;
+    cur = cur[idx];
+  }
+  return cur;
+}
+
+function safeRegex(src) {
+  try { return new RegExp(src); } catch { return null; }
+}
+
+// Run one assertion against a case's captured output + metrics.
+// Returns { ok, detail }.
+function runAssertion(a, ctx) {
+  const out = ctx.output != null ? String(ctx.output) : "";
+  switch (a.type) {
+    case "contains":
+      return { ok: out.includes(String(a.value)), detail: `contains "${a.value}"` };
+    case "not_contains":
+      return { ok: !out.includes(String(a.value)), detail: `not_contains "${a.value}"` };
+    case "equals":
+      return { ok: out === String(a.value), detail: `equals "${a.value}"` };
+    case "regex": {
+      const re = safeRegex(a.value);
+      if (!re) return { ok: false, detail: `invalid regex: ${a.value}` };
+      return { ok: re.test(out), detail: `regex /${a.value}/` };
+    }
+    case "not_regex": {
+      const re = safeRegex(a.value);
+      if (!re) return { ok: false, detail: `invalid regex: ${a.value}` };
+      return { ok: !re.test(out), detail: `not_regex /${a.value}/` };
+    }
+    case "min_length":
+      return { ok: out.length >= Number(a.value), detail: `min_length ${a.value} (got ${out.length})` };
+    case "max_length":
+      return { ok: out.length <= Number(a.value), detail: `max_length ${a.value} (got ${out.length})` };
+    case "json_valid":
+      try { JSON.parse(out); return { ok: true, detail: "json_valid" }; }
+      catch { return { ok: false, detail: "output is not valid JSON" }; }
+    case "json_path": {
+      let parsed;
+      try { parsed = JSON.parse(out); } catch { return { ok: false, detail: "json_path: output not JSON" }; }
+      const val = getPath(parsed, a.path);
+      if (val === undefined) return { ok: false, detail: `json_path ${a.path}: missing` };
+      if (a.equals !== undefined) return { ok: String(val) === String(a.equals), detail: `json_path ${a.path} equals "${a.equals}" (got "${val}")` };
+      if (a.contains !== undefined) return { ok: String(val).includes(String(a.contains)), detail: `json_path ${a.path} contains "${a.contains}"` };
+      return { ok: true, detail: `json_path ${a.path} present` };
+    }
+    case "max_latency_ms":
+      if (ctx.latency_ms == null) return { ok: false, detail: "max_latency_ms: no latency_ms recorded on case" };
+      return { ok: Number(ctx.latency_ms) <= Number(a.value), detail: `max_latency_ms ${a.value} (got ${ctx.latency_ms})` };
+    case "max_cost_usd":
+      if (ctx.cost_usd == null) return { ok: false, detail: "max_cost_usd: no cost_usd recorded on case" };
+      return { ok: Number(ctx.cost_usd) <= Number(a.value), detail: `max_cost_usd ${a.value} (got ${ctx.cost_usd})` };
+    case "llm_rubric": {
+      const v = a.verdict != null ? String(a.verdict).toLowerCase() : null;
+      if (v === null) return { ok: false, pending: true, detail: `llm_rubric PENDING (no judge verdict): "${a.rubric}"` };
+      return { ok: v === "pass", detail: `llm_rubric "${a.rubric}" → ${v}` };
+    }
+    default:
+      return { ok: false, detail: `unknown assertion type: ${a.type}` };
+  }
+}
+
+function resolveOutput(root, c) {
+  if (c.output != null) return c.output;
+  if (c.output_file) {
+    try { return fs.readFileSync(path.resolve(root, c.output_file), "utf8"); }
+    catch (e) { return { __error: `output_file unreadable: ${e.message}` }; }
+  }
+  return "";
+}
+
+function run(suite, opts = {}) {
+  const root = path.resolve(opts.cwd || process.cwd());
+  const cases = [];
+  let pending = 0;
+  for (const c of suite.cases || []) {
+    const output = resolveOutput(root, c);
+    const ctx = { output: (output && output.__error) ? "" : output, latency_ms: c.latency_ms, cost_usd: c.cost_usd };
+    const assertions = [];
+    if (output && output.__error) {
+      assertions.push({ type: "output", ok: false, detail: output.__error });
+    }
+    for (const a of c.assert || []) {
+      const r = runAssertion(a, ctx);
+      if (r.pending) pending++;
+      assertions.push({ type: a.type, ok: !!r.ok, pending: !!r.pending, detail: r.detail });
+    }
+    const ok = assertions.length > 0 && assertions.every((x) => x.ok);
+    cases.push({ name: c.name || "(unnamed)", ok, assertions });
+  }
+  const passed = cases.filter((c) => c.ok).length;
+  return {
+    ok: cases.length > 0 && passed === cases.length,
+    feature: suite.feature || "(unnamed feature)",
+    total_cases: cases.length,
+    passed_cases: passed,
+    failed_cases: cases.length - passed,
+    pending,
+    cases,
+  };
+}
+
+// ── 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:",
+    "  eval-runner.js <suite.json> [--json] [--write] [--cwd DIR]",
+    "",
+    "Layered assertion runner for AI-feature eval suites.",
+    "Exit 0 = all cases pass, 1 = failure/unjudged rubric, 2 = invocation error.",
+  ].join("\n"));
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const suitePath = args._[0];
+  if (!suitePath || suitePath === "-h" || suitePath === "--help") { usage(); return 2; }
+  const root = path.resolve(args.cwd || process.cwd());
+
+  let suite;
+  try {
+    suite = JSON.parse(fs.readFileSync(path.resolve(root, suitePath), "utf8"));
+  } catch (e) {
+    console.error(`ERROR: cannot read eval suite: ${e.message}`);
+    return 2;
+  }
+
+  const result = run(suite, { cwd: root });
+
+  if (args.write) {
+    const dir = path.join(root, ".planning", "evals");
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const slug = String(result.feature).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      fs.writeFileSync(path.join(dir, `eval-${slug || "feature"}.json`), JSON.stringify(result, null, 2) + "\n");
+    } catch (e) {
+      console.error(`WARN: could not write eval artifact: ${e.message}`);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+
+  console.log(`EVAL ${result.ok ? "PASS" : "FAIL"} [${result.feature}]: ` +
+    `${result.passed_cases}/${result.total_cases} cases` +
+    (result.pending ? ` (${result.pending} rubric(s) unjudged)` : ""));
+  for (const c of result.cases) {
+    if (c.ok) continue;
+    console.log(`  ✗ ${c.name}`);
+    for (const a of c.assertions) if (!a.ok) console.log(`      - ${a.detail}`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+module.exports = { run, runAssertion, getPath };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/host-adapters.js

@@ -1,17 +1,43 @@
 #!/usr/bin/env node
-// Host adapter rendering for installed Qualia text surfaces.
+// host-adapters.js — the single internal contract for everything that differs
+// between the runtimes Qualia targets (Claude Code, OpenAI Codex).
+//
+// The rule (ACP shape): NOTHING else branches on runtime. Skills, install, and
+// hooks ask the adapter for a fact ("what's the instruction filename?", "how do
+// I render this text for this host?") instead of hardcoding an `if (codex)`.
+// When a third runtime arrives, it's one entry in HOSTS — not a grep-and-patch
+// across the tree.
 
 const path = require("path");
 const os = require("os");
 
+// Per-host facts. Each host declares — declaratively, in ONE place:
+//   home            install root
+//   name            display name (used in the naming map + UX copy)
+//   instructionFile the top-level agent-instructions file this runtime reads
+//   configFile      the runtime's settings file
+//   agentDir        where subagent definitions live (relative to home)
+//   agentExt        the subagent file extension the runtime consumes
+//   naming          source→host display-string swaps applied to rendered text
 const HOSTS = {
   claude: {
     name: "Claude Code",
     home: path.join(os.homedir(), ".claude"),
+    instructionFile: "CLAUDE.md",
+    configFile: "settings.json",
+    agentDir: "agents",
+    agentExt: ".md",
+    naming: {}, // Claude is the canonical voice — no swaps.
   },
   codex: {
     name: "OpenAI Codex",
     home: path.join(os.homedir(), ".codex"),
+    instructionFile: "AGENTS.md",
+    configFile: "config.toml",
+    agentDir: "agents",
+    agentExt: ".toml",
+    // Canonical source speaks "Claude Code"; Codex artifacts speak "Codex".
+    naming: { "Claude Code": "Codex", "Claude's": "Codex's" },
   },
 };
 
@@ -21,6 +47,9 @@ function adapter(name) {
   const home = host.home;
   return {
     ...host,
+    instructionPath: path.join(home, host.instructionFile),
+    configPath: path.join(home, host.configFile),
+    agentPath: path.join(home, host.agentDir),
     tokens: {
       QUALIA_HOME: home,
       QUALIA_BIN: `${home}/bin`,
@@ -35,32 +64,63 @@ function adapter(name) {
   };
 }
 
-function renderText(content, hostName) {
+// Host-display naming swaps only (e.g. "Claude Code" → "Codex"). Split out from
+// path rendering so the canonical→artifact compile can swap names WITHOUT baking
+// in install-time paths (install resolves those per host afterwards).
+function applyNaming(content, hostName) {
+  const host = adapter(hostName);
+  let out = String(content);
+  for (const [from, to] of Object.entries(host.naming)) {
+    out = out.replaceAll(from, to);
+  }
+  return out;
+}
+
+// Path/token rendering: ${QUALIA_*} tokens + legacy `.claude/` literals → this
+// host's install paths. Idempotent (running twice is a no-op), so install can
+// safely re-render an already-compiled artifact.
+function applyPaths(content, hostName) {
   const host = adapter(hostName);
   let out = String(content);
   for (const [token, value] of Object.entries(host.tokens)) {
     out = out.replaceAll(`\${${token}}`, value);
   }
-
-  // Backward-compatible rendering while source files migrate from hardcoded
-  // Claude paths to explicit ${QUALIA_*} tokens.
-  out = out
+  return out
     .replaceAll("~/.claude/", `${host.home}/`)
     .replaceAll("$HOME/.claude/", `${host.home}/`)
     .replaceAll("${HOME}/.claude/", `${host.home}/`)
     .replaceAll("@~/.claude/", `@${host.home}/`)
     .replaceAll(".claude/", `${path.basename(host.home)}/`);
+}
 
-  if (hostName === "codex") {
-    out = out
-      .replaceAll("Claude Code", "Codex")
-      .replaceAll("Claude's", "Codex's");
-  }
-  return out;
+// Full install-time render: paths + naming. Unchanged public behavior.
+function renderText(content, hostName) {
+  return applyNaming(applyPaths(content, hostName), hostName);
+}
+
+// Host-conditional blocks in a canonical source:
+//   <!--QUALIA-HOST claude-->  …kept only for claude…  <!--/QUALIA-HOST-->
+// Keep the matching host's block (unwrapped), drop every other host's block.
+function stripHostBlocks(content, hostName) {
+  const re = /[ \t]*<!--QUALIA-HOST\s+(\w+)-->\n?([\s\S]*?)\n?[ \t]*<!--\/QUALIA-HOST-->\n?/g;
+  return String(content).replace(re, (_m, host, body) =>
+    host === hostName ? `${body}\n` : ""
+  );
+}
+
+// Compile a canonical instruction source into one host's artifact: resolve
+// conditional blocks + apply naming, but DO NOT resolve paths or {{ROLE}} —
+// those stay as tokens for install.js to render per concrete install.
+function compileInstructions(canonical, hostName) {
+  return applyNaming(stripHostBlocks(canonical, hostName), hostName);
 }
 
 module.exports = {
   HOSTS,
   adapter,
+  applyNaming,
+  applyPaths,
   renderText,
+  stripHostBlocks,
+  compileInstructions,
 };

package/bin/install.js

@@ -6,7 +6,7 @@ const fs = require("fs");
 const ui = require("./qualia-ui.js");
 const { RUNTIME_BIN_SCRIPTS, binFiles } = require("./runtime-manifest.js");
 const { ACTIVE_SKILLS, RETIRED_SKILLS } = require("./command-surface.js");
-const { renderText } = require("./host-adapters.js");
+const { renderText, adapter } = require("./host-adapters.js");
 
 // ─── Colors (kept for legacy log lines; new sections route through qualia-ui) ─
 const TEAL = "\x1b[38;2;0;206;209m";
@@ -555,8 +555,9 @@ function askCode() {
 // ─── Employee mode (no team code) ────────────────────────
 // A new employee may not have a QS-NAME-## code yet. Typing "EMPLOYEE" at the
 // install-code prompt installs the full framework at the least-privilege role:
-// feature branches only, no main pushes (enforced by branch-guard, which trusts
-// the role bit in the 0o600 config). ERP reporting stays OFF until a real team
+// feature branches by default; main pushes are allowed but recorded by
+// branch-guard (counted locally + reported to the ERP, which trusts the role bit
+// in the 0o600 config). ERP reporting stays OFF until a real team
 // code is set, so /qualia-report degrades to a local-only report.
 //
 // Defaulting to EMPLOYEE (not OWNER) on a missing/keyword code is the secure
@@ -955,13 +956,16 @@ async function main() {
   // ─── CLAUDE.md with role ───────────────────────────────
   printSection("Configuration");
   try {
+    // Source + dest filenames come from the host adapter (single per-host
+    // contract). CLAUDE.md is a generated artifact of templates/instructions.md.
+    const claudeFile = adapter("claude").instructionFile;
     let claudeMd = fs.readFileSync(
-      path.join(FRAMEWORK_DIR, "CLAUDE.md"),
+      path.join(FRAMEWORK_DIR, claudeFile),
       "utf8"
     );
     claudeMd = claudeMd.replace("{{ROLE}}", member.role);
     claudeMd = claudeMd.replace("{{ROLE_DESCRIPTION}}", member.description);
-    const claudeDest = path.join(CLAUDE_DIR, "CLAUDE.md");
+    const claudeDest = path.join(CLAUDE_DIR, claudeFile);
     // v5.0: backup existing CLAUDE.md before overwrite. Users may have added
     // personal instructions; without a backup, re-install silently destroys
     // them. .bak files are harmless and easy to clean up.
@@ -1276,7 +1280,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
     "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
     "git-guardrails.js", "stop-session-log.js",
-    "fawzi-approval-guard.js",
+    "fawzi-approval-guard.js", "task-write-guard.js",
     // v5.0 — insights-driven destructive-op + wrong-account guards
     "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
     // performance-audit telemetry capture (UserPromptSubmit)
@@ -1305,7 +1309,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
           { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "⬢ Checking git safety..." },
           { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
-          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Recording branch activity..." },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
           { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 600, statusMessage: "⬢ Running quality gates..." },
           // v5.0 hooks — insights-driven friction prevention
@@ -1318,6 +1322,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         matcher: "Edit|Write",
         hooks: [
           { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
+          { type: "command", command: nodeCmd("task-write-guard.js"), timeout: 5, statusMessage: "⬢ Checking plan-contract file scope..." },
           { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
@@ -1588,24 +1593,29 @@ async function installCodex(member, target, employeeMode = false) {
     }
   }
 
-  // Render AGENTS.md with role substitution. Source is the same AGENTS.md
-  // already shipped in the framework root (it's the cross-vendor mirror of
-  // CLAUDE.md, kept under 25 lines per Pocock's instruction-budget rule).
+  // AGENTS.md is the Codex artifact of templates/instructions.md (compiled by
+  // bin/compile-instructions.js). Source filename + render come from the host
+  // adapter, mirroring the CLAUDE.md path exactly. codexText() resolves
+  // ${QUALIA_*} tokens + .claude→.codex paths — CLAUDE.md got this rendering;
+  // AGENTS.md previously did not (latent drift the single-contract path fixes).
+  const codexFile = adapter("codex").instructionFile;
   let agentsContent;
   try {
-    agentsContent = fs.readFileSync(path.join(FRAMEWORK_DIR, "AGENTS.md"), "utf8");
-    agentsContent = agentsContent
-      .replace("{{ROLE}}", member.role)
-      .replace("{{ROLE_DESCRIPTION}}", member.description);
+    agentsContent = fs.readFileSync(path.join(FRAMEWORK_DIR, codexFile), "utf8");
+    agentsContent = codexText(
+      agentsContent
+        .replace("{{ROLE}}", member.role)
+        .replace("{{ROLE_DESCRIPTION}}", member.description)
+    );
   } catch (e) {
-    warn(`Codex — could not read framework AGENTS.md: ${e.message}`);
+    warn(`Codex — could not read framework ${codexFile}: ${e.message}`);
     return;
   }
 
-  const dest = path.join(CODEX_DIR, "AGENTS.md");
+  const dest = path.join(CODEX_DIR, codexFile);
 
   try {
-    backupIfDifferent(dest, agentsContent, "AGENTS.md");
+    backupIfDifferent(dest, agentsContent, codexFile);
     atomicWrite(dest, agentsContent);
     sectionCount++;
     ok(`AGENTS.md (configured as ${member.role})`);

package/bin/last-report.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// last-report.js — surface "where work was left off last time" at session start.
+//
+// WHY: the /qualia router classifies state from state.js, .continue-here.md, and
+// git log — but it ignores .planning/reports/, which is the richest "where we
+// left off" signal a team has. A teammate (or future-you) picking the project
+// back up should instantly see the last session's outcome and next step without
+// opening a file. This extracts a compact digest from the newest report so the
+// router can print it at the TOP of its output when a project is loaded.
+//
+// Reports are written by /qualia-report at .planning/reports/report-{YYYY-MM-DD}.md
+// (the date filename may carry a suffix, e.g. report-2026-05-31-session3.md). The
+// markdown has a "# Session Report — {date}" title, a "**Date:**" line, a
+// "## What Was Done" section (the summary), and a "## Next Steps" section.
+//
+// Read-only. Zero npm dependencies.
+// Exit 0 = a report was found, 1 = none found, 2 = bad input.
+
+const fs = require("fs");
+const path = require("path");
+
+// Pull a YYYY-MM-DD from a report filename. Returns null when absent so a
+// misnamed file falls back to mtime ordering rather than poisoning the sort.
+function dateFromName(name) {
+  const m = name.match(/(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : null;
+}
+
+// Whole-day difference between two ISO-ish dates (report date vs --now). Floors
+// to a non-negative integer; a future report date (clock skew) reads as 0.
+function ageDays(dateStr, nowIso) {
+  if (!dateStr) return null;
+  const then = Date.parse(dateStr + "T00:00:00Z");
+  const now = nowIso ? Date.parse(nowIso) : Date.now();
+  if (Number.isNaN(then) || Number.isNaN(now)) return null;
+  return Math.max(0, Math.floor((now - then) / 86400000));
+}
+
+// Collapse markdown bullets/bold/whitespace into one tight prose line.
+function flatten(s) {
+  return s
+    .replace(/^\s+/, "")         // leading indentation, so list-marker anchors match
+    .replace(/\*\*/g, "")
+    .replace(/^[-*]\s+/, "")     // unordered bullet
+    .replace(/^\d+[.)]\s+/, "")  // ordered list marker (1. / 1))
+    .replace(/`/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// Lines that carry no signal for a digest (metadata, blank, headings).
+function isNoise(line) {
+  const t = line.trim();
+  if (!t) return true;
+  if (t.startsWith("#")) return true;
+  if (/^\*\*[A-Za-z ]+:\*\*/.test(t)) return true; // **Project:** / **Date:** etc.
+  return false;
+}
+
+// Find the body under a "## {heading}" until the next "## " heading or EOF.
+function sectionBody(lines, headingRe) {
+  let i = lines.findIndex((l) => headingRe.test(l.trim()));
+  if (i === -1) return [];
+  const out = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (/^##\s/.test(lines[j].trim())) break;
+    out.push(lines[j]);
+  }
+  return out;
+}
+
+// First meaningful sentence/clause of a section, capped to keep the digest tight.
+function firstMeaningful(bodyLines, cap = 160) {
+  for (const raw of bodyLines) {
+    if (isNoise(raw)) continue;
+    const flat = flatten(raw);
+    if (!flat) continue;
+    return flat.length > cap ? flat.slice(0, cap - 1).trimEnd() + "…" : flat;
+  }
+  return "";
+}
+
+// Extract the digest from a single report's markdown text.
+function digest(text) {
+  const lines = text.split(/\r?\n/);
+
+  // Date: prefer the explicit **Date:** line, else the title's trailing date.
+  let date = null;
+  const dateLine = lines.find((l) => /^\*\*Date:\*\*/.test(l.trim()));
+  if (dateLine) date = (dateFromName(dateLine) || null);
+  if (!date) {
+    const title = lines.find((l) => /^#\s+Session Report/.test(l.trim()));
+    if (title) date = dateFromName(title);
+  }
+
+  // Summary: first meaningful line of "## What Was Done", else first meaningful
+  // line of the whole body (so malformed reports still yield something).
+  let summary = firstMeaningful(sectionBody(lines, /^##\s+What Was Done/i));
+  if (!summary) summary = firstMeaningful(lines);
+
+  // Next: first meaningful line of "## Next Steps" / "## Next Step".
+  let next = firstMeaningful(sectionBody(lines, /^##\s+Next Steps?/i));
+
+  return { date, summary, next };
+}
+
+// Library: find the newest report under root and return its digest object.
+//   { found, file, date, summary, next, age_days }
+function latestReport(root, opts = {}) {
+  const dir = path.join(path.resolve(root || process.cwd()), ".planning", "reports");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return { found: false, file: null, date: null, summary: "", next: "", age_days: null };
+  }
+
+  const reports = entries
+    .filter((f) => /^report-.*\.md$/.test(f))
+    .map((f) => {
+      const full = path.join(dir, f);
+      let mtime = 0;
+      try { mtime = fs.statSync(full).mtimeMs; } catch {}
+      return { file: f, full, date: dateFromName(f), mtime };
+    });
+
+  if (reports.length === 0) {
+    return { found: false, file: null, date: null, summary: "", next: "", age_days: null };
+  }
+
+  // Newest by filename date desc; tiebreak (same/absent date) by mtime desc.
+  reports.sort((a, b) => {
+    const ad = a.date || "";
+    const bd = b.date || "";
+    if (ad !== bd) return bd.localeCompare(ad);
+    return b.mtime - a.mtime;
+  });
+
+  const top = reports[0];
+  let text = "";
+  try { text = fs.readFileSync(top.full, "utf8"); } catch {}
+  const d = digest(text);
+  const date = d.date || top.date || null;
+
+  return {
+    found: true,
+    file: top.file,
+    date,
+    summary: d.summary,
+    next: d.next,
+    age_days: ageDays(date, opts.now),
+  };
+}
+
+// ── 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 === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--now") args.now = argv[++i]; // ISO; tests inject determinism
+    else if (a.startsWith("--now=")) args.now = a.slice(6);
+    else { args._bad = a; }
+  }
+  return args;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args._bad) {
+    console.error(`last-report: unknown argument '${args._bad}'`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = latestReport(args.cwd, { now: args.now });
+  } catch (e) {
+    console.error(`last-report: ${e.message || e}`);
+    return 2;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.found ? 0 : 1;
+  }
+
+  if (!result.found) {
+    console.log("No session reports yet — nothing to surface.");
+    return 1;
+  }
+
+  const age = result.age_days == null ? "?" : result.age_days;
+  const summary = result.summary || "(no summary in report)";
+  let line = `Last session (${result.date || "undated"}, ${age}d ago): ${summary}`;
+  if (result.next) line += ` → next: ${result.next}`;
+  console.log(line);
+  return 0;
+}
+
+module.exports = { latestReport };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}