great-cto 3.12.0 → 3.14.0

package/board/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "great_cto",
   "id": "great_cto",
   "description": "Engineering process for solo founders and teams up to 50 engineers. Agents do architecture, code review, QA, and security. You make two decisions per feature.",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/board/packages/board/lib/data-readers.mjs

@@ -155,7 +155,18 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
   for (let i = 0; i <= days; i++) {
     const d = new Date(now - i * 86400000);
     const key = d.toISOString().slice(0, 10);
-    buckets.set(key, { date: key, llm: 0, human: 0, plans: 0, runs: 0 });
+    // `runs` was one field incremented in two places for two different things:
+  // once per verdict that carried a cost, and once per closed task on a day that
+  // happened to have no cost data. Its meaning therefore changed from day to day
+  // depending on whether anything had been measured, and the two sums were
+  // indistinguishable once added.
+  //
+  // Measured against the verdict logs on disk, it was wrong in BOTH directions —
+  // +18 on one project over 90 days (closed tasks counted as agent runs) and −3
+  // on two others (verdicts with no cost contributing nothing). Split into the
+  // two facts, with `runs` kept as their sum so every existing reader keeps
+  // working and no chart silently changes shape.
+  buckets.set(key, { date: key, llm: 0, human: 0, plans: 0, runs: 0, agent_runs: 0, task_estimates: 0 });
   }
 
   // Plans: file mtime as date
@@ -165,6 +176,20 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
   // "LLM" and another near "Human", and FIRE the sanity check below to
   // reject pathological pairs (the 7,638× regression — total_human present
   // but total_llm fell to zero because the LLM regex was too strict).
+  // Whether a plan carried a cost at all, kept apart from what that cost was.
+  //
+  // The pair of regexes below reads a format nothing writes: measured across
+  // this repository's 41 plans, ZERO carry an LLM figure at the start of a line
+  // and one carries a Human figure — which the guard then subtracts back out. So
+  // `total_human` was $0 on every window, beside a plan count in the dozens, and
+  // read as "these plans cost nothing" rather than "no plan states a cost".
+  //
+  // There is no plan template to blame the plans for: the only template shipped
+  // is GAP-WAVE-PLAN-template.yaml, so no cost line was ever specified. Counted
+  // rather than parsed harder — the dollar figures that DO appear in plans are
+  // prose ("10 × ~$0.15", "assert total < $5") and reading them as this plan's
+  // cost would be inventing a number.
+  let planCostParsed = 0, planCostAbsent = 0, planHumanSuppressed = 0;
   const plansDir = path.join(cwd, 'docs/plans');
   if (fs.existsSync(plansDir)) {
     const planFiles = fs.readdirSync(plansDir).filter(x => x.endsWith('.md')).map(x => path.join(plansDir, x));
@@ -199,8 +224,10 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
       if (humanMatch && !llmMatch && b.human > 0) {
         // Reverse the suppression — drop the bogus single-sided Human entry.
         b.human -= parseFloat(humanMatch[1].replace(/,/g, ''));
+        planHumanSuppressed += 1;
       }
       b.plans++;
+      if (llmMatch || humanMatch) planCostParsed += 1; else planCostAbsent += 1;
     }
   }
 
