great-cto 3.66.0 → 3.67.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.66.0",
+  "version": "3.67.0",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"

package/board/agents/architect.md

@@ -502,7 +502,7 @@ constraint in the new ARCH doc — document why this design choice was not taken
 
    **If the product's core claim is empirical** — a systematic-trading strategy, a signal, a model whose value IS its measured edge — the architecture question is downstream of whether the claim survives testing. Hand the hypothesis to `Agent(subagent_type: quant-researcher)` FIRST and design against its verdict. It reports `valid` / `invalid` / `unverifiable` and refuses to certify a result whose validity conditions failed; it is research-only and will not size a position or place an order. Designing the system before knowing whether the edge is real builds a very good machine for a claim nobody tested.
 
-4. **Write** `docs/architecture/ARCH-<feature>.md` with: Problem, Decision (with alternatives), Components, API/Data contracts, Security considerations, DB migration plan (if schema changes), Implementation tasks, Definition of Done, Cost Estimate, Requirements Checklist. **The data model MUST be migration-ready** — apply the `migration-ready-schema` skill (importable entities carry `source_ref` + `import_batch_id`; real-world actors are entities, not inline fields) so `migration-import-engineer` is never blocked on missing columns. **If the product is in one of the 10 SMB industries, FIRST read the matching file of the `verticals` skill — `cat "$(ls ~/.claude/plugins/cache/*/great_cto/*/skills/verticals/<industry>.md 2>/dev/null | awk -F'/plugins/cache/' '{split($NF,p,"/"); print p[3], $0}' | sort -V | tail -1 | cut -d' ' -f2-)"` — it is not preloaded, and not through the Skill tool — that tool puts the name of every installed skill into every turn (+13k tokens measured 25.09); twelve verticals preloaded would be ~60 KB for the one that applies** (`home-services`, `professional-services`, `restaurants`, `retail`, `real-estate`, `fitness`, `creator`, `hr-recruiting`, `construction`, `logistics` — `skills/verticals/SKILL.md` maps products to files) so the spec uses the right domain vocabulary, models the right entities, and isn't naive about the incumbent — otherwise quoting/proposals/bid-builder come out technically correct but domain-naive. **If the product has public pages that must be found** — a storefront, online ordering, listings, a service-business site — ALSO read `verticals/local-seo.md` and put its structured data and on-page signals in the spec. **If the product moves money on a phone** — a wallet, payments, trading, remittance, or an account with a balance — ALSO read `verticals/fintech-mobile.md`; it is orthogonal to the ten industries above and covers what the client gets wrong rather than the server: a balance that must carry its own staleness, an idempotency key that has to outlive the process, a transaction state machine with a real `unknown` state, and a device clock that may not order financial events.
+4. **Write** `docs/architecture/ARCH-<feature>.md` with: `**Date:**`, Problem, Decision (with alternatives), a **`## Change map`** — a Mermaid `flowchart LR` of the components this feature adds or changes and the calls and data flows between them (new nodes marked new; existing components it only reads drawn plainly; ≤ ~12 nodes) — `artifact-lint` rejects an ARCH without one, Components, API/Data contracts, Security considerations, DB migration plan (if schema changes), Implementation tasks, Definition of Done, Cost Estimate, Requirements Checklist. **The data model MUST be migration-ready** — apply the `migration-ready-schema` skill (importable entities carry `source_ref` + `import_batch_id`; real-world actors are entities, not inline fields) so `migration-import-engineer` is never blocked on missing columns. **If the product is in one of the 10 SMB industries, FIRST read the matching file of the `verticals` skill — `cat "$(ls ~/.claude/plugins/cache/*/great_cto/*/skills/verticals/<industry>.md 2>/dev/null | awk -F'/plugins/cache/' '{split($NF,p,"/"); print p[3], $0}' | sort -V | tail -1 | cut -d' ' -f2-)"` — it is not preloaded, and not through the Skill tool — that tool puts the name of every installed skill into every turn (+13k tokens measured 25.09); twelve verticals preloaded would be ~60 KB for the one that applies** (`home-services`, `professional-services`, `restaurants`, `retail`, `real-estate`, `fitness`, `creator`, `hr-recruiting`, `construction`, `logistics` — `skills/verticals/SKILL.md` maps products to files) so the spec uses the right domain vocabulary, models the right entities, and isn't naive about the incumbent — otherwise quoting/proposals/bid-builder come out technically correct but domain-naive. **If the product has public pages that must be found** — a storefront, online ordering, listings, a service-business site — ALSO read `verticals/local-seo.md` and put its structured data and on-page signals in the spec. **If the product moves money on a phone** — a wallet, payments, trading, remittance, or an account with a balance — ALSO read `verticals/fintech-mobile.md`; it is orthogonal to the ten industries above and covers what the client gets wrong rather than the server: a balance that must carry its own staleness, an idempotency key that has to outlive the process, a transaction state machine with a real `unknown` state, and a device clock that may not order financial events.
 
    **Anti-patterns to avoid** (see `skills/great_cto/references/anti-patterns.md`, ARCH rules A1–A8). Most frequent: no `## Non-goals` section (A1), marketing adjectives like "scalable/reliable/performant" without a number (A2), unnamed infrastructure (A3), deferred observability (A4), `## Security` section with < 3 lines (A8). These are flagged by `/audit lint`.
 
