great-cto 3.67.1 → 3.68.1

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

@@ -1,7 +1,7 @@
 {
   "name": "great-cto",
   "description": "You already have the agent. This is everything around it. great_cto runs Claude Code as a pipeline of 72 specialist agents \u2014 an independent model checks each stage before the next builds on it, spending caps refuse rather than warn, and three decisions stay yours: what gets built, how, and whether it ships.",
-  "version": "3.67.1",
+  "version": "3.68.1",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"
@@ -149,6 +149,11 @@
             "timeout": 5,
             "command": "_gd=\"$PWD\"; while [ -n \"$_gd\" ] && { [ \"$_gd\" = \"$HOME\" ] || [ ! -f \"$_gd/.great_cto/PROJECT.md\" ]; }; do _gd=\"${_gd%/*}\"; done; [ -n \"$_gd\" ] && cd \"$_gd\"; [ -n \"$GREAT_CTO_AGENT_BUDGET_FILE\" ] || exit 0; node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/agent-execution-budget.mjs\" pre; _budget_exit=$?; if [ $_budget_exit -ne 0 ]; then exit 2; fi",
             "statusMessage": "Checking shared agent execution budget..."
+          },
+          {
+            "type": "command",
+            "command": "_gd=\"$PWD\"; while [ -n \"$_gd\" ] && { [ \"$_gd\" = \"$HOME\" ] || [ ! -f \"$_gd/.great_cto/PROJECT.md\" ]; }; do _gd=\"${_gd%/*}\"; done; [ -n \"$_gd\" ] && cd \"$_gd\"; node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/graph-guard.mjs\" || true",
+            "timeout": 10
           }
         ]
       },

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

@@ -14,7 +14,6 @@
 
 import fs from 'node:fs';
 import { judgeFreshness } from '../../../scripts/lib/freshness.mjs';
-import { linkGraph } from '../../../scripts/lib/doc-links.mjs';
 import path from 'node:path';
 
 /**
@@ -130,6 +129,67 @@ const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', 'scre
 
 /** A cap, so a repository with thousands of markdown files cannot stall the board. */
 export const MAX_DOCS = 500;
+export const MAX_DOC_BYTES = 1024 * 1024;
+
+/** Root aliases are allowed; links inside a project are not read capabilities. */
+function safePath(root, rel) {
+  if (!rel || path.isAbsolute(rel) || rel.includes('\0') || rel.split(/[\\/]/).includes('..')) return null;
+  try {
+    const canonical = fs.realpathSync(root);
+    const abs = path.resolve(canonical, rel);
+    if (!abs.startsWith(canonical + path.sep)) return null;
+    let current = canonical;
+    for (const part of path.relative(canonical, abs).split(path.sep)) {
+      current = path.join(current, part);
+      if (fs.lstatSync(current).isSymbolicLink()) return null;
+    }
+    return abs;
+  } catch { return null; }
+}
+
+/** Bounded descriptor reads also refuse a path replaced between lookup and open. */
+export function readProjectFile(root, rel) {
+  let fd;
+  try {
+    const abs = safePath(root, rel);
+    if (!abs) return { state: 'unreadable', content: null };
+    const expected = fs.lstatSync(abs);
+    if (!expected.isFile()) return { state: 'unreadable', content: null };
+    if (expected.size > MAX_DOC_BYTES) return { state: 'too-large', content: null };
+    fd = fs.openSync(abs, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const before = fs.fstatSync(fd);
+    if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino
+      || safePath(root, rel) !== abs) return { state: 'unreadable', content: null };
+    if (before.size > MAX_DOC_BYTES) return { state: 'too-large', content: null };
+    const bytes = Buffer.alloc(Math.min(before.size + 1, MAX_DOC_BYTES + 1));
+    let count = 0, n;
+    while (count < bytes.length && (n = fs.readSync(fd, bytes, count, bytes.length - count, count))) count += n;
+    const after = fs.fstatSync(fd);
+    if (count > MAX_DOC_BYTES) return { state: 'too-large', content: null };
+    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs
+      || after.ctimeMs !== before.ctimeMs) return { state: 'unreadable', content: null };
+    return { state: 'readable', content: bytes.subarray(0, count).toString('utf8') };
+  } catch { return { state: 'unreadable', content: null }; }
+  finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+export function declaredStatus(text) {
+  let fence = null;
+  const head = String(text || '').slice(0, 8192).replace(/^\uFEFF/, '').split('\n').filter(line => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+      return false;
+    }
+    return !fence;
+  }).join('\n');
+  const fm = head.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const value = (fm ? fm[1].match(/^status:\s*(.*?)\s*$/im)?.[1] : null)
+    ?? head.match(/^(?:\*\*)?Status(?:\*\*)?:\s*(.*?)\s*$/im)?.[1];
+  const clean = value?.replace(/^["']|["']$/g, '').trim().toLowerCase();
+  return ['draft', 'accepted', 'superseded'].includes(clean) ? clean : null;
+}
 
 /**
  * The title an author gave a document.
@@ -138,8 +198,8 @@ export const MAX_DOCS = 500;
  * 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 { return titleFromText(String(read(absPath, 'utf8'))); }
+export function titleOf(absPath, { read } = {}) {
+  try { return titleFromText(read ? String(read(absPath, 'utf8')) : readProjectFile(path.dirname(absPath), path.basename(absPath)).content); }
   catch { return null; }
 }
 
@@ -155,11 +215,13 @@ const IS_TRANSLATED = /^docs[/\\][a-z]{2}(-[A-Z]{2})?[/\\]/;
 
 function walk(dir, root, out, depth = 0) {
   if (depth > 3 || out.length >= MAX_DOCS) return;
+  const safe = safePath(root, path.relative(root, dir));
+  if (!safe) return;
   let entries;
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  try { entries = fs.readdirSync(safe, { 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;
+    if (e.isSymbolicLink() || 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;
@@ -168,7 +230,7 @@ function walk(dir, root, out, depth = 0) {
     // and stood a machine-written summary in the index beside its own source.
     if (IS_COPY.test(e.name) || IS_TRANSLATED.test(path.relative(root, abs))) continue;
     let st;
-    try { st = fs.statSync(abs); } catch { continue; }
+    try { if (!safePath(root, path.relative(root, abs))) continue; st = fs.lstatSync(abs); if (!st.isFile()) continue; } catch { continue; }
     out.push({ abs, rel: path.relative(root, abs), size: st.size, modified: st.mtime.toISOString() });
   }
 }
@@ -333,13 +395,15 @@ function freshnessOf(text, nowMs = Date.now(), staleDays = 180) {
 }
 
 export function listDocs(root, { max = MAX_DOCS } = {}) {
+  try { root = fs.realpathSync(root); } catch { return { total: 0, truncated: false, groups: [], state: 'unreadable' }; }
   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 (!safePath(root, f)) continue;
+        const st = fs.lstatSync(abs);
         if (st.isFile()) found.push({ abs, rel: f, size: st.size, modified: st.mtime.toISOString() });
       } catch { /* absent */ }
     }
@@ -349,13 +413,6 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
   // the link graph is defined; anything outside it gets `null` — "not measured"
   // and "measured, and the answer is none" are different facts, and rendering
   // the first as the second is the substitution this whole board refuses.
