create-pmos 0.55.4 → 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/goals.js

@@ -7,9 +7,16 @@
  *
  *   emptyDay(date)                         → { date, goals: [] }
  *   edit(day, op, { now })                 → { ok:true, day } | { ok:false, error }
- *        op: { action: 'add', text, initiative_id? } | { action: 'done'|'drop'|'reopen'|'remove', id }
+ *        op: { action: 'add', text, initiative_id?, repo? } | { action: 'done'|'drop'|'reopen'|'remove', id }
+ *            | { action: 'tag', id, repo }   (repo: a workspace id, or null for none)
  *   readDay(raw, date)                     → a checked day record, or an empty day when `raw` is not one
  *   planDay({ day, brief, cards, now, endOfDay }) → the plan Today and `pmos proactive goals` show
+ *   itemRepos({ day, brief, placeRepos })   → { itemId: repo } for the brief items that have a repository
+ *
+ * ONE DAY, REPOSITORY TAGS. The day is the PM's, not a repository's: every repository shows the same goals, brief and
+ * jobs. A goal can carry a repository (`repo`, a workspace id), and so can a channel, project or space (the settings'
+ * `placeRepos`). An item takes the repository of the open goal it is under; failing that, of the place it came from
+ * (its `where`). An item with neither is personal and shows under every repository.
  *
  * THE JOIN IS CHECKABLE. A brief item or calendar event belongs to a goal when it names the goal's id (the morning-brief
  * session sets it). Failing that, an item or Today card belongs to the first open goal tied to the same initiative. There
@@ -25,7 +32,9 @@ const crypto = require('crypto');
 const MAX_GOALS = 7;
 const MAX_TEXT = 140;
 const STATUSES = ['open', 'done', 'dropped'];
-const ACTIONS = ['add', 'done', 'drop', 'reopen', 'remove'];
+const ACTIONS = ['add', 'done', 'drop', 'reopen', 'remove', 'tag'];
+const REPO_RE = /^[A-Za-z0-9._-]{1,80}$/;
+const repoOrNull = (r) => (typeof r === 'string' && REPO_RE.test(r) ? r : null);
 const INI_RE = /^[a-z0-9][a-z0-9._-]*$/i;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const GOAL_ID_RE = /^g-[0-9a-f]{8}$/;
@@ -42,6 +51,7 @@ function readDay(raw, date) {
     && STATUSES.includes(g.status)).slice(0, MAX_GOALS).map((g) => ({
     id: g.id, text: clip(g.text, MAX_TEXT), initiative_id: typeof g.initiative_id === 'string' && INI_RE.test(g.initiative_id) ? g.initiative_id : null,
     status: g.status, added_at: typeof g.added_at === 'string' ? g.added_at : null, closed_at: typeof g.closed_at === 'string' ? g.closed_at : null,
+    repo: repoOrNull(g.repo),
   }));
   return { date, goals };
 }
@@ -58,16 +68,22 @@ function edit(day, op, { now = Date.now() } = {}) {
     if (goals.length >= MAX_GOALS) return { ok: false, error: `a day has at most ${MAX_GOALS} goals. Drop or remove one first.` };
     const ini = op.initiative_id == null || op.initiative_id === '' ? null : op.initiative_id;
     if (ini !== null && (typeof ini !== 'string' || !INI_RE.test(ini))) return { ok: false, error: 'initiative_id is not an initiative id' };
+    if (op.repo != null && op.repo !== '' && !repoOrNull(op.repo)) return { ok: false, error: 'repo is not a workspace id' };
     const text = clip(op.text, MAX_TEXT);
     if (goals.some((g) => g.text.toLowerCase() === text.toLowerCase())) return { ok: false, error: 'that goal is already on the list' };
     const id = 'g-' + crypto.createHash('sha1').update(`${day.date}|${text}|${at}|${goals.length}`).digest('hex').slice(0, 8);
-    goals.push({ id, text, initiative_id: ini, status: 'open', added_at: at, closed_at: null });
+    goals.push({ id, text, initiative_id: ini, status: 'open', added_at: at, closed_at: null, repo: repoOrNull(op.repo) });
     return { ok: true, day: { date: day.date, goals }, goal: goals[goals.length - 1] };
   }
   const i = goals.findIndex((g) => g.id === op.id);
   if (i < 0) return { ok: false, error: 'no goal with that id today' };
   const g = goals[i];
   if (op.action === 'remove') { goals.splice(i, 1); return { ok: true, day: { date: day.date, goals }, goal: g }; }
