ai-agentmanager 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.10.0 (2026-10-31)
+
+- **Review scorecard:** an agent's changes scored 0-100 for Intent, Spec (each acceptance criterion met / not met / unverified, with evidence), Tests, Safety, Scope and Plan, with an overall readiness, a recommendation (Ready to approve / Look at these first / Not ready) and **Where to look**: the few hunks a person should read. Facts the app measures cap the model's scores (failing CI, failing checks, code without tests, plan steps ticked, unassessed criteria) and the recommendation follows fixed rules. At the top of Review changes, as a **Scorecard** document, as a badge in Land, in the PR description, and posted on the PR with **Post to PR** (posting again updates the comment). Runs by itself when the agent marks its work done (`"scorecard": { "auto": false }` turns that off); `agentmgr doc <agent> scorecard`.
+
+## 1.9.0 (2026-10-31)
+
+- **Intent, spec and plan:** each task agent now has INTENT.md (the request as given, its Jira summary, attachments and who started it; written by AI Agent Manager), SPEC.md (requirements, acceptance criteria, out of scope; the agent writes it before changing code) and PLAN.md (steps it ticks off), next to its brief. **Intent · Spec · Plan** buttons and the split view's Docs menu show them; Explain, the documents and AI review read the spec and plan; **Push & open PR** puts them in the pull request's description (intent in full, spec and plan folded). `"specs": false` in config.json turns the spec and plan instructions off.
+- **Export diagrams:** every drawn diagram has **Copy image** (paste into Slack, a PR comment or a doc), **PNG** and **SVG**; a document with diagrams also downloads as one self-contained **.html**. Diagrams now use SVG text labels so they export as images.
+- **Listen:** **🔊 Listen** reads Explain, the documents and the change walkthrough aloud with the browser's own voices (nothing leaves the device; works on phones). The walkthrough is read change by change, showing each as it's read. Pause, stop and speed (0.85× to 1.75×).
+
 ## 1.8.0 (2026-10-31)
 
 - **Update from your phone:** **Update to …** and **About → Update and restart** now show over remote access too; the install and restart run on the computer and the page reloads when it's back. It installs only the official release, from where this copy came from.

package/README.md

