create-pmos 0.150.0 → 0.152.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.150.0",
+  "version": "0.152.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. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `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@3f66dcc
+kernel-source: pmos@159c05c
 assembled: 2026-10-12
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-12T03:30:13Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T03:39:15Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-12T03:30:13Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T03:39:15Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-12T03:30:13Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T03:39:15Z"}
 status: stable
 ---
 

package/workspace/guide/ask-the-agent.md

@@ -12,20 +12,20 @@ Five presses in the console (`/c3.html`) start an agent from the page. You do no
 ## Ask the agent on a document
 
 1. Open a document in Initiatives › Documents, or open a report as a document from Reports.
-2. Select **Ask the agent**, write what to change, and select **Ask the agent** again.
+2. Select **Proposals**, write what to change, and select **Ask the agent**.
 3. The sheet says that the agent is drafting. You can close the sheet and come back.
-4. When the draft is ready, the sheet shows the difference, section by section.
-5. Slide to accept the draft, or select **Change the request** or **Discard**.
+4. When the draft is ready, it shows in **Proposals** with the difference, section by section.
+5. Clear the tick of any section that you do not want, and slide to accept. Or select **Change the request** or **Reject**.
 
 The agent runs in the background and can only read: it has the Read, Glob and Grep tools and nothing else. It answers with the revised document. The workspace records that answer as a proposal. The file does not change until you slide to accept it, and the slide is bound to the proposal's hash. If the document changed while the agent worked, the sheet tells you to ask again.
 
 **Copy the request** stays beside the button. Use it to give the request to a session that you already have open.
 
-On a document's **Health** segment, **Fix with the agent** writes the fix as the request and opens Ask the agent.
+On a document's **Health** segment, **Fix with the agent** writes the fix as the request and opens Proposals.
 
 ## Fix with the agent on a report
 
-In Reports, open a section that is not traced and select **Fix with the agent**. The report opens as a document on Ask the agent, with the fix written in. A report that is not issued yet has no stored document, so the sheet tells you to issue it first.
+In Reports, open a section that is not traced and select **Fix with the agent**. The report opens as a document on Proposals, with the fix written in. A report that is not issued yet has no stored document, so the sheet tells you to issue it first.
 
 ## Lifecycle: a draft, a spike and an early gate
 

package/workspace/guide/console-calendar.md

@@ -21,7 +21,7 @@ Under the title, the note shows its meeting and its initiative. Press **Link to
 
 - **Before** shows what the note kept about its meeting: the agenda, what the meeting is for, what to do to be ready, what to read first, the people, and the meeting: its time, its place and who organized it. A tick shows an agenda item that was heard in the transcript. A note with no meeting says so, and has **Link to a meeting** and **Link to an initiative**.
 - **During** shows the live notes while the note is recorded or paused. At other times it shows the transcript.
-- **After** shows **Replay** first when the sound of the note is kept on this machine. Then it shows the overview, the decisions with why, the next steps with owner and due date, the open questions, the statements that differ from a file, the highlights and the screenshots of the shared screen (**Screen**; press one to see it large). The transcript is folded at the bottom. When the final notes are written, click a text to correct it. Leave the text to save it. Press `Esc` to cancel. **Make task** adds a next step to the note's initiative.
+- **After** shows **Replay** first when the sound of the note is kept on this machine. Then it shows the overview, the decisions with why, the next steps with owner and due date, the open questions, the statements that differ from a file, the highlights and the screenshots of the shared screen (**Screen**; press one to see it large). The transcript is folded at the bottom. Click a text to correct it: the summary, a decision and its why, or a next step, its owner and its due day. Press `Enter` or leave the text to save it. Press `Esc` to cancel. Empty an owner or a due day to clear it. A decision caught while the meeting was recorded has no why. Before the final notes are written, press **Write a summary of the meeting** to write your own summary; empty it to go back to the caught one. **Make task** adds a next step to the note's initiative.
 
 A note that is recorded now opens on **During**. Other notes open on **After**. **Show in the calendar** goes back to the grid, on the day of the meeting, with the meeting selected. The copy button puts the note on the clipboard as Markdown.
 

package/workspace/guide/document-sheet.md

