create-pmos 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ac2ee81
+kernel-source: pmos@bb78e24
 assembled: 2026-07-31
 mode: vendor

package/workspace/lib/four-panel.js

@@ -57,6 +57,15 @@ const path = require('path');
 
 const ARTIFACT_LINKS = 'artifact-links.jsonl';
 const INITIATIVE_LINKS = 'initiative-links.jsonl';
+/**
+ * The THIRD store, and the newest place this module has to refuse something.
+ *
+ * A link says *this file corresponds to that page*. A sync row says *the PM decided which way the
+ * content should travel, and here is what came back*. They are different facts with different
+ * lifetimes — a link outlives any number of syncs — so they are different files rather than a
+ * `direction` column bolted onto a link row, where every re-sync would supersede the link itself.
+ */
+const ARTIFACT_SYNC = 'artifact-sync.jsonl';
 
 /** The destinations the surface can declare. A kind outside this set is refused, not stored. */
 const LINK_KINDS = ['confluence', 'jira', 'google'];
@@ -70,12 +79,38 @@ const LINK_KINDS = ['confluence', 'jira', 'google'];
  *   resolved    — a lookup performed BY A SESSION that holds the PM's MCP returned this record.
  *                 Carries the destination's own title and the moment it was read.
  *   unreachable — a lookup was attempted and did not succeed. Carries the reason it failed.
+ *   retracted   — the PM withdrew this reference. It is a STATE and not an absence, because the
+ *                 store is append-only and "the PM removed this" is a fact worth keeping; a link
+ *                 deleted from disk would be a link that never existed, and the history of what the
+ *                 PM declared is the whole reason this file is a ledger. A later declaration for
+ *                 the same pair brings the reference back, because `linkView` reads the latest row
+ *                 and nothing here is a tombstone.
  *
  * `connected` was the word this surface used before, and it is retired rather than re-worded: PMOS
  * is never connected to anything — a session is — so the word had no honest referent here. It is
  * also the word that let a row the PM had merely declared read as a row PMOS had verified.
  */
-const LINK_STATES = ['declared', 'resolved', 'unreachable'];
+const LINK_STATES = ['declared', 'resolved', 'unreachable', 'retracted'];
+
+/**
+ * Which way the content travels, and what happened. The sync store's own closed vocabulary.
+ *
+ *   push  — the repo file is the source; its content goes to the destination.
+ *   adopt — the destination is the source; its content comes into the repo file.
+ *
+ *   proposed — the PM chose this direction. A task was composed. NOTHING has been written anywhere,
+ *              and this is the only state PMOS itself can produce.
+ *   applied  — a session holding the PM's MCP performed the write and reported back. Carries the
+ *              profile that did it and the moment it did.
+ *   failed   — the attempt was made and did not succeed. Carries the reason.
+ *
+ * There is deliberately no `in sync`. The prototype's status line read `pushed · repo → jira · in
+ * sync 12:41`, where `12:41` was a literal in a seed module and `in sync` was a claim about two
+ * documents PMOS had never compared. `applied` says the smaller true thing: a session wrote, and
+ * here is who and when.
+ */
+const SYNC_DIRECTIONS = ['push', 'adopt'];
+const SYNC_STATES = ['proposed', 'applied', 'failed'];
 
 /**
  * How a reference came to be in the store. This is the field that makes the store cleanable: the
@@ -384,6 +419,12 @@ function provenance(body, at) {
   if (state === 'unreachable' && !reason) {
     return { error: 'an unreachable reference must carry the reason the lookup failed' };
   }
+  // Withdrawing a reference is the PM's act and nobody else's. A session that could retract could
+  // silently un-say something the PM said, which is the mirror image of the rule above — there, a
+  // caller may not claim to have read what it did not read; here, it may not claim to be the person.
+  if (state === 'retracted' && origin !== 'typed') {
+    return { error: 'a retraction is the PM withdrawing their own reference — send origin: typed' };
+  }
   return {
     origin,
     state,
@@ -472,7 +513,7 @@ function initiativeLinkRow(body, { at } = {}) {
  * the other. Rows are ordered by their recorded time with file order as the tiebreak, because two
  * rows can share a timestamp and file order is the only thing that then says which was written second.
  */
