great-cto 2.95.0 → 2.97.0

package/board/packages/board/lib/routes.mjs

@@ -9,7 +9,8 @@ import {
 import { GREAT_CTO_DIR, VAPID_KEYS_FILE, PUSH_SUBS_FILE, BUILD_VERSION } from './config.mjs';
 import { eventSurface, readFileSafe, originAllowed } from './util.mjs';
 import { sseClients, notifHistory } from './state.mjs';
-import { autoRegisterProject, listProjects, resolveProjectCwd, getChangeTier } from './projects.mjs';
+import { autoRegisterProject, listProjects, resolveProjectCwd, resolveProjectInfo, getChangeTier, readProjectsRegistry, getRegistryDegradation } from './projects.mjs';
+import { readVerdictsWithHealth } from './verdicts.mjs';
 import { broadcastTasks } from './sse.mjs';
 import { saveNotifHistory } from './notifications.mjs';
 import { getMemory, getPipeline, getCostHistory, getInbox } from './data-readers.mjs';
@@ -25,9 +26,51 @@ import { listSessions, readSession, editedFiles, searchSessions } from './transc
 // dispatch(req, res, url, cwd, projInfo) handles every /api/* route plus /api/sse.
 // Returns true if the request was handled (response already sent or streaming),
 // false if the caller (server.mjs) should fall through to static file serving.
+/**
+ * Headers for a response whose data came from the verdict reader.
+ *
+ * Metrics, cost, the pipeline strip and the inbox are all built from
+ * readVerdicts, which returned [] on every kind of failure — so an unreadable
+ * verdict directory arrived at four panels as "this project has not run
+ * anything". That is a different claim from "I could not look", and a confident
+ * one.
+ */
+function verdictHeaders(cwd, base = { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }) {
+  try {
+    const { unread } = readVerdictsWithHealth(cwd);
+    if (unread) return { ...base, 'X-Board-Degraded': encodeURIComponent(unread) };
+  } catch { /* never fail a response over its own health check */ }
+  return base;
+}
+
 async function dispatch(req, res, url, cwd) {
   const pathname = url.pathname;
 
+  // The selected project, resolved ONCE for every route below.
+  //
+  // The board is multi-project — a registry of twenty-two, a switcher in the
+  // sidebar — and sixteen of its eighteen endpoints read `cwd`, the directory
+  // the SERVER was started in. Switching to another project changed the heading
+  // and nothing else: a project with a .great_cto holding two verdicts and
+  // thirty-nine session logs had every panel show 0.
+  //
+  // Which is the failure this board keeps making in other forms: a read that did
+  // not happen looked exactly like an absence of data. Resolving here rather than
+  // per-route means the next endpoint added cannot forget.
+  //
+  // A slug that does not resolve falls back to the server's directory — that is
+  // pre-existing behaviour and it is defensible, but it must not be silent, so
+  // it is announced in a header rather than shown as if it were the project asked
+  // for.
+  const requestedProject = url.searchParams.get('project');
+  if (requestedProject) {
+    const info = resolveProjectInfo(requestedProject);
+    cwd = info.cwd;
+    if (info.resolved === 'fallback' && typeof res.setHeader === 'function') {
+      try { res.setHeader('X-Project-Fallback', String(info.requested || requestedProject)); } catch { /* headers already sent */ }
+    }
+  }
+
   // SSE
   if (pathname === '/api/sse') {
     res.writeHead(200, {
@@ -120,7 +163,7 @@ async function dispatch(req, res, url, cwd) {
     let days = parseInt(url.searchParams.get('days') || '30', 10);
     if (!Number.isFinite(days) || days < 1) days = 30;
     if (days > 365) days = 365;
-    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.writeHead(200, verdictHeaders(cwd));
     res.end(JSON.stringify(getMetrics(cwd, days)));
     return true;
   }
@@ -297,6 +340,61 @@ async function dispatch(req, res, url, cwd) {
 
   // ── Read a project doc (markdown) referenced from a task — for the side-panel viewer.
   // Path-traversal-safe: the resolved path must stay inside the project cwd; .md only.
+  // Which documents exist, and the two diagrams nobody hand-draws.
+  //
+  // /api/doc could already fetch one document by path; the question before that
+  // — which documents exist — had no answer, so a project's twenty architecture
+  // documents and ten ADRs were reachable only by knowing a filename.
+  //
+  // The maps are computed per request rather than stored. docs/ARCHITECTURE.md
+  // is a hand-drawn diagram, three months old, that says "34 agents" where there
+  // are sixty-nine; a picture that is regenerated when looked at cannot drift.
+  // The whole fleet on one screen.
+  //
+  // Every other endpoint answers about one project, so "what needs me right now
+  // across all twenty-two" had no answer and the switcher was a poor substitute
+  // for one. Read-only, file-only: gate approval is authoritative but costs about
+  // 530ms per project, which is twelve seconds on a screen meant to be glanced
+  // at. This reads 23 projects in about 140ms.
+  if (pathname === '/api/portfolio' && req.method === 'GET') {
+    try {
+      const { portfolio } = await import('./portfolio.mjs');
+      const reg = readProjectsRegistry();
+      const degraded = getRegistryDegradation();
+      // A registry that could not be read used to render as a board with no
+      // projects — the same silence this screen exists to remove, one level out.
+      const out = portfolio(degraded ? { unread: degraded } : reg);
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify(out));
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: String(e.message || e) }));
+    }
+    return true;
+  }
+
+  if (pathname === '/api/docs' && req.method === 'GET') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    try {
+      const [{ listDocs }, { systemMap, toMermaid, pipelineMermaid }] = await Promise.all([
+        import('./docs.mjs'), import('../../../scripts/lib/system-map.mjs'),
+      ]);
+      const map = systemMap(c);
+      let pipeline = null;
+      try { pipeline = pipelineMermaid(fs.readFileSync(path.join(c, 'shared', 'pipeline.toml'), 'utf8')); } catch { /* not a great_cto project */ }
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({
+        ...listDocs(c),
+        map: { nodes: map.nodes, edges: map.edges, generatedAt: map.generatedAt, mermaid: toMermaid(map) },
+        pipeline,
+      }));
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: String(e.message || e) }));
+    }
+    return true;
+  }
+
   if (pathname === '/api/doc' && req.method === 'GET') {
     const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
     const rel = String(url.searchParams.get('path') || '');
@@ -352,6 +450,10 @@ async function dispatch(req, res, url, cwd) {
         res.end(JSON.stringify(beadsErr));
         return;
       }
+      // Named outside the serialised block so the wake below can say WHICH gate a
+      // human approved; the lookup itself belongs inside the lock.
+      let gateTitle = id;
+
       // BH-16 fix: serialise gate writes through bd-write queue.
       // Without this, concurrent approve+reject on the same gate produced
       // TWO appendDecisionLog entries (one wrong) — log says approved AND
@@ -379,6 +481,7 @@ async function dispatch(req, res, url, cwd) {
           const allTasks = getTasks(gateCwd);
           const gateTask = allTasks.find(t => t.id === id);
           const title = gateTask?.title || id;
+          gateTitle = title;
           appendDecisionLog({
             ts: new Date().toISOString(),
             project: projectSlug,
@@ -396,8 +499,37 @@ async function dispatch(req, res, url, cwd) {
         res.end(JSON.stringify({ error: (result && result.error) || 'bd update failed' }));
         return;
       }
+      // An approval is evidence that the pipeline is waiting — record it.
+      //
+      // `session-pipeline-resume` opens with a freshness shortcut: a pipeline
+      // whose newest verdict is over a day old is treated as history and the
+      // hook returns before reading a single gate. Approve `gate:arch` on a
+      // stage that ran three days ago and the one fact that proves work is
+      // waiting is the one thing never consulted.
+      //
+      // This records the approval so the next session looks properly. It
+      // decides nothing: tickDecision still applies every refusal it has,
+      // including never dispatching devops or infra-provisioner unattended
+      // (ADR-009). Best-effort — a wake we cannot write must not fail an
+      // approval that already happened.
+      let wake = null;
+      if (action === 'approve') {
+        try {
+          const { recordWake } = await import('../../../scripts/lib/pipeline-wake.mjs');
+          const r = recordWake(gateCwd, { gate: gateTitle, id });
+          wake = r.ok ? { recorded: true } : { recorded: false, why: r.why };
+        } catch (e) {
+          // Report the actual failure. The first version of this catch guessed
+          // ("unavailable in this board build") and printed the guess as a
+          // finding — it was a ReferenceError three lines up, and the guess sent
+          // the reader looking at packaging. A handler that names a cause it did
+          // not observe is worse than one that says nothing.
+          wake = { recorded: false, why: String(e?.message || e) };
+        }
+      }
+
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, id, action, via: result.via }));
+      res.end(JSON.stringify({ ok: true, id, action, via: result.via, ...(wake ? { wake } : {}) }));
       broadcastTasks(gateCwd);
       // Auto-republish share report when a gate is approved (fire-and-forget)
       if (action === 'approve') {
@@ -414,14 +546,121 @@ async function dispatch(req, res, url, cwd) {
 
   // Inbox — what needs your attention right now
   if (pathname === '/api/inbox') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getInbox(cwd)));
     return true;
   }
 
