create-pmos 0.7.3 → 0.8.0

package/README.md

@@ -333,6 +333,50 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.8.0
+
+**The document review is gone. There is a document editor instead.**
+
+Minor, not patch: a feature that shipped in 0.7.0–0.7.3 has been **removed**, and what replaces it is
+a different thing with a different point. If you were using the review surface, it is not there any
+more — read on.
+
+### Why it went
+
+It answered a question nobody asked. An agent read your planning documents and told you what it
+thought was wrong with them, before you had touched anything. What was actually wanted was the
+opposite direction: **you** edit a document, and the tooling reacts to *your* change.
+
+**It also never fully worked.** The browser's Edit → Apply path depended on a script the server was
+never configured to serve, so it 404'd silently in every version that shipped it. The tests that
+covered it went straight to the endpoint and never exercised the path a person takes. If you tried to
+edit a proposal and apply it and nothing happened, that was why, and it was our bug.
+
+### What replaces it
+
+- **Edit any markdown document in the reader.** `edit` in the document header; `save`, `cancel` and
+  `history` while you are in it. ⌘S saves.
+- **The diff is beside you as you type** — the replaced lines struck through, the new ones marked,
+  with a running `+n −n` and the line the change starts at. Nothing to summon; it appears when the
+  document differs from what you opened.
+- **A save that refuses rather than clobbers.** If the file changed on disk since you opened it, the
+  save fails and says so, and **your text stays in the editor** so you can copy it out. It will not
+  merge over whoever changed it.
+- **Every save is logged, per repository.** What changed, where, and — if you write one — why. It
+  lands in your repo's own state directory, never in the installed app. `history` in the document
+  header shows that document's own log.
+
+The log records the changed region and your reason, **not a parallel history of your repository**.
+`git log` remains the record of what your files contain; this records what you changed and why, which
+git has no place to put.
+
+### Not built yet, and named so you are not waiting for it
+
+Two halves of the intended feature are **not** in this release: using a save to work out which *other*
+documents are now out of step and drafting the edits that would realign them, and feeding the
+accumulated change log to agents as context. The editor, the diff and the log are here; the
+propagation is not.
+
 ## What's new in 0.7.3
 
 **A fix — read this if you ran a document review on 0.7.1 or 0.7.2, and especially if you have more

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@56ab797
+kernel-source: pmos@f56d5eb
 assembled: 2026-07-28
 mode: vendor

package/workspace/lib/apply-change.js

@@ -102,5 +102,55 @@
     return { ok: true, text: r.text, eol: r.eol };
   }
 
-  return { applyChange, changeStat, matchesRendered, detectEol };
+  /**
+   * Save a whole edited document (workspace-doc-editor R3).
+   *   current — the file on disk right now
+   *   base    — the text the editor loaded, i.e. what the PM's edit was made against
+   *   next    — what they wrote
+   * Refuses when `current` no longer matches `base`: the document moved under the PM, and writing
+   * `next` would silently discard whoever changed it. Same stance as applyChange's stale check —
+   * refuse loudly rather than merge — but for the case where the whole document is the unit.
+   */
+  function saveWhole(current, base, next) {
+    if (typeof current !== 'string' || typeof base !== 'string' || typeof next !== 'string') {
+      return { ok: false, reason: 'not-text' };
+    }
+    if (toLf(current) !== toLf(base)) {
+      return { ok: false, reason: 'stale', detail: 'this document changed on disk since you opened it' };
+    }
+    if (toLf(current) === toLf(next)) return { ok: false, reason: 'no-change' };
+    const eol = detectEol(current);
+    const out = toLf(next);
+    return { ok: true, text: eol === '\n' ? out : out.replace(/\n/g, eol), eol };
+  }
+
+  /**
+   * The changed REGION of an edit, for the change log (R4/R8).
+   *
+   * Common leading and trailing lines are trimmed away, leaving the part that actually differs. That
+   * is deliberately not a stored diff history — git holds the repository's content, and R4 says so.
+   * What this exists for is R8: an agent reading the log should see *what the PM tends to change and
+   * how*, which line counts alone cannot convey and whole documents would bury.
+   */
+  function changedRegion(base, next, maxLines = 40) {
+    const a = toLf(base == null ? '' : base).split('\n');
+    const b = toLf(next == null ? '' : next).split('\n');
+    let s = 0;
+    while (s < a.length && s < b.length && a[s] === b[s]) s++;
+    let e = 0;
+    while (e < a.length - s && e < b.length - s && a[a.length - 1 - e] === b[b.length - 1 - e]) e++;
+    const before = a.slice(s, a.length - e);
+    const after = b.slice(s, b.length - e);
+    const clip = (arr) => (arr.length > maxLines
+      ? arr.slice(0, maxLines).concat([`… ${arr.length - maxLines} more line(s)`]) : arr);
+    return {
+      at_line: s + 1,
+      removed: before.length,
+      added: after.length,
+      before: clip(before).join('\n'),
+      after: clip(after).join('\n'),
+    };
+  }
+
+  return { applyChange, changeStat, matchesRendered, detectEol, saveWhole, changedRegion };
 });

