great-cto 2.96.0 → 2.97.0

package/board/scripts/lib/freshness.mjs

@@ -0,0 +1,175 @@
+/**
+ * freshness — judges whether an artifact is fresh, stale, or unknown.
+ *
+ * Two axes feed the verdict:
+ *
+ *   1. DECLARED — an author-chosen `stale_after: YYYY-MM-DD`, in YAML
+ *      frontmatter or an inline `**Stale after:** YYYY-MM-DD` marker. When
+ *      present it is authoritative: past that date the doc is stale, future
+ *      of it the doc is fresh — with NO reference to when the file was last
+ *      touched. This is the fix for a re-dated typo rejuvenating content that
+ *      stopped being true months earlier (measured: 13/159 docs, worst case
+ *      76 days — see docs/plans/PLAN-2026-08-15-stale-after.md).
+ *
+ *   2. mtime (label only) — the fallback when `stale_after` is absent. The
+ *      house-rule word for this axis is "mtime", but it does NOT read the
+ *      filesystem's modified time: it reads the doc's own declared
+ *      `**Date:**` / frontmatter `date:` and compares that age to a
+ *      threshold. We keep the label because that's the vocabulary the third
+ *      state (`unknown`) is named in throughout the ARCH/ADR; this comment is
+ *      the correction — what's actually measured is edit-age-as-declared, not
+ *      inode mtime.
+ *
+ * Three states, never two: 'fresh' | 'stale' | 'unknown'. Absence of
+ * `stale_after` is never silently "fresh forever" — it falls through to the
+ * mtime rule, which still fires past the threshold, and a doc with neither
+ * field reads as 'unknown', not fresh.
+ *
+ * `now` is always an injected parameter (`nowMs`) — nothing in this module
+ * calls Date.now(). The caller (artifact-lint.mjs) resolves one NOW_MS at
+ * startup from --now / GREAT_CTO_NOW / the real clock, so every state is
+ * reachable in tests without a timer hack.
+ *
+ * `dateType` ('any' | 'optional') is accepted for signature completeness with
+ * the ARCH's freshness contract but is NOT used to change the verdict here:
+ * the verdict is a fact about the document, not a policy about whether to
+ * warn. Whether an 'unknown' verdict becomes a printed WARN for a
+ * date:'optional' type (PLAN, TM) — vs staying silent, as it does today — is
+ * a report-time decision the caller makes in its lint loop, matching the
+ * ARCH's own "Warn mapping in the lint loop" section. Keeping that policy out
+ * of this pure function means `freshness[]` (the JSON audit trail) can record
+ * every checked artifact's true verdict, warned or not.
+ *
+ * ARCH:  docs/architecture/ARCH-stale-after.md
+ * ADR:   docs/adr/ADR-011-stale-after-precedence.md
+ */
+
+const ISO_DATE = /\d{4}-\d{2}-\d{2}/;
+
+/**
+ * Strip a UTF-8 BOM. A file that starts with one has no `^---` at position 0,
+ * so its frontmatter is invisible to every anchored match below and the
+ * author's declared date is silently lost.
+ */
+function stripBom(s) {
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+/**
+ * True if `iso` (YYYY-MM-DD) is a real calendar date, not just digit-shaped.
+ *
+ * `Date.parse` alone is not enough: it rejects an impossible MONTH
+ * (`2026-13-40` → NaN) but silently rolls an impossible DAY forward, so
+ * `2026-02-30` becomes March 2 rather than failing. Round-tripping the parsed
+ * value back to its components and requiring they match what the author typed
+ * discards such a date instead of quietly judging the document against a
+ * nearby one it never wrote.
+ */
+function isValidIsoDate(iso) {
+  const ms = Date.parse(`${iso}T00:00:00Z`);
+  if (Number.isNaN(ms)) return false;
+  const [y, m, d] = iso.split('-').map(Number);
+  const back = new Date(ms);
+  return back.getUTCFullYear() === y && back.getUTCMonth() + 1 === m && back.getUTCDate() === d;
+}
+
+/**
+ * Parse a declared `stale_after` date from frontmatter or the inline
+ * `**Stale after:**` marker. Defensive by construction: the regex is
+ * anchored to `\d{4}-\d{2}-\d{2}` so a non-date value (`stale_after: soon`)
+ * never matches at all, and a shape-valid but impossible calendar date — an
+ * impossible month (`2026-13-40`) or an impossible day (`2026-02-30`) — is
+ * caught by `isValidIsoDate` and discarded, never coerced, never read as
+ * fresh. Frontmatter takes precedence when both forms appear; the field
+ * describes a single intended value, not two independent ones.
+ *
+ * CRLF and a leading BOM are tolerated: a file normalised by a Windows
+ * checkout or an editor still declares the date its author wrote, and losing
+ * it to an invisible byte would silently demote the document to the mtime
+ * rule while looking exactly like a document that never declared one.
+ *
+ * @param {string} text
+ * @returns {string|null} 'YYYY-MM-DD' or null
+ */
+export function parseStaleAfter(text) {
+  const fm = stripBom(String(text ?? '')).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fm) {
+    const m = fm[1].match(/^stale_after:\s*(\d{4}-\d{2}-\d{2})\b/im);
+    if (m && isValidIsoDate(m[1])) return m[1];
+  }
+  const inline = text.match(/\*\*stale[ _-]?after:?\*\*\s*(\d{4}-\d{2}-\d{2})\b/i);
+  if (inline && isValidIsoDate(inline[1])) return inline[1];
+  return null;
+}
+
+/**
+ * Extract the most recent date (YYYY-MM-DD) from YAML frontmatter or inline
+ * `**Date:**` / `**Last reviewed:**` / `**Updated:**` markers. Moved here
+ * from artifact-lint.mjs per ARCH Risk R3: keeping both date parsers in one
+ * module means they cannot drift apart silently — which is why the CRLF/BOM
+ * tolerance added to `parseStaleAfter` is applied here too rather than only
+ * where it was reported.
+ *
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function extractDate(text) {
+  const found = [];
+  const fm = stripBom(String(text ?? '')).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fm) {
+    for (const m of fm[1].matchAll(/^(?:date|last[_-]?reviewed|updated):\s*(\d{4}-\d{2}-\d{2})/gim)) {
+      found.push(m[1]);
+    }
+  }
+  for (const m of text.matchAll(/\*\*(?:date|last[_-]?reviewed|updated)[:\s]*\*\*\s*(\d{4}-\d{2}-\d{2})/gi)) {
+    found.push(m[1]);
+  }
+  if (!found.length) return null;
+  return found.sort().at(-1); // most recent
+}
+
+/**
+ * Age in whole days of an ISO date against an injected `nowMs` — never
+ * `Date.now()`. Returns null for an unparseable date.
+ *
+ * @param {string} iso
+ * @param {number} nowMs
+ * @returns {number|null}
+ */
+export function ageDays(iso, nowMs) {
+  const then = Date.parse(`${iso}T00:00:00Z`);
+  if (Number.isNaN(then)) return null;
+  return Math.floor((nowMs - then) / 86_400_000);
+}
+
+/**
+ * Judge one artifact's freshness.
+ *
+ * @param {{text: string, dateType: 'any'|'optional', nowMs: number, staleDays: number}} args
+ * @returns {{
+ *   verdict: 'fresh'|'stale'|'unknown',
+ *   basis: 'declared'|'mtime',
+ *   staleAfter: string|null,
+ *   date: string|null,
+ *   ageDays: number|null,
+ * }}
+ */
+export function judgeFreshness({ text, dateType: _dateType, nowMs, staleDays }) {
+  const staleAfter = parseStaleAfter(text);
+  const date = extractDate(text);
+  const age = date ? ageDays(date, nowMs) : null;
+
+  if (staleAfter) {
+    const staleAfterMs = Date.parse(`${staleAfter}T00:00:00Z`);
+    // "Stale on/after that date" (ADR-011 decision #1) — equality counts as stale.
+    const verdict = nowMs >= staleAfterMs ? 'stale' : 'fresh';
+    return { verdict, basis: 'declared', staleAfter, date, ageDays: age };
+  }
+
+  if (!date) {
+    return { verdict: 'unknown', basis: 'mtime', staleAfter: null, date: null, ageDays: null };
+  }
+
+  const verdict = age !== null && age > staleDays ? 'stale' : 'fresh';
+  return { verdict, basis: 'mtime', staleAfter: null, date, ageDays: age };
+}

