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

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

@@ -9,6 +9,7 @@ import {
 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';
@@ -251,26 +252,42 @@ 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\n${seen.sentence}\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`,
+              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}`,

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.18.0",
+  "version": "3.20.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",