great-cto 3.75.10 → 3.76.0

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.75.10",
+  "version": "3.76.0",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"

package/board/agents/architect.md

@@ -666,6 +666,10 @@ manual configuration needed.
    ```
    `auto` cost → real token spend via cost-meter, not a guess.
 
+   **The feature has a user-facing surface** (T1 or higher): record `APPROVED_UI`
+   instead of `APPROVED`. That token is what sends the chain through
+   `design-advisor` before `pm`; with plain `APPROVED` the design stage never starts.
+
    Then create epic + implementation tasks:
    ```bash
    bd create "ARCH: <feature>" --type epic --priority 1

package/board/agents/ci-resolver.md

@@ -11,6 +11,7 @@ memory: project
 color: red
 skills:
   - done-blocked
+  - build-speed
 ---
 
 # ci-resolver

package/board/agents/design-advisor.md

@@ -157,6 +157,8 @@ so every level needs a second signal.
 - You **never** write production UI code (no `.tsx`/`.css`/`.html` implementation).
   That is senior-dev's job, working from your DESIGN doc. If you find yourself
   writing a component body, stop and put the contract in the doc instead.
+- One exception, draft-screens mode below: a throwaway HTML sketch that nothing
+  ships from.
 
 ## Phase task tracking (mandatory)
 
@@ -170,6 +172,30 @@ Run before or parallel to `pm`. On `change_tier` **T0 (maintenance) you do not
 run** — design is a T1+ concern (see `scripts/lib/change-tier.mjs` /
 `effectiveGates`). Skip yourself for a pure fix.
 
+The architect sends you here with `APPROVED_UI`. `product-owner` can also send you
+here earlier with `SCREENS_NEEDED`, before any architecture exists. That is
+draft-screens mode.
+
+## Draft-screens mode (`SCREENS_NEEDED`)
+
+The CTO is about to decide whether to build this, and wants to see it. You have the
+brief and its `## Key scenarios`; no ARCH doc exists and none is needed.
+
+1. Draw **3 to 5 screens of the main scenario** into one self-contained file,
+   `docs/design/SCREENS-<slug>.html`: inline CSS, no external requests, links between
+   screens so the scenario can be clicked through. Screens another scenario needs
+   wait for the full design.
+2. Use realistic content from the brief, never lorem ipsum. Show one failure or
+   empty state if the scenario depends on it.
+3. Put a visible banner on every screen: `Draft: for discussion, not a design
+   decision`. Nothing here commits the design system, the tokens or the stack.
+4. Add a `## Draft screens` line with the path to the brief, then record
+   `SCREENS_DRAFT`. The dispatcher raises `gate:product` from that verdict.
+
+Stop there: none of the sections below, no DESIGN doc. After `architect` you run
+again in full. The drafts are then an input you may overrule, and §10 says where you
+did and why.
+
 ## Inputs (read first)
 
 1. `.great_cto/PROJECT.md` — archetype, project_size, brand, compliance, platform.
@@ -336,4 +362,6 @@ parse it; `auto` records real token cost:
 
 ```bash
 bash scripts/log-verdict.sh design-advisor <DONE|BLOCKED> auto design=docs/design/DESIGN-<slug>.md
+# draft-screens mode:
+bash scripts/log-verdict.sh design-advisor SCREENS_DRAFT auto feature=<slug> screens=docs/design/SCREENS-<slug>.html
 ```

package/board/agents/devops.md

@@ -17,6 +17,7 @@ skills:
   - observability-baseline
   - deploy-landed
   - signing-preflight
+  - build-speed
 ---
 
 You are the DevOps Engineer. Deploy after security approval.

package/board/agents/product-owner.md

@@ -57,6 +57,8 @@ fine. Each is the thing you are here to test, not a premise to build on:
         │
    👤 product-owner  ←  YOU. frame → brainstorm → debate → synthesize
         ▼