@@ -85,13 +85,13 @@ Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the
 
 ```sh
 npm install -g ai-agentmanager          # the latest release
-npm install -g ai-agentmanager@1.8.0    # or a specific one
+npm install -g ai-agentmanager@1.10.0    # or a specific one
 ```
 
 Or from the repository, at a release tag:
 
 ```sh
-git clone --branch v1.8.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
+git clone --branch v1.10.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
 cd ai-agentmanager-core
 npm install
 npm link            # optional: puts `agentmgr` on your PATH
@@ -111,7 +111,7 @@ npm link
 | Installed with | Update |
 | --- | --- |
 | npm | `npm install -g ai-agentmanager@latest` |
-| A clone at a release tag | `git fetch --tags && git checkout v1.8.0 && npm install` (the tag you want) |
+| A clone at a release tag | `git fetch --tags && git checkout v1.10.0 && npm install` (the tag you want) |
 | A clone of `main` | `git pull && npm install` |
 
 **Check your setup.** `agentmgr doctor` checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix anything missing.
@@ -331,6 +331,8 @@ The Brief panel's **Share for review** buttons, or `agentmgr doc <agent> <kind>`
 | **Human vs AI** | Your top 5 decisions, each with why it needs you, the stakes, options and what the work suggests, plus a box for your answer. Up to 5 questions the AI answers, each with its confidence, evidence and how to check it. A second model's verdict on each. |
 | **Diagrams** | Diagrams only, for a quick grasp: the problem, the architecture (with what changes highlighted), the design, the data flow (animated) and the key interaction, plus the plan. Drawn from the documents already written and the agent's work. Optional: **Write all** leaves it out. |
 
+Each drawn diagram has **Copy image** (paste it into Slack, a PR comment or a doc), **PNG** and **SVG**, and a document with diagrams also downloads as one **.html** file. **🔊 Listen** reads Explain, documents and the change walkthrough aloud with the browser's own voices; the walkthrough is read change by change, showing each as it goes.
+
 **Human vs AI.** This review takes two separate read-only calls.
 1. **The split.** The agent's engine splits the open questions. *For you to decide* covers judgment calls such as intent, priorities, risk appetite and trade-offs. *Answered by AI* covers reasoning and evaluation: correctness, edge cases, test coverage and what's left.
 2. **The second opinion.** Another model reviews that split against the same context. It marks each AI answer *agrees*, *partly* or *disagrees*, with a correction where needed. It marks each of your questions *keep*, *AI could answer* or *reword*, and lists questions both lists missed.
@@ -385,9 +387,11 @@ Each card has at most **three points of about 12 words each**, so they're easy t
 
 - **Files and diff.** The changed files on the left with lines added and removed, and the diff file by file on the right. Click a file header to fold it; very large files start folded.
 - **Line comments.** Click **+** next to a line (or its line number) to comment on it, and add an overall comment if you like. **Send to agent** types them into the agent as one message, each with its file, line and the code it is about, and asks it to address them. Comments not sent yet are kept in this browser.
+- **Review scorecard.** **📊 Score changes** (it also runs by itself when the agent marks its work done) scores the changes 0-100 for **Intent**, **Spec** (each acceptance criterion met, not met or unverified, with evidence), **Tests**, **Safety**, **Scope** and **Plan**, and gives an overall readiness with a recommendation: *Ready to approve*, *Look at these first* or *Not ready*, plus **Where to look**, the few hunks worth a person's time. What the app measures caps the model: failing CI or checks, code changed without tests, plan steps not ticked, criteria not assessed. **Post to PR** puts it on the pull request as a comment (again: updates it), and Push & open PR includes it in the description. It also shows as a badge in Land. Turn the automatic run off with `"scorecard": { "auto": false }`.
 - **Explain changes** explains each change one by one: a title, what it changes, why (from the request and the conversation), the risk and what to check, in the order a reviewer should read them. Each explanation sits above its hunk, and **◀ / ▶** (or **[** and **]**) step through them, opening folded files on the way. When the agent changes the code afterwards, the page says so and **Explain again** brings it up to date. From the CLI: `agentmgr doc <agent> walkthrough`.
 - **Commit all** commits everything in the worktree, new files included, with your git name and email.
-- **Push & open PR** pushes the branch and opens a pull request with `gh`, against the branch the agent started from (title from your text, or from the commits; **Draft** if you like). With a pull request already open, it pushes to it. The pull request is linked to the agent.
+- **Intent, spec and plan.** Each agent keeps INTENT.md (what was asked, written by AI Agent Manager), SPEC.md (requirements and acceptance criteria, written by the agent before it changes code) and PLAN.md (steps, ticked off as it goes) next to its brief. Open them with **Intent · Spec · Plan** or in the split view's Docs; Explain, the documents and AI review read them too. `"specs": false` in config.json stops asking agents for the spec and plan.
+- **Push & open PR** pushes the branch and opens a pull request with `gh`, against the branch the agent started from (title from your text, or from the commits; **Draft** if you like). Its description carries the intent, and the spec and plan in folded sections. With a pull request already open, it pushes to it. The pull request is linked to the agent.
 
 The same from the API: `GET /api/agents/:id/changes`, `POST …/changes/comments`, `…/changes/commit`, `…/changes/pr`. Plugins can refuse a commit or a pull request (`agent.commit`, `agent.pr`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",

package/public/app.js

@@ -6,6 +6,9 @@ import { touchScroll } from '/touchscroll.js';
 import { openStream, post, REMOTE } from '/transport.js';
 import { attachBox } from '/attach.js';
 import { initSide } from '/side.js';
+import { addTools, download, htmlFile, initExport } from '/export.js';
+import { badgeHtml as scoreBadge, scorecardHtml, scorecardSpeech } from '/scorecard.js';
+import { bindListen, listenHtml, play, speakable, now as speaking, stop as stopSpeaking } from '/speak.js';
 import { initReview } from '/review.js';
 import { initLand, prChips } from '/land.js';
 import { initTriggers } from '/triggers.js';
@@ -121,7 +124,7 @@ $('#new-playbook').onclick = () => {
   playbooksUi.open({ intent: f.intents.value.trim(), projects: f.project.value.trim() ? [f.project.value.trim()] : [], model: f.model.value.trim(), permissionMode: f.permissionMode.value });
 };
 $('#triggers-open').onclick = () => triggersUi.open();
-const landUi = initLand({ api, esc, toast, agents, $, select: (id) => (showTab('agents'), select(id)), openReview: (id) => reviewUi.open(id), isOpen: () => sideTab === 'land' });
+const landUi = initLand({ api, esc, toast, agents, $, scoreBadge, select: (id) => (showTab('agents'), select(id)), openReview: (id) => reviewUi.open(id), isOpen: () => sideTab === 'land' });
 
 function statusOf(a) {
   if (a.runtime.planning) return a.runtime.attention ? 'attention' : 'planning';
@@ -169,10 +172,13 @@ const isDark = () => {
   const t = document.documentElement.dataset.theme;
   return t ? t === 'dark' : matchMedia('(prefers-color-scheme: dark)').matches;
 };
+// SVG text labels rather than HTML ones: a diagram then exports to PNG (the browser won't turn
+// HTML-in-SVG into an image).
+const mermaidConfig = () => ({ startOnLoad: false, securityLevel: 'strict', theme: isDark() ? 'dark' : 'default', htmlLabels: false, flowchart: { htmlLabels: false } });
 // Diagrams are drawn in the theme's colors: redraw them when it changes.
 window.addEventListener('agentmgr-theme', () => {
   diagrams.clear();
-  mermaidLib?.initialize({ startOnLoad: false, securityLevel: 'strict', theme: isDark() ? 'dark' : 'default' });
+  mermaidLib?.initialize(mermaidConfig());
   for (const el of document.querySelectorAll('[data-mermaid][data-filled]')) delete el.dataset.filled;
   renderDiagrams(document);
 });
@@ -201,8 +207,7 @@ async function renderDiagrams(root) {
       try {
         if (!mermaidLib) {
           mermaidLib = (await import('/vendor/mermaid/mermaid.esm.min.mjs')).default;
-          const dark = isDark();
-          mermaidLib.initialize({ startOnLoad: false, securityLevel: 'strict', theme: dark ? 'dark' : 'default' });
+          mermaidLib.initialize(mermaidConfig());
         }
         const { svg } = await mermaidLib.render(`mmd-${diagrams.size}-${Date.now()}`, src);
         diagrams.set(src, { svg });
@@ -215,7 +220,10 @@ async function renderDiagrams(root) {
     for (const el of document.querySelectorAll('[data-mermaid]')) {
       if (el.dataset.mermaid !== src || el.dataset.filled) continue;
       el.dataset.filled = '1';
-      if (out.svg) el.innerHTML = out.svg;
+      if (out.svg) {
+        el.innerHTML = out.svg;
+        addTools(el);
+      }
       else el.innerHTML = `<div class="hint">Diagram could not be drawn (${esc(out.error)}). Source:</div><pre>${esc(src)}</pre>`;
     }
   }
@@ -233,7 +241,7 @@ function explainBox(a) {
       ${ex.markdown
         ? `${stale ? '<p class="hint">The brief has changed since this explanation; use <b>Explain again</b> to refresh it.</p>' : ''}
            ${clamp(a, 'explain', md(ex.markdown))}