package/workspace/public/app.js

@@ -872,7 +872,7 @@ async function openDoc(pth, kind) {
   }
   try {
     const res = await fetch(`/api/doc?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(pth)}`);
-    if (!res.ok) { body.innerHTML = `<p class="doc-empty">Could not read <code>${esc(pth)}</code>.</p>`; markActiveDoc(pth); refit(); return; }
+    if (!res.ok) { body.innerHTML = `<p class="doc-empty">Could not read <code>${esc(pth)}</code>.</p>`; markActiveDoc(pth); edControls(); refit(); return; }
     const k = res.headers.get('X-Doc-Kind') || 'markdown';
     const text = await res.text();
     if (k === 'html') renderHtmlDoc(body, text);
@@ -883,8 +883,7 @@ async function openDoc(pth, kind) {
   body.querySelectorAll('[data-doc]').forEach((a) => a.onclick = (e) => { e.preventDefault(); openDoc(a.dataset.doc); });
   wireImgFallback(body);
   markActiveDoc(pth);
-  // Only a markdown document can be reviewed, and only a document — never a summoned surface.
-  $('docReview').hidden = !(state.docPath && /\.(md|markdown|mdown|mkd|mdx|skill)$/i.test(state.docPath));
+  edControls();
   refit();
 }
 function markActiveDoc(pth) {
@@ -931,7 +930,6 @@ function renderHtmlDoc(body, text) {
 }
 function closeDoc() {
   state.docPath = null; state.surface = null;
-  $('docReview').hidden = true;
   $('paneDoc').hidden = true;
   $('railSplit').hidden = true;
   $('docBody').innerHTML = '';
@@ -1810,24 +1808,122 @@ $('themeBtn').onclick = () => {
 };
 $('closeDoc').onclick = closeDoc;
 
-// "review" on an open document. The whole point of putting it HERE is that the scope needs no
-// naming — the thing to review is the thing you are reading. The server assembles the prompt
-// (skill body + resolved paths) because a tenant repo has no workspace/ folder to point at.
-$('docReview').onclick = async () => {
+// ── the document editor (workspace-doc-editor) ────────────────────────────────────────────────
+// The reader gains an edit mode. Nothing an agent produced can reach this path: the PM opens a
+// document, changes it, and saves. Alignment happens AFTER, from the change — never before it.
+//
+// `base` is the text the editor loaded. It travels with the save so the server can refuse if the
+// file moved on disk in the meantime, rather than quietly discarding whoever changed it.
+const ed = { on: false, path: null, base: '', dirty: false };
+
+function edControls() {
+  const isMd = !!(state.docPath && /\.(md|markdown|mdown|mkd|mdx|skill)$/i.test(state.docPath));
+  $('docEdit').hidden = !isMd || ed.on;
+  $('docHistory').hidden = !isMd || ed.on;
+  $('docSave').hidden = !ed.on;
+  $('docCancel').hidden = !ed.on;
+}
+
+async function edOpen() {
   const pth = state.docPath;
   if (!pth) return;
-  const btn = $('docReview');
-  btn.disabled = true; btn.textContent = 'starting…';
+  let text = '';
+  try {
+    const r = await fetch(`/api/doc?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(pth)}`);
+    if (!r.ok) { flash('could not open this document for editing'); return; }
+    text = await r.text();
+  } catch { flash('could not reach the workspace server'); return; }
+
+  ed.on = true; ed.path = pth; ed.base = text; ed.dirty = false;
+  $('docBody').innerHTML = `<div class="ed-wrap">
+      <div class="ed-split" data-diff="off">
+        <textarea class="ed-ta" id="edTa" spellcheck="false"></textarea>
+        <div class="ed-diff" id="edDiff"></div>
+      </div>
+      <div class="ed-bar">
+        <span class="n" id="edStat">no changes yet</span>
+        <input id="edNote" placeholder="why (optional — it is what makes the log worth reading)" autocomplete="off" />
+      </div>
+    </div>`;
+  $('edTa').value = text;
+  $('edTa').oninput = edRender;
+  $('edTa').focus();
+  edControls();
+  refit();
+}
+
+// The diff is a VIEW of the edit in progress, computed from the same module the server saves
+// through — so what is shown and what is written cannot disagree. It is never stored (R4: git holds
+// the repository's content; the change log holds what changed and why).
+function edRender() {
+  const next = $('edTa').value;
+  ed.dirty = next !== ed.base;
+  const r = window.ApplyChange.changedRegion(ed.base, next);
+  const split = $('docBody').querySelector('.ed-split');
+  split.dataset.diff = ed.dirty ? 'on' : 'off';
+  $('edStat').innerHTML = ed.dirty
+    ? `<b>+${r.added}</b> <i>−${r.removed}</i> · from line ${r.at_line} · <span class="dirty">unsaved</span>`
+    : 'no changes yet';
+  if (!ed.dirty) { $('edDiff').innerHTML = ''; return; }
+  const rows = [];
+  if (r.before) r.before.split('\n').forEach((l) => rows.push(`<div class="ed-l del"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`));
+  if (r.after) r.after.split('\n').forEach((l) => rows.push(`<div class="ed-l add"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`));
+  $('edDiff').innerHTML = rows.join('') || '<div class="ed-none">whitespace only</div>';
+}
+
+function edClose(reload) {
+  ed.on = false; ed.path = null; ed.base = ''; ed.dirty = false;
+  edControls();
+  if (reload && state.docPath) openDoc(state.docPath);
+}
+
+async function edSave() {
+  if (!ed.on) return;
+  const text = $('edTa').value;
+  if (text === ed.base) { flash('nothing changed'); return; }
+  const btn = $('docSave'); btn.disabled = true;
   let out = {};
   try {
-    out = await (await fetch('/api/review/start', { method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ws: state.wsId, path: pth }) })).json();
+    out = await (await fetch('/api/doc/save', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ws: state.wsId, path: ed.path, base: ed.base, text, note: $('edNote').value }) })).json();
   } catch { out = { ok: false, error: 'could not reach the workspace server' }; }
