create-pmos 0.55.5 → 0.56.0

package/workspace/public/pm/dest-docs.js

@@ -0,0 +1,405 @@
+/* pm/dest-docs.js — the Docs destination: is each document the same as its Google Docs and Confluence copy, and use
+ * one version over the other on the PM's press (initiative docs-three-way-sync, PRD R-D1 to R-D6 and R-F1 to R-F4).
+ *
+ * A DESTINATION MODULE (registry.js): mountDestination(host, ctx) on every render with the same host, disposeDestination(host).
+ * It keeps ONE persistent root per host; the header (title and search) is built once, so typing never loses focus, and
+ * only the body is rebuilt when its own data changed.
+ *
+ * What it shows, for the repository the tab names (or the open one):
+ *   - Docs, a search box, Needs you · All, and when the copies were last compared, with a control that compares again;
+ *   - the copies grouped by initiative, ONE line per copy: a status dot, the title, a link that opens the copy, one
+ *     sentence (which side is newer, and who edited it last) and at most one button (Use PMOS version, Use Confluence
+ *     version, or Choose… when both changed);
+ *   - a click on a line: both sides with where they live and their last edit, a Use … version button for each, the first
+ *     difference the check saw, Compare again and Stop tracking this copy;
+ *   - search: every markdown file that matches; a file without a copy offers Add copy, in place.
+ * The signal is decided on the server (lib/doc-sync.js) from what a check session read. Nothing here reads or writes
+ * Google Docs or Confluence. Use … version waits five seconds behind Undo, then asks the server to start ONE doc-sync
+ * session for that copy, which writes one side with the PM's own connectors (the PM's ruling, amended 2026-10-06).
+ * In fixture mode it reads nothing.
+ */
+
+import { el } from './dom.js';
+import { button, row, field, toast, empty, tabs, ensureComponentsCss } from './primitives.js';
+import { ensureSprite } from './icons.js';
+import { pmGet, pmPost } from './http.js';
+import { wsOf } from './data.js';
+import { registerCommand, openDestination } from './registry.js';
+
+const LABEL = { google: 'Google Docs', confluence: 'Confluence' };
+const UNDO_MS = 5000;
+
+export const COPY = Object.freeze({
+  title: 'Docs',
+  fixture: 'Docs shows linked documents in a real session.',
+  noRepo: 'Open a repository to see its documents.',
+  loading: 'Reading…',
+  readError: 'The documents could not be read.',
+  find: 'Find a document',
+  needs: 'Needs you',
+  all: 'All',
+  compared: (iso) => 'Compared ' + ago(iso),
+  never: 'Not compared yet',
+  comparing: 'Comparing…',
+  compareAll: 'Compare every copy again',
+  none: 'No document has a copy yet. Find a document above and press Add copy.',
+  nothingNeeds: 'Nothing needs you. Every copy matches PMOS.',
+  noMatch: (q) => `No document matches “${q}”.`,
+  other: 'Other',
+  usePmos: 'Use PMOS version',
+  useCopy: (label) => `Use ${label} version`,
+  choose: 'Choose…',
+  noCopy: 'No copy',
+  addCopy: 'Add copy',
+  add: 'Add',
+  cancel: 'Cancel',
+  paste: 'Paste a Google Docs or Confluence link',
+  badPaste: 'Paste the address of a Google Doc or a Confluence page.',
+  added: 'Copy added. Compare to see which side is newer.',
+  compareAgain: 'Compare again',
+  stop: 'Stop tracking this copy',
+  stopped: (label) => `Stopped tracking the ${label} copy. Nothing was deleted.`,
+  undo: 'Undo',
+  pushing: (label) => `Updating ${label} with the PMOS version.`,
+  pulling: (label) => `Updating PMOS with the ${label} version.`,
+  cancelled: 'Nothing was changed.',
+  started: 'Compare started. It reads every copy and changes nothing.',
+});
+
+// Docs is not in the top bar (the bar holds at most 7 controls); ⌘K and `g d` open it.
+registerCommand({ id: 'docs-open', label: 'Docs', hint: 'Is each document the same as its Google Docs and Confluence copy', cli: 'pmos docs list', run: () => openDestination('docs') });
+
+/* ── words ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function ago(iso) {
+  if (!iso) return 'never';
+  const m = Math.round((Date.now() - Date.parse(iso)) / 60000);
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m} min ago`;
+  if (m < 48 * 60) return `${Math.round(m / 60)} h ago`;
+  return `${Math.round(m / 1440)} days ago`;
+}
+/** "today 09:12", "yesterday 17:55", "Mon 14:05", "Sep 30". */
+function when(iso) {
+  const t = new Date(iso);
+  if (Number.isNaN(t.getTime())) return '';
+  const hm = t.toTimeString().slice(0, 5);
+  const day = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+  const days = Math.round((day(new Date()) - day(t)) / 86400000);
+  if (days === 0) return 'today ' + hm;
+  if (days === 1) return 'yesterday ' + hm;
+  if (days > 1 && days < 7) return t.toLocaleDateString('en-US', { weekday: 'short' }) + ' ' + hm;
+  return t.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}
+const edit = (by, at) => [by, at ? when(at) : null].filter(Boolean).join(', ');
+const keyOf = (doc, link) => `${doc.path}|${link.kind}`;
+/** Which kind a pasted address names. The server checks it again; this only picks the kind. */
+function kindOf(target) {
+  const t = String(target || '');
+  if (/atlassian|confluence|\/wiki\/|pageId=/i.test(t)) return 'confluence';
+  if (/google|docs\.|drive\./i.test(t)) return 'google';
+  return null;
+}
+
+/** One dot, one sentence and at most one button per copy. The newer side's last edit is the only detail on the line. */
+function stateOf(inst, doc, link) {
+  const L = link.label || LABEL[link.kind];
+  const pend = inst.pending.get(keyOf(doc, link));
+  const syncing = link.syncing || (pend ? { use: pend.use } : null);
+  if (syncing) return { dot: 'none', strong: syncing.use === 'pmos' ? `Updating ${L}…` : `Updating PMOS from ${L}…` };
+  const by = (s) => (link.basis === 'date' ? s + ' · by date' : s);
+  let st;
+  switch (link.signal) {
+    case 'same': st = { dot: 'ok', rest: 'Same' }; break;
+    case 'ahead': st = { dot: 'warn', strong: 'PMOS is newer', rest: by(edit(doc.repo && doc.repo.modified_by, doc.repo && doc.repo.modified_at)), btn: 'pmos' }; break;
+    case 'behind': st = { dot: 'warn', strong: `${L} is newer`, rest: by(edit(link.remote_modified_by, link.remote_modified_at)), btn: 'copy' }; break;
+    case 'diverged': st = { dot: 'bad', strong: 'Edited on both sides', btn: 'choose' }; break;
+    case 'unchecked': st = { dot: 'none', rest: COPY.never }; break;
+    case 'unreadable': st = { dot: 'bad', strong: `Can't open in ${L}`, rest: String(link.words || '').replace(/^Could not check — /, '') }; break;
+    case 'missing-remote': st = { dot: 'bad', strong: `Not found in ${L}` }; break;
+    case 'missing-repo': st = { dot: 'bad', strong: 'Not in PMOS any more' }; break;
+    default: st = { dot: 'none', rest: link.words || '' };
+  }
+  if (link.sync_failed) return { ...st, dot: 'bad', strong: 'Sync failed', rest: link.sync_failed.reason };
+  return st;
+}
+
+/* ── mount ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const insts = new WeakMap();
+const REREAD_MS = 5000;
+
+export function mountDestination(host, ctx) {
+  let inst = insts.get(host);
+  if (!inst) {
+    inst = { host, root: el('div', { class: 'rp-page rp-docs', 'data-docs': '' }), head: null, body: el('div', { class: 'rp-docs-body' }),
+      ws: null, loaded: false, error: null, view: null, filter: 'needs', q: '', files: [], open: null, adding: null,
+      pending: new Map(), busy: false, seq: 0, fseq: 0, last: '', timer: null, ftimer: null };
+    insts.set(host, inst);
+  }
+  ensureComponentsCss();
+  if (!inst.root.isConnected || inst.root.parentNode !== host) host.replaceChildren(inst.root);
+  if (ctx && ctx.FIXTURE) { inst.root.replaceChildren(empty({ text: COPY.fixture })); return; }
+  const repo = (ctx && ctx.tab && ctx.tab.repo) || (ctx && ctx.state && ctx.state.product) || null;
+  const ws = repo ? wsOf(repo) : null;
+  if (ws !== inst.ws) {
+    stopPoll(inst);
+    Object.assign(inst, { ws, loaded: false, error: null, view: null, last: '', open: null, adding: null, files: [] });
+    if (ws) { ensureSprite(); refresh(inst); }
+    draw(inst);
+    return;
+  }
+  // Coming back to Docs reads again (at most every few seconds): a file edited since shows its new signal.
+  if (Date.now() - (inst.readAt || 0) > REREAD_MS) refresh(inst);
+  if (!inst.last) draw(inst);
+}
+
+export function disposeDestination(host) {
+  const inst = insts.get(host);
+  if (!inst) return;
+  stopPoll(inst);
+  inst.seq++;
+  inst.root.remove();
+  insts.delete(host);
+}
+
+function stopPoll(inst) { if (inst.timer) { clearInterval(inst.timer); inst.timer = null; } }
+/** While a compare or a sync runs, read again every few seconds so its result lands without a reload; stop when it ends. */
+function pollWhileRunning(inst) {
+  const v = inst.view;
+  const running = v && (v.open || v.session || v.docs.some((d) => d.links.some((l) => l.syncing)));
+  if (running && !inst.timer) inst.timer = setInterval(() => refresh(inst), 4000);
+  if (!running) stopPoll(inst);
+}
+
+async function refresh(inst) {
+  const ws = inst.ws;
+  if (!ws) return;
+  const seq = ++inst.seq;
+  inst.readAt = Date.now();
+  const v = await pmGet('/api/docs?ws=' + encodeURIComponent(ws));
+  if (seq !== inst.seq || ws !== inst.ws) return;
+  inst.loaded = true;
+  if (!v || v.ok === false) { inst.error = (v && v.error) || COPY.readError; inst.view = null; }
+  else { inst.error = null; inst.view = v; }
+  pollWhileRunning(inst);
+  draw(inst);
+}
+
+/** The repository's files that match the search and have no copy yet: what Add copy is offered on. */
+function searchFiles(inst) {
+  if (inst.ftimer) clearTimeout(inst.ftimer);
+  const q = inst.q.trim();
+  if (!q) { inst.files = []; return; }
+  inst.ftimer = setTimeout(async () => {
+    const seq = ++inst.fseq;
+    const r = await pmGet('/api/docs/files?ws=' + encodeURIComponent(inst.ws) + '&q=' + encodeURIComponent(q));
+    if (seq !== inst.fseq || q !== inst.q.trim()) return;
+    inst.files = (r && r.ok && r.files) || [];
+    draw(inst);
+  }, 200);
+}
+
+/* ── actions ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+async function compareAll(inst) {
+  inst.busy = true; draw(inst);
+  const r = await pmPost('/api/docs/check', { ws: inst.ws });
+  inst.busy = false;
+  if (r && r.ok) toast({ text: COPY.started, timeout: 4000 });
+  else toast({ text: (r && r.error) || 'The compare could not start.', tone: 'error' });
+  await refresh(inst);
+}
+
+/** Use one version over the other. Held for five seconds behind Undo; only then is the session asked for. */
+function useVersion(inst, doc, link, use) {
+  const key = keyOf(doc, link);
+  if (inst.pending.has(key)) return;
+  const L = link.label || LABEL[link.kind];
+  const p = { use, timer: null, toast: null };
+  p.timer = setTimeout(async () => {
+    inst.pending.delete(key);
+    const r = await pmPost('/api/docs/sync', { ws: inst.ws, path: doc.path, kind: link.kind, use });
+    if (!r || !r.ok) toast({ text: (r && r.error) || 'The sync could not start.', tone: 'error' });
+    await refresh(inst);
+  }, UNDO_MS);
+  p.toast = toast({ text: use === 'pmos' ? COPY.pushing(L) : COPY.pulling(L), actionLabel: COPY.undo, timeout: UNDO_MS,
+    onAction: () => { clearTimeout(p.timer); inst.pending.delete(key); draw(inst); toast({ text: COPY.cancelled, timeout: 3000 }); } });
+  inst.pending.set(key, p);
+  inst.open = null;
+  draw(inst);
+}
+
+async function stopTracking(inst, doc, link) {
+  const r = await pmPost('/api/docs/unlink', { ws: inst.ws, path: doc.path, kind: link.kind });
+  if (!r || !r.ok) { toast({ text: (r && r.error) || 'The copy is still tracked.', tone: 'error' }); return; }
+  inst.open = null;
+  toast({ text: COPY.stopped(link.label || LABEL[link.kind]), actionLabel: COPY.undo, timeout: 6000,
+    onAction: async () => { await pmPost('/api/docs/link', { ws: inst.ws, path: doc.path, kind: link.kind, target: link.target }); refresh(inst); } });
+  refresh(inst);
+}
+
+async function addCopy(inst, path, target, err) {
+  const kind = kindOf(target);
+  if (!kind) { err.textContent = COPY.badPaste; return; }
+  const r = await pmPost('/api/docs/link', { ws: inst.ws, path, kind, target });
+  if (!r || !r.ok) { err.textContent = (r && r.error) || 'The copy was not added.'; return; }
+  inst.adding = null;
+  inst.files = inst.files.filter((f) => f.path !== path);
+  toast({ text: COPY.added, timeout: 4000 });
+  refresh(inst);
+}
+
+/* ── lines ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function copyLine(inst, doc, link) {
+  const key = keyOf(doc, link);
+  const L = link.label || LABEL[link.kind];
+  const st = stateOf(inst, doc, link);
+  const open = inst.open === key;
+  const toggle = () => { inst.open = open ? null : key; draw(inst); };
+  let act = null;
+  if (st.btn === 'pmos' || st.btn === 'copy') {
+    act = button({ label: st.btn === 'pmos' ? COPY.usePmos : COPY.useCopy(L), variant: 'primary', size: 'sm',
+      attrs: { 'data-docs-act': 'use-' + st.btn, 'data-docs-key': key }, onClick: () => useVersion(inst, doc, link, st.btn) });
+  } else if (st.btn === 'choose') {
+    act = button({ label: COPY.choose, variant: 'outline', size: 'sm', attrs: { 'data-docs-act': 'choose', 'data-docs-key': key, 'aria-expanded': open ? 'true' : 'false' },
+      onClick: toggle });
+  }
+  const opener = link.url
+    ? el('a', { class: 'rp-docs-open', href: link.url, target: '_blank', rel: 'noopener noreferrer', 'data-docs-open': link.kind }, L + ' ↗')
+    : el('span', { class: 'rp-docs-open' }, L);
+  const line = row({
+    title: doc.title,
+    meta: [st.strong, st.rest].filter(Boolean),
+    lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--' + st.dot, 'aria-hidden': 'true' })],
+    trail: [opener, act].filter(Boolean),
+    onOpen: toggle,
+    openLabel: `${doc.title}, ${L}: ${[st.strong, st.rest].filter(Boolean).join(', ')}`,
+    openAttrs: { 'aria-expanded': open ? 'true' : 'false', title: doc.path, 'data-docs-toggle': key },
+    attrs: { 'data-docs-line': key, 'data-docs-signal': link.signal, 'data-docs-kind': link.kind, 'data-docs-title': doc.title,
+      'data-docs-state': [st.strong, st.rest].filter(Boolean).join(' · ') },
+  });
+  const wrap = el('div', { class: 'rp-docs-row', role: 'listitem', 'data-docs-doc': doc.path }, line);
+  if (open) wrap.appendChild(details(inst, doc, link, st));
+  return wrap;
+}
+
+/** The details, on a click: where each side lives, its last edit, both choices, and the first difference the check saw. */
+function details(inst, doc, link, st) {
+  const L = link.label || LABEL[link.kind];
+  const can = !st.strong || !/^Updating/.test(st.strong);
+  const offer = can && ['ahead', 'behind', 'diverged'].includes(link.signal);
+  const pNew = link.signal === 'ahead';
+  const cNew = link.signal === 'behind';
+  const side = (name, where, last, isNew, use) => el('div', { class: 'rp-docs-side' + (isNew ? ' rp-docs-side--new' : ''), 'data-docs-side': use },
+    el('span', { class: 'rp-docs-side__label' }, name + (isNew ? ' · newer' : '')),
+    el('span', { class: 'rp-docs-side__where' }, where),
+    el('span', { class: 'rp-docs-side__edit' }, last ? 'Last edit: ' + last : 'Last edit: read at the next compare'),
+    offer ? button({ label: use === 'pmos' ? COPY.usePmos : COPY.useCopy(L), variant: isNew ? 'primary' : 'outline', size: 'sm',
+      attrs: { 'data-docs-act': 'use-' + use, 'data-docs-key': keyOf(doc, link) }, onClick: () => useVersion(inst, doc, link, use) }) : null);
+  const diff = link.note && link.signal !== 'same' && link.signal !== 'unchecked'
+    ? el('p', { class: 'rp-docs-diff', 'data-docs-diff': '' }, 'First difference: ' + link.note) : null;
+  return el('div', { class: 'rp-docs-detail', 'data-docs-detail': keyOf(doc, link) },
+    side('PMOS', doc.path, edit(doc.repo && doc.repo.modified_by, doc.repo && doc.repo.modified_at), pNew, 'pmos'),
+    side(L, link.target, edit(link.remote_modified_by, link.remote_modified_at), cNew, 'copy'),
+    diff,
+    el('div', { class: 'rp-docs-more' },
+      button({ label: COPY.compareAgain, variant: 'ghost', size: 'sm', disabled: !!(inst.view && (inst.view.open || inst.view.session)) || inst.busy,
+        attrs: { 'data-docs-act': 'compare-one' }, onClick: () => compareAll(inst) }),
+      button({ label: COPY.stop, variant: 'ghost', size: 'sm', attrs: { 'data-docs-act': 'stop', 'data-docs-key': keyOf(doc, link) },
+        onClick: () => stopTracking(inst, doc, link) })));
+}
+
+/** A file with no copy: "No copy" and Add copy, which opens a paste field in place. */
+function fileLine(inst, f) {
+  const start = () => { inst.adding = f.path; draw(inst); };
+  const adding = inst.adding === f.path;
+  const line = row({
+    title: f.title,
+    meta: [COPY.noCopy],
+    lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--none', 'aria-hidden': 'true' })],
+    trail: adding ? [] : [button({ label: COPY.addCopy, variant: 'outline', size: 'sm', attrs: { 'data-docs-act': 'add-copy', 'data-docs-key': f.path }, onClick: start })],
+    attrs: { 'data-docs-file-line': f.path, title: f.path },
+  });
+  const wrap = el('div', { class: 'rp-docs-row', role: 'listitem', 'data-docs-file': f.path }, line);
+  if (!adding) return wrap;
+  const err = el('span', { class: 'rp-docs-add__err', role: 'alert' });
+  const inp = field({ label: `Copy of ${f.title}`, hideLabel: true, placeholder: COPY.paste, attrs: { 'data-docs-field': 'target' } });
+  inp.control.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') addCopy(inst, f.path, inp.control.value.trim(), err);
+    if (e.key === 'Escape') { inst.adding = null; draw(inst); }
+  });
+  setTimeout(() => inp.control.focus(), 0);
+  wrap.appendChild(el('div', { class: 'rp-docs-add' }, el('div', { class: 'rp-docs-add__input' }, inp),
+    button({ label: COPY.add, variant: 'primary', size: 'sm', attrs: { 'data-docs-act': 'add-save' }, onClick: () => addCopy(inst, f.path, inp.control.value.trim(), err) }),
+    button({ label: COPY.cancel, variant: 'ghost', size: 'sm', onClick: () => { inst.adding = null; draw(inst); } }),
+    err));
+  return wrap;
+}
+
+/* ── the page ────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function header(inst) {
+  if (inst.head) return inst.head;
+  const find = field({ label: COPY.find, hideLabel: true, placeholder: COPY.find, attrs: { 'data-docs-find': '' } });
+  const q = find.control;
+  q.addEventListener('input', () => { inst.q = q.value; inst.open = null; inst.adding = null; searchFiles(inst); draw(inst); });
+  // The field restores its last committed text on Escape; here Escape clears the search instead.
+  q.addEventListener('keydown', (e) => { if (e.key === 'Escape') { q.resetCommitted(''); inst.q = ''; searchFiles(inst); draw(inst); } });
+  inst.head = el('div', { class: 'rp-docs-top' }, el('h2', { class: 'rp-head__title' }, COPY.title), el('div', { class: 'rp-docs-find' }, find));
+  return inst.head;
+}
+
+function grouped(inst, docs) {
+  const by = new Map();
+  for (const d of docs) {
+    const k = d.initiative ? d.initiative.id : '';
+    if (!by.has(k)) by.set(k, { title: d.initiative ? d.initiative.title : COPY.other, docs: [] });
+    by.get(k).docs.push(d);
+  }
+  return [...by.entries()].sort((a, b) => (a[0] === '') - (b[0] === '')).map(([k, g]) =>
+    el('section', { class: 'rp-docs-group', 'data-docs-group': k || 'other' },
+      el('h3', { class: 'rp-docs-group__title' }, g.title),
+      el('div', { role: 'list' }, g.docs.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))))));
+}
+
+function body(inst) {
+  const v = inst.view;
+  const q = inst.q.trim().toLowerCase();
+  if (q) {
+    const hits = v.docs.filter((d) => [d.title, d.path, d.initiative ? d.initiative.title : ''].join(' ').toLowerCase().includes(q));
+    const rows = [...hits.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))), ...inst.files.map((f) => fileLine(inst, f))];
+    return rows.length ? [el('div', { role: 'list', class: 'rp-docs-group', 'data-docs-results': '' }, rows)] : [el('p', { class: 'rp-section__empty' }, COPY.noMatch(inst.q.trim()))];
+  }
+  const all = v.docs.reduce((n, d) => n + d.links.length, 0);
+  const needs = v.docs.reduce((n, d) => n + d.links.filter((l) => l.signal !== 'same' || l.syncing).length, 0);
+  const running = !!(v.open || v.session) || inst.busy;
+  const out = [el('div', { class: 'rp-docs-views' },
+    tabs({ variant: 'line', items: [{ id: 'needs', label: COPY.needs, count: needs }, { id: 'all', label: COPY.all, count: all }],
+      value: inst.filter, ariaLabel: 'Filter', attrs: { 'data-docs-filter': '' }, onChange: (val) => { inst.filter = val; draw(inst); } }),
+    el('span', { class: 'rp-docs-when', 'data-docs-summary': '' },
+      running ? COPY.comparing : (v.last ? COPY.compared(v.last.finished_at) : COPY.never),
+      button({ label: '↻', variant: 'ghost', size: 'sm', disabled: running || !all,
+        attrs: { 'data-docs-act': 'check', 'aria-label': COPY.compareAll, title: COPY.compareAll }, onClick: () => compareAll(inst) })))];
+  if (!v.docs.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.none)); return out; }
+  const shown = inst.filter === 'needs'
+    ? v.docs.map((d) => ({ ...d, links: d.links.filter((l) => l.signal !== 'same' || l.syncing || inst.pending.has(keyOf(d, l))) })).filter((d) => d.links.length)
+    : v.docs;
+  if (!shown.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.nothingNeeds)); return out; }
+  out.push(...grouped(inst, shown));
+  return out;
+}
+
+function draw(inst) {
+  const root = inst.root;
+  if (!inst.ws) { root.replaceChildren(empty({ text: COPY.noRepo })); inst.last = 'none'; return; }
+  const fp = JSON.stringify([inst.loaded, inst.error, inst.view, inst.filter, inst.busy, inst.q, inst.files, inst.open, inst.adding, [...inst.pending.keys()]]);
+  if (fp === inst.last && root.childNodes.length && root.contains(inst.body)) return;
+  inst.last = fp;
+  const head = header(inst);
+  if (head.parentNode !== root || inst.body.parentNode !== root) root.replaceChildren(head, inst.body);
+  if (!inst.loaded) { inst.body.replaceChildren(el('p', { class: 'rp-section__empty' }, COPY.loading)); return; }
+  if (inst.error) { inst.body.replaceChildren(el('p', { class: 'rp-section__empty rp-section__empty--bad', role: 'alert' }, inst.error)); return; }
+  inst.body.replaceChildren(...body(inst));
+}

package/workspace/public/pm/registry.js

@@ -48,6 +48,8 @@ export const DESTINATIONS = Object.freeze([
   Object.freeze({ id: 'initiatives', label: 'Initiatives', key: 'g i', module: 'dest-initiatives.js', run: 2 }),
   Object.freeze({ id: 'board', label: 'Board', key: 'g b', module: 'dest-board.js', run: 4 }),
   Object.freeze({ id: 'reports', label: 'Reports', key: 'g r', module: 'dest-reports.js', run: 5 }),
+  // Not a pm-os-absorb run (run: null): docs-three-way-sync added it — is each linked document the same as its copies.
+  Object.freeze({ id: 'docs', label: 'Docs', key: 'g d', module: 'dest-docs.js', run: null }),
   Object.freeze({ id: 'settings', label: 'Settings', key: null, module: 'dest-settings.js', run: 3 }),
 ]);
 export const EXTENSIONS = Object.freeze([

package/workspace/replaced-tests.json

@@ -2904,6 +2904,20 @@
       "names": [
         "E3b: an outcome check recorded ONLY in planning/runs/ disposes its initiative"
       ]
+    },
+    {
+      "id": "E72",
+      "group": "E",
+      "file": "workspace/d86-seams.test.js",
+      "section": "assertion 7: the registry's destination modules",
+      "change": "replaced",
+      "slice": "docs-three-way-sync",
+      "reason": "docs-three-way-sync adds a sixth destination, Docs (dest-docs.js), opened from ⌘K and g d. The assertion counted exactly five destination modules, so its name and count change.",
+      "replacement": "The same assertion 7 under a new name counts six destination modules; the three extensions and provider-cards.js first are unchanged.",
+      "pm_approval": null,
+      "names": [
+        "7 registry.js lists the five destination modules and the three extensions (provider-cards.js first)"
+      ]
     }
   ]
 }

package/workspace/server.js

@@ -128,6 +128,12 @@ const profilesLib = require('./lib/profiles');         // readProfiles(homeDir)
 const focus = require('./lib/focus');                  // buildFocus(input) → FocusView (cross-product)
 const handoff = require('./lib/handoff');              // readLinks(parsedFrontmatterObject) — never a path
 const fourPanel = require('./lib/four-panel');         // GET /api/initiative — the one-initiative join + the declaration stores
+const docSyncStore = require('./lib/doc-sync-store');
+// The session each repository's Check now started (workspace id → session id), so a second press while it runs refuses.
+const docCheckSessions = new Map();
+// The session each Use … version press started (workspace id|path|kind → { session, use }), so the line says "Updating…"
+// before the session has opened its sync, and a second press on the same copy refuses.
+const docSyncSessions = new Map();
 const planItems = require('./lib/plan-items.js');      // pm-os-absorb Run 1 — the ONE writer and fold of plan-items.jsonl (control graph)
 const planTree = require('./lib/plan-tree.js');        // …and the Breakdown layout: derived stages, owed rows, the Board columns
 const routeModules = require('./lib/route-modules.js'); // pm-os-absorb Runs 2–5 — each run's routes in its own lib/routes-<name>.js
@@ -6389,6 +6395,103 @@ async function handleRequest(req, res) {
     pushSessions();
     return json(res, { ok: true, id: s.id, initiative: next, attributed_by: s.attributedBy, previous });
   }
+  // ── Docs: the sync signal for documents linked to Google Docs and Confluence (docs-three-way-sync) ──────────────
+  // GET reads the links (the artifact-link store), the check readings and the files, and decides one signal per copy in
+  // lib/doc-sync.js. The POSTs add or remove a link, or start the read-only `doc-check` skill as a session — the same
+  // path a scheduled agent skill takes. No route here reads Google or Confluence: a session holding the PM's own
+  // connectors does, and records what it read (D53). There is no sync and no schedule: the PM asked for a signal.
+  if (p === '/api/docs' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    const v = docSyncStore.view(root);
+    if (!v.ok) return json(res, v, 500);
+    const alive = (id) => !!(id && sessions.get(id) && sessions.get(id).state !== 'exited');
+    const sess = docCheckSessions.get(w ? w.id : '') || null;
+    const live = alive(sess) ? sess : null;
+    // Group by initiative: the library's own attribution of each file (pmos-shaped repositories only).
+    const owner = new Map();
+    try {
+      if (wsShape(root) === 'pmos') {
+        for (const g of initiativeIndex(root).initiatives) for (const a of g.artifacts) if (!owner.has(a.path)) owner.set(a.path, { id: g.id, title: g.title || g.id });
+      }
+    } catch { /* no grouping: every document is under Other */ }
+    const wid = w ? w.id : '';
+    const docs = v.docs.map((d) => ({
+      ...d,
+      initiative: owner.get(d.path) || (d.initiative_id ? { id: d.initiative_id, title: d.initiative_id } : null),
+      links: d.links.map((l) => {
+        if (l.syncing) return l;
+        const ps = docSyncSessions.get(`${wid}|${d.path}|${l.kind}`);
+        return ps && alive(ps.session) ? { ...l, syncing: { run: null, use: ps.use, started_at: ps.at } } : l;
+      }),
+    }));
+    return json(res, { ...v, docs, ws: w ? w.id : null, session: live, connectors: fourPanel.connectors(os.homedir()) });
+  }
+  if (p === '/api/docs/files' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    const found = docSyncStore.findFiles(root, String(url.searchParams.get('q') || '').slice(0, 200));
+    const v = docSyncStore.view(root);
+    const linked = new Set(v.ok ? v.docs.map((d) => d.path) : []);
+    return json(res, { ok: true, files: found.filter((f) => !linked.has(f.path)) });
+  }
+  if ((p === '/api/docs/link' || p === '/api/docs/unlink' || p === '/api/docs/check' || p === '/api/docs/sync') && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const g = pmGuard.requirePagePress(req, body);
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
+    const w = body.ws ? workspaces.get(String(body.ws)) : getWs(null);
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 404);
+    if (p === '/api/docs/link') {
+      const r = docSyncStore.addLink(w.root, { path: String(body.path || '').trim(), kind: body.kind, target: String(body.target || '').trim() });
+      return json(res, r.ok ? { ok: true } : { ok: false, error: r.error }, r.ok ? 200 : 400);
+    }
+    if (p === '/api/docs/unlink') {
+      const r = docSyncStore.removeLink(w.root, { path: String(body.path || ''), kind: body.kind });
+      return json(res, r.ok ? { ok: true } : { ok: false, error: r.error }, r.ok ? 200 : 400);
+    }
+    // Use … version (amended 2026-10-06): one doc-sync session for one copy, in the direction the PM pressed. The page
+    // holds the press for five seconds behind Undo before it posts here. The session writes one side with the PM's own
+    // connectors and records it through `pmos docs sync-start|sync-finish|sync-fail`; nothing here touches a copy.
+    if (p === '/api/docs/sync') {
+      const rel = String(body.path || '').trim();
+      const kind = String(body.kind || '');
+      const use = String(body.use || '');
+      if (!['pmos', 'copy'].includes(use)) return json(res, { ok: false, error: 'say which version to use: pmos or copy' }, 400);
+      const v = docSyncStore.view(w.root);
+      if (!v.ok) return json(res, v, 500);
+      const doc = v.docs.find((d) => d.path === rel);
+      const link = doc && doc.links.find((l) => l.kind === kind);
+      if (!link) return json(res, { ok: false, error: `${rel} has no such copy` }, 404);
+      const key = `${w.id}|${rel}|${kind}`;
+      const prevSync = docSyncSessions.get(key);
+      if (link.syncing || (prevSync && sessions.get(prevSync.session) && sessions.get(prevSync.session).state !== 'exited')) {
+        return json(res, { ok: false, error: 'that copy is already being synced' }, 409);
+      }
+      const task = taskById('doc-sync', w.root);
+      if (!task || !task.prompt) return json(res, { ok: false, error: 'the doc-sync skill is not installed' }, 500);
+      const ask = `\n\nThis sync:\n- file: ${rel}\n- copy: ${kind} (${link.target})\n- use: ${use}`;
+      const s = spawnSession({ name: 'Doc sync', agent: task.agent || 'claude', ws: w.id, origin: 'docs:sync',
+        initialInput: task.prompt + ask + '\r', modelAsk: { skillTier: task.tier || null, skill: task.skill } });
+      const started = s.state !== 'exited';
+      if (started) docSyncSessions.set(key, { session: s.id, use, at: new Date().toISOString() });
+      return json(res, { ok: started, session: s.id, error: started ? undefined : (s.note || 'could not start the session') }, started ? 200 : 500);
+    }
+    // Check now: one check per repository. A session already running, or a check the ledger still holds open, refuses.
+    const prev = docCheckSessions.get(w.id);
+    if (prev && sessions.get(prev) && sessions.get(prev).state !== 'exited') {
+      return json(res, { ok: false, error: 'a check is already running', session: prev }, 409);
+    }
+    const v = docSyncStore.view(w.root);
+    if (v.ok && v.open) return json(res, { ok: false, error: `a check is already running (started ${v.open.started_at})` }, 409);
+    if (v.ok && !v.docs.length) return json(res, { ok: false, error: 'no document is linked yet — add a link first' }, 400);
+    const task = taskById('doc-check', w.root);
+    if (!task || !task.prompt) return json(res, { ok: false, error: 'the doc-check skill is not installed' }, 500);
+    const s = spawnSession({ name: 'Doc check', agent: task.agent || 'claude', ws: w.id, origin: 'docs:check',
+      initialInput: task.prompt + '\r', modelAsk: { skillTier: task.tier || null, skill: task.skill } });
+    const started = s.state !== 'exited';
+    if (started) docCheckSessions.set(w.id, s.id);
+    return json(res, { ok: started, session: s.id, error: started ? undefined : (s.note || 'could not start the session') }, started ? 200 : 500);
+  }
   if (p === '/api/initiative/link' && req.method === 'POST') {
     // Recording that an artifact corresponds to an external page. This writes a DECLARATION and
     // makes no request: PMOS holds no credential, so it can state what the PM says the mapping is

package/workspace/skills/doc-check.skill

@@ -0,0 +1,40 @@
+---
+name: doc-check
+label: "Check linked documents against Google Docs and Confluence"
+description: "Read the Google Docs and Confluence copies of every linked document and record whether each is the same as the repository file. Read-only: it writes no document, page or file."
+run: agent
+agent: claude
+output:
+  - Same
+  - Ahead or behind
+  - Edited in both
+  - Could not check
+---
+
+/doc-check — read every Google Docs and Confluence copy of a linked document in THIS repository and record what you saw. PMOS then shows the PM, per document, whether the repository copy is the same as, ahead of or behind each copy.
+
+The PM asked for a signal, not a sync. You read; you never write.
+
+Rules that always hold:
+1. READ-ONLY EVERYWHERE. Never create, update, move, rename, comment on, share or delete a Google Doc, a Drive file or a Confluence page. Never edit, create or delete a file in this repository. Never commit or push.
+2. THE ONLY WRITES are `pmos docs check-start`, `pmos docs record` and `pmos docs check-finish`. Never write a `*.jsonl` file by hand.
+3. RECORD ONLY WHAT YOU READ. A version, a modified time or a title that you did not read from the copy is not recorded. If you cannot read a copy, record the error. Do not guess.
+4. USE THE PM'S CONNECTORS. Google Docs: the Google Drive tools (file metadata and file content). Confluence: the Atlassian tools (get the page, with its version). If a connector is missing or refuses, record that as the error for each of its copies and go on with the others.
+5. "SAME" MEANS THE SAME DOCUMENT. Compare the copy's text with the repository file's body as documents: the same headings, paragraphs, lists and tables, in the same order. Ignore formatting, whitespace, the YAML frontmatter of the repository file and the copy's title. If any sentence, item or row differs, it is not the same. If you cannot tell, it is not the same: set `same: false` and say why in `note`.
+
+Procedure:
+1. Run `pmos docs check-start --json`. Keep `run` (the check id) and `links`. Each link has `path`, `kind` (google or confluence), `target` (the address), `remote_id` and `repo_hash`. If it says a check is already running, stop and report that.
+2. For each link, in order:
+   a. Read the copy's metadata. Google: the file's `modifiedTime`, its revision or version, who last modified it, and whether it is trashed. Confluence: the page's `version.number`, its last-modified time and who made that version.
+   b. If the copy does not exist or is in the trash, the reading is `{"path","kind","remote_id","exists":false}`.
+   c. If reading failed for any other reason (no access, no connector, an error), the reading is `{"path","kind","remote_id","error":"<the error, in one line>"}`.
+   d. Otherwise read the copy's content and the repository file `path` (skip this when `repo_hash` is null: the file is not in the repository). Decide `same` by rule 5. The reading is `{"path","kind","remote_id","exists":true,"version":"<version>","modified_at":"<ISO time>","modified_by":"<the person's name, when the copy says it>","title":"<the copy's title>","url":"<its address>","same":true|false,"repo_hash":"<repo_hash from step 1>","note":"<one line when same is false: the first difference>"}`.
+3. Write all readings as a JSON list to a file outside the repository (for example in /tmp) and run `pmos docs record <run> --file <that file>`. If a reading is refused, fix that reading from what you actually read and record it again; never invent a value to get it accepted.
+4. Run `pmos docs check-finish <run> --summary "<n> same, <n> ahead or behind, <n> edited in both, <n> could not check"`.
+5. Run `pmos docs list` and report it in the output sections below.
+
+Output contract — produce EXACTLY these sections, the same shape every run, one short line per document and copy:
+- Same
+- Ahead or behind
+- Edited in both
+- Could not check

package/workspace/skills/doc-sync.skill

@@ -0,0 +1,34 @@
+---
+name: doc-sync
+label: "Sync one linked document with its Google Docs or Confluence copy"
+description: "Write one version of a linked document over the other, in the direction the PM pressed: the PMOS version to the copy, or the copy's version to the repository file. One copy, one side, nothing else."
+run: agent
+agent: claude
+output:
+  - Written
+  - Not written
+---
+
+/doc-sync — the PM pressed "Use … version" for ONE copy of ONE document in Docs. Write that version over the other side, record it, and stop. The lines after this procedure name the file, the copy and the version to use.
+
+Rules that always hold:
+1. ONE COPY, ONE SIDE. With `use: pmos`, write the repository file's text to the copy, and change nothing in the repository. With `use: copy`, write the copy's text to the repository file, and change nothing in Google Docs or Confluence. Never write the other side, another copy, or another file.
+2. NEVER CREATE, MOVE, RENAME, SHARE OR DELETE. Update the existing Google Doc or Confluence page in place. If it does not exist or is in the trash, do not create it: record the sync as failed.
+3. KEEP THE FRONTMATTER. The repository file may start with a YAML frontmatter block (between two `---` lines). With `use: copy`, keep that block exactly as it is and replace only the text after it. With `use: pmos`, do not write the frontmatter to the copy.
+4. KEEP THE DOCUMENT. Convert between markdown and the copy's format faithfully: the same headings, paragraphs, lists, tables and links, in the same order. Do not add a summary, a note or a heading of your own.
+5. THE ONLY RECORDS are `pmos docs sync-start`, `pmos docs sync-finish` and `pmos docs sync-fail`. Never write a `*.jsonl` file by hand. Never commit or push: the PM's own Sync does that.
+6. USE THE PM'S CONNECTORS. Google Docs: the Google Drive tools. Confluence: the Atlassian tools. If the PM is asked to allow the write, that is expected; wait for their answer. If the connector is missing or refuses, record the sync as failed with the error.
+
+Procedure:
+1. Run `pmos docs sync-start <file> <google|confluence> --use <pmos|copy> --json` with the values below. Keep `run`, `target` and `remote_id`. If it is refused (for example, the copy is already being synced), stop and report the reason.
+2. Read the copy (its content, its version and its last-modified time) and the repository file.
+3. Write, by rule 1 to rule 4:
+   - `use: pmos`: update the copy's content with the repository file's body. Confluence: update the page with its next version number and keep its title. Google Docs: replace the document's content.
+   - `use: copy`: replace the repository file's body with the copy's content, converted to markdown. Keep the frontmatter.
+4. Read the copy again and take its version and last-modified time AFTER the write (with `use: copy` the copy did not change; take what you read in step 2).
+5. Run `pmos docs sync-finish <run> --version "<version>" --modified-at "<ISO time>" --url "<the copy's address>"`.
+6. If any step failed, run `pmos docs sync-fail <run> --reason "<the error, in one line>"` instead of step 5, and say what was and was not written.
+
+Output contract — produce EXACTLY these sections, one short line each:
+- Written
+- Not written

package/workspace/test-lists/docs-three-way-sync.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "docs-three-way-sync: the sync signal for documents linked to Google Docs and Confluence.",
+  "modules": ["doc-sync.test.js", "docs-cli.test.js"],
+  "panels": ["pm-docs-test.js"],
+  "seconds": { "doc-sync.test.js": 1, "docs-cli.test.js": 6, "pm-docs-test.js": 60 }
+}