create-pmos 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → 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. `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@181425a
+kernel-source: pmos@ec75724
 assembled: 2026-07-31
 mode: vendor

package/workspace/lib/four-panel.js

@@ -26,13 +26,22 @@
  * this endpoint's `frontmatter` can agree with its own `ladder`.
  *
  * ── The declaration stores ───────────────────────────────────────────────────────────────────
- * `artifact-links.jsonl` and `initiative-links.jsonl` are APPEND-ONLY records of what the PM
- * declared, never of anything PMOS read. PMOS holds no credential and makes no outbound request
- * (PRD, "External sync"), so a link row is a statement of intent — "this artifact corresponds to
- * that page" — and the surface that renders it must say that nothing was read and nothing will be
- * written. `connectors()` below is the honest answer to "is a connector configured": always none.
- * It is a function rather than a constant so that the day a connector genuinely exists there is
- * exactly one place that has to start telling a different truth.
+ * `artifact-links.jsonl` and `initiative-links.jsonl` are APPEND-ONLY records of external
+ * references. PMOS holds no credential and makes no outbound request (PRD, "External sync") — that
+ * has not changed and must not. What a row may now say about itself has: every row carries a
+ * `state` from a closed three-word vocabulary (`declared` · `resolved` · `unreachable`) and the
+ * provenance behind it, so a reference the PM typed and a reference a session actually read are
+ * different facts on disk instead of the same row wearing the word `connected`.
+ *
+ * `resolved` is the only state that claims anything about the destination, and it cannot be
+ * asserted — only evidenced. See `provenance()`: a row claiming `resolved` without the profile that
+ * resolved it is REFUSED. That refusal is the mechanical form of this whole module's promise, and
+ * it is why the day a connector genuinely exists there is exactly one place that has to start
+ * telling a different truth — and no way for anything else to start telling it early.
+ *
+ * `connectors()` below answers "what could be looked up, and by whom" from the agent profiles on
+ * disk. It used to return a constant `[]`. A constant cannot be wrong, which is exactly why it
+ * could not be trusted: it said "none" on a machine whose profiles declared a Jira MCP.
  *
  * The files land beside the repo's other append-only records, resolved through the workflow
  * engine's own `layout(root)`: `pmos/state/` in a kit repo — exactly as the PRD names it — and
@@ -52,19 +61,110 @@ const INITIATIVE_LINKS = 'initiative-links.jsonl';
 /** The destinations the surface can declare. A kind outside this set is refused, not stored. */
 const LINK_KINDS = ['confluence', 'jira', 'google'];
 
+/**
+ * The closed vocabulary a link row may use about itself. Three states, and the word `connected` is
+ * deliberately not among them.
+ *
+ *   declared    — the PM named this reference. Nothing was checked. Carries no claim about the
+ *                 destination beyond the PM's own say-so.
+ *   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.
+ *
+ * `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'];
+
+/**
+ * How a reference came to be in the store. This is the field that makes the store cleanable: the
+ * rows written by the fabricating build carry neither, so they are distinguishable from real ones
+ * forever rather than only until someone forgets.
+ *
+ *   typed    — a human wrote the reference into the form. The only origin a `declared` row can have.
+ *   resolved — a session searched the destination and returned this record.
+ */
+const LINK_ORIGINS = ['typed', 'resolved'];
+
+/**
+ * Which MCP server name on a profile makes which destination resolvable. The names on the left are
+ * what a profile descriptor actually declares (`mcp: [jira, confluence, ...]`); the kinds on the
+ * right are this store's closed vocabulary. Anything a profile declares that is not in here simply
+ * does not make a destination resolvable — an unknown server name is not evidence of anything.
+ */
+const MCP_FOR_KIND = {
+  jira: ['jira', 'atlassian'],
+  confluence: ['confluence', 'atlassian'],
+  google: ['gworkspace', 'google-workspace', 'gdrive', 'google-drive'],
+};
+
 /** An initiative id is a FILENAME, never a path. Same guard the handoff surface uses. */
 const ID_RE = /^[A-Za-z0-9][\w.-]*$/;
 const validId = (id) => typeof id === 'string' && id.length <= 120 && ID_RE.test(id);
 
 /**
- * No connector is configured, on every code path, because PMOS holds no credential. Returned as a
- * list so the client can render "which destinations are live" without a second shape to learn; it
- * is empty, and the note says why.
+ * Which destinations can be RESOLVED right now, and by what.
+ *
+ * This used to return a constant `[]` with a note explaining that PMOS holds no credential. The
+ * note was true and the list was not an answer — it said "none" on a machine where the PM's own
+ * agent profile declares a Jira MCP, and it would have gone on saying "none" after a real
+ * connection existed. A constant cannot be wrong, which is exactly why it cannot be trusted.
+ *
+ * The honest answer is derived, and it is careful about WHOSE capability it is describing. PMOS
+ * still holds no credential and still makes no outbound request — that has not changed and must
+ * not. What has changed is that PMOS can now see which agent PROFILES declare an MCP server for a
+ * destination, and a session started on such a profile can perform a lookup with the PM's own auth
+ * (D53: the agent layer acts, PMOS records). So `configured` does not mean "PMOS is connected"; it
+ * means "a session on this profile could look this up for you", and every entry names the profile
+ * so the claim is attributable rather than ambient.
+ *
+ * `declared: true` on every entry is the load-bearing hedge. A profile DECLARES an MCP server in a
+ * file; PMOS has not reached it, cannot reach it, and will not pretend the declaration is a
+ * handshake. A profile that lists a Jira MCP whose token expired last week still reads as
+ * resolvable here, and the resulting failure surfaces where it actually happens — as an
+ * `unreachable` row carrying the reason, written by the session that tried.
  */