-  btn.disabled = false; btn.textContent = 'review';
-  if (!out.ok) { flash(out.error || 'could not start the review'); return; }
-  flash('reviewing ' + pth.split('/').pop() + ' — watch the session');
-  if (out.sessionId) selectSession(out.sessionId);
+  btn.disabled = false;
+  if (!out.ok) {
+    // Refused — say so where the PM is looking, and DO NOT close: their text is still in the box.
+    const box = $('docBody').querySelector('.ed-wrap');
+    let e = box.querySelector('.ed-err');
+    if (!e) { e = document.createElement('div'); e.className = 'ed-err'; box.insertBefore(e, box.querySelector('.ed-bar')); }
+    e.textContent = out.error === 'stale'
+      ? (out.detail || 'this document changed on disk since you opened it') + ' — your text is still here; copy it before reopening.'
+      : (out.detail || out.error || 'the save was refused');
+    return;
+  }
+  flash(out.warning ? 'saved — but the change could not be logged' : `saved · +${out.change.added} −${out.change.removed}`);
+  edClose(true);
+}
+
+$('docEdit').onclick = edOpen;
+$('docCancel').onclick = () => edClose(true);          // closing IS the whole of "cancel writes nothing"
+$('docSave').onclick = edSave;
+$('docHistory').onclick = async () => {
+  const pth = state.docPath; if (!pth) return;
+  let out = {};
+  try { out = await (await fetch(`/api/doc/changes?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(pth)}`)).json(); }
+  catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  if (!out.ok) { flash(out.error || 'could not read the change log'); return; }
+  const rows = (out.changes || []).map((c) => `<div class="hist-row">
+      <div class="hist-when"><b>+${c.added}</b> <i>−${c.removed}</i> · line ${c.at_line} · ${esc((c.at || '').replace('T', ' ').replace(/\..*$/, ''))}</div>
+      ${c.note ? `<div class="hist-note">${esc(c.note)}</div>` : ''}
+    </div>`).join('');
+  $('docBody').innerHTML = `<div class="hist"><h3>Your changes to this document</h3>
+    <div class="sub">Recorded here as you saved them. The document's own history is <span class="mono">git log</span>; this is what changed and why.</div>
+    ${rows || '<div class="hist-none">You have not changed this document here yet.</div>'}</div>`;
+  refit();
 };
