great-cto 3.17.0 → 3.19.0

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

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

package/board/packages/board/lib/alert-recurrence.mjs

@@ -0,0 +1,73 @@
+/**
+ * Has this alert fired here before?
+ *
+ * `alerts-fired.json` has recorded every alert this machine sent, keyed
+ * `<event>:<project>:<id>` with the time it fired. It was read only as a dedupe
+ * set — "have I already sent THIS instance" — so a gate going stale for the
+ * first time in a project and the ninth in a month produced the same sentence,
+ * and the operator had no way to tell a one-off from a pattern.
+ *
+ * A threshold cannot make that distinction; only history can, and the history
+ * was already on disk.
+ *
+ * Three states, because the file is lossy and its absence means something:
+ *
+ *   unknown    — no history to read. NOT "first": a count nobody took is not a
+ *                count of zero, and this is the substitution the project exists
+ *                to refuse.
+ *   first      — history exists and holds nothing for this rule in this project.
+ *   recurring  — it holds N earlier fires inside the window.
+ *
+ * `atLeast` marks a count taken from a FULL history: the writer keeps only the
+ * last 500 keys, so anything older is gone and the number is a floor.
+ */
+
+/** The writer's cap — see writeAlertsFired in alerts.mjs. */
+const HISTORY_CAP = 500;
+const DEFAULT_WINDOW_DAYS = 30;
+
+/**
+ * @param {Record<string,string>|null} fired  parsed alerts-fired.json, or null
+ *   when there is no such file
+ * @param {{event: string, project: string, now?: number, windowDays?: number}} q
+ * @returns {{state:'unknown'|'first'|'recurring', count:number|null,
+ *            windowDays:number, atLeast:boolean, sentence:string}}
+ */
+export function recurrence(fired, { event, project, now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS }) {
+  if (!fired || typeof fired !== 'object') {
+    return {
+      state: 'unknown', count: null, windowDays, atLeast: false,
+      sentence: 'No alert history on this machine, so whether this has happened before is unknown.',
+    };
+  }
+
+  // Anchored on the full `event:project:` prefix. A bare startsWith(event) would
+  // count `gate.stalest` as `gate.stale`, and a project slug may itself contain
+  // a colon — so both parts are matched as one literal prefix.
+  const prefix = `${event}:${project}:`;
+  const cutoff = now - windowDays * 86_400_000;
+  const keys = Object.keys(fired);
+
+  let count = 0;
+  for (const k of keys) {
+    if (!k.startsWith(prefix)) continue;
+    const at = Date.parse(fired[k]);
+    // An unreadable timestamp is not evidence of a recent fire. Skipped, not
+    // counted as now — which is what a NaN comparison would have done silently.
+    if (!Number.isFinite(at) || at < cutoff) continue;
+    count++;
+  }
+
+  const atLeast = keys.length >= HISTORY_CAP;
+  if (count === 0) {
+    return {
+      state: 'first', count: 0, windowDays, atLeast,
+      sentence: `First time this has fired for this project in ${windowDays} days.`,
+    };
+  }
+  return {
+    state: 'recurring', count, windowDays, atLeast,
+    sentence: `${atLeast ? 'At least ' : ''}${count} other time${count === 1 ? '' : 's'} `
+      + `in the last ${windowDays} days for this project — a pattern, not a one-off.`,
+  };
+}

package/board/packages/board/lib/alerts.mjs

@@ -8,6 +8,8 @@ import {
 } from '../push-adapter.mjs';
 import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT, BUILD_VERSION } from './config.mjs';
 import { _reportRepublishDedupeSet } from './state.mjs';
+import { recurrence } from './alert-recurrence.mjs';
+import { waitingOnYou, dedupeKeyFor } from '../../../scripts/lib/waiting-on-you.mjs';
 import { listProjects, readProjectMd } from './projects.mjs';
 import { addNotification } from './notifications.mjs';
 import { getMetrics } from './metrics.mjs';
@@ -43,6 +45,22 @@ function readAlertsFired() {
   try { return JSON.parse(fs.readFileSync(ALERTS_FIRED_PATH, 'utf8')); } catch { return {}; }
 }
 