+  if (op.action === 'tag') {
+    if (op.repo != null && op.repo !== '' && !repoOrNull(op.repo)) return { ok: false, error: 'repo is not a workspace id' };
+    g.repo = repoOrNull(op.repo);
+    return { ok: true, day: { date: day.date, goals }, goal: g };
+  }
   const to = { done: 'done', drop: 'dropped', reopen: 'open' }[op.action];
   if (g.status === to) return { ok: false, error: `that goal is already ${to}` };
   g.status = to; g.closed_at = to === 'open' ? null : at;
@@ -184,4 +200,28 @@ function planDay({ day, brief = null, cards = [], now = Date.now(), endOfDay = E
   };
 }
 
-module.exports = { MAX_GOALS, MAX_TEXT, STATUSES, ACTIONS, GOAL_ID_RE, START_OF_DAY, END_OF_DAY, emptyDay, readDay, edit, freeTime, planDay };
+/** The place an item came from, as a key that a place name can match: lower case, no leading '#', and a Jira issue key
+ *  (PAY-412) reduced to its project key (pay). A place named "PAY · Payments" matches by its first word. */
+const placeKey = (s) => { const t = String(s || '').trim().toLowerCase().replace(/^#/, ''); const k = /^([a-z][a-z0-9]*)-\d+$/.exec(t); return k ? k[1] : t; };
+const placeNameKeys = (n) => { const t = String(n || '').trim().toLowerCase().replace(/^#/, ''); return [t, t.split(/[\s·:|]+/)[0]].filter(Boolean); };
+
+/** { itemId: repo } for today's brief items: the repository of the open goal an item is under, else of its place. */
+function itemRepos({ day, brief, placeRepos = {} } = {}) {
+  const out = {};
+  if (!brief || !day || brief.date !== day.date) return out;
+  const open = (day.goals || []).filter((g) => g.status === 'open');
+  const byId = new Map(open.map((g) => [g.id, g]));
+  const byIni = (ini) => (ini ? open.find((g) => g.initiative_id === ini) || null : null);
+  for (const x of [...(brief.priorities || []), ...(brief.worth_asking || [])]) {
+    const g = (x.goal && byId.get(x.goal)) || byIni(x.initiative_id);
+    let r = g ? repoOrNull(g.repo) : null;
+    if (!r && x.where) {
+      const want = placeKey(x.where);
+      for (const [name, repo] of Object.entries(placeRepos[x.source] || {})) if (placeNameKeys(name).includes(want) && repoOrNull(repo)) { r = repo; break; }
+    }
+    if (r) out[x.id] = r;
+  }
+  return out;
+}
+
+module.exports = { MAX_GOALS, MAX_TEXT, STATUSES, ACTIONS, GOAL_ID_RE, START_OF_DAY, END_OF_DAY, emptyDay, readDay, edit, freeTime, planDay, itemRepos };

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/lib/proactive.js

@@ -44,7 +44,7 @@ const MAX_WEBSITES = 10;
 const DAY_CHECK_EVERY = [0, 30, 60];
 const DAY_CHECK_DEFAULT = Object.freeze({ every: 60, start: '09:00', end: '18:00' });
 const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, backgroundPrepare: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false,
-  scopes: Object.freeze({ slack: Object.freeze({}), jira: Object.freeze({}), confluence: Object.freeze({}) }), dayCheck: DAY_CHECK_DEFAULT, websites: Object.freeze([]) });
+  scopes: Object.freeze({ slack: Object.freeze({}), jira: Object.freeze({}), confluence: Object.freeze({}) }), placeRepos: Object.freeze({ slack: Object.freeze({}), jira: Object.freeze({}), confluence: Object.freeze({}) }), dayCheck: DAY_CHECK_DEFAULT, websites: Object.freeze([]) });
 
 const idOf = (key) => crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 12);
 const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