+  // Receipt — does the approval still apply to what is in the tree?
+  //
+  // The reviewing agents already record a hash-bound receipt of the bytes they
+  // read, and those verdicts are in the log this board reads. Nothing surfaced
+  // them, so the top rung of the evidence ladder — the reviewed bytes are the
+  // shipped bytes — was being written and never looked at. An approval that no
+  // longer describes the tree is the one thing a gate button cannot tell you.
+  if (pathname === '/api/receipt') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    let out;
+    try {
+      const { latestApproval, treeReceipt, compareReceipts, mergeBase } = await import('../../../scripts/lib/receipt.mjs');
+      const approval = latestApproval(c);
+      if (!approval?.receipt) {
+        out = { state: 'no-receipt', why: 'no approving verdict carries a receipt yet', agent: approval?.agent || null, ts: approval?.ts || null };
+      } else {
+        const current = treeReceipt(c, { base: approval.receipt.base || mergeBase(c) });
+        const cmp = compareReceipts(approval.receipt, current, { cwd: c });
+        out = { ...cmp, agent: approval.agent, ts: approval.ts };
+      }
+    } catch (e) {
+      // Never "matches" on an error. Not knowing whether the approval still
+      // holds is its own state, and calling it a match would put the strongest
+      // reassurance exactly where the least is known.
+      out = { state: 'unreadable', why: String(e?.message || e), agent: null, ts: null };
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(out));
+    return true;
+  }
+
+  // Gate tiers — will this gate wait for you, or announce and proceed?
+  //
+  // A gate card offered Approve/Reject regardless, which is the right control
+  // for a `gated` gate and the wrong one for a tiered gate that already went
+  // ahead. Two states rendered where the machinery has three.
+  //
+  // `enabled` is returned alongside, because a tier is only in force when the
+  // project opted in with `gate-tiering: evidence`. Showing "notify" on a
+  // project that never opted in would describe a stand-down that will not
+  // happen — the mirror image of the defect this whole feature guards.
+  if (pathname === '/api/gate-tiers') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    try {
+      const { tierAll, tieringEnabled } = await import('../../../scripts/lib/gate-tier.mjs');
+      const { fileURLToPath: f2u } = await import('node:url');
+      const libDir = path.dirname(f2u(import.meta.url));
+      const histPath = path.join(libDir, '..', '..', '..', 'tests', 'eval', 'results-history.jsonl');
+
+      let enabled = false;
+      try { enabled = tieringEnabled(fs.readFileSync(path.join(c, '.great_cto', 'PROJECT.md'), 'utf8')); }
+      catch { /* no PROJECT.md — tiering is off, which is the safe reading */ }
+
+      const rows = [];
+      let historyRead = false;
+      try {
+        for (const line of fs.readFileSync(histPath, 'utf8').split('\n')) {
+          if (!line.trim()) continue;
+          try { rows.push(JSON.parse(line)); } catch { /* a bad row is not evidence */ }
+        }
+        historyRead = true;
+      } catch { /* reported as unmeasured below, never as gated-because-fine */ }
+
+      const byAgent = {};
+      for (const t of tierAll(rows)) byAgent[t.agent] = { tier: t.tier, why: t.why, evals: t.evals };
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({ enabled, measured: historyRead, agents: byAgent }));
+    } catch (e) {
+      // The real error. An agent missing from `agents` reads as unmeasured on the
+      // client, which keeps its gate — the correct direction to be wrong in.
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({ enabled: false, measured: false, agents: {}, why: String(e?.message || e) }));
+    }
+    return true;
+  }
+
+  // Stand-downs — gates that proceeded WITHOUT being asked, and on what evidence.
+  //
+  // ADR-009: a gate is not the only valid answer, but silence is never one. An
+  // evidence-tiered gate announces instead of waiting, and until now that
+  // announcement had nowhere on this board to land — the record was being
+  // written and nothing read it.
+  if (pathname === '/api/stand-downs') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    let rows = null;
+    let why = '';
+    try {
+      const { readStandDowns } = await import('../../../scripts/lib/stand-down.mjs');
+      rows = readStandDowns(c, { limit: 50 });
+    } catch (e) {
+      // The real error. A handler that names a cause it did not observe sends
+      // the reader looking in the wrong place — this file has done that once.
+      why = String(e?.message || e);
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    // Three states, because two cannot carry them: `readStandDowns` returns null
+    // when the ledger exists and could not be read, [] when nothing has stood
+    // down, and rows when something has. "I could not look" must never render as
+    // "nothing happened".
+    res.end(JSON.stringify(
+      rows === null
+        ? { state: 'unreadable', why: why || 'the stand-down ledger exists but could not be read', rows: [] }
+        : { state: rows.length ? 'some' : 'none', why: '', rows },
+    ));
+    return true;
+  }
+
   // Resume — pick up where you left off (last verdicts + WIP + recent decisions)
   if (pathname === '/api/resume') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getResume(cwd)));
     return true;
   }