-           <p class="hint">Explained ${ago(ex.at)}.</p>`
+           <p class="hint explain-foot">Explained ${ago(ex.at)}. ${listenHtml(`explain:${a.id}`, { title: 'Read the explanation aloud' })}</p>`
         : ''}
     </div>`;
   return { button, box };
@@ -260,12 +268,21 @@ const INSIGHT_ICONS = { why: '🎯', what: '📦', how: '🛠', now: '📍' };
 
 // ------------------------------------------------------------------ stakeholder documents
 
-const DOCS = { analysis: 'Analysis', design: 'Design', flow: 'Flow', proposal: 'Proposal', humanai: 'Human vs AI', diagrams: 'Diagrams' };
+const DOCS = { analysis: 'Analysis', design: 'Design', flow: 'Flow', proposal: 'Proposal', humanai: 'Human vs AI', diagrams: 'Diagrams', scorecard: 'Scorecard' };
 // Optional extras that "Write all" leaves out.
-const DOC_EXTRAS = new Set(['diagrams']);
-const DOC_TITLES = { ...DOCS, plan: 'Implementation plan' };
+const DOC_EXTRAS = new Set(['diagrams', 'scorecard']);
+const DOC_TITLES = { ...DOCS, plan: 'Plan', intent: 'Intent', spec: 'Spec' };
+// The agent's intent, spec and plan files (read from the daemon when opened; kept here by agent and kind).
+const SPEC_KINDS = { intent: 'Intent', spec: 'Spec', plan: 'Plan' };
+const specCache = new Map(); // "<agent>:<kind>" -> { markdown, at }
+const isSpecKind = (a, kind) => Boolean(SPEC_KINDS[kind]) && !(kind === 'plan' && a?.planReview);
+async function loadSpec(agentId, kind) {
+  const r = await api('GET', `/agents/${agentId}/specs/${kind}`).catch(() => null);
+  specCache.set(`${agentId}:${kind}`, { markdown: r?.markdown ?? null, at: r?.updatedAt ?? null, loaded: true });
+}
 /** What the document dialog shows: a stakeholder document, or the agent's plan under review. */
-const docOf = (a, kind) => (kind === 'plan' ? a?.planReview && { markdown: a.planReview.markdown, at: a.planReview.updatedAt } : a?.docs?.[kind]);
+const docOf = (a, kind) =>
+  isSpecKind(a, kind) ? specCache.get(`${a?.id}:${kind}`) : kind === 'plan' ? a?.planReview && { markdown: a.planReview.markdown, at: a.planReview.updatedAt } : a?.docs?.[kind];
 
 const VERDICT = { agree: '✓ Agrees', partly: '≈ Partly agrees', disagree: '✗ Disagrees', keep: '✓ Keep', ai: '🤖 AI could answer', reword: '✎ Reword' };
 const CONFIDENCE = { high: 'High confidence', medium: 'Medium confidence', low: 'Low confidence' };
@@ -334,7 +351,18 @@ function docButtons(a) {
       const d = a.docs?.[k];
       const stale = d?.markdown && a.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
       return `<button class="small doc-btn ${d?.markdown ? 'has' : ''}" data-doc="${k}" ${d?.pending ? 'disabled' : ''}