-function linkView(rows) {
+function linkView(rows, { includeRetracted = false } = {}) {
   const list = Array.isArray(rows) ? rows : [];
   const seen = new Map();
   list.forEach((row, i) => {
@@ -493,7 +534,154 @@ function linkView(rows) {
       // this initiative was opened to make identifiable. They are reported as what they are.
       origin: row.origin || null,
       state: row.state || (row.origin ? 'declared' : 'unattributed'),
-    }));
+    }))
+    // A pair whose LATEST row is a retraction is not a link any more, and the surface is a statement
+    // of now. The row it came from is still on disk and still readable — `includeRetracted` is how
+    // a caller that wants the history rather than the statement asks for it — but the panel that
+    // asks "what is linked" gets an answer that does not include what the PM withdrew.
+    .filter((row) => includeRetracted || row.state !== 'retracted');
+}
+
+/* ── the sync ledger ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Validate + normalise one sync row, and enforce the rule this whole store exists for.
+ *
+ * THE RULE, which is `provenance`'s rule carried onto a stronger verb: **`applied` cannot be
+ * asserted, only evidenced.** A row may claim a session wrote to the destination only if it can name
+ * the profile whose session did it. A caller that says "applied" and cannot say by whom is not
+ * describing a write.
+ *
+ * It matters more here than it did for `resolved`, not less. A failed search is obviously
+ * unfinished; a *publish* that a PM ran in another window looks finished from inside this process,
+ * and the difference between "the task was composed" and "the page was updated" is invisible from
+ * here. `proposed` is therefore the ONLY state PMOS can produce on its own, and it says exactly what
+ * happened: a direction was chosen and a task was written down.
+ */
+function syncRow(body, { at } = {}) {
+  const artifact_path = String((body && body.artifact_path) || '').trim();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const target = String((body && body.target) || '').trim();
+  const direction = String((body && body.direction) || '').trim().toLowerCase();
+  if (!artifact_path) return { ok: false, error: 'artifact_path is required' };
+  if (artifact_path.includes('..')) return { ok: false, error: 'artifact_path must be a repo-relative path' };
+  if (!LINK_KINDS.includes(kind)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  if (!target) return { ok: false, error: 'target is required — a sync needs the destination it was linked to' };
+  if (!SYNC_DIRECTIONS.includes(direction)) {
+    return { ok: false, error: `direction must be one of: ${SYNC_DIRECTIONS.join(', ')}` };
+  }
+  const state = String((body && body.state) || 'proposed').trim().toLowerCase();
+  if (!SYNC_STATES.includes(state)) return { ok: false, error: `state must be one of: ${SYNC_STATES.join(', ')}` };
+  const profile = body && body.profile ? String(body.profile).slice(0, 120) : null;
+  const reason = body && body.reason ? String(body.reason).slice(0, 300) : null;
+  const detail = body && body.detail ? String(body.detail).slice(0, 300) : null;
+  if (state === 'applied' && !profile) {
+    return { ok: false, error: 'an applied sync must name the profile whose session performed it — PMOS wrote nothing itself. Send profile with the session that did.' };
+  }
+  if (state === 'failed' && !reason) {
+    return { ok: false, error: 'a failed sync must carry the reason it failed' };
+  }
+  const initiative_id = body && body.initiative_id ? String(body.initiative_id) : null;
+  if (initiative_id && !validId(initiative_id)) return { ok: false, error: 'that initiative id is not a record name' };
+  return {
+    ok: true,
+    row: {
+      at: at || new Date().toISOString(),
+      initiative_id,
+      artifact_path,
+      kind,
+      target: target.slice(0, 300),
+      direction,
+      state,
+      profile,
+      reason,
+      // What the session reported about what it wrote — a page version, a commit, a summary of the
+      // change. Free text, and only ever the session's own words: nothing here composes one.
+      detail,
+      // Only a row that actually wrote something carries a write time, for the same reason only a
+      // row that read something carries a read time. Absent means nobody has written, which is a
+      // fact the surface renders rather than a gap it fills in with a clock.
+      applied_at: state === 'applied' ? (at || new Date().toISOString()) : null,
+    },
+  };
+}
+
+/**
+ * One row per (artifact, destination kind): the latest sync, which is what the status line says.
+ * Same read-time collapse as `linkView` and for the same reason — the store is the history, the
+ * surface is the statement of now.
+ */
+function syncView(rows) {
+  const list = Array.isArray(rows) ? rows : [];
+  const seen = new Map();
+  list.forEach((row, i) => {
+    if (!row || typeof row !== 'object') return;
+    const key = String(row.artifact_path || '') + '|' + String(row.kind || '');
+    const prev = seen.get(key);
+    if (!prev) { seen.set(key, { row, i }); return; }
+    const a = String(prev.row.at || ''), b = String(row.at || '');
+    if (b > a || (b === a && i > prev.i)) seen.set(key, { row, i });
+  });
+  return [...seen.values()].sort((x, y) => x.i - y.i).map(({ row }) => ({ ...row }));
+}
+
+/**
+ * The task a session performs to carry out a sync. Composed here, on the server, for the same
+ * reason `lookupTask` is: it is the thing the design turns on, and a string built in a click handler
+ * is a string no test ever sees.
+ *
+ * Note what changed from `lookupTask`, because it is the whole risk of this initiative. That task
+ * said *search, and do not create, publish or modify anything*. This one asks a session to WRITE.
+ * So it names its target and names what it will overwrite, in both directions, and forbids touching
+ * anything else — the cost of a vague target here is an overwritten Confluence page or an
+ * overwritten repo file, not a wrong pixel. It also asks the session to record the outcome through
+ * the same validated endpoint, where a claim of success will be refused unless it names the profile
+ * that made it.
+ */
+function syncTask({ direction, kind, artifact_path, target, profile } = {}) {
+  const d = String(direction || '').toLowerCase();
+  const k = String(kind || '').toLowerCase();
+  if (!SYNC_DIRECTIONS.includes(d)) return { ok: false, error: `direction must be one of: ${SYNC_DIRECTIONS.join(', ')}` };
+  if (!LINK_KINDS.includes(k)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  const file = String(artifact_path || '').slice(0, 300);
+  const dest = String(target || '').slice(0, 300);
+  if (!file) return { ok: false, error: 'artifact_path is required' };
+  if (!dest) return { ok: false, error: 'target is required' };
+  const what = k === 'jira' ? 'Jira issue' : k === 'confluence' ? 'Confluence page' : 'Google Doc';
+  const lines = d === 'push'
+    ? [
+      `Publish the repository file ${file} to the ${what} at ${dest}.`,
+      '',
+      `Use your ${k} MCP tools. THE DESTINATION YOU WILL OVERWRITE IS ${dest} — write to that record`,
+      'and to nothing else. Do not create a new page, do not touch a parent or a child, and do not',
+      'edit any other record you happen to find while looking.',
+      'Convert the markdown to the destination\'s own format; keep the repository file unchanged.',
+      'Report the version or revision you wrote and the time you wrote it.',
+    ]
+    : [
+      `Bring the ${what} at ${dest} into the repository file ${file}.`,
+      '',
+      `Use your ${k} MCP tools to READ ${dest}. THE FILE YOU WILL OVERWRITE IS ${file} — write to`,
+      'that path and to nothing else, and PRESERVE ITS EXISTING YAML FRONTMATTER BLOCK VERBATIM:',
+      'the repository\'s gates read those keys, and a document that arrives without them fails CI.',
+      'Convert the destination\'s content to markdown, and report what changed in the file.',
+    ];
+  return {
+    ok: true,
+    direction: d,
+    profile: profile || null,
+    text: [
+      ...lines,
+      '',
+      'Then record the outcome: POST /api/initiative/sync with state applied and the profile you ran',
+      `under (${profile || 'the profile holding this MCP'}), or state failed with the reason verbatim.`,
+      'A success that cannot name the profile that performed it will be refused, and refusal is',
+      'correct — PMOS wrote nothing itself and must not report that it did.',
+      'If you did not complete the write, say so plainly. An unreported failure reads here as a',
+      'sync that never happened, which is the honest outcome; a reported success that did not',
+      'happen is the defect this whole surface exists to refuse.',
+    ].join('\n'),
+  };
 }
 
 /**
@@ -537,7 +725,7 @@ function lookupTask({ kind, subject, hint, profile } = {}) {
  * artifacts are still listed, because the library can see them and claiming otherwise would hide
  * real files), `{ok:true,…}` otherwise.
  */
-function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, homeDir }) {
+function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, artifactSync, homeDir }) {
   if (!rec.ok) return { ok: false, id, error: rec.error };
   const artifacts = artifactsFor(index, id);
   const sess = sessionsFor({ sessions, workspaces, id });
@@ -565,16 +753,23 @@ function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor,
       artifacts: mine(artifactLinks, (r) => r && (r.initiative_id === id
         || artifacts.some((a) => a.path === r.artifact_path))),
       links: mine(initiativeLinks, (r) => r && r.initiative_id === id),
+      // Scoped the same way the links are, and collapsed the same way: this initiative's rows only,
+      // latest per (artifact, destination). A sync row for another initiative's copy of the same
+      // path is not this initiative's status line.
+      sync: syncView((artifactSync && artifactSync.ok ? artifactSync.rows : []).filter((r) => r
+        && (r.initiative_id === id || artifacts.some((a) => a.path === r.artifact_path)))),
       artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
       links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
+      sync_error: artifactSync && artifactSync.ok ? null : (artifactSync && artifactSync.error) || null,
     },
     connectors: connectors(homeDir),
   };
 }
 
 module.exports = {
-  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND,
+  ARTIFACT_LINKS, INITIATIVE_LINKS, ARTIFACT_SYNC,
+  LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND, SYNC_DIRECTIONS, SYNC_STATES,
   validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
   storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
-  linkView, lookupTask,
+  linkView, lookupTask, syncRow, syncView, syncTask,
 };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.24.0",
+      "version": "0.25.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

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

package/workspace/public/pm/data.js

@@ -38,11 +38,17 @@
  *
  * ── The one thing this file refuses to do ───────────────────────────────────────────────────
  * Linking an artifact records a DECLARATION (`{artifact_path, kind, target}` appended to
- * `artifact-links.jsonl`). It makes no outbound request, because PMOS holds no credential. The
- * sync panel therefore reports an unconfigured connector rather than a difference summary it never
- * read — `state.connectors` is published empty, which is what makes panel 3's two approval buttons
- * inert. A "2 sections differ" line over a destination nobody contacted is the watermelon this
- * repo has a word for.
+ * `artifact-links.jsonl`) and choosing a sync direction records another (`artifact-sync.jsonl`).
+ * Neither makes an outbound request, because PMOS holds no credential: the request is made by an
+ * agent session holding the PM's own MCP, and what comes back here is a report (D53).
+ *
+ * `state.connectors` used to be published as a literal `[]` on every load. That was written when it
+ * was true of every machine, and it stayed after the server learned to DERIVE the answer from the
+ * PM's agent profiles — so a careful derivation shipped into a client that had already decided. The
+ * panel branches on it (`hasConnector`, `resolverFor`), so the visible cost was a control that never
+ * rendered and a machine with a Jira MCP that reported having none. It is now published from the
+ * payload, and the constant is gone rather than corrected: a constant cannot be wrong, which is
+ * exactly why it could not be trusted.
  */
 
 import { state, setState, subscribe, FIXTURE } from './state.js';