@@ -722,13 +722,28 @@ Mark each item `- [ ]` so senior-dev and security-officer can tick off during re
    | Check | Rule |
    |-------|------|
    | File scope | >8 files or >1 new service? State it explicitly in the ARCH doc. |
-   | Data flow | >3 components exchanging data? Draw ASCII diagram, check for cycles. |
+   | Data flow | Draw it in `## Change map` (below) and check it for cycles. |
    | Rollback | State the rollback procedure for BOTH surfaces: (a) compute/deploy (e.g. instant revert to previous deployment) AND (b) schema/data (down-migration or forward-fix). Answer both — a deploy that reverts but leaves a one-way migration is not rolled back. |
    | Credentials | List every API key, token, third-party account the plan requires. No credential requests mid-implementation. |
    | External deps | Every external API, MCP server, third-party CLI — verify reachable before handoff. |
    | Test paths | Happy path, error cases, edge cases — all listed in Requirements Checklist. |
 
-8. **Write Requirements Checklist** at the end of `ARCH-<feature>.md`:
+8. **Draw the Change map** in `ARCH-<feature>.md` — the picture the approver sees
+   on the gate brief. Every ARCH has one, whatever the size; when you answer
+   without writing the file, put it in the answer. Components this feature adds
+   are marked `:::new`; existing ones it calls or reads are drawn plainly; nothing
+   it does not touch. ≤ ~12 nodes. `artifact-lint` rejects an ARCH without it.
+   ```markdown
+   ## Change map
+   ```mermaid
+   flowchart LR
+     classDef new stroke-width:3px
+     Retry[RetryScheduler]:::new -->|reads failed| Deliveries[(deliveries)]
+     Retry -->|re-sends| Sender[WebhookSender]
+   ```
+   ```
+
+9. **Write Requirements Checklist** at the end of `ARCH-<feature>.md`:
    ```markdown
    ## Requirements Checklist
    > Derived from CTO request. qa-engineer will verify each item at QA step.
@@ -766,7 +781,7 @@ Mark each item `- [ ]` so senior-dev and security-officer can tick off during re
 
    **If bd unavailable**: skip silently — the REQ checklist in the ARCH doc is the fallback trace.
 
-9. **Report**:
+10. **Report**:
    ```
    Architecture ready → docs/architecture/ARCH-<feature>.md
    Key decisions:

package/board/agents/code-reviewer.md

@@ -165,9 +165,15 @@ sets the verdict, and the human at the gate sees both.
 
 1. For each P0/P1 Finding, file a Beads bug:
    `bd create "<finding> (<file:line>)" --type bug --priority <0-2>`
-2. Write the review to `docs/reviews/REVIEW-<feature-slug>.md` — Findings table
-   (severity · file:line · evidence · fix), Observations, and what the change does
-   well.
+2. Write the review to `docs/reviews/REVIEW-<feature-slug>.md` — `**Date:**`,
+   Findings table (severity · file:line · evidence · fix), Observations, what the
+   change does well, and a **`## Change map`**: a Mermaid `flowchart LR` of what
+   the diff touches, drawn from the diff itself — one node per changed file or
+   component (label = its path), an edge per call or data flow between them that
+   the diff adds or changes, a P0/P1 Finding marked on its node. At most ~12
+   nodes; group by directory beyond that. It is what the approver sees on the
+   gate brief instead of the log, so it shows the change, not the whole system.
+   `artifact-lint` rejects a review without one.
 3. Emit the verdict (see `agents/_shared/verdict-format.md`):
    `scripts/log-verdict.sh code-reviewer <APPROVED|BLOCKED> auto feature=<slug> review=docs/reviews/REVIEW-<slug>.md need=<implementer|decision> finding=<id>`
    — `BLOCKED` if any P0 (or unresolved P1) Finding exists; else `APPROVED`.

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