package/board/scripts/lib/gate-tier.mjs

@@ -0,0 +1,279 @@
+// When a gate may stop asking, and — more usefully — why it may not.
+//
+// The parent plan's phase 5: once an agent's holdout conclusively clears its
+// bar, its gate drops to notify-only. The pipeline proceeds, the entry still
+// appears in the board's inbox, the human may intervene and need not.
+//
+// Why this could not be written until today
+// -----------------------------------------
+// Every earlier "conclusively passes" rested on single-sample runs, and a single
+// sample of a three-case eval can only score 0, 0.33, 0.67 or 1.00 — its own
+// history swings 0.83 → 1.00 → 0.83 with nothing changing. The holdout×3
+// baseline finished on 2026-08-11, 75 of 75, three samples with a majority
+// judge. That is the first evidence in this repository that could carry a
+// decision to stop asking a human.
+//
+// The refusals are the substance
+// ------------------------------
+// Thirty evals clear the interval. Only some of those may drop a gate, and the
+// three cuts are mechanical rather than judgement:
+//
+//   - `sharedExpanded` non-empty: the harness inlined `_shared` contracts into
+//     the actor's prompt, so the agent was handed something it may never fetch
+//     on a live run. On 2026-08-07 architect did not fetch the one whose command
+//     sat verbatim in its own file. An eval that inlines the handoff measures an
+//     agent that does not exist.
+//   - `actorSource` not `agent:<name>`: the generic actor measures the eval, not
+//     the agent.
+//   - Class A: `devops` and `infra-provisioner` both clear the interval today —
+//     devops at 82%, [72%, 89%], n=77 — and both stay gated. The question at a
+//     production deploy is not competence (ADR-009). A tier that cannot refuse
+//     those two is not a tier, it is a rubber stamp.
+//
+// Each refusal names itself. "Inconclusive" and "fixture-inlined" are different
+// work: one needs more samples, the other needs the eval rewritten.
+
+/**
+ * Agents whose gate never drops, whatever the evidence says.
+ *
+ * The same list `pipeline-tick` refuses to dispatch unattended, and for the same
+ * reason: a gate is configuration, and this is not. An operation that escapes
+ * the machine, costs money, or cannot be undone needs a human in the loop, and
+ * "it scored well" is not the same as "a human decided".
+ */
+export const CLASS_A = Object.freeze(['devops', 'infra-provisioner']);
+
+/** The run shape a tier decision may be based on. Anything else is not evidence. */
+export const REQUIRED_SPLIT = 'holdout';
+export const REQUIRED_SAMPLES = 3;
+
+/**
+ * The eval count above which the evidence is at least plural.
+ *
+ * Found by reading our own output rather than the code: of the fifteen agents
+ * whose gate stands down today, FOURTEEN qualified on a single eval file. One
+ * file is roughly six holdout cases at three samples — about eighteen trials —
+ * and that was the entire basis for deciding a human need not be asked.
+ *
+ * The statistics were never wrong. `power.status === 'passed'` means the
+ * interval clears the bar ON THE CASES THAT EXIST, and it says nothing about
+ * whether those cases span what the agent is responsible for. `insurance-
+ * reviewer` answers for NAIC, IFRS 17, Solvency II, ACORD and actuarial
+ * auditability; one passing eval dropped its gate for all of it.
+ *
+ * So this threshold does NOT measure coverage — nothing here can, and claiming
+ * otherwise would be the same defect one layer up. It marks the case where
+ * coverage is UNMEASURED, so that a narrow result stops reading exactly like a
+ * broad one.
+ */
+export const BROAD_EVALS = 2;
+
+/**
+ * The newest qualifying row per eval, for one agent.
+ *
+ * Newest rather than best: an agent that improved and then regressed is at its
+ * regression, and picking the best row would be choosing the evidence to suit
+ * the conclusion.
+ */
+export function evidenceFor(agent, rows = []) {
+  const mine = rows.filter((r) =>
+    r?.agent === agent &&
+    r.split === REQUIRED_SPLIT &&
+    Number(r.samples || 1) === REQUIRED_SAMPLES &&
+    !r.dropout?.severe);
+
+  const newest = new Map();
+  for (const r of mine) {
+    const prev = newest.get(r.eval);
+    if (!prev || String(r.run_id || '') >= String(prev.run_id || '')) newest.set(r.eval, r);
+  }
+  return [...newest.values()];
+}
+
+/**
+ * May this agent's gate drop to notify-only?
+ *
+ * Three answers, not two — the same rule this repository applies everywhere
+ * else. `notify` is a stand-down on plural evidence; `notify-thin` is a
+ * stand-down on ONE eval, where the statistics are sound and the coverage is
+ * simply unmeasured. Collapsing the two would put "we checked one thing and it
+ * was fine" and "we checked broadly and it was fine" behind one word, which is
+ * how an absent measurement comes to wear a result's clothes.
+ *
+ * `notify-thin` is a real tier, not a warning label: whether it stands down or
+ * keeps its gate is the CALLER's decision (see `notifyOnlyAgents`), because
+ * that is a policy about risk appetite and this is a fact about evidence.
+ *
+ * @returns {{tier:'gated'|'notify'|'notify-thin', why:string, evals:number}}
+ */
+export function tierFor(agent, { rows = [], classA = CLASS_A } = {}) {
+  if (classA.includes(agent)) {
+    return { tier: 'gated', evals: 0, why: 'Class A — the question at a production deploy is not competence (ADR-009), so no score drops this gate' };
+  }
+
+  const ev = evidenceFor(agent, rows);
+  if (!ev.length) {
+    return { tier: 'gated', evals: 0, why: `no holdout run at ${REQUIRED_SAMPLES} samples — unmeasured, which is not the same as failing` };
+  }
+
+  // Every eval bound to this agent must clear. An agent that passes one of its
+  // three evals has not shown it can be left alone; it has shown one thing it
+  // can do.
+  const failing = ev.filter((r) => r.power?.status !== 'passed');
+  if (failing.length) {
+    const kinds = [...new Set(failing.map((r) => r.power?.status ?? 'unknown'))].join(', ');
+    return { tier: 'gated', evals: ev.length, why: `${failing.length} of ${ev.length} eval(s) not conclusively passed (${kinds}) — the interval, not the point` };
+  }
+
+  const inlined = ev.filter((r) => (r.sharedExpanded || []).length);
+  if (inlined.length) {
+    const names = [...new Set(inlined.flatMap((r) => r.sharedExpanded))].slice(0, 3).join(', ');
+    return { tier: 'gated', evals: ev.length, why: `the fixture inlined ${names} — this measures an agent that was handed contracts it may never fetch, not the handoff` };
+  }
+
+  const generic = ev.filter((r) => !String(r.actorSource || '').startsWith('agent:'));
+  if (generic.length) {
+    return { tier: 'gated', evals: ev.length, why: 'ran against the generic actor — that measures the eval, not this agent\'s prompt' };
+  }
+
+  const passed = `${ev.length} eval(s) conclusively passed at ${REQUIRED_SPLIT}×${REQUIRED_SAMPLES}, none fixture-inlined`;
+
+  if (ev.length < BROAD_EVALS) {
+    return {
+      tier: 'notify-thin',
+      evals: ev.length,
+      why: `${passed} — but on a single eval, so how much of this agent's responsibility was exercised is unmeasured, not broad`,
+    };
+  }
+
+  return { tier: 'notify', evals: ev.length, why: passed };
+}
+
+/** Every agent that appears in the evidence, tiered. */
+export function tierAll(rows = [], opts = {}) {
+  const agents = [...new Set(rows.map((r) => r?.agent).filter(Boolean))].sort();
+  return agents.map((a) => ({ agent: a, ...tierFor(a, { rows, ...opts }) }));
+}
+
+
+/**
+ * The agents whose gate may stand down, as a Set the pipeline can consult.
+ *
+ * OFF unless the project asks for it. Tiering changes when a human is asked to
+ * decide, and shipping that on by default would change behaviour for every
+ * project that never saw the evidence — the ADR-009 "crosses a project
+ * boundary" case. A project opts in with `gate-tiering: evidence` in its
+ * PROJECT.md.
+ *
+ * Derived at read time, never a list. A stored list of blessed agents is a
+ * snapshot that rots silently: an agent that regresses keeps its pass until
+ * someone remembers to revoke it, which is `ARCHITECTURE.md` saying "34 agents"
+ * for three months. Computed from the history, a regression restores the gate on
+ * the next measurement without anybody acting.
+ */
+export function notifyOnlyAgents(rows = [], { enabled = false, classA = CLASS_A, thin = 'notify' } = {}) {
+  if (!enabled) return new Set();
+  const stands = thin === 'gated' ? ['notify'] : ['notify', 'notify-thin'];
+  return new Set(tierAll(rows, { classA }).filter((a) => stands.includes(a.tier)).map((a) => a.agent));
+}
+
+/**
+ * How much evidence this project wants before a gate stops asking.
+ *
+ *   off             — every gate stands. The default, and what a project that
+ *                     never saw the evidence gets.
+ *   evidence        — a conclusive holdout stands a gate down, including on a
+ *                     single eval. What `gate-tiering: evidence` has meant
+ *                     since it shipped; unchanged, so no project's behaviour
+ *                     moves under it without the owner asking.
+ *   evidence-broad  — the same, except a single-eval pass (`notify-thin`) keeps
+ *                     its gate. Costs fourteen of today's fifteen stand-downs
+ *                     on this repository; buys not treating one eval as breadth.
+ *
+ * Anything unrecognised is `off`. A misspelt mode must not be read as the more
+ * permissive one — the failure of a mis-read here is a gate that quietly
+ * stopped asking.
+ */
+export function tieringMode(projectMdText) {
+  const m = String(projectMdText ?? '').match(/^\s*gate-tiering:\s*(evidence-broad|evidence)\s*$/mi);
+  return m ? m[1].toLowerCase() : 'off';
+}
+
+/** Does this project want evidence-based tiering at all? Default: no. */
+export function tieringEnabled(projectMdText) {
+  return tieringMode(projectMdText) !== 'off';
+}
+
+
+/**
+ * The notify-only set for a project, assembled from its own opt-in and the
+ * measured history. One place, so callers cannot each get it subtly wrong.
+ *
+ * Fails closed: any problem reading either file leaves every gate standing. The
+ * failure mode of a mis-read here is a gate that quietly stops asking, and that
+ * is the one outcome this must never produce by accident.
+ */
+export async function notifyOnlyForProject(cwd = process.cwd()) {
+  try {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const { join, dirname } = await import('node:path');
+    const { fileURLToPath } = await import('node:url');
+
+    const projectMd = join(cwd, '.great_cto', 'PROJECT.md');
+    if (!existsSync(projectMd)) return new Set();
+    const mode = tieringMode(readFileSync(projectMd, 'utf8'));
+    if (mode === 'off') return new Set();
+
+    const history = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'tests', 'eval', 'results-history.jsonl');
+    if (!existsSync(history)) return new Set();
+
+    const rows = [];
+    for (const line of readFileSync(history, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try { rows.push(JSON.parse(line)); } catch { /* a bad row is not evidence */ }
+    }
+    return notifyOnlyAgents(rows, { enabled: true, thin: mode === 'evidence-broad' ? 'gated' : 'notify' });
+  } catch {
+    return new Set();   // fail closed — every gate stands
+  }
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+//
+// Prints who qualifies and, for everyone else, the specific reason — because
+// "inconclusive" and "fixture-inlined" are different work.
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { readFileSync, existsSync } = await import('node:fs');
+  const { join, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  const HISTORY = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'tests', 'eval', 'results-history.jsonl');
+  if (!existsSync(HISTORY)) { console.log('gate-tier: no results-history.jsonl — nothing measured.'); process.exit(0); }
+
+  const rows = [];
+  for (const line of readFileSync(HISTORY, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+  }
+
+  const all = tierAll(rows);
+  const notify = all.filter((a) => a.tier === 'notify');
+  const thin = all.filter((a) => a.tier === 'notify-thin');
+
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(all, null, 2));
+  } else {
+    const projectMd = join(process.cwd(), '.great_cto', 'PROJECT.md');
+    const mode = existsSync(projectMd) ? tieringMode(readFileSync(projectMd, 'utf8')) : 'off';
+
+    console.log(`gate-tier: ${notify.length} broad, ${thin.length} thin, ${all.length - notify.length - thin.length} gated — of ${all.length} agent(s)`);
+    console.log(`  this project: gate-tiering: ${mode}${mode === 'evidence' ? '  (thin stands down too — `evidence-broad` would keep those gates)' : ''}\n`);
+
+    for (const a of notify) console.log(`  notify      ${a.agent.padEnd(28)} ${a.why}`);
+    if (notify.length) console.log('');
+    for (const a of thin) console.log(`  notify-thin ${a.agent.padEnd(28)} ${a.why}`);
+    if (thin.length) console.log('');
+    for (const a of all.filter((x) => x.tier === 'gated')) console.log(`  gated       ${a.agent.padEnd(28)} ${a.why}`);
+  }
+}

