create-pmos 0.14.0 → 0.16.0

package/workspace/lib/four-panel.js

@@ -0,0 +1,345 @@
+'use strict';
+/* lib/four-panel.js — the assembly behind `GET /api/initiative?id=&ws=`, and the two
+ * declaration stores the four-panel surface writes.
+ *
+ * ── Why this endpoint exists ─────────────────────────────────────────────────────────────────
+ * Panel 3 answers one question about ONE initiative, and answering it today costs four reads that
+ * every client would have to join for itself: `/api/library` for artifacts, `/api/console?
+ * name=ladder` for the engine's rungs, `/api/console?name=handoff` for external references, and a
+ * client-side join of `/api/sessions` against the `initiative/<id>` branch convention. Four
+ * round-trips per selection, and — worse — four chances for two surfaces to disagree about what a
+ * record declares. This module does the join once, server-side, from the SAME producers the
+ * existing endpoints use. It adds no new reader: `ladder`, `links`, `index` and `sessions` are
+ * passed IN by the route, already produced by console-state, handoff.js, initiativeIndex() and
+ * sessionList(). Nothing here re-derives them, so `/api/initiative` and `/api/console` can never
+ * hold two opinions about the same initiative.
+ *
+ * The existing endpoints are untouched on purpose — other surfaces still read them.
+ *
+ * ── The frontmatter reader ───────────────────────────────────────────────────────────────────
+ * The record's frontmatter is parsed with the WORKFLOW ENGINE's parser, not the workspace's
+ * `file-mode-parse`. The two disagree: file-mode-parse requires at least one character after the
+ * colon (`/^([a-z_]+):\s*(.+?)\s*$/`), so a record carrying an empty-valued key — `prd_path:` with
+ * nothing after it, which several records do — terminates the block there and drops every key
+ * below it, including `lane` and `parent_kr`. The engine tolerates the empty value and strips
+ * surrounding quotes. Reading a record through the parser that DERIVES the ladder is the only way
+ * 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.
+ *
+ * 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
+ * `planning/runs/` in pmos-self, where `pmos/state/` does not exist and the runs, evals and
+ * acceptances live. Hard-coding the PRD's path would have put every pmos-self declaration in a
+ * directory nothing else reads; and the workspace's own `state/` was the other candidate and is
+ * wrong for the opposite reason — it is gitignored runtime state, so a declaration written there
+ * would be a record of a PM decision that does not survive the machine.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ARTIFACT_LINKS = 'artifact-links.jsonl';
+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'];
+
+/** 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.
+ */
+function connectors() {
+  return {
+    configured: [],
+    note: 'no connector configured — nothing was read, and nothing will be written.',
+  };
+}
+
+/* ── the record ─────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Read `<initiatives>/<id>.md`. ABSENT and BROKEN are different facts and never share an answer:
+ * a record that does not exist is a supported state the panel already draws ("no record"), while
+ * an unreadable one is PMOS failing to look and must render RED.
+ *
+ * `parse` is the engine's `parseLeadingFrontmatter`, injected so this module owns no second
+ * opinion about what a record declares.
+ */
+function readRecord({ root, dir, id, parse }) {
+  const file = path.join(dir, `${id}.md`);
+  const rel = path.relative(root, file);
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: true, absent: true, record: rel, frontmatter: null };
+    return { ok: false, error: `${rel} could not be read — ${String((e && e.code) || 'read failed')}` };
+  }
+  let fm;
+  try { fm = parse(text); }
+  catch (e) {
+    return { ok: false, error: `${rel} — ${String((e && e.message) || 'the frontmatter could not be parsed').slice(0, 160)}` };
+  }
+  return { ok: true, absent: false, record: rel, frontmatter: fm, tasks: parseTasks(text) };
+}
+
+/**
+ * The OPTIONAL authored-task override (PRD, "Tasks"): a `## Tasks` section in the record BODY,
+ * with `### <phase>` sub-headings and `- title:` items carrying single-line `key: value` fields.
+ *
+ * It lives in the body and not in the frontmatter for a mechanical reason: the leading-frontmatter
+ * readers stop at the first line that is not `key: value`, so a YAML list under a `tasks:` key
+ * would silently drop `lane:` and `parent_kr:` below it. Absence of the section is not a defect
+ * and returns null — the caller derives instead, and a `{}` here would be indistinguishable from
+ * "authored, and empty".
+ */
+function parseTasks(text) {
+  const lines = String(text == null ? '' : text).split('\n');
+  let i = lines.findIndex((l) => /^##\s+Tasks\s*$/i.test(l));
+  if (i < 0) return null;
+  const out = {};
+  let phase = null, task = null;
+  for (i += 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line) && !/^###\s+/.test(line)) break;      // the next section ends Tasks
+    let m = line.match(/^###\s+(\S+)\s*$/);
+    if (m) { phase = m[1]; task = null; if (!out[phase]) out[phase] = []; continue; }
+    if (!phase) continue;
+    m = line.match(/^\s*-\s+title:\s*(.*?)\s*$/);
+    if (m) { task = { title: m[1], status: 'todo' }; out[phase].push(task); continue; }
+    m = line.match(/^\s+([a-zA-Z_]+):\s*(.*?)\s*$/);
+    if (m && task) task[m[1] === 'evaluation' ? 'evalNote' : m[1]] = m[2];
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/* ── artifacts ──────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * This initiative's artifacts out of the library index. The index is the SAME producer
+ * `/api/library` uses, so the two surfaces list the same files in the same order — an artifact
+ * list that differed between panel 3 and the library lens would be two answers to one question.
+ * An initiative the index has never heard of has no artifacts; that is an empty list, not an error.
+ */
+function artifactsFor(index, id) {
+  const rows = (index && Array.isArray(index.initiatives)) ? index.initiatives : [];
+  const hit = rows.find((r) => r && r.id === id);
+  if (!hit || !Array.isArray(hit.artifacts)) return [];
+  return hit.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path, title: a.title || null }));
+}
+
+/* ── sessions ───────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Which live sessions belong to this initiative. Sessions carry NO `initiative_id` — the only
+ * signal is the `initiative/<id>` branch convention, so the join is: every registered working tree
+ * whose branch is `initiative/<id>`, then every session whose `ws` is one of those trees.
+ *
+ * `matched` names the trees the join found. It is carried because "no sessions" and "no working
+ * tree on that branch" are different states with different copy, and a client that only received
+ * an empty array would have to guess which one it was looking at.
+ */
+function sessionsFor({ sessions, workspaces, id }) {
+  const branch = `initiative/${id}`;
+  const trees = (workspaces || []).filter((w) => w && w.branch === branch);
+  const ids = new Set(trees.map((w) => w.id));
+  return {
+    matched: trees.map((w) => ({ ws: w.id, name: w.name, root: w.root, branch: w.branch })),
+    sessions: (sessions || []).filter((s) => s && ids.has(s.ws)),
+  };
+}
+
+/* ── anchor ─────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Resolve the record's `parent_kr` through the same resolver the spine and the ladder use.
+ * `anchors` is `scripts/anchor-resolve.js`, injected; without it the anchor is UNKNOWN and says so
+ * rather than being reported as unanchored — "we could not look" and "there is nothing there" are
+ * the two answers this repo most insists on keeping apart.
+ */
+function anchorFor({ anchors, root, raw }) {
+  if (!anchors) {
+    return {
+      raw: raw || null, status: 'unknown', canonical: null,
+      reason: 'the anchor resolver (scripts/anchor-resolve.js) is not present in this install',
+    };
+  }
+  const index = anchors.parseOkrIndex(root);
+  const budgets = anchors.readBudgets(root);
+  const r = anchors.resolveAnchor(raw == null ? '' : String(raw), index, budgets);
+  return Object.assign({}, r, { canonical: anchors.canonical(r, index && index.period) });
+}
+
+/* ── the declaration stores ─────────────────────────────────────────────────────────────────── */
+
+function linkFile(stateDir, name) {
+  return stateDir ? path.join(stateDir, name) : null;
+}
+
+/**
+ * Where the two stores live for a repo: the same directory the engine already puts this repo's
+ * append-only records in. One resolver, so a declaration cannot land somewhere the reader does not
+ * look. Returns null when the engine is unavailable — the caller then says it could not write,
+ * rather than inventing a location.
+ */
+function storeDir(engine, root) {
+  if (!engine || typeof engine.layout !== 'function') return null;
+  try { return engine.layout(root).runsDir; } catch { return null; }
+}
+
+/** Read one store. A torn line is DROPPED, never guessed — the same rule every jsonl reader here follows. */
+function readDeclarations(stateDir, name) {
+  const file = linkFile(stateDir, name);
+  if (!file) return { ok: false, error: 'no file-mode state directory for this workspace — nothing was read', rows: [] };
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: true, empty: true, file, rows: [] };
+    return { ok: false, error: `${name} could not be read — ${String((e && e.code) || 'read failed')}`, rows: [] };
+  }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch { /* torn line — dropped */ }
+  }
+  return { ok: true, empty: rows.length === 0, file, rows };
+}
+
+/**
+ * Append one declaration. Append-only: a later row for the same artifact supersedes an earlier one
+ * on read, and the earlier one stays on disk, because the history of what the PM declared is the
+ * point of a declaration store.
+ *
+ * A failed write returns `{ok:false}` and never a false green — the same rule `POST /api/gate`
+ * follows, and for the same reason: a click that goes green over a record that was never written
+ * is the worst failure this surface can have.
+ */
+function appendDeclaration(stateDir, name, row) {
+  const file = linkFile(stateDir, name);
+  if (!file) {
+    return { ok: false, error: 'this workspace has no file-mode state directory — the declaration was NOT recorded' };
+  }
+  try {
+    // The directory is created rather than required: a repo that has never recorded a run has no
+    // runs directory yet, and refusing the PM's first declaration for that reason would be a
+    // failure with no cause the PM could act on.
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return { ok: true, recorded: row, sink: file };
+  } catch (e) {
+    return { ok: false, error: `could not write ${name} — ${String((e && e.code) || 'write failed')}`, sink: file };
+  }
+}
+
+/** 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();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const target = String((body && body.target) || '').trim();
+  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' };
+  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),
+      // 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,
+    },
+  };
+}
+
+/** Validate + normalise an initiative-link (manual reference) declaration. */
+function initiativeLinkRow(body, { at } = {}) {
+  const initiative_id = String((body && body.initiative_id) || '').trim();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const label = String((body && body.label) || '').trim();
+  const target = String((body && (body.target || body.path)) || '').trim();
+  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' };
+  return {
+    ok: true,
+    row: {
+      at: at || new Date().toISOString(),
+      initiative_id,
+      kind: kind.slice(0, 40),
+      label: (label || target).slice(0, 200),
+      target: target.slice(0, 300),
+      declared: true,
+      connector: null,
+    },
+  };
+}
+
+/* ── the assembled payload ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * Join the pieces into the one payload panel 3 reads. Every field is either something a producer
+ * returned or explicitly null; nothing here invents a value.
+ *
+ * The result follows the house contract: `{ok:false,error}` for a failed read (RED),
+ * `{ok:true,absent:true,…}` for an initiative with no record (a supported, calm state — the
+ * 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 }) {
+  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) : []);
+  return {
+    ok: true,
+    id,
+    absent: !!rec.absent,
+    record: rec.record,
+    frontmatter: rec.frontmatter,
+    tasks: rec.tasks || null,
+    artifacts,
+    // Straight through from console-state — the SAME object `/api/console?name=ladder` returns,
+    // including its own {ok,empty,row,scope} discrimination, so a client already reading that
+    // endpoint reads this one without a second shape.
+    ladder: ladder || null,
+    // Straight through from handoff.js. `connected` is the literal false on every path it has.
+    links: links || null,
+    anchor: anchor || null,
+    sessions: sess.sessions,
+    session_trees: sess.matched,
+    declarations: {
+      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),
+      artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
+      links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
+    },
+    connectors: connectors(),
+  };
+}
+
+module.exports = {
+  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS,
+  validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
+  storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
+};

package/workspace/lib/git-info.js

@@ -85,6 +85,33 @@ function worktreesAt(top) {
   return out;
 }
 
+// The URL `origin` fetches from, or null when there is no origin (or no git at all). This is the
+// ONLY thing that can answer "did this working tree come from somewhere, or is it a folder on this
+// machine?" — the presence of a `.git` directory answers a different question and answering with it
+// would put a provenance label on a row that no read supports.
+// `git remote get-url` rather than `git config remote.origin.url`: it resolves insteadOf/pushInsteadOf
+// rewrites, so what comes back is the URL git would actually contact.
+function originUrl(root) {
+  if (!root || !isDir(root)) return null;
+  const r = git(root, ['remote', 'get-url', 'origin']);
+  if (r.failed || r.code !== 0 || !r.out) return null;
+  return r.out.split('\n')[0].trim() || null;
+}
+
+// Is this remote a GitHub one? Both URL shapes git accepts: scp-style (git@github.com:o/r.git) and
+// a real URL (https://github.com/o/r, ssh://git@github.com/o/r). Any other host — GitLab, Gitea, a
+// bare path, a local mirror — is NOT github, and saying otherwise would be the unsupported label
+// this function exists to avoid. It answers about the URL only; the caller decides what to call it.
+function isGithubRemote(url) {
+  const u = String(url || '').trim();
+  if (!u) return false;
+  const scp = u.match(/^[^/@]+@([^:/]+):/);              // git@host:owner/repo.git
+  const host = scp ? scp[1] : (u.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/:]+)/i) || [])[1];
+  if (!host) return false;
+  const h = host.toLowerCase();
+  return h === 'github.com' || h.endsWith('.github.com');
+}
+
 // Where an isolated worktree lands: a sibling of the repo, gathered under one `<repo>-worktrees/`
 // folder. Deliberately OUTSIDE the repo — nothing new appears inside the tree, so no `git status`
 // noise and nothing for .gitignore to chase. The path is derived from a name already passed
@@ -240,4 +267,4 @@ function branchInfo(root) {
 }
 
 module.exports = { isRepo, repoRoot, validBranchName, branchInfo, checkout, worktrees, worktreePath,
-  addWorktree, worktreeSafety, removeWorktree };
+  addWorktree, worktreeSafety, removeWorktree, originUrl, isGithubRemote };

package/workspace/lib/handoff.js

@@ -0,0 +1,280 @@
+'use strict';
+/*
+ * The handoff links model (workspace-jira-handoff · PRD R1/R4/R5/R6/R7).
+ *
+ * A real PMOS workflow can end outside PMOS: the PM owns intake through spec, and the build happens
+ * on another team's board. This module turns what an initiative RECORD declares about that handoff
+ * into a model the panel can render. It reads the record's frontmatter and nothing else, because
+ * there is nothing else to read.
+ *
+ * THE DISTINCTION THE WHOLE MODULE RESTS ON:
+ *   A DECLARATION is something the PM typed into `planning/initiatives/<id>.md`.
+ *   A READING is something PMOS went and looked at.
+ *   This module returns declarations, labels them as declarations, and returns no readings at all.
+ *
+ * Even the epic key is a declaration. PMOS does not know that `ATL-482` exists, that it is an epic,
+ * that it belongs to this initiative, or that anyone has touched it. It knows that a human wrote
+ * that string in a file in this repository. Every rule below follows from taking that seriously.
+ *
+ * WHY THERE IS NO STORY COUNT AND NO SYNC TIME, AND WHY THAT IS NOT A "NOT YET".
+ * There is no Jira client, no Confluence client, no credential store, no host allow-list and no
+ * outbound call anywhere in the workspace. That absence is a RULING, not a gap:
+ * `planning/prd/jira-sync-prd.md` records that a PMOS-side Jira REST client and a stored credential
+ * were built in a first draft and then REJECTED by the PM at build review, under D01 (orchestrate,
+ * don't execute) and D51 (no standing credential). So `3 of 7 stories done` here would not be an
+ * optimistic estimate or a stale cache — it would be a fabricated reading of a system PMOS cannot
+ * see, wearing the same visual grammar the panel uses for facts it actually derived. A PM who
+ * believes PMOS is watching Jira stops watching Jira, and that is the failure this module exists to
+ * make impossible.
+ *
+ * HONEST BY CONSTRUCTION, NOT BY DISCIPLINE. The defence is structural, so that it survives an
+ * author who has not read this comment. handoff.test.js asserts each of these as a property:
+ *
+ *   · this file `require`s NOTHING — no fs, no net, no clock. There is no path by which an external
+ *     reading could enter it, and no I/O to mock, stub or accidentally re-enable;
+ *   · the model contains NO NUMBER anywhere — every value is a string, a boolean, null, or an array
+ *     of those. A story count, an issue tally and a progress percentage have no field to live in;
+ *   · the field sets are closed. A link is exactly LINK_FIELDS, the result is exactly RESULT_FIELDS,
+ *     and the test compares those key lists for equality — so `synced_at` cannot be added quietly;
+ *   · `connected` is the literal `false`, and the whole result is deep-frozen, so a consumer can
+ *     neither flip it nor bolt a fabricated field onto it after the fact;
+ *   · every string this module emits is either copied VERBATIM out of the record or is fixed prose
+ *     enumerated in the test — so a value that is computed, estimated, or formatted relative to now
+ *     fails the moment it is invented, whatever it is and however plausible it looks.
+ *
+ * The not-connected state is not decoration on this feature — it IS the feature. The failure it
+ * prevents is a screen on which every individual sentence is true and the composition still reads
+ * as a live connection.
+ *
+ * WHAT THIS MODULE DOES NOT DO — deliberately, and the renderer must:
+ *   · it does not escape. Values come straight from frontmatter and have NOT passed through `esc()`
+ *     (unlike `mdLink`, which is safe only because `inline()` escaped the whole line first). They
+ *     are returned verbatim so the whitelist property test can compare them against the record file
+ *     byte for byte; the renderer MUST escape at every interpolation site, including the `href`;
+ *   · it does not compose the R8 ladder annotation or the R10 sessions line. It returns the pieces
+ *     (`to`, `at`, `systems`) and leaves the sentence to the surface that shows it.
+ */
+
+// ── the record fields (PRD R1) ──────────────────────────────────────────────────────────────────
+// All five optional, all flat, all single-line — `parseLeadingFrontmatter` (lib/file-mode-parse.js)
+// admits `^[a-z_]+: value$` and nothing else. A YAML list under a `links:` key does not partially
+// parse: it TERMINATES the frontmatter block at that line and silently drops every field below it,
+// including `lane` and `parent_kr`. That is why there is no list form here and never will be; the
+// truncation is pinned by a test in handoff.test.js so the next author who reaches for a list finds
+// a failing test explaining it rather than an initiative that reads as unanchored.
+const HANDOFF_KEYS = ['flow', 'handoff_to', 'handoff_epic', 'handoff_page', 'handoff_at'];
+
+// The two keys that name something in another system. Iteration order here — not frontmatter order —
+// fixes the order of `links`, so the section renders the same way whatever order the PM typed.
+const REFERENCE_KEYS = ['handoff_epic', 'handoff_page'];
+const KIND = { handoff_epic: 'jira', handoff_page: 'confluence' };
+const SYSTEM = { handoff_epic: 'Jira', handoff_page: 'Confluence' };
+
+// The closed field sets. These exist to be asserted against: a new field is a test failure, which is
+// the point — "no story count" has to be a property of the shape, not a habit of the author.
+const LINK_FIELDS = ['kind', 'id', 'declared', 'state', 'why', 'state_text', 'href', 'inert_why'];
+const PROBLEM_FIELDS = ['id', 'declared', 'why'];
+const RESULT_FIELDS = ['connected', 'handoff', 'flow', 'to', 'at', 'systems', 'links', 'problems', 'empty'];
+
+// The one state a link can be in. There is no second value and no code path toward one.
+const NOT_CONNECTED = 'not-connected';
+
+// R5 — why a bare reference is inert. PMOS was handed a key, not a location; guessing the location
+// (a base URL, an issue-browse path) would be PMOS inventing the one thing it was not told.
+const INERT_WHY = 'PMOS was given a reference, not a URL, and will not construct one it was not given';
+
+// R4 — the state, per row and per system. `why` is the short clause; `state_text` is the full
+// sentence for the row's accessible name. BOTH are per-link on purpose: a single banner at the top
+// of the section is the FAIL shape the PRD names, because a PM scanning a row sees the row.
+function whyFor(system) { return `no ${system} credential is configured`; }
+function stateTextFor(system) {
+  return `not connected — ${whyFor(system)}; this is what the record declares, not a reading`;
+}
+
+// ── validation ──────────────────────────────────────────────────────────────────────────────────
+// This surface has no read that can fail, so a malformed declaration is the only failure it CAN
+// have — which makes it the only thing that may render red, and it must (R7).
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const ISO_DATE = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/;
+const SINGLE_TOKEN = /^\S+$/;
+// `flow` names the file `planning/workflows/<flow>.md`, so it is a filename and is checked as one.
+// A value carrying `/` or a leading `.` would send the "open the template" affordance somewhere the
+// PM did not point it.
+const TEMPLATE_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+// R5's allow-list, deliberately STRICTER than `mdLink`'s (`app.js:2999`), which also admits
+// protocol-relative `//host` and `mailto:`. Neither belongs on a handoff reference: `//evil` inherits
+// whatever scheme the page happens to be on, and a mail address is not an epic. A host character is
+// required after the slashes, so a bare `https://` is refused rather than rendered as a dead link.
+const ABSOLUTE_URL = /^https?:\/\/[^\s/?#]+/i;
+
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+// Names a JS type for a problem message. Used ONLY when the declared value is not text at all, in
+// which case there is no "value verbatim" to print and naming what arrived is the honest substitute.
+function typeName(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'an array';
+  return typeof v === 'object' ? 'an object' : `a ${typeof v}`;
+}
+
+// Per-key shape rules. Each returns a reason string when the value is malformed, else null.
+// NOTE: a reason NEVER embeds the declared value — the `declared` field prints it verbatim, and
+// keeping the prose value-free is what lets the whitelist property test enumerate the fixed
+// vocabulary this module can emit.
+const CHECK = {
+  flow: (v) => (TEMPLATE_NAME.test(v) ? null
+    : '`flow:` names a template file under planning/workflows/ — lower-case letters, digits, dot, underscore and hyphen only. This value cannot name a file, so there is nothing to open'),
+  // `handoff_to` is "who received it, in plain language" (R1), so whitespace is EXPECTED here and
+  // the token rule below must not be applied to it. The asymmetry is deliberate, not an oversight.
+  handoff_to: () => null,
+  handoff_epic: (v) => (SINGLE_TOKEN.test(v) ? null
+    : '`handoff_epic:` holds a reference or an absolute URL — a single token. This value contains whitespace, so it is prose in a field meant for an identifier, and PMOS will not dress prose as a reference'),
+  handoff_page: (v) => (SINGLE_TOKEN.test(v) ? null
+    : '`handoff_page:` holds a reference or an absolute URL — a single token. This value contains whitespace, so it is prose in a field meant for an identifier, and PMOS will not dress prose as a reference'),
+  handoff_at: (v) => (ISO_DATE.test(v) ? null
+    : '`handoff_at:` is the ISO date the PM declared the handoff (YYYY-MM-DD). This value is not one, and PMOS will not guess what date was meant'),
+};
+
+/* Read ONE declared key. Returns { present, value, why }:
+ *   present:false           — the key is not in the record. Nothing is claimed about it.
+ *   why:null                — a well-formed declaration; `value` is the verbatim (trimmed) string.
+ *   why:<reason>            — malformed; `value` is the offending string verbatim, or null when the
+ *                             declared value was never text.
+ * ABSENT and MALFORMED are answered separately because they are different facts: one is an
+ * initiative that was not handed off, the other is a record with a mistake in it, and rendering the
+ * second as the first is how a typo becomes silence.
+ */
+function readDeclared(fm, key) {
+  if (!has(fm, key)) return { present: false, value: null, why: null };
+  const raw = fm[key];
+  if (typeof raw !== 'string') {
+    return { present: true, value: null,
+      why: `\`${key}:\` is ${typeName(raw)}, not the single-line string the record format admits — PMOS prints what the record declares as text, and there is no text here to print` };
+  }
+  const v = raw.trim();
+  if (!v) {
+    return { present: true, value: null,
+      why: `\`${key}:\` is present but empty — the key is declared and no value is, so there is nothing to state` };
+  }
+  if (CONTROL_CHARS.test(v)) {
+    return { present: true, value: null,
+      why: `\`${key}:\` contains a control character — refused rather than rendered, because what it would print is not what the record shows` };
+  }
+  return { present: true, value: v, why: CHECK[key](v) };
+}
+
+// Freezing is part of the contract, not tidiness: a frozen result cannot acquire a `synced_at` or a
+// `story_count` downstream, and `connected` cannot be flipped by a consumer that would rather it
+// were true.
+function deepFreeze(o) {
+  if (o && typeof o === 'object' && !Object.isFrozen(o)) {
+    Object.freeze(o);
+    for (const k of Object.keys(o)) deepFreeze(o[k]);
+  }
+  return o;
+}
+
+/* readLinks(record) — the handoff model for ONE initiative.
+ *
+ * `record` is the initiative's parsed leading frontmatter: the plain object
+ * `parseLeadingFrontmatter(text)` returns (lib/file-mode-parse.js). Not a path, not the file text —
+ * this module does no I/O by design, and a caller that hands it text gets a stated problem rather
+ * than a silent empty, because "no handoff declared" and "you gave me the wrong thing" are
+ * different facts.
+ *
+ * Returns a deep-frozen object with exactly RESULT_FIELDS:
+ *
+ *   connected  false — ALWAYS, a literal. There is no argument, no record field and no code path
+ *                      that produces any other value.
+ *   handoff    boolean — the record declares `flow:` or any `handoff_*` key. False for every
+ *                      initiative that was not handed off, so the panel is unchanged for them.
+ *   flow       string|null — the verbatim `flow:` value, or null (absent or malformed).
+ *   to         string|null — the verbatim `handoff_to:` value.
+ *   at         string|null — the verbatim `handoff_at:` value, only when it is an ISO date.
+ *   systems    string[] — 'Jira' and/or 'Confluence', from which reference keys are DECLARED
+ *                      (including malformed ones — a broken epic still names what PMOS cannot read).
+ *   links      link[] — one per well-formed reference, in REFERENCE_KEYS order.
+ *   problems   problem[] — one per malformed declaration (R7). Render red, value verbatim.
+ *   empty      boolean — a handoff is declared and there is nothing to link and nothing wrong: the
+ *                      verified empty of R6. Absence is STATED, never implied by a missing section.
+ *
+ * A link is exactly LINK_FIELDS:
+ *   kind       'jira' | 'confluence' — which system the reference points AT. A kind marker, never a
+ *                      claim about it, and never to be styled like the panel's derived `d2-pill`.
+ *   id         'handoff_epic' | 'handoff_page' — the RECORD KEY this row came from. This is the
+ *                      row's identity for rendering; it is NOT the epic's identifier. The thing the
+ *                      PM typed is `declared`.
+ *   declared   string — the reference, verbatim and UNESCAPED. The renderer escapes.
+ *   state      'not-connected' — always, for every link, for every record.
+ *   why        string — the short clause, per system ('no Jira credential is configured').
+ *   state_text string — the full R4 sentence for the row's accessible name.
+ *   href       string|null — the value IFF it is an absolute http(s) URL (R5); else null. Byte-
+ *                      identical to `declared` when set — never normalised, never constructed.
+ *   inert_why  string|null — why this row is not a link, when href is null.
+ *
+ * A problem is exactly PROBLEM_FIELDS: { id, declared, why } — the record key (or 'record' for a
+ * caller that passed the wrong shape), the offending value verbatim (null when it was never text),
+ * and the reason, which never embeds the value.
+ */
+function readLinks(record) {
+  const problems = [];
+  const links = [];
+  let fm = {};
+
+  if (record !== null && record !== undefined) {
+    if (typeof record !== 'object' || Array.isArray(record)) {
+      problems.push({ id: 'record', declared: null,
+        why: `readLinks was given ${typeName(record)}, not the parsed frontmatter object it reads — no handoff is being claimed for this record, and that is a fault rather than an absence` });
+    } else {
+      fm = record;
+    }
+  }
+
+  const declared = HANDOFF_KEYS.filter((k) => has(fm, k));
+  const value = {};
+  for (const key of HANDOFF_KEYS) {
+    const r = readDeclared(fm, key);
+    if (!r.present) continue;
+    if (r.why) { problems.push({ id: key, declared: r.value, why: r.why }); continue; }
+    value[key] = r.value;
+  }
+
+  for (const key of REFERENCE_KEYS) {
+    const v = value[key];
+    if (v === undefined) continue;
+    const isUrl = ABSOLUTE_URL.test(v);
+    links.push({
+      kind: KIND[key],
+      id: key,
+      declared: v,
+      state: NOT_CONNECTED,
+      why: whyFor(SYSTEM[key]),
+      state_text: stateTextFor(SYSTEM[key]),
+      href: isUrl ? v : null,
+      inert_why: isUrl ? null : INERT_WHY,
+    });
+  }
+
+  return deepFreeze({
+    connected: false,
+    handoff: declared.length > 0,
+    flow: value.flow === undefined ? null : value.flow,
+    to: value.handoff_to === undefined ? null : value.handoff_to,
+    at: value.handoff_at === undefined ? null : value.handoff_at,
+    systems: REFERENCE_KEYS.filter((k) => declared.indexOf(k) !== -1).map((k) => SYSTEM[k]),
+    links,
+    problems,
+    // A `flow:` with no references is a VERIFIED EMPTY, in the panel's existing vocabulary — not a
+    // hidden section. A malformed declaration is not empty; it is red, and red wins.
+    empty: declared.length > 0 && links.length === 0 && problems.length === 0,
+  });
+}
+
+module.exports = deepFreeze({
+  readLinks,
+  HANDOFF_KEYS, REFERENCE_KEYS, LINK_FIELDS, PROBLEM_FIELDS, RESULT_FIELDS,
+  NOT_CONNECTED, INERT_WHY,
+  // Exported so the renderer states EXACTLY what this module states — a surface that rewords the
+  // not-connected sentence is a surface that can soften it.
+  whyFor, stateTextFor,
+});