@@ -33,7 +33,7 @@ import { bdCacheInvalidate, checkBeadsAvailable, bdWriteSerialised, bd, bdErr, g
 import { getMetrics } from './metrics.mjs';
 import { agentActivity, agentActivitySince } from './agent-activity.mjs';
 import { issueTokensAsync, checkToken, checkBinding, consumeToken, approvalSnapshot, beginGateDecision, readTokens } from './gate-tokens.mjs';
-import { gateBrief, settle, readVerdictLogs } from '../../../scripts/lib/gate-brief.mjs';
+import { gateBrief, settle, readVerdictLogs, mapDocPaths } from '../../../scripts/lib/gate-brief.mjs';
 import { readTurns, turnPatch } from '../../../scripts/lib/turn-snapshot.mjs';
 import { appendEvent } from '../../../scripts/lib/agent-events.mjs';
 
@@ -954,12 +954,22 @@ async function dispatch(req, res, url, cwd) {
     // inbox poll may hold one.
     const touches = await settle(readTouches(c));
     const secondOpinion = await settle(readSecondOpinion(c));
+    const verdictLogs = await settle(() => readVerdictLogs(c));
+    // The documents the latest reviewer/architect verdicts point at, for the
+    // change map. mapDocPaths admits only paths under docs/ with no `..`.
+    const docs = {};
+    if (verdictLogs.ok) {
+      for (const { path: rel } of mapDocPaths(verdictLogs.value)) {
+        docs[rel] = await settle(() => fs.readFileSync(path.join(c, rel), 'utf8'));
+      }
+    }
     const brief = gateBrief({
       gate,
       token: readTokens(c).tokens[id] || null,
       binding: touches.ok ? { ok: true, value: touches.value.binding } : touches,
       tests: touches.ok ? touches.value.tests : touches,
-      verdictLogs: await settle(() => readVerdictLogs(c)),
+      verdictLogs,
+      docs,
       secondOpinion,
       tier: await settle(() => getChangeTier(c)),
     });

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

@@ -2151,6 +2151,7 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
 .gate-brief .brief-sec { display: grid; grid-template-columns: 110px 1fr; gap: 10px; align-items: baseline; }
 .gate-brief .brief-k { color: var(--text3); }
 .gate-brief .brief-v { min-width: 0; overflow-wrap: anywhere; }
+.gate-brief .brief-map { margin: 4px 0 0; padding: 6px 8px; background: var(--bg-card); border-radius: 4px; font-size: var(--fs-small, 12px); white-space: pre-wrap; overflow-x: auto; }
 .gate-brief .brief-moved { color: var(--status-blocked); margin-bottom: 4px; }
 .inbox-row {
   display: grid;
@@ -4761,7 +4762,7 @@ function renderGateBrief(d) {
   const row = (label, s, body) => `<div class="brief-sec"><span class="brief-k">${label}</span>`
     + `<span class="brief-v" style="color:${BRIEF_TONE[s.state] || 'inherit'}">${s.state === 'unknown' ? `unknown — ${esc(s.why || '')}` : body}</span></div>`;
   const by = Object.fromEntries(d.sections.map((s) => [s.key, s]));
-  const t = by.tree, c = by.change, r = by.risk, v = by.reviews, o = by.second, x = by.touches;
+  const t = by.tree, c = by.change, r = by.risk, v = by.reviews, o = by.second, x = by.touches, mp = by.map;
   const head = t.moved
     ? `<div class="brief-moved"><b>The tree moved after this gate was shown</b> — ${[
         [...(t.changed || []), ...(t.removed || [])].length ? `changed: ${briefList([...(t.changed || []), ...(t.removed || [])])}` : '',
@@ -4781,6 +4782,9 @@ function renderGateBrief(d) {
     + row('Change', c, `${c.total} file(s)${c.tier ? ` · tier ${esc(c.tier)}` : ` · tier unknown${c.tierWhy ? ` — ${esc(c.tierWhy)}` : ''}`}${c.files?.length ? `<details><summary class="muted">files</summary>${briefList(c.files, 100)}</details>` : ''}`)
     + row('Undo', r, `${esc(r.reversibility)}${r.categories?.length ? ` · ${esc(r.categories.join(', '))}` : ''}`)
     + row('Reviews', v, reviews)
+    + (mp ? row('Change map', mp, mp.state === 'empty'
+        ? `<span class="muted">${esc(mp.why || 'none')}</span>`
+        : `<span class="${mp.onThisTree ? '' : 'muted'}">${esc(mp.agent)} · ${esc(mp.path)}${mp.onThisTree ? ' ✓ this tree' : ' · other tree'}</span><pre class="brief-map">${esc(mp.source)}</pre>`) : '')
     + row('Second model', o, second)
     + row('Touches', x, touches);
 }

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

@@ -114,6 +114,52 @@ function touchesSection(binding, tests) {
   return out;
 }
 
+// ── change map (great_cto-2m2l) ──────────────────────────────────────────────
+// code-reviewer and architect draw what a change touches as a Mermaid flowchart
+// in their documents; the brief shows the one the latest verdict points at. The
+// board ships no diagram library, so the page shows the source, which reads as a
+// list of edges and pastes into any Mermaid viewer.
+const MAP_AGENTS = [['code-reviewer', 'review'], ['architect', 'arch']];
+
+/** The flowchart source in a document's `## Change map`, or null. */
+export function changeMapSource(text) {
+  const lines = String(text || '').split('\n');
+  const start = lines.findIndex((l) => /^##\s+change map\b/i.test(l));
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) if (/^##\s/.test(lines[i])) { end = i; break; }
+  const m = lines.slice(start + 1, end).join('\n').match(/```mermaid\s*\n([\s\S]*?)```/);
+  return m && /^\s*(flowchart|graph)\b/m.test(m[1]) ? m[1].replace(/\s+$/, '') : null;
+}
+
+/** Latest verdict per map agent → the document it points at; only paths under docs/. */
+export function mapDocPaths(verdictLogs) {
+  const out = [];
+  for (const [agent, key] of MAP_AGENTS) {
+    const { records } = parseVerdictLog(verdictLogs?.[agent] || '', { agent });
+    const latest = records.filter((r) => r.meta?.[key]).sort((a, b) => String(b.ts).localeCompare(String(a.ts)))[0];
+    const p = latest?.meta?.[key];
+    if (p && /^docs\/[A-Za-z0-9._/-]+\.md$/.test(p) && !p.split('/').includes('..')) out.push({ agent, path: p });
+  }
+  return out;
+}
+
+function mapSection(verdictLogs, docs, binding, digest) {
+  if (!verdictLogs.ok) return { key: 'map', state: 'unknown', why: verdictLogs.why };
+  const targets = mapDocPaths(verdictLogs.value);
+  if (!targets.length) return { key: 'map', state: 'empty', why: 'no reviewer or architect verdict points at a document with a change map' };
+  const { agent, path } = targets[0];
+  const doc = docs?.[path];
+  if (!doc || !doc.ok) return { key: 'map', state: 'unknown', agent, path, why: doc ? doc.why : 'the document was not read' };
+  const source = changeMapSource(doc.value);
+  if (!source) return { key: 'map', state: 'empty', agent, path, why: `${path} has no Change map section with a flowchart` };
+  const { records } = parseVerdictLog(verdictLogs.value[agent] || '', { agent });
+  const rec = records.filter((r) => r.meta?.review === path || r.meta?.arch === path).sort((a, b) => String(b.ts).localeCompare(String(a.ts)))[0];
+  const current = binding.ok ? binding.value : null;
+  const onThisTree = Boolean(rec?.receipt && current && compareReceipts(rec.receipt, current, { digest }).state === 'matches');
+  return { key: 'map', state: 'recorded', agent, path, onThisTree, source };
+}
+
 /**
  * @param {object} p
  * @param {object} p.gate            pending gate as the inbox returns it
@@ -123,9 +169,10 @@ function touchesSection(binding, tests) {
  * @param {{ok:boolean}} p.secondOpinion
  * @param {{ok:boolean}} p.tier
  * @param {{ok:boolean}} p.tests     affectedTests() result
+ * @param {object} [p.docs]      {path: {ok, value|why}} documents the verdicts point at
  * @param {Function} [p.digest]      file digest for compareReceipts (injected in tests)
  */
-export function gateBrief({ gate, token = null, binding, verdictLogs, secondOpinion, tier, tests, digest = undefined }) {
+export function gateBrief({ gate, token = null, binding, verdictLogs, secondOpinion, tier, tests, docs = {}, digest = undefined }) {
   const tree = treeSection(token, binding, digest);
   return {
     gate: { id: gate?.id || null, title: gate?.title || '', gate: gate?.gate || null },
@@ -135,6 +182,7 @@ export function gateBrief({ gate, token = null, binding, verdictLogs, secondOpin
       changeSection(binding, tier),
       riskSection(gate),
       reviewsSection(verdictLogs, binding, digest),
+      mapSection(verdictLogs, docs, binding, digest),
       secondSection(secondOpinion),
       touchesSection(binding, tests),
     ],

package/package.json

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