-        title="${k === 'diagrams' ? (d?.markdown ? `Open the diagrams${stale ? ' (the brief changed since)' : ''}` : 'Draw the problem and its solution for a quick grasp: architecture, design, data flow (animated) and the key interaction, diagrams only. Built from the documents already written and the agent\'s work') : d?.markdown ? `Open the ${label.toLowerCase()} document${stale ? ' (the brief changed since)' : ''}` : `Write a ${label.toLowerCase()} document for stakeholders`}">${d?.pending ? `${label}…` : label}${d?.markdown ? (stale ? ' •' : ' ✓') : ''}</button>`;
+        title="${k === 'scorecard' ? (d?.markdown ? `Open the review scorecard: ${d.data?.overall ?? '—'}/100` : 'Score the changes for review: intent, spec, scope, plan, tests and safety, with an overall readiness and where to look') : k === 'diagrams' ? (d?.markdown ? `Open the diagrams${stale ? ' (the brief changed since)' : ''}` : 'Draw the problem and its solution for a quick grasp: architecture, design, data flow (animated) and the key interaction, diagrams only. Built from the documents already written and the agent\'s work') : d?.markdown ? `Open the ${label.toLowerCase()} document${stale ? ' (the brief changed since)' : ''}` : `Write a ${label.toLowerCase()} document for stakeholders`}">${d?.pending ? `${label}…` : label}${d?.markdown ? (stale ? ' •' : ' ✓') : ''}</button>`;
+    })
+    .join('')}</span>${specButtons(a)}`;
+}
+
+/** Intent · Spec · Plan: the files kept for reviewers (and put in the pull request's description). */
+function specButtons(a) {
+  if (!a.specDocs) return '';
+  return `<span class="doc-buttons spec-buttons" title="For reviewers, people and agents: what was asked, what done means, and the plan. Push & open PR puts them in the description">${Object.entries(SPEC_KINDS)
+    .map(([k, label]) => {
+      const at = a.specDocs[k] ?? (k === 'plan' ? a.planReview?.updatedAt : null);
+      return `<button class="small doc-btn ${at ? 'has' : ''}" data-doc="${k}" title="${at ? `Open ${label} (updated ${ago(at)})` : k === 'intent' ? 'Written when the agent is created' : `The agent writes it ${k === 'spec' ? 'before changing code' : 'and keeps it current'}`}">${label}${at ? ' ✓' : ''}</button>`;
     })
     .join('')}</span>`;
 }
@@ -346,7 +374,9 @@ function renderDocDialog() {
   const a = agents.get(docView.agentId);
   const d = docOf(a, docView.kind);
   const label = DOC_TITLES[docView.kind];
-  const plan = docView.kind === 'plan';
+  // The plan under review (approve / send back); otherwise a plain file to read.
+  const plan = docView.kind === 'plan' && Boolean(a?.planReview);
+  const specKind = isSpecKind(a, docView.kind);
   $('#doc-title').textContent = `${label} · ${a?.name ?? ''}`;
   const body = $('#doc-body');
   body.classList.toggle('diagrams-view', docView.kind === 'diagrams');
@@ -355,19 +385,24 @@ function renderDocDialog() {
     body.dataset.rendered = '';
   } else if (d?.error) body.innerHTML = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
   else if (plan && !d?.markdown) body.innerHTML = '<p class="hint">The agent is investigating and hasn\'t written its plan yet. You\'ll see it here (and in the inbox) when it has.</p>';
+  else if (specKind && !d?.loaded) body.innerHTML = '<p class="hint">Loading…</p>';
+  else if (specKind && !d?.markdown) body.innerHTML = `<p class="hint">${docView.kind === 'intent' ? 'No intent file for this agent (agents created before 1.9 have none).' : `The agent hasn't written its ${label.toLowerCase()} yet. It writes ${docView.kind === 'spec' ? 'the spec before changing code' : 'the plan and keeps it current'}.`}</p>`;
   else if (d?.markdown) {
     if (body.dataset.rendered !== d.at) {
-      body.innerHTML = d.data ? humanAiHtml(d) : docHtml(d.markdown);
+      body.innerHTML = docView.kind === 'scorecard' ? scorecardHtml(d, esc) : d.data ? humanAiHtml(d) : docHtml(d.markdown);
       body.dataset.rendered = d.at;
       renderDiagrams(body);
     }
   }
   const stale = !plan && d?.markdown && a.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
   const by = d?.writer ? ` by ${d.writer}${d.critique ? `, checked by ${d.critique.label}` : ''}${d.from ? ` from ${d.from.length ? d.from.join(', ') : "the agent's work"}` : ''}` : '';
-  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : docView.kind === 'diagrams' ? 'Drawn' : 'Written'} ${ago(d.at)}${by}${stale ? ' · the brief has changed since; Regenerate for the latest' : ''}` : '';
+  $('#doc-meta').textContent = d?.markdown ? `${plan ? `Plan · ${PLAN_LABEL[a.planReview.status]} · updated` : specKind ? 'Updated' : docView.kind === 'diagrams' ? 'Drawn' : 'Written'} ${ago(d.at)}${by}${stale && !specKind ? ' · the brief has changed since; Regenerate for the latest' : ''}${specKind ? ' · goes into the pull request description' : ''}` : '';
   for (const id of ['doc-copy', 'doc-download', 'doc-print']) $(`#${id}`).disabled = !d?.markdown;