@@ -299,20 +305,36 @@ function linksFor(payload) {
     out.push({ kind: l.kind, label: l.declared, path: l.href || l.declared, st: l.state_text || l.state });
   }
   for (const r of (payload.declarations && payload.declarations.links) || []) {
-    out.push({ kind: r.kind, label: r.label, path: r.target, st: 'declared · not connected' });
+    // The row's OWN provenance, carried rather than replaced. `declared · not connected` was a
+    // literal written before the store had a state vocabulary, and it outlived it: a reference a
+    // session had genuinely resolved rendered the same seven words as one the PM had typed a second
+    // earlier. The panel derives its state text from these fields (`linkStateText`), so carrying
+    // them is the whole fix — there is no second opinion to keep in step.
+    out.push({
+      kind: r.kind, label: r.label, path: r.target,
+      state: r.state, origin: r.origin, profile: r.profile || null,
+      reason: r.reason || null, resolved_at: r.resolved_at || null,
+    });
   }
   return out;
 }
 
-/** Artifacts, with any declared external destination attached. */
+/** Artifacts, with any declared external destination and the latest sync for it attached. */
 function artsFor(payload) {
   const dest = new Map();
   for (const r of (payload.declarations && payload.declarations.artifacts) || []) {
-    dest.set(r.artifact_path, { kind: r.kind, target: r.target });   // a later row supersedes an earlier
+    // The server has already collapsed the store to one row per pair and dropped what the PM
+    // retracted, so what arrives here is the statement of now.
+    dest.set(r.artifact_path, { kind: r.kind, target: r.target, state: r.state, origin: r.origin });
+  }
+  const sync = new Map();
+  for (const r of (payload.declarations && payload.declarations.sync) || []) {
+    sync.set(r.artifact_path + '|' + r.kind, r);
   }
   return (payload.artifacts || []).map((a) => {
     const d = dest.get(a.path);
-    return d ? { role: a.role, path: a.path, dest: d } : { role: a.role, path: a.path };
+    if (!d) return { role: a.role, path: a.path };
+    return { role: a.role, path: a.path, dest: d, sync: sync.get(a.path + '|' + d.kind) || null };
   });
 }
 
@@ -662,7 +684,14 @@ async function hydrate(slug) {
     // and its footer ("read failed · as of …") is entitled to say when it was attempted.
     const asOf = readStamp();
     hydrated[slug] = { ...recordFrom(payload), asOf };
-    setState((s) => ({ records: { ...s.records, [slug]: hydrated[slug] } }));
+    setState((s) => ({
+      records: { ...s.records, [slug]: hydrated[slug] },
+      // The server's `{configured:[{kind, profile, server, declared}], declaredBy, note}`, straight
+      // through. Published on every hydration rather than once at boot, because a profile added
+      // while the workspace is open should reach the panel on the next selection rather than on the
+      // next restart — and because the payload is the only place this fact is ever produced.
+      connectors: payload && payload.connectors ? payload.connectors : s.connectors,
+    }));
     return payload;
   } finally { inFlight.delete(slug); }
 }