-function connectors() {
+function connectors(homeDir) {
+  const empty = (note) => ({ configured: [], declaredBy: [], note });
+  const home = typeof homeDir === 'string' && homeDir ? homeDir : null;
+  if (!home) {
+    return empty('no home directory to read agent profiles from — PMOS cannot say what is resolvable, so it says nothing.');
+  }
+
+  let read;
+  try { read = require('./profiles').readProfiles(home); }
+  catch { return empty('the profile reader is unavailable — PMOS cannot say what is resolvable, so it says nothing.'); }
+
+  // ABSENT and BROKEN are different facts here for the same reason they are in the profile reader:
+  // "you have declared no profiles" is calm and actionable, "PMOS could not look" is a failure the
+  // PM has to go fix, and collapsing them would hide the second behind the first.
+  if (!read.ok) {
+    return empty(`agent profiles could not be read — ${read.error || 'unknown error'}. Nothing is claimed about what is resolvable.`);
+  }
+  if (!read.profiles || !read.profiles.length) {
+    return empty('no agent profile declares an MCP server for these destinations — a reference you add here is one you typed, and PMOS will say so.');
+  }
+
+  const configured = [];
+  for (const kind of LINK_KINDS) {
+    const names = MCP_FOR_KIND[kind] || [];
+    for (const prof of read.profiles) {
+      const mcp = Array.isArray(prof.mcp) ? prof.mcp : [];
+      const hit = mcp.find((s) => names.includes(String(s).toLowerCase()));
+      if (!hit) continue;
+      configured.push({ kind, profile: prof.id, server: hit, declared: true });
+      break;                                  // one profile per kind is enough to offer the lookup
+    }
+  }
+
+  if (!configured.length) {
+    return empty('no agent profile declares an MCP server for these destinations — a reference you add here is one you typed, and PMOS will say so.');
+  }
   return {
-    configured: [],
-    note: 'no connector configured — nothing was read, and nothing will be written.',
+    configured,
+    declaredBy: [...new Set(configured.map((c) => c.profile))],
+    note: 'a session on the named profile can look these up with your own credentials. PMOS itself holds none and reads nothing.',
   };
 }
 
@@ -244,6 +344,58 @@ function appendDeclaration(stateDir, name, row) {
   }
 }
 