@@ -0,0 +1,58 @@
+---
+type: Guide
+title: "The document sheet"
+description: "How to read a document as rich text, edit it, review the agent's proposals section by section, read the edit log, and clear a stale document."
+timestamp: 2026-10-12
+---
+
+# The document sheet
+
+Open a document in Initiatives › Documents, in an initiative's Docs, or from Reports. The document opens in a sheet on the right. On a phone, it opens from the bottom. The segment under the title has six modes.
+
+## Read
+
+Read shows the document as formatted text: headings, bold, links, tables, checklists and callouts. The front matter shows as properties at the top.
+
+- Each section shows who changed it last: a person, or the agent and the person who accepted it, with the revision and the day. Select the name to open that revision in the edit log.
+- **Show who wrote what** colours each section: blue for a person, purple for the agent.
+- **Markdown source** shows the file as text. **Copy the markdown** copies it.
+- **Contents** goes to a section.
+- When an open proposal changes a section, a note shows above that section. Select **Show change** to see the difference in place.
+
+## Edit
+
+Edit opens the whole document as rich text. Use the toolbar for the paragraph style, bold, italic, code, links, lists, checklists, tables and dividers. Use **Markdown** to edit the same draft as text, and **Rich** to go back. The front matter shows as fields.
+
+1. Change the text. A changed section shows **Edited** next to its heading.
+2. Write why you change it. The sheet does not save a change without a reason.
+3. Select **Save**.
+
+A section that you did not change is saved exactly as it was. The reason goes to the edit log with your name.
+
+## Proposals
+
+Proposals lists what the agent drafted and you did not accept or reject yet. To ask for a change, see [Ask the agent from the page](ask-the-agent.md).
+
+1. Read the difference of each section. Added words are green. Removed words are struck through.
+2. Clear the tick of each section that you do not want.
+3. Slide to accept. Only the ticked sections are written, as one revision.
+
+If a section changed after the agent drafted it, you cannot tick it. Ask the agent again. To reject a proposal, select **Reject** and write why.
+
+## Edit log
+
+The edit log lists every change, newest first: who wrote the text, how it came in, the reason, the sections and the words added and removed. It also lists rejected proposals, requests to the agent, and documents marked as still current. Use **All**, **People**, **Agent** and **Outside PMOS** to filter it.
+
+- A change made outside the sheet (in an editor, or by a commit) shows **outside PMOS**, with its commit when git knows it. When it has no reason, select **Add a reason**. The reason is added to the log; the revision itself does not change.
+- Select **Show the change** to see the difference.
+
+## Stale documents
+
+A document is stale when a document that it links to changed after it. The sheet shows a banner that lists those sources and the sections that cite them.
+
+- Edit the sections, or ask the agent for an update.
+- If the document is still right, select **Mark as still current** and write why. The mark counts as a change, so the banner clears.
+
+## Health and Relations
+
+Health shows the checks of the document and how many pass. Relations shows the documents around this one.

package/workspace/guide/index.md

@@ -69,6 +69,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Integrated work](integrated-work.md): how `pmos verify-work` turns a merged commit into Done, and what "Done · your call · not merged" means.
 - [Report slides](report-slides.md): how the Reports page shows a report as the PM-OS biweekly slides, Present and Print / PDF, and how your notes become the words on the slides.
 - [Reports: dashboards of reports](reports-dashboards.md): the console Reports page, its dashboards at portfolio, board and initiative scope, how to edit and share one as a draft, and the Drafts tab.
+- [The document sheet](document-sheet.md): read a document as rich text, edit it, accept the agent's proposals section by section, read the edit log, and clear a stale document.
 - [Ask the agent from the page](ask-the-agent.md): the five presses that start an agent from the console, what the agent may do, and what stays yours.
 - [Sessions in console3](console3-sessions.md): the Sessions panel, how to open the terminal of a session on the same page, and how to end a session.
 - [Settings in console3](settings.md): how to open Settings, what each section holds, the scope tags, the environment notes, and where the settings are kept.

package/workspace/lib/engine/doc-health.js