package/board/scripts/lib/pipeline-wake.mjs

@@ -0,0 +1,120 @@
+// An approval is evidence that work is waiting. Record it where the next
+// session will look.
+//
+// The hole
+// --------
+// `session-pipeline-resume` opens with a cheap freshness question: if the newest
+// verdict is more than a day old, the pipeline is "history, not work waiting",
+// and the hook returns before reading a single gate. That is the right default
+// for the case it was written for — most sessions start on a project with
+// nothing in flight, and reading gate state costs half a second of shelling out
+// to `bd`.
+//
+// But it answers the wrong question when a gate is approved late. Approve
+// `gate:arch` on a stage that ran three days ago and the strongest possible
+// evidence that the pipeline is waiting — a human just said "go" — is the one
+// thing the hook never consults. It stats the verdict logs, sees three days,
+// and calls the whole thing history.
+//
+// So the board records the approval as a fact when it happens, and the hook
+// treats that fact as the freshness signal it is.
+//
+// What this does NOT do
+// ---------------------
+// It does not decide anything. `tickDecision` still runs with every refusal it
+// has: only `ready-to-dispatch` moves, `devops` and `infra-provisioner` are
+// never dispatched unattended whatever the gates say (ADR-009), the same
+// transition is never dispatched twice, and the minimum interval still applies.
+// A wake only says "look properly, the freshness shortcut does not apply here".
+//
+// It also does not spawn anything. The board cannot — this repository's own
+// `orchestrator-check` hook treats `claude -p` from a tool as an anti-pattern
+// and blocks it. What this removes is the second DECISION, not the second
+// action: you approve, and the next session already knows what it is for.
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * How long an approval stays a reason to look.
+ *
+ * Long enough that approving on Friday still works on Monday; short enough that
+ * an approval nobody acted on in a fortnight stops re-announcing itself. A wake
+ * that never expires becomes a permanent "there is work waiting" that stops
+ * meaning anything.
+ */
+export const WAKE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const FILE = '.pipeline-wake';
+
+function wakePath(cwd, projDir = '.great_cto') {
+  return path.join(cwd, projDir, FILE);
+}
+
+/**
+ * Record that a human approved a gate.
+ *
+ * Best-effort by design: a board that cannot write this must still complete the
+ * approval. The approval is the decision; this is only a note about where to
+ * look for its consequence.
+ *
+ * @returns {{ok: boolean, why?: string, wake?: object}}
+ */
+export function recordWake(cwd, { gate, id, at = Date.now(), by = 'board' } = {}) {
+  const wake = { gate: gate || null, id: id || null, at, by };
+  try {
+    mkdirSync(path.join(cwd, '.great_cto'), { recursive: true });
+    writeFileSync(wakePath(cwd), `${JSON.stringify(wake)}\n`);
+    return { ok: true, wake };
+  } catch (e) {
+    return { ok: false, why: String(e?.message || e) };
+  }
+}
+
+/**
+ * The pending approval, or why there is none.
+ *
+ * Returns a reason rather than null-for-everything: "no approval recorded",
+ * "the record is unreadable" and "the approval is three weeks old" are three
+ * different states, and a caller that collapses them is the defect this
+ * repository keeps removing.
+ */
+export function readWake(cwd, { now = Date.now(), ttlMs = WAKE_TTL_MS } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(wakePath(cwd), 'utf8');
+  } catch {
+    return { pending: false, why: 'no approval recorded' };
+  }
+  let wake;
+  try {
+    wake = JSON.parse(raw.trim());
+  } catch {
+    return { pending: false, why: 'the approval record could not be parsed', unreadable: true };
+  }
+  if (!wake || typeof wake.at !== 'number' || !Number.isFinite(wake.at)) {
+    return { pending: false, why: 'the approval record has no usable timestamp', unreadable: true };
+  }
+  const age = now - wake.at;
+  if (age > ttlMs) {
+    return { pending: false, why: `the approval is ${Math.round(age / 86400_000)} days old — past the ${Math.round(ttlMs / 86400_000)}-day window`, wake, expired: true };
+  }
+  if (age < 0) {
+    // A clock that moved backwards, or a file written by another machine. Treat
+    // it as pending rather than discarding a human's decision over arithmetic.
+    return { pending: true, wake, age: 0, why: 'approval recorded in the future — honouring it anyway' };
+  }
+  return { pending: true, wake, age, why: `approved ${Math.round(age / 60_000)} minute(s) ago` };
+}
+
+/**
+ * Consume the approval.
+ *
+ * Called once the decision has been handed to a session, so the same approval
+ * does not re-announce itself at every session start for a week. Failure to
+ * clear is not fatal — `tickDecision`'s own marker still refuses to dispatch the
+ * same transition twice.
+ */
+export function clearWake(cwd) {
+  try { rmSync(wakePath(cwd), { force: true }); return true; } catch { return false; }
+}