ai-agentmanager 1.8.0 → 1.10.0

package/public/scorecard.js

@@ -0,0 +1,68 @@
+// The review scorecard on the page: an overall readiness, a bar per score with why, the acceptance
+// criteria, and where to look. Shared by Review changes, the Scorecard document and Land's badges.
+
+const DIMENSIONS = [
+  ['intent', 'Intent'],
+  ['spec', 'Spec'],
+  ['tests', 'Tests'],
+  ['safety', 'Safety'],
+  ['scope', 'Scope'],
+  ['plan', 'Plan'],
+];
+export const RECOMMENDATION = { ready: 'Ready to approve', look: 'Look at these first', not_ready: 'Not ready' };
+const tone = (n) => (n == null ? '' : n >= 80 ? 'good' : n >= 50 ? 'mid' : 'bad');
+const recTone = { ready: 'good', look: 'mid', not_ready: 'bad' };
+
+/** The scorecard of an agent and whether it still matches the changes (diffHash from /changes). */
+export function scorecardOf(agent, diffHash) {
+  const d = agent?.docs?.scorecard;
+  return { doc: d?.data ? d : null, pending: Boolean(d?.pending), error: d?.error ?? null, stale: Boolean(d?.data && diffHash && d.diffHash !== diffHash) };
+}
+
+/** A small badge: "82 · Ready to approve". */
+export function badgeHtml(doc, esc) {
+  if (!doc?.data) return '';
+  const sc = doc.data;
+  return `<span class="sc-badge ${recTone[sc.recommendation]}" title="Review scorecard: ${esc(RECOMMENDATION[sc.recommendation])}${sc.reasons.length ? ` (${esc(sc.reasons.join('; '))})` : ''}">${sc.overall ?? '—'} · ${esc(RECOMMENDATION[sc.recommendation])}</span>`;
+}
+
+/**
+ * The full card. `actions` is extra HTML for the head (buttons); look items carry
+ * data-sc-look="<file>\t<head>" for the page to jump to.
+ */
+export function scorecardHtml(doc, esc, { stale = false, actions = '' } = {}) {
+  const sc = doc.data;
+  const rows = DIMENSIONS.map(([k, label]) => {
+    const d = sc.scores[k];
+    if (!d) return `<div class="sc-row na"><span class="sc-label">${label}</span><span class="sc-bar"></span><span class="sc-n">—</span><span class="sc-why hint">${k === 'spec' ? 'No spec written' : 'Not scored'}</span></div>`;
+    return `<div class="sc-row"><span class="sc-label">${label}</span><span class="sc-bar"><span class="${tone(d.score)}" style="width:${d.score}%"></span></span><span class="sc-n">${d.score}</span><span class="sc-why">${esc(d.why)}${d.notes.length ? ` <span class="sc-note">${esc(d.notes.join('; '))}</span>` : ''}</span></div>`;
+  }).join('');
+  const crit = sc.criteria.length
+    ? `<details class="sc-crit" ${sc.criteria.some((c) => c.status !== 'met') ? 'open' : ''}><summary>Acceptance criteria: ${sc.criteria.filter((c) => c.status === 'met').length} of ${sc.criteria.length} met</summary><ul>${sc.criteria.map((c) => `<li class="${c.status}"><span class="sc-mark">${c.status === 'met' ? '✓' : c.status === 'not_met' ? '✗' : '?'}</span>${esc(c.criterion)}${c.evidence ? ` <span class="hint">${esc(c.evidence)}</span>` : ''}</li>`).join('')}</ul></details>`
+    : '';
+  const look = sc.look.length
+    ? `<div class="sc-look"><b>Where to look</b><ol>${sc.look.map((l) => `<li><button type="button" class="link" data-sc-look="${esc(`${l.file}\t${l.head}`)}"><code>${esc(l.file)}</code></button> ${esc(l.reason)}</li>`).join('')}</ol></div>`
+    : '';
+  const f = sc.facts;
+  return `<div class="scorecard">
+    <div class="sc-head">
+      <span class="sc-overall ${recTone[sc.recommendation]}"><b>${sc.overall ?? '—'}</b><small>/100</small></span>
+      <div class="sc-verdict"><b>${esc(RECOMMENDATION[sc.recommendation])}</b>${sc.reasons.length ? `<div class="hint">${esc(sc.reasons.join(' · '))}</div>` : ''}<div class="hint">${esc(sc.summary)}</div></div>
+      <span class="spacer"></span>${actions}
+    </div>
+    ${stale ? '<p class="hint sc-stale"><b>The changes moved since this was scored.</b> Score again for the latest.</p>' : ''}
+    <div class="sc-rows">${rows}</div>
+    ${crit}${look}
+    <div class="hint sc-facts">Measured: ${f.files} files (+${f.added} −${f.removed}) · ${f.testFiles} test files · CI ${esc(f.ci ?? 'n/a')} · checks ${f.checks.passed}✓ ${f.checks.failed}✗${f.plan ? ` · plan ${f.plan.done}/${f.plan.steps}` : ''}${doc.writer ? ` · scored by ${esc(doc.writer)}` : ''}</div>
+  </div>`;
+}
+
+/** What Listen reads: the verdict, then each score with why. */
+export function scorecardSpeech(doc) {
+  const sc = doc.data;
+  return [
+    `${RECOMMENDATION[sc.recommendation]}. Overall ${sc.overall ?? 'not scored'} out of 100. ${sc.reasons.join('. ')} ${sc.summary}`,
+    ...DIMENSIONS.filter(([k]) => sc.scores[k]).map(([k, label]) => `${label}: ${sc.scores[k].score}. ${sc.scores[k].why} ${sc.scores[k].notes.join('. ')}`),
+    ...(sc.look.length ? [`Where to look: ${sc.look.map((l) => `${l.file.split('/').pop()}: ${l.reason}`).join('. ')}`] : []),
+  ];
+}