@@ -24,8 +24,10 @@ const ts = (v) => { const t = Date.parse(v); return Number.isNaN(t) ? null : t;
 function fresh(doc, c) {
   const at = ts(doc.changed);
   if (at == null) return na('fresh');
-  const newer = (c.sources || []).filter((s) => ts(s.changed) != null && ts(s.changed) > at).map((s) => s.path);
-  if (newer.length) return { id: 'fresh', pass: false, reason: 'a cited source changed after this document: ' + newer.join(', ') };
+  const newerSrc = (c.sources || []).filter((s) => ts(s.changed) != null && ts(s.changed) > at);
+  const newer = newerSrc.map((s) => s.path);
+  // `sources` names each newer source and when it changed, so a page can list them (the document sheet's stale banner)
+  if (newer.length) return { id: 'fresh', pass: false, reason: 'a cited source changed after this document: ' + newer.join(', '), sources: newerSrc.map((s) => ({ path: s.path, changed: s.changed })) };
   if (c.staleAfterDays != null) {
     const now = ts(c.now) != null ? ts(c.now) : Date.now();
     const age = Math.floor((now - at) / day);

package/workspace/lib/engine/doc-sheet.js

@@ -7,6 +7,9 @@
  *   askAgentProposal({ before, after, prompt }) → { state:'proposed', prompt, diff, hash }   only a proposal; nothing is written
  *   acceptProposal(proposal, { hash, by })      → { ok:true, event } | { ok:false, reason }   PM only, hash-bound
  *   changeNote(doc, downstreamDocs)             → a DRAFT note for owners of documents whose source rev is behind; never sent
+ *   splitSections(text)                         → the text cut at its headings: [{ i, prefix, name, lead, text, tail }], joined back exactly
+ *   mergeSections(current, before, after, names) → { ok, text } with only the named sections of `after` applied to `current`;
+ *                                                  { ok:false, stale:[name] } when a named section changed since `before`
  *
  * The slide-to-accept is the same hash-bound confirm as the outbox: the hash covers the proposed text, so an edited
  * proposal has a new hash and the PM's press on the old one is void. An agent can create a proposal and never accept it.
@@ -72,4 +75,49 @@ function changeNote(doc, downstreamDocs) {
   return { draft: true, sent: false, path: doc.path, rev: doc.rev, behind, body };
 }
 
-module.exports = { editWithWhy, revisions, foldAt, askAgentProposal, acceptProposal, changeNote, hashText, proposalHash };
+/* Sections: the same cut as the page's splitDoc (public/pm/c3-doc-sheet.js), so a name means the same section on both sides. */
+function splitSections(text) {
+  const t = String(text == null ? '' : text);
+  const heads = []; let off = 0; let fence = false;
+  for (const line of t.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    if (!fence && /^#{1,6}\s+\S/.test(line)) heads.push({ at: off, line, end: off + line.length + 1 });
+    off += line.length + 1;
+  }
+  const raw = [];
+  const first = heads.length ? heads[0].at : t.length;
+  if (first > 0 || !heads.length) raw.push({ prefix: '', name: /^---\n/.test(t) ? 'Front matter' : 'Overview', body: t.slice(0, first) });
+  heads.forEach((h, i) => raw.push({ prefix: t.slice(h.at, Math.min(h.end, t.length)), name: h.line.replace(/^#+\s+/, '').replace(/\s+#+\s*$/, '').trim(), body: t.slice(Math.min(h.end, t.length), i + 1 < heads.length ? heads[i + 1].at : t.length) }));
+  return raw.map((x, i) => {
+    const lead = x.body.match(/^\s*/)[0]; const rest = x.body.slice(lead.length); const tail = rest.match(/\s*$/)[0];
+    return { i, prefix: x.prefix, name: x.name, lead, tail, text: rest.slice(0, rest.length - tail.length) };
+  });
+}
+const joinSections = (secs) => secs.map((x) => x.prefix + x.lead + x.text + x.tail).join('');
+
+// Apply only the named sections of a proposal. A named section must read in `current` as it read in `before` (the text the
+// proposal was drafted against); otherwise it is stale and nothing is applied. A section new in `after` goes after the
+// section that precedes it there, or last; a section `after` dropped is removed.
+function mergeSections(current, before, after, names) {
+  const C = splitSections(current), B = splitSections(before), P = splitSections(after);
+  const want = [...new Set((names || []).map(String))];
+  const stale = want.filter((n) => { const b = B.find((x) => x.name === n), c = C.find((x) => x.name === n); return b ? (!c || c.text !== b.text) : !!c; });
+  const unknown = want.filter((n) => !B.some((x) => x.name === n) && !P.some((x) => x.name === n));
+  if (unknown.length) return { ok: false, unknown };
+  if (stale.length) return { ok: false, stale };
+  let out = C.map((x) => ({ ...x }));
+  for (const n of want) {
+    const p = P.find((x) => x.name === n); const k = out.findIndex((x) => x.name === n);
+    if (!p) { if (k >= 0) out.splice(k, 1); continue; }
+    if (k >= 0) { out[k] = { ...out[k], text: p.text }; continue; }
+    const prev = P[P.indexOf(p) - 1]; const at = prev ? out.findIndex((x) => x.name === prev.name) : -1;
+    const add = { ...p, tail: p.tail || '\n' };
+    if (at >= 0) { if (!/\n\s*\n$/.test(out[at].tail)) out[at] = { ...out[at], tail: '\n\n' }; out.splice(at + 1, 0, add); }
+    else if (prev === undefined && out.length && out[0].prefix === '' && out[0].name === 'Front matter') out.splice(1, 0, add);
+    else if (prev === undefined) out.unshift(add);
+    else { const l = out.length - 1; if (l >= 0 && !/\n\s*\n$/.test(out[l].tail)) out[l] = { ...out[l], tail: '\n\n' }; out.push(add); }
+  }
+  return { ok: true, text: joinSections(out) };
+}
+
+module.exports = { splitSections, joinSections, mergeSections, editWithWhy, revisions, foldAt, askAgentProposal, acceptProposal, changeNote, hashText, proposalHash };

package/workspace/lib/notes.js

@@ -903,11 +903,11 @@ function summarize(note) {
   // PM labelled it; without bullets, from the lines as before
   const bl = ((note && note.bullets) || []).filter((b) => b && b.text);
   const bitems = bl.map((b, k) => ({ i: n + k, bid: b.id, text: b.text, t: Number.isFinite(b.t) ? b.t : null, src: 'bullet', cat: b.cat || null, by_pm: b.cat_by === 'pm',
-    dropped: !!b.dropped, open: !!b.open, owner: typeof b.owner === 'string' && b.owner ? b.owner : null }));
+    dropped: !!b.dropped, open: !!b.open, owner: typeof b.owner === 'string' && b.owner ? b.owner : null, due: typeof b.due === 'string' && b.due ? b.due : null }));
   const caught = bl.length ? bitems.concat(items.filter((x) => x.src === 'transcript' && x.by_pm)) : items;
   const decisions = cap(caught.filter((x) => kindOf(x, 'decision')).filter(once), 'decisions');
   const actions = cap(caught.filter((x) => kindOf(x, 'action')).filter(once), 'actions')
-    .map((x) => ({ ...x, owner: x.owner || ownerOf(x.text, names), due: dueOf(x.text) }));
+    .map((x) => ({ ...x, owner: x.owner || ownerOf(x.text, names), due: x.due || dueOf(x.text) }));
   const questions = cap(caught.filter((x) => kindOf(x, 'question')).filter(once), 'questions');
   const points = cap(bitems.filter((x) => !x.dropped && !x.open && (x.cat === 'topic' || x.cat === 'statement')).filter(once), 'points');
   const facts = items.filter((x) => x.src === 'transcript' && isFact(x)).filter(once);
@@ -1569,7 +1569,7 @@ function updateBullet(dir, { id, bid, text, patch = {} } = {}) {
   return { ok: true, bullet: b };
 }
 /** The PM's correction to one bullet: its label (the seven), `drop` (out of its section and the summary), or its words. */
-function editBullet(dir, { id, bid, cat, drop, text, now = Date.now() } = {}) {
+function editBullet(dir, { id, bid, cat, drop, text, owner, due, now = Date.now() } = {}) {
   const note = load(dir, id);
   if (!note) return err(404, 'no such note');
   if (!BULLET_ID_RE.test(String(bid || ''))) return err(400, 'that is not a bullet id');
@@ -1583,6 +1583,9 @@ function editBullet(dir, { id, bid, cat, drop, text, now = Date.now() } = {}) {
     if (t.length > MAX_BULLET) return err(413, 'that bullet is too long');
     if (t !== b.text) { if (b.orig_text === undefined) b.orig_text = b.text; b.text = t; delete b.check; }
   }
+  // the PM's owner or due day for a next step; an empty one clears it
+  if (owner !== undefined) { const o = String(owner == null ? '' : owner).replace(/\s+/g, ' ').trim().slice(0, 80); if (o) b.owner = o; else delete b.owner; }
+  if (due !== undefined) { const d = String(due == null ? '' : due).replace(/\s+/g, ' ').trim().slice(0, 60); if (d) b.due = d; else delete b.due; }
   if (cat !== undefined) { b.cat = cat; b.cat_by = 'pm'; delete b.open; }
   if (drop === true) b.dropped = true; else if (drop === false) delete b.dropped;
   refreshLocal(note, now);
@@ -1642,14 +1645,36 @@ function removeHighlight(dir, { id, hid, now = Date.now() } = {}) {
   store(dir, note);
   return { ok: true };
 }
-/** The PM's correction to the final notes: the overview, or the text of one decision, next step or open question. The
- * first words the agent wrote are kept as `orig_text`. */
+/** The PM's correction to the final notes: the overview (before the final notes, the PM's summary of the note), or the text of one decision, next step or open question. The
+ * first words the agent wrote are kept as `orig_text`. `field` corrects another part of one item instead: a next step's
+ * `owner` or `due`, or a decision's `why`; an empty one clears it. */
 const FINAL_SECS = { decision: 'decisions', action: 'actions', question: 'questions' };
-function editFinal(dir, { id, sec, i, text, now = Date.now() } = {}) {
+const FINAL_FIELDS = { action: { owner: 80, due: 60 }, decision: { why: 400 } };
+function editFinal(dir, { id, sec, i, text, field, now = Date.now() } = {}) {
   const note = load(dir, id);
   if (!note) return err(404, 'no such note');
   const f = note.final_notes;
+  // before the final notes exist, the PM's summary is kept beside what was caught live; an empty one goes back to that
+  if (!f && sec === 'overview') {
+    const t = clip(text, 2000);
+    if (t) note.overview_pm = t; else delete note.overview_pm;
+    note.updated_at = iso(now);
+    store(dir, note);
+    return { ok: true, final_notes: null, overview_pm: note.overview_pm || null };
+  }
   if (!f) return err(409, 'this note has no final notes yet');
+  if (field !== undefined && field !== 'text') {
+    const max = (FINAL_FIELDS[sec] || {})[field];
+    if (!max) return err(400, 'a ' + (sec || 'note') + ' has no ' + String(field).slice(0, 20) + ' to correct');
+    const list = f[FINAL_SECS[sec]];
+    const x = Array.isArray(list) ? list[Number(i)] : null;
+    if (!x) return err(404, 'no such item');
+    x[field] = clip(text, max) || null;
+    keepVersion(note, now);
+    note.updated_at = iso(now);
+    store(dir, note);
+    return { ok: true, final_notes: f };
+  }
   const t = clip(text, sec === 'overview' ? 2000 : 400);
   if (!t) return err(400, 'the text is empty');
   if (sec === 'overview') {

package/workspace/lib/routes-doc-health.js

@@ -5,7 +5,7 @@
  *
  * A read: nothing is written and no page press is needed. The file is read from the repository (or the named workspace's
  * root) and refused when it resolves outside that root. From git it derives: the last change of the file, the last change
- * of every relative Markdown link it cites, and the last change of each ADR a `D<n>` id in its text names. Everything
+ * of every relative Markdown link it cites (a save or a "still current" mark in the document sheet counts as a change), and the last change of each ADR a `D<n>` id in its text names. Everything
  * else (requiredHeadings, data, readers, current, staleAfterDays) comes only from `context` in the body; a check without
  * its input answers "not enough input". No write routes in this wave.
  */
@@ -34,7 +34,18 @@ function adrFor(root, id) {
   try { return fs.readdirSync(dir).find((f) => new RegExp('^d0*' + n + '-', 'i').test(f)) || null; } catch { return null; }
 }
 
-function check(root, body) {
+// The document's last change: its last commit, or a later save or "still current" mark in the document sheet, which
+// writes the file without committing it (routes-doc-sheet.js lastSheetChange).
+function lastChange(root, relOut, runtimeDir) {
+  const git = gitChanged(root, relOut);
+  let sheet = null;
+  if (runtimeDir) { try { sheet = require('./routes-doc-sheet.js').lastSheetChange(runtimeDir, relOut); } catch { sheet = null; } }
+  if (!git) return sheet;
+  if (!sheet) return git;
+  return Date.parse(sheet) > Date.parse(git) ? sheet : git;
+}
+
+function check(root, body, runtimeDir) {
   const rel = typeof body.path === 'string' ? body.path : '';
   if (!rel) return bad('path is required');
   const full = path.resolve(root, rel);
@@ -42,7 +53,7 @@ function check(root, body) {
   let text;
   try { if (!inside(root, full)) return bad('outside workspace', 404); text = fs.readFileSync(full, 'utf8'); } catch { return bad('file not found', 404); }
   const relOut = path.relative(root, full);
-  const changed = gitChanged(root, relOut);
+  const changed = lastChange(root, relOut, runtimeDir);
   const sources = [];
   for (const m of text.matchAll(/\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g)) {
     if (/^[a-z]+:/i.test(m[1])) continue;
@@ -73,7 +84,7 @@ module.exports = {
     const body = got.body || {};
     const w = body.ws && ctx.getWs ? ctx.getWs(body.ws) : null;
     if (body.ws && !w) { ctx.json(res, { ok: false, error: 'no workspace' }, 404); return true; }
-    const r = check(w ? w.root : (ctx.root || ROOT), body);
+    const r = check(w ? w.root : (ctx.root || ROOT), body, ctx.runtimeDir);
     ctx.json(res, r.body, r.status);
     return true;
   },

package/workspace/lib/routes-doc-sheet.js

@@ -11,6 +11,17 @@
  *                                                            (lib/headless.js 'ask'); its answer becomes a proposal, never a write
  *   GET  /api/doc-sheet/ask?id=                             → { ok, id, state: working | proposed | failed, error?, proposal? }
  *   POST /api/doc-sheet/change-note { path, downstream? }   a draft body only; nothing is sent
+ *   GET  /api/doc-sheet/proposals?path=          → { ok, proposals: [{ id, state, prompt, at, hash, after, sections: [{ name, kind, stale }] }] }
+ *   GET  /api/doc-sheet/log?path=                → { ok, revisions, events }   the edit log: revisions (with a reason added later) and
+ *                                                  the other entries (proposed, rejected, asked, marked current)
+ *   POST /api/doc-sheet/reject { path, id, why }            page press; a why is required; the proposal is closed, the file untouched
+ *   POST /api/doc-sheet/why { path, rev, why }              page press; a reason for a revision that has none (an outside change);
+ *                                                            appended to annotations.jsonl, the revision itself is not rewritten
+ *   POST /api/doc-sheet/mark-current { path, why }          page press; "still current" with a reason; it counts as the last change
+ *
+ * Every revision says who wrote the text and how it came in: via 'sheet' (an edit here), 'proposal' (accepted; text_by 'agent',
+ * by 'pm', the proposal id and the sections taken) or 'outside' (the file changed outside the sheet; git's last commit of
+ * the file names the author when there is one).
  *
  * Storage (append-only JSONL): <runtime>/doc-sheet/revisions.jsonl, proposals.jsonl and asks.jsonl.
  * The write is the same one /api/doc/save makes: the path must resolve inside the repository root, only Markdown is
@@ -56,12 +67,29 @@ function resolveDoc(root, rel) {
 
 const revsOf = (runtimeDir, rel) => S.revisions(readLines(path.join(dirOf(runtimeDir), 'revisions.jsonl')), rel);
 
+// git's last commit of a file: who and why, when the file is committed as it reads now. Best effort; null otherwise.
+function lastCommit(root, rel, text) {
+  try {
+    const { spawnSync } = require('child_process');
+    const r = spawnSync('git', ['log', '-1', '--format=%h%x09%an%x09%cI%x09%s', '--', rel], { cwd: root, encoding: 'utf8', timeout: 3000 });
+    if (r.status !== 0 || !r.stdout.trim()) return null;
+    const [commit, author, at, subject] = r.stdout.trim().split('\t');
+    const head = spawnSync('git', ['show', commit + ':' + rel.split(path.sep).join('/')], { cwd: root, encoding: 'utf8', timeout: 3000, maxBuffer: 8 << 20 });
+    if (head.status !== 0 || head.stdout !== text) return { committed: false };
+    return { committed: true, commit, author, at, subject: (subject || '').slice(0, 200), agent: /\b(claude|agent|bot)\b/i.test(author || '') };
+  } catch { return null; }
+}
+
 // Record the file's current text first when it moved outside this sheet (or was never seen), so the fold is complete.
-function syncBaseline(runtimeDir, rel, text, now) {
+function syncBaseline(runtimeDir, rel, text, now, root) {
   const revs = revsOf(runtimeDir, rel), last = revs[revs.length - 1];
   if (last && last.after_hash === S.hashText(text)) return last.rev;
   const rev = last ? last.rev + 1 : 1;
-  const ev = { ...S.editWithWhy(last ? last.text : text, text, last ? 'changed outside the sheet' : 'first seen by the sheet', 'baseline', { rev, path: rel, at: now.toISOString() }) };
+  const git = root ? lastCommit(root, rel, text) : null;
+  const why = git && git.committed && git.subject ? git.subject : (last ? 'changed outside the sheet' : 'first seen by the sheet');
+  const ev = { ...S.editWithWhy(last ? last.text : text, text, why, 'baseline', { rev, path: rel, at: now.toISOString() }), via: last ? 'outside' : 'first',
+    why_known: !!(git && git.committed && git.subject) };
+  if (git && git.committed) { ev.git = { commit: git.commit, author: git.author, at: git.at }; ev.text_by = git.agent ? 'agent' : 'person'; }
   append(runtimeDir, 'revisions.jsonl', ev);
   return rev;
 }
@@ -75,21 +103,30 @@ function logChange(ctx, w, rel, before, after, why, by, now) {
   try { fs.mkdirSync(dir, { recursive: true }); fs.appendFileSync(path.join(dir, 'doc-changes.jsonl'), JSON.stringify(rec) + '\n'); return true; } catch { return null; }
 }
 
-function writeDoc(root, rel, before, after, why, runtimeDir, ctx, w, now) {
+function writeDoc(root, rel, before, after, why, runtimeDir, ctx, w, now, extra) {
   const r = resolveDoc(root, rel); if (r.error) return r.error;
   if (r.text !== before) return fail(409, 'stale: the document changed since it was read');
-  syncBaseline(runtimeDir, r.rel, r.text, now);
+  syncBaseline(runtimeDir, r.rel, r.text, now, root);
   const rev = revsOf(runtimeDir, r.rel).length + 1;
-  const ev = S.editWithWhy(before, after, why, 'pm', { rev, path: r.rel, at: now.toISOString() });
+  const ev = { ...S.editWithWhy(before, after, why, 'pm', { rev, path: r.rel, at: now.toISOString() }), via: 'sheet', text_by: 'person', ...(extra || {}) };
   try { fs.writeFileSync(r.full, after); } catch { return fail(500, 'could not write the document — nothing was changed'); }
   append(runtimeDir, 'revisions.jsonl', ev);
   const logged = logChange(ctx, w, r.rel, before, after, why, 'pm', now);
   return { status: 200, body: { ok: true, path: r.rel, rev, revision: { ...ev, text: undefined }, logged: !!logged } };
 }
 
+const annotationsOf = (runtimeDir, rel) => readLines(path.join(dirOf(runtimeDir), 'annotations.jsonl')).filter((a) => a && a.path === rel);
+function revsOut(runtimeDir, rel) {
+  const notes = annotationsOf(runtimeDir, rel);
+  return revsOf(runtimeDir, rel).map(({ text, ...rest }) => {
+    const n = notes.filter((a) => a.rev === rest.rev).pop();
+    return n ? { ...rest, why_added: n.why, why_added_at: n.at } : rest;
+  });
+}
 function revisionsRoute(root, q, runtimeDir) {
   const r = resolveDoc(root, q.path); if (r.error) return r.error;
-  return { status: 200, body: { ok: true, path: r.rel, revisions: revsOf(runtimeDir, r.rel).map(({ text, ...rest }) => rest) } };
+  syncBaseline(runtimeDir, r.rel, r.text, new Date(), root);
+  return { status: 200, body: { ok: true, path: r.rel, revisions: revsOut(runtimeDir, r.rel) } };
 }
 function atRoute(root, q, runtimeDir) {
   const r = resolveDoc(root, q.path); if (r.error) return r.error;
@@ -100,6 +137,14 @@ function atRoute(root, q, runtimeDir) {
   return { status: 200, body: { ok: true, path: r.rel, rev, text } };
 }
 
+/** The last time the document changed through this sheet or was marked current: the Fresh check counts it as a change. */
+function lastSheetChange(runtimeDir, rel) {
+  let t = null;
+  for (const e of revsOf(runtimeDir, rel)) if (e.by !== 'baseline' && e.at && (!t || e.at > t)) t = e.at;
+  for (const m of readLines(path.join(dirOf(runtimeDir), 'marks.jsonl'))) if (m && m.path === rel && m.at && (!t || m.at > t)) t = m.at;
+  return t;
+}
+
 function edit(req, body, ctx, now = new Date()) {
   const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
   if (typeof body.why !== 'string' || !body.why.trim()) return fail(400, 'a why is required: say why the document changes');
@@ -120,11 +165,16 @@ function propose(req, body, ctx, now = new Date()) {
   if (!body || typeof body !== 'object' || Array.isArray(body)) return fail(400, 'body must be an object');
   if (typeof body.after !== 'string') return fail(400, 'after is required');
   const r = resolveDoc(ctx.root, body.path); if (r.error) return r.error;
+  // an agent answering a request from the sheet names the request; its prompt is the PM's words, kept on the request
+  const asked = typeof body.ask === 'string' ? readLines(path.join(dirOf(ctx.runtimeDir), 'asks.jsonl')).find((a) => a.id === body.ask && a.path === r.rel) : null;
+  if (asked && (typeof body.prompt !== 'string' || !body.prompt.trim())) body = { ...body, prompt: asked.prompt };
   let p; try { p = S.askAgentProposal({ before: r.text, after: body.after, prompt: body.prompt }); } catch (e) { return fail(400, e.message); }
   const id = typeof body.id === 'string' && proposalsOf(ctx.runtimeDir).has(body.id) ? body.id : 'prop-' + require('crypto').randomBytes(6).toString('hex');
   const prior = proposalsOf(ctx.runtimeDir).get(id);
   if (prior && prior.path !== r.rel) return fail(400, 'that proposal belongs to another document');
-  const row = { event: prior ? 'revised' : 'proposed', id, path: r.rel, at: now.toISOString(), state: 'proposed', prompt: p.prompt, before_hash: p.before_hash, before_text: r.text, after: p.after, hash: p.hash };
+  const row = { event: prior ? 'revised' : 'proposed', id, path: r.rel, at: now.toISOString(), state: 'proposed', prompt: p.prompt, before_hash: p.before_hash, before_text: r.text, after: p.after, hash: p.hash,
+    by: body.by === 'pm' ? 'pm' : 'agent' };
+  if (asked) { row.ask = asked.id; if (asked.session) row.session = asked.session; }
   append(ctx.runtimeDir, 'proposals.jsonl', row);
   return { status: 200, body: { ok: true, id, state: 'proposed', hash: p.hash, diff: p.diff, voided_hash: prior ? prior.hash : null } };
 }
@@ -137,12 +187,100 @@ function accept(req, body, ctx, now = new Date()) {
   if (!p || p.path !== r.rel) return fail(404, 'no such proposal');
   const res = S.acceptProposal(p, { hash: body.hash, by: 'pm' });   // by is set here, never read from the body
   if (!res.ok) return fail(409, res.reason, { reason: res.reason });
-  if (r.text !== p.before_text) return fail(409, 'stale: the document changed since this proposal was made', { reason: 'stale' });
-  const out = writeDoc(root, body.path, r.text, p.after, p.prompt, ctx.runtimeDir, ctx, ctx.w || null, now);
-  if (out.status === 200) append(ctx.runtimeDir, 'proposals.jsonl', { event: 'accepted', id: p.id, path: r.rel, at: now.toISOString(), state: 'accepted', hash: p.hash });
+  const all = changedNames(p.before_text, p.after);
+  const names = Array.isArray(body.sections) ? body.sections.map(String).filter((n) => all.includes(n)) : null;
+  if (names && !names.length) return fail(400, 'pick at least one section of the proposal');
+  let text;
+  if (names) {
+    const m = S.mergeSections(r.text, p.before_text, p.after, names);
+    if (!m.ok) return fail(409, m.stale ? 'stale: ' + m.stale.join(', ') + ' changed since this proposal was made' : 'not in the proposal: ' + m.unknown.join(', '), { reason: 'stale', stale: m.stale || [] });
+    text = m.text;
+  } else {
+    if (r.text !== p.before_text) return fail(409, 'stale: the document changed since this proposal was made', { reason: 'stale' });
+    text = p.after;
+  }
+  const taken = names || all;
+  const out = writeDoc(root, body.path, r.text, text, p.prompt, ctx.runtimeDir, ctx, ctx.w || null, now,
+    { via: 'proposal', proposal: p.id, text_by: p.by === 'pm' ? 'person' : 'agent', sections: taken, of: all.length });
+  if (out.status === 200) append(ctx.runtimeDir, 'proposals.jsonl', { event: 'accepted', id: p.id, path: r.rel, at: now.toISOString(), state: 'accepted', hash: p.hash, sections: taken, of: all.length, rev: out.body.rev });
   return out;
 }
 
+const changedNames = (a, b) => {
+  const A = S.splitSections(a), B = S.splitSections(b); const out = [];
+  B.forEach((x) => { const y = A.find((q) => q.name === x.name); if (!y || y.text !== x.text) out.push(x.name); });
+  A.forEach((y) => { if (!B.some((x) => x.name === y.name)) out.push(y.name); });
+  return out;
+};
+
+function proposalsRoute(root, q, runtimeDir) {
+  const r = resolveDoc(root, q.path); if (r.error) return r.error;
+  const cur = S.splitSections(r.text);
+  const list = [...proposalsOf(runtimeDir).values()].filter((p) => p.path === r.rel).map((p) => {
+    const A = S.splitSections(p.before_text || ''), B = S.splitSections(p.after || '');
+    const sections = changedNames(p.before_text || '', p.after || '').map((name) => {
+      const a = A.find((x) => x.name === name), b = B.find((x) => x.name === name), c = cur.find((x) => x.name === name);
+      const kind = !a ? 'added' : !b ? 'removed' : 'changed';
+      const stale = a ? (!c || c.text !== a.text) : !!c;
+      return { name, kind, before: a ? a.text : '', after: b ? b.text : '', current: c ? c.text : null, stale };
+    });
+    return { id: p.id, state: p.state, prompt: p.prompt, at: p.at, hash: p.hash, by: p.by || 'agent', session: p.session || null, ask: p.ask || null,
+      closed_at: p.state === 'proposed' ? null : p.at, why: p.why || null, taken: p.sections || null, of: p.of || null, rev: p.rev || null, sections };
+  }).sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  return { status: 200, body: { ok: true, path: r.rel, proposals: list } };
+}
+
+function logRoute(root, q, runtimeDir) {
+  const r = resolveDoc(root, q.path); if (r.error) return r.error;
+  syncBaseline(runtimeDir, r.rel, r.text, new Date(), root);
+  const events = [];
+  const firstOf = new Map();
+  for (const e of readLines(path.join(dirOf(runtimeDir), 'proposals.jsonl'))) {
+    if (!e || e.path !== r.rel) continue;
+    if (e.event === 'proposed' || e.event === 'revised') { if (!firstOf.has(e.id)) firstOf.set(e.id, e.prompt); events.push({ kind: e.event, at: e.at, id: e.id, prompt: e.prompt || firstOf.get(e.id), by: e.by || 'agent', session: e.session || null }); }
+    else if (e.event === 'rejected') events.push({ kind: 'rejected', at: e.at, id: e.id, prompt: firstOf.get(e.id) || null, why: e.why, by: 'pm' });
+  }
+  for (const a of readLines(path.join(dirOf(runtimeDir), 'asks.jsonl'))) {
+    if (!a || a.path !== r.rel) continue;
+    if (a.event === 'asked') events.push({ kind: 'asked', at: a.at, id: a.id, prompt: a.prompt, session: a.session || null, by: 'pm' });
+    else if (a.event === 'failed') events.push({ kind: 'ask-failed', at: a.at, id: a.id, why: a.error, by: 'agent' });
+  }
+  for (const m of readLines(path.join(dirOf(runtimeDir), 'marks.jsonl'))) if (m && m.path === r.rel) events.push({ kind: 'marked', at: m.at, why: m.why, by: 'pm' });
+  return { status: 200, body: { ok: true, path: r.rel, revisions: revsOut(runtimeDir, r.rel), events } };
+}
+
+const needWhy = (body) => (typeof body.why !== 'string' || !body.why.trim() ? fail(400, 'a why is required') : null);
+
+function reject(req, body, ctx, now = new Date()) {
+  const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
+  const nw = needWhy(body); if (nw) return nw;
+  const r = resolveDoc(ctx.root, body.path); if (r.error) return r.error;
+  const p = proposalsOf(ctx.runtimeDir).get(body.id);
+  if (!p || p.path !== r.rel) return fail(404, 'no such proposal');
+  if (p.state !== 'proposed') return fail(409, 'the proposal is already ' + p.state);
+  append(ctx.runtimeDir, 'proposals.jsonl', { event: 'rejected', id: p.id, path: r.rel, at: now.toISOString(), state: 'rejected', why: body.why.trim().slice(0, 400) });
+  return { status: 200, body: { ok: true, id: p.id, state: 'rejected' } };
+}
+
+function addWhy(req, body, ctx, now = new Date()) {
+  const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
+  const nw = needWhy(body); if (nw) return nw;
+  const r = resolveDoc(ctx.root, body.path); if (r.error) return r.error;
+  const rev = Number(body.rev);
+  if (!revsOf(ctx.runtimeDir, r.rel).some((e) => e.rev === rev)) return fail(404, 'no such revision');
+  append(ctx.runtimeDir, 'annotations.jsonl', { path: r.rel, rev, why: body.why.trim().slice(0, 400), at: now.toISOString(), by: 'pm' });
+  return { status: 200, body: { ok: true, rev } };
+}
+
+function markCurrent(req, body, ctx, now = new Date()) {
+  const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
+  const nw = needWhy(body); if (nw) return nw;
+  const r = resolveDoc(ctx.root, body.path); if (r.error) return r.error;
+  append(ctx.runtimeDir, 'marks.jsonl', { path: r.rel, why: body.why.trim().slice(0, 400), at: now.toISOString(), by: 'pm' });
+  return { status: 200, body: { ok: true, at: now.toISOString() } };
+}
+
+
 /* ── Ask the agent from the page (page-starts-agent) ──
  * The run reads the document and answers with the whole revised text between two marker lines. It has Read, Glob and Grep
  * only, so it cannot write; its answer is recorded through propose() and changes nothing until the PM's slide accepts it. */
@@ -187,7 +325,7 @@ function settleAsk(ctx, a, { result, timedOut, stopped, note } = {}, now = new D
   if (r.text !== a.before_text) return end({ event: 'failed', state: 'failed', error: 'The document changed while the agent worked. Ask again.' });
   if (/\n$/.test(r.text) && !/\n$/.test(after)) after += '\n';
   if (after === r.text) return end({ event: 'failed', state: 'failed', error: 'The agent proposed no change.' });
-  const p = propose(null, { path: a.path, prompt: a.prompt, after }, ctx, now);
+  const p = propose(null, { path: a.path, prompt: a.prompt, after, by: 'agent', ask: a.id }, ctx, now);
   if (p.status !== 200) return end({ event: 'failed', state: 'failed', error: p.body.error });
   return end({ event: 'proposed', state: 'proposed', proposal: p.body.id, hash: p.body.hash });
 }
@@ -231,7 +369,7 @@ const respond = (ctx, res, r) => { ctx.json(res, r.body, r.status); return true;
 
 module.exports = {
   prefixes: ['/api/doc-sheet'],
-  resolveDoc, revisionsRoute, atRoute, edit, propose, accept, changeNote, ask, askState, askPrompt, parseAsk, settleAsk,
+  resolveDoc, revisionsRoute, atRoute, edit, propose, accept, changeNote, proposalsRoute, logRoute, reject, addWhy, markCurrent, lastSheetChange, ask, askState, askPrompt, parseAsk, settleAsk,
   handle: async (req, res, url, ctx) => {
     const p = url.pathname;
     const w = (url.searchParams.get('ws') && ctx.getWs) ? ctx.getWs(url.searchParams.get('ws')) : null;
@@ -239,7 +377,10 @@ module.exports = {
     if (req.method === 'GET' && p === '/api/doc-sheet/revisions') return respond(ctx, res, revisionsRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
     if (req.method === 'GET' && p === '/api/doc-sheet/ask') return respond(ctx, res, askState(Object.fromEntries(url.searchParams), base));
     if (req.method === 'GET' && p === '/api/doc-sheet/at') return respond(ctx, res, atRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
-    const fn = req.method === 'POST' && { '/api/doc-sheet/edit': edit, '/api/doc-sheet/propose': propose, '/api/doc-sheet/accept': accept, '/api/doc-sheet/ask': ask,
+    if (req.method === 'GET' && p === '/api/doc-sheet/proposals') return respond(ctx, res, proposalsRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
+    if (req.method === 'GET' && p === '/api/doc-sheet/log') return respond(ctx, res, logRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
+    const fn = req.method === 'POST' && { '/api/doc-sheet/edit': edit, '/api/doc-sheet/propose': propose, '/api/doc-sheet/accept': accept,
+      '/api/doc-sheet/reject': reject, '/api/doc-sheet/why': addWhy, '/api/doc-sheet/mark-current': markCurrent, '/api/doc-sheet/ask': ask,
       '/api/doc-sheet/change-note': (rq, b, c) => changeNote(c.root, b, c.runtimeDir) }[p];
     if (!fn) return false;
     const got = await ctx.readJson(req);