-  $('#doc-print').hidden = plan;
-  $('#doc-regen').hidden = plan;
+  // Diagrams: the whole document as one HTML file with every diagram (each also has Copy / PNG / SVG).
+  $('#doc-html').hidden = !/```mermaid/.test(d?.markdown ?? '');
+  $('#doc-listen').innerHTML = d?.markdown && docView.kind !== 'diagrams' ? listenHtml(docView.kind === 'scorecard' ? `score:${docView.agentId}` : `doc:${docView.agentId}:${docView.kind}`, { title: 'Read the document aloud' }) : '';
+  $('#doc-print').hidden = plan || specKind;
+  $('#doc-regen').hidden = plan || specKind;
   $('#doc-regen').disabled = Boolean(d?.pending);
   $('#doc-bg').hidden = !d?.pending;
   // Footer: send your answers (Human vs AI), or approve / send back the plan.
@@ -388,7 +423,10 @@ function openDoc(agentId, kind) {
   $('#doc-body').dataset.rendered = '';
   $('#doc-dialog').showModal();
   const a = agents.get(agentId);
-  if (kind !== 'plan' && !a.docs?.[kind]?.markdown && !a.docs?.[kind]?.pending) generateDoc();
+  if (isSpecKind(a, kind)) {
+    specCache.delete(`${agentId}:${kind}`);
+    loadSpec(agentId, kind).then(() => docView?.agentId === agentId && docView.kind === kind && renderDocDialog());
+  } else if (kind !== 'plan' && !a.docs?.[kind]?.markdown && !a.docs?.[kind]?.pending) generateDoc();
   renderDocDialog();
 }
 
@@ -398,6 +436,7 @@ function generateDoc() {
 }
 
 $('#doc-close').onclick = () => {
+  if (speaking()?.id.startsWith('doc:')) stopSpeaking();
   docView = null;
   $('#doc-dialog').close();
 };
@@ -484,6 +523,26 @@ function planRow(a) {
     ${p.status !== 'approved' ? '<button class="small ghost" data-act="plan-skip" title="Stop waiting for review; the agent goes ahead">Skip review</button>' : ''}</div>`;
 }
 $('#doc-print').onclick = () => window.open(`/share.html#${docView.agentId}/${docView.kind}`, '_blank', 'noopener');