+/**
+ * The provenance half of every link row, and the one rule that makes the vocabulary mean something.
+ *
+ * THE RULE: `resolved` cannot be asserted, only evidenced. A row may claim `state: 'resolved'` only
+ * if it also carries the profile that resolved it and the moment it did. A caller that says
+ * "resolved" and cannot say by whom is not describing a lookup, and the store refuses it rather
+ * than recording an unsupported claim — which is exactly the failure this whole initiative exists
+ * to remove, arriving through the front door instead of through a fabricating helper.
+ *
+ * The consequence worth stating plainly: a reference the PM TYPED can never be stored as
+ * `resolved`, no matter what the client sends. `origin: 'typed'` forces `declared`. That is what
+ * makes the three states worth reading — a `resolved` row is a fact about the destination, and
+ * nothing else in the system can mint one.
+ */
+function provenance(body, at) {
+  const origin = String((body && body.origin) || 'typed').trim().toLowerCase();
+  if (!LINK_ORIGINS.includes(origin)) {
+    return { error: `origin must be one of: ${LINK_ORIGINS.join(', ')}` };
+  }
+  let state = String((body && body.state) || (origin === 'resolved' ? 'resolved' : 'declared')).trim().toLowerCase();
+  if (!LINK_STATES.includes(state)) {
+    return { error: `state must be one of: ${LINK_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 title = body && body.title ? String(body.title).slice(0, 300) : null;
+
+  // A typed reference is the PM's word, and the PM's word is a declaration. Silently downgrading
+  // would be the friendlier-looking choice and the wrong one: a client that asked to store a typed
+  // reference AS resolved has a bug, and a store that quietly corrects it hides the bug while the
+  // next caller writes the same line.
+  if (origin === 'typed' && state === 'resolved') {
+    return { error: 'a typed reference cannot be stored as resolved — nothing read it. Send origin: resolved with the profile that did.' };
+  }
+  if (state === 'resolved' && !profile) {
+    return { error: 'a resolved reference must name the profile whose session resolved it' };
+  }
+  if (state === 'unreachable' && !reason) {
+    return { error: 'an unreachable reference must carry the reason the lookup failed' };
+  }
+  return {
+    origin,
+    state,
+    profile,
+    reason,
+    title,
+    // Only a row that actually read something carries a read time. Absent means "nothing read it",
+    // which is a fact the surface renders rather than a gap it fills in.
+    resolved_at: state === 'resolved' ? (at || new Date().toISOString()) : null,
+  };
+}
+
 /** Validate + normalise an artifact-link declaration. Returns `{ok:false,error}` for a bad shape. */
 function artifactLinkRow(body, { at } = {}) {
   const artifact_path = String((body && body.artifact_path) || '').trim();
@@ -255,6 +407,8 @@ function artifactLinkRow(body, { at } = {}) {
   if (!target) return { ok: false, error: 'target is required' };
   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' };
+  const prov = provenance(body, at);
+  if (prov.error) return { ok: false, error: prov.error };
   return {
     ok: true,
     row: {
@@ -263,10 +417,13 @@ function artifactLinkRow(body, { at } = {}) {
       artifact_path,
       kind,
       target: target.slice(0, 300),
-      // Stated on every row, not implied by its absence: this is a DECLARATION. Nothing was read
-      // from the destination and nothing was written to it.
-      declared: true,
-      connector: null,
+      ...prov,
+      // Kept, and no longer the whole story. `declared: true` said "PMOS read nothing" back when
+      // that was true of every row; now it is true of exactly the rows whose state says so, and
+      // the state is the field to read. Retained because rows on disk carry it and a reader that
+      // drops a field silently changes what the history means.
+      declared: prov.state !== 'resolved',
+      connector: prov.state === 'resolved' ? prov.profile : null,
     },
   };
 }
@@ -280,20 +437,95 @@ function initiativeLinkRow(body, { at } = {}) {
   if (!validId(initiative_id)) return { ok: false, error: 'that initiative id is not a record name' };
   if (!kind) return { ok: false, error: 'kind is required' };
   if (!target) return { ok: false, error: 'a target reference is required' };
+  const prov = provenance(body, at);
+  if (prov.error) return { ok: false, error: prov.error };
   return {
     ok: true,
     row: {
       at: at || new Date().toISOString(),
       initiative_id,
       kind: kind.slice(0, 40),
-      label: (label || target).slice(0, 200),
+      // The destination's OWN title when a lookup returned one; otherwise what the PM typed, and
+      // failing that the reference itself. Never a label built out of the initiative slug — that
+      // was the fabrication, and a label assembled from local strings is one whatever it is called.
+      label: (prov.title || label || target).slice(0, 200),
       target: target.slice(0, 300),
-      declared: true,
-      connector: null,
+      ...prov,
+      declared: prov.state !== 'resolved',
+      connector: prov.state === 'resolved' ? prov.profile : null,
     },
   };
 }
 
+/**
+ * Collapse an append-only store into what the surface shows: ONE row per subject and destination
+ * kind, the latest winning.
+ *
+ * Both halves of that matter and they pull in opposite directions, which is why this is a read-time
+ * derivation rather than a write-time replace. The store is a history of what the PM declared and
+ * every row stays on disk — that is the whole reason it is append-only. The SURFACE is a statement
+ * of what is true now, and six clicks on one button are not six references; they are one reference
+ * declared six times. Before this, the store was right and the surface showed all six.
+ *
+ * `subject` is the artifact path for an artifact link and the initiative id for a reference, so a
+ * PRD linked to Jira and the initiative linked to Jira are different pairs and neither supersedes
+ * 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) {
+  const list = Array.isArray(rows) ? rows : [];
+  const seen = new Map();
+  list.forEach((row, i) => {
+    if (!row || typeof row !== 'object') return;
+    const subject = row.artifact_path || row.initiative_id || '';
+    const key = subject + '|' + 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,
+      // Rows written before provenance existed carry neither an origin nor a state. They are NOT
+      // rewritten to look like typed references — that would launder exactly the fabricated 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'),
+    }));
+}
+
+/**
+ * The task a session performs to resolve a reference. Composed here, on the server, because it is
+ * the thing the whole design turns on and a string built in a click handler is a string no test
+ * ever sees.
+ *
+ * Note what it asks for and what it does not. It asks the session to SEARCH and to report what it
+ * found, including finding nothing; it does not ask it to create, publish, or push anything, and it
+ * names the recording endpoint so the session records through the same validated path the PM's own
+ * typing goes through. There is no branch here in which PMOS makes a request.
+ */
+function lookupTask({ kind, subject, hint, profile } = {}) {
+  const k = String(kind || '').toLowerCase();
+  if (!LINK_KINDS.includes(k)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  const what = k === 'jira' ? 'Jira issue or epic' : k === 'confluence' ? 'Confluence page' : 'Google Doc';
+  return {
+    ok: true,
+    profile: profile || null,
+    text: [
+      `Find the ${what} that corresponds to "${String(subject || '').slice(0, 200)}".`,
+      hint ? `The PM's hint about which one: ${String(hint).slice(0, 200)}` : null,
+      '',
+      `Use your ${k} MCP tools to SEARCH. Do not create, publish, or modify anything.`,
+      'Report the candidates you found — key/id, title, and URL for each — and let the PM pick.',
+      'If you find nothing, say so plainly. If the lookup fails, report the error verbatim.',
+      'Do not guess an identifier, and do not construct one from the name above — a made-up',
+      'reference is worse here than no reference, which is the defect this replaced.',
+    ].filter((l) => l !== null).join('\n'),
+  };
+}
+
 /* ── the assembled payload ──────────────────────────────────────────────────────────────────── */
 
 /**
@@ -305,11 +537,13 @@ function initiativeLinkRow(body, { at } = {}) {
  * 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 }) {
+function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, homeDir }) {
   if (!rec.ok) return { ok: false, id, error: rec.error };
   const artifacts = artifactsFor(index, id);
   const sess = sessionsFor({ sessions, workspaces, id });
-  const mine = (rows, pred) => (rows && rows.ok ? rows.rows.filter(pred) : []);
+  // linkView LAST, so superseding happens across this initiative's rows only — collapsing the whole
+  // store first would let another initiative's link to the same path win a pair that is not its own.
+  const mine = (rows, pred) => linkView((rows && rows.ok ? rows.rows.filter(pred) : []));
   return {
     ok: true,
     id,
@@ -334,12 +568,13 @@ function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor,
       artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
       links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
     },
-    connectors: connectors(),
+    connectors: connectors(homeDir),
   };
 }
 
 module.exports = {
-  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS,
+  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND,
   validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
   storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
+  linkView, lookupTask,
 };

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "private": true,
-  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
+    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/pm/data.js

@@ -969,6 +969,18 @@ export async function recordArtifactLink({ artifact_path, slug, kind, target })
   return out;
 }
 
+/**
+ * panel-detail.js — `lookupTask({kind, subject, hint, profile})`.
+ *
+ * Asks the server to compose the task a SESSION will run to resolve a reference. It returns text.
+ * Nothing here contacts Jira, Confluence or Google, and nothing here can: the workspace holds no
+ * credential (D53 — the agent layer acts with the PM's own MCP, PMOS records the result).
+ */
+export async function lookupTask({ kind, subject, hint, profile }) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode composes no task' };
+  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 }) {
   if (FIXTURE) return { ok: true };

package/workspace/public/pm/fixture.js

@@ -790,7 +790,30 @@ export const artDiffText = dest => 'repo file is the source. read ' + (dest ? de
 export const artSyncPushed = dest => ({ color: 'var(--success)', text: 'pushed · repo → ' + dest.kind + ' · in sync 12:41' });
 export const artSyncPulled = dest => ({ color: 'var(--warning)', text: 'pulled · ' + dest.kind + ' → repo · file updated' });
 
-/** addLink (lines 1757–1766) — the link a source button appends. */
+/* addLink (lines 1757–1766) — PROTOTYPE TRANSCRIPTION ONLY. It has no caller, and must not gain one.
+ *
+ * This is the helper the whole workspace-external-linking initiative was opened about. It returns
+ * `{kind:'jira epic', label:'ATL-501 · <slug>', path:'jira://ATL-501', st:'connected'}` — a Jira key
+ * counted up from the constant 501, a label built from the initiative slug, and the word `connected`
+ * on a row nothing had read. panel-detail.js called it on every ＋ click and wrote the result to
+ * `initiative-links.jsonl`, so PMOS accumulated references to epics that do not exist, rendered in
+ * the same visual grammar it uses for facts.
+ *
+ * WHY IT IS STILL HERE, WHICH IS A REAL TENSION AND NOT AN OVERSIGHT. The initiative's rubric asks
+ * for the fabricating helpers to be REMOVED rather than bypassed, and deleting this function is the
+ * literal reading. But this module is a TRANSCRIPTION of the prototype, and fixture-parity.test.mjs
+ * exists to pin it line-for-line — deleting the function deletes that suite's assertion, and the
+ * same rubric forbids weakening an assertion to make a change pass. Both rules are right and they
+ * point opposite ways.
+ *
+ * The property that actually matters is not this function's existence; it is that nothing in real
+ * mode can reach it. So it stays, as the pinned record of what the prototype drew, and the guarantee
+ * is enforced mechanically instead of by deletion: pm-detail-test.js asserts that no module outside
+ * this file references `makeLink`. If a later change wires it back up, that test fails and names it.
+ *
+ * The seeded rows below (`ATL-482` and its siblings) are the same case and are correct: a prototype
+ * draws specimens. They are rendered in FIXTURE mode only and never reach the real store.
+ */
 export function makeLink(slug, src, existing = []) {
   if (src === 'jira') {
     const num = 501 + existing.filter(x => x.kind === 'jira epic').length;

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

@@ -151,12 +151,33 @@ function hasConnector(kind) {
     return c.some((x) => (typeof x === 'string' ? x : x && x.kind) === kind
       && (typeof x === 'string' || x.configured !== false));
   }
+  // The server's shape: `{configured:[{kind, profile, ...}], note}`. Checked BEFORE the plain-map
+  // branch below, which would otherwise read `c['jira']` on this object, find undefined, and report
+  // "no connector" on a machine whose profiles declare one — a false negative dressed as caution.
+  if (c && Array.isArray(c.configured)) return c.configured.some((x) => x && x.kind === kind);
   if (c && typeof c === 'object') return !!c[kind];
   return false;
 }
 
 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.';
+
 /* ── 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
  * header and search box do.
@@ -276,24 +297,89 @@ function phaseBlock(slug, rec) {
 }
 
 /* ── 5a · LINKS (lines 380–398, derivation 1757–1766, 1797–1798) ────────────────────────────
- * External references — NOT repo files. Sessions add them automatically; the three ＋ buttons let
- * the PM add one by hand, and adding one opens its preview immediately so the reference is
- * verified by looking at it rather than by trusting the row. Multiple links of a kind are allowed:
- * the Jira numbering counts the ones already filed rather than replacing them.
+ * External references — NOT repo files.
+ *
+ * WHAT CHANGED HERE, AND WHY IT IS THE POINT. This used to append a reference the moment a ＋ button
+ * was clicked, built out of the initiative slug and a counter: `ATL-501`, then `ATL-502`. The PM was
+ * never asked which epic. The row then labelled itself `connected`, and after a reload the same row
+ * read `declared · not connected` — one row, two labels, and the flattering one was the one visible
+ * at the moment of the click. Six clicks recorded six references to six epics that did not exist.
+ *
+ * A ＋ button now opens a FORM. Nothing is recorded until the PM supplies the reference or a session
+ * resolves it, because a reference nobody chose is not a reference — it is a guess written down in
+ * a place the PM will later trust. `makeLink` is gone rather than bypassed: a helper that can
+ * fabricate an identifier is a helper someone re-wires later.
+ */
+/**
+ * Hand the lookup to a session that can actually perform it.
+ *
+ * This is the seam the whole initiative turns on, so it is worth being explicit about what it does
+ * NOT do: it does not contact Jira, Confluence or Google, and it does not record a link. It asks
+ * the server to compose a task and shows that task to the PM to run in a session on the named
+ * profile — the session holds the credential, PMOS does not (D53). The session then records the
+ * resolved reference through the same validated endpoint the PM's own typing goes through, where
+ * it will be refused unless it names the profile that read it.
+ *
+ * The alternative — having the workspace perform the search itself — is the design D53 rejected and
+ * that `no-network.test.js` fails by construction. There is no version of this function that calls out.
  */
+function askSessionToResolve(slug, kind, resolver, hint) {
+  const data = sibling('data', './data.js');
+  if (!data || typeof data.lookupTask !== 'function') return;
+  Promise.resolve(data.lookupTask({ kind, subject: slug, hint, profile: resolver.profile }))
+    .then((out) => {
+      if (!out || out.ok === false) {
+        setState((s) => ({ linkTask: { ...s.linkTask, [slug]: { error: (out && out.error) || 'the task could not be composed' } } }));
+        return;
+      }
+      setState((s) => ({ linkTask: { ...s.linkTask, [slug]: { text: out.text, profile: resolver.profile, kind } } }));
+    })
+    .catch((e) => setState((s) => ({ linkTask: { ...s.linkTask, [slug]: { error: String((e && e.message) || e) } } })));
+}
+
+function linkStateStyle(st) {
+  if (st === 'resolved') return { color: 'var(--success)', label: 'resolved' };
+  if (st === 'unreachable') return { color: 'var(--warning)', label: 'unreachable' };
+  if (st === 'unattributed') return { color: 'var(--muted-foreground)', label: 'unattributed' };
+  return { color: 'var(--muted-foreground)', label: 'declared' };
+}
+
+/**
+ * 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
+ * returns a bare status word, because a bare status word is what `connected` was.
+ */
+function linkStateText(lk) {
+  const st = lk.state || (lk.origin ? 'declared' : 'unattributed');
+  if (st === 'resolved') {
+    const when = String(lk.resolved_at || '').slice(11, 16);
+    return 'resolved by ' + (lk.profile || 'a session') + (when ? ' · read ' + when : '');
+  }
+  if (st === 'unreachable') return 'unreachable · ' + (lk.reason || 'the lookup failed');
+  if (st === 'unattributed') return 'recorded before provenance — origin unknown';
+  return 'declared · nothing read it';
+}
+
 function linksRow(slug) {
   const rec = records()[slug] || {};
   const manual = (state.initLinks || {})[slug] || [];
   const links = [...(rec.links || []), ...manual];
-
-  const addLink = (src) => {
-    const link = FX.makeLink(slug, src, manual);
+  const openSrc = (state.linkForm || {})[slug] || null;
+
+  /**
+   * Record what the PM typed. `origin: 'typed'` is sent explicitly and the server will refuse to
+   * store it as anything stronger — a typed reference is the PM's word, and the row says so.
+   */
+  const submitTyped = (src, ref) => {
+    const target = String(ref || '').trim();
+    if (!target) return;
+    const link = { kind: src, label: target, path: target, target, origin: 'typed', state: 'declared' };
     setState(
-      (s) => ({ initLinks: { ...s.initLinks, [slug]: [...((s.initLinks || {})[slug] || []), link] } }),
-      () => {
-        declare('recordInitiativeLink', { slug, ...link });
-        openDoc(slug, link.path, link.kind.toUpperCase());
-      },
+      (s) => ({
+        initLinks: { ...s.initLinks, [slug]: [...((s.initLinks || {})[slug] || []), link] },
+        linkForm: { ...s.linkForm, [slug]: null },
+      }),
+      () => declare('recordInitiativeLink', { slug, ...link }),
     );
   };
 
@@ -304,13 +390,80 @@ function linksRow(slug) {
   },
     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)),
-    el('span', { style: 'margin-left:auto;flex:none;font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' }, iv(lk.st)),
+    // 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)),
   ));
 
+  // 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.
+  const conn = (state.connectors && state.connectors.configured) || [];
+  const resolverFor = (kind) => conn.find((c) => c.kind === kind) || null;
+
+  const form = openSrc ? (() => {
+    const resolver = resolverFor(openSrc);
+    const task = (state.linkTask || {})[slug] || null;
+    const inputId = 'linkref-' + slug + '-' + openSrc;
+    const read = () => {
+      const node = document.getElementById(inputId);
+      return node ? node.value : '';
+    };
+    return el('div', { style: 'margin-top:6px;padding:9px 11px;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:7px' },
+        iv(resolver
+          ? 'paste the reference, or ask ' + resolver.profile + ' to find it — that session holds your '
+            + openSrc + ' MCP. PMOS itself reads nothing.'
+          : 'paste the reference. No agent profile declares a ' + openSrc
+            + ' MCP, so nothing here can look it up for you — what you type is recorded as your own declaration.')),
+      el('input', {
+        id: inputId,
+        placeholder: openSrc === 'jira' ? 'ATL-482 or its URL' : 'the page or document URL',
+        style: 'width:100%;font-family:var(--mono);font-size:11.5px;padding:6px 8px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
+      }),
+      el('div', { style: 'display:flex;gap:6px;margin-top:8px;flex-wrap:wrap' },
+        el('button', {
+          onClick: () => submitTyped(openSrc, read()),
+          style: 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:28px;background:var(--brand);color:oklch(0.987 0.002 197.1);font-weight:500',
+        }, 'record this reference'),
+        resolver && el('button', {
+          onClick: () => askSessionToResolve(slug, openSrc, resolver, read()),
+          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)',
+        }, 'ask ', iv(resolver.profile), ' to find it'),
+        el('button', {
+          onClick: () => setState((s) => ({ linkForm: { ...s.linkForm, [slug]: null } })),
+          style: 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:28px;background:transparent;border:1px solid var(--border);color:var(--muted-foreground)',
+        }, 'cancel'),
+      ),
+      task && (task.error
+        ? el('div', { style: 'margin-top:8px;font-size:11.5px;color:var(--warning);line-height:1.5' },
+          iv('the lookup task could not be composed — ' + task.error))
+        : el('div', { style: 'margin-top:8px' },
+          el('div', { style: 'font-size:11px;color:var(--muted-foreground);line-height:1.5;margin-bottom:5px' },
+            iv('run this in a session on ' + task.profile + '. it records the reference itself, and PMOS'
+              + ' will refuse the result unless it names the profile that read 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)))),
+    );
+  })() : null;
+
   const addRow = el('div', { style: 'display:flex;gap:6px;align-items:center;flex-wrap:wrap;margin-top:4px' },
     el('span', { style: 'font-family:var(--mono);font-size:9.5px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted-foreground)' }, 'link'),
     FX.LINK_SRCS.map((ls) => el('button', {
-      onClick: () => addLink(ls.src),
+      onClick: () => setState((s) => ({
+        linkForm: { ...s.linkForm, [slug]: (s.linkForm || {})[slug] === ls.src ? null : ls.src },
+      })),
       style: 'display:flex;gap:5px;align-items:center;font-family:var(--mono);font-size:10.5px;padding:4px 9px;min-height:28px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
       hover: 'border-color:var(--ring)',
     }, '＋ ', iv(ls.l))),
@@ -321,6 +474,7 @@ function linksRow(slug) {
     el('div', { style: 'display:flex;flex-direction:column;gap:2px;min-width:0' },
       rows,
       addRow,
+      form,
       el('span', { style: 'font-size:11px;color:var(--muted-foreground);margin-top:3px;line-height:1.5' },
         'references — not in the repo. sessions add these automatically; link one yourself when you need it.'),
     ),
@@ -354,19 +508,69 @@ function artifactRow(slug, a) {
 
   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', {
         onClick: () => {
-          const d = FX.linkArtDest(key, ls.kind);
-          setState((s) => ({ artLinks: { ...s.artLinks, [key]: d } }));
-          declare('recordArtifactLink', { artifact_path: a.path, slug, kind: d.kind, target: d.target });
+          if (FIXTURE) {
+            const d = FX.linkArtDest(key, ls.kind);
+            setState((s) => ({ artLinks: { ...s.artLinks, [key]: d } }));
+            return;
+          }
+          setState((s) => ({
+            artLinkForm: { ...s.artLinkForm, [key]: (s.artLinkForm || {})[key] === ls.kind ? null : ls.kind },
+          }));
         },
         style: 'font-family:var(--mono);font-size:10px;padding:3px 8px;min-height:24px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)',
         hover: 'border-color:var(--ring)',
       }, '＋ ', iv(ls.l))),
     );
-    return el('div', { style: 'min-width:0' }, head, linkRow);
+
+    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);
   }
 
   // Linked: the destination pill, the sync button, and the persisted result of the last approval.