@@ -217,18 +244,28 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
   // feature=X aggregation — answers "how much did stripe-webhook cost?"
   const featureMap = new Map(); // feature → { llm, runs }
   for (const v of verdicts) {
-    if (v.cost_usd == null) continue;
     const dayKey = (v.ts || '').slice(0, 10);
     if (!buckets.has(dayKey)) continue;
     const b = buckets.get(dayKey);
-    b.llm += v.cost_usd;
+    // A run that was never priced is still a run.
+    //
+    // This began `if (v.cost_usd == null) continue`, so a verdict carrying no
+    // cost contributed nothing at all — not even its own existence. Measured
+    // against the logs: one project had four verdicts and reported ZERO agent
+    // runs, because none of the four had been priced. "We do not know what it
+    // cost" was being rendered as "it did not happen", which is the confusion
+    // this codebase keeps having to unpick.
+    //
+    // Cost is added only when there is one; the run is counted either way.
+    if (v.cost_usd != null) b.llm += v.cost_usd;
+    b.agent_runs++;
     b.runs++;
     // Extract feature= tag from raw verdict line
     const featMatch = v.raw && v.raw.match(/\bfeature=([^\s|]+)/);
     if (featMatch) {
       const feat = featMatch[1];
       const f = featureMap.get(feat) || { llm: 0, runs: 0 };
-      f.llm += v.cost_usd;
+      if (v.cost_usd != null) f.llm += v.cost_usd;
       f.runs++;
       featureMap.set(feat, f);
     }
@@ -258,6 +295,10 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
       if (b.llm === 0) {
         const mins = t.estimated_minutes || DEFAULT_TASK_MIN;
         b.llm += mins / 60 * LLM_RATE_PER_HR;
+        // A closed task is not an agent run. It is counted, and counted
+        // separately, so a caller asking "how many times did agents run" is not
+        // handed a number that is partly something else.
+        b.task_estimates++;
         b.runs++;
       }
     }
@@ -267,6 +308,11 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
   let totalLlm = series.reduce((a, b) => a + b.llm, 0);
   let totalHuman = series.reduce((a, b) => a + b.human, 0);
   const totalPlans = series.reduce((a, b) => a + b.plans, 0);
+  // Reported alongside the sum rather than instead of it: `total_runs` keeps its
+  // meaning for every existing caller, and the two facts it was made of are now
+  // separately answerable.
+  const totalAgentRuns = series.reduce((a, b) => a + b.agent_runs, 0);
+  const totalTaskEstimates = series.reduce((a, b) => a + b.task_estimates, 0);
 
   // SANITY GUARD — anti-7,638× regression. If ratio > 1000×, one of the
   // numbers is wrong. Almost always: total_llm collapsed to ~0 because plan
@@ -291,6 +337,14 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
     total_llm: Math.round(totalLlm * 100) / 100,
     total_human: Math.round(totalHuman),
     total_plans: totalPlans,
+    total_agent_runs: totalAgentRuns,
+    total_task_estimates: totalTaskEstimates,
+    // Three states, not a number and a silence: a plan that states a cost, a
+    // plan that states none, and a plan whose Human figure was suppressed
+    // because its LLM counterpart could not be read.
+    plans_with_cost: planCostParsed,
+    plans_without_cost: planCostAbsent,
+    plans_human_suppressed: planHumanSuppressed,
     daily_avg: Math.round(dayRate * 100) / 100,
     projected_monthly: projectedMonthly,
     monthly_budget: budget,

package/board/packages/board/lib/docs.mjs

@@ -44,9 +44,86 @@ export const DOC_GROUPS = Object.freeze([
   { key: 'plans', label: 'Plans', dirs: ['docs/plans'], why: 'what was going to be done' },
   { key: 'reviews', label: 'Reviews', dirs: ['docs/qa', 'docs/security', 'docs/quality'], why: 'what was checked, and what it found' },
   { key: 'design', label: 'Design', dirs: ['docs/design', 'docs/product'], why: 'what it should look like and for whom' },
+  // Added because it was carrying real weight in `other`, not for symmetry: one
+  // project keeps 17 runbooks under `docs/runbooks`, and this repository has
+  // `docs/reference`, `docs/tutorials`, `docs/operations` and a FAQ. "How do I
+  // run this" is a question a reader arrives with, and it is not answered by any
+  // of the six groups above.
+  { key: 'guides', label: 'How to run it', dirs: ['docs/runbooks', 'docs/reference', 'docs/tutorials', 'docs/operations'], why: 'how to operate it and how to use it' },
   { key: 'other', label: 'Other', dirs: ['docs'], why: 'everything else the project wrote down' },
 ]);
 
