create-pmos 0.55.5 → 0.57.0

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
@@ -282,6 +288,64 @@ const layoutModel = require('./lib/layout');           // the arrangement model
 // REFUSED (BIND.refused) so the server exits — there is no code path to a public interface.
 const BIND = remoteAccess.resolveBinds({ env: process.env });
 const TOKEN = BIND.token || null;                     // non-loopback peers must present it; never logged (D08)
+// workspace-online-mode (D89): the Online switch. Its record lives in the per-user state folder; while it is on, the
+// workspace runs the tunnel itself and admits the public hostname, and a request to that hostname passes on a verified
+// Cloudflare Access assertion for the PM's email instead of the token. An environment-set PMOS_PUBLIC_HOST wins and keeps
+// the token (PRD O7). ONLINE.keys is the team's public key set (lib/access-keys.js, the one D89 fetch), only while on.
+const onlineMode = require('./lib/online-mode');
+const accessJwt = require('./lib/access-jwt');
+const accessKeys = require('./lib/access-keys');
+const ONLINE = { settings: onlineMode.read(STATE), keys: null, keysTeam: null, fetchKeys: accessKeys.fetchCerts, find: onlineMode.findCloudflared };
+const tunnel = onlineMode.createTunnel({ stateDir: STATE, find: () => ONLINE.find() });
+/** The public hostname the guards admit right now: the environment's, else the Online switch's while it is on. */
+function publicHost() { return BIND.publicHost || (ONLINE.settings.on ? ONLINE.settings.host : null); }
+/** True when this request is addressed to the Online switch's hostname, so the Access assertion decides it (D89). */
+function viaOnlineHost(headers) {
+  return !BIND.publicHost && ONLINE.settings.on && remoteAccess.hostnameOf((headers || {}).host) === ONLINE.settings.host;
+}
+/** Bring the tunnel and the key store in line with the record. Called at start, and after every change of the record. */
+function applyOnline() {
+  const s = ONLINE.settings;
+  if (s.on && !BIND.publicHost) {
+    if (!ONLINE.keys || ONLINE.keysTeam !== s.team) {
+      ONLINE.keys = accessKeys.createStore({ teamDomain: s.team, fetch: (d) => ONLINE.fetchKeys(d) });
+      ONLINE.keysTeam = s.team;
+      ONLINE.keys.ensure().catch(() => {});
+    }
+    if (ONLINE.tunnelName && ONLINE.tunnelName !== s.tunnel) tunnel.stop();
+    ONLINE.tunnelName = s.tunnel;
+    tunnel.start(s.tunnel);
+  } else {
+    tunnel.stop();
+    ONLINE.tunnelName = null;
+    ONLINE.keys = null; ONLINE.keysTeam = null;
+  }
+}
+/** The D89 decision for one request: { ok: true } or { ok: false, reason }. The assertion is never logged (D08). */
+async function accessVerdict(headers) {
+  const s = ONLINE.settings; const store = ONLINE.keys;
+  if (!store) return { ok: false, reason: 'no keys' };
+  try { await store.ensure(); } catch { /* the store records its own error */ }
+  const token = (headers || {})['cf-access-jwt-assertion'];
+  const opts = { keyFor: store.keyFor, teamDomain: s.team, audience: s.audience, email: s.email, now: Math.floor(Date.now() / 1000) };
+  let v = accessJwt.verify(token, opts);
+  if (!v.ok && v.reason === 'unknown key' && v.kid && await store.refetchFor(v.kid)) v = accessJwt.verify(token, opts);
+  return v;
+}
+/** The Online record and state, as GET /api/online returns it. Nothing secret is in it: the fields are not credentials. */
+function onlineView(req) {
+  const s = ONLINE.settings;
+  return {
+    ok: true, on: s.on, host: s.host, tunnel: s.tunnel, team: s.team, audience: s.audience, email: s.email,
+    complete: onlineMode.complete(s), envHost: BIND.publicHost || null, cloudflared: !!ONLINE.find(),
+    running: tunnel.status(), keys: ONLINE.keys ? ONLINE.keys.status() : null,
+    canChange: onlineChangeAllowed(req),
+  };
+}
+/** PRD O3: only the desktop changes the switch — a loopback peer that came through no proxy. */
+function onlineChangeAllowed(req) {
+  return remoteAccess.isLoopbackAddr(req.socket && req.socket.remoteAddress) && !remoteAccess.isProxied(req.headers || {}, publicHost());
+}
 // Per-OS default shell. On Windows there is no `bash` — use ComSpec/PowerShell.
 function defaultShell() {
   if (process.platform === 'win32') return process.env.COMSPEC || 'powershell.exe';
@@ -6389,6 +6453,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
@@ -7029,6 +7190,23 @@ async function handleRequest(req, res) {
   if (p === '/api/typesafe' && req.method === 'GET') {
     return json(res, { ok: true, key: tsSettings.status(STATE), host: tsClient.HOST });
   }
+  /* ── workspace-online-mode (D89): the Online switch. Any signed-in device may read it; only the desktop changes it (O3). ── */
+  if (p === '/api/online' && req.method === 'GET') return json(res, onlineView(req));
+  if (p === '/api/online' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    if (!onlineChangeAllowed(req)) return json(res, { ok: false, error: 'Online can only be changed on the computer that runs the workspace' }, 403);
+    const press = pmGuard.requirePagePress(req, body);
+    if (!press.ok) return json(res, { ok: false, error: press.error }, press.status || 403);
+    if (BIND.publicHost && body.on === true) return json(res, { ok: false, error: `PMOS_PUBLIC_HOST=${BIND.publicHost} was set when the workspace started, so it is already online that way. Restart it without PMOS_PUBLIC_HOST to use the switch.` }, 409);
+    if (body.on === true && !ONLINE.find()) return json(res, { ok: false, field: 'on', error: 'cloudflared is not installed. Install it (brew install cloudflared), then switch Online on again.' }, 409);
+    const out = onlineMode.save(STATE, body);
+    if (!out.ok) return json(res, { ok: false, field: out.field || null, error: out.error }, out.field ? 400 : 500);
+    ONLINE.settings = out.settings;
+    applyOnline();
+    return json(res, onlineView(req));
+  }
   if (p === '/api/typesafe/key' && (req.method === 'PUT' || req.method === 'DELETE')) {
     let body = {};
     if (req.method === 'PUT') {
@@ -7847,20 +8025,33 @@ function writeChangeContext(dir) {
 function httpGuard(req, res) {
   // Origin/Host allowlist FIRST (D64 A1): reject a cross-site / DNS-rebinding request before the
   // token exemption for loopback can be reached. Header values are never logged (D08).
-  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds, publicHost: BIND.publicHost })) {
+  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds, publicHost: publicHost() })) {
     res.writeHead(403, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: false, error: 'forbidden origin/host' }));
     return;
   }
   // workspace-public-host: a request to the public hostname must have passed Cloudflare Access. A tunnel
   // with no Access application in front fails here, before even the sign-in form can be reached.