-  let inboundBy = null;
-  try {
-    const g = linkGraph(path.join(root, 'docs'));
-    inboundBy = new Map();
-    for (const [k, v] of g.inbound) inboundBy.set(path.relative(root, k), v.length);
-  } catch { inboundBy = null; }
-
   const seen = new Set();
   const docs = [];
   for (const d of found) {
@@ -365,15 +422,17 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
     // 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 */ }
+    const read = readProjectFile(root, d.rel), text = read.content;
     docs.push({
       path: d.rel,
       name: path.basename(d.rel),
       title: (text !== null && titleFromText(text)) || path.basename(d.rel, '.md'),
       group: groupFor(d.rel, { text: text ?? '' }),
       size: d.size,
-      inbound: inboundBy ? (inboundBy.has(d.rel) ? inboundBy.get(d.rel) : null) : null,
+      inbound: null,
+      readState: read.state,
+      status: declaredStatus(text),
+      sourceRevision: null,
       modified: d.modified,
       // A modification time answers "when was this file last touched", which is
       // a different question from "is this still true". A typo fix rejuvenates a
@@ -382,6 +441,27 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
       // rule produced each — see scripts/lib/freshness.mjs.
       ...freshnessOf(text),
     });
+    // Kept only for this bounded index pass, never serialized into the listing.
+    docs.at(-1)._text = text;
+  }
+
+  const cited = new Map(docs.filter(d => d.path.startsWith('docs/')).map(d => [d.path, new Set()]));
+  const complete = docs.length < max && docs.every(d => d.readState === 'readable');
+  for (const d of docs) {
+    if (!cited.has(d.path) || d._text === null) continue;
+    const add = target => { if (target !== d.path) cited.get(target)?.add(d.path); };
+    for (const m of d._text.matchAll(/\]\(([^)#\s]+\.md)/g)) {
+      add(path.normalize(path.join(path.dirname(d.path), m[1])));
+      add(path.normalize(m[1].replace(/^\.\.\//, '')));
+      add(path.normalize(path.join('docs', m[1])));
+    }
+    for (const m of d._text.matchAll(/\bADR-(\d{3})\b/g)) {
+      for (const target of cited.keys()) if (path.basename(target).startsWith(`ADR-${m[1]}`)) add(target);
+    }
+  }
+  for (const d of docs) {
+    d.inbound = complete && cited.has(d.path) ? cited.get(d.path).size : null;
+    delete d._text;
   }
 
   const groups = DOC_GROUPS.map((g) => ({

package/board/packages/board/lib/knowledge.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { GROUPS, groupOf } from '../../../scripts/lib/system-map.mjs';
+import { readProjectFile, MAX_DOCS } from './docs.mjs';
+
+/** Legacy source-map projection, using the same bounded reads as Knowledge. */
+export function knowledgeMap(root) {
+  const nodes = [], files = [], edges = new Map();
+  let visited = 0, partial = false;
+  const walk = (dir, ext, out, depth = 0) => {
+    if (depth > 3 || visited >= MAX_DOCS) { partial = true; return; }
+    let current = root;
+    try {
+      for (const part of dir.split(path.sep)) {
+        current = path.join(current, part);
+        if (fs.lstatSync(current).isSymbolicLink()) { partial = true; return; }
+      }
+      for (const e of fs.readdirSync(current, { withFileTypes: true })) {
+        if (visited >= MAX_DOCS) { partial = true; break; }
+        if (e.name.startsWith('.') || ['node_modules', 'dist', 'build', 'coverage', 'vendor', '_shared'].includes(e.name)) continue;
+        if (e.isSymbolicLink()) { partial = true; continue; }
+        const rel = path.join(dir, e.name);
+        if (e.isDirectory()) walk(rel, ext, out, depth + 1);
+        else if (e.isFile() && ext.some(x => e.name.endsWith(x))) {
+          visited++;
+          const read = readProjectFile(root, rel);
+          if (read.state === 'readable') out.push({ rel, text: read.content });
+          else partial = true;
+        }
+      }
+    } catch (e) { if (e.code !== 'ENOENT') partial = true; }
+  };
+  for (const g of GROUPS) {
+    const own = [];
+    for (const dir of g.dirs) walk(dir, g.ext, own);
+    files.push(...own);
+    if (own.length) nodes.push({ key: g.key, label: g.label, what: g.what, count: own.length });
+  }
+  for (const f of files.filter(f => /\.(mjs|ts)$/.test(f.rel))) {
+    const from = groupOf(f.rel);
+    for (const m of f.text.matchAll(/(?:^|\n)\s*import\s[^'"]*from\s+['"](\.[^'"]+)['"]/g)) {
+      const to = groupOf(path.join(path.dirname(f.rel), m[1]));
+      if (!to || from === to) continue;
+      const key = `${from}:${to}`;
+      edges.set(key, { from, to, count: (edges.get(key)?.count || 0) + 1 });
+    }
+  }
+  return { nodes, edges: [...edges.values()].sort((a, b) => b.count - a.count),
+    generatedAt: new Date().toISOString(), state: partial ? 'partial' : 'observed' };
+}

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

@@ -123,9 +123,16 @@ async function dispatch(req, res, url, cwd) {
 
   // These read models accept registered projects or the server's own root,
   // never an arbitrary HOME directory supplied as a query parameter.
-  const scopedProject = ['/api/skills', '/api/usage', '/api/outcomes'].includes(pathname)
+  const knowledgeRead = ['/api/docs', '/api/doc', '/api/docs/search'].includes(pathname);
+  const scopedProject = (knowledgeRead || ['/api/skills', '/api/usage', '/api/outcomes'].includes(pathname))
     ? scopedReadProject(cwd, serverCwd, requestedProject) : null;
 
+  if (knowledgeRead && req.method === 'GET' && !scopedProject) {
+    res.writeHead(404, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify({ error: 'Unknown project; documentation was not read', state: 'unavailable' }));
+    return true;
+  }
+
   // Existing synchronous projections may consume a completed snapshot, but
   // HTTP cold reads must await async I/O instead of freezing unrelated clients.
   const taskRead = ['/api/work', '/api/sse', '/api/tasks', '/api/metrics',
@@ -646,44 +653,48 @@ async function dispatch(req, res, url, cwd) {
   }
 
   if (pathname === '/api/docs' && req.method === 'GET') {
-    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    const c = scopedProject.path;
     try {
-      const [{ listDocs }, { systemMap, toMermaid, pipelineMermaid }] = await Promise.all([
-        import('./docs.mjs'), import('../../../scripts/lib/system-map.mjs'),
+      const [{ listDocs, readProjectFile }, { toMermaid, pipelineMermaid }, { knowledgeMap }] = await Promise.all([
+        import('./docs.mjs'), import('../../../scripts/lib/system-map.mjs'), import('./knowledge.mjs'),
       ]);
-      const map = systemMap(c);
+      const map = knowledgeMap(c);
       let pipeline = null;
-      try { pipeline = pipelineMermaid(fs.readFileSync(path.join(c, 'shared', 'pipeline.toml'), 'utf8')); } catch { /* not a great_cto project */ }
+      const pipelineSource = readProjectFile(c, 'shared/pipeline.toml');
+      if (pipelineSource.state === 'readable') pipeline = pipelineMermaid(pipelineSource.content);
       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) },
+        map: { ...map, mermaid: toMermaid(map) },
         pipeline,
       }));
-    } catch (e) {
+    } catch {
       res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: String(e.message || e) }));
+      res.end(JSON.stringify({ error: 'Documentation index is unavailable' }));
     }
     return true;
   }
 
   if (pathname === '/api/doc' && req.method === 'GET') {
-    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    const c = scopedProject.path;
     const rel = String(url.searchParams.get('path') || '');
     const abs = path.resolve(c, rel);
-    if (!rel || !abs.startsWith(path.resolve(c) + path.sep) || !abs.toLowerCase().endsWith('.md')) {
+    if (!rel || path.isAbsolute(rel) || rel.includes('\0') || rel.split(/[\\/]/).includes('..')
+      || !abs.startsWith(c + path.sep) || !abs.toLowerCase().endsWith('.md')) {
       res.writeHead(400, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: 'path must be a .md file inside the project' }));
       return true;
     }
     try {
-      const st = fs.statSync(abs);
-      if (!st.isFile() || st.size > 1024 * 1024) throw new Error('not a readable doc');
+      const { readProjectFile, declaredStatus } = await import('./docs.mjs');
+      const read = readProjectFile(c, rel);
+      if (read.state !== 'readable') throw new Error('not a readable doc');
       res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
-      res.end(JSON.stringify({ name: path.basename(abs), path: rel, content: fs.readFileSync(abs, 'utf8') }));
+      res.end(JSON.stringify({ name: path.basename(abs), path: rel, content: read.content,
+        status: declaredStatus(read.content), sourceRevision: null }));
     } catch {
       res.writeHead(404, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: 'doc not found: ' + rel }));
+      res.end(JSON.stringify({ error: 'Document is missing, unreadable or exceeds the size limit' }));
     }
     return true;
   }
@@ -2332,7 +2343,7 @@ async function dispatch(req, res, url, cwd) {
   //
   // GET /api/docs/search?q=...  ->  { q, matched, scanned, results[] }
   if (pathname === '/api/docs/search' && req.method === 'GET') {
-    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    const c = scopedProject.path;
     const q = (url.searchParams.get('q') || '').trim();
     if (q.length < 2) {
       res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -2340,7 +2351,7 @@ async function dispatch(req, res, url, cwd) {
       return true;
     }
     try {
-      const { listDocs } = await import('./docs.mjs');
+      const { listDocs, readProjectFile } = await import('./docs.mjs');
       const all = listDocs(c);
       const needle = q.toLowerCase();
       const results = [];
@@ -2348,9 +2359,9 @@ async function dispatch(req, res, url, cwd) {
       for (const g of (all.groups || [])) {
         for (const d of (g.docs || [])) {
           if (results.length >= 60) break;
-          let text;
-          try { text = fs.readFileSync(path.join(c, d.path), 'utf8'); scanned++; }
-          catch { unreadable++; continue; }   // counted, never silently skipped
+          const read = readProjectFile(c, d.path);
+          if (read.state !== 'readable') { unreadable++; continue; }
+          const text = read.content; scanned++;
           const lines = text.split('\n');
           const hits = [];
           for (let i = 0; i < lines.length && hits.length < 3; i++) {
@@ -2366,9 +2377,9 @@ async function dispatch(req, res, url, cwd) {
       // 187 files and "no results" over 3 that could be opened are different
       // facts, and only one of them means the phrase is not there.
       res.end(JSON.stringify({ q, matched: results.length, scanned, unreadable, results }));
-    } catch (e) {
+    } catch {
       res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: String(e.message || e) }));
+      res.end(JSON.stringify({ error: 'Documentation search is unavailable' }));
     }
     return true;
   }

package/board/packages/board/lib/work.mjs

@@ -16,17 +16,38 @@ const date = v => typeof v === 'string' && Number.isFinite(Date.parse(v)) ? v :
 const RUN_PHASE = { ready: 'accepted', 'awaiting-gate': 'needs_decision',
   'awaiting-release': 'needs_decision', blocked: 'blocked', 'manual-action': 'blocked' };
 
+/** Historical attempt observations only; no context, results or causal edges cross this boundary. */
+function executionAttempts(run) {
+  const short = v => text(v)?.slice(0, 128) || null;
+  const identity = v => text(v) && v.length <= 128 ? v : null;
+  const attempts = Array.isArray(run?.attempts) ? run.attempts : [];
+  const window = attempts.slice(-200);
+  const nodes = window.filter(a => a && identity(a.id) && short(a.role)).map(a => ({
+    runId: identity(run.id), attemptId: identity(a.id), role: short(a.role),
+    host: ['codex', 'claude-code'].includes(a.host) ? a.host : null,
+    number: Number.isInteger(a.number) && a.number > 0 ? a.number : null,
+    phase: short(a.phase), status: short(a.status), startedAt: date(a.startedAt), finishedAt: date(a.finishedAt),
+  }));
+  const truncated = attempts.length > 200;
+  return { state: nodes.length ? 'recorded' : 'unknown', nodes, topology: 'unknown', truncated,
+    partial: !run || truncated || nodes.length !== window.length,
+    reason: !run ? 'Stable attempt observations are unavailable without a single explicitly linked controlled run.'
+      : !nodes.length ? 'No usable attempt observations are recorded.' : null };
+}
+
 /** Recorded observations are not current-tree verification or gate authority. */
 function evidenceSections(entry) {
   const events = entry.inspector?.state === 'recorded' ? entry.inspector.events.length : 0;
+  const attempts = entry.execution?.nodes.length || 0;
   const verdicts = entry.evidence.filter(e => e.kind === 'verdict');
   const reported = verdicts.filter(e => e.verifierReported === true).length;
   const publication = entry.publication;
   const published = ['prepared', 'pushed', 'pr-linked'].includes(publication?.state);
   return [
-    { id: 'execution', label: 'Execution', state: events ? 'recorded' : 'unknown',
+    { id: 'execution', label: 'Execution', state: events || attempts ? 'recorded' : 'unknown',
       detail: events ? `${events} linked activity events in the bounded window. Liveness and task acceptance are not established.${entry.inspector.partial ? ' The activity window is incomplete.' : ''}`
-        : entry.inspector?.reason || 'No explicitly linked execution events are available.' },
+        : attempts ? `${attempts} historical attempt observations. Current verification, dependencies and task acceptance are not established.${entry.execution.partial ? ' Attempt observations are incomplete.' : ''}`
+          : entry.inspector?.reason || 'No explicitly linked execution events are available.' },
     { id: 'checks', label: 'Checks', state: verdicts.length ? 'recorded' : 'unknown',
       detail: verdicts.length ? `In this bounded view: ${verdicts.length} role verdict records; ${reported} verifier-success reports. Test counts and current input bindings are not available in this projection.`
         : 'No task-linked check records are available. Completed roles do not establish verification.' },
@@ -50,7 +71,7 @@ export function projectWork({ projectId, issues = [], codex = { state: 'absent',
     const phase = active ? 'working' : RUN_PHASE[r.status] || null;
     const pending = !!r.pending || ['awaiting-gate', 'awaiting-release'].includes(r.status);
     const canCopyResume = !terminal && !pending && !active && r.status === 'ready';
-    const updatedAt = (r.attempts || []).flatMap(a => [date(a.startedAt), date(a.finishedAt)])
+    const updatedAt = (Array.isArray(r.attempts) ? r.attempts : []).flatMap(a => [date(a?.startedAt), date(a?.finishedAt)])
       .filter(Boolean).sort((a, b) => Date.parse(b) - Date.parse(a))[0] || date(r.pending?.createdAt);
     entries.push({ key: `run:${r.id}`, kind: 'run', taskId: null, runId: r.id, issueIds: [],
       title: `Controlled run ${r.id}`, goal: null, acceptance: [], host: 'codex',
@@ -66,6 +87,7 @@ export function projectWork({ projectId, issues = [], codex = { state: 'absent',
       evidence: (r.rolesCompleted || []).map(role => ({ kind: 'recorded_role', label: role })),
       stage: text(r.active) || text(r.pending?.role) || (r.wave?.status === 'running' && Array.isArray(r.wave.roles) ? r.wave.roles.filter(role => typeof role === 'string').join(', ') : null),
       inspector: taskInspector([r.id], activity),
+      execution: executionAttempts(r),
       release: r.release ? { status: text(r.release.status), url: text(r.release.url), verifiedAt: date(r.release.verifiedAt) } : null,
     });
   }
@@ -106,6 +128,7 @@ export function projectWork({ projectId, issues = [], codex = { state: 'absent',
         label: `${e.role.slice(0, 80)}: ${text(e.verdict)?.slice(0, 80) || 'not recorded'}`, verifierReported: typeof e.verified === 'boolean' ? e.verified : null })),
       release: run?.release || null, revision: t.revision, metrics: t.metrics,
       inspector: taskInspector([...t.links.runs, ...t.links.sessions], activity),
+      execution: run?.execution || executionAttempts(null),
       publication: t.publication || null,
       publicationAllow: Array.isArray(t.authority?.writeScope) ? t.authority.writeScope.join(',') : '',
       publicationPreview: t.managed !== false && t.intent !== 'research' && t.phase === 'verified' && !owner && !t.decisions?.length,

package/board/packages/board/public/assets/admin-shell.css

@@ -0,0 +1,38 @@
+/* Approved task-first shell, using existing light/dark semantic tokens. */
+#nav-tablist .nav-item{width:100%;background:transparent;border:0;border-radius:5px;font-family:var(--sans,Geist,sans-serif);font-size:14px;text-align:left;min-height:44px;color:var(--text2);cursor:pointer}
+#nav-tablist .nav-item.active{background:var(--accent-soft);color:var(--text);font-weight:600}
+#nav-tablist .nav-item:hover{background:var(--bg-muted)}
+.nav-view-item{min-height:44px;font-size:14px}
+.work-task-row small{font-size:12px}
+.admin-page,.work-page{width:100%}.work-task-row>strong,.work-task-row>span{display:block}
+.admin-page-heading>.gate-btn{flex:0 0 auto;width:auto;padding:8px 14px;border:1px solid var(--border-strong);border-radius:5px;background:var(--bg-card);color:var(--text);cursor:pointer}
+#tools-nav[hidden],[hidden]{display:none!important}
+#admin-subnav{padding:12px 24px;border-bottom:1px solid var(--border);display:flex;gap:9px;flex-wrap:wrap;background:var(--bg-card)}
+.admin-subtab{border:1px solid var(--border-strong);color:var(--text2);background:transparent;padding:8px 13px;font:inherit;border-radius:5px;cursor:pointer}
+.admin-subtab[aria-pressed=true]{color:var(--text);background:var(--accent-soft);border-color:var(--accent)}
+.admin-page{padding:26px;max-width:1700px;margin:0 auto;font-size:14px}
+.admin-page-heading{display:flex;justify-content:space-between;align-items:center;gap:16px;margin-bottom:24px}
+.admin-page-heading h1{font-size:28px;margin:0 0 8px;letter-spacing:-.7px}
+.admin-page-heading p{color:var(--text2);margin:0;line-height:1.6}
+.admin-page h2{font-size:18px;margin:0 0 12px;line-height:1.5}
+.admin-notice{padding:14px 16px;margin:16px 0;line-height:1.7;border:1px solid var(--border-strong);border-radius:5px;background:var(--bg-muted);color:var(--text2);font-size:12px}
+.knowledge-layout{display:grid;grid-template-columns:280px minmax(0,1fr);border:1px solid var(--border-strong);border-radius:7px;background:var(--bg-card);min-height:600px;overflow:hidden}
+#knowledge-index{padding:18px 12px;border-right:1px solid var(--border);max-height:calc(100vh - 200px);overflow:auto}
+.admin-doc-search{font-size:12px;color:var(--text2);display:block;padding:0 6px}.admin-doc-search input{width:100%;box-sizing:border-box;margin-top:9px;padding:10px;border:1px solid var(--border-strong);border-radius:5px;background:var(--bg-page);font:inherit;color:var(--text)}
+#knowledge-index h2{font-size:12px;margin:23px 8px 9px;color:var(--text2)}
+.knowledge-file{display:block;text-align:left;width:100%;border:0;border-left:2px solid transparent;background:transparent;color:var(--text);font:inherit;font-size:13px;padding:10px;line-height:1.6;cursor:pointer;overflow-wrap:anywhere}
+.knowledge-file small{display:block;font-size:10px;color:var(--text2)}
+.knowledge-file:hover,.knowledge-file[aria-current=true]{background:var(--accent-soft);border-left-color:var(--accent)}
+#knowledge-document{min-width:0;padding:27px;line-height:1.7;overflow-wrap:anywhere}
+.admin-doc-heading{display:flex;justify-content:space-between;gap:15px;align-items:center}.admin-doc-heading h2{font-size:25px;margin:0}
+.admin-source{font-family:var(--mono,monospace);font-size:12px;color:var(--text2)}
+.admin-document{max-width:1000px}.admin-document p,.admin-document li{max-width:85ch}.admin-document pre{max-width:100%;overflow:auto}.admin-document table{display:block;max-width:100%;overflow:auto}
+.admin-diagram{padding:15px;border:1px solid var(--border-strong);border-radius:6px;background:var(--bg-muted);overflow:auto;margin:15px 0}.admin-diagram summary{cursor:pointer;font-size:12px}.knowledge-diagram{display:block;min-width:500px;width:100%;max-height:500px}.knowledge-diagram rect{fill:var(--bg-card);stroke:var(--border-strong)}.knowledge-diagram text{fill:var(--text);font:14px var(--sans,sans-serif)}.diagram-edges{stroke:var(--text2);stroke-width:1.5}
+.admin-metrics{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));border-block:1px solid var(--border-strong);margin:22px 0}.admin-metrics section{padding:22px 17px;border-right:1px solid var(--border)}.admin-metrics section:first-child{padding-left:0}.admin-metrics section:last-child{border:0}.admin-metrics h2{font-size:28px;overflow-wrap:anywhere;margin:0 0 8px}.admin-metrics p{font-size:13px;margin:0 0 8px}.admin-metrics small{color:var(--text2);font-size:11px;line-height:1.7;display:block}
+.admin-section-title{margin-top:30px!important}.admin-table-scroll{overflow:auto}.admin-table{border-collapse:collapse;width:100%;font-size:13px}.admin-table th,.admin-table td{padding:14px 10px;border-bottom:1px solid var(--border);text-align:left;overflow-wrap:anywhere}.admin-table th{font-size:12px;color:var(--text2);font-weight:500}
+.admin-compose{margin:16px 0 22px;padding:14px 16px;border:1px solid var(--border-strong);border-radius:6px;background:var(--bg-card)}.admin-compose summary{cursor:pointer;font-size:14px}.admin-compose form{margin-top:18px}
+.work-page{max-width:1700px!important;padding:26px!important;margin:0 auto;font-size:14px}.work-page>h1{font-size:28px;margin:0 0 10px}.work-meta{color:var(--text2);font-size:12px;line-height:1.7}.work-warning{border-left:3px solid var(--status-progress);padding:10px 14px;background:var(--bg-muted)}
+.work-cockpit{display:grid;grid-template-columns:280px minmax(0,1fr);background:var(--bg-card);border:1px solid var(--border-strong);border-radius:7px;overflow:hidden;min-height:450px}.work-task-list{border-right:1px solid var(--border);padding:0;background:var(--bg-muted)}.work-task-row{display:block;width:100%;text-align:left;border:0;border-bottom:1px solid var(--border);border-left:3px solid transparent;padding:18px 15px;background:transparent;color:var(--text);font:inherit;line-height:1.6;cursor:pointer;overflow-wrap:anywhere}.work-task-row[aria-current=true],.work-task-row[aria-current=page]{border-left-color:var(--accent);background:var(--accent-soft)}.work-task-row small{display:block;color:var(--text2)}.work-detail{min-width:0;padding:24px;overflow-wrap:anywhere}.work-card{border:0!important;margin:0!important;background:transparent!important;box-shadow:none!important}.work-card h2{font-size:23px;line-height:1.5;margin:0 0 15px}.work-card p{line-height:1.7}.work-card details{margin:15px 0;padding:12px;border:1px solid var(--border);border-radius:5px}.work-card pre{overflow:auto;max-width:100%}.work-filters{display:flex;gap:8px;flex-wrap:wrap;margin:15px 0 20px}.work-filter,.work-tab{padding:9px 13px;min-height:38px;border:1px solid var(--border-strong);border-radius:5px;background:var(--bg-card);color:var(--text2);font:inherit;cursor:pointer}.work-filter[aria-pressed=true]{color:var(--text);background:var(--accent-soft);border-color:var(--accent)}.work-tabs{display:flex;gap:10px;border-bottom:1px solid var(--border);margin-bottom:20px;flex-wrap:wrap}.work-tab{border:0;border-radius:0}.work-tab[aria-selected=true]{color:var(--text);border-bottom:2px solid var(--accent)}.work-execution{padding:15px;border:1px solid var(--border);border-radius:5px;background:var(--bg-muted)}.work-observation{margin:12px 0;padding:12px;border:1px solid var(--border);background:var(--bg-card);border-radius:5px;line-height:1.7}
+#panel-inbox .inbox-page{max-width:1500px}.nav-item:focus-visible,.admin-subtab:focus-visible,.knowledge-file:focus-visible,.work-filter:focus-visible,.work-tab:focus-visible,.work-task-row:focus-visible{outline:2px solid var(--focus-ring);outline-offset:2px}
+@media(max-width:1100px){.knowledge-layout,.work-cockpit{grid-template-columns:230px minmax(0,1fr)}.admin-metrics{grid-template-columns:1fr 1fr}.admin-metrics section{border-bottom:1px solid var(--border)}}
+@media(max-width:768px){.admin-page,.work-page{padding:16px!important}.knowledge-layout,.work-cockpit{grid-template-columns:minmax(0,1fr)}#knowledge-index{border-right:0;border-bottom:1px solid var(--border);max-height:270px}.work-task-list{border-right:0;border-bottom:1px solid var(--border);max-height:240px;overflow:auto}#knowledge-document,.work-detail{padding:18px}.admin-page-heading{align-items:flex-start}.admin-metrics section{padding:15px 10px}.admin-metrics h2{font-size:23px}.admin-doc-heading{align-items:flex-start;flex-direction:column}#admin-subnav{padding:10px 16px}.admin-table{min-width:530px}.work-tabs{gap:4px}}

package/board/packages/board/public/assets/admin-shell.js

@@ -0,0 +1,122 @@
+/* Task-first projection. Existing controller commands and authorization remain authoritative. */
+(() => {
+  const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  const aliases = { docs:'knowledge', usage:'insights/consumption', ledger:'insights/ledger', budgets:'insights/ledger', dashboard:'insights/ledger', fleet:'settings/executors', agents:'settings/executors', harness:'settings/runtime', skills:'settings/capabilities', history:'work/completed', inbox:'decisions', notifications:'settings/general', share:'settings/general' };
+  function route(input) {
+    if (/^(?:agents|fleet)\/[a-z0-9-]+$/i.test(input)) return {canonical:input,panel:'agents',primary:'settings'};
+    const canonical = aliases[input] || input;
+    const panels = { work:'work','work/completed':'history',decisions:'inbox',knowledge:'knowledge',insights:'admin-outcomes','insights/outcomes':'admin-outcomes','insights/consumption':'usage','insights/ledger':'budgets',settings:'agents','settings/executors':'agents','settings/runtime':'harness','settings/capabilities':'skills','settings/general':'settings' };
+    if (!panels[canonical]) return null;
+    return { canonical, panel:panels[canonical], primary:canonical.split('/')[0] };
+  }
+  function outcomes(snapshot) {
+    const tasks = (snapshot.entries || []).filter(e => e.kind === 'task');
+    const completed = tasks.filter(e => e.taskOutcome?.state === 'completed').length;
+    return {tasks:tasks.length,completed,unknown:tasks.length-completed,acceptanceRate:null,costPerAcceptedTask:null};
+  }
+  let generation=0, selectedDoc=null, selectedRoute='work', request=0, indexRequest=0;
+  const scope = () => new URLSearchParams(location.search).get('project') || '';
+  const scoped = path => path+(path.includes('?')?'&':'?')+'project='+encodeURIComponent(scope());
+  const panel = id => document.getElementById(id);
+  function current(seq, project) { return seq===generation && project===scope(); }
+  function reset() {
+    generation++; request++; selectedDoc=null;
+    for (const id of ['knowledge-index','knowledge-document','admin-outcomes-body']) if(panel(id)) panel(id).textContent='Loading selected project…';
+    if (selectedRoute==='knowledge') loadKnowledge();
+    if (selectedRoute==='insights'||selectedRoute==='insights/outcomes') loadTaskOutcomes();
+  }
+  async function loadTaskOutcomes() {
+    const seq=generation, project=scope(), ticket=++request, el=panel('admin-outcomes-body');
+    el.textContent='Reading task-linked outcomes…';
+    try {
+      const data=await api(scoped('/api/work'));
+      if (!current(seq,project)||ticket!==request) return;
+      if (!data || data.error || data.schemaVersion!==1) throw Error(data?.error || 'Task outcomes are unavailable.');
+      const d=outcomes(data);
+      el.innerHTML=`<p class="work-meta">Observed ${esc(data.observedAt)} · ${data.health==='current'?'Sources read':'Sources incomplete'} · Recorded task metadata, not a benchmark</p>
+        <div class="admin-metrics"><section><h2>${d.tasks}</h2><p>Tracked tasks</p><small>Legacy issues and standalone runs excluded</small></section><section><h2>${d.completed}</h2><p>Explicitly completed outcomes</p><small>Recorded completion, not an acceptance-rate estimate</small></section><section><h2>${d.unknown}</h2><p>No completed outcome recorded</p><small>Includes in-progress tasks; not a failure count</small></section><section><h2>Unavailable</h2><p>Cost per accepted task</p><small>Complete task-bound actual spend is not available</small></section></div>
+        <div class="admin-notice">Acceptance rate, time to acceptance and severe regressions are not measured by this projection. Role verdicts, closed issues and successful processes cannot supply those numbers.</div>
+        <h2 class="admin-section-title">Recorded work</h2><div class="admin-table-scroll"><table class="admin-table"><thead><tr><th>Task</th><th>Host</th><th>State</th><th>Outcome</th></tr></thead><tbody>${(data.entries||[]).filter(e=>e.kind==='task').slice(0,100).map(e=>`<tr><td>${esc(e.title)}</td><td>${esc(e.host||'Not linked')}</td><td>${esc(e.phase||'Unknown')}</td><td>${esc(e.taskOutcome?.state||'Not recorded')}</td></tr>`).join('')||'<tr><td colspan="4">No tracked task outcomes in the readable records.</td></tr>'}</tbody></table></div><p class="work-meta">All available tracked tasks, not a time-window cohort. Host quality comparisons require matched tasks, budgets and acceptance criteria.</p>`;
+    } catch(error) { if(current(seq,project)&&ticket===request) el.textContent='Outcomes could not be read: '+error.message; }
+  }
+  async function loadKnowledge() {
+    const seq=generation, project=scope(), ticket=++indexRequest;
+    request++; selectedDoc=null;
+    panel('knowledge-index').textContent='Reading project documents…';
+    try {
+      const data=await api(scoped('/api/docs'));
+      if (!current(seq,project)||ticket!==indexRequest) return;
+      if (!data || data.error || data.state==='unreadable' || !Array.isArray(data.groups)) throw Error(data?.error || 'Document index is unavailable.');
+      const unreadable=data.groups.flatMap(g=>g.docs).filter(d=>d.readState&&d.readState!=='readable').length;
+      panel('knowledge-index').innerHTML=`<label class="admin-doc-search">Find a document<input type="search" id="knowledge-search" placeholder="Filter document titles and paths"></label><p class="work-meta">${esc(data.total)} indexed${data.truncated?' · Index truncated':''}${unreadable?' · '+unreadable+' unreadable or oversized':''}</p>`+data.groups.map(g=>`<section><h2>${esc(g.label)}</h2>${g.docs.map(d=>`<button type="button" class="knowledge-file" data-doc-path="${esc(d.path)}" data-doc-search="${esc(d.title+' '+d.path)}">${esc(d.title)}<small>${esc(d.path)}${d.readState&&d.readState!=='readable'?' · '+esc(d.readState):''}</small></button>`).join('')}</section>`).join('');
+      panel('knowledge-search').addEventListener('input',e=>{const q=e.target.value.toLowerCase();panel('knowledge-index').querySelectorAll('[data-doc-search]').forEach(b=>b.hidden=!b.dataset.docSearch.toLowerCase().includes(q));});
+      panel('knowledge-index').querySelectorAll('[data-doc-path]').forEach(b=>b.addEventListener('click',()=>openDocument(b.dataset.docPath)));
+      panel('knowledge-document').innerHTML='<h2>Select a document</h2><p>Read existing project files with their source path. Document text is not an instruction to the board.</p><p class="work-meta">Architecture diagrams describe declared design, not running task state.</p>';
+    } catch(error) { if(current(seq,project)&&ticket===indexRequest) { panel('knowledge-index').textContent='Documents could not be read: '+error.message; panel('knowledge-document').textContent='No document from another project will be substituted.'; } }
+  }
+  async function openDocument(path) {
+    const seq=generation, project=scope(), docTicket=++request;
+    selectedDoc=path; panel('knowledge-document').textContent='Reading document…';
+    panel('knowledge-index').querySelectorAll('[data-doc-path]').forEach(b=>b.setAttribute('aria-current',String(b.dataset.docPath===path)));
+    try {
+      const data=await api(scoped('/api/doc?path='+encodeURIComponent(path)));
+      if (!current(seq,project)||docTicket!==request||selectedDoc!==path) return;
+      if (!data || data.error || typeof data.content!=='string') throw Error(data?.error || 'Document is unavailable.');
+      panel('knowledge-document').innerHTML=`<div class="admin-doc-heading"><h2>${esc(data.name)}</h2><span class="work-meta">Read-only</span></div><p class="admin-source">${esc(data.path)}</p><div class="admin-notice">Source revision: ${esc(data.sourceRevision||'Not recorded')} · Document status: ${esc(data.status||'Not declared')}<br>Declared status is not a verification verdict. Original document language is preserved.</div><div class="md admin-document">${mdToHtml(data.content)}</div>`;
+      panel('knowledge-document').querySelectorAll('pre code.language-mermaid').forEach(code=>{
+        const source=code.textContent, result=window.GctoDiagram.render(source), section=document.createElement('section');section.className='admin-diagram';
+        section.innerHTML=`<p class="work-meta">Architecture / declared diagram, not live execution</p>${result.state==='rendered'?result.html:`<p>${esc(result.reason)}</p>`}<details><summary>Mermaid source</summary><pre></pre></details>`;
+        section.querySelector('pre').textContent=source;code.parentElement.replaceWith(section);
+      });
+      // Links remain project documents or external navigation, never commands.
+      panel('knowledge-document').querySelectorAll('a[href]').forEach(a=>{
+        const href=a.getAttribute('href');
+        if (/^https?:\/\//i.test(href)) {a.target='_blank';a.rel='noopener noreferrer';}
+        else if(!href.startsWith('#')) {a.removeAttribute('href');a.title='Open this relative document from the project index.';}
+      });
+    } catch(error) {if(current(seq,project)&&docTicket===request) panel('knowledge-document').textContent='Document could not be read: '+error.message;}
+  }
+  function setup() {
+    const nav=panel('nav-tablist'), existing={};
+    document.querySelectorAll('.nav-item[data-tab]').forEach(n=>existing[n.dataset.tab]=n.querySelector('svg')?.outerHTML||'');
+    nav.innerHTML=['work','decisions','knowledge','insights','settings'].map(key=>`<button type="button" class="nav-item${key==='work'?' active':''}" role="tab" aria-selected="${key==='work'}" data-tab="${key}" tabindex="0" onkeydown="navTabKeydown(event,this)">${existing[key]||existing[key==='knowledge'?'skills':key==='insights'?'usage':'harness']||''}<span class="nav-label">${key[0].toUpperCase()+key.slice(1)}</span>${key==='decisions'?'<span class="count" id="nav-inbox-count">0</span>':''}</button>`).join('');
+    nav.querySelectorAll('[data-tab]').forEach(n=>n.addEventListener('click',()=>window.switchTab(n.dataset.tab)));
+    const tools=panel('tools-nav');tools.hidden=true;
+    const workspace=document.querySelector('.workspace');
+    const bar=document.createElement('div');bar.id='admin-subnav';bar.hidden=true;workspace.querySelector('.topbar').after(bar);
+    const knowledge=document.createElement('div');knowledge.className='panel';knowledge.id='panel-knowledge';knowledge.setAttribute('role','tabpanel');knowledge.innerHTML='<div class="admin-page"><header class="admin-page-heading"><div><h1>Knowledge</h1><p>Project documents and architecture. Git files remain the source.</p></div><button type="button" class="gate-btn" id="knowledge-reload">Reload</button></header><div class="knowledge-layout"><aside id="knowledge-index" aria-label="Project documents"></aside><article id="knowledge-document" aria-live="polite"></article></div></div>';workspace.append(knowledge);
+    panel('knowledge-reload').addEventListener('click',()=>{generation++;loadKnowledge();});
+    const insights=document.createElement('div');insights.id='panel-admin-outcomes';insights.className='panel';insights.setAttribute('role','tabpanel');insights.innerHTML='<div class="admin-page"><header class="admin-page-heading"><div><h1>Insights</h1><p>Recorded outcomes are separate from token consumption.</p></div><button type="button" class="gate-btn" id="outcomes-reload">Reload</button></header><div id="admin-outcomes-body" aria-live="polite"></div></div>';workspace.append(insights);
+    panel('outcomes-reload').addEventListener('click',loadTaskOutcomes);
+    const original=window.switchTab;
+    window.switchTab=function(id,el){
+      const agentLink=String(id).match(/^(?:agents|fleet)\/([a-z0-9-]+)$/i);
+      if(agentLink) {
+        window.switchTab('settings/executors');history.replaceState(null,'','#agents/'+agentLink[1]);
+        const expected=location.hash, project=scope();
+        const open=(n)=>{if(location.hash!==expected||scope()!==project)return;if(typeof currentProject==='string'&&currentProject){openAgentDrawer(agentLink[1],{fromHash:true});}else if(n<50)setTimeout(()=>open(n+1),100);};
+        open(0);return;
+      }
+      const r=route(id);
+      if(!r) {bar.hidden=true;return original(id,el);}
+      selectedRoute=r.canonical;
+      const old={inbox:'decisions',budgets:'ledger',agents:'fleet','admin-outcomes':'admin-outcomes',knowledge:'knowledge'}[r.panel]||r.panel;
+      original(old); // Keep established loaders and mutation guards.
+      document.querySelectorAll('.nav-item[data-tab]').forEach(n=>{const active=n.closest('#nav-tablist')&&n.dataset.tab===r.primary;n.classList.toggle('active',!!active);n.setAttribute('aria-selected',String(!!active));});
+      panel('crumb-here').textContent=r.primary[0].toUpperCase()+r.primary.slice(1);
+      const items=r.primary==='settings'?[['settings/executors','Executors'],['settings/runtime','Runtime'],['settings/capabilities','Capabilities'],['settings/general','General']]:r.primary==='insights'?[['insights/outcomes','Outcomes'],['insights/consumption','Consumption'],['insights/ledger','Ledger & budgets']]:[];
+      bar.hidden=!items.length;bar.innerHTML=items.map(([key,label])=>`<button type="button" class="admin-subtab" data-route="${key}" aria-pressed="${r.canonical===key||(r.canonical===r.primary&&key===items[0][0])}">${label}</button>`).join('');
+      bar.querySelectorAll('[data-route]').forEach(b=>b.onclick=()=>window.switchTab(b.dataset.route));
+      history.replaceState(null,'','#/'+r.canonical);
+      if(r.primary==='knowledge')loadKnowledge();
+      if(r.panel==='admin-outcomes')loadTaskOutcomes();
+      // Restore a working route after projection errors; an error is not an empty list.
+    };
+    const composer=panel('work-compose');
+    const disclosure=document.createElement('details');disclosure.className='admin-compose';const summary=document.createElement('summary');summary.textContent='New task · prepare launch command';disclosure.append(summary);composer.before(disclosure);disclosure.append(composer);
+    composer.querySelector('button[type="submit"]').textContent='Copy launch command';
+    window.switchTab((location.hash||'#/work').replace(/^#\/?/,''));
+  }
+  window.GctoAdmin={route,outcomes,reset,openDocument};
+  if(typeof document!=='undefined') setup();
+})();

package/board/packages/board/public/assets/diagram-view.js

@@ -0,0 +1,42 @@
+/* Bounded, non-executable Mermaid flowchart subset. Other syntax stays source. */
+(() => {
+  const esc = s => String(s).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  function render(source) {
+    const unsupported = { state: 'unsupported', html: '', reason: 'This diagram syntax is not supported by the bounded viewer. Read the Mermaid source below.' };
+    if (typeof source !== 'string' || source.length > 20000) return unsupported;
+    const lines = source.split(/\n|;/).map(s => s.trim()).filter(s => s && !s.startsWith('%%'));
+    if (!/^(?:flowchart|graph)\s+LR$/.test(lines.shift() || '')) return unsupported;
+    const nodes = new Map(), edges = [];
+    const node = part => {
+      const m = part.trim().match(/^([A-Za-z_][\w-]*)(?:\[([^\]\n]{1,120})\])?$/);
+      if (!m) throw Error('unsupported node');
+      if (m[2] !== undefined || !nodes.has(m[1])) nodes.set(m[1], (m[2] || m[1]).replace(/^"(.*)"$/, '$1'));
+      if (nodes.size > 40) throw Error('node bound'); return m[1];
+    };
+    try {
+      for (const line of lines) {
+        const parts = line.split(/\s*-->\s*/);
+        if (parts.length > 8) return unsupported;
+        const ids = parts.map(node);
+        for (let i = 1; i < ids.length; i++) edges.push([ids[i-1], ids[i]]);
+        if (edges.length > 80) return unsupported;
+      }
+      if (!nodes.size) return unsupported;
+      const level = new Map([...nodes.keys()].map(id => [id, 0]));
+      let changed = false;
+      for (let i = 0; i < nodes.size; i++) {
+        changed = false;
+        for (const [a,b] of edges) if (level.get(b) <= level.get(a)) { level.set(b, level.get(a)+1); changed = true; }
+        if (!changed) break;
+      }
+      if (changed) return unsupported; // Cyclic diagrams need a full layout engine.
+      const lanes = new Map(), positions = new Map();
+      for (const id of nodes.keys()) { const l = level.get(id), row = lanes.get(l) || 0; lanes.set(l,row+1); positions.set(id,{x:25+l*220,y:35+row*100}); }
+      const width = 50+(Math.max(...level.values())+1)*220, height = 55+Math.max(...lanes.values())*100;
+      const paths = edges.map(([a,b]) => { const p=positions.get(a),q=positions.get(b);return `<path d="M${p.x+180} ${p.y+28} C${p.x+205} ${p.y+28},${q.x-25} ${q.y+28},${q.x} ${q.y+28} M${q.x-6} ${q.y+23} L${q.x} ${q.y+28} L${q.x-6} ${q.y+33}"/>`; }).join('');
+      const boxes = [...nodes].map(([id,label]) => {const p=positions.get(id);return `<g><rect x="${p.x}" y="${p.y}" width="180" height="56" rx="5"/><text x="${p.x+90}" y="${p.y+33}" text-anchor="middle">${esc(label.length > 24 ? label.slice(0,23)+'…' : label)}</text><title>${esc(label)}</title></g>`;}).join('');
+      return {state:'rendered',html:`<svg class="knowledge-diagram" viewBox="0 0 ${width} ${height}" role="img" aria-label="Declared diagram, not live execution"><g class="diagram-edges" fill="none">${paths}</g>${boxes}</svg>`};
+    } catch { return unsupported; }
+  }
+  window.GctoDiagram = { render };
+})();

package/board/packages/board/public/assets/work-view.js

@@ -57,6 +57,53 @@
         + (e.durationMs !== null ? ` · ${esc(e.durationMs)} ms` : '') + '</li>').join('') + '</ol>' : '')
       + '</details>';
   }
+  const categories = [['active', 'All active'], ['attention', 'Needs attention'], ['running', 'Running'], ['queued', 'Queued'], ['completed', 'Completed']];
+  function inCategory(entry, category) {
+    if (category === 'completed') return entry.terminal;
+    if (entry.terminal) return false;
+    if (category === 'attention') return (entry.decisions || []).length > 0 || entry.nativeState === 'blocked' || ['needs_decision', 'blocked', 'unknown'].includes(entry.phase);
+    if (category === 'running') return ['working', 'publishing'].includes(entry.phase);
+    if (category === 'queued') return entry.phase === 'accepted';
+    return true;
+  }
+  function cockpitEntries(data, category, search) {
+    return data.entries.filter(e => inCategory(e, category) && (!search || `${e.title} ${e.key}`.toLowerCase().includes(search.toLowerCase())));
+  }
+  function renderExecution(entry) {
+    const roles = Array.isArray(entry.evidence) ? entry.evidence : [];
+    const execution = entry.execution, nodes = Array.isArray(execution?.nodes) ? execution.nodes.slice(0, 200) : [];
+    return '<section class="work-execution"><h3>Recorded observations</h3>'
+      + '<p>Dependencies not recorded. This is an observation list, not an inferred execution graph. Event order does not establish dependencies.</p>'
+      + `<p>Recorded stage: ${esc(entry.stage || 'not recorded')}</p>`
+      + (execution?.reason ? `<p>${esc(execution.reason)}</p>` : '')
+      + (execution?.truncated ? '<p class="work-warning">Showing the latest 200 recorded attempts; earlier observations are truncated.</p>' : execution?.partial ? '<p class="work-warning">Attempt observations are incomplete.</p>' : '')
+      + (nodes.length ? '<ul class="work-observations" aria-label="Recorded execution attempts">' + nodes.map(n => `<li class="work-observation" data-attempt-id="${esc(n.attemptId)}"><strong>${esc(n.role)} · attempt ${esc(n.number || 'unknown')}</strong>`
+        + `<p>${esc(n.host || 'Host not recorded')} · phase: ${esc(n.phase || 'not recorded')}</p><p>Controller recorded status: ${esc(n.status || 'unknown')}; not current verification or acceptance.</p>`
+        + `<p>Run: ${esc(n.runId)} · Attempt: ${esc(n.attemptId)}</p><p>Started: ${esc(n.startedAt || 'not recorded')} · Finished: ${esc(n.finishedAt || 'not recorded')}</p></li>`).join('') + '</ul>' : '')
+      + (roles.length ? '<ul class="work-observations">' + roles.map(role => `<li class="work-observation">${esc(role.label)} · recorded role observation; acceptance is not inferred</li>`).join('') + '</ul>' : '<p>No role observations recorded.</p>')
+      + (entry.inspector ? renderInspector(entry.inspector).replace('<details ', '<details open ') : '<p>Linked activity unavailable. Absence of events is not proof of inactivity.</p>')
+      + '</section>';
+  }
+  function renderCockpit(data, options = {}) {
+    const category = categories.some(([key]) => key === options.category) ? options.category : 'active';
+    const tab = ['overview', 'execution', 'evidence'].includes(options.tab) ? options.tab : 'overview';
+    const rows = cockpitEntries(data, category, options.search || '');
+    const selected = rows.find(e => e.key === options.selectedKey) || rows[0];
+    const warnings = data.sources.filter(s => ['degraded', 'unavailable'].includes(s.health));
+    const feedback = warnings.map(s => `<p class="work-warning">${esc(s.id)}: ${esc(s.reason || s.health)}</p>`).join('');
+    const observed = `<p class="work-meta">Observed ${esc(data.observedAt)} · ${data.health === 'current' ? 'Sources read' : 'Sources incomplete'}</p>`;
+    const toolbar = '<div class="work-filters" role="group" aria-label="Task status filters">' + categories.map(([key, label]) => `<button type="button" class="work-filter" data-work-filter="${key}" aria-pressed="${category === key}">${label} <span>${cockpitEntries(data, key, options.search || '').length}</span></button>`).join('') + '</div>';
+    if (!selected) return toolbar + observed + feedback + `<p>${warnings.length || data.health !== 'current' ? 'No readable entries match this view; sources are incomplete.' : options.search ? 'No entries match the search.' : 'No work records match this filter.'}</p>`;
+    const list = '<div class="work-task-list" role="group" aria-label="Project tasks">' + rows.map(e => `<button type="button" class="work-task-row" data-work-select="${esc(e.key)}" aria-current="${e.key === selected.key}"><strong>${esc(e.title)}</strong><span>${esc(phaseLabel(e))}</span><small>${esc(e.host || 'Host not linked')} · ${esc(e.stage || 'Stage not recorded')}</small></button>`).join('') + '</div>';
+    const tabs = '<div class="work-tabs" role="tablist" aria-label="Selected task">' + ['overview', 'execution', 'evidence'].map(name => `<button type="button" class="work-tab" id="work-tab-${name}" data-work-tab="${name}" role="tab" aria-selected="${tab === name}" aria-controls="work-detail-panel" tabindex="${tab === name ? 0 : -1}">${name[0].toUpperCase() + name.slice(1)}</button>`).join('') + '</div>';
+    // Only the selected Overview owns mutation controls; observation tabs cannot duplicate them.
+    const detail = tab === 'execution' ? renderExecution(selected) : tab === 'evidence'
+      ? (Array.isArray(selected.evidenceSections) && selected.evidenceSections.length ? renderEvidence(selected.evidenceSections).replace('<details ', '<details open ') : '<p>Evidence unavailable. No verification or acceptance is inferred.</p>')
+      : render({ ...data, sources: [], sessions: [], entries: [{ ...selected, inspector: null, evidenceSections: null }] }, selected.terminal);
+    return toolbar + (tab === 'overview' ? '' : observed) + feedback + '<p class="work-meta">Running means host activity was recorded; current liveness is not measured. Closed records do not by themselves prove acceptance.</p>'
+      + `<div class="work-cockpit">${list}<section class="work-detail" aria-label="Selected task details">${tabs}<div id="work-detail-panel" role="tabpanel" aria-labelledby="work-tab-${tab}" tabindex="0">${detail}</div></section></div>`
+      + (data.sessions.length ? `<details><summary>Claude sessions (${data.sessions.length}) · task linkage not recorded</summary>${data.sessions.map(s => `<p>${esc(s.session)} · ${esc(s.state)} · ${esc(s.reason || '')}</p>`).join('')}</details>` : '');
+  }
   function renderEvidence(sections) {
     if (!Array.isArray(sections)) return '';
     return '<details data-work-detail="evidence"><summary>Task evidence · read-only</summary>'
@@ -105,7 +152,7 @@
       status('Draft PR publication recorded. Merge and release remain separate decisions.'); await refresh();
     } catch (error) { if (project === config.project()) { status(error.message); await refresh(); } }
   }
-  let config, snapshot, generation = 0, filter = '';
+  let config, snapshot, generation = 0, filter = '', selectedKey = null, category = 'active', tab = 'overview';
   const status = message => { document.getElementById('work-feedback').textContent = message; };
   async function refresh() {
     const seq = ++generation, project = config.project();
@@ -127,14 +174,18 @@
     const expanded = [...document.querySelectorAll('.work-card details[open]')].map(d => `${d.closest('[data-entry-key]').dataset.entryKey}:${d.dataset.workDetail}`);
     const focused = document.activeElement;
     const focusKey = focused?.dataset?.workKey, focusAction = focused?.dataset?.workAction;
-    document.getElementById('work-list').innerHTML = render(snapshot, false, filter);
+    const focusSelect = focused?.dataset?.workSelect, focusFilter = focused?.dataset?.workFilter, focusTab = focused?.dataset?.workTab;
+    document.getElementById('work-list').innerHTML = renderCockpit(snapshot, { search: filter, selectedKey, category, tab });
     document.getElementById('history-list').innerHTML = render(snapshot, true, filter);
     for (const card of document.querySelectorAll('[data-entry-key]')) for (const detail of card.querySelectorAll('details'))
       if (expanded.includes(`${card.dataset.entryKey}:${detail.dataset.workDetail}`)) detail.open = true;
     if (focusKey) [...document.querySelectorAll('[data-work-key]')].find(b => b.dataset.workKey === focusKey && b.dataset.workAction === focusAction)?.focus();
+    else if (focusSelect) [...document.querySelectorAll('[data-work-select]')].find(b => b.dataset.workSelect === focusSelect)?.focus();
+    else if (focusFilter) [...document.querySelectorAll('[data-work-filter]')].find(b => b.dataset.workFilter === focusFilter)?.focus();
+    else if (focusTab) [...document.querySelectorAll('[data-work-tab]')].find(b => b.dataset.workTab === focusTab)?.focus();
   }
   function reset() {
-    generation++; snapshot = null; previews.clear(); status('');
+    generation++; snapshot = null; previews.clear(); selectedKey = null; category = 'active'; tab = 'overview'; filter = ''; status('');
     for (const id of ['work-list', 'history-list']) document.getElementById(id).textContent = 'Loading project work…';
     refresh();
   }
@@ -156,7 +207,17 @@
       document.getElementById('work-command').textContent = ''; status('');
     });
     for (const id of ['work-list', 'history-list']) document.getElementById(id).addEventListener('click', event => {
-      const button = event.target.closest('[data-work-action]'); if (!button || !snapshot) return;
+      if (!snapshot) return;
+      const button = event.target.closest('[data-work-action]');
+      if (!button?.dataset.workAction) {
+        const selection = event.target.closest('[data-work-select]');
+        const filterButton = event.target.closest('[data-work-filter]');
+        const tabButton = event.target.closest('[data-work-tab]');
+        if (selection?.dataset.workSelect && snapshot.entries.some(e => e.key === selection.dataset.workSelect)) { selectedKey = selection.dataset.workSelect; tab = 'overview'; paint(); }
+        else if (categories.some(([key]) => key === filterButton?.dataset.workFilter)) { category = filterButton.dataset.workFilter; selectedKey = null; tab = 'overview'; paint(); }
+        else if (['overview', 'execution', 'evidence'].includes(tabButton?.dataset.workTab)) { tab = tabButton.dataset.workTab; paint(); }
+        return;
+      }
       const entry = snapshot.entries.find(e => e.key === button.dataset.workKey);
       if (button.dataset.workAction === 'preview_publication' && entry?.publicationPreview) { previewPublication(entry); return; }
       if (button.dataset.workAction === 'publish_publication' && entry?.publicationPreview) { publish(entry, button); return; }
@@ -165,7 +226,17 @@
       if (action.action === 'copy_resume' || action.action === 'copy_approve') copy(entry.command);
       else options.openIssue(entry.issueIds[0], action.action === 'review_decision');
     });
+    document.getElementById('work-list').addEventListener('keydown', event => {
+      const button = event.target.closest('[data-work-tab]');
+      if (!button || !['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;
+      const tabs = ['overview', 'execution', 'evidence'], current = tabs.indexOf(button.dataset.workTab);
+      if (current < 0) return;
+      event.preventDefault();
+      tab = event.key === 'Home' ? tabs[0] : event.key === 'End' ? tabs[2] : tabs[(current + (event.key === 'ArrowRight' ? 1 : 2)) % 3];
+      paint();
+      [...document.querySelectorAll('[data-work-tab]')].find(b => b.dataset.workTab === tab)?.focus();
+    });
     setInterval(() => { if (!document.hidden && options.visible()) refresh(); }, 10000);
   }
-  window.GctoWork = { bind, refresh, reset, render, commandFor, publicationCommand, search(value) { filter = value; paint(); } };
+  window.GctoWork = { bind, refresh, reset, render, renderCockpit, commandFor, publicationCommand, getSnapshot() { return snapshot; }, showCompleted() { category = 'completed'; selectedKey = null; tab = 'overview'; paint(); }, search(value) { filter = value; paint(); } };
 })();

package/board/packages/board/public/index.html

@@ -24,6 +24,7 @@
 <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16.png" />
 <link rel="shortcut icon" href="/assets/favicon.ico" />
 <link href="/assets/fonts/fonts.css" rel="stylesheet" />
+<link href="/assets/admin-shell.css" rel="stylesheet" />
 <script src="/assets/vendor/marked.min.js"></script>
 <script src="/assets/vendor/purify.min.js"></script>
 <style>
@@ -6176,6 +6177,7 @@ let usageData = null;
 let _usageTimer = null;
 let _usageRequest = 0;
 function resetProjectUsage() {
+  if (typeof window !== 'undefined') window.GctoAdmin?.reset();
   clearTimeout(_usageTimer); clearTimeout(_outcomesTimer);
   ++_usageRequest; ++_outcomesRequest;
   usageData = null;
@@ -9407,6 +9409,7 @@ function navTabKeydown(event, el) {
 const LEGACY_ROUTES = { inbox: 'decisions', budgets: 'ledger', dashboard: 'ledger', agents: 'fleet', notifications: 'settings', share: 'settings' };
 function routeFromHash() {
   const h = (location.hash || '').replace(/^#\/?/, '');
+  if (window.GctoAdmin?.route(h)) return h;
   if (!h || h.startsWith('agents/')) return null;
   // #/fleet/<slug>: open the agent in place (DESIGN §2 deep link).
   const m = h.match(/^fleet\/([a-z0-9-]+)$/i);
@@ -10544,5 +10547,7 @@ const _costLbl = document.getElementById('mp-cost-label');
 if (_costLbl) _costLbl.textContent = `Cost · last ${periodLabel(currentPeriod)}`;
 </script>
 
+<script src="/assets/diagram-view.js"></script>
+<script src="/assets/admin-shell.js"></script>
 </body>
 </html>

package/board/scripts/lib/receipt.mjs

@@ -29,7 +29,8 @@ import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import * as fsModule from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const sha = (s) => createHash('sha256').update(String(s)).digest('hex');
 
@@ -351,12 +352,23 @@ export function describeDrift(cmp, { max = 10 } = {}) {
 export const APPROVING_AGENTS = Object.freeze(['code-reviewer', 'security-officer', 'qa-engineer']);
 const APPROVING_VERDICTS = new Set(['APPROVED', 'PASS', 'PASSED']);
 
-export function latestApproval(cwd = process.cwd(), { agents = APPROVING_AGENTS, read = readFileSync } = {}) {
+/** Same state location as log-verdict.sh; the candidate bytes stay in cwd. */
+export function verdictStateDir(cwd = process.cwd(), env = process.env) {
+  if (env.GREAT_CTO_DIR) return resolve(cwd, env.GREAT_CTO_DIR);
+  const common = git(['rev-parse', '--git-common-dir'], cwd)?.trim();
+  const gitdir = git(['rev-parse', '--git-dir'], cwd)?.trim();
+  if (common && gitdir && resolve(cwd, common) !== resolve(cwd, gitdir)) {
+    return join(dirname(resolve(cwd, common)), '.great_cto');
+  }
+  return join(cwd, '.great_cto');
+}
+
+export function latestApproval(cwd = process.cwd(), { agents = APPROVING_AGENTS, read = readFileSync, stateDir = verdictStateDir(cwd) } = {}) {
   let best = null;
   for (const agent of agents) {
     let text;
     try {
-      text = read(join(cwd, '.great_cto', 'verdicts', `${agent}.log`), 'utf8');
+      text = read(join(stateDir, 'verdicts', `${agent}.log`), 'utf8');
     } catch { continue; }
     for (const line of String(text).split('\n')) {
       if (!line.trim()) continue;
@@ -454,8 +466,26 @@ function requireFs() {
 // `--check <file>`  compares a recorded receipt held in a file.
 // `--verify` compares the newest approving verdict's receipt against now.
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+function currentForReceipt(cwd, receipt) {
+  // Persisted evidence is data, not Git options or a new revision expression.
+  // Missing bases retain legacy behavior; invalid declared bases stay unreadable.
+  let base = receipt?.base;
+  // The emitter uses HEAD when there is no conventional default branch. Bind
+  // that legacy symbolic base to the recorded commit, not today's moving HEAD.
+  if (base === 'HEAD') {
+    if (!receipt?.head) return null;
+    base = receipt.head;
+  }
+  if (base != null && (typeof base !== 'string' || !/^[0-9a-f]{7,64}$/i.test(base))) return null;
+  return treeReceipt(cwd, { base: base || null });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
   const argv = process.argv.slice(2);
+  if (argv.includes('--state-dir')) {
+    console.log(verdictStateDir());
+    process.exit(0);
+  }
   if (argv.includes('--emit')) {
     // `--verdicts <dir>`: measure the change from where the previous stage stood.
     const vi = argv.indexOf('--verdicts');
@@ -467,7 +497,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   if (argv.includes('--verify')) {
     const cwd = process.cwd();
     const approval = latestApproval(cwd);
-    const current = treeReceipt(cwd);
+    const current = currentForReceipt(cwd, approval?.receipt);
     const cmp = compareReceipts(approval?.receipt ?? null, current);
     if (cmp.state === 'no-receipt') {
       // Not silence. A push with no approval to compare against and a push whose
@@ -479,6 +509,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     console.log(`receipt: against ${who}`);
     console.log(describeDrift(cmp).split('\n').map((l) => `  ${l}`).join('\n'));
 
+    if (cmp.state === 'unreadable') process.exit(2);
     if (cmp.state !== 'differs') process.exit(0);
 
     // Drift, but a human may already have looked at exactly this state.
@@ -507,8 +538,12 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   if (argv.includes('--accept')) {
     const cwd = process.cwd();
     const approval = latestApproval(cwd);
-    const current = treeReceipt(cwd);
+    const current = currentForReceipt(cwd, approval?.receipt);
     const cmp = compareReceipts(approval?.receipt ?? null, current);
+    if (cmp.state === 'unreadable') {
+      console.error(`receipt: cannot accept — ${cmp.why}`);
+      process.exit(2);
+    }
     if (cmp.state !== 'differs') {
       console.log(`receipt: nothing to accept — ${cmp.why}`);
       process.exit(0);
@@ -537,9 +572,9 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     const { readFileSync } = await import('node:fs');
     let recorded = null;
     try { recorded = JSON.parse(readFileSync(argv[i + 1], 'utf8')); } catch { /* absent */ }
-    const cmp = compareReceipts(recorded, treeReceipt(process.cwd()));
+    const cmp = compareReceipts(recorded, currentForReceipt(process.cwd(), recorded));
     console.log(describeDrift(cmp));
-    process.exit(cmp.state === 'differs' ? 1 : 0);
+    process.exit(cmp.state === 'unreadable' ? 2 : cmp.state === 'differs' ? 1 : 0);
   }
   console.log(JSON.stringify(treeReceipt(process.cwd()), null, 2));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.67.1",
+  "version": "3.68.1",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",

package/board/scripts/lib/doc-links.mjs

@@ -1,146 +0,0 @@
-/**
- * doc-links — how much of the documentation is connected to the rest of it.
- *
- * The operator's words: "документация — по-прежнему не связана в единое целое."
- * First measured over `docs/`, excluding machine summaries and translations:
- *
- *     155 documents
- *      89 orphans — link to nothing, and nothing links to them
- *      18 ADRs, every one of which links to another ADR
- *
- * As of 2026-09-01: 160 documents, 58 orphans. The eighteen orphaned plans were
- * closed by `docs/plans/README.md` — written by hand, one line per plan taken
- * from the plan's own heading. The ratchet in tests/lib/doc-links.test.mjs
- * carries the current floor.
- *
- * So the corpus is one connected island and a field of loose leaves. `ADR-009` has
- * ten inbound links; eighteen plans in `docs/plans` have none in either direction.
- *
- * WHY THIS DOES NOT TRY TO FIX IT
- * ------------------------------
- * The obvious idea is to derive the links: a PLAN about X should point at the ARCH
- * about X and the QA report about X. Measured before attempting it — across 155
- * documents there are THREE shared slugs, covering six files, and front-matter
- * exists on eight. There is no naming convention to derive from. Two real pairs
- * (`judge-provenance`, `stale-after`) are the exception that shows the rule.
- *
- * Connecting the other 89 means reading and understanding 89 documents. A script
- * that guessed would produce links nobody meant, which is exactly the confident
- * fabrication this project spends its checks removing.
- *
- * So this measures, and it ratchets. The number may not grow. Closing it is
- * authoring work, done deliberately, a few documents at a time.
- */
-
-import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
-import path from 'node:path';
-
-/** Generated summaries and translations are copies, not documents. */
-const IS_SUMMARY = /\.summary\.md$/;
-
-/**
- * A two-letter directory is not evidence of a language.
- *
- * This used to be `/^docs\/[a-z]{2}(-[A-Z]{2})?\//`, which reads `docs/qa/`,
- * `docs/ai/`, `docs/ci/`, `docs/ux/` and `docs/db/` as language codes and drops
- * every document under them — silently, from the board's docs tab and from the
- * link graph both, because a dropped document declares nothing that could go
- * missing. `docs/qa/` was already being eaten; the rest were waiting.
- *
- * A whitelist of language codes would rot the first time someone adds one, so
- * the test is STRUCTURAL instead: a translation MIRRORS a document at the docs
- * root. `docs/ru/index.md` is a translation because `docs/index.md` exists;
- * `docs/qa/QA-judge-provenance.md` is not, because `docs/QA-judge-provenance.md`
- * does not. Measured across all ten two-letter directories here — de, es, fr,
- * ja, ko, pt-BR, ru, zh-CN, zh-TW each mirror 1 of 1; qa mirrors 0 of 2 — and it
- * self-corrects when a language is added or removed.
- *
- * Consequence worth stating, because it is a visible surface change hiding
- * inside a classifier fix: `docs/qa/` drafts now APPEAR on the board's docs tab.
- * That is the intended direction — the board is local and should show drafts —
- * but it is not what a reader expects from a regex change.
- */
-const LANG_DIR = /^docs\/[a-z]{2}(?:-[A-Z]{2})?\//;
-
-/** The basename a translation would be a translation OF. */
-const baseName = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
-export function listDocs(root = 'docs') {
-  // The translation rule is written against a path that starts at the docs
-  // directory. `root` may be relative ('docs') or absolute (the board serves
-  // other projects by absolute path), so every candidate is re-expressed
-  // relative to root's parent before the rule is applied — otherwise the rule
-  // matches nothing on an absolute walk and translations count as documents,
-  // which is a wrong number that looks like a right one.
-  const base = path.dirname(root);
-  const found = [];
-  const walk = (dir) => {
-    let entries;
-    try { entries = readdirSync(dir); } catch { return; }
-    for (const e of entries) {
-      const full = path.join(dir, e);
-      let st;
-      try { st = statSync(full); } catch { continue; }
-      if (st.isDirectory()) walk(full);
-      else if (e.endsWith('.md') && !IS_SUMMARY.test(e)) found.push({ full, rel: path.relative(base, full) });
-    }
-  };
-  walk(root);
-
-  // Two passes, because whether a file under a two-letter directory is a
-  // TRANSLATION depends on the rest of the tree: it is one when a document of
-  // the same name lives outside every language directory. One pass cannot know
-  // that, and the single-pass version of this rule only looked at the docs
-  // root — which called `docs/ru/ADR-001-a.md` a document because its source
-  // sits in `docs/adr/`.
-  const sources = new Set(
-    found.filter((f) => !LANG_DIR.test(f.rel)).map((f) => baseName(f.rel)),
-  );
-  return found
-    .filter((f) => !(LANG_DIR.test(f.rel) && sources.has(baseName(f.rel))))
-    .map((f) => f.full)
-    .sort();
-}
-
-/**
- * @returns {{docs:string[], orphans:string[], inbound:Map<string,string[]>}}
- *   An orphan links to no document in this set AND is linked to by none. Both
- *   directions matter: a document nobody references is unreachable, and one that
- *   references nothing is unplaced.
- */
-export function linkGraph(root = 'docs', read = readFileSync) {
-  const docs = listDocs(root);
-  const known = new Set(docs);
-  const out = new Map(docs.map((d) => [d, new Set()]));
-  const inbound = new Map(docs.map((d) => [d, new Set()]));
-
-  for (const f of docs) {
-    let text = '';
-    try { text = String(read(f, 'utf8')); } catch { continue; }
-    const add = (target) => {
-      if (!known.has(target) || target === f) return;
-      out.get(f).add(target);
-      inbound.get(target).add(f);
-    };
-    // Markdown links, resolved relative to the file and to the repo root.
-    for (const m of text.matchAll(/\]\(([^)#\s]+\.md)/g)) {
-      const rel = m[1];
-      add(path.normalize(path.join(path.dirname(f), rel)));
-      add(path.normalize(rel.replace(/^\.\.\//, '')));
-      add(path.normalize(path.join(root, rel)));
-    }
-    // `ADR-009` in prose is a reference even without a link — the convention this
-    // repository actually uses, and the reason the ADRs are its one connected set.
-    for (const m of text.matchAll(/\bADR-(\d{3})\b/g)) {
-      for (const c of docs) {
-        if (path.basename(c).startsWith(`ADR-${m[1]}`)) add(c);
-      }
-    }
-  }
-
-  const orphans = docs.filter((d) => out.get(d).size === 0 && inbound.get(d).size === 0);
-  return {
-    docs,
-    orphans,
-    inbound: new Map([...inbound].map(([k, v]) => [k, [...v]])),
-  };
-}