+/**
+ * The word a document uses to say what KIND of document it is, and the group
+ * that word belongs to.
+ *
+ * Path alone recognised 24% of one project's corpus — 165 of 217 documents fell
+ * into `other`, which is a classifier that has stopped classifying. The reason
+ * is that `docs/architecture`, `docs/adr`, `docs/plans` are this repository's
+ * own conventions and real projects do not share them: they write
+ * `docs/impl-briefs/IMPL-BRIEF-*.md`, `docs/research/2026-04-06-max-backtest.md`,
+ * `docs/agent_quality_hardening_plan.md`.
+ *
+ * So the type token is looked for wherever an author might have put it — a
+ * directory name, the filename, or the first heading — and each of those is
+ * split into words rather than matched as a prefix, because `IMPL-BRIEF-x`,
+ * `sec-threats/` and `agent_quality_hardening_plan` all announce their type in
+ * a word that is not at position zero.
+ *
+ * Words that are a document's SUBJECT more often than its type are deliberately
+ * absent, and each omission was bought by a wrong answer: `quality` put
+ * `agent_quality_hardening_plan.md` in Reviews, `ux` put a plan named
+ * `…-flow-compiler-ux.md` in Design, `product` pulled `PRODUCT-BUILDER-DIRECTION.md`
+ * out of the strategy directory it was filed in. `deploy`, `live` and `prod`
+ * never made it in for the same reason. A confident wrong group is worse for a
+ * reader than `other` — `docs/quality`, `docs/product` and `docs/design` are
+ * still canonical directories below, so a project that files by that word keeps
+ * the grouping; what is gone is guessing from the word appearing anywhere.
+ */
+const TYPE_TOKENS = Object.freeze({
+  adr: 'decisions', adrs: 'decisions', dec: 'decisions', decision: 'decisions',
+  decisions: 'decisions', rfc: 'decisions',
+
+  arch: 'architecture', architecture: 'architecture', spec: 'architecture',
+  specs: 'architecture', schema: 'architecture',
+
+  plan: 'plans', plans: 'plans', roadmap: 'plans', backlog: 'plans',
+  impl: 'plans', strategy: 'plans', proposal: 'plans',
+
+  qa: 'reviews', uat: 'reviews', audit: 'reviews', audits: 'reviews',
+  review: 'reviews', reviews: 'reviews', test: 'reviews', tests: 'reviews',
+  testing: 'reviews', security: 'reviews', sec: 'reviews', tm: 'reviews',
+  threat: 'reviews', risk: 'reviews', risks: 'reviews', incident: 'reviews',
+  incidents: 'reviews', postmortem: 'reviews', research: 'reviews',
+  analysis: 'reviews', benchmark: 'reviews', benchmarks: 'reviews',
+  bench: 'reviews', report: 'reviews', reports: 'reviews', eval: 'reviews',
+  evaluation: 'reviews', measurement: 'reviews', validation: 'reviews',
+  checklist: 'reviews', backtest: 'reviews',
+
+  design: 'design', designs: 'design', brief: 'design', briefs: 'design',
+  prd: 'design',
+
+  runbook: 'guides', runbooks: 'guides', guide: 'guides', guides: 'guides',
+  tutorial: 'guides', tutorials: 'guides', howto: 'guides',
+  reference: 'guides', operations: 'guides', faq: 'guides', help: 'guides',
+  setup: 'guides', onboarding: 'guides',
+});
+
+/** Words of a name, so `IMPL-BRIEF-x`, `sec-threats` and `a_b_plan` all yield tokens. */
+function words(s) {
+  return String(s).toLowerCase().split(/[^a-z0-9]+/i).filter(Boolean);
+}
+
+/** The first word that names a kind of document, left to right — a type is announced early. */
+function tokenGroup(name, { limit = Infinity } = {}) {
+  const w = words(name);
+  for (let i = 0; i < w.length && i < limit; i++) {
+    const g = TYPE_TOKENS[w[i]];
+    if (g) return g;
+  }
+  return null;
+}
+
 /** Never walked: large, generated, or not this project's writing. */
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', 'screenshots', 'vendor']);
 