@@ -435,28 +674,28 @@ async function dispatch(req, res, url, cwd) {
     const limit = Number.isFinite(parsed) && parsed > 0
       ? Math.min(parsed, 200)
       : 20;
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(readDecisionsLog(limit, cwd)));
     return true;
   }
 
   // Memory — 4-layer memory file contents
   if (pathname === '/api/memory') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getMemory(cwd)));
     return true;
   }
 
   // Pipeline — current stage states (idle / active / done / failed)
   if (pathname === '/api/pipeline') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getPipeline(cwd)));
     return true;
   }
 
   // change_tier for the current working-tree diff — the gate + judge plan (ADR-003/004).
   if (pathname === '/api/change-tier') {
-    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getChangeTier(cwd)));
     return true;
   }
@@ -475,7 +714,7 @@ async function dispatch(req, res, url, cwd) {
     const days = Number.isFinite(parsed) && parsed > 0
       ? Math.min(parsed, 365)
       : 30;
-    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.writeHead(200, verdictHeaders(cwd));
     res.end(JSON.stringify(getCostHistory(cwd, days)));
     return true;
   }
@@ -923,7 +1162,10 @@ async function dispatch(req, res, url, cwd) {
       return true;
     }
     if (!sub) {
-      const profile = getAgentProfile(slug);
+      // Scoped to the selected project — see getAgentProfile. Unscoped, this
+      // reported an agent's record across all twenty-two projects while the
+      // reader was looking at one of them.
+      const profile = getAgentProfile(slug, cwd);
       if (!profile) {
         res.writeHead(404, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'agent_not_found', slug }));