+   design-advisor (draft screens)  ←  UI products only, when you record SCREENS_NEEDED
+        ▼
    👤 gate:product  ←  the CTO approves the brief (the one human gate: WHAT before HOW)
         │
    architect → pm → senior-dev → reviewers → qa → devops      (HOW, automated)
@@ -352,6 +354,15 @@ Then raise **gate:product**.
 > archetype is high-compliance, are `team-size`, `cost-cap-usd-month`, `geo` all set?
 > If any is missing, the CTO's approval is wasted because architect will bounce it.
 
+**Show it before it is approved.** When the call is BUILD, the product has a
+user-facing surface and `gate:product` is active at this approval level, add a
+`## Key scenarios` section to the brief: who does what, step by step, for the main
+scenario and at most two others. Then record `SCREENS_NEEDED` and do **not** raise
+the gate: `design-advisor` draws the drafts and the gate rises when they exist.
+Skip this for a fix, a backend or CLI product, or a level where the gate is off: a
+draft nobody is asked about is money spent on nothing. You write the scenarios, not
+the screens; drawing them is not your job.
+
 If the call is DON'T BUILD: write `.great_cto/DISCOVERY-NO-BUILD.md` (problem,
 why-no-build, what would change the decision) and stop — do not hand to architect.
 
@@ -365,6 +376,7 @@ PRODUCT BRIEF: <title>
   The bet: <one line>
   Panel: <FOR n · AGAINST n · decisive point>
   Scope v1: <bullets>
+  Screens: <docs/design/SCREENS-<slug>.html, or none>
 → approve  ·  comment (I revise, max 3 rounds)  ·  reject
 ```
 
@@ -396,5 +408,5 @@ Before your final report, record the canonical verdict line (see
 parse it; `auto` records real token cost:
 
 ```bash