+$('#doc-html').onclick = () => {
+  const a = agents.get(docView.agentId);
+  download(htmlFile($('#doc-body'), `${DOC_TITLES[docView.kind]}: ${a?.name ?? ''}`), `${a?.slug ?? 'agent'}-${docView.kind}.html`);
+};
+
+// Diagram export: files named after the agent they belong to.
+initExport({ toast, base: (slot) => (slot.closest('#doc-body') && docView ? agents.get(docView.agentId)?.slug : agents.get(term.agentId)?.slug ?? agents.get(selectedId)?.slug) ?? '' });
+
+// Listening: what each Listen control reads.
+bindListen((id) => {
+  const [what, agentId, kind] = id.split(':');
+  const a = agents.get(agentId);
+  let parts = null;
+  if (what === 'explain') parts = [speakable(a?.explanation?.markdown)];
+  else if (what === 'doc') parts = [speakable(kind === 'explain' ? a?.explanation?.markdown : docOf(a, kind)?.markdown)];
+  else if (what === 'walk') parts = reviewUi.listenParts();
+  else if (what === 'score') parts = a?.docs?.scorecard?.data ? scorecardSpeech(a.docs.scorecard) : null;
+  else if (what === 'sidewalk') parts = sidePane?.listenParts();
+  if (!parts?.length || !play(id, parts)) toast('Nothing to read aloud here (or this browser has no speech)');
+});
 
 /** Why / What / How / Now as four cards. */
 function insightsBox(a) {
@@ -2120,6 +2179,7 @@ sidePane = initSide({
   codeUi,
   docHtml,
   renderDiagrams,
+  listenHtml,
   mainKind: () => term.kind,
   setMain: (kind) => term.agentId && term.open(term.agentId, kind),
   refit: () => requestAnimationFrame(() => term.refit()),
@@ -2909,6 +2969,10 @@ function upsert(a) {
 /** Views that show one agent's details outside the main render: keep them current. */
 function agentChanged(a) {
   if (a.id === term.agentId) term.renderTabs();
+  // An open intent / spec / plan that the agent just updated: read it again.
+  if (docView?.agentId === a.id && isSpecKind(a, docView.kind) && specCache.get(`${a.id}:${docView.kind}`)?.at !== (a.specDocs?.[docView.kind] ?? null)) {
+    loadSpec(a.id, docView.kind).then(renderDocDialog);
+  }
   reviewUi.agentChanged(a);
   sidePane?.agentChanged(a);
 }

package/public/export.js

@@ -0,0 +1,110 @@
+// Taking diagrams out of the page, for a pull request or Slack: each drawn diagram gets Copy image,
+// PNG and SVG; a whole document of diagrams downloads as one self-contained HTML file. Diagrams are
+// drawn with SVG text labels (not HTML in foreignObject), so they turn into PNGs without the
+// browser refusing a "tainted" canvas.
+
+const TOOLS = `<span class="dg-tools"><button type="button" class="small ghost" data-dg="copy" title="Copy as an image: paste into Slack, a GitHub comment or a doc">Copy image</button><button type="button" class="small ghost" data-dg="png" title="Download as a PNG">PNG</button><button type="button" class="small ghost" data-dg="svg" title="Download as an SVG (sharp at any size)">SVG</button></span>`;
+
+/** Add the export buttons to a drawn diagram slot. */
+export function addTools(slot) {
+  if (slot.querySelector('.dg-tools') || !slot.querySelector('svg')) return;
+  slot.insertAdjacentHTML('afterbegin', TOOLS);
+}
+
+const pageBg = () => getComputedStyle(document.body).backgroundColor || '#ffffff';
+
+/** A standalone copy of a diagram's SVG: sized, namespaced, on the page's background. */
+export function svgText(svg, { background = pageBg() } = {}) {
+  const copy = svg.cloneNode(true);
+  copy.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  copy.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink');
+  const vb = svg.viewBox?.baseVal;
+  const box = svg.getBoundingClientRect();
+  const w = Math.ceil(vb?.width || box.width || 800);
+  const h = Math.ceil(vb?.height || box.height || 600);
+  copy.setAttribute('width', w);
+  copy.setAttribute('height', h);
+  copy.removeAttribute('style'); // mermaid's max-width would shrink it outside the page
+  if (background) {
+    const bg = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+    Object.entries({ x: vb?.x ?? 0, y: vb?.y ?? 0, width: '100%', height: '100%', fill: background }).forEach(([k, v]) => bg.setAttribute(k, v));
+    if (vb) {
+      bg.setAttribute('width', vb.width);
+      bg.setAttribute('height', vb.height);
+    }
+    copy.insertBefore(bg, copy.firstChild);
+  }
+  return { text: new XMLSerializer().serializeToString(copy), w, h };
+}
+
+/** The diagram as a PNG blob, at twice its size so it stays sharp on retina screens and in PRs. */
+export function pngBlob(svg, scale = 2) {
+  const { text, w, h } = svgText(svg);
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      const canvas = Object.assign(document.createElement('canvas'), { width: w * scale, height: h * scale });
+      const ctx = canvas.getContext('2d');
+      ctx.scale(scale, scale);
+      ctx.drawImage(img, 0, 0, w, h);
+      canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('Could not make the image'))), 'image/png');
+    };
+    img.onerror = () => reject(new Error('Could not draw the diagram as an image'));
+    img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(text)}`;
+  });
+}
+
+export function download(blob, name) {
+  const link = Object.assign(document.createElement('a'), { href: URL.createObjectURL(blob), download: name });
+  document.body.append(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(link.href), 2000);
+}
+
+const slugOf = (s) => String(s || 'diagram').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'diagram';
+
+/** The diagram's name for files: its heading in the document, or "diagram". */
+function nameOf(slot, base) {
+  let el = slot.previousElementSibling;
+  while (el && !/^H[1-4]$/.test(el.tagName)) el = el.previousElementSibling;
+  return `${base ? `${slugOf(base)}-` : ''}${slugOf(el?.textContent)}`;
+}
+
+/** One page with every diagram (and heading) of a rendered document, to keep or attach. */
+export function htmlFile(article, title) {
+  const copy = article.cloneNode(true);
+  copy.querySelectorAll('.dg-tools').forEach((t) => t.remove());
+  copy.querySelectorAll('svg').forEach((svg, i) => {
+    const live = article.querySelectorAll('svg')[i];
+    if (live) svg.outerHTML = svgText(live, { background: null }).text;
+  });
+  const css = `body{font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;max-width:1000px;margin:32px auto;padding:0 16px;color:#1c2330;background:#fff}
+h1{font-size:24px}h2{font-size:18px;margin-top:28px;border-top:1px solid #dde1e7;padding-top:14px}
+.diagram{display:flex;justify-content:center;margin:12px 0;overflow-x:auto}svg{max-width:100%;height:auto}`;
+  const html = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title.replace(/</g, '&lt;')}</title><style>${css}</style></head><body>${copy.innerHTML}</body></html>`;
+  return new Blob([html], { type: 'text/html' });
+}
+
+/** Clicks on any diagram's buttons, wherever it is drawn. `base` names the files (the agent). */
+export function initExport({ toast, base = () => '' }) {
+  document.addEventListener('click', async (e) => {
+    const b = e.target.closest('[data-dg]');
+    if (!b) return;
+    const slot = b.closest('.diagram');
+    const svg = slot?.querySelector('svg');
+    if (!svg) return;
+    const name = nameOf(slot, base(slot));
+    try {
+      if (b.dataset.dg === 'svg') download(new Blob([svgText(svg).text], { type: 'image/svg+xml' }), `${name}.svg`);
+      else if (b.dataset.dg === 'png') download(await pngBlob(svg), `${name}.png`);
+      else {
+        // Safari wants the promise handed over within the click.
+        await navigator.clipboard.write([new ClipboardItem({ 'image/png': pngBlob(svg) })]);
+        toast('Diagram copied as an image: paste it into Slack, a PR comment or a doc');
+      }
+    } catch (err) {
+      toast(b.dataset.dg === 'copy' ? `Couldn't copy (${err.message}); use PNG instead` : `Couldn't export: ${err.message}`, 5000);
+    }
+  });
+}

package/public/index.html

@@ -378,7 +378,9 @@
         <button type="button" id="doc-bg" class="small" hidden title="Close this and keep writing; you'll be told when it's ready">Continue in background</button>
         <button type="button" id="doc-regen" class="small" title="Write it again from the agent's latest work">Regenerate</button>
         <button type="button" id="doc-copy" class="small" title="Copy as Markdown">Copy Markdown</button>
+        <span id="doc-listen"></span>
         <button type="button" id="doc-download" class="small">Download .md</button>
+        <button type="button" id="doc-html" class="small" hidden title="One HTML file with every diagram: open it anywhere, attach it, or print it">Download .html</button>
         <button type="button" id="doc-print" class="small primary" title="Open a print-ready page (Save as PDF)">Print / PDF</button>
         <button type="button" id="doc-close" class="small ghost">Close</button>
       </div>

package/public/land.js

@@ -25,7 +25,7 @@ export function prChips(pr, esc) {
   return out.join(' ');
 }
 
-export function initLand({ api, esc, toast, agents, $, select, openReview, isOpen }) {
+export function initLand({ api, esc, toast, agents, $, scoreBadge = () => '', select, openReview, isOpen }) {
   const view = $('#land-view');
   let settings = null;
 
@@ -46,7 +46,7 @@ export function initLand({ api, esc, toast, agents, $, select, openReview, isOpe
       <div class="line1"><span class="prio p${a.priority ?? 2}">P${a.priority ?? 2}</span>
         <a class="name" href="${esc(pr.url)}" target="_blank" rel="noopener" title="${esc(pr.title ?? pr.url)}">#${esc(pr.number ?? '')} ${esc(pr.title ?? pr.url)}</a></div>
       <div class="line2"><button class="link" data-land="goto">${esc(a.name)}</button>${a.runtime?.busy ? ' <span class="hint">working</span>' : ''}</div>
-      <div class="land-chips">${prChips(pr, esc)}</div>
+      <div class="land-chips">${scoreBadge(a.docs?.scorecard, esc)} ${prChips(pr, esc)}</div>
       <div class="bl-actions">
         <button class="small" data-land="review" title="Its diff, line comments for the agent, commit and push">Review</button>
         ${land === 'behind' || pr.mergeable === 'CONFLICTING' ? '<button class="small" data-land="update" title="Merge the base branch in here (when the agent is idle and its work is committed) and push; otherwise, or on conflicts, ask the agent">Update</button>' : ''}

package/public/review.js

@@ -1,7 +1,9 @@
 // Review screen: an agent's changes file by file, line comments sent back to the agent as one
 // message, and Commit / Push & open PR. Comments not sent yet are kept per agent in this browser.
 // With a walkthrough, each hunk shows its explanation and ◀ / ▶ step through them in reading order.
-import { cardHtml, explainButton, stepOf, walkthroughOf } from './walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, stepOf, walkthroughOf } from './walkthrough.js';
+import { listenHtml, now as speaking, stop as stopSpeaking } from './speak.js';
+import { scorecardHtml, scorecardOf } from './scorecard.js';
 
 /** Unified diff -> [{ path, status, binary, hunks: [{ head, lines: [{ t, old, new, text }] }] }] */
 export function parseDiff(text) {
@@ -137,7 +139,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     for (const h of f.hunks) {
       const i = w.doc ? stepOf(w.doc, f.path, h.head) : -1;
       if (i >= 0) rows.push(`<tr class="rv-explain ${st.step === i ? 'current' : ''}" id="rv-step-${i}"><td colspan="3">${cardHtml(w.doc.data.changes[i], i, w.doc.data.changes.length, esc)}</td></tr>`);
-      rows.push(`<tr class="rv-hunk"><td colspan="3">${esc(h.head)}</td></tr>`);
+      rows.push(`<tr class="rv-hunk" data-rv-hunk="${esc(`${f.path}\t${h.head}`)}"><td colspan="3">${esc(h.head)}</td></tr>`);
       for (const l of h.lines) {
         const side = l.t === 'del' ? 'old' : 'new';
         const line = side === 'old' ? l.old : l.new;
@@ -156,6 +158,32 @@ export function initReview({ api, esc, toast, agents, $ }) {
     return `<div class="rv-file" id="rv-${encodeURIComponent(f.path)}">${head}<table class="rv-table">${rows.join('')}</table></div>`;
   }
 
+  /** The review scorecard at the top: scores, verdict and where to look, or the button to score. */
+  function scorePanel() {
+    if (!st.data?.files.length) return '';
+    const sc = scorecardOf(agents.get(st.id), st.data.diffHash);
+    const openPr = st.data.prs.find((p) => p.state === 'OPEN');
+    const run = `<button type="button" class="small ${sc.doc && !sc.stale ? 'ghost' : 'primary'}" data-sc-run ${sc.pending ? 'disabled' : ''} title="Score the changes against the intent, spec, plan and tests, with where to look (a separate one-off call)">${sc.pending ? 'Scoring…' : sc.doc ? (sc.stale ? 'Score again (changed)' : 'Score again') : '📊 Score changes'}</button>`;
+    if (!sc.doc) {
+      return `<div class="rv-score-empty">${run}<span class="hint">${sc.error && !sc.pending ? `<span class="error">Couldn't score: ${esc(sc.error)}</span>` : 'Scores against the intent, spec, scope, plan, tests and safety, with an overall readiness and the few places to read.'}</span></div>`;
+    }
+    const post = openPr ? `<button type="button" class="small ghost" data-sc-post title="Post the scorecard on the pull request as a comment (posting again updates it)">${sc.doc.postedTo === openPr.url ? 'Update on PR' : 'Post to PR'}</button>` : '';
+    return `<div class="rv-score">${scorecardHtml(sc.doc, esc, { stale: sc.stale, actions: `${listenHtml(`score:${st.id}`, { title: 'Hear the scorecard' })}${post}${run}` })}</div>`;
+  }
+
+  /** Open the file of a hunk (from "where to look") and scroll to it. */
+  function gotoHunk(key) {
+    const [file] = key.split('\t');
+    st.collapsed.delete(file);
+    keepInputs();
+    render();
+    const row = [...body.querySelectorAll('[data-rv-hunk]')].find((r) => r.dataset.rvHunk === key);
+    if (!row) return toast('That part of the change has moved since it was scored');
+    row.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    row.classList.add('flash');
+    setTimeout(() => row.classList.remove('flash'), 1600);
+  }
+
   /** Explain changes, then ◀ n of N ▶ once there is a walkthrough. */
   function walkNav() {
     const w = walk();
@@ -163,7 +191,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     const nav = n
       ? `<span class="rv-walk"><button type="button" class="small ghost" data-rv-step="-1" title="Previous change ([)">◀</button><span class="hint">${st.step == null ? `${n} changes` : `${st.step + 1} of ${n}`}</span><button type="button" class="small ghost" data-rv-step="1" title="Next change (])">▶</button></span>`
       : '';
-    return `${nav}${explainButton(w, 'data-rv-explain')}`;
+    return `${nav}${n ? listenHtml(`walk:${st.id}`, { title: 'Hear the changes one by one; each is shown as it is read' }) : ''}${explainButton(w, 'data-rv-explain')}`;
   }
 
   function walkNote() {
@@ -220,6 +248,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
         ${d.files.length ? walkNav() : ''}
         <button type="button" class="small ghost" data-rv-reload>${st.loading ? 'Loading…' : 'Reload'}</button>
       </div>
+      ${scorePanel()}
       ${walkNote()}
       ${d.busy ? '<p class="hint rv-warn">The agent is working, so the changes may still move. Reload when it is idle.</p>' : ''}
       ${d.truncated ? '<p class="hint rv-warn">The diff is large and was cut short; open a shell for the rest.</p>' : ''}
@@ -288,6 +317,29 @@ export function initReview({ api, esc, toast, agents, $ }) {
     if (t.closest('[data-rv-reload]')) return keepInputs(), reload();
     const stepBtn = t.closest('[data-rv-step]');
     if (stepBtn) return step(Number(stepBtn.dataset.rvStep));
+    const look = t.closest('[data-sc-look]');
+    if (look) return gotoHunk(look.dataset.scLook);
+    if (t.closest('[data-sc-run]')) {
+      keepInputs();
+      try {
+        agents.set(st.id, await api('POST', `/agents/${st.id}/docs/scorecard?background=1`));
+        render();
+      } catch (err) {
+        toast(`Error: ${err.message}`, 5000);
+      }
+      return;
+    }
+    if (t.closest('[data-sc-post]')) {
+      t.disabled = true;
+      try {
+        const r = await api('POST', `/agents/${st.id}/scorecard/post`);
+        toast(r.edited ? 'Scorecard updated on the pull request' : 'Scorecard posted on the pull request', 4000, { label: 'Open', run: () => window.open(r.url, '_blank', 'noopener') });
+      } catch (err) {
+        toast(`Error: ${err.message}`, 6000);
+      }
+      t.disabled = false;
+      return;
+    }
     if (t.closest('[data-rv-explain]')) {
       keepInputs();
       try {
@@ -432,6 +484,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
 
   $('#review-close').onclick = () => dlg.close();
   dlg.addEventListener('close', () => {
+    if (speaking()?.id.startsWith('walk:')) stopSpeaking();
     st.id = null;
     st.note = st.msg = st.prTitle = '';
   });
@@ -440,12 +493,21 @@ export function initReview({ api, esc, toast, agents, $ }) {
   function agentChanged(a) {
     if (!dlg.open || a.id !== st.id || !st.data) return;
     const w = a.docs?.walkthrough;
-    const sig = `${w?.at}|${w?.pending}|${w?.error}`;
+    const sc = a.docs?.scorecard;
+    const sig = `${w?.at}|${w?.pending}|${w?.error}|${sc?.at}|${sc?.pending}|${sc?.error}|${sc?.postedTo}`;
     if (sig === st.walkSig) return;
     st.walkSig = sig;
     keepInputs();
     render();
   }
 
-  return { open, agentChanged, get openId() { return dlg.open ? st.id : null; } };
+  /** What Listen reads: the summary, then each change still in the diff, shown as it is read. */
+  function listenParts() {
+    const w = walk();
+    if (!w.doc) return [];
+    const ok = new Set(present(w));
+    return walkParts(w.doc.data, (i) => (ok.has(i) ? () => gotoStep(i) : null)).filter((p) => typeof p === 'string' || ok.has(p.i));
+  }
+
+  return { open, agentChanged, listenParts, get openId() { return dlg.open ? st.id : null; } };
 }