great-cto 3.13.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.13.0",
+  "version": "3.14.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

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';