@@ -178,7 +178,7 @@ const HHMM = /^([01]\d|2[0-3]):([0-5]\d)$/;
 function normalizeSettings(raw) {
   const r = raw && typeof raw === 'object' ? raw : {};
   const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, backgroundPrepare: DEFAULTS.backgroundPrepare, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning,
-    scopes: { slack: {}, jira: {}, confluence: {} }, dayCheck: { ...DAY_CHECK_DEFAULT }, websites: [] };
+    scopes: { slack: {}, jira: {}, confluence: {} }, placeRepos: { slack: {}, jira: {}, confluence: {} }, dayCheck: { ...DAY_CHECK_DEFAULT }, websites: [] };
   if (r.enabled !== undefined) { if (typeof r.enabled !== 'boolean') return { ok: false, error: 'enabled must be true or false' }; s.enabled = r.enabled; }
   if (r.name !== undefined) { if (typeof r.name !== 'string' || r.name.length > 40) return { ok: false, error: 'name must be text of at most 40 characters' }; s.name = r.name.replace(/\s+/g, ' ').trim(); }
   if (r.briefScoring !== undefined) { if (typeof r.briefScoring !== 'boolean') return { ok: false, error: 'briefScoring must be true or false' }; s.briefScoring = r.briefScoring; }
@@ -228,6 +228,24 @@ function normalizeSettings(raw) {
       s.scopes[svc] = out;
     }
   }
+  // placeRepos: the repository a channel, project or space belongs to (a workspace id). Today shows its mentions and jobs
+  // under that repository; a place with none is personal. null clears it; the route merges a patch over what is stored.
+  if (r.placeRepos !== undefined) {
+    if (!r.placeRepos || typeof r.placeRepos !== 'object' || Array.isArray(r.placeRepos)) return { ok: false, error: `placeRepos must be an object of ${SCOPE_SERVICES.join(', ')} → {name: workspace id}` };
+    for (const [svc, names] of Object.entries(r.placeRepos)) {
+      if (!SCOPE_SERVICES.includes(svc)) return { ok: false, error: `unknown placeRepos service "${svc}" — one of ${SCOPE_SERVICES.join(', ')}` };
+      if (!names || typeof names !== 'object' || Array.isArray(names)) return { ok: false, error: `placeRepos.${svc} must be an object of name → workspace id` };
+      const out = {};
+      for (const [name, repo] of Object.entries(names)) {
+        if (repo === null || repo === '') continue;
+        if (!name.trim() || name.length > 120) return { ok: false, error: `a ${svc} name is 1 to 120 characters` };
+        if (typeof repo !== 'string' || !/^[A-Za-z0-9._-]{1,80}$/.test(repo)) return { ok: false, error: `the repository of ${svc} "${name}" must be a workspace id` };
+        out[name] = repo;
+      }
+      if (Object.keys(out).length > MAX_SCOPE_NAMES) return { ok: false, error: `placeRepos.${svc} has ${Object.keys(out).length} names — at most ${MAX_SCOPE_NAMES}` };
+      s.placeRepos[svc] = out;
+    }
+  }
   if (r.dayCheck !== undefined) {
     const d = r.dayCheck;
     if (!d || typeof d !== 'object' || Array.isArray(d)) return { ok: false, error: 'dayCheck must be {every, start, end}' };

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.55.4",
+  "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;