+document.addEventListener('keydown', (e) => {
+  if (ed.on && (e.metaKey || e.ctrlKey) && e.key === 's') { e.preventDefault(); edSave(); }
+});
+
 
 // ── ⌘K / Ctrl-K jump palette (client-side: workspaces + sessions + initiatives + docs) ──
 // ── on-demand surfaces (Plan · Deliver · Measure · Report) ─────────────────────────────────────
@@ -1843,11 +1939,6 @@ const SURFACES = [
   { name: 'needs', label: 'needs you', phase: 'deliver', console: true },
   { name: 'radar', label: 'radar', phase: 'measure', console: true },
   { name: 'metrics', label: 'metrics', phase: 'measure', console: true },
-  // The summoned document review (workspace-review-and-edit). Summoned like every surface here and
-  // never resident — nothing reviews the PM's documents until they ask. The only INTERACTIVE surface:
-  // each finding is disposed of by Apply / Edit / Dismiss, and each disposition writes a correction
-  // record. Whether an Apply control exists at all is decided by the finding contract, never here.
-  { name: 'review', label: 'review', phase: 'deliver', review: true },
 ];
 const SURFACE_BY_NAME = {}; SURFACES.forEach((v) => { SURFACE_BY_NAME[v.name] = v; });
 const SF_STAT = { planning: ['○', 'planning'], building: ['◐', 'building'], blocked: ['◆', 'blocked'], landed: ['▲', 'landed'] };
