create-pmos 0.55.5 → 0.56.0

package/workspace/lib/doc-sync.js

@@ -0,0 +1,225 @@
+'use strict';
+/* doc-sync.js — the sync SIGNAL for documents linked to Google Docs and Confluence (initiative docs-three-way-sync).
+ *
+ * The PM asked for no automatic sync: "I want signal if synced file on pmos is obsolete or ahead or same as the one of
+ * other services." So this module decides one word per link — same, ahead, behind, diverged — and never a write.
+ *
+ * PURE: no require, no file, no network, no clock. lib/doc-sync-store.js reads the links, the readings and the
+ * repository files and passes them in.
+ *
+ *   checkRow(row)                          → { ok:true, row } | { ok:false, error }   the gate every ledger line passes
+ *   readingsByLink(rows)                   → Map "<path>|<kind>" → readings, oldest first (refused lines skipped)
+ *   runsOf(rows)                           → { runs, open, last, syncs }   checks, and the syncs the PM pressed
+ *   signal(link, readings, repo)           → { signal, words, basis, checked_at, … }
+ *   remoteIdOf(kind, target)               → the Google Doc id or Confluence page id in a pasted link
+ *
+ * ── How a signal is decided ────────────────────────────────────────────────────────────────────────────────────
+ * A READING is what a check session saw for one link: whether the copy exists, its version and modified time, and
+ * whether its text is the same as the repository file's body, with the hash of that file at that moment.
+ * The BASELINE is the latest reading that found the text the same. Against it:
+ *   repo changed   = the file's hash now ≠ the baseline's hash
+ *   remote changed = the latest reading's version ≠ the baseline's version
+ *   neither → same · repo only → ahead · remote only → behind · both → diverged.
+ * With no baseline (the copies have never matched) the newer modified time decides and `basis` says 'date'.
+ *
+ * ── The rule this module carries forward ───────────────────────────────────────────────────────────────────────
+ * A reading cannot be asserted, only evidenced (four-panel.js, `resolved` and `applied`). A reading must name the
+ * session or profile that read, and the check it belongs to. `same: true` must carry the repository hash it was
+ * compared with. No signal but `unchecked` exists without a reading, and nothing here turns a clock into a claim about
+ * a copy.
+ *
+ * ── Sync on the PM's press (amended 2026-10-06) ────────────────────────────────────────────────────────────────
+ * The PM reviewed the mockup and asked to sync one copy at a time, in the direction they pick. A sync is a `run` row
+ * with `mode: 'sync'`, the link it is about and `use` (pmos: the repository text is written to the copy; copy: the
+ * copy's text is written to the repository file). It is started, then finished or failed. A finished sync writes a
+ * reading that says the two sides are the same, so the baseline moves to what was just written. This module still
+ * writes nothing: a session holding the PM's connectors does the write and records it through `pmos docs`.
+ */
+
+const KINDS = Object.freeze(['google', 'confluence']);
+const KIND_LABEL = Object.freeze({ google: 'Google Docs', confluence: 'Confluence' });
+const EVENTS = Object.freeze(['run', 'reading']);
+const SIGNALS = Object.freeze(['same', 'ahead', 'behind', 'diverged', 'unchecked', 'unreadable', 'missing-remote', 'missing-repo']);
+// What needs the PM's eye: everything but `same`. `unchecked` is included — a copy nobody read is not known to match.
+const ATTENTION = Object.freeze(SIGNALS.filter((s) => s !== 'same'));
+const RUN_ID = /^r-[0-9a-z]{6,32}$/;
+const USES = Object.freeze(['pmos', 'copy']);
+const HASH = /^[0-9a-f]{16,64}$/;
+
+const str = (v, n = 300) => (v == null || v === '' ? null : String(v).slice(0, n));
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+const keyOf = (p, kind) => `${p}|${kind}`;
+
+/** A repository path a link may name: relative, inside the repository. */
+function okPath(p) {
+  if (typeof p !== 'string' || !p || p.length > 300) return false;
+  return !(p.startsWith('/') || p.includes('\\') || p.split('/').some((s) => s === '..' || s === '.' || s === ''));
+}
+
+/** The id inside a pasted link, so the same copy pasted in two shapes is one copy. */
+function remoteIdOf(kind, target) {
+  const t = String(target || '').trim();
+  if (!t) return null;
+  if (kind === 'google') {
+    const m = /\/d\/([A-Za-z0-9_-]{10,})/.exec(t) || /[?&]id=([A-Za-z0-9_-]{10,})/.exec(t);
+    if (m) return m[1];
+    return /^[A-Za-z0-9_-]{10,}$/.test(t) ? t : null;
+  }
+  if (kind === 'confluence') {
+    const m = /\/pages\/(?:edit-v2\/)?(\d+)/.exec(t) || /[?&]pageId=(\d+)/.exec(t);
+    if (m) return m[1];
+    return /^\d+$/.test(t) ? t : null;
+  }
+  return null;
+}
+
+/** The one gate every ledger line passes. A refused row is never written, and the readers skip it. */
+function checkRow(input) {
+  if (!isObj(input)) return { ok: false, error: 'a ledger row is an object' };
+  const ev = String(input.ev || '');
+  if (!EVENTS.includes(ev)) return { ok: false, error: `ev must be one of: ${EVENTS.join(', ')}` };
+  const at = str(input.at, 40);
+  if (!at || Number.isNaN(Date.parse(at))) return { ok: false, error: 'at must be an ISO time' };
+  if (!RUN_ID.test(String(input.run || ''))) return { ok: false, error: 'run must name a check (r-…)' };
+  const by = str(input.by, 120);
+  if (!by) return { ok: false, error: `a ${ev === 'run' ? 'check' : 'reading'} must name the session or profile that made it — PMOS read nothing itself` };
+
+  if (ev === 'run') {
+    if (input.mode === 'sync') {
+      if (!['started', 'finished', 'failed'].includes(input.state)) return { ok: false, error: 'a sync state is started, finished or failed' };
+      if (!okPath(input.path)) return { ok: false, error: 'a sync names the repository file it is about' };
+      if (!KINDS.includes(input.kind)) return { ok: false, error: `a sync names its copy: ${KINDS.join(' or ')}` };
+      if (!USES.includes(input.use)) return { ok: false, error: 'a sync says which version it uses: pmos or copy' };
+      const summary = str(input.summary, 400);
+      if (input.state === 'failed' && !summary) return { ok: false, error: 'a failed sync says why' };
+      return { ok: true, row: { ev, at, run: input.run, mode: 'sync', state: input.state, by, path: input.path, kind: input.kind, use: input.use, summary } };
+    }
+    if (!['started', 'finished'].includes(input.state)) return { ok: false, error: 'state must be started or finished' };
+    return { ok: true, row: { ev, at, run: input.run, state: input.state, by, summary: str(input.summary, 400) } };
+  }
+
+  if (!okPath(input.path)) return { ok: false, error: 'path must be a repository-relative path' };
+  if (!KINDS.includes(input.kind)) return { ok: false, error: `kind must be one of: ${KINDS.join(', ')}` };
+  const error = str(input.error, 300);
+  if (!error && typeof input.exists !== 'boolean') return { ok: false, error: 'a reading says exists: true or false, or carries the error' };
+  const exists = error ? null : input.exists;
+  const version = str(input.version, 120);
+  if (exists === true && !version) return { ok: false, error: 'a reading of a copy that exists must carry its version' };
+  let same = null;
+  if (exists === true && input.same != null) {
+    if (typeof input.same !== 'boolean') return { ok: false, error: 'same is true or false' };
+    same = input.same;
+  }
+  const repo_hash = input.repo_hash == null || input.repo_hash === '' ? null : String(input.repo_hash);
+  if (repo_hash && !HASH.test(repo_hash)) return { ok: false, error: 'repo_hash is the hash `pmos docs check-start` gave for the file' };
+  if (same === true && !repo_hash) return { ok: false, error: 'a reading that says the text is the same must carry the repository hash it was compared with' };
+  const modified_at = str(input.modified_at, 40);
+  if (modified_at && Number.isNaN(Date.parse(modified_at))) return { ok: false, error: 'modified_at must be an ISO time' };
+  return {
+    ok: true,
+    row: {
+      ev, at, run: input.run, by, path: input.path, kind: input.kind,
+      remote_id: str(input.remote_id, 200), exists, version, modified_at, same, repo_hash,
+      title: str(input.title, 300), url: str(input.url, 400), error, note: str(input.note, 300),
+      modified_by: str(input.modified_by, 120),
+    },
+  };
+}
+
+/** The readings of every link, oldest first. A line that fails checkRow is skipped, never guessed. */
+function readingsByLink(rows) {
+  const by = new Map();
+  for (const raw of Array.isArray(rows) ? rows : []) {
+    const c = checkRow(raw);
+    if (!c.ok || c.row.ev !== 'reading') continue;
+    const k = keyOf(c.row.path, c.row.kind);
+    if (!by.has(k)) by.set(k, []);
+    by.get(k).push(c.row);
+  }
+  return by;
+}
+
+/** Every check, the one still open (started, not finished), the last one that finished, and every sync. */
+function runsOf(rows) {
+  const runs = new Map();
+  const syncs = new Map();
+  for (const raw of Array.isArray(rows) ? rows : []) {
+    const c = checkRow(raw);
+    if (!c.ok || c.row.ev !== 'run') continue;
+    const r = c.row;
+    if (r.mode === 'sync') {
+      const cur = syncs.get(r.run) || { run: r.run, by: r.by, path: r.path, kind: r.kind, use: r.use, state: 'started', started_at: null, ended_at: null, reason: null };
+      if (r.state === 'started') cur.started_at = cur.started_at || r.at;
+      else if (!cur.ended_at) { cur.state = r.state; cur.ended_at = r.at; cur.reason = r.state === 'failed' ? r.summary : null; }
+      syncs.set(r.run, cur);
+      continue;
+    }
+    const cur = runs.get(r.run) || { run: r.run, by: r.by, started_at: null, finished_at: null, summary: null };
+    if (r.state === 'started') cur.started_at = cur.started_at || r.at;
+    else { cur.finished_at = r.at; cur.summary = r.summary; }
+    runs.set(r.run, cur);
+  }
+  const list = [...runs.values()];
+  return {
+    runs: list,
+    open: list.filter((r) => r.started_at && !r.finished_at).pop() || null,
+    last: list.filter((r) => r.finished_at).pop() || null,
+    syncs: [...syncs.values()].filter((x) => x.started_at),
+  };
+}
+
+/**
+ * The signal for one link. `link` = { artifact_path, kind, target }. `readings` = this link's readings, oldest first.
+ * `repo` = { exists, hash, modified_at } for the repository file now. A reading of a different copy (the PM changed
+ * the link since) does not count: it read something this link no longer names.
+ */
+function signal(link, readings, repo) {
+  const kind = link.kind;
+  const label = KIND_LABEL[kind] || kind;
+  const rid = remoteIdOf(kind, link.target);
+  const mine = (Array.isArray(readings) ? readings : []).filter((r) => !rid || !r.remote_id || r.remote_id === rid);
+  const last = mine[mine.length - 1] || null;
+  const base = [...mine].reverse().find((r) => r.exists === true && r.same === true) || null;
+  const out = (sig, words, extra = {}) => ({
+    signal: sig, words, basis: null, kind, label,
+    checked_at: last ? last.at : null, checked_by: last ? last.by : null,
+    title: last && last.title ? last.title : null,
+    url: (last && last.url) || (/^https?:\/\//i.test(String(link.target || '')) ? link.target : null),
+    note: last && last.note ? last.note : null,
+    remote_modified_at: last && last.modified_at ? last.modified_at : null,
+    remote_modified_by: last && last.modified_by ? last.modified_by : null, ...extra,
+  });
+  const r = repo || { exists: false };
+
+  if (!r.exists) return out('missing-repo', 'Not in the repo');
+  if (!last) return out('unchecked', 'Not checked yet');
+  if (last.error) return out('unreadable', `Could not check — ${last.error}`);
+  if (last.exists === false) return out('missing-remote', `Not found in ${label}`);
+
+  // The latest reading compared the text and found it different, with nothing changed since the baseline it would
+  // otherwise use: that baseline was wrong, so it is not used.
+  const stale = base && last !== base && last.same === false && last.version === base.version && last.repo_hash === base.repo_hash;
+  if (base && !stale) {
+    const repoChanged = base.repo_hash !== r.hash;
+    const remoteChanged = last.version !== base.version;
+    if (!repoChanged && !remoteChanged) return out('same', 'Same', { basis: 'text' });
+    if (repoChanged && !remoteChanged) return out('ahead', 'Ahead — the repo is newer', { basis: 'text' });
+    if (!repoChanged && remoteChanged) return out('behind', `Behind — ${label} is newer`, { basis: 'text' });
+    return out('diverged', 'Edited in both', { basis: 'text' });
+  }
+
+  // Never matched. The text differs (or was not compared): the newer side by modified time, and the row says so.
+  const remoteAt = Date.parse(last.modified_at || '');
+  const repoAt = Date.parse(r.modified_at || '');
+  if (Number.isNaN(remoteAt) || Number.isNaN(repoAt)) {
+    return out('diverged', 'Different, and no date says which is newer', { basis: 'date' });
+  }
+  return remoteAt > repoAt
+    ? out('behind', `Behind — ${label} is newer (by date)`, { basis: 'date' })
+    : out('ahead', 'Ahead — the repo is newer (by date)', { basis: 'date' });
+}
+
+module.exports = {
+  KINDS, KIND_LABEL, EVENTS, SIGNALS, ATTENTION, RUN_ID, USES,
+  checkRow, readingsByLink, runsOf, signal, remoteIdOf, okPath, keyOf,
+};

package/workspace/lib/docs-cli.js

@@ -0,0 +1,221 @@
+'use strict';
+/* docs-cli.js — `pmos docs`: the sync signal for documents linked to Google Docs and Confluence, from a terminal
+ * (initiative docs-three-way-sync).
+ *
+ *   pmos docs [list] [--attention] [--json]               each linked document and its signal per copy
+ *   pmos docs link <file> <google-or-confluence-link>     link a repository file to a copy
+ *   pmos docs unlink <file> google|confluence             remove that link (the copy is not touched)
+ *   pmos docs check-start [--json]                        open a check: what to read, with each file's hash
+ *   pmos docs record <check> --file <readings.json>       record what the session read
+ *   pmos docs check-finish <check> [--summary "…"]        close the check
+ *   pmos docs find [words]                                the repository's markdown files that match, with or without a copy
+ *   pmos docs sync-start <file> google|confluence --use pmos|copy [--json]   open a sync of one copy (the sync session)
+ *   pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]   close it: both sides now the same
+ *   pmos docs sync-fail <sync> --reason "…"               close it: nothing was written, and why
+ *
+ * The same module the Docs place reads (lib/doc-sync-store.js), so a terminal line and a row cannot disagree.
+ * No command writes a document. A check reads; a sync (amended 2026-10-06: the PM presses Use … version for one copy) is
+ * written by the doc-sync session with the PM's connectors, and these commands only record that it started and ended.
+ * check-start, record and check-finish are the check session's commands; each must name who read, which is the
+ * session's PMOS_SESSION token, or `--by <profile>` when the session runs outside the workspace.
+ *
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const D = require('./doc-sync');
+const store = require('./doc-sync-store');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { docs: ['list', 'link', 'unlink', 'check-start', 'record', 'check-finish', 'find', 'sync-start', 'sync-finish', 'sync-fail'] };
+const USAGE = [
+  'usage: pmos docs [list|link|unlink|find|check-start|record|check-finish|sync-start|sync-finish|sync-fail] — is each linked document the same as its Google Docs and Confluence copy',
+  '  pmos docs [list] [--attention] [--json]            each linked document and its signal: same, ahead, behind, edited in both',
+  '  pmos docs link <file> <link>                       link a repository file to a Google Doc or a Confluence page',
+  '  pmos docs unlink <file> google|confluence          remove that link; the copy is not touched',
+  '  pmos docs check-start [--json]                     (check session) open a check and list what to read',
+  '  pmos docs record <check> --file <readings.json>    (check session) record what was read',
+  '  pmos docs check-finish <check> [--summary "…"]     (check session) close the check',
+  '  pmos docs find [words]                             the repository\'s markdown files that match',
+  '  pmos docs sync-start <file> google|confluence --use pmos|copy   (sync session) open a sync of one copy',
+  '  pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]   (sync session) both sides are now the same',
+  '  pmos docs sync-fail <sync> --reason "…"            (sync session) nothing was written, and why',
+  'Nothing here writes a document. Press Check now, or Use … version on one copy, in Docs.',
+];
+const BOOL = new Set(['json', 'attention', 'help']);
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+/** Who is reading: the workspace session's token names it; outside the workspace, the profile the PM names. */
+function whoOf(flags, env) {
+  const tok = String(env.PMOS_SESSION || '').trim();
+  if (tok) return 'session:' + tok.split('.')[0].slice(0, 60);
+  if (flags.by) return 'profile:' + String(flags.by).slice(0, 60);
+  return null;
+}
+const kindOf = (target) => {
+  if (D.remoteIdOf('confluence', target) && /atlassian|confluence|\/wiki\/|pageId=/i.test(target)) return 'confluence';
+  if (D.remoteIdOf('google', target) && /google|docs\.|drive\./i.test(target)) return 'google';
+  return null;
+};
+const ago = (iso, now) => {
+  if (!iso) return 'never';
+  const m = Math.round((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`;
+};
+
+async function run(argv, { say = console.log, cwd = process.cwd(), env = process.env, now = Date.now() } = {}) {
+  const { pos, flags } = parse(argv.slice(1));
+  const sub = pos[0] || 'list';
+  if (flags.help || sub === 'help') { USAGE.forEach((l) => say(l)); return 0; }
+  const json = !!flags.json;
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const rel = (p) => {
+    const abs = path.resolve(cwd, p);
+    const r = path.relative(root, abs).split(path.sep).join('/');
+    return r.startsWith('..') ? null : r;
+  };
+
+  if (sub === 'list') {
+    const v = store.view(root);
+    if (!v.ok) return fail(v.error);
+    const docs = flags.attention ? v.docs.filter((d) => d.attention) : v.docs;
+    if (json) { say(JSON.stringify({ ...v, docs })); return 0; }
+    if (!v.docs.length) { say('No document is linked to Google Docs or Confluence. Link one: pmos docs link <file> <link>'); return 0; }
+    const s = v.summary;
+    say(`Docs · ${s.documents} document${s.documents === 1 ? '' : 's'} · ${s.same} same · ${s.ahead} ahead · ${s.behind} behind · ${s.diverged} edited in both · ${s.unchecked} not checked`);
+    say(v.last ? `Last check ${ago(v.last.finished_at, now)}${v.last.summary ? ': ' + v.last.summary : ''}` : 'Never checked. Press Check now in Docs.');
+    if (v.open) say(`A check is running (started ${ago(v.open.started_at, now)}).`);
+    for (const d of docs) {
+      say(`${d.title}  (${d.path})`);
+      for (const l of d.links) say(`  ${l.label.padEnd(12)} ${l.words}${l.checked_at ? ' · checked ' + ago(l.checked_at, now) : ''}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'link') {
+    const [file, target] = [pos[1], pos[2]];
+    if (!file || !target) return fail('usage: pmos docs link <file> <google-or-confluence-link>', 2);
+    const kind = flags.kind || kindOf(target);
+    if (!kind) return fail('that is not a Google Docs or Confluence link — paste the page\'s address');
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const w = store.addLink(root, { path: r, kind, target });
+    if (!w.ok) return fail(w.error);
+    if (json) say(JSON.stringify({ ok: true, path: r, kind })); else say(`✓ ${r} is linked to ${D.KIND_LABEL[kind]}. Its signal shows after the next check.`);
+    return 0;
+  }
+
+  if (sub === 'unlink') {
+    const [file, kind] = [pos[1], pos[2]];
+    if (!file || !D.KINDS.includes(kind)) return fail('usage: pmos docs unlink <file> google|confluence', 2);
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const w = store.removeLink(root, { path: r, kind });
+    if (!w.ok) return fail(w.error);
+    if (json) say(JSON.stringify({ ok: true })); else say(`✓ ${r} is no longer linked to ${D.KIND_LABEL[kind]}. The copy is not touched.`);
+    return 0;
+  }
+
+  if (sub === 'find') {
+    const found = store.findFiles(root, pos.slice(1).join(' '));
+    const v = store.view(root);
+    const linked = new Map((v.ok ? v.docs : []).map((d) => [d.path, d.links.map((l) => l.label)]));
+    const files = found.map((f) => ({ ...f, copies: linked.get(f.path) || [] }));
+    if (json) { say(JSON.stringify({ ok: true, files })); return 0; }
+    if (!files.length) { say('No markdown file matches.'); return 0; }
+    for (const f of files) say(`${f.title}  (${f.path})  ${f.copies.length ? f.copies.join(', ') : 'no copy'}`);
+    return 0;
+  }
+
+  const by = whoOf(flags, env);
+  if (sub === 'check-start') {
+    if (!by) return fail('a check must name who reads: run it in a workspace session, or add --by <profile>');
+    const s = store.checkStart(root, { by, now: new Date(now) });
+    if (!s.ok) return fail(s.error);
+    if (json) { say(JSON.stringify(s)); return 0; }
+    say(`Check ${s.run} · ${s.links.length} link${s.links.length === 1 ? '' : 's'} to read`);
+    for (const l of s.links) say(`  ${l.path}  ${D.KIND_LABEL[l.kind]}  ${l.target}  hash ${l.repo_hash || '(no file)'}`);
+    return 0;
+  }
+  if (sub === 'record') {
+    const runId = pos[1];
+    if (!runId || !flags.file) return fail('usage: pmos docs record <check> --file <readings.json>', 2);
+    if (!by) return fail('a reading must name who read: run it in a workspace session, or add --by <profile>');
+    let readings;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.resolve(cwd, flags.file), 'utf8'));
+      readings = Array.isArray(parsed) ? parsed : parsed.readings;
+    } catch (e) { return fail(`could not read ${flags.file}: ${String((e && e.message) || e).slice(0, 160)}`); }
+    const r = store.record(root, { run: runId, by, readings, now: new Date(now) });
+    if (json) say(JSON.stringify(r));
+    else {
+      say(`${r.recorded ? r.recorded.length : 0} reading(s) recorded.`);
+      for (const x of r.refused || []) say(`✗ ${x.path} ${x.kind}: ${x.error}`);
+      if (!r.recorded && r.error) say(`✗ ${r.error}`);
+    }
+    return r.ok ? 0 : 1;
+  }
+  if (sub === 'check-finish') {
+    const runId = pos[1];
+    if (!runId) return fail('usage: pmos docs check-finish <check> [--summary "…"]', 2);
+    if (!by) return fail('a check must name who ran it: run it in a workspace session, or add --by <profile>');
+    const r = store.checkFinish(root, { run: runId, by, summary: flags.summary || null, now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    const v = store.view(root);
+    if (json) say(JSON.stringify({ ok: true, summary: v.ok ? v.summary : null }));
+    else say(v.ok ? `✓ Check closed · ${v.summary.same} same · ${v.summary.ahead} ahead · ${v.summary.behind} behind · ${v.summary.diverged} edited in both` : '✓ Check closed');
+    return 0;
+  }
+  if (sub === 'sync-start') {
+    const [file, kind] = [pos[1], pos[2]];
+    if (!file || !D.KINDS.includes(kind) || !D.USES.includes(flags.use)) return fail('usage: pmos docs sync-start <file> google|confluence --use pmos|copy', 2);
+    if (!by) return fail('a sync must name who writes: run it in a workspace session, or add --by <profile>');
+    const r = rel(file);
+    if (!r) return fail(`${file} is not inside this repository`);
+    const s = store.syncStart(root, { path: r, kind, use: flags.use, by, now: new Date(now) });
+    if (!s.ok) return fail(s.error);
+    if (json) { say(JSON.stringify(s)); return 0; }
+    say(`Sync ${s.run} · ${s.path} · ${s.use === 'pmos' ? 'write the PMOS version to ' + s.label : 'write the ' + s.label + ' version to PMOS'} · ${s.target}`);
+    return 0;
+  }
+  if (sub === 'sync-finish') {
+    const runId = pos[1];
+    if (!runId || !flags.version) return fail('usage: pmos docs sync-finish <sync> --version <v> [--modified-at <t>] [--url <u>]', 2);
+    if (!by) return fail('a sync must name who wrote: run it in a workspace session, or add --by <profile>');
+    const r = store.syncFinish(root, { run: runId, by, version: flags.version, modified_at: flags['modified-at'] || null,
+      modified_by: flags['modified-by'] || null, url: flags.url || null, now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    if (json) say(JSON.stringify({ ok: true })); else say('✓ Sync closed. Both sides are the same.');
+    return 0;
+  }
+  if (sub === 'sync-fail') {
+    const runId = pos[1];
+    if (!runId || !flags.reason) return fail('usage: pmos docs sync-fail <sync> --reason "…"', 2);
+    if (!by) return fail('a sync must name who ran it: run it in a workspace session, or add --by <profile>');
+    const r = store.syncFail(root, { run: runId, by, reason: String(flags.reason), now: new Date(now) });
+    if (!r.ok) return fail(r.error);
+    if (json) say(JSON.stringify({ ok: true })); else say('✓ Sync closed as failed. Nothing was written.');
+    return 0;
+  }
+  return fail(`pmos docs ${sub} is not a command. ${USAGE[0]}`, 2);
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/pmos-verbs.js

@@ -35,6 +35,9 @@ const VERBS = Object.freeze({
   report: Object.freeze({ module: 'report-cli.js', run: 5, guide: 'reports.md',
     help: 'pmos report draft|issue|list … — draft and issue reports (pmos report help)' }),
   // Not a pm-os-absorb verb (run: null): the workspace-launcher initiative added it through the same table.
+  // Not a pm-os-absorb verb (run: null): docs-three-way-sync added it through the same table.
+  docs: Object.freeze({ module: 'docs-cli.js', run: null, guide: 'docs.md',
+    help: 'pmos docs [list|link|unlink|find] … — is each linked document the same as, ahead of or behind its Google Docs and Confluence copy, and record a sync (pmos docs help)' }),
   launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
     help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.55.5",
+  "version": "0.56.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.55.5",
+  "version": "0.56.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/app.js

@@ -406,7 +406,7 @@ function render() {
 
 const FRAME = !FIXTURE && !LEGACY_LAYOUT_FLAG;
 const FRAME_KEY = 'pmos.workspace.pm.frame';
-const FRAME_DESTS = Object.freeze(['today', 'initiatives', 'board', 'reports', 'settings']);
+const FRAME_DESTS = Object.freeze(['today', 'initiatives', 'board', 'reports', 'docs', 'settings']);
 
 function readFrame() {
   if (!FRAME) return {};
@@ -637,7 +637,7 @@ function pressIn(r, key) {
   if (b && !b.disabled) { b.click(); return true; }
   return false;
 }
-const G_KEYS = { t: 'today', i: 'initiatives', b: 'board', r: 'reports' };
+const G_KEYS = { t: 'today', i: 'initiatives', b: 'board', r: 'reports', d: 'docs' };
 
 function frameKey(e) {
   const mod = e.metaKey || e.ctrlKey;

package/workspace/public/pm/components.css

@@ -4067,6 +4067,152 @@
   }
 }
 
+/* Docs (docs-three-way-sync): one line per copy — a status dot, the title over the copy's link, one sentence, one action. */
+.rp-docs {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.rp-docs-top {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+}
+.rp-docs-top > .rp-head__title {
+  margin-right: auto;
+}
+.rp-docs-find {
+  flex: 1 1 260px;
+  max-width: 420px;
+}
+.rp-docs-body {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.rp-docs-views {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  border-bottom: 1px solid var(--border);
+}
+.rp-docs-when {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-left: auto;
+  font-size: 12px;
+  color: var(--muted-foreground);
+}
+.rp-docs-group__title {
+  margin: 0;
+  padding: 8px 0;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--muted-foreground);
+}
+.rp-docs-row {
+  border-top: 1px solid var(--border);
+}
+.rp-docs-row:last-child {
+  border-bottom: 1px solid var(--border);
+}
+.rp-docs-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  background: var(--muted-foreground);
+}
+.rp-docs-dot--ok {
+  background: var(--muted-foreground);
+}
+.rp-docs-dot--warn {
+  background: var(--warning);
+}
+.rp-docs-dot--bad {
+  background: var(--destructive);
+}
+.rp-docs-dot--none {
+  background: transparent;
+  border: 1px solid var(--muted-foreground);
+}
+.rp-docs-open {
+  font-size: 12px;
+  color: var(--muted-foreground);
+  white-space: nowrap;
+  text-underline-offset: 2px;
+}
+.rp-docs-detail {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  padding: 4px 0 16px 24px;
+}
+.rp-docs-side {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+  min-width: 0;
+  padding: 12px;
+  border: 1px solid var(--border);
+}
+.rp-docs-side--new {
+  border-color: var(--foreground);
+}
+.rp-docs-side__label {
+  font-size: 12px;
+  color: var(--muted-foreground);
+}
+.rp-docs-side__where {
+  max-width: 100%;
+  font-family: var(--mono);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.rp-docs-side__edit {
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+.rp-docs-diff {
+  grid-column: 1 / -1;
+  margin: 0;
+  padding: 8px 10px;
+  border: 1px solid var(--border);
+  font-family: var(--mono);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.rp-docs-more {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.rp-docs-add {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 0 12px 24px;
+}
+.rp-docs-add__input {
+  flex: 1 1 240px;
+}
+.rp-docs-add__err {
+  flex-basis: 100%;
+  font-size: 12px;
+  color: var(--destructive);
+}
+@media (max-width: 640px) {
+  .rp-docs-detail {
+    grid-template-columns: 1fr;
+    padding-left: 0;
+  }
+}
+
 /* -- layouts · .lg- the legacy and fixture shells (Run 3, slice 3D) -- */
 /* The legacy and fixture cockpit's two columns: the list head (a stack) and the rail's tile column. */
 .lg-stack {