@@ -384,7 +588,9 @@ function artifactRow(slug, a) {
   let panel = null;
   if (syncOpen) {
     const live = hasConnector(dest.kind);
-    const inert = !live;
+    // 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 decide = (make) => () => {
       if (inert) return;
       setState((s) => ({
@@ -395,7 +601,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(live ? FX.artDiffText(dest) : NO_CONNECTOR)),
+        iv(FIXTURE ? (live ? FX.artDiffText(dest) : NO_CONNECTOR) : SYNC_OUT_OF_SCOPE)),
       el('div', { style: 'display:flex;gap:6px;margin-top:8px;flex-wrap:wrap' },
         el('button', {
           onClick: decide(FX.artSyncPushed), disabled: inert,

package/workspace/server.js

@@ -3850,6 +3850,11 @@ async function handleRequest(req, res) {
         : null,
       artifactLinks: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_LINKS),
       initiativeLinks: fourPanel.readDeclarations(stateDir, fourPanel.INITIATIVE_LINKS),
+      // 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
+      // tested against the machine running the suite.
+      homeDir: os.homedir(),
     });
     // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
     return json(res, { ws: w ? w.id : null, ...out });
@@ -3877,7 +3882,20 @@ async function handleRequest(req, res) {
       built.row,
     );
     // A write that failed returns 500 and says so — never a false green (the /api/gate rule).
-    return json(res, { ...wrote, connectors: fourPanel.connectors() }, wrote.ok ? 200 : 500);
+    return json(res, { ...wrote, connectors: fourPanel.connectors(os.homedir()) }, 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,
+    // an agent session holding the PM's own MCP performs it, and the result comes back through
+    // /api/initiative/link like any other declaration. There is no branch here that reaches out.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const built = fourPanel.lookupTask({
+      kind: body.kind, subject: body.subject, hint: body.hint, profile: body.profile,
+    });
+    return json(res, built, built.ok ? 200 : 400);
   }
   if (p === '/api/search') {
     // Episodic recall over this workspace's own past sessions. Localhost only, like everything