@@ -1856,7 +1947,7 @@ async function openSurface(name) {
   showRail();
   $('paneDoc').hidden = false; $('railSplit').hidden = false; foldPane('doc', true);
   state.surface = name; state.docPath = null;
-  $('docReview').hidden = true;
+  ed.on = false; edControls();
   document.querySelectorAll('.doc').forEach((b) => b.classList.remove('on'));
   $('crumb').innerHTML = `<bdi>surface · ${esc(name)}</bdi>`;
   $('docBody').scrollTop = 0;
@@ -1865,18 +1956,15 @@ async function openSurface(name) {
   $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name)}<div class="sf-body"><div class="sf-skel"><i></i><i></i><i></i></div></div></div>`;
   wireSurface();
   const meta = SURFACE_BY_NAME[name] || {};
-  const endpoint = meta.review
-    ? `/api/review?ws=${encodeURIComponent(state.wsId || '')}`
-    : meta.console
+  const endpoint = meta.console
       ? `/api/console?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`
       : `/api/surface?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`;
   try {
     const r = await fetch(endpoint);
     const payload = await r.json();
-    const body = meta.review ? reviewBody(payload) : meta.console ? consoleBody(name, payload) : surfaceBody(name, payload);
+    const body = meta.console ? consoleBody(name, payload) : surfaceBody(name, payload);
     const okFlag = payload.ok !== false;
     $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name, okFlag)}<div class="sf-body">${body}</div></div>`;