package/board/packages/board/lib/verdicts.mjs

@@ -4,7 +4,38 @@ import { GREAT_CTO_DIR } from './config.mjs';
 import { parseVerdictLine } from '../../../scripts/lib/verdict-record.mjs';
 
 
-function readVerdicts(cwd = null) {
+/**
+ * Verdicts, plus an account of what could not be read.
+ *
+ * This function feeds metrics, cost, the pipeline strip, the inbox, resume and
+ * agent statistics — six surfaces from one read. It returned `[]` on every kind
+ * of failure, so an unreadable verdict directory arrived at all six as "this
+ * project has not run anything", which is a different claim and a confident one.
+ *
+ * Three things can go wrong and each is now named rather than absorbed: a
+ * directory that cannot be listed, a file that cannot be read, and a line that
+ * does not parse. The last is not a failure of this reader — a half-written
+ * append is normal — so it is counted and only reported when it is the reason a
+ * project looks empty.
+ */
+function readVerdictsWithHealth(cwd = null) {
+  const problems = [];
+  let unreadableLines = 0;
+  const verdicts = readVerdicts(cwd, { problems, onBadLine: () => { unreadableLines += 1; } });
+  return {
+    verdicts,
+    unreadableLines,
+    // Only a real read failure degrades. Unparseable lines beside readable ones
+    // are noise; unparseable lines and NOTHING else is the project looking empty
+    // for a reason worth saying out loud.
+    unread: problems.length
+      ? problems.join('; ')
+      : (unreadableLines && !verdicts.length
+        ? `${unreadableLines} verdict line(s) could not be parsed and none could` : null),
+  };
+}
+
+function readVerdicts(cwd = null, health = null) {
   // Verdict attribution model:
   //   1. cwd given → read project-local <cwd>/.great_cto/verdicts/
   //      PLUS any global verdict line tagged `project=<slug>` matching cwd
@@ -21,9 +52,18 @@ function readVerdicts(cwd = null) {
   }
   // First read project-local verdicts when scoped
   const projectVerdictDir = cwd ? path.join(cwd, '.great_cto', 'verdicts') : null;
-  const useProjectDir = projectVerdictDir
-    && fs.existsSync(projectVerdictDir)
-    && fs.readdirSync(projectVerdictDir).filter(f => f.endsWith('.log')).length > 0;
+  // This listing happens before the main loop, to decide whether a project has
+  // any local verdicts at all — and it threw where the loop's own read is
+  // guarded, so an unreadable directory crashed the caller instead of being
+  // reported. Same failure, one line earlier.
+  let useProjectDir = false;
+  if (projectVerdictDir && fs.existsSync(projectVerdictDir)) {
+    try {
+      useProjectDir = fs.readdirSync(projectVerdictDir).filter(f => f.endsWith('.log')).length > 0;
+    } catch (e) {
+      health?.problems?.push(`verdicts could not be listed in ${projectVerdictDir}: ${e.code || e.message}`);
+    }
+  }
   // For cwd-scoped reads, we collect from BOTH local AND tagged global lines
   const verdictDirs = [];
   if (useProjectDir) verdictDirs.push(projectVerdictDir);
@@ -41,13 +81,27 @@ function readVerdicts(cwd = null) {
     const verdictDir = typeof entry === 'string' ? entry : entry.dir;
     const projectTagFilter = typeof entry === 'string' ? null : entry.filterByProjectTag;
     if (!fs.existsSync(verdictDir)) continue;
-    for (const file of fs.readdirSync(verdictDir)) {
+    let files;
+    try {
+      files = fs.readdirSync(verdictDir);
+    } catch (e) {
+      // A directory that exists and cannot be listed is the case that made a
+      // project look like it had never run.
+      health?.problems?.push(`verdicts could not be listed in ${verdictDir}: ${e.code || e.message}`);
+      continue;
+    }
+    for (const file of files) {
     const agent = file.replace('.log', '');
-    const lines = fs.readFileSync(path.join(verdictDir, file), 'utf8')
-      .split('\n').filter(Boolean);
+    let lines;
+    try {
+      lines = fs.readFileSync(path.join(verdictDir, file), 'utf8').split('\n').filter(Boolean);
+    } catch (e) {
+      health?.problems?.push(`${file} could not be read: ${e.code || e.message}`);
+      continue;
+    }
     for (const line of lines) {
       const parsed = parseVerdictLine(line);
-      if (!parsed.ok) continue;          // unreadable — counted by the CLI, not shown as a verdict
+      if (!parsed.ok) { health?.onBadLine?.(); continue; }  // counted, never shown as a verdict
 
       // When reading global with a project filter, only include records for this
       // project. Read from the parsed record, not from a `project=` substring:
@@ -169,4 +223,4 @@ function readSecStats(cwd = process.cwd()) {
   return { approved, blocked };
 }
 
-export { readVerdicts, readPlanCosts, readQAStats, readSecStats };
+export { readVerdicts, readVerdictsWithHealth, readPlanCosts, readQAStats, readSecStats };