package/public/share.js

@@ -24,7 +24,7 @@ async function main() {
   document.title = (d.markdown.match(/^#\s+(.+)$/m)?.[1] ?? `${kind} · ${a.name}`).slice(0, 120);
   if (blocks.length) {
     const mermaid = (await import('/vendor/mermaid/mermaid.esm.min.mjs')).default;
-    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default' });
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default', htmlLabels: false, flowchart: { htmlLabels: false } });
     for (const el of document.querySelectorAll('.diagram')) {
       try {
         el.innerHTML = (await mermaid.render(`d${el.dataset.i}`, blocks[Number(el.dataset.i)])).svg;

package/public/side.js

@@ -2,10 +2,13 @@
 // pane shows the same agent's Code, its Docs (Diagrams by default) or its Changes explained one by
 // one. On, the tab and the document are remembered in this browser.
 import { parseDiff } from '/review.js';
-import { cardHtml, explainButton, walkthroughOf } from '/walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, walkthroughOf } from '/walkthrough.js';
 
 const DOCS = [
   ['diagrams', 'Diagrams'],
+  ['intent', 'Intent'],
+  ['spec', 'Spec'],
+  ['plan', 'Plan'],
   ['design', 'Design'],
   ['flow', 'Flow'],
   ['analysis', 'Analysis'],
@@ -27,14 +30,23 @@ const pref = {
   },
 };
 
-export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, mainKind, setMain, refit }) {
+export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, listenHtml, mainKind, setMain, refit }) {
   const pane = $('#side-pane');
   const body = $('#side-body');
   const code = $('#code');
   const codeHome = $('#term-main');
   const st = { on: pref.get('on', '0') === '1', tab: pref.get('tab', 'docs'), doc: pref.get('doc', 'diagrams'), agentId: null, changes: null, sig: '', loading: false };
 
-  const docOf = (a, kind) => (kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  // Intent, spec and plan are files the daemon reads on request; the rest live on the agent.
+  const FILES = new Set(['intent', 'spec', 'plan']);
+  const files = new Map(); // "<agent>:<kind>" -> { markdown, at }
+  const docOf = (a, kind) => (FILES.has(kind) ? files.get(`${a?.id}:${kind}`) : kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  async function loadFile(kind) {
+    const id = st.agentId;
+    const r = await api('GET', `/agents/${id}/specs/${kind}`).catch(() => null);
+    files.set(`${id}:${kind}`, { markdown: r?.markdown ?? null, at: r?.updatedAt ?? null, loaded: true });
+    if (st.agentId === id && st.doc === kind) renderDocs(true);
+  }
 
   function show() {
     const on = st.on && Boolean(st.agentId);
@@ -56,22 +68,37 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
   // ------------------------------------------------------------ Docs
   function renderDocs(force) {
     const a = agents.get(st.agentId);
-    const d = docOf(a, st.doc);
+    let d = docOf(a, st.doc);
+    // A file that changed on disk (or was never read): read it, then draw.
+    if (FILES.has(st.doc) && (!d || (d.at ?? null) !== (a?.specDocs?.[st.doc] ?? null))) {
+      if (!d?.loading) {
+        files.set(`${st.agentId}:${st.doc}`, { ...d, loading: true });
+        loadFile(st.doc);
+      }
+      d = d?.loaded ? d : null;
+      if (!d) {
+        body.innerHTML = '<p class="hint side-pad">Loading…</p>';
+        return;
+      }
+    }
     const sig = `docs|${st.agentId}|${st.doc}|${d?.at}|${d?.pending}|${d?.error}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
     const label = DOCS.find(([k]) => k === st.doc)?.[1] ?? st.doc;
     const picker = `<select data-side-doc>${DOCS.map(([k, l]) => `<option value="${k}" ${k === st.doc ? 'selected' : ''}>${l}${docOf(a, k)?.markdown ? ' ✓' : ''}</option>`).join('')}</select>`;
     const stale = d?.markdown && a?.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
-    const action = d?.pending
+    const action = FILES.has(st.doc)
+      ? ''
+      : d?.pending
       ? `<span class="hint">Writing…</span>`
       : `<button type="button" class="small ${d?.markdown ? 'ghost' : 'primary'}" data-side-write>${d?.markdown ? 'Again' : st.doc === 'diagrams' ? 'Draw' : 'Write'}</button>`;
     let content;
     if (d?.pending && !d?.markdown) content = `<p class="hint">Writing the ${esc(label.toLowerCase())} from the agent's work so far…</p>`;
     else if (d?.error && !d?.markdown) content = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
     else if (d?.markdown) content = `<div class="md ${st.doc === 'diagrams' ? 'diagrams-view' : ''}">${docHtml(d.markdown)}</div>`;
-    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.</p>`;
-    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${action}</div><div class="side-scroll">${content}</div>`;
+    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.${FILES.has(st.doc) && st.doc !== 'intent' ? ' The agent writes it as it works.' : ''}</p>`;
+    const listen = d?.markdown && st.doc !== 'diagrams' ? listenHtml(`doc:${st.agentId}:${st.doc}`, { title: 'Read it aloud' }) : '';
+    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${listen}${action}</div><div class="side-scroll">${content}</div>`;
     renderDiagrams(body);
   }
 
@@ -107,7 +134,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     const sig = `changes|${st.agentId}|${a?.docs?.walkthrough?.at}|${w.pending}|${w.error}|${st.changes.diffHash}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
-    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
+    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}${w.doc ? listenHtml(`sidewalk:${st.agentId}`, { title: 'Hear the changes one by one' }) : ''}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
     let content;
     if (st.changes.error) content = `<p class="error">${esc(st.changes.error)}</p>`;
     else if (!st.changes.files.length) content = '<p class="hint">No changes yet.</p>';
@@ -115,7 +142,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     else {
       const list = w.doc.data.changes;
       content = `<p class="hint">${esc(w.doc.data.summary)}${w.stale ? ' <b>The changes moved since this was written.</b>' : ''}</p>${list
-        .map((c, i) => `<section class="sd-step"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
+        .map((c, i) => `<section class="sd-step" id="sd-step-${i}"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
         .join('')}`;
     }
     body.innerHTML = `${tools}<div class="side-scroll">${content}</div>`;
@@ -182,6 +209,17 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
       }
     },
     showing: (tab) => st.on && Boolean(st.agentId) && st.tab === tab,
+    /** What Listen reads in Changes: each change, scrolled to and marked as it is read. */
+    listenParts() {
+      const w = walkthroughOf(agents.get(st.agentId), st.changes?.diffHash);
+      if (!w.doc) return [];
+      return walkParts(w.doc.data, (i) => () => {
+        body.querySelectorAll('.sd-step.current').forEach((el) => el.classList.remove('current'));
+        const el = body.querySelector(`#sd-step-${i}`);
+        el?.classList.add('current');
+        el?.scrollIntoView({ block: 'start', behavior: 'smooth' });
+      });
+    },
     agentChanged(a) {
       if (!st.on || a.id !== st.agentId) return;
       if (st.tab === 'docs') renderDocs(false);

package/public/speak.js

@@ -0,0 +1,171 @@
+// Listening instead of reading: Explain, the documents and the change walkthrough read aloud with
+// the browser's own speech (nothing leaves the device; it works on phones). Text goes in short
+// pieces, since some browsers stop a long utterance partway. One thing plays at a time.
+
+const RATES = [0.85, 1, 1.25, 1.5, 1.75];
+const RATE_KEY = 'agentmgr.speechRate';
+
+export const canSpeak = () => typeof window !== 'undefined' && 'speechSynthesis' in window && 'SpeechSynthesisUtterance' in window;
+
+/** Markdown as something to say: no code, diagrams, links' addresses or markup. */
+export function speakable(markdown) {
+  return String(markdown ?? '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, 'a link')
+    .replace(/^#{1,6}\s+(.*)$/gm, '$1.')
+    .replace(/^\s*[-*+]\s+/gm, '')
+    .replace(/^\s*\d+\.\s+/gm, '')
+    .replace(/[*_~>|]/g, '')
+    .replace(/\.\.+/g, '.')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+/** Text in pieces of a few sentences (under ~220 characters), on paragraph and sentence breaks. */
+export function pieces(text, max = 220) {
+  const out = [];
+  for (const para of String(text).split(/\n\s*\n|\n/)) {
+    const sentences = para.match(/[^.!?]+[.!?]*\s*/g) ?? [];
+    let cur = '';
+    for (const s of sentences) {
+      if ((cur + s).length > max && cur) {
+        out.push(cur.trim());
+        cur = '';
+      }
+      cur += s;
+    }
+    if (cur.trim()) out.push(cur.trim());
+  }
+  return out.filter((p) => /\w/.test(p));
+}
+
+let session = null; // { id, parts: [{ text, onStart }], i, paused, onEnd, onState }
+
+function rate() {
+  try {
+    const r = Number(localStorage.getItem(RATE_KEY));
+    return RATES.includes(r) ? r : 1;
+  } catch {
+    return 1;
+  }
+}
+
+function playNext() {
+  const s = session;
+  if (!s) return;
+  if (s.i >= s.parts.length) return stop(true);
+  const part = s.parts[s.i];
+  const u = new SpeechSynthesisUtterance(part.text);
+  u.rate = rate();
+  u.onstart = () => part.onStart?.();
+  u.onend = () => {
+    if (session !== s || s.paused) return;
+    s.i++;
+    playNext();
+  };
+  u.onerror = (e) => {
+    if (session !== s || e.error === 'interrupted' || e.error === 'canceled') return;
+    stop(false);
+  };
+  speechSynthesis.speak(u);
+}
+
+/**
+ * Play `parts` (strings, or { text, onStart } to follow along, e.g. highlight a change) under `id`.
+ * `onState(state)` hears 'playing' | 'paused' | 'stopped'.
+ */
+export function play(id, parts, { onState, onEnd } = {}) {
+  stop(false);
+  if (!canSpeak()) return false;
+  const list = parts.flatMap((p) => {
+    const text = typeof p === 'string' ? p : p.text;
+    const chunks = pieces(text);
+    return chunks.map((c, k) => ({ text: c, onStart: k === 0 && typeof p !== 'string' ? p.onStart : null }));
+  });
+  if (!list.length) return false;
+  session = { id, parts: list, i: 0, paused: false, onState, onEnd };
+  onState?.('playing');
+  notify();
+  playNext();
+  return true;
+}
+
+export function pause() {
+  if (!session || session.paused) return;
+  session.paused = true;
+  // Cancel rather than speechSynthesis.pause(): pausing is unreliable on Chrome and iOS. Resume
+  // restarts the piece that was playing.
+  speechSynthesis.cancel();
+  session.onState?.('paused');
+  notify();
+}
+
+export function resume() {
+  if (!session?.paused) return;
+  session.paused = false;
+  session.onState?.('playing');
+  notify();
+  playNext();
+}
+
+export function stop(finished = false) {
+  const s = session;
+  session = null;
+  if (canSpeak()) speechSynthesis.cancel();
+  if (s) {
+    s.onState?.('stopped');
+    if (finished) s.onEnd?.();
+    notify();
+  }
+}
+
+/** What is playing: { id, paused } or null. */
+export const now = () => (session ? { id: session.id, paused: session.paused } : null);
+
+export function cycleRate() {
+  const next = RATES[(RATES.indexOf(rate()) + 1) % RATES.length];
+  try {
+    localStorage.setItem(RATE_KEY, String(next));
+  } catch {}
+  notify();
+  return next;
+}
+export const rateLabel = () => `${rate()}×`;
+
+// Buttons anywhere on the page redraw themselves from this.
+const listeners = new Set();
+export const onChange = (fn) => listeners.add(fn);
+const notify = () => listeners.forEach((fn) => fn(now()));
+
+/**
+ * A Listen control for `id`: 🔊 Listen, or ⏸ / ▶ with ■ and the speed while that id plays.
+ * Clicks are handled by `bindListen`; `data-say` names what to read.
+ */
+export function listenHtml(id, { title = 'Read it aloud' } = {}) {
+  if (!canSpeak()) return '';
+  const cur = now();
+  if (cur?.id !== id) return `<span class="say" data-say="${id}"><button type="button" class="small ghost" data-say-act="play" title="${title}">🔊 Listen</button></span>`;
+  return `<span class="say on" data-say="${id}"><button type="button" class="small" data-say-act="${cur.paused ? 'resume' : 'pause'}" title="${cur.paused ? 'Resume' : 'Pause'}">${cur.paused ? '▶' : '⏸'}</button><button type="button" class="small ghost" data-say-act="stop" title="Stop">■</button><button type="button" class="small ghost" data-say-act="rate" title="Speed">${rateLabel()}</button></span>`;
+}
+
+/** Handle Listen controls: `start(id)` begins playing that id (it knows what to read). */
+export function bindListen(start) {
+  document.addEventListener('click', (e) => {
+    const b = e.target.closest('[data-say-act]');
+    if (!b) return;
+    const id = b.closest('[data-say]').dataset.say;
+    const act = b.dataset.sayAct;
+    if (act === 'play') start(id);
+    else if (act === 'pause') pause();
+    else if (act === 'resume') resume();
+    else if (act === 'stop') stop(false);
+    else if (act === 'rate') cycleRate();
+  });
+  // Keep every visible control in step with what is playing.
+  onChange(() => {
+    for (const el of document.querySelectorAll('[data-say]')) el.outerHTML = listenHtml(el.dataset.say);
+  });
+}

package/public/style.css

@@ -894,3 +894,43 @@ form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px;
 .menu-theme .seg { display: inline-flex; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin-left: auto; }
 .menu-theme .seg button { border: 0; border-radius: 0; padding: 3px 9px; font-size: 12px; background: transparent; }
 .menu-theme .seg button.on { background: var(--accent); color: var(--accent-text); }
+
+/* Diagram export buttons: on each drawn diagram, shown on hover (always on touch screens). */
+.diagram { position: relative; }
+.dg-tools { position: absolute; top: 6px; right: 6px; display: flex; gap: 4px; opacity: 0; transition: opacity .15s; z-index: 1; }
+.diagram:hover .dg-tools, .diagram:focus-within .dg-tools { opacity: 1; }
+@media (hover: none) { .dg-tools { opacity: 1; position: static; justify-content: flex-end; margin-bottom: 4px; } }
+.dg-tools button { background: var(--panel); }
+/* Listen controls. */
+.say { display: inline-flex; gap: 4px; align-items: center; vertical-align: middle; }
+.say.on button:first-child { min-width: 30px; }
+.explain-foot { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.sd-step.current { box-shadow: 0 0 0 2px var(--accent, #6b8cff); }
+
+/* Review scorecard. */
+.scorecard { display: flex; flex-direction: column; gap: 8px; padding: 10px 12px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel); }
+.sc-head { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
+.sc-overall { display: flex; align-items: baseline; gap: 2px; padding: 4px 10px; border-radius: 8px; border: 2px solid currentColor; }
+.sc-overall b { font-size: 26px; line-height: 1; }
+.sc-overall small { opacity: .7; }
+.sc-verdict { min-width: 0; flex: 1 1 260px; }
+.good { color: var(--green); } .mid { color: var(--yellow); } .bad { color: var(--red); }
+.sc-rows { display: flex; flex-direction: column; gap: 4px; }
+.sc-row { display: grid; grid-template-columns: 64px 140px 32px 1fr; gap: 8px; align-items: center; font-size: 13px; }
+.sc-label { font-weight: 600; }
+.sc-bar { height: 8px; border-radius: 4px; background: var(--panel-2); overflow: hidden; }
+.sc-bar > span { display: block; height: 100%; background: currentColor; }
+.sc-n { text-align: right; font-variant-numeric: tabular-nums; }
+.sc-note { color: var(--yellow); }
+.sc-row.na { opacity: .6; }
+.sc-crit ul, .sc-look ol { margin: 4px 0 0; padding-left: 20px; }
+.sc-crit li { list-style: none; margin-left: -16px; }
+.sc-mark { display: inline-block; width: 16px; font-weight: 700; }
+.sc-crit li.met .sc-mark { color: var(--green); } .sc-crit li.not_met .sc-mark { color: var(--red); } .sc-crit li.unverified .sc-mark { color: var(--yellow); }
+.sc-facts { font-size: 11.5px; }
+.sc-badge { display: inline-block; padding: 1px 8px; border-radius: 999px; border: 1px solid currentColor; font-size: 12px; white-space: nowrap; }
+.rv-score { margin: 0 12px 8px; }
+.rv-score-empty { display: flex; align-items: center; gap: 10px; margin: 0 12px 8px; }
+.rv-hunk.flash td { animation: rvflash 1.6s; }
+@keyframes rvflash { 0%, 60% { background: var(--accent); color: var(--accent-text); } }
+@media (max-width: 640px) { .sc-row { grid-template-columns: 56px 1fr 28px; } .sc-why { grid-column: 1 / -1; } }

package/public/walkthrough.js

@@ -34,3 +34,19 @@ export function explainButton(w, attrs = 'data-wt-explain') {
   return `<button type="button" class="small ${w.doc && !w.stale ? 'ghost' : 'primary'}" ${attrs} ${w.pending ? 'disabled' : ''}
     title="Explain each change one by one: what, why, the risk and what to check, in the order to read them (a separate one-off call; the agent isn't interrupted)">${label}</button>`;
 }
+
+/** What Listen reads for a walkthrough: the summary, then each change; `follow(i)` runs as change i starts. */
+export function listenParts(data, follow = () => null) {
+  const n = data.changes.length;
+  return [
+    data.summary ? `${data.summary} ${n} change${n === 1 ? '' : 's'} to go through.` : `${n} changes to go through.`,
+    ...data.changes.map((c, i) => ({
+      i,
+      text: c.unexplained ? `Change ${i + 1} of ${n}, in ${spokenFile(c.file)}, has no explanation.` : `Change ${i + 1} of ${n}: ${c.title}. In ${spokenFile(c.file)}. ${c.what} ${c.why && c.why !== 'Not stated' ? `Why: ${c.why}` : ''} Risk: ${c.risk}. ${c.check ? `Check: ${c.check}` : ''}`,
+      onStart: follow(i),
+    })),
+  ];
+}
+
+/** "src/server/auth.js" read as "auth.js". */
+const spokenFile = (f) => String(f).split('/').pop();

package/src/brief.js

@@ -654,3 +654,82 @@ export function loadPlanFile(agentId, prev) {
   if (prev && prev.mtimeMs === st.mtimeMs) return null;
   return { markdown: fs.readFileSync(planPath(agentId), 'utf8').slice(0, 200_000), mtimeMs: st.mtimeMs, updatedAt: st.mtime.toISOString() };
 }
+
+// ------------------------------------------------------------------ intent, spec and plan
+
+// Three files per agent, next to the brief, for reviewers (people, other agents, AI review):
+//   INTENT.md - what was asked, written by AI Agent Manager when the agent is created
+//   SPEC.md   - what done means (requirements, acceptance criteria), written by the agent first
+//   PLAN.md   - how it gets there, step by step, kept by the agent (the plan review uses it too)
+// Push & open PR puts them in the pull request's description.
+export const INTENT_FILE = 'INTENT.md';
+export const SPEC_FILE = 'SPEC.md';
+export const intentPath = (agentId) => path.join(briefDir(agentId), INTENT_FILE);
+export const specPath = (agentId) => path.join(briefDir(agentId), SPEC_FILE);
+export const SPEC_DOCS = { intent: intentPath, spec: specPath, plan: planPath };
+
+/** INTENT.md: the request as given, and where it came from. */
+export function intentMarkdown(agent) {
+  const by = agent.startedBy ? 'the assistant' : agent.trigger ? (agent.trigger.source === 'github' ? 'a labeled GitHub issue' : 'a webhook') : agent.playbook ? `the playbook ${agent.playbook.name}` : agent.team ? `team ${agent.team.id} (${agent.team.role})` : agent.raceId ? `race ${agent.raceId}` : 'you';
+  const out = [`# Intent: ${agent.name}`, ''];
+  if (agent.synopsis?.text) out.push(`**${agent.synopsis.source === 'jira' ? `${agent.synopsis.key}: ` : ''}${agent.synopsis.text}**`, '');
+  out.push('## Request', '', agent.intent || '(none)', '');
+  const ctx = [
+    `- Started by: ${by}${agent.trigger?.url ? ` (${agent.trigger.url})` : ''}`,
+    agent.repo || agent.requestedDir ? `- Where: ${agent.repo || agent.requestedDir}${agent.base ? ` (from ${agent.base})` : ''}` : null,
+    agent.engine ? `- Engine: ${agent.engine}${agent.model ? ` (${agent.model})` : ''}` : null,
+    `- Created: ${agent.createdAt}`,
+  ].filter(Boolean);
+  out.push('## Context', '', ...ctx, '');
+  return out.join('\n');
+}
+
+/** The agent's instructions for SPEC.md and PLAN.md (the plan only when the plan review isn't on). */
+export const specPrompt = (specFile, planFile, { withPlan = true } = {}) =>
+  `Before you change any code, write a short spec of the task to ${specFile} (Markdown), so reviewers (people and other agents) ` +
+  'can check the work against it:\n# Spec: <short name>\n## Requirements\nWhat must be true when it is done, as a list.\n' +
+  '## Acceptance criteria\nHow each requirement is checked: a command, a test or an observable behavior.\n## Out of scope\n## Open questions\n' +
+  (withPlan
+    ? `Then write your plan to ${planFile}: "# Plan: <short name>", then "## Steps" as a task list ("- [ ]" to do, "- [x]" done), ` +
+      'small enough to check, and "## Files to change". Keep both current: tick steps as you finish them, and update the spec ' +
+      'if the requirements change (say why). Do not stop to wait for approval; carry on with the work. '
+    : 'Keep it current if the requirements change (say why). ') +
+  'Both files are outside the repository: never copy them into the repo or commit them.';
+
+/** One of the three (intent, spec, plan): its Markdown and when it changed, or null. */
+export function readSpecDoc(agentId, name) {
+  const file = SPEC_DOCS[name]?.(agentId);
+  if (!file) return null;
+  try {
+    const st = fs.statSync(file);
+    return { name, path: file, markdown: fs.readFileSync(file, 'utf8').slice(0, 200_000), updatedAt: st.mtime.toISOString() };
+  } catch {
+    return null;
+  }
+}
+
+/** Which of the three exist, and when they changed (for the page's buttons). */
+export function specDocsInfo(agentId) {
+  const out = {};
+  for (const [name, fn] of Object.entries(SPEC_DOCS)) {
+    try {
+      out[name] = fs.statSync(fn(agentId)).mtime.toISOString();
+    } catch {}
+  }
+  return out;
+}
+
+/** The pull request description's sections: the intent in full, the spec and plan folded. */
+export function prSections(agentId, read = (n) => readSpecDoc(agentId, n)?.markdown) {
+  const doc = (n) => read(n)?.trim();
+  // Demote the files' own headings under the description's.
+  const demote = (md) => md.replace(/^(#{1,4}) /gm, '#$1 ').replace(/^## (Intent|Spec|Plan): .*\n+/m, '');
+  const parts = [];
+  const intent = doc('intent');
+  if (intent) parts.push('## Intent', '', demote(intent), '');
+  for (const [name, label] of [['spec', 'Spec'], ['plan', 'Plan']]) {
+    const md = doc(name);
+    if (md) parts.push(`<details><summary><b>${label}</b></summary>`, '', demote(md), '', '</details>', '');
+  }
+  return parts.length ? [...parts, '<sub>Intent, spec and plan kept by AI Agent Manager.</sub>'].join('\n') : '';
+}

package/src/cli.js

@@ -430,9 +430,9 @@ export async function main(argv) {
 
   program
     .command('doc')
-    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal, humanai (Human vs AI), diagrams (diagrams only) or walkthrough (its changes explained one by one)')
+    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal, humanai (Human vs AI), diagrams (diagrams only), walkthrough (its changes explained one by one) or scorecard (its changes scored for review)')
     .argument('<agent>')
-    .argument('<kind>', 'analysis, design, flow, proposal, humanai, diagrams, walkthrough, or all (background; diagrams and walkthrough not included)')
+    .argument('<kind>', 'analysis, design, flow, proposal, humanai, diagrams, walkthrough, scorecard, or all (background; diagrams, walkthrough and scorecard not included)')
     .option('-o, --output <file>', 'also save the Markdown to this file')
     .option('--cached', 'print the last version instead of writing a new one')
     .option('-b, --background', 'start writing and return at once (kind "all" writes all five)')