-    if (meta.review) { state.review = payload; wireReview(); }
   } catch {
     // A failed FETCH is a broken read — render RED, never a calm "nothing here" (honesty by construction).
     $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name, false)}<div class="sf-body">${csError(name, 'could not reach the workspace server to build this surface')}</div></div>`;
@@ -1902,195 +1990,6 @@ function wireSurface() {
   document.querySelectorAll('[data-open-surface]').forEach((b) => b.onclick = () => openSurface(b.dataset.openSurface));
   $('docBody').querySelectorAll('.sf-art[data-doc]').forEach((b) => b.onclick = () => openDoc(b.dataset.doc));
 }
-// ── the summoned review (workspace-review-and-edit) ───────────────────────────────────────────
-// Renders findings in the quiet register the PM validated on the prototype: no cards, no severity
-// colours, no taxonomy headers, no explanation of its own guardrails. Each finding is a title and a
-// source line; the argument and the actions appear on expansion. Detail is AVAILABLE, not ambient.
-//
-// The load-bearing line is `f.applyable`. It comes from the SERVER, which asks finding-contract.js —
-// the client never re-derives it. A withheld finding renders no Apply control at all: the missing
-// button IS the guard (R7), and a disabled-but-present button would be the failure it exists to stop.
-function reviewBody(p) {
-  if (!p || p.ok === false) {
-    return csError('review', (p && p.error) || 'the review could not be read')
-      + (p && p.errors ? `<ul class="rv-errs">${p.errors.map((e) => `<li>${esc(e)}</li>`).join('')}</ul>` : '');
-  }
-  if (p.empty) {
-    return `<div class="rv-empty"><p>No review filed yet.</p>
-      <p class="rv-dim">Run the <b>Review documents</b> skill on the documents you want read.
-      Nothing reviews them until you ask.</p></div>`;
-  }
-  const open = p.findings.filter((f) => !f.settled);
-  const lede = open.length === 0
-    ? 'Nothing here that these documents cannot already tell you about themselves.'
-    : `${open.length} thing${open.length === 1 ? '' : 's'} ${open.length === 1 ? 'this document cannot' : 'these documents cannot'} tell you about ${open.length === 1 ? 'itself' : 'themselves'}.`;
-  return `<div class="rv">
-    <div class="rv-lede">${esc(lede)}</div>
-    <div class="rv-sub">Read ${p.read.map((r) => `<span class="mono">${esc(r)}</span>`).join(', ')}.</div>
-    ${p.findings.map((f, i) => rvFinding(f, i)).join('')}
-    <div class="rv-tail">Read ${p.read.length} document${p.read.length === 1 ? '' : 's'}. <b>Nothing written.</b>${rvStats(p.stats)}</div>
-  </div>`;
-}
-// The PRD's success signal, on the face of the surface. Action rate comes straight off the correction
-// records. Quiet-rate CANNOT — it needs a corpus with a labelled clean class, which does not exist —
-// so it says "not measured" rather than rendering a flattering zero. An unmeasured number shown as a
-// number is the watermelon this whole surface exists to catch.
-function rvStats(s) {
-  if (!s || !s.dispositions) return '';
-  const pct = (v) => (v == null ? null : `${Math.round(v * 100)}%`);
-  const bits = [
-    `${s.dispositions} disposition${s.dispositions === 1 ? '' : 's'}`,
-    `${s.corrections} correction${s.corrections === 1 ? '' : 's'}`,
-    `acted on ${pct(s.action_rate)}`,
-    `quiet on clean <i>not measured</i>`,
-  ];
-  const warn = s.inferred_attributions
-    ? ` <b class="rv-bad">${s.inferred_attributions} inferred attribution${s.inferred_attributions === 1 ? '' : 's'}</b>`
-    : '';
-  return `<div class="rv-stats">${bits.join(' · ')}${warn}</div>`;
-}
-function rvFinding(f, i) {
-  const ev = (f.evidence || []).map((e) => `${e.file}:${e.line}`).join(' · ');
-  // Three states, and only one of them offers a write. `settled` is terminal for this review.
-  const acts = f.settled
-    ? `<span class="rv-only">${esc(f.settled === 'dismiss' ? 'Dismissed.' : f.settled === 'edit' ? 'Edited and applied.' : 'Applied.')}</span>`
-    : f.applyable
-      ? `<button data-rv-apply="${i}">Apply</button><button data-rv-edit="${i}">Edit</button><button class="q" data-rv-dismiss="${i}">Dismiss</button>`
-      : `<span class="rv-only">${esc(f.withheld ? 'Yours to settle.' : 'Nothing to apply.')}</span><button class="q" data-rv-dismiss="${i}">Dismiss</button>`;
-  return `<div class="rv-f${f.settled ? ' rv-done' : ''}${f.applyable ? '' : ' rv-quiet'}" data-rv="${i}">
-    <div class="rv-h">${esc(f.title)}</div>
-    <div class="rv-src">${esc(ev || f.file)}</div>
-    <div class="rv-d">
-      <p>${esc(f.argument)}</p>
-      ${f.withheld_reason ? `<p class="rv-why">${esc(f.withheld_reason)}</p>` : ''}
-      <div class="rv-acts">${acts}</div>
-    </div>
-    <div class="rv-ed" data-rv-edbox="${i}"></div>
-  </div>`;
-}
-// The edit surface: opens IN PLACE under the finding — no modal, no mode switch, no navigation.
-// Gutter change bars are the VS Code cue; the replaced lines sit struck through above the new ones.
-// Cancel needs no write path at all — it just closes, which is the whole of "Cancel writes nothing".
-// The reason taxonomy, deliberately short. A vocabulary nobody can hold in their head gets skipped,
-// and a skipped reason is a record that teaches nothing. Values match correction-record.js's REASONS;
-// the server rejects anything outside it, so this list can never drift into inventing one.
-const RV_REASONS = [
-  ['factually-wrong', 'factually wrong'], ['incomplete', 'incomplete'],
-  ['wrong-scope', 'wrong scope'], ['style', 'style'], ['other', 'other…'],
-];
-function rvEditor(f, i) {
-  const before = (f.proposal && f.proposal.before) || '';
-  const after = (f.proposal && f.proposal.after) || '';
-  const nl = (s) => (s ? s.split('\n').length : 0);
-  return `<div class="rv-edfile"><span class="mono">${esc(f.file)}</span>
-      <span class="rv-n"><b>+${nl(after)}</b> <i>−${nl(before)}</i></span></div>
-    <div class="rv-code">
-      ${before.split('\n').map((l) => `<div class="rv-l was"><span class="g"></span><span class="t">${esc(l)}</span></div>`).join('')}
-    </div>
-    <textarea class="rv-ta" data-rv-ta="${i}" spellcheck="false" rows="${Math.min(12, Math.max(3, nl(after) + 1))}">${esc(after)}</textarea>
-    <div class="rv-reason" data-rv-reason="${i}">
-      <span class="rv-only">What was wrong with it?</span>
-      ${RV_REASONS.map((r) => `<button class="rv-rz" data-rv-rz="${i}" data-val="${r[0]}">${esc(r[1])}</button>`).join('')}
-    </div>
-    <input class="rv-note" data-rv-note="${i}" hidden placeholder="in a few words…" aria-label="Why" autocomplete="off" />
-    <div class="rv-acts">
-      <button data-rv-save="${i}">Apply</button>
-      <button class="q" data-rv-cancel="${i}">Cancel</button>
-      <span class="rv-only">You are editing the change, not the file.</span>
-    </div>`;
-}
-function wireReview() {
-  const rv = state.review || {};
-  const F = (n) => (rv.findings || [])[Number(n)];
-  const box = (n) => $('docBody').querySelector(`[data-rv-edbox="${n}"]`);
-  const card = (n) => $('docBody').querySelector(`[data-rv="${n}"]`);
-
-  $('docBody').querySelectorAll('.rv-f').forEach((el) => {
-    el.addEventListener('click', (e) => {
-      if (e.target.closest('button') || e.target.closest('textarea')) return;
-      if (el.dataset.editing === '1') return;                 // never collapse an open editor by clicking it
-      el.classList.toggle('on');
-    });
-  });
-  $('docBody').querySelectorAll('[data-rv-edit]').forEach((b) => b.onclick = () => {
-    const n = b.dataset.rvEdit;
-    box(n).innerHTML = rvEditor(F(n), n);
-    card(n).dataset.editing = '1';
-    wireReview();                                             // re-wire the freshly rendered controls
-    const ta = $('docBody').querySelector(`[data-rv-ta="${n}"]`); if (ta) ta.focus();
-  });
-  $('docBody').querySelectorAll('[data-rv-cancel]').forEach((b) => b.onclick = () => {
-    const n = b.dataset.rvCancel;
-    box(n).innerHTML = ''; card(n).dataset.editing = '0';     // closing IS the whole of "writes nothing"
-  });
-  $('docBody').querySelectorAll('[data-rv-apply]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvApply), 'apply'));
-  $('docBody').querySelectorAll('[data-rv-dismiss]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvDismiss), 'dismiss'));
-  // The reason tap. Required on an edit (R8 / correction-record.js) — an edit is where the agent was
-  // wrong in a way worth knowing, and a record that cannot say HOW is the self-report this feature
-  // exists to replace. Dismiss stays one click: friction belongs on the informative action, not the
-  // common one (PRD open question 2).
-  $('docBody').querySelectorAll('[data-rv-rz]').forEach((b) => b.onclick = () => {
-    const n = b.dataset.rvRz;
-    const row = $('docBody').querySelector(`[data-rv-reason="${n}"]`);
-    row.querySelectorAll('.rv-rz').forEach((x) => x.classList.toggle('on', x === b));
-    row.dataset.picked = b.dataset.val;
-    const note = $('docBody').querySelector(`[data-rv-note="${n}"]`);
-    note.hidden = b.dataset.val !== 'other';                 // 'other' is only useful with words
-    if (b.dataset.val === 'other') note.focus();
-    const nudge = row.querySelector('.rv-nudge'); if (nudge) nudge.remove();
-  });
-  $('docBody').querySelectorAll('[data-rv-save]').forEach((b) => b.onclick = () => {
-    const n = b.dataset.rvSave;
-    const row = $('docBody').querySelector(`[data-rv-reason="${n}"]`);
-    const picked = row && row.dataset.picked;
-    if (!picked) {
-      // An inline nudge, not a modal and not a silent default. Defaulting is what produced the bug
-      // this replaces: every edit recorded "incomplete" whether or not it was.
-      if (!row.querySelector('.rv-nudge')) {
-        const s = document.createElement('span');
-        s.className = 'rv-nudge'; s.textContent = 'Pick one — the record is worth nothing without it.';
-        row.appendChild(s);
-      }
-      return;
-    }
-    const note = $('docBody').querySelector(`[data-rv-note="${n}"]`);
-    const ta = $('docBody').querySelector(`[data-rv-ta="${n}"]`);
-    rvDispose(F(n), 'edit', ta ? ta.value : '', picked, note && !note.hidden ? note.value : undefined);
-  });
-}
-async function rvDispose(f, disposition, pmText, reason, reasonNote) {
-  if (!f) return;
-  const rv = state.review || {};
-  // The client sends back the exact text it rendered; the server re-derives the diff and refuses if
-  // they differ (sprint criterion 4). That is what makes a stale or tampered client safe.
-  let renderedAfter = null;
-  if (disposition !== 'dismiss') {
-    try {
-      const r = await fetch(`/api/doc?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(f.file)}`);
-      const cur = await r.text();
-      const prop = disposition === 'edit' ? { before: f.proposal.before, after: pmText } : f.proposal;
-      renderedAfter = window.ApplyChange.applyChange(cur, prop).text;
-    } catch { /* leave null — the server refuses rather than guessing */ }
-  }
-  const body = {
-    ws: state.wsId, disposition, finding: f, rendered_after: renderedAfter,
-    pm_text: disposition === 'edit' ? pmText : undefined,
-    reason, reason_note: reasonNote,          // the PM's own word — never defaulted, never inferred
-    run_id: rv.id, initiative_id: 'workspace-review-and-edit',
-  };
-  let out = {};
-  try { out = await (await fetch('/api/review/dispose', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) })).json(); }
-  catch { out = { ok: false, error: 'could not reach the workspace server' }; }
-  if (!out.ok) { rvSay(out.error || 'refused', out.detail); return; }
-  openSurface('review');                                       // re-read: the record is the source of truth
-}
-function rvSay(msg, detail) {
-  const el = document.createElement('div');
-  el.className = 'rv-say';
-  el.textContent = detail ? `${msg} — ${detail}` : msg;
-  $('docBody').querySelector('.rv') ? $('docBody').querySelector('.rv').prepend(el) : $('docBody').prepend(el);
-}
-
 function surfaceBody(name, payload) {
   if (!payload || !payload.ok) return sfCantProduce(name, payload && payload.contract);
   const s = payload.surface || {};

package/workspace/public/index.html

@@ -187,7 +187,10 @@
         <div class="cap">
           <button class="fold" id="docFold" aria-expanded="true" title="Hide the document"><span class="chev" aria-hidden="true">▾</span>document</button>
           <span class="crumb" id="crumb"></span>
-          <button class="mini docrev" id="docReview" hidden title="Have an agent review this document">review</button>
+          <button class="mini docrev" id="docEdit" hidden title="Edit this document">edit</button>
+          <button class="mini docrev" id="docSave" hidden title="Save (⌘S)">save</button>
+          <button class="mini docrev" id="docCancel" hidden title="Discard changes">cancel</button>
+          <button class="mini docrev" id="docHistory" hidden title="Changes you have made to this document">history</button>
           <button class="x" id="closeDoc" aria-label="Close document">✕</button>
         </div>
         <div class="pane-body doc-body" id="docBody" tabindex="0"></div>
@@ -257,9 +260,8 @@
 <script src="/vendor/addon-web-links.js"></script>
 <script src="/lib/preview-kind.js"></script>
 <script src="/lib/layout.js"></script>
-<!-- Both sides of the review must agree about what is applyable and what a change produces, so the
-     browser loads the SAME modules the server requires — the client never re-derives either. -->
-<script src="/lib/finding-contract.js"></script>
+<!-- The editor computes its diff with the SAME module the server saves through, so what you see
+     while editing and what the server writes can never disagree. -->
 <script src="/lib/apply-change.js"></script>
 <script src="/app.js"></script>
 </body>