-  if (!remoteAccess.edgeAllowed({ headers: req.headers, publicHost: BIND.publicHost })) {
+  if (!remoteAccess.edgeAllowed({ headers: req.headers, publicHost: publicHost() })) {
     res.writeHead(403, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: false, error: 'the public host is only reachable through Cloudflare Access' }));
     return;
   }
+  // workspace-online-mode (D89): on the Online switch's hostname the verified Access assertion is the whole check.
+  // It replaces the token, so neither the sign-in form nor the token cookie is reachable there.
+  if (viaOnlineHost(req.headers)) {
+    accessVerdict(req.headers).then((v) => {
+      if (v.ok) return handleRequest(req, res);
+      res.writeHead(403, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({ ok: false, error: 'your Cloudflare sign-in could not be verified for this workspace' }));
+    }, () => {
+      res.writeHead(403, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify({ ok: false, error: 'your Cloudflare sign-in could not be verified for this workspace' }));
+    });
+    return;
+  }
   // The cookie is Secure when the browser reached us on the public host (HTTPS at the edge).
-  const secureCookie = !!BIND.publicHost && remoteAccess.isProxied(req.headers, BIND.publicHost);
+  const secureCookie = !!publicHost() && remoteAccess.isProxied(req.headers, publicHost());
   // Token may arrive as an Authorization header, a ?token= query param, or the seeded cookie. A
   // browser only carries the token on the FIRST navigation URL — it cannot attach a header/query to
   // sub-resource loads (CSS/JS) or the WS upgrade — so the documented "open http://…/?token=<t>"
@@ -7883,7 +8074,7 @@ function httpGuard(req, res) {
     });
     return;
   }