+/**
+ * The same file, read as HISTORY rather than as a dedupe set.
+ *
+ * readAlertsFired answers "have I already sent this instance", and `{}` on
+ * failure is right for that: not knowing must never block a send. Read as
+ * history, that same `{}` says "this has never happened here" — a claim nobody
+ * checked. `null` keeps the two apart.
+ */
+function readAlertsHistory() {
+  try {
+    if (!fs.existsSync(ALERTS_FIRED_PATH)) return null;
+    const parsed = JSON.parse(fs.readFileSync(ALERTS_FIRED_PATH, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch { return null; }
+}
+
 function writeAlertsFired(map) {
   try {
     if (!fs.existsSync(GREAT_CTO_DIR)) fs.mkdirSync(GREAT_CTO_DIR, { recursive: true });
@@ -234,20 +252,46 @@ function startAlertCron() {
       const projects = listProjects();
       for (const proj of projects) {
         const tasks = getTasks(proj.path, SWEEP);
-        const gates = tasks.filter(t => t.is_gate && t.raw_status !== 'closed' && t.raw_status !== 'blocked');
-        for (const g of gates) {
-          const created = new Date(g.created_at || g.updated_at || 0).getTime();
-          const ageHr = (Date.now() - created) / 3600_000;
-          if (ageHr < 2 || ageHr > 24 * 7) continue;
-          const dedupeKey = `gate.stale:${proj.slug}:${g.id}`;
+        // Which gates are waiting, and for how long — the same reader the console
+        // hook uses, so the two surfaces cannot tell you different things about
+        // the same gate. See scripts/lib/waiting-on-you.mjs.
+        //
+        // Two silencers were removed here, and each is worth naming because each
+        // was reasonable alone and together they produced total silence:
+        //
+        //   · `raw_status !== 'blocked'` — but gate-expiry MARKS a gate blocked at
+        //     72h, so this hid precisely the gates that had waited longest.
+        //   · `ageHr > 24 * 7 → skip`, on the grounds that a gate open past a week
+        //     is "abandoned, not stale". A decision nobody has made does not get
+        //     less urgent by ageing; every stage behind it is still stopped.
+        //
+        // Measured before this change: six gate.stale alerts in the tool's
+        // lifetime, most recent 41 days old, over a period that contained a gate
+        // sitting open for 29 days.
+        const waiting = waitingOnYou(tasks, { limit: Infinity });
+        for (const g of waiting.items) {
+          const ageHr = g.ageHours;
+          // The period lives in the key, so the same dedupe machinery that
+          // silenced this forever now repeats it daily, then weekly.
+          const dedupeKey = dedupeKeyFor(proj.slug, g);
+          // How often this has happened here. A threshold says the gate is old;
+          // only the history says whether old gates are this project's normal
+          // state. Both readings come from the same file — one as a dedupe set,
+          // this one as history.
+          const seen = recurrence(readAlertsHistory(), { event: 'gate.stale', project: proj.slug });
           const stalePayload = {
-            title: `${proj.slug} — ${g.title.slice(0, 60)} pending ${ageHr.toFixed(1)}h`,
-            body: `A gate has been waiting for your approval for ${ageHr.toFixed(1)} hours.\n\nGate: ${g.id}\nProject: ${proj.slug}`,
+            title: `${proj.slug} — ${g.title.slice(0, 60)} · ${g.why}`,
+            body: `${g.why}. Nothing downstream of it can move.\n\n${seen.sentence}\n\nGate: ${g.id}\nProject: ${proj.slug}`,
             level: 'warning',
             project: proj.slug,
             link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}&task=${encodeURIComponent(g.id)}#inbox`,
             action: 'Approve in board',
-            kv: { gate: g.id, agent: g.agent || 'unknown', age: `${ageHr.toFixed(1)}h` },
+            kv: {
+              gate: g.id, age: `${ageHr}h`, cadence: g.cadence,
+              // `unknown` is carried through rather than rendered as 0 — a count
+              // nobody took is not a count of none.
+              seen_before: seen.count === null ? 'unknown' : `${seen.atLeast ? '\u2265' : ''}${seen.count}`,
+            },
           };
           fireEmailAlert('gate.stale', dedupeKey, stalePayload);
           addNotification('gate.stale', stalePayload, dedupeKey);

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

@@ -682,7 +682,22 @@ function getReadDegradation(cwd = process.cwd()) {
   // 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;
+  const fromTasksMd = readDegradation.get(cwd);
+  if (fromTasksMd) return fromTasksMd;
+
+  // A project that never ran `bd init` has no beads store to fail. bd still
+  // reports its absence as an error, and reporting THAT as a degradation put a
+  // permanent "counts are incomplete" banner over complete counts on every
+  // project that tracks tasks in tasks.md — a supported source, not a fallback
+  // of last resort. Absent and broken are different states; this file already
+  // draws that line for tasks.md ("Missing is a normal state") and now draws it
+  // for beads too.
+  //
+  // Deliberately narrow: an existing .beads/ that bd cannot open is still a
+  // defect and is still reported. Only absence is forgiven.
+  if (checkBeadsAvailable(cwd)) return null;
+
+  return bdFailureFor(cwd) || null;
 }
 
 function parseTasksMd(cwd) {

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

@@ -27,6 +27,14 @@ function getMemory(cwd = process.cwd()) {
   ];
   const result = layers.map(l => ({
     ...l,
+    // `path` opens the file; `displayPath` is what a person — or a README
+    // screenshot — sees. An absolute path here names the operator's home
+    // directory and username: fine in a local tool, wrong the moment the screen
+    // is photographed. The layer already knows its scope, so the display form is
+    // derived rather than guessed.
+    displayPath: l.scope === 'global'
+      ? path.join('~', path.relative(home, l.path)).split(path.sep).join('/')
+      : path.relative(cwd, l.path).split(path.sep).join('/'),
     content: readFileSafe(l.path),
     exists: fs.existsSync(l.path),
     size: fs.existsSync(l.path) ? fs.statSync(l.path).size : 0,

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

@@ -14,6 +14,7 @@
 
 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';
 
 /**
@@ -148,6 +149,10 @@ export function titleFromText(text) {
   return m ? m[1].replace(/\.md$/i, '').trim() : null;
 }
 
+/** Generated summaries and translated copies — see listDocs. */
+const IS_COPY = /\.summary\.md$/i;
+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;
   let entries;
@@ -158,6 +163,10 @@ function walk(dir, root, out, depth = 0) {
     const abs = path.join(dir, e.name);
     if (e.isDirectory()) { walk(abs, root, out, depth + 1); continue; }
     if (!e.name.toLowerCase().endsWith('.md')) continue;
+    // A generated summary and a translation are copies of a document, not more
+    // documents. Counting them made this screen report 188 where there are 156,
+    // 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; }
     out.push({ abs, rel: path.relative(root, abs), size: st.size, modified: st.mtime.toISOString() });
@@ -336,6 +345,17 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
     }
   }
 
+  // How many documents cite this one. Measured over docs/ only, which is where
+  // 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) {
@@ -353,6 +373,7 @@ export function listDocs(root, { max = MAX_DOCS } = {}) {
       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,
       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

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

@@ -5402,6 +5402,52 @@ async function refreshDocsCount() {
   el.textContent = (d && !d.error && typeof d.total === 'number') ? d.total : '—';
 }
 
+// How many documents cite this one, and the order of the list.
+//
+// 105 of 156 documents have no inbound reference. A badge on two rows in three
+// marks nothing — so the count itself is the signal, and sorting by it answers
+// "where would I find X" while letting the zeroes surface without being shouted
+// at. "not measured" is not a zero: it means the document sits outside the link
+// graph, which is a different fact from being cited by nobody.
+let _docsSort = 'recent';
+
+function setDocsSort(mode) {
+  _docsSort = mode;
+  const host = document.getElementById('docs-groups');
+  if (host && _docsCache) host.innerHTML = renderDocGroups(_docsCache.groups || []);
+}
+
+function citedLabel(doc) {
+  if (doc.inbound === null || doc.inbound === undefined) {
+    return '<span class="muted absent" title="Outside docs/ — citations were not measured">not measured</span>';
+  }
+  return `<span class="muted">cited by ${doc.inbound}</span>`;
+}
+
+function renderDocGroups(groups) {
+  const sorted = (docs) => _docsSort === 'cited'
+    ? docs.slice().sort((a, b) => (b.inbound ?? -1) - (a.inbound ?? -1) || a.title.localeCompare(b.title))
+    : docs.slice().sort((a, b) => String(b.modified).localeCompare(String(a.modified)));
+
+  const control = `<div class="card" style="display:flex;align-items:center;gap:10px;flex-wrap:wrap">
+    <b>Sort</b>
+    <button type="button" class="ab-btn" aria-pressed="${_docsSort === 'recent'}" onclick="setDocsSort('recent')">Recently changed</button>
+    <button type="button" class="ab-btn" aria-pressed="${_docsSort === 'cited'}" onclick="setDocsSort('cited')">Most cited</button>
+    <span class="muted" style="font-size:var(--fs-caption)">How many other documents link here.</span>
+  </div>`;
+
+  return control + groups.map(g => `<div class="card">
+      <b>${esc(g.label)}</b> <span class="muted">${g.docs.length} — ${esc(g.why || '')}</span>
+      <div style="margin-top:8px">${sorted(g.docs).map(doc => `
+        <div style="padding:4px 0;border-bottom:1px solid var(--border,#eee)">
+          <a href="#" onclick="openDoc('${esc(doc.path)}');return false">${esc(doc.title)}</a>
+          <span class="muted" style="font-size:var(--fs-caption)"> · ${esc(doc.path)} · ${ago(doc.modified)} · </span>
+          <span style="font-size:var(--fs-caption)">${citedLabel(doc)}</span>
+          ${freshnessBadge(doc)}
+        </div>`).join('')}</div>
+      </div>`).join('');
+}
+
 async function loadDocs() {
   const el = document.getElementById('docs-body');
   el.innerHTML = '<span class="muted">loading…</span>';
@@ -5439,15 +5485,7 @@ async function loadDocs() {
       <details style="margin-top:8px"><summary class="muted">Mermaid source</summary>
         <pre style="white-space:pre-wrap;font-size:var(--fs-caption)">${esc(d.map.mermaid)}</pre></details></div>` : '';
 
-  const groups = (d.groups || []).map(g => `<div class="card">
-      <b>${esc(g.label)}</b> <span class="muted">${g.docs.length} — ${esc(g.why || '')}</span>
-      <div style="margin-top:8px">${g.docs.map(doc => `
-        <div style="padding:4px 0;border-bottom:1px solid var(--border,#eee)">
-          <a href="#" onclick="openDoc('${esc(doc.path)}');return false">${esc(doc.title)}</a>
-          <span class="muted" style="font-size:var(--fs-caption)"> · ${esc(doc.path)} · ${ago(doc.modified)}</span>
-          ${freshnessBadge(doc)}
-        </div>`).join('')}</div>
-      </div>`).join('');
+  const groups = renderDocGroups(d.groups || []);
 
   // Memory used to be its own tab listing PROJECT.md, CODEBASE.md and lessons —
   // the same files this panel's "This project" group already showed. One section
@@ -5457,7 +5495,7 @@ async function loadDocs() {
 
   // The document itself opens in the side panel now, so this panel no longer
   // needs a place to append one.
-  el.innerHTML = pipeline + map + mem + groups;
+  el.innerHTML = pipeline + map + mem + `<div id="docs-groups">${groups}</div>`;
 }
 
 /**
@@ -5526,12 +5564,18 @@ async function loadContextLayers() {
   }
 
   const layers = (m.layers || []).map(l => {
-    const global = String(l.path || '').includes('/.great_cto/') && !String(l.path || '').includes(projectRootHint());
-    const where = global ? ' <span class="muted" style="font-size:var(--fs-caption)">shared by every project</span>' : '';
+    // The reader sees `displayPath` — `.great_cto/PROJECT.md`, or `~/.great_cto/…`
+    // for a shared layer. The absolute path stays behind openDoc(), because it
+    // names this machine's home directory and username and this screen is
+    // photographed for the README. `scope` comes from the server, which knows;
+    // this used to be guessed by matching the breadcrumb text against the path.
+    const shared = l.scope === 'global';
+    const where = shared ? ' <span class="muted" style="font-size:var(--fs-caption)">shared by every project</span>' : '';
+    const shown = l.displayPath || l.name || l.id;
     return l.exists
       ? `<div style="padding:4px 0;border-bottom:1px solid var(--border,#eee)">
            <a href="#" onclick="openDoc('${esc(l.path)}');return false">${esc(l.id)}</a>${where}
-           <span class="muted" style="font-size:var(--fs-caption)"> · ${esc(l.path)}</span></div>`
+           <span class="muted" style="font-size:var(--fs-caption)"> · ${esc(shown)}</span></div>`
       : `<div style="padding:4px 0;border-bottom:1px solid var(--border,#eee)" class="muted">
            ${esc(l.id)} — not written yet${where}</div>`;
   }).join('');
@@ -5547,12 +5591,6 @@ async function loadContextLayers() {
       <div style="margin-top:8px">${pats}</div></div>` : '');
 }
 
-/** The selected project's root, for telling a shared layer from a local one. */
-function projectRootHint() {
-  const crumb = document.querySelector('.crumb-project, #crumb-project');
-  return (crumb && crumb.textContent || '').trim() || '\u0000';
-}
-
 /** The pipeline as boxes and gates — no diagram library, so it always renders. */
 // Named `renderDeclaredPipeline`, not `renderPipeline`, because there is already
 // a `renderPipeline(stages)` above that draws the LIVE rail. Both were declared
@@ -6448,7 +6486,11 @@ function cardHTML(t) {
   const pIdx = t.priority ?? 3;
   const pClass = `p${pIdx}`;
   const pLabel = PRIORITY_LABEL[pIdx];
-  const labels = (t.labels || []).filter(l => l !== 'gate');
+  // The agent is stored in BOTH `agent` and `labels` — deliberately, so filtering
+  // by label finds it — and the card drew a chip from each, so every card carried
+  // its owner's name twice. Keep the data; draw it once. The agent chip is the
+  // one that stays, because it is the one that is styled as an owner.
+  const labels = (t.labels || []).filter(l => l !== 'gate' && l !== t.agent);
   const isGate = !!t.is_gate || (t.labels || []).includes('gate');
   // raw_status reflects bd's actual status (open/in_progress/closed/blocked) —
   // mapStatus() returns 'gate' for gate-labeled cards regardless, so we need

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

@@ -0,0 +1,103 @@
+/**
+ * doc-links — how much of the documentation is connected to the rest of it.
+ *
+ * The operator's words: "документация — по-прежнему не связана в единое целое."
+ * 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
+ *
+ * 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 } from 'node:fs';
+import path from 'node:path';
+
+/** Generated summaries and translations are copies, not documents. */
+const IS_SUMMARY = /\.summary\.md$/;
+const IS_TRANSLATION = /^docs\/[a-z]{2}(-[A-Z]{2})?\//;
+
+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 out = [];
+  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) && !IS_TRANSLATION.test(path.relative(base, full))) out.push(full);
+    }
+  };
+  walk(root);
+  return out.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]])),
+  };
+}

package/board/scripts/lib/waiting-on-you.mjs

@@ -0,0 +1,134 @@
+/**
+ * What is waiting on a human, and for how long. One reader, both surfaces.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Three mechanisms independently decided that old work should stop being
+ * mentioned, and each is defensible alone:
+ *
+ *   · `gate.stale` alerts between 2h and 7 days, skips anything marked
+ *     `blocked`, and dedupes so one gate yields exactly one alert, ever.
+ *   · `gate-expiry` marks a gate `blocked` at 72h — which silences the above.
+ *   · `session-pipeline-resume` treats anything past 24h as history rather than
+ *     work waiting: "a stage that succeeded last week is not work waiting for
+ *     you, it is something that happened."
+ *
+ * Together they produce silence. Measured on the author's machine: `gate.stale`
+ * had fired six times in its life, most recently 41 days earlier, across a
+ * period containing a gate that sat open for 29 days.
+ *
+ * The rule is inverted here: **age is the reason to speak, not to stop.** A
+ * decision nobody has made does not become less urgent by ageing; it becomes
+ * the only thing standing between the project and every stage after it.
+ *
+ * Noise is controlled by RANKING and CADENCE, not by going quiet — see
+ * `cadenceFor`. The alternative that was tried is the one being replaced.
+ *
+ * Both the console hook and the board render this, so the two cannot drift into
+ * telling the operator different things about the same gate.
+ */
+
+/** Below this, a gate is simply in flight. Nagging at once trains the reader to ignore the channel. */
+const NUDGE_FLOOR_HOURS = 2;
+
+/**
+ * How often to repeat a reminder, given how long it has waited.
+ * It decays. It never reaches "never".
+ */
+export function cadenceFor(ageHours) {
+  return ageHours < 24 * 7 ? 'daily' : 'weekly';
+}
+
+function describe(ageHours, wasExpired) {
+  const d = Math.floor(ageHours / 24);
+  const age = d >= 1 ? `${d}d` : `${Math.round(ageHours)}h`;
+  return wasExpired
+    ? `waiting ${age} — past the 72h expiry, so nothing downstream can move`
+    : `waiting ${age} for your decision`;
+}
+
+/**
+ * @param {Array|null} tasks  the project's tasks, or null when they could not be read
+ * @param {{now?: number, limit?: number}} [opts]
+ * @returns {{state:'waiting'|'clear'|'unknown', items:Array, total:number,
+ *            hidden:number, line:string}}
+ */
+export function waitingOnYou(tasks, { now = Date.now(), limit = 3 } = {}) {
+  if (!Array.isArray(tasks)) {
+    // Could-not-read must never render as an empty queue. That substitution is
+    // the one this project exists to refuse, and it is what an empty array from
+    // a failed read would produce.
+    return { state: 'unknown', items: [], total: 0, hidden: 0,
+      line: 'Could not read this project’s tasks, so what is waiting on you is unknown.' };
+  }
+
+  const open = [];
+  for (const t of tasks) {
+    if (!t || !t.is_gate) continue;
+    const status = String(t.raw_status || t.status || '').toLowerCase();
+    // `blocked` is INCLUDED. gate-expiry sets it at 72h, and a gate the machine
+    // gave up on is the one most in need of a human — hiding it was the defect.
+    if (status === 'closed' || status === 'done') continue;
+    const created = Date.parse(t.created_at || t.updated_at || 0);
+    if (!Number.isFinite(created)) continue;
+    const ageHours = (now - created) / 3600_000;
+    if (ageHours < NUDGE_FLOOR_HOURS) continue;
+    open.push({
+      id: t.id,
+      title: String(t.title || '').slice(0, 80),
+      ageHours: Math.round(ageHours),
+      expired: status === 'blocked',
+      cadence: cadenceFor(ageHours),
+      why: describe(ageHours, status === 'blocked'),
+    });
+  }
+
+  if (!open.length) {
+    return { state: 'clear', items: [], total: 0, hidden: 0,
+      line: 'Nothing is waiting on you.' };
+  }
+
+  // Oldest first: the longest wait is the strongest signal, and the one whose
+  // cost has already been paid the longest.
+  open.sort((a, b) => b.ageHours - a.ageHours);
+  const items = open.slice(0, limit);
+  const hidden = open.length - items.length;
+  const n = open.length;
+  const oldest = open[0];
+  return {
+    state: 'waiting',
+    items, total: n, hidden,
+    line: `${n} decision${n === 1 ? '' : 's'} waiting on you`
+      + `, the oldest for ${Math.floor(oldest.ageHours / 24) || '<1'} day`
+      + `${Math.floor(oldest.ageHours / 24) === 1 ? '' : 's'}.`,
+  };
+}
+
+/**
+ * The dedupe key an alert should use — the thing that turns "once, ever" into a
+ * cadence.
+ *
+ * `fireEmailAlert` refuses to send twice for the same key, which is correct and
+ * was the whole problem: the key was `gate.stale:<project>:<gate-id>`, so one
+ * gate produced exactly one alert in its lifetime and then silence, however long
+ * it waited.
+ *
+ * Putting the PERIOD in the key reuses that same machinery to repeat on a
+ * schedule. Same gate, same day: one alert. Same gate, tomorrow: a new key, so
+ * it speaks again. Once the wait passes a week the period widens to a week —
+ * quieter, never silent.
+ */
+export function dedupeKeyFor(project, item, now = Date.now()) {
+  const d = new Date(now);
+  let period;
+  if (item.cadence === 'weekly') {
+    // ISO week: Thursday of the current week identifies the week uniquely, which
+    // avoids the year-boundary bug a naive week number has.
+    const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));
+    period = `w${t.toISOString().slice(0, 10)}`;
+  } else {
+    period = d.toISOString().slice(0, 10);
+  }
+  return `gate.stale:${project}:${item.id}:${period}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.17.0",
+  "version": "3.19.0",
   "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",