@@ -780,7 +809,9 @@ export async function loadRepos() {
   const sel = state.sel || (p ? firstSlugOf(p.name) : null);
   setState({
     wsId: p ? p.ws : null,
-    connectors: [],          // no connector is configured — panel 3's approvals stay inert
+    // NOT initialised to a value here. What is resolvable is the server's derivation from the PM's
+    // agent profiles, it arrives with the first `/api/initiative` payload, and seeding a `[]` in the
+    // meantime is not a placeholder — it is an answer, and the panel would render it as one.
     product: state.product && products.has(state.product) ? state.product : first,
     sel,
   });
@@ -992,7 +1023,7 @@ export async function saveDoc({ ws, path, base, text }) {
  * Appends ONE declaration to `artifact-links.jsonl`. It contacts nothing: PMOS holds no credential,
  * so this records what the PM says the mapping is and says nothing about the destination.
  */
-export async function recordArtifactLink({ artifact_path, slug, kind, target }) {
+export async function recordArtifactLink({ artifact_path, slug, kind, target, origin, state: st }) {
   if (FIXTURE) return { ok: true };
   const p = products.get(currentProductName());
   const out = await postJson('/api/initiative/link', {
@@ -1001,11 +1032,37 @@ export async function recordArtifactLink({ artifact_path, slug, kind, target })
     // The surface labels a Google destination `google doc`; the store's vocabulary is `google`.
     kind: String(kind || '').startsWith('google') ? 'google' : kind,
     target,
+    // Passed through rather than defaulted here. The server owns the rules about which origin may
+    // claim which state — including that a retraction is the PM's alone — and a client that filled
+    // these in itself would be a second opinion about provenance, which is the one thing this store
+    // must have exactly one of.
+    origin, state: st,
   });
   if (out && out.ok === false) console.warn('[pm] the artifact link was NOT recorded: ' + out.error);
   return out;
 }
 
+/**
+ * panel-detail.js — `recordSync({artifact_path, slug, kind, target, direction, profile})`.
+ *
+ * Records the direction the PM chose and returns the TASK a session will run to carry it out. It
+ * syncs nothing: the row lands as `proposed`, which is the only state PMOS can produce on its own,
+ * and it stays that way until a session that actually performed the write reports back and names
+ * itself. Nothing here contacts Confluence, Jira or Google, and nothing here can.
+ */
+export async function recordSync({ artifact_path, slug, kind, target, direction, profile }) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode records no sync' };
+  const p = products.get(currentProductName());
+  const out = await postJson('/api/initiative/sync', {
+    ws: state.wsId || (p ? p.ws : ''),
+    initiative_id: slug, artifact_path,
+    kind: String(kind || '').startsWith('google') ? 'google' : kind,
+    target, direction, profile: profile || null,
+  });
+  if (out && out.ok === false) console.warn('[pm] the sync direction was NOT recorded: ' + out.error);
+  return out;
+}
+
 /**
  * panel-detail.js — `lookupTask({kind, subject, hint, profile})`.
  *
@@ -1018,13 +1075,13 @@ export async function lookupTask({ kind, subject, hint, profile }) {
   return postJson('/api/initiative/lookup-task', { kind, subject, hint, profile });
 }
 
-/** panel-detail.js — `recordInitiativeLink({slug, kind, label, path, st})` → `initiative-links.jsonl`. */
-export async function recordInitiativeLink({ slug, kind, label, path }) {
+/** panel-detail.js — `recordInitiativeLink({slug, kind, label, path, origin, state})` → `initiative-links.jsonl`. */
+export async function recordInitiativeLink({ slug, kind, label, path, origin, state: st }) {
   if (FIXTURE) return { ok: true };
   const p = products.get(currentProductName());
   const out = await postJson('/api/initiative/link', {
     store: 'initiative', ws: state.wsId || (p ? p.ws : ''),
-    initiative_id: slug, kind, label, target: path,
+    initiative_id: slug, kind, label, target: path, origin, state: st,
   });
   if (out && out.ok === false) console.warn('[pm] the reference link was NOT recorded: ' + out.error);
   return out;

package/workspace/public/pm/panel-detail.js

@@ -35,11 +35,18 @@
  * rendering in the real app is "the beautiful shell" the PRD names as a failure mode.
  *
  * ── The one place the design's fiction is refused ────────────────────────────────────────────
- * The artifact sync panel renders exactly as designed — the repo-is-source statement, the
- * difference summary, the two approvals. In FIXTURE mode the summary is the prototype's copy
- * verbatim. In real mode with no connector configured it says so, and the two approval buttons are
- * inert, because a panel that reported "2 sections differ" without having read anything would be
- * precisely the watermelon this repo has a word for (PRD, "External sync").
+ * The artifact sync panel keeps the design's SHAPE — the statement, then the two approvals — and
+ * replaces its claims. In FIXTURE mode the prototype's copy renders verbatim, because the parity
+ * comparator measures this surface against the design file and a re-worded label is a defect there.
+ * In real mode the panel says only what a row in the store says: nothing chosen yet, a direction
+ * proposed and unreported, or a named session's write at a named time. The design's
+ * `2 sections differ` and `in sync 12:41` are unreachable from the real path — a difference summary
+ * over a destination nobody contacted is precisely the watermelon this repo has a word for.
+ *
+ * The two approvals ACT. They record the direction the PM chose and show the task a session will
+ * run; they do not sync, because PMOS holds no credential and makes no outbound request (D53). The
+ * property that has to survive every future change to this file: there is no path from a click to a
+ * rendered claim about a destination without a profile in between.
  */
 
 import { el, setChildren } from './dom.js';
@@ -162,21 +169,27 @@ function hasConnector(kind) {
 const NO_CONNECTOR = 'no connector configured — nothing was read, and nothing will be written.';
 
 /**
- * Why the two sync approvals are inert in real mode even when a destination IS resolvable.
+ * What the two sync approvals now do, and why they stopped being inert.
+ *
+ * They used to be dead in every real session — `const inert = FIXTURE ? !live : true` — because
+ * publishing and read-back were out of scope by name and an inert control that states its reason
+ * beats a control that lies. That was right on the day it shipped and it stopped being right when
+ * the PM asked for the capability, because the reason it gave was *waiting on a decision the PM had
+ * not made*, and they made it.
  *
- * They are publishing and read-back, and both are out of scope by name (PRD non-goals 1–2).
- * Publishing puts PMOS content in two places and needs a fork/drift ruling the PM has not made;
- * read-back has no surviving architecture at all, because D53's inbound half was a hosted-Supabase
- * webhook and D64 deprecated that path. The buttons' old results — `pushed · repo → jira · in sync
- * 12:41` — were a hardcoded clock time presented as a sync confirmation, which is the same defect
- * as the fabricated identifier one level up.
+ * What a click does now is the whole design in one sentence: it records the DIRECTION the PM chose
+ * and shows the TASK a session will run to carry it out. It does not sync. PMOS holds no credential
+ * and makes no outbound request (D53) — the session holds the credential, performs the write, and
+ * reports back through a store that refuses any claim of success that cannot name the profile that
+ * made it.
  *
- * Deleting the buttons was the other option and is worse: the PM would be left wondering whether
- * PMOS forgot how to sync. An inert control that states the reason is a surface telling the truth
- * about its own limits.
+ * So the surface can now say three different true things where it previously said one: nothing has
+ * been chosen; a direction was chosen and nobody has reported; a named session wrote at a named
+ * time. The word it still cannot say is `in sync`, because that is a claim about two documents PMOS
+ * has never compared.
  */
-const SYNC_OUT_OF_SCOPE = 'publishing and read-back are not built. PMOS records which record this '
-  + 'corresponds to; it does not write to that record, and it has read nothing from it.';
+const SYNC_NOT_A_SYNC = 'PMOS does not perform this itself — it records which way you chose and '
+  + 'composes the task. The session you run it in holds the credential; PMOS holds none.';
 
 /* ── the sticky detail header (lines 332–335) ───────────────────────────────────────────────
  * Built once and re-used, so panel 3's chrome keeps its identity across renders the way panel 2's
@@ -344,6 +357,22 @@ function linkStateStyle(st) {
   return { color: 'var(--muted-foreground)', label: 'declared' };
 }
 
+/* ── the small controls a recorded link needs to be the PM's ────────────────────────────────
+ * `edit` and `unlink`. Neither existed, and their absence made a paste error permanent: the store
+ * is append-only and supersedes on read, so CHANGING a link was always one row away — there was
+ * simply nothing in the UI that could write that row. Removing one had no representation at all.
+ *
+ * They are rendered only in real mode. Fixture mode is a transcription of the prototype, pinned
+ * line-for-line by the parity comparator, and the prototype has no such controls; adding them there
+ * would be a parity failure dressed as a feature.
+ */
+const MINI_BTN = 'font-family:var(--mono);font-size:10px;padding:3px 8px;min-height:24px;'
+  + 'background:transparent;border:1px solid var(--border);color:var(--muted-foreground)';
+
+function miniBtn(label, onClick, extra) {
+  return el('button', { onClick, style: MINI_BTN + (extra || ''), hover: 'border-color:var(--ring);color:var(--foreground)' }, label);
+}
+
 /**
  * The one sentence a link row is allowed to say about itself, built from what was actually observed.
  * Every branch names its evidence or admits it has none — there is deliberately no branch that
@@ -363,7 +392,13 @@ function linkStateText(lk) {
 function linksRow(slug) {
   const rec = records()[slug] || {};
   const manual = (state.initLinks || {})[slug] || [];
-  const links = [...(rec.links || []), ...manual];
+  // A reference the PM withdrew in this window is dropped here as well as on disk. The server
+  // already omits retracted pairs from what it publishes, so this only covers the moment between
+  // the click and the next hydration — without it the row would linger until a reload and the PM
+  // would reasonably conclude the control had failed.
+  const dropped = (state.linkGone || {})[slug] || [];
+  const gone = (lk) => dropped.some((d) => d.kind === lk.kind && d.target === (lk.target || lk.path));
+  const links = [...(rec.links || []), ...manual].filter((lk) => !gone(lk));
   const openSrc = (state.linkForm || {})[slug] || null;
 
   /**
@@ -378,31 +413,62 @@ function linksRow(slug) {
       (s) => ({
         initLinks: { ...s.initLinks, [slug]: [...((s.initLinks || {})[slug] || []), link] },
         linkForm: { ...s.linkForm, [slug]: null },
+        // A pair the PM re-declares is no longer withdrawn. Clearing this is what makes R-B3's
+        // "a later declaration brings it back" true on the screen as well as in the store.
+        linkGone: { ...s.linkGone, [slug]: ((s.linkGone || {})[slug] || []).filter((d) => !(d.kind === src && d.target === target)) },
       }),
       () => declare('recordInitiativeLink', { slug, ...link }),
     );
   };
 
-  const rows = links.map((lk) => el('button', {
-    onClick: () => openDoc(slug, lk.path, String(lk.kind).toUpperCase()),
-    style: 'display:flex;gap:8px;align-items:center;padding:5px 6px;margin:0 -6px;min-height:34px',
-    hover: 'background:var(--accent)',
-  },
-    el('span', { style: 'flex:none;width:76px;font-family:var(--mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--info)' }, iv(lk.kind)),
-    el('span', { style: 'font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap' }, iv(lk.label)),
-    // A row that CARRIES provenance states what was observed; a row that does not keeps whatever
-    // status copy it came with. The branch is on the row, not on the mode, which is the point: the
-    // prototype's seeded rows (`auto · session`) render unchanged so the parity comparator still
-    // sees a like-for-like surface, while every row this surface actually records — in either mode —
-    // is held to the three-word vocabulary. Branching on FIXTURE instead would have left a real row
-    // in a fixture-mode session rendering `undefined`.
-    (lk.state || lk.origin)
-      ? el('span', {
-        style: 'margin-left:auto;flex:none;font-family:var(--mono);font-size:10px;color:'
-          + linkStateStyle(lk.state || 'declared').color,
-      }, iv(linkStateText(lk)))
-      : el('span', { style: 'margin-left:auto;flex:none;font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' }, iv(lk.st)),
-  ));
+  /**
+   * Withdraw a reference. This appends a `retracted` row — it does not delete anything, because the
+   * store is a history of what the PM declared and a deleted row is a declaration that never
+   * happened. The server refuses a retraction that does not come from the PM.
+   */
+  const retract = (lk) => {
+    const target = lk.target || lk.path;
+    setState(
+      (s) => ({
+        linkGone: { ...s.linkGone, [slug]: [...((s.linkGone || {})[slug] || []), { kind: lk.kind, target }] },
+        initLinks: { ...s.initLinks, [slug]: ((s.initLinks || {})[slug] || []).filter((x) => !(x.kind === lk.kind && (x.target || x.path) === target)) },
+      }),
+      () => declare('recordInitiativeLink', {
+        slug, kind: lk.kind, label: lk.label, path: target, origin: 'typed', state: 'retracted',
+      }),
+    );
+  };
+
+  const rows = links.map((lk) => {
+    const body = el('button', {
+      onClick: () => openDoc(slug, lk.path, String(lk.kind).toUpperCase()),
+      // In fixture mode this button IS the row and carries the prototype's own negative margin. In
+      // real mode it sits inside a wrapper that carries it instead, and the button flexes to fill.
+      style: 'display:flex;gap:8px;align-items:center;padding:5px 6px;min-height:34px;'
+        + (FIXTURE ? 'margin:0 -6px' : 'flex:1;min-width:0'),
+      hover: 'background:var(--accent)',
+    },
+      el('span', { style: 'flex:none;width:76px;font-family:var(--mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:var(--info)' }, iv(lk.kind)),
+      el('span', { style: 'font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap' }, iv(lk.label)),
+      // A row that CARRIES provenance states what was observed; a row that does not keeps whatever
+      // status copy it came with. The branch is on the row, not on the mode, which is the point: the
+      // prototype's seeded rows (`auto · session`) render unchanged so the parity comparator still
+      // sees a like-for-like surface, while every row this surface actually records — in either mode —
+      // is held to the closed vocabulary. Branching on FIXTURE instead would have left a real row
+      // in a fixture-mode session rendering `undefined`.
+      (lk.state || lk.origin)
+        ? el('span', {
+          style: 'margin-left:auto;flex:none;font-family:var(--mono);font-size:10px;color:'
+            + linkStateStyle(lk.state || 'declared').color,
+        }, iv(linkStateText(lk)))
+        : el('span', { style: 'margin-left:auto;flex:none;font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' }, iv(lk.st)),
+    );
+    // The prototype's row is a single button and the comparator measures it as one. Only real mode
+    // grows the wrapper and the withdraw control.
+    if (FIXTURE) return body;
+    return el('div', { style: 'display:flex;gap:6px;align-items:center;margin:0 -6px;min-width:0' },
+      body, miniBtn('unlink', () => retract(lk)));
+  });
 
   // Which destinations a session could actually look up, and under which profile. Derived by the
   // server from the PM's agent profiles — never a constant, and never a claim that PMOS is connected.
@@ -484,16 +550,69 @@ function linksRow(slug) {
 /* ── 5b · ARTIFACTS (lines 399–437, derivation 1779–1795) ───────────────────────────────────
  * Repo files, each with its role and path; clicking one opens the document. An artifact may carry
  * an external DESTINATION — recorded as a declaration, never as an outbound call — and once linked
- * it grows the ⇄ pill, a `sync` button, and the inline sync panel behind it.
+ * it grows the ⇄ pill, a `sync` button, `edit`/`unlink`, and the inline sync panel behind it.
+ *
+ * The sync panel is where this surface is at its most careful, and the care moved rather than
+ * relaxed. It used to be careful by refusing to act; it is now careful about WHAT A CLICK MEANS. A
+ * direction is a decision the PM makes and PMOS records; the write is performed by a session
+ * holding the PM's own MCP; and the status line reports the latest recorded row and nothing else.
+ * There is no path from a click to a claim about the destination without a profile in between —
+ * that sentence is the acceptance criterion for this whole region.
+ */
+
+/**
+ * The status line beside the pill, derived from the latest recorded sync row.
  *
- * The sync panel is where this surface is at its most careful. The repo is the source of truth,
- * stated first; then the difference summary; then the two approvals, whose chosen result persists
- * as the status line beside the pill. With no connector, the summary says nothing was read and
- * both approvals are inert.
+ * Everything it can say is something a row on disk says. It cannot say `in sync`, because that
+ * compares two documents PMOS has never read; it cannot invent a time, because the only times here
+ * are the ones the store stamped. `proposed` says the quiet true thing that the old panel had no
+ * way to express: you chose a direction, and nobody has reported doing it.
  */
+function syncStatus(sy) {
+  if (!sy) return null;
+  const hm = (t) => String(t || '').slice(11, 16);
+  const arrow = sy.direction === 'push' ? 'repo → ' + sy.kind : sy.kind + ' → repo';
+  if (sy.state === 'applied') {
+    return {
+      color: 'var(--success)',
+      text: arrow + ' · applied by ' + (sy.profile || 'a session') + (hm(sy.applied_at) ? ' · ' + hm(sy.applied_at) : ''),
+    };
+  }
+  if (sy.state === 'failed') {
+    return { color: 'var(--warning)', text: arrow + ' · failed · ' + (sy.reason || 'no reason recorded') };
+  }
+  return {
+    color: 'var(--muted-foreground)',
+    text: arrow + ' · proposed' + (hm(sy.at) ? ' ' + hm(sy.at) : '') + ' · no session has reported',
+  };
+}
+
+/** What the open sync panel says about where things stand. One sentence per recorded state. */
+function syncSummary(sy, dest) {
+  const hm = (t) => String(t || '').slice(11, 16);
+  if (!sy) {
+    return 'no direction has been chosen for this document yet. nothing has been written either way,'
+      + ' and PMOS has read nothing from ' + dest.kind + '.';
+  }
+  const way = sy.direction === 'push' ? 'push to ' + sy.kind : 'adoption from ' + sy.kind;
+  if (sy.state === 'applied') {
+    return sy.profile + ' reported applying this ' + way + (hm(sy.applied_at) ? ' at ' + hm(sy.applied_at) : '')
+      + '.' + (sy.detail ? ' it reported: ' + sy.detail : '');
+  }
+  if (sy.state === 'failed') {
+    return 'the last attempt at this ' + way + ' failed — ' + (sy.reason || 'no reason was recorded')
+      + '. nothing was written.';
+  }
+  return 'a ' + way + ' was proposed' + (hm(sy.at) ? ' at ' + hm(sy.at) : '')
+    + '. the task below is what performs it, and no session has reported back.';
+}
+
 function artifactRow(slug, a) {
   const key = FX.artKey(slug, a.path);
-  const dest = (state.artLinks || {})[key] || a.dest || null;
+  // `hasOwnProperty`, not `||`. An unlinked artifact records `null` under its key, and a falsy check
+  // would fall straight through to the server's `a.dest` and re-draw the link the PM just withdrew.
+  const over = state.artLinks || {};
+  const dest = Object.prototype.hasOwnProperty.call(over, key) ? over[key] : (a.dest || null);
   const syncState = (state.artSyncState || {})[key] || null;
   const syncOpen = !!(state.artSyncOpen || {})[key];
 
@@ -506,28 +625,76 @@ function artifactRow(slug, a) {
     el('span', { style: 'font-family:var(--mono);font-size:10px;color:var(--muted-foreground);overflow:hidden;text-overflow:ellipsis;white-space:nowrap' }, iv(a.path)),
   );
 
+  const openHere = (state.artLinkForm || {})[key] || null;
+  const inputId = 'artref-' + key.replace(/[^A-Za-z0-9]/g, '-');
+  const conn = (state.connectors && state.connectors.configured) || [];
+
+  /**
+   * Record a destination for this artifact. Used by BOTH the first link and an edit of one already
+   * recorded — they are the same act as far as the store is concerned, because it is append-only and
+   * supersedes on read. That is why editing needed no new endpoint and no mutation: the second row
+   * simply wins, and the first stays as the history of what the PM once believed.
+   */
+  const submit = (kind) => {
+    const node = document.getElementById(inputId);
+    const target = String((node && node.value) || '').trim();
+    if (!target) return;
+    const d = { kind, target, origin: 'typed', state: 'declared' };
+    setState((s) => ({
+      artLinks: { ...s.artLinks, [key]: d },
+      artLinkForm: { ...s.artLinkForm, [key]: null },
+      // A re-linked pair discards whatever sync was recorded against the OLD destination in this
+      // window. Carrying it over would attach a status line to a record it was never about.
+      artSyncTask: { ...s.artSyncTask, [key]: null },
+    }));
+    declare('recordArtifactLink', { artifact_path: a.path, slug, kind, target, origin: 'typed', state: 'declared' });
+  };
+
+  /** Withdraw this artifact's destination — an appended `retracted` row, never a deletion. */
+  const retract = () => {
+    if (!dest) return;
+    setState((s) => ({
+      artLinks: { ...s.artLinks, [key]: null },
+      artSyncOpen: { ...s.artSyncOpen, [key]: false },
+      artSyncTask: { ...s.artSyncTask, [key]: null },
+    }));
+    declare('recordArtifactLink', {
+      artifact_path: a.path, slug, kind: dest.kind, target: dest.target, origin: 'typed', state: 'retracted',
+    });
+  };
+
+  /** The paste-a-reference form. `initial` pre-fills it when the PM is editing rather than adding. */
+  const destForm = (kind, initial) => el('div', { style: 'margin-top:6px;padding:8px 10px;border:1px solid var(--border);background:var(--background)' },
+    el('div', { style: 'font-size:11.5px;color:var(--muted-foreground);line-height:1.5;margin-bottom:6px' },
+      iv(conn.some((c) => c.kind === kind)
+        ? 'paste the ' + kind + ' reference this file corresponds to. a session on '
+          + (conn.find((c) => c.kind === kind) || {}).profile + ' can find it for you — PMOS reads nothing.'
+        : 'paste the ' + kind + ' reference this file corresponds to. nothing here can look it up,'
+          + ' so what you type is recorded as your own declaration.')),
+    el('input', {
+      id: inputId,
+      value: initial || '',
+      placeholder: kind === 'jira' ? 'ATL-482 or its URL' : 'the page or document URL',
+      style: 'width:100%;font-family:var(--mono);font-size:11px;padding:5px 7px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
+    }),
+    el('div', { style: 'display:flex;gap:6px;margin-top:7px;flex-wrap:wrap' },
+      el('button', {
+        onClick: () => submit(kind),
+        style: 'font-family:var(--mono);font-size:10px;padding:4px 9px;min-height:26px;background:var(--brand);color:oklch(0.987 0.002 197.1);font-weight:500',
+      }, 'record'),
+      el('button', {
+        onClick: () => setState((s) => ({ artLinkForm: { ...s.artLinkForm, [key]: null } })),
+        style: 'font-family:var(--mono);font-size:10px;padding:4px 9px;min-height:26px;background:transparent;border:1px solid var(--border);color:var(--muted-foreground)',
+      }, 'cancel'),
+    ),
+  );
+
   if (!dest) {
     // Unlinked: the three destinations it could be linked to.
     // In FIXTURE mode the prototype's own destination copy is drawn, so the parity comparator still
     // sees a like-for-like surface. In REAL mode a click opens a FORM: `linkArtDest` built the
     // destination out of the artifact's own FILENAME — `PM / <basename>`, `ATL epic · <basename>` —
     // which is a name for a page nobody created, recorded as though the PM had chosen it.
-    const openHere = (state.artLinkForm || {})[key] || null;
-    const inputId = 'artref-' + key.replace(/[^A-Za-z0-9]/g, '-');
-    const conn = (state.connectors && state.connectors.configured) || [];
-
-    const submit = (kind) => {
-      const node = document.getElementById(inputId);
-      const target = String((node && node.value) || '').trim();
-      if (!target) return;
-      const d = { kind, target, origin: 'typed', state: 'declared' };
-      setState((s) => ({
-        artLinks: { ...s.artLinks, [key]: d },
-        artLinkForm: { ...s.artLinkForm, [key]: null },
-      }));
-      declare('recordArtifactLink', { artifact_path: a.path, slug, kind, target, origin: 'typed', state: 'declared' });
-    };
-
     const linkRow = el('div', { style: 'display:flex;gap:6px;align-items:center;flex-wrap:wrap;padding:3px 0 0' },
       el('span', { style: 'font-family:var(--mono);font-size:9.5px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted-foreground)' }, 'link'),
       FX.ART_LINK_SRCS.map((ls) => el('button', {
@@ -546,34 +713,13 @@ function artifactRow(slug, a) {
       }, '＋ ', iv(ls.l))),
     );
 
-    const form = openHere ? el('div', { style: 'margin-top:6px;padding:8px 10px;border:1px solid var(--border);background:var(--background)' },
-      el('div', { style: 'font-size:11.5px;color:var(--muted-foreground);line-height:1.5;margin-bottom:6px' },
-        iv(conn.some((c) => c.kind === openHere)
-          ? 'paste the ' + openHere + ' reference this file corresponds to. a session on '
-            + (conn.find((c) => c.kind === openHere) || {}).profile + ' can find it for you — PMOS reads nothing.'
-          : 'paste the ' + openHere + ' reference this file corresponds to. nothing here can look it up,'
-            + ' so what you type is recorded as your own declaration.')),
-      el('input', {
-        id: inputId,
-        placeholder: openHere === 'jira' ? 'ATL-482 or its URL' : 'the page or document URL',
-        style: 'width:100%;font-family:var(--mono);font-size:11px;padding:5px 7px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
-      }),
-      el('div', { style: 'display:flex;gap:6px;margin-top:7px;flex-wrap:wrap' },
-        el('button', {
-          onClick: () => submit(openHere),
-          style: 'font-family:var(--mono);font-size:10px;padding:4px 9px;min-height:26px;background:var(--brand);color:oklch(0.987 0.002 197.1);font-weight:500',
-        }, 'record'),
-        el('button', {
-          onClick: () => setState((s) => ({ artLinkForm: { ...s.artLinkForm, [key]: null } })),
-          style: 'font-family:var(--mono);font-size:10px;padding:4px 9px;min-height:26px;background:transparent;border:1px solid var(--border);color:var(--muted-foreground)',
-        }, 'cancel'),
-      ),
-    ) : null;
-
-    return el('div', { style: 'min-width:0' }, head, linkRow, form);
+    return el('div', { style: 'min-width:0' }, head, linkRow, openHere ? destForm(openHere, '') : null);
   }
 
-  // Linked: the destination pill, the sync button, and the persisted result of the last approval.
+  // Linked: the destination pill, the sync button, the PM's own controls, and the status line —
+  // which in real mode is what the store recorded, and in fixture mode is the prototype's own.
+  const recorded = FIXTURE ? null : syncStatus(a.sync || null);
+  const shown = FIXTURE ? syncState : (recorded || syncState);
   const pillRow = el('div', { style: 'display:flex;gap:7px;align-items:center;flex-wrap:wrap;padding:3px 0 0 0' },
     el('span', { style: 'font-family:var(--mono);font-size:10px;padding:1px 6px;background:var(--brand-wash);color:var(--brand)' },
       '⇄ ', iv(dest.kind), ' · ', iv(dest.target)),
@@ -582,15 +728,22 @@ function artifactRow(slug, a) {
       style: 'font-family:var(--mono);font-size:10.5px;padding:3px 10px;min-height:26px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
       hover: 'border-color:var(--ring)',
     }, 'sync'),
-    syncState && el('span', { style: 'font-family:var(--mono);font-size:10px;color:' + syncState.color }, iv(syncState.text)),
+    // Real mode only: the prototype has no edit or unlink control and the comparator measures the
+    // fixture surface against it.
+    FIXTURE ? null : miniBtn('edit', () => setState((s) => ({
+      artLinkForm: { ...s.artLinkForm, [key]: (s.artLinkForm || {})[key] ? null : dest.kind },
+    }))),
+    FIXTURE ? null : miniBtn('unlink', retract),
+    shown && el('span', { style: 'font-family:var(--mono);font-size:10px;color:' + shown.color }, iv(shown.text)),
   );
 
   let panel = null;
-  if (syncOpen) {
+  if (syncOpen && FIXTURE) {
+    // The prototype's panel, transcribed. Its two approvals write the seed module's own result
+    // strings; nothing here reaches a store, and the parity comparator measures this surface against
+    // the design file character for character.
     const live = hasConnector(dest.kind);
-    // FIXTURE mode draws the prototype's two working approvals so the comparator sees a like-for-like
-    // surface. REAL mode never enables them: they are publishing and read-back, both out of scope.
-    const inert = FIXTURE ? !live : true;
+    const inert = !live;
     const decide = (make) => () => {
       if (inert) return;
       setState((s) => ({
@@ -601,7 +754,7 @@ function artifactRow(slug, a) {
     const off = inert ? ';opacity:.5;cursor:not-allowed' : '';
     panel = el('div', { style: 'margin-top:6px;padding:9px 11px;border:1px solid var(--border);background:var(--background)' },
       el('div', { style: 'font-size:12px;line-height:1.5;color:var(--muted-foreground)' },
-        iv(FIXTURE ? (live ? FX.artDiffText(dest) : NO_CONNECTOR) : SYNC_OUT_OF_SCOPE)),
+        iv(live ? FX.artDiffText(dest) : NO_CONNECTOR)),
       el('div', { style: 'display:flex;gap:6px;margin-top:8px;flex-wrap:wrap' },
         el('button', {
           onClick: decide(FX.artSyncPushed), disabled: inert,
@@ -614,9 +767,90 @@ function artifactRow(slug, a) {
         }, 'adopt ', iv(dest.kind), ' → repo'),
       ),
     );
+  } else if (syncOpen) {
+    panel = realSyncPanel(slug, a, key, dest);
   }
 
-  return el('div', { style: 'min-width:0' }, head, pillRow, panel);
+  return el('div', { style: 'min-width:0' }, head, pillRow, openHere ? destForm(openHere, dest.target) : null, panel);
+}
+
+/**
+ * The real sync panel: what is true now, who could perform the next step, the two directions, and —
+ * once a direction is chosen — the task that carries it out.
+ *
+ * The click handler is worth reading closely, because it is where this initiative could most easily
+ * have reproduced the defect it exists to remove. It records a `proposed` row and asks the server
+ * for the task text. It does NOT set a status line of its own, does not stamp a time, and has no
+ * success branch — because from in here there is no such thing as success to observe. The status
+ * line updates when the panel next reads the store, and it can only say what a row says.
+ */
+function realSyncPanel(slug, a, key, dest) {
+  const task = (state.artSyncTask || {})[key] || null;
+  const resolver = ((state.connectors && state.connectors.configured) || []).find((c) => c.kind === dest.kind) || null;
+
+  const choose = (direction) => () => {
+    const data = sibling('data', './data.js');
+    if (!data || typeof data.recordSync !== 'function') return;
+    setState((s) => ({ artSyncTask: { ...s.artSyncTask, [key]: { pending: true, direction } } }));
+    Promise.resolve(data.recordSync({
+      artifact_path: a.path, slug, kind: dest.kind, target: dest.target,
+      direction, profile: resolver ? resolver.profile : null,
+    }))
+      .then((out) => setState((s) => ({
+        artSyncTask: {
+          ...s.artSyncTask,
+          [key]: (!out || out.ok === false)
+            // A refusal is shown, never absorbed. The store returning 500 rather than a false green
+            // is the server's half of this rule; showing what it said is the client's.
+            ? { error: (out && out.error) || 'the direction could not be recorded', direction }
+            : { text: out.task, error: out.task_error || null, direction, profile: resolver ? resolver.profile : null },
+        },
+      })))
+      .catch((e) => setState((s) => ({
+        artSyncTask: { ...s.artSyncTask, [key]: { error: String((e && e.message) || e), direction } },
+      })));
+  };
+
+  const btn = (label, primary, onClick) => el('button', {
+    onClick,
+    style: 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:28px;'
+      + (primary
+        ? 'background:var(--brand);color:oklch(0.987 0.002 197.1);font-weight:500'
+        : 'background:var(--secondary);border:1px solid var(--border);color:var(--foreground)'),
+    hover: primary ? null : 'border-color:var(--ring)',
+  }, label);
+
+  return el('div', { style: 'margin-top:6px;padding:9px 11px;border:1px solid var(--border);background:var(--background)' },
+    el('div', { style: 'font-size:12px;line-height:1.5;color:var(--muted-foreground)' },
+      iv(syncSummary(a.sync || null, dest))),
+    el('div', { style: 'font-size:11.5px;line-height:1.5;color:var(--muted-foreground);margin-top:5px' },
+      iv(resolver
+        ? SYNC_NOT_A_SYNC + ' a session on ' + resolver.profile + ' holds your ' + dest.kind + ' MCP.'
+        : SYNC_NOT_A_SYNC + ' no agent profile declares a ' + dest.kind + ' MCP, so the task below is'
+          + ' yours to run wherever you hold that access.')),
+    el('div', { style: 'display:flex;gap:6px;margin-top:8px;flex-wrap:wrap' },
+      btn('repo is source → push', true, choose('push')),
+      el('button', {
+        onClick: choose('adopt'),
+        style: 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:28px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
+        hover: 'border-color:var(--ring)',
+      }, 'adopt ', iv(dest.kind), ' → repo'),
+    ),
+    task && (task.error
+      ? el('div', { style: 'margin-top:8px;font-size:11.5px;color:var(--warning);line-height:1.5' },
+        iv('the direction was not recorded — ' + task.error))
+      : task.pending
+        ? el('div', { style: 'margin-top:8px;font-size:11.5px;color:var(--muted-foreground)' }, iv('recording…'))
+        : el('div', { style: 'margin-top:8px' },
+          el('div', { style: 'font-size:11px;color:var(--muted-foreground);line-height:1.5;margin-bottom:5px' },
+            iv('recorded as proposed. run this in a session on ' + (task.profile || 'a profile holding that MCP')
+              + '. it records the outcome itself, and PMOS will refuse a success that does not name'
+              + ' the profile that performed it.')),
+          el('pre', {
+            style: 'font-family:var(--mono);font-size:10.5px;line-height:1.5;white-space:pre-wrap;'
+              + 'padding:8px 9px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground);margin:0',
+          }, iv(task.text)))),
+  );
 }
 
 function artifactsRow(slug, rec) {

package/workspace/public/pm/state.js

@@ -37,6 +37,12 @@ function initial() {
     detail: { kind: 'init' },
     tabs: [], active: null, splitId: null,
     initLinks: {}, artLinks: {}, artSyncOpen: {}, artSyncState: {},
+    /* The sync half of panel 3, all per-window and none of it persisted. `artSyncTask` holds the
+     * task text the server composed for a direction the PM just chose; `linkGone` holds the
+     * references withdrawn since the last hydration, so a retracted row leaves the screen at the
+     * click rather than at the next read. Neither is a source of truth — what a link IS and what
+     * was synced both come back from the store on the next `/api/initiative`. */
+    artSyncTask: {}, linkGone: {},
     extraSess: {}, termHist: {}, startN: 1, docEdits: {}, docModes: {},
     /* `＋ session` into a working tree that already has sessions in it opens a CHOOSER instead of
      * spawning (workspace-session-choice): `{slug, tree, branch, peers}` while it is open, null

package/workspace/server.js

@@ -702,11 +702,21 @@ function readTextDoc(root, rel) {
 // falling back to the filename convention when an artifact declares nothing.
 // Ordered LONGEST-DISCRIMINATOR-FIRST: `-copy-brief` must be tested before `-brief`, and
 // `-eval-rubric` before any `-rubric`, because the first match wins and slices the stem.
+//
+// The qualified-brief entries (`-comms-brief`, `-launch-brief`) are here for a reason worth stating,
+// because it is the same reason `-copy-brief` was: a stem ending `-comms-brief` ALSO ends `-brief`,
+// so without its own entry it matches the shorter one and the slice leaves a `-comms` tail on the
+// stem. That tail belongs to the qualifier, not to the initiative, and it is enough to put a comms
+// brief in a different group from the PRD it was written for — which is precisely what the PM
+// reported seeing (PRD, defect 3).
 const ROLE_SUFFIXES = [
   ['-eval-rubric', 'rubric'], ['-design-brief', 'design brief'], ['-design-reference', 'design'],
-  ['-copy-brief', 'copy brief'], ['-user-stories', 'user stories'], ['-copy', 'copy'],
+  ['-copy-brief', 'copy brief'], ['-comms-brief', 'comms brief'], ['-launch-brief', 'launch brief'],
+  ['-user-stories', 'user stories'], ['-user-story', 'user stories'], ['-stories', 'user stories'],
+  ['-one-pager', 'one-pager'], ['-copy', 'copy'],
   ['-dogfood', 'dogfood'], ['-reconcile', 'reconcile'], ['-findings', 'findings'],
   ['-scoping', 'scoping'], ['-intake', 'intake'], ['-brief', 'brief'], ['-prd', 'PRD'],
+  ['-spec', 'spec'],
 ];
 const ROLE_BY_DIR = {
   prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
@@ -864,12 +874,34 @@ function initiativeIndex(root) {
   for (const m of metas) if (!m.initiative) byStem.set(m.stem, (byStem.get(m.stem) || 0) + 1);
   const groups = new Map();
   const ungrouped = [];
+  // PREFIX ATTACHMENT, and the three constraints that keep it from becoming a similarity score.
+  //
+  // The join above is stem EQUALITY, and equality is the wrong shape for how PMs name files. An
+  // initiative `ooh-zbsg-ast1` carries `ooh-zbsg-ast1-design-prd.md`, `ooh-zbsg-ast1-user-stories.md`
+  // and `ooh-zbsg-ast1-comms-brief.md`; after the role suffix is sliced those are three DIFFERENT
+  // stems, so the initiative's own PRD was attributed to no initiative and never reached panel 3.
+  // Measured on this repository one initiative ago: 148 documents attributed to nothing, 31 of them
+  // beginning with a declared id.
+  //
+  //   1. Only EXPLICITLY DECLARED ids may capture (`declared`, not `groups`). A group that exists
+  //      only because two filenames happened to share a stem was never named by anyone, and giving
+  //      it the authority to claim documents would let a naming coincidence annex a neighbourhood.
+  //   2. LONGEST WINS, so `workspace-session-choice-prd.md` cannot be captured by `workspace-session`
+  //      when both are declared. Sorted once per call, not per document.
+  //   3. It runs LAST, after equality and after the convention join, so it can only move a document
+  //      that would otherwise be `ungrouped`. It cannot take a document away from a group that has a
+  //      better claim on it, which is what makes the total document count provably unchanged.
+  //
+  // The boundary being held here is the one `lib/related-docs.js` holds for the same reason: a
+  // concrete tie, never "feels related". `x-` is a tie the PM typed. Similarity is not.
+  const capturing = [...declared].sort((a, b) => b.length - a.length);
+  const prefixOwner = (stem) => capturing.find((id) => stem.length > id.length + 1 && stem.startsWith(id + '-')) || null;
   const keyFor = (m) => {
     if (m.initiative) return m.initiative;
     if (declared.has(m.stem)) return m.stem;
     // the convention join: `jira-sync-prd.md` + `jira-sync-eval-rubric.md` are one unit
     if ((byStem.get(m.stem) || 0) > 1) return m.stem;
-    return null;
+    return prefixOwner(m.stem);
   };
   for (const m of metas) {
     const k = keyFor(m);
@@ -3952,6 +3984,7 @@ async function handleRequest(req, res) {
         : null,
       artifactLinks: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_LINKS),
       initiativeLinks: fourPanel.readDeclarations(stateDir, fourPanel.INITIATIVE_LINKS),
+      artifactSync: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_SYNC),
       // Which destinations a session could look up, derived from the PM's agent profiles. The home
       // directory is passed IN rather than read inside four-panel.js for the same reason
       // readProfiles takes it as a parameter: a module that reads os.homedir() itself can only be
@@ -3986,6 +4019,36 @@ async function handleRequest(req, res) {
     // A write that failed returns 500 and says so — never a false green (the /api/gate rule).
     return json(res, { ...wrote, connectors: fourPanel.connectors(os.homedir()) }, wrote.ok ? 200 : 500);
   }
+  if (p === '/api/initiative/sync' && req.method === 'POST') {
+    // The PM chose a direction for a link they already recorded, or a session is reporting what it
+    // did about one. Both arrive here, and the difference between them is exactly the difference the
+    // store enforces: a direction the PM chose is `proposed` and claims nothing, while a session's
+    // report is `applied` and is REFUSED unless it names the profile that performed it.
+    //
+    // This route composes the task text and appends the row. It performs no sync — there is no
+    // branch here that contacts Confluence, Jira or Google, and there cannot be one: the workspace
+    // holds no credential (D53), and `no-network.test.js` asserts the absence structurally.
+    const w = getWs(url.searchParams.get('ws'));
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w2 = body.ws ? getWs(body.ws) : w;
+    const built = fourPanel.syncRow(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    const task = fourPanel.syncTask({
+      direction: built.row.direction, kind: built.row.kind,
+      artifact_path: built.row.artifact_path, target: built.row.target, profile: body.profile || null,
+    });
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, error: engine.error }, 500);
+    const stateDir = fourPanel.storeDir(engine.engine, w2 ? w2.root : SELF_ROOT);
+    const wrote = fourPanel.appendDeclaration(stateDir, fourPanel.ARTIFACT_SYNC, built.row);
+    // A write that failed returns 500 and says so — never a false green (the /api/gate rule). The
+    // task is returned either way: a PM whose store is unwritable can still run the work by hand,
+    // and withholding the text would turn a recording failure into a capability failure.
+    return json(res, { ...wrote, task: task.ok ? task.text : null, task_error: task.ok ? null : task.error },
+      wrote.ok ? 200 : 500);
+  }
   if (p === '/api/initiative/lookup-task' && req.method === 'POST') {
     // The task a SESSION runs to resolve a reference. This endpoint composes a string and returns
     // it. It contacts nothing — that is the entire point of the design: PMOS describes the lookup,