-  if (!remoteAccess.authorize({ remoteAddress: req.socket.remoteAddress, headers: req.headers, publicHost: BIND.publicHost,
+  if (!remoteAccess.authorize({ remoteAddress: req.socket.remoteAddress, headers: req.headers, publicHost: publicHost(),
       presentedToken: remoteAccess.presentedToken(req), expectedToken: TOKEN })) {
     // A phone's browser gets a page it can act on, not JSON. API calls, scripts and anything else
     // that is not a page load keep the JSON 401 they had.
@@ -7899,7 +8090,7 @@ function httpGuard(req, res) {
   // navigation, so the browser's subsequent sub-resource + WS-upgrade requests authenticate without it
   // in the URL. HttpOnly (JS never needs it) + SameSite=Strict + the D64 Origin/Host allowlist keep a
   // foreign site from riding it; no Secure flag because the tailnet speaks plain HTTP (WireGuard-encrypted).
-  if (!remoteAccess.isLoopbackAddr(req.socket.remoteAddress) || remoteAccess.isProxied(req.headers, BIND.publicHost)) {
+  if (!remoteAccess.isLoopbackAddr(req.socket.remoteAddress) || remoteAccess.isProxied(req.headers, publicHost())) {
     let qTok = null;
     try { qTok = new URL(req.url || '', 'http://localhost').searchParams.get('token'); } catch { /* ignore */ }
     if (qTok && remoteAccess.tokenMatches(qTok.trim(), TOKEN)) {
@@ -7925,20 +8116,31 @@ function handleUpgrade(req, socket, head) {
   // Same origin/host allowlist on the WS upgrade handshake (D64 A1): a cross-origin page must not be
   // able to open ws://127.0.0.1:<port> and spawn/type into a shell. Rejected BEFORE the socket is
   // accepted, and before loopback's token exemption applies. Header values never logged (D08).
-  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds, publicHost: BIND.publicHost })
-      || !remoteAccess.edgeAllowed({ headers: req.headers, publicHost: BIND.publicHost })) {
+  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds, publicHost: publicHost() })
+      || !remoteAccess.edgeAllowed({ headers: req.headers, publicHost: publicHost() })) {
     socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
     socket.destroy();
     return;
   }
+  // workspace-online-mode (D89): the same verified-assertion rule as the HTTP guard, before the socket is accepted.
+  if (viaOnlineHost(req.headers)) {
+    accessVerdict(req.headers).then((v) => {
+      if (!v.ok) { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); socket.destroy(); return; }
+      acceptUpgrade(req, socket, head);
+    }, () => { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n'); socket.destroy(); });
+    return;
+  }
   // A browser WebSocket cannot set a header or a ?token= — it authenticates via the same-origin cookie
   // seeded on the page load. presentedToken() resolves header → query → subprotocol → cookie.
-  if (!remoteAccess.authorize({ remoteAddress: socket.remoteAddress, headers: req.headers, publicHost: BIND.publicHost,
+  if (!remoteAccess.authorize({ remoteAddress: socket.remoteAddress, headers: req.headers, publicHost: publicHost(),
       presentedToken: remoteAccess.presentedToken(req), expectedToken: TOKEN })) {
     socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
     socket.destroy();     // reject the upgrade; nothing about the request is logged (D08)
     return;
   }
+  acceptUpgrade(req, socket, head);
+}
+function acceptUpgrade(req, socket, head) {
   // R25 (bind): a session started with an initiative is bound to it, a PM-only act. Only a socket the page opened with
   // this launch's nonce (`?pmos-nonce=`) may bind; any other socket still spawns, unbound, and is told why.
   const bind = pmGuard.requirePmUpgrade(req, { act: 'bind' });
@@ -8081,6 +8283,7 @@ if (require.main === module) {
     if (shuttingDown) return; shuttingDown = true;
     for (const s of sessions.values()) if (s.pty) { try { persist(s); } catch {} }
     for (const l of listeners) { try { l.close(); } catch {} }
+    try { tunnel.stop(); } catch {}   // workspace-online-mode: the tunnel is this server's child and ends with it
     try { fs.unlinkSync(PID_FILE); } catch {}   // stop being discoverable the moment we stop serving
     process.exit(0);
   };
@@ -8113,12 +8316,15 @@ if (require.main === module) {
       // one started by `pmos` — otherwise the next `pmos` cannot see it and starts a second server.
       try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(PID_FILE, String(process.pid)); } catch {}
       for (const line of remoteAccess.startupLines(BIND, PORT, { ansi: !!process.stdout.isTTY && !process.env.NO_COLOR })) console.log(line);
+      // workspace-online-mode: a workspace that stopped while Online was on comes back online (PRD O2)
+      applyOnline();
+      if (ONLINE.settings.on && !BIND.publicHost) console.log(`  online: https://${ONLINE.settings.host}/ (Cloudflare Access sign-in, tunnel ${ONLINE.settings.tunnel})`);
       // bring in what another machine pushed while this one was off (D70 as amended); never on the request path
       { const t = setTimeout(() => { autoSync.startup().catch(() => {}); }, 3000); if (t.unref) t.unref(); }
     });
   });
 }
-module.exports = { server, spawnSession, removeSession, renameSession, sessions, libraryTree, readTextDoc,
+module.exports = { server, online: { ONLINE, applyOnline, tunnel, publicHost }, spawnSession, removeSession, renameSession, sessions, libraryTree, readTextDoc,
   registerWorkspace, forgetWorkspace, workspaces, library, initiativeIndex, fsList,
   // R1 — exported so the suite can assert the CARRY-THROUGH: branchInfo separates an ordinary
   // non-repo folder from a real git fault, and the whole legibility defect was that distinction

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 }
+}

package/workspace/test-lists/workspace-online-mode.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "workspace-online-mode (D89): the Cloudflare Access assertion check, the key store's fetch rules, the Online record and tunnel process, and the guards and /api/online driven on server.js as a library. No request leaves the process.",
+  "modules": ["online-mode.test.js"],
+  "seconds": { "online-mode.test.js": 4 }
+}