@@ -61,11 +138,14 @@ export const MAX_DOCS = 500;
  * is in the first few lines or it is not a title.
  */
 export function titleOf(absPath, { read = fs.readFileSync } = {}) {
-  try {
-    const head = String(read(absPath, 'utf8')).slice(0, 2000);
-    const m = head.match(/^#\s+(.+?)\s*$/m);
-    return m ? m[1].replace(/\.md$/i, '').trim() : null;
-  } catch { return null; }
+  try { return titleFromText(String(read(absPath, 'utf8'))); }
+  catch { return null; }
+}
+
+/** The same heading, from text already in hand — the classifier reads it too. */
+export function titleFromText(text) {
+  const m = String(text || '').slice(0, 2000).match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1].replace(/\.md$/i, '').trim() : null;
 }
 
 function walk(dir, root, out, depth = 0) {
@@ -84,16 +164,110 @@ function walk(dir, root, out, depth = 0) {
   }
 }
 
-/** Which group a path belongs to — first match wins, so `other` catches the rest. */
-export function groupFor(rel) {
+/**
+ * Which group a document belongs to.
+ *
+ * Signals in order of how much they actually know, which is not the order they
+ * look convincing in:
+ *
+ *   1. an exact named file          README.md / CLAUDE.md — not a guess at all
+ *   2. front-matter `type:`         the author said it outright
+ *   3. the LEADING filename token   `ADR-019-…`, `PLAN-…`, `IMPL-BRIEF-…`,
+ *                                   `2026-08-21-…` after the date is skipped
+ *   4. a canonical directory        docs/adr, docs/plans, docs/product, …
+ *   5. any other directory segment  deepest first: `superpowers/plans` is a
+ *                                   plans directory, `superpowers` is not
+ *   6. a token elsewhere in the name `agent_quality_hardening_plan.md`
+ *   7. the first `# ` heading       opening words only
+ *   8. a bare README              a name that describes nothing else
+ *
+ * The leading filename token outranks the directory, and that ordering was
+ * bought: 14 `docs/architecture/ADR-0NN-*.md` files were being filed as
+ * Architecture, and `docs/design/PLAN-*.md` as Design. A directory is where a
+ * project dumps a category; the front of a filename is what the author called
+ * THIS document. Mid-name tokens rank below the directory instead, because
+ * there the word is usually the subject — which is why
+ * `…-flow-compiler-ux.md`, a plan, must not leave `docs/superpowers/plans`.
+ *
+ * `other` stays the answer when nothing above speaks. A document that will not
+ * classify is still listed — never dropped, never hidden.
+ *
+ * @param {string} rel  path relative to the project root
+ * @param {{text?: string}} hints  the document's text, when it has been read
+ */
+export function groupFor(rel, { text = '' } = {}) {
   const p = rel.split(path.sep).join('/');
+  const base = path.basename(p, '.md');
+
   for (const g of DOC_GROUPS) {
     if ((g.files || []).includes(p)) return g.key;
+  }
+
+  const declared = declaredType(text);
+  if (declared && TYPE_TOKENS[declared]) return TYPE_TOKENS[declared];
+
+  const lead = leadingTypeToken(base);
+  if (lead) return lead;
+
+  // `other` owns `docs/`, which would swallow every path — it is the fallback,
+  // not a directory rule, so it is skipped here and returned at the end.
+  for (const g of DOC_GROUPS) {
+    if (g.key === 'other') continue;
     if ((g.dirs || []).some((d) => p === d || p.startsWith(`${d}/`))) return g.key;
   }
+
+  const segments = p.split('/').slice(0, -1);
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const g = tokenGroup(segments[i]);
+    if (g) return g;
+  }
+
+  const fromName = tokenGroup(base);
+  if (fromName) return fromName;
+
+  // Only the heading's opening words. A title announces its type at the front
+  // ("QA report — …", "ADR-011: …"); four words in, "The details the README used
+  // to carry" filed a page about the README under "This project", and
+  // "Positioning vocabulary — product-builder language" landed in Design.
+  const heading = text ? titleFromText(text) : null;
+  if (heading) {
+    const g = tokenGroup(heading, { limit: 2 });
+    if (g) return g;
+  }
+
+  // Last, not in TYPE_TOKENS: `README` names no type, so it must not outrank a
+  // directory that does — `docs/uat/README.md` is a review and
+  // `docs/benchmarks/briefs/README.md` is a brief. Reaching here means nothing
+  // else spoke, and then it is the project's own front page (including
+  // `docs/ru/README.md` and the nine other translations).
+  if (base.toLowerCase() === 'readme') return 'state';
+
   return 'other';
 }
 