-bash scripts/log-verdict.sh product-owner <APPROVED|NO_BUILD> auto feature=<slug> brief=docs/product/BRIEF-<slug>.md
+bash scripts/log-verdict.sh product-owner <APPROVED|SCREENS_NEEDED|NO_BUILD> auto feature=<slug> brief=docs/product/BRIEF-<slug>.md
 ```

package/board/agents/senior-dev.md

@@ -162,22 +162,38 @@ files or items, dispatch them as parallel subagents in the **same turn** (e.g. g
 smoke tests for several modules at once). Do **not** spawn a subagent for work you can finish
 directly in this response — refactoring a function you can already see, editing one file.
 
-## Worktree isolation
+## Workspace
 
-`isolation: worktree` is set — the orchestrator will try to create a git worktree for each parallel task.
+**Before your first edit**, ask for this task's workspace:
+
+```bash
+WS="${CLAUDE_PLUGIN_ROOT:-$(ls -d ~/.claude/plugins/cache/*/great_cto/*/ 2>/dev/null | awk -F'/plugins/cache/' '{split($NF,p,"/"); print p[3], $0}' | sort -V | tail -1 | cut -d' ' -f2- | sed 's|/$||')}/scripts/workspace.mjs"
+[ -f "$WS" ] || WS="$(pwd)/scripts/workspace.mjs"
+node "$WS" claim <task-id>
+```
+
+It prints one JSON object. Act on it exactly:
+
+| Answer | What you do |
+|---|---|
+| `state` is `adopt`, `reuse` or `create`, and `ok` is true | `cd` to `path` and do all the work there, on `branch`. A server you start uses `port`. |
+| `ok` is false | The workspace exists but `dependencies` or `setup` failed. Stop and report BLOCKED with that field. |
+| `state` is `conflict` | Stop and report BLOCKED with `reason`. Do not delete, re-point or reuse that directory: it is unexplained work. |
+| `state` is `unavailable` | Stop and report BLOCKED with `reason`. Do **not** continue in the shared tree. |
+| `mode` is `shared` | The project has not opted in. Follow the section below. |
+
+After your branch is merged, run `node "$WS" archive <task-id>`. A refusal names its reason and is not an error: leave the worktree alone. Never run `git worktree remove` yourself.
+
+### When `mode` is `shared`
+
+`isolation: worktree` is set, so the orchestrator will try to create a git worktree for each parallel task.
 
 **If you receive a worktree error** ("not in a git repository", "WorktreeCreate hooks not configured", "no commits"):
 1. Do NOT abort. Continue in the main working directory without isolation.
 2. Prefix your first output with: `⚠ Running without worktree isolation (hooks not configured) — changes go to main working tree.`
 3. Extra caution: stage and commit frequently (`git add -p && git commit`) to create checkpoints, since there is no branch isolation.
 
-Worktree hooks setup (for the CTO to fix later): add to `~/.claude/settings.json`:
-```json
-"hooks": {
-  "WorktreeCreate": [{"hooks": [{"type": "command", "command": "mkdir -p $WORKTREE_PATH && git worktree add $WORKTREE_PATH -b $WORKTREE_BRANCH 2>/dev/null || true"}]}],
-  "WorktreeRemove": [{"hooks": [{"type": "command", "command": "git worktree remove $WORKTREE_PATH --force 2>/dev/null || true"}]}]
-}
-```
+The hook setup that fixes this is printed by `/start` in its pre-flight.
 
 ## Session Memory
 

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

@@ -34,6 +34,8 @@ import { isFailure } from './fleet.mjs';
 import { getShareState, toggleShare } from './share.mjs';
 import { checkForRelease, buildUpdatePayload } from './update-alert.mjs';
 import { log } from './log.mjs';
+import { readSessionStatus } from '../../../scripts/lib/session-status.mjs';
+import { blockedAgentEvents, redGateRunEvents, waitingGateEvents, readGateRuns, selectedInstantTriggers } from './instant-alerts.mjs';
 
 // ── Email alerts (Resend) ─────────────────────────────────────────────────
 // Dispatch model: read webhooks.json on every fire (idempotent if disabled
@@ -161,10 +163,48 @@ async function firePushAlert(eventName, dedupeKey, payload) {
   } catch (e) { log.warn('firePushAlert failed:', e.message); }
 }
 
+/**
+ * One pass of the instant triggers over every known project. Exported so a test
+ * can drive it without waiting for the timer.
+ * @returns {Promise<{event:string,dedupeKey:string}[]>} what was sent this pass
+ */
+async function sweepInstantAlerts({ now = Date.now(), projects = listProjects(), greatCtoDir = GREAT_CTO_DIR,
+  send = { email: fireEmailAlert, push: firePushAlert, history: addNotification } } = {}) {
+  const on = selectedInstantTriggers(greatCtoDir);
+  if (!on.size) return [];
+  const sent = [];
+  for (const proj of projects) {
+    const events = [];
+    if (on.has('agent.blocked')) events.push(...blockedAgentEvents(proj.slug, readSessionStatus(proj.path, { now }), { now }));
+    if (on.has('gate.local_red')) events.push(...redGateRunEvents(proj.slug, readGateRuns(proj.path), { now }));
+    if (on.has('gate.waiting')) events.push(...waitingGateEvents(proj.slug, getTasks(proj.path, SWEEP), { now }));
+    for (const ev of events) {
+      // Email and push each mark what THEY sent, and only when configured. The
+      // sweep marks the instance itself, before sending, so with neither channel
+      // set up it still reaches the in-app list once, not once a minute.
+      // An unreadable map is not an empty one: writing `{}` plus one key back
+      // would erase every other alert's dedupe and re-send them all. Stop instead.
+      const fired = fs.existsSync(ALERTS_FIRED_PATH) ? readAlertsHistory() : {};
+      if (!fired) { log.warn('instant alerts: alerts-fired.json is unreadable — nothing sent this pass'); return sent; }
+      const mark = `instant:${ev.dedupeKey}`;
+      if (fired[mark]) continue;
+      fired[mark] = new Date(now).toISOString();
+      const keys = Object.keys(fired);
+      writeAlertsFired(keys.length > 1000 ? Object.fromEntries(keys.slice(-1000).map((k) => [k, fired[k]])) : fired);
+      send.history(ev.event, ev.payload, ev.dedupeKey);
+      await send.email(ev.event, ev.dedupeKey, ev.payload);
+      await send.push(ev.event, ev.dedupeKey, ev.payload);
+      sent.push({ event: ev.event, dedupeKey: ev.dedupeKey });
+    }
+  }
+  return sent;
+}
+
 // ── Cron: scan gates / cost / weekly digest ───────────────────────────────
 // Runs every 5 minutes once the server boots. Each check is idempotent
 // thanks to alerts-fired.json dedupe.
 function startAlertCron() {
+  const ONE_MIN = 60 * 1000;
   const FIVE_MIN = 5 * 60 * 1000;
   const ONE_HOUR = 60 * 60 * 1000;
   const ONE_DAY = 24 * 60 * 60 * 1000;
@@ -302,6 +342,11 @@ function startAlertCron() {
     } catch (e) { log.warn('cron gate.stale failed:', e.message); }
   }, FIVE_MIN);
 
+  // agent.blocked / gate.local_red / gate.waiting — the instant triggers.
+  // Every minute, and only for triggers the operator switched on (see
+  // lib/instant-alerts.mjs for why these three are opt-in on every channel).
+  setInterval(() => { sweepInstantAlerts().catch((e) => log.warn('cron instant alerts failed:', e.message)); }, ONE_MIN);
+
   // cost.threshold: monthly LLM spend at 80% / 100% of budget
   setInterval(async () => {
     try {
@@ -519,4 +564,4 @@ function startAlertCron() {
   log.info('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00), update.available (24h)');
 }
 
-export { readAlertsFired, writeAlertsFired, fireEmailAlert, firePushAlert, startAlertCron };
+export { readAlertsFired, writeAlertsFired, fireEmailAlert, firePushAlert, startAlertCron, sweepInstantAlerts };

package/board/packages/board/lib/gate-run.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# gate-run.sh <worktree> <branch> <main checkout>: one full local gate on a worktree,
+# started from the board's merge-readiness card. It waits for a quiet machine and
+# keeps <main checkout>/.great_cto/gate-queue.json current so the card can say so.
+# Its result reaches the card through gate-runs.jsonl, which ci-local writes itself.
+set -u
+W=$1; B=$2; R=$3; Q="$R/.great_cto/gate-queue.json"
+HEAD_SHA="$(git -C "$W" rev-parse HEAD)"
+write() { # state idle ahead
+  local tmp="$Q.$$"
+  printf '{"branch":"%s","head":"%s","state":"%s","idle":%s,"ahead":%s,"pid":%s}\n' "$B" "$HEAD_SHA" "$1" "${2:-null}" "${3:-0}" "$$" > "$tmp" && mv "$tmp" "$Q"
+}
+LINKED=""
+cleanup() { rm -f "${Q:?}"; for d in $LINKED; do [ -L "$W/$d" ] && rm -f "${W:?}/${d:?}"; done; }
+trap cleanup EXIT
+idle() { top -l 4 -n 0 -s 5 2>/dev/null | grep "CPU usage" | tail -3 | awk '{gsub("%","",$7); s+=$7} END {if (NR) printf "%d", s/NR}'; }
+write queued
+for _ in $(seq 1 480); do
+  others=$(ps -axo command | grep -cE "^(/bin/)?bash .*ci-local\.sh" || true); id=$(idle); free=$(df -g / 2>/dev/null | awk 'NR==2{print $4}')
+  write queued "${id:-null}" "$others"
+  # No reading on this platform is no reason to wait: only a measured busy machine waits.
+  [ "$others" = 0 ] && { [ -z "$id" ] || [ "$id" -ge 30 ]; } && { [ -z "$free" ] || [ "$free" -ge 8 ]; } && break
+  sleep 45
+done
+cd "$W" || exit 1
+for d in node_modules packages/cli/node_modules; do [ -e "$d" ] || { [ -e "$R/$d" ] && ln -s "$R/$d" "$d" && LINKED="$LINKED $d"; }; done
+[ -d "$HOME/.great_cto/tools/ms-playwright" ] && export PLAYWRIGHT_BROWSERS_PATH="$HOME/.great_cto/tools/ms-playwright"
+(cd packages/cli && npm run build >/dev/null 2>&1) || exit 1
+write running
+bash scripts/ci-local.sh --e2e --jobs=8 > "$R/.great_cto/gate-run.log" 2>&1

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

@@ -0,0 +1,159 @@
+/**
+ * The three alerts that speak at once (owner-approved design v16):
+ *
+ *   agent.blocked   — a session is sitting on a permission prompt or waiting for
+ *                     input (state written by the Notification hook through
+ *                     scripts/lib/session-status.mjs);
+ *   gate.local_red  — a ci-local run finished with failures (one line per run in
+ *                     <project>/.great_cto/gate-runs.jsonl, written by
+ *                     scripts/lib/gate-run-record.mjs);
+ *   gate.waiting    — a gate opened and is waiting for the operator, reported
+ *                     when it opens instead of after gate.stale's 2 hours.
+ *
+ * These functions only DECIDE what to send; alerts.mjs sends it. Each event
+ * carries a dedupe key that names one instance, so a 1-minute sweep reports an
+ * instance once.
+ *
+ * Fresh-only on purpose: a board that starts, or a trigger that is switched on,
+ * must not replay a backlog. Older gates are gate.stale's job; older runs and
+ * older blocked sessions are history.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** gate.waiting covers the gap before gate.stale's 2-hour floor. */
+export const GATE_WAITING_WINDOW_MS = 2 * 3600_000;
+/** A red run older than this is history, not news. */
+export const GATE_RUN_WINDOW_MS = 24 * 3600_000;
+/** A blocked state older than this is the session-status DROP horizon anyway. */
+export const BLOCKED_WINDOW_MS = 24 * 3600_000;
+
+export const INSTANT_TRIGGERS = Object.freeze(['agent.blocked', 'gate.local_red', 'gate.waiting']);
+
+const boardLink = (slug, task) =>
+  `http://localhost:3141/?project=${encodeURIComponent(slug)}${task ? `&task=${encodeURIComponent(task)}` : ''}#inbox`;
+
+/**
+ * @param {string} slug
+ * @param {{session:string,state:string,reason?:string,since:string}[]} sessions readSessionStatus() rows
+ */
+export function blockedAgentEvents(slug, sessions, { now = Date.now() } = {}) {
+  if (!Array.isArray(sessions)) return [];
+  const out = [];
+  for (const s of sessions) {
+    if (!s || s.state !== 'blocked' || !s.session) continue;
+    // idle_prompt is Claude Code's reminder that a finished turn is still
+    // unanswered — it follows every turn. That is a session done, not an agent
+    // stuck; alerting on it would page the operator after every reply.
+    if (s.kind === 'idle_prompt') continue;
+    const since = Date.parse(s.since);
+    if (!Number.isFinite(since) || now - since > BLOCKED_WINDOW_MS) continue;
+    const reason = String(s.reason || 'waiting for your input').slice(0, 160);
+    out.push({
+      event: 'agent.blocked',
+      dedupeKey: `agent.blocked:${slug}:${s.session}:${s.since}`,
+      payload: {
+        title: `An agent is blocked — ${slug}`,
+        body: `${slug} · ${reason}\n\nOpens the board. Nothing is approved from a notification.`,
+        level: 'warning',
+        project: slug,
+        link: boardLink(slug),
+        action: 'Open in board',
+        kv: { session: String(s.session).slice(0, 12), since: s.since, reason },
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {string} slug
+ * @param {object[]|null} runs readGateRuns() records
+ */
+export function redGateRunEvents(slug, runs, { now = Date.now() } = {}) {
+  if (!Array.isArray(runs)) return [];
+  const out = [];
+  for (const r of runs) {
+    if (!r || r.result !== 'red' || !r.ts) continue;
+    const ts = Date.parse(r.ts);
+    if (!Number.isFinite(ts) || now - ts > GATE_RUN_WINDOW_MS) continue;
+    const failed = Array.isArray(r.failed) ? r.failed.map(String).slice(0, 8) : [];
+    const where = [r.branch, r.sha].filter(Boolean).join(' @ ') || 'unknown commit';
+    out.push({
+      event: 'gate.local_red',
+      dedupeKey: `gate.local_red:${slug}:${r.ts}:${r.sha || ''}`,
+      payload: {
+        title: `Local gate red — ${slug} · ${where}`,
+        body: `A ci-local run finished with failures.\n\n${failed.length ? `Failed steps:\n- ${failed.join('\n- ')}` : 'Failed steps were not recorded.'}`,
+        level: 'error',
+        project: slug,
+        link: boardLink(slug),
+        action: 'Open in board',
+        kv: { branch: r.branch || 'unknown', sha: r.sha || 'unknown', failed: failed.length ? failed.join(', ') : 'not recorded', ts: r.ts },
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * @param {string} slug
+ * @param {object[]|null} tasks getTasks() rows
+ */
+export function waitingGateEvents(slug, tasks, { now = Date.now() } = {}) {
+  if (!Array.isArray(tasks)) return [];
+  const out = [];
+  for (const t of tasks) {
+    if (!t || !t.is_gate || !t.id) continue;
+    const status = String(t.raw_status || t.status || '').toLowerCase();
+    if (status === 'closed' || status === 'done') continue;
+    const created = Date.parse(t.created_at || t.updated_at || 0);
+    if (!Number.isFinite(created) || now - created > GATE_WAITING_WINDOW_MS) continue;
+    const title = String(t.title || t.id).slice(0, 80);
+    out.push({
+      event: 'gate.waiting',
+      dedupeKey: `gate.waiting:${slug}:${t.id}`,
+      payload: {
+        title: `Gate waiting — ${title} (${slug})`,
+        body: `A gate opened and is waiting for your decision. Nothing downstream of it moves until you decide.\n\nGate: ${t.id}\nProject: ${slug}`,
+        level: 'warning',
+        project: slug,
+        link: boardLink(slug, t.id),
+        action: 'Review in board',
+        kv: { gate: t.id, opened: new Date(created).toISOString().slice(0, 16) },
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * Which instant triggers the operator switched on, from ~/.great_cto/notifications.json.
+ * These triggers are opt-in on EVERY channel (email, push, the in-app list):
+ * unlike the five older ones they can fire many times a day, and a channel
+ * that pages for what nobody asked for gets switched off.
+ */
+export function selectedInstantTriggers(greatCtoDir) {
+  try {
+    const s = JSON.parse(fs.readFileSync(path.join(greatCtoDir, 'notifications.json'), 'utf8'));
+    return new Set((s.triggers || []).filter((t) => INSTANT_TRIGGERS.includes(t)));
+  } catch { return new Set(); } // display-only: no settings file = nothing switched on; nothing is written from this
+}
+
+/**
+ * The project's ci-local run log. `null` when it exists and cannot be read —
+ * a failed read is never an empty history. A missing file is [] (no runs yet).
+ * Malformed lines are skipped: one bad line must not hide the rest.
+ */
+export function readGateRuns(projectDir) {
+  const file = path.join(projectDir, '.great_cto', 'gate-runs.jsonl');
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); }
+  catch (e) { return e.code === 'ENOENT' ? [] : null; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try { const r = JSON.parse(line); if (r && typeof r === 'object') out.push(r); } catch { /* skip */ }
+  }
+  return out;
+}