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

package/board/packages/board/lib/beads.mjs

@@ -100,20 +100,64 @@ function bdWriteSerialised(fn) {
 // populated board on every SSE push (great_cto-e2ew). We deliberately do NOT
 // refresh cached.ts on failure, so the next call retries bd immediately
 // rather than being TTL-gated on a failed read.
+//
+// Why the failure is also RECORDED
+// --------------------------------
+// Falling back to `[]` keeps the board up, but `[]` is the same value a project
+// with no tasks returns, and the reader cannot tell them apart. A project whose
+// directory name contains a dot — `<private-project>.ai` — makes bd refuse to open its
+// database at all ("invalid database name"), and the board answered that with a
+// clean empty board: no tasks, no metrics, no explanation. Switching to it looked
+// exactly like a project nobody had started.
+//
+// So the reason is kept per-cwd and handed up to the API, which reports it in
+// `X-Board-Degraded`. The empty list is still returned — the board stays usable —
+// but it now arrives labelled.
+const bdFailures = new Map();
+
+/** Why this project's tasks could not be read, or null if they could. */
+function bdFailureFor(cwd = process.cwd()) {
+  return bdFailures.get(cwd) || null;
+}
+
+/** The first meaningful line of bd's complaint, short enough for a header. */
+function bdReason(result) {
+  const text = String(result?.stderr || result?.stdout || '').trim();
+  // bd reports some failures as JSON on stdout with status 0-adjacent shapes.
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && parsed.error) return String(parsed.error).slice(0, 300);
+  } catch { /* not JSON — use the raw first line */ }
+  const line = text.split('\n').map((s) => s.trim()).find(Boolean);
+  return (line || 'bd exited non-zero without a message').slice(0, 300);
+}
+
 function bdList(cwd = process.cwd(), runner = bd) {
   const cached = bdCache.get(cwd);
   if (cached && Date.now() - cached.ts < BD_CACHE_TTL_MS) return cached.data;
   try {
     const result = runner(['list', '--json', '--all', '--include-gates'], { cwd });
     if (result.status !== 0) {
+      bdFailures.set(cwd, bdReason(result));
       if (cached) return cached.data; // last-good data, cache untouched
       bdCache.set(cwd, { ts: Date.now(), data: [] });
       return [];
     }
-    const data = JSON.parse(result.stdout || '[]');
-    bdCache.set(cwd, { ts: Date.now(), data });
-    return data;
-  } catch {
+    // bd 0.6x reports some open failures as a JSON object on stdout with exit 0.
+    // `JSON.parse` succeeds, the result is not an array, and the board rendered
+    // it as no tasks — the same silent zero one layer further in.
+    const parsed = JSON.parse(result.stdout || '[]');
+    if (!Array.isArray(parsed)) {
+      bdFailures.set(cwd, String(parsed?.error || 'bd returned something that is not a task list').slice(0, 300));
+      if (cached) return cached.data;
+      bdCache.set(cwd, { ts: Date.now(), data: [] });
+      return [];
+    }
+    bdFailures.delete(cwd);
+    bdCache.set(cwd, { ts: Date.now(), data: parsed });
+    return parsed;
+  } catch (e) {
+    bdFailures.set(cwd, `bd could not be run: ${e?.message || e}`.slice(0, 300));
     if (cached) return cached.data; // last-good data, cache untouched
     bdCache.set(cwd, { ts: Date.now(), data: [] });
     return [];
@@ -322,7 +366,10 @@ const readDegradation = new Map();
 
 /** Degradation reason for a project's task sources, or null when healthy. */
 function getReadDegradation(cwd = process.cwd()) {
-  return readDegradation.get(cwd) || null;
+  // tasks.md first: if that file exists and is broken, that is the specific
+  // problem. Otherwise report bd's failure, which until now was swallowed — the
+  // board answered "no tasks" for a project whose database bd refused to open.
+  return readDegradation.get(cwd) || bdFailureFor(cwd) || null;
 }
 
 function parseTasksMd(cwd) {
@@ -460,6 +507,7 @@ export {
   checkBeadsAvailable,
   bdWriteSerialised,
   bdList,
+  bdFailureFor,
   parseTasksMd,
   getReadDegradation,
   setTaskStatusInTasksMd,

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

@@ -0,0 +1,137 @@
+// The project's own documentation, as something you can browse.
+//
+// A great_cto project accumulates a lot of it — this repository has twenty
+// documents at the root of `docs/`, thirty-one plans, twenty architecture
+// documents, ten ADRs — and the board showed none of it. Agents write ARCH docs,
+// ADRs, QA and security reports, and the only way to read one was to know its
+// filename and open an editor.
+//
+// `/api/doc` could already fetch a document by path. What was missing is the
+// question before that one: which documents exist, and which of them is about
+// the thing I am looking at now.
+//
+// Zero dependencies, like the rest of the board.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where a project keeps documentation, and what each place answers.
+ *
+ * Grouped by the QUESTION rather than by directory: `docs/architecture` and
+ * `docs/adr` sit next to each other on disk and answer different things — one
+ * says how the system is built, the other why it was decided that way. A reader
+ * arrives with one of those questions, not with a directory in mind.
+ */
+export const DOC_GROUPS = Object.freeze([
+  // Named files rather than the whole of `.great_cto`: that directory also holds
+  // session logs, verdict logs and lesson captures — a hundred and fourteen of
+  // them here. They are state the pipeline writes, not documentation someone
+  // would read, and burying four useful files under them is how a browser
+  // becomes something nobody opens.
+  // The .great_cto context files are listed by the "Agent context" group in the
+  // board, which knows the canonical set — including layers that are not written
+  // yet, which a directory walk cannot report because there is no file to find.
+  // Listing them here as well was the duplication between Docs and Memory.
+  {
+    key: 'state', label: 'This project',
+    files: ['README.md', 'CLAUDE.md'],
+    why: 'what it is, for a person arriving',
+  },
+  { key: 'architecture', label: 'Architecture', dirs: ['docs/architecture'], why: 'how the system is built' },
+  { key: 'decisions', label: 'Decisions', dirs: ['docs/adr', 'docs/decisions'], why: 'why it was built that way' },
+  { 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' },
+  { key: 'other', label: 'Other', dirs: ['docs'], why: 'everything else the project wrote down' },
+]);
+
+/** Never walked: large, generated, or not this project's writing. */
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', 'screenshots', 'vendor']);
+
+/** A cap, so a repository with thousands of markdown files cannot stall the board. */
+export const MAX_DOCS = 500;
+
+/**
+ * The title an author gave a document.
+ *
+ * From the first `# ` heading, because `ADR-010-pipeline-position-pull-view.md`
+ * is a filename and not what anyone called it. Read from a bounded head: a title
+ * 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; }
+}
+
+function walk(dir, root, out, depth = 0) {
+  if (depth > 3 || out.length >= MAX_DOCS) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (out.length >= MAX_DOCS) return;
+    if (SKIP.has(e.name) || e.name.startsWith('.') && e.name !== '.great_cto') continue;
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) { walk(abs, root, out, depth + 1); continue; }
+    if (!e.name.toLowerCase().endsWith('.md')) continue;
+    let st;
+    try { st = fs.statSync(abs); } catch { continue; }
+    out.push({ abs, rel: path.relative(root, abs), size: st.size, modified: st.mtime.toISOString() });
+  }
+}
+
+/** Which group a path belongs to — first match wins, so `other` catches the rest. */
+export function groupFor(rel) {
+  const p = rel.split(path.sep).join('/');
+  for (const g of DOC_GROUPS) {
+    if ((g.files || []).includes(p)) return g.key;
+    if ((g.dirs || []).some((d) => p === d || p.startsWith(`${d}/`))) return g.key;
+  }
+  return 'other';
+}
+
+/**
+ * Every document in the project, grouped and newest first within each group.
+ *
+ * Newest first because a document written today and one written in March answer
+ * differently — the same reason the pipeline view labels a stale verdict rather
+ * than hiding it.
+ */
+export function listDocs(root, { max = MAX_DOCS } = {}) {
+  const found = [];
+  for (const g of DOC_GROUPS) {
+    for (const d of g.dirs || []) walk(path.join(root, d), root, found);
+    for (const f of g.files || []) {
+      const abs = path.join(root, f);
+      try {
+        const st = fs.statSync(abs);
+        if (st.isFile()) found.push({ abs, rel: f, size: st.size, modified: st.mtime.toISOString() });
+      } catch { /* absent */ }
+    }
+  }
+
+  const seen = new Set();
+  const docs = [];
+  for (const d of found) {
+    if (seen.has(d.rel) || docs.length >= max) continue;
+    seen.add(d.rel);
+    docs.push({
+      path: d.rel,
+      name: path.basename(d.rel),
+      title: titleOf(d.abs) || path.basename(d.rel, '.md'),
+      group: groupFor(d.rel),
+      size: d.size,
+      modified: d.modified,
+    });
+  }
+
+  const groups = DOC_GROUPS.map((g) => ({
+    key: g.key, label: g.label, why: g.why,
+    docs: docs.filter((d) => d.group === g.key).sort((a, b) => b.modified.localeCompare(a.modified)),
+  })).filter((g) => g.docs.length);
+
+  return { total: docs.length, truncated: docs.length >= max, groups };
+}

package/board/packages/board/lib/fleet.mjs

@@ -193,7 +193,18 @@ function getAgentsFleet(projectCwd) {
   };
 }
 
-function getAgentProfile(slug) {
+/**
+ * One agent's profile and its recent record.
+ *
+ * `cwd` scopes the statistics to a project. Without it the counts came from
+ * every project's verdicts at once, so opening an agent while looking at
+ * one project showed its behaviour across twenty-two projects — a number that is
+ * about the fleet answering a question about this project.
+ *
+ * Omitting `cwd` still means "the whole fleet", which is what the fleet view
+ * itself wants; the defect was the caller, not the default.
+ */
+function getAgentProfile(slug, cwd = null) {
   const fp = path.join(AGENTS_DIR, `great_cto-${slug}.md`);
   if (!fs.existsSync(fp)) return null;
 
@@ -222,7 +233,7 @@ function getAgentProfile(slug) {
   const skillsM = raw.match(/^skills:\s*\n((?:[ \t]*-[ \t]*.+\n?)+)/m);
   if (skillsM) for (const line of skillsM[1].split('\n')) { const v = (line.match(/^[ \t]*-[ \t]*(.+)$/) || [])[1]; const t = v && v.trim(); if (t && !/^-+$/.test(t)) skills.push(t); }
 
-  const verdicts = readVerdicts();
+  const verdicts = readVerdicts(cwd);
   const all = verdicts.filter(v => v.agent === slug);
   const now = Date.now();
   const day30Ms = 30 * 86400_000;

package/board/packages/board/lib/portfolio.mjs

@@ -0,0 +1,128 @@
+// One screen for the whole fleet.
+//
+// The board answers a CTO's questions one project at a time. With twenty-two in
+// the registry, finding out where you are needed means switching to each of them
+// by hand — so the question "what needs me right now, across everything" has no
+// answer at all, and the switcher is a poor substitute for one.
+//
+// Three columns, one row per project: what is waiting on a decision, when the
+// project last moved, what it has cost. No sorting, no drill-down, no charts —
+// if this page is worth having, that will show without them.
+//
+// Every cell can say `unread`
+// ---------------------------
+// This is the point rather than a detail. A fleet view built on readers that
+// return zero when they fail multiplies one silent lie by twenty-two, and the
+// screen most likely to be trusted becomes the one most likely to mislead. A
+// project whose state could not be read says so; it never contributes a
+// confident zero to a total.
+//
+// Why no `bd`
+// -----------
+// Gate approval is authoritative but costs about 530ms per project — twelve
+// seconds for the fleet, on a screen meant to be glanced at. The pipeline
+// position computed from verdict files alone reports `awaiting-gate`
+// conservatively, which for a decisions queue errs toward "this may need you".
+// That is the right direction to be wrong in here, and it is stated rather than
+// hidden.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readVerdicts } from './verdicts.mjs';
+
+/** A project's state, or an honest account of why it is unknown. */
+export function projectRow(entry, { now = Date.now() } = {}) {
+  const base = { slug: entry.slug, path: entry.path, archetype: entry.archetype || null, description: entry.description || '' };
+
+  if (!entry.path || !fs.existsSync(entry.path)) {
+    return { ...base, unread: 'the project directory no longer exists' };
+  }
+  const gc = path.join(entry.path, '.great_cto');
+  if (!fs.existsSync(gc)) {
+    return { ...base, unread: 'not initialised — no .great_cto here' };
+  }
+
+  let verdicts;
+  try {
+    verdicts = readVerdicts(entry.path);
+  } catch (e) {
+    return { ...base, unread: `verdicts could not be read: ${e.message}` };
+  }
+  if (!Array.isArray(verdicts)) {
+    return { ...base, unread: 'verdicts could not be read' };
+  }
+
+  const withTs = verdicts.filter((v) => v.ts && !Number.isNaN(Date.parse(v.ts)));
+  const newest = withTs.length
+    ? Math.max(...withTs.map((v) => Date.parse(v.ts)))
+    : null;
+
+  // Spend is only claimed over verdicts that carry a cost. A verdict without one
+  // is not zero spend — it is spend nobody recorded, and adding it as zero is how
+  // a dashboard reports a number smaller than the invoice.
+  const priced = verdicts.filter((v) => typeof v.cost_usd === 'number');
+  const spend = priced.reduce((a, v) => a + v.cost_usd, 0);
+
+  const last = verdicts.length
+    ? verdicts.reduce((a, b) => (Date.parse(b.ts || 0) > Date.parse(a.ts || 0) ? b : a))
+    : null;
+
+  return {
+    ...base,
+    stages: verdicts.length,
+    lastAgent: last?.agent || null,
+    lastVerdict: last?.verdict || null,
+    lastMovedAt: newest ? new Date(newest).toISOString() : null,
+    idleMs: newest ? now - newest : null,
+    spend: priced.length ? Number(spend.toFixed(4)) : null,
+    spendKnownFor: priced.length,
+    spendUnknownFor: verdicts.length - priced.length,
+    needsYou: needsAttention(last),
+  };
+}
+
+/**
+ * Does this project look like it is waiting on a human?
+ *
+ * A blocking verdict is unambiguous. Everything else is a guess made without
+ * reading gate state, so it is reported as a reason rather than a flag — the row
+ * says "security-officer returned REJECTED", not a red dot the reader has to
+ * interpret.
+ */
+export function needsAttention(last) {
+  if (!last) return null;
+  const v = String(last.verdict || '').toUpperCase();
+  if (['BLOCKED', 'FAIL', 'FAILED', 'REJECTED'].includes(v)) {
+    return `${last.agent || 'a stage'} returned ${v}`;
+  }
+  return null;
+}
+
+/**
+ * The fleet.
+ *
+ * `registryUnread` carries a broken projects.json up to the reader: an
+ * unreadable registry used to render as a board with no projects, which is the
+ * same lie one level further out.
+ */
+export function portfolio(registry, { now = Date.now(), maxProjects = 100 } = {}) {
+  if (!registry || registry.unread) {
+    return { registryUnread: registry?.unread || 'the project registry could not be read', projects: [] };
+  }
+  const entries = (registry.projects || []).slice(0, maxProjects);
+  const projects = entries.map((e) => projectRow(e, { now }));
+
+  const readable = projects.filter((p) => !p.unread);
+  return {
+    projects,
+    total: projects.length,
+    unreadable: projects.length - readable.length,
+    // Totals are over what could be read, and say so. A sum that silently
+    // excludes four projects is a different number from the one it claims to be.
+    spend: readable.some((p) => p.spend != null)
+      ? Number(readable.reduce((a, p) => a + (p.spend || 0), 0).toFixed(4))
+      : null,
+    spendCoveredProjects: readable.filter((p) => p.spend != null).length,
+    needsYou: readable.filter((p) => p.needsYou).length,
+  };
+}

package/board/packages/board/lib/projects.mjs

@@ -205,6 +205,37 @@ function getChangeTier(dir) {
   }
 }
 function autoRegisterProject(dir) {
+  // The home directory is never a project.
+  //
+  // `~/.great_cto/` is the GLOBAL store — cross-project verdicts, decisions,
+  // secrets — and it is shaped exactly like a project's own `.great_cto/`, same
+  // name and same contents. So the home directory reads as a project, and
+  // auto-registration kept adding it: deleted from the registry, it was back two
+  // minutes later, contributing 124 stages and $93 of $95 to a fleet view that
+  // has 22 real projects.
+  //
+  // Nothing downstream can tell these apart, because they are the same shape.
+  // The distinction is the location, so that is where it belongs.
+  //
+  // The installed plugin is not a project either, for the same reason and by the
+  // same mechanism: `~/.claude/plugins/cache/local/great_cto/2.95.0` ships a
+  // `.great_cto/` because it IS great_cto, so running the board from there
+  // registered the plugin's own copy as a twenty-third project — a version
+  // number in the switcher next to real work.
+  //
+  // Nor is a directory inside a project already registered. `packages/cli` ships
+  // its own `.great_cto/` because the published package carries one, so opening
+  // the board there added it as a separate project reading great_cto's beads —
+  // 228 tasks counted twice, under two names, in a fleet of seventeen.
+  try {
+    const resolved = path.resolve(dir);
+    if (resolved === path.resolve(os.homedir())) return null;
+    if (isInsideDir(path.join(os.homedir(), '.claude', 'plugins'), resolved)) return null;
+    const enclosing = readProjectsRegistry().projects
+      .find((e) => e.path && path.resolve(e.path) !== resolved && isInsideDir(path.resolve(e.path), resolved));
+    if (enclosing) return null;
+  } catch { /* if we cannot resolve it, fall through to the normal checks */ }
+
   const meta = readProjectMd(dir);
   if (!meta) return null;
   const reg = readProjectsRegistry();