+/**
+ * The type token at the FRONT of a filename, past any leading date or number.
+ *
+ * `ADR-019-…`, `TM-…`, `UAT-2026-08-21-0824`, `00_Backlog` all announce their
+ * type first; `2026-04-16-blog-quality-improvement` announces a date first and
+ * then a subject, and must not be read as a type at all.
+ */
+function leadingTypeToken(base) {
+  for (const w of words(base)) {
+    if (/^\d+$/.test(w)) continue;  // a leading date or ordinal, not a type
+    return TYPE_TOKENS[w] || null;  // the first real word decides, or nothing does
+  }
+  return null;
+}
+
+/** An author's own `type:` / `group:` / `kind:` / `category:` in YAML front-matter. */
+function declaredType(text) {
+  const fm = String(text || '').replace(/^\uFEFF/, '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return null;
+  const m = fm[1].match(/^(?:doc_?type|type|group|kind|category):\s*["']?([A-Za-z][\w-]*)/im);
+  return m ? m[1].toLowerCase() : null;
+}
+
 /**
  * Every document in the project, grouped and newest first within each group.
  *
@@ -102,30 +276,46 @@ export function groupFor(rel) {
  * than hiding it.
  */
 /**
- * One document's freshness, as three states rather than a date.
+ * One document's freshness — three states, and an absence that is not a state.
  *
- * `unknown` covers two different absences and says which: a file we could not
- * read at all, and a file that simply declares no date. Neither may render as
- * fresh — the whole reason `stale_after` exists is that a document nobody can
- * judge must not look like one that passed.
+ *   'stale'    a review date was declared and it has passed, or the doc's own
+ *              date is older than the threshold. The actionable one.
+ *   'fresh'    a date was declared and the doc is inside it.
+ *   null       the doc declares no review date. This is the NORM, not a finding:
+ *              of 1634 md files in one project, zero declare `stale_after`; of
+ *              2541 here, five do. Measured on the live board, the old code put
+ *              `unknown` on 198 of 217 documents in one project and 148 of 187
+ *              in another — a mark on nine rows in ten distinguishes nothing,
+ *              and it hid the 19 documents that had actually been judged.
+ *              `null` rather than a word so a caller can skip the badge with
+ *              `if (!doc.freshness)` and never has to know a vocabulary.
+ *
+ *   'unknown'  reserved for the one case that IS a defect: the file could not be
+ *              read. That must not render as fresh and must not be filed with
+ *              the ordinary majority — `freshnessBasis: 'unreadable'` says which.
+ *
+ * `freshnessBasis` and `freshnessWhy` are kept in every case, so nothing that
+ * was in the payload has been removed: 'declared' | 'mtime' | 'undeclared' |
+ * 'unreadable' still names the rule that produced (or did not produce) a verdict.
  */
-function freshnessOf(abs, nowMs = Date.now(), staleDays = 180) {
-  let text;
-  try { text = fs.readFileSync(abs, 'utf8'); }
-  catch (e) {
+function freshnessOf(text, nowMs = Date.now(), staleDays = 180) {
+  if (text === null) {
     return { freshness: 'unknown', freshnessBasis: 'unreadable', staleAfter: null,
-      freshnessWhy: `could not read this file: ${String(e?.message || e)}` };
+      freshnessWhy: 'could not read this file' };
   }
   try {
     const j = judgeFreshness({ text, dateType: 'any', nowMs, staleDays });
+    if (!j.declared) {
+      return { freshness: null, freshnessBasis: 'undeclared', staleAfter: null,
+        freshnessWhy: 'declares no review date — most documents do not, so there is nothing to judge and nothing wrong' };
+    }
     return {
       freshness: j.verdict,
       freshnessBasis: j.basis,
       staleAfter: j.staleAfter,
       freshnessWhy: j.basis === 'declared'
         ? `the author declared it good until ${j.staleAfter}`
-        : (j.date ? `judged by its own date ${j.date} (${j.ageDays}d, threshold ${staleDays}d)`
-                  : 'no stale_after and no date — nothing to judge it by'),
+        : `judged by its own date ${j.date} (${j.ageDays}d, threshold ${staleDays}d)`,
     };
   } catch (e) {
     return { freshness: 'unknown', freshnessBasis: 'unreadable', staleAfter: null,
@@ -151,11 +341,17 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
   for (const d of found) {
     if (seen.has(d.rel) || docs.length >= max) continue;
     seen.add(d.rel);
+    // Read once. The title, the group and the freshness verdict are three
+    // questions about the same bytes, and this used to open every file twice.
+    // `null` distinguishes "could not be read" from "read and said nothing" —
+    // the distinction the freshness badge now rests on.
+    let text = null;
+    try { text = fs.readFileSync(d.abs, 'utf8'); } catch { /* unreadable */ }
     docs.push({
       path: d.rel,
       name: path.basename(d.rel),
-      title: titleOf(d.abs) || path.basename(d.rel, '.md'),
-      group: groupFor(d.rel),
+      title: (text !== null && titleFromText(text)) || path.basename(d.rel, '.md'),
+      group: groupFor(d.rel, { text: text ?? '' }),
       size: d.size,
       modified: d.modified,
       // A modification time answers "when was this file last touched", which is
@@ -163,7 +359,7 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
       // document that stopped being true months earlier, and the list showed
       // only the former. `judgeFreshness` gives three verdicts and names which
       // rule produced each — see scripts/lib/freshness.mjs.
-      ...freshnessOf(d.abs),
+      ...freshnessOf(text),
     });
   }
 

package/board/packages/board/lib/metrics.mjs

@@ -123,6 +123,26 @@ function getMetrics(cwd = process.cwd(), days = 30) {
   // with the "Last 30 days" panel ($6.42) shown directly below it. Now both
   // sit on the same N-day window so the dashboard numbers reconcile.
   const costWindowMs = days * 86400_000;
+  // How much of the requested window actually contains anything.
+  //
+  // The operator switched 1D → 7D → 30D → 90D, saw the same figures every time,
+  // and reported the period selector as broken. It was not: every task in that
+  // project closed within the last 24 hours, so a wider window selects the same
+  // work. The numbers were right and unreadable — a screen that answers
+  // identically to four different questions gives you no way to tell "nothing
+  // changed" from "nothing is being computed".
+  //
+  // So the payload carries the span the data actually occupies. A caller can
+  // then say "90 days requested, 1 day has data" instead of showing four
+  // identical tiles and leaving the reader to guess which failure it is.
+  const _closedTs = tasks
+    .filter((t) => t.closed_at)
+    .map((t) => new Date(t.closed_at).getTime())
+    .filter((ms) => Number.isFinite(ms) && (now - ms) <= costWindowMs);
+  const _daysWithData = new Set(_closedTs.map((ms) => new Date(ms).toISOString().slice(0, 10))).size;
+  const _spanDays = _closedTs.length
+    ? Math.max(1, Math.ceil((Math.max(..._closedTs) - Math.min(..._closedTs)) / 86400_000))
+    : 0;
   // AI active time per task: use estimated_minutes if set, else DEFAULT_TASK_MIN (30m).
   // We deliberately DO NOT use wall-clock (closed_at - created_at) because that
   // includes idle time — tasks that sit in backlog for days before being closed
@@ -227,7 +247,15 @@ function getMetrics(cwd = process.cwd(), days = 30) {
       llm_usd:   Math.round(verdictLlmTotal * 100) / 100,
       human_usd: Math.round(humanLeg),
       savings_x: humanLeg > 0 ? Math.round(humanLeg / verdictLlmTotal) : null,
-      window_days: 30,
+      // `days`, not a hardcoded 30. Both of these branches asserted a 30-day
+      // window whatever was asked for, so a request for one day came back
+      // labelled as a month. The values were windowed correctly all along — only
+      // the label lied, which is the harder kind to notice.
+      window_days: days,
+      // Reported beside the window, not instead of it: "90 days requested, 1 day
+      // has data" is a different statement from "90 days of data".
+      days_with_data: _daysWithData,
+      data_span_days: _spanDays,
       count:     verdictsWithCost,
       coverage:  doneInWindowCount > 0 ? Math.round((verdictsWithCost / doneInWindowCount) * 100) : null,
       source:    'measured',
@@ -244,7 +272,11 @@ function getMetrics(cwd = process.cwd(), days = 30) {
       human_usd: Math.round(taskHumanTotal),
       savings_x: null,
       rate_ratio: Math.round(HUMAN_RATE_PER_HR / LLM_RATE_PER_HR),
-      window_days: 30,
+      window_days: days,
+      // Reported beside the window, not instead of it: "90 days requested, 1 day
+      // has data" is a different statement from "90 days of data".
+      days_with_data: _daysWithData,
+      data_span_days: _spanDays,
       count:     0,
       source:    'tasks',
       real_llm_usd: verdictLlmTotal > 0 ? Math.round(verdictLlmTotal * 10000) / 10000 : null,

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

@@ -12,6 +12,7 @@ import { sseClients, notifHistory } from './state.mjs';
 import { autoRegisterProject, listProjects, resolveProjectCwd, resolveProjectInfo, getChangeTier, readProjectsRegistry, getRegistryDegradation } from './projects.mjs';
 import { readVerdictsWithHealth } from './verdicts.mjs';
 import { readScores, summarizeScores } from '../../../scripts/lib/scores.mjs';
+import { status as routerKeyStatus, writeKey as writeRouterKey } from '../../../scripts/lib/router-key.mjs';
 import { broadcastTasks } from './sse.mjs';
 import { saveNotifHistory } from './notifications.mjs';
 import { getMemory, getPipeline, getCostHistory, getInbox } from './data-readers.mjs';
@@ -690,6 +691,57 @@ async function dispatch(req, res, url, cwd) {
   // caller cannot render "100%" without also being handed the count it is out
   // of. An agent with nine unverifiable runs and one verified one is not a 100%
   // agent, and the payload refuses to let the UI say it is.
+  // Is the judge connected, and let the operator connect it.
+  //
+  // Nothing breaks without a key — every stage comes back `unverifiable`, which
+  // is honest. But "the judge is not connected" and "the judge found nothing to
+  // check" read identically from here, and the user has no way to discover a key
+  // is involved: the README mentions OpenRouter once without saying where the key
+  // goes, and the router's own hint names a file it is not read from.
+  //
+  // GET NEVER RETURNS THE KEY. It answers presence, which of the three locations
+  // it came from, and eight characters of it — enough to tell two keys apart,
+  // useless as a key. A read path would make any future XSS in a 7,600-line
+  // single-page app a secret disclosure, and buys nothing: nobody needs to read
+  // back a key they already hold.
+  if (pathname === '/api/router-key' && req.method === 'GET') {
+    res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
+    res.end(JSON.stringify(routerKeyStatus({ cwd })));
+    return true;
+  }
+
+  if (pathname === '/api/router-key' && req.method === 'POST') {
+    if (!originAllowed(req)) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'origin not allowed' }));
+      return true;
+    }
+    let body = '';
+    req.on('data', (c) => { body += c; if (body.length > 4096) req.destroy(); });
+    req.on('end', () => {
+      let parsed;
+      try { parsed = JSON.parse(body || '{}'); }
+      catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'invalid_json', message: String(e.message || e) }));
+        return;
+      }
+      const r = writeRouterKey(String(parsed.key || ''));
+      if (!r.ok) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: r.error }));
+        return;
+      }
+      // The reply carries the new status, not the key, and names the backup —
+      // a write to a file holding other credentials should say what it saved
+      // first, because this file has been destroyed once by a careless write.
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, replaced: r.replaced, backup: r.backup,
+                               status: routerKeyStatus({ cwd }) }));
+    });
+    return true;
+  }
+
   if (pathname === '/api/scores') {
     const agent = url.searchParams.get('agent') || null;
     const name = url.searchParams.get('name') || 'independent-verify';

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

@@ -92,6 +92,28 @@ function readVerdicts(cwd = null, health = null) {
       continue;
     }
     for (const file of files) {
+    // Only per-agent verdict logs. `<agent>-YYYY-MM-DD-HHMMSS.log` is a different
+    // artefact that lives in the same directory: a free-text report of one run,
+    // written as prose. Reading it as a verdict log made its first words into
+    // records — `ts: "DONE:"`, `ts: "artifact:"`, `ts: "next:"`, with the agent
+    // name taken from the filename including its timestamp. Six of the ten
+    // "verdicts" one project appeared to have were paragraph openings.
+    //
+    // Skipped rather than parsed leniently: a run report has no verdict token, no
+    // cost and no meta, so anything recovered from it would be invented. Counted,
+    // though — a directory whose contents this reader ignores is worth saying out
+    // loud, because from outside it looks identical to a project that never ran.
+    if (!file.endsWith('.log')) continue;
+    // Rejected by the shape that IDENTIFIES a run report, not by trying to
+    // describe what a valid agent name looks like. The first attempt did the
+    // latter — `/^[A-Za-z0-9_:.-]+\.log$/` — and matched
+    // `architect-2026-08-26-134109.log` perfectly well, because digits and
+    // hyphens are exactly what an agent name may contain. An allowlist that
+    // cannot exclude the thing it was written to exclude is not a filter.
+    if (RUN_REPORT_FILE.test(file)) {
+      health?.notes?.push(`${file} is a run report, not a verdict log — not read`);
+      continue;
+    }
     const agent = file.replace('.log', '');
     let lines;
     try {
@@ -192,6 +214,9 @@ function readVerdicts(cwd = null, health = null) {
   return results.sort((a, b) => a.ts.localeCompare(b.ts));
 }
 
+/** `<agent>-YYYY-MM-DD-HHMMSS.log` — a prose report of one run, not a verdict. */
+const RUN_REPORT_FILE = /-\d{4}-\d{2}-\d{2}-\d{6}\.log$/;
+
 function readPlanCosts(cwd = process.cwd(), sinceMsAgo = null) {
   const plansDir = path.join(cwd, 'docs/plans');
   let totalLlmMin = 0, totalLlmUsd = 0, totalHumanUsd = 0, count = 0;