create-pmos 0.29.1 → 0.30.0

package/README.md

@@ -333,6 +333,38 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.30.0
+
+**Your user stories are on the board, and a story can name the Jira issue, Confluence page or
+Google Doc it corresponds to — in the file itself. The scratchpad drags up and down.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **User stories show up on an initiative's artifacts list, in the right place.** The index has
+  recognised `*-user-stories.md` for a while and nothing downstream used it: stories sorted *below*
+  the PRD and the rubric they decompose, and the role label was twelve characters in a box built for
+  eight, so it ran under the file path beside it. Stories now sort directly after the PRD, and the
+  chip fits. A file in a `planning/stories/` folder counts as a story too, with no suffix needed in
+  its name.
+- **A story can carry its own destination.** Put `jira: ABC-123`, `confluence: SPACE / page` or
+  `google_doc: <url>` in a story's frontmatter and the workspace draws the ⇄ pill on its row — no
+  clicking, no re-typing on a second machine, and the tie is in git where an agent reading the file
+  can see it. It works for any planning document, not only stories.
+- **It says what it knows, which is nothing.** That pill reads *declared in the file · nothing has
+  been checked*. PMOS holds no credential, makes no request, and cannot mark a reference resolved —
+  only a session carrying your own MCP can do that. A link you record in the panel still wins over
+  the one in the file, and `unlink` now survives a reload instead of the file quietly putting the
+  pill back.
+- **The scratchpad resizes.** Drag the handle along its top edge — up for taller, down for shorter.
+  It cannot be dragged shut, it cannot take more than 70% of the panel (the pane above is often a
+  live terminal), the size sticks across reloads, and `↑`/`↓` work when the handle is focused with
+  `Home` to reset. Resizing never touches what you have staged in the pad.
+- **Not in this release, said plainly:** the `Story` frontmatter type, the gate rule that enforces
+  it and the `--fix` repair are PMOS-self only and are **not** in this payload. The registry they
+  enforce is PMOS's own vocabulary, and running it inside your repository would fail files written
+  to your conventions. The workspace half above works whatever `type:` your story files declare.
+  Nothing here reads status back from a tracker — there is no "3 of 7 done", and the surface does
+  not imply there is.
+
 ## What's new in 0.29.1
 
 **0.29.0 could not reach an existing install. This is that release, delivered.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.29.1",
+  "version": "0.30.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@b59909d
+kernel-source: pmos@ace75db
 assembled: 2026-08-04
 mode: vendor

package/payload/okf/core/concepts/frontmatter-format.md

@@ -57,12 +57,47 @@ The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontma
 the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
 
 - **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
-- **Planning:** `Initiative`, `PRD`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
   - `Initiative` is the repo-native initiative record in [`planning/initiatives/`](/planning/initiatives/), read by the
     [Initiative Gate](/.github/scripts/initiative-gate.sh). Its D56 **work-type lane** rides a separate `lane:` key —
     not `type:` — so the lane vocabulary and this registry never collide.
+  - `Story` is a **user-story document** — the decomposition of a spec into the units of work handed
+    to whoever builds them. It is the one type in this registry that is also **checked positionally**
+    (see below), and it may carry an optional `jira:` / `confluence:` / `google_doc:` key naming the
+    tracker record it corresponds to. That key is a *declaration* the workspace displays, never a
+    lookup: PMOS holds no credential and makes no outbound request.
 - **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
 
+### When the path decides the type
+
+Most types are the author's to choose. A few document kinds are identifiable from the path alone, and
+for those `type ∈ registry` is not enough — the gate also checks the type is the RIGHT one, because a
+file wearing a plausible wrong type passes the membership test forever.
+
+**User stories** are the first such kind. A tracked `.md` whose filename ends `-user-stories.md`,
+`-user-story.md` or `-stories.md`, **or** whose immediate parent directory is `stories/` (or
+`user-stories/`), must declare `type: Story`. These are exactly the shapes the workspace's library
+index calls a story (`ROLE_SUFFIXES` / `ROLE_BY_DIR` in `workspace/server.js`) — the board and the
+gate are held to one definition of what a story is, rather than two that can drift.
+
+The boundary is deliberately narrow: `planning/stories/archive/notes.md` is a note filed beside
+stories, not a story, and `planning/research/story-mapping.md` is research. Both directions are
+asserted in [`scripts/tests/frontmatter-story.sh`](/scripts/tests/frontmatter-story.sh).
+
+**Retroactive repair (PMOS-self — the kit does not carry this tool).** Story files written before
+`Story` existed declare something else — this repo's own test fixture declared `type: PRD`, because
+nothing else was available. `python3 scripts/frontmatter_lint.py --fix` corrects them, and
+`--root <dir>` points it at another repository so a product repo's stories can be repaired too. It
+is bounded on purpose: story files only, the `type:` key only, and it never invents a `title` or a
+`timestamp` — a story file missing those is reported rather than guessed at.
+
+The linter and this registry are **not** in the create-pmos payload, and that is a decision rather
+than an omission: the registry is *PMOS's* vocabulary, and enforcing it inside an adopter's
+repository would fail files written to their own conventions. Whose vocabulary governs an adopter's
+repo is its own question, and it deserves its own initiative. What adopters *do* get is the reading
+half — the workspace draws a story on the artifacts row and shows the destination its frontmatter
+declares, whatever `type:` the file carries.
+
 ### Extending the vocabulary
 
 Add **one line** to `scripts/frontmatter_registry.txt` and a matching row above. A new `type` is a

package/workspace/lib/four-panel.js

@@ -272,7 +272,36 @@ 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 }));
+  return hit.artifacts.map((a) => ({
+    role: a.role, name: a.name, path: a.path, title: a.title || null,
+    // The destination the document declares about ITSELF, from its frontmatter (server.js
+    // `frontmatterDest`). It is carried, not resolved — see `withFrontmatterDest` for the one rule
+    // that decides when the panel is allowed to see it.
+    dest: a.dest || null,
+  }));
+}
+
+/**
+ * Decide, per artifact, whether the file's own declared destination is the one the panel shows.
+ *
+ * THE RULE: **if the store has spoken about an artifact at all, the store owns it.** The file fills
+ * the silence, and only the silence.
+ *
+ * "At all" includes a `retracted` row, and that clause is the whole reason this function exists
+ * rather than a `||` at the call site. `unlink` appends a retraction; `linkView` then correctly
+ * reports no link. If the fallback consulted the file at that point, the pill the PM just removed
+ * would be back on the next reload and the button would be a button that undoes itself. A
+ * retraction is a decision about this artifact, so it counts as the store having spoken.
+ *
+ * The precedence direction is the other half: a row in the store is the PM's own act in a UI, made
+ * later than the file was written, against a destination they were looking at. The file is the
+ * artifact's own statement and travels with the repository. When they disagree, the later explicit
+ * act wins — and the file is left exactly as it is, because PMOS does not edit the PM's documents.
+ */
+function withFrontmatterDest(artifacts, storeRows) {
+  const spoken = new Set();
+  for (const r of storeRows || []) if (r && r.artifact_path) spoken.add(r.artifact_path);
+  return (artifacts || []).map((a) => (a.dest && spoken.has(a.path) ? { ...a, dest: null } : a));
 }
 
 /* ── sessions ───────────────────────────────────────────────────────────────────────────────── */
@@ -727,11 +756,19 @@ function lookupTask({ kind, subject, hint, profile } = {}) {
  */
 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 indexed = artifactsFor(index, id);
   const sess = sessionsFor({ sessions, workspaces, id });
   // 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) : []));
+  // …and `includeRetracted` here, because "the PM withdrew this" is the store having spoken about
+  // the artifact. See withFrontmatterDest: without it, unlink would undo itself on the next reload.
+  const spokenFor = linkView(
+    (artifactLinks && artifactLinks.ok ? artifactLinks.rows : []).filter((r) => r
+      && (r.initiative_id === id || indexed.some((a) => a.path === r.artifact_path))),
+    { includeRetracted: true },
+  );
+  const artifacts = withFrontmatterDest(indexed, spokenFor);
   return {
     ok: true,
     id,
@@ -769,7 +806,7 @@ function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor,
 module.exports = {
   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,
+  validId, connectors, readRecord, parseTasks, artifactsFor, withFrontmatterDest, sessionsFor, anchorFor,
   storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
   linkView, lookupTask, syncRow, syncView, syncTask,
 };

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "private": true,
   "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -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 external-linking.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js && node state-isolation.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 story-artifacts.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js && node state-isolation.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",

package/workspace/public/pm/data.js

@@ -332,7 +332,12 @@ function artsFor(payload) {
     sync.set(r.artifact_path + '|' + r.kind, r);
   }
   return (payload.artifacts || []).map((a) => {
-    const d = dest.get(a.path);
+    // A row in the store, else the destination the FILE declares about itself (server.js
+    // `frontmatterDest`, gated by `withFrontmatterDest` — the server has already decided which of
+    // the two the panel is allowed to see, including for an artifact whose link the PM retracted).
+    // This used to return `{role, path}` here and drop `a.dest` on the floor, even though
+    // `artifactRow` reads it as its fallback: the reader existed and the producer did not.
+    const d = dest.get(a.path) || a.dest || null;
     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 };
   });

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

@@ -679,6 +679,20 @@ function syncSummary(sy, dest) {
     + '. the task below is what performs it, and no session has reported back.';
 }
 
+/* ── the role chip's short form ───────────────────────────────────────────────────────────────
+ * The chip is a fixed 52px box — roughly eight characters of 10px mono with `.1em` tracking — and
+ * the design drew it that way. The index's canonical role for a user-story document is
+ * `user stories`, which is twelve, so it ran under the path beside it.
+ *
+ * The canonical role is NOT renamed. It is asserted as `user stories` in two suites, and it is the
+ * string the search results (`artifact · user stories`) and a document tab's label read — both
+ * places where the longer, clearer word is the right one. Only the CHIP is abbreviated, and only
+ * where a role is genuinely too long for the box the design specified. The prototype's own stories
+ * row says `STORIES`, so this is the design's word, shortened to the case the real index uses.
+ */
+const ROLE_CHIP = { 'user stories': 'stories' };
+function roleChip(role) { return ROLE_CHIP[role] || role; }
+
 function artifactRow(slug, a) {
   const key = FX.artKey(slug, a.path);
   // `hasOwnProperty`, not `||`. An unlinked artifact records `null` under its key, and a falsy check
@@ -693,7 +707,7 @@ function artifactRow(slug, a) {
     style: 'display:flex;gap:8px;align-items:center;width:100%;padding:4px 6px;margin:0 -6px;min-width:0;min-height:30px',
     hover: 'background:var(--accent)',
   },
-    el('span', { style: 'flex:none;width:52px;font-family:var(--mono);font-size:10px;letter-spacing:.1em;color:var(--info)' }, iv(a.role)),
+    el('span', { style: 'flex:none;width:52px;font-family:var(--mono);font-size:10px;letter-spacing:.1em;color:var(--info)' }, iv(roleChip(a.role))),
     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)),
   );
 
@@ -795,6 +809,16 @@ function artifactRow(slug, a) {
   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)),
+    /* WHERE THE CLAIM CAME FROM. A destination read out of the file's own frontmatter is exactly as
+     * unverified as one the PM typed — PMOS has not looked at either — but it arrived without
+     * anybody in this window doing anything, so the row has to say so or it reads as something the
+     * app established. This region already lost that argument once: its predecessor existed because
+     * a row said `connected` about a record nobody had checked. Real mode only; the prototype has
+     * no such row, and the parity comparator measures the fixture surface against it. */
+    (!FIXTURE && dest.origin === 'frontmatter')
+      ? el('span', { style: 'font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' },
+        'declared in the file · nothing has been checked')
+      : null,
     el('button', {
       onClick: () => setState((s) => ({ artSyncOpen: { ...s.artSyncOpen, [key]: !s.artSyncOpen[key] } })),
       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)',

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

@@ -361,6 +361,84 @@ const scratchTa = el('textarea', {
   onInput: (e) => onScratchInput(e.target.value),
 });
 
+/* ── the drawer's height ────────────────────────────────────────────────────────────────────
+ * 96px — four lines of the 12px mono face — was a literal in the style string above, and it was the
+ * pad's only size. The pad's job (see the block comment above) is to stage the next thing to type
+ * into a particular agent, and a staged instruction is routinely longer than four lines, so the PM
+ * composed in a box that scrolled internally while a large empty pane sat above it.
+ *
+ * The handle is REAL MODE ONLY. The parity comparator renders the app at `?fixture=proto` against
+ * the PM's own prototype and diffs text nodes, computed styles, geometry and pixels; the prototype
+ * has no such control, so drawing one in fixture mode would be a difference the comparator is right
+ * to report. This module already draws that line for the placeholder string, and for the same
+ * reason.
+ *
+ * The clamps are the two ways this could damage the surface it sits in. `SCRATCH_MIN` keeps two
+ * lines and the button row reachable — a drawer that can be dragged shut is a drawer with two
+ * different closed states, one of which has no way back. The 70% ceiling keeps the pane above from
+ * being driven to nothing, which matters more than it sounds: that pane is frequently a live PTY.
+ *
+ * NOTHING HERE TOUCHES THE PAD. Resizing does not read or write `state.scratchText`, does not call
+ * `syncPad` or `flushPad`, and cannot change `state.scratchKey`. The height is a property of the
+ * window, the text is a property of the session, and the two stores stay separate.
+ */
+const SCRATCH_MIN = 56;
+const SCRATCH_DEFAULT = 96;
+const SCRATCH_MAX_FRACTION = 0.7;
+const SCRATCH_STEP = 16;
+
+/** The tallest the pad may be right now: 70% of panel 4, never below the minimum. */
+function scratchMax() {
+  const host = scratchBlock && scratchBlock.parentElement;
+  const h = host && host.clientHeight ? host.clientHeight : 0;
+  // No host to measure (the drawer is not mounted yet) — fall back to the viewport, and to a plain
+  // number if there is no window either, so this is safe to call from a test harness.
+  const basis = h || (typeof window !== 'undefined' && window.innerHeight) || 600;
+  return Math.max(SCRATCH_MIN, Math.round(basis * SCRATCH_MAX_FRACTION));
+}
+
+export function clampScratchH(v) {
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return SCRATCH_DEFAULT;
+  return Math.min(scratchMax(), Math.max(SCRATCH_MIN, n));
+}
+
+function setScratchH(v) {
+  const h = clampScratchH(v);
+  if (h === state.scratchH) return;
+  setState({ scratchH: h });
+}
+
+let dragFrom = null;      // {y, h} while the handle is held; null otherwise
+
+const scratchGrip = el('div', {
+  tabindex: '0',
+  role: 'separator',
+  'aria-orientation': 'horizontal',
+  'aria-label': 'resize the scratchpad — drag, or ↑ / ↓',
+  title: 'drag to resize · ↑ / ↓ to nudge · double-click to reset',
+  style: 'flex:none;height:7px;cursor:ns-resize;background:oklch(0.11 0.004 228.8);'
+    + 'border-top:1px solid oklch(1 0 0 / 10%);touch-action:none',
+  hover: 'background:oklch(1 0 0 / 10%)',
+  onPointerdown: (e) => {
+    dragFrom = { y: e.clientY, h: state.scratchH || SCRATCH_DEFAULT };
+    try { e.target.setPointerCapture(e.pointerId); } catch { /* not captured — the move still works */ }
+    e.preventDefault();
+  },
+  // Up is taller: the drawer grows toward the top edge the PM is pulling, which is the direction
+  // the handle itself moves. `clientY` decreases as the pointer rises, hence `from.y - clientY`.
+  onPointermove: (e) => { if (dragFrom) setScratchH(dragFrom.h + (dragFrom.y - e.clientY)); },
+  onPointerup: () => { dragFrom = null; },
+  onPointercancel: () => { dragFrom = null; },
+  onDblclick: () => setScratchH(SCRATCH_DEFAULT),
+  onKeydown: (e) => {
+    const h = state.scratchH || SCRATCH_DEFAULT;
+    if (e.key === 'ArrowUp') { setScratchH(h + SCRATCH_STEP); e.preventDefault(); }
+    else if (e.key === 'ArrowDown') { setScratchH(h - SCRATCH_STEP); e.preventDefault(); }
+    else if (e.key === 'Home') { setScratchH(SCRATCH_DEFAULT); e.preventDefault(); }
+  },
+});
+
 /* ── pad identity, loading and autosave ─────────────────────────────────────────────────────── */
 
 const padLoading = new Set();      // keys with a read in flight — one read per key, ever
@@ -467,6 +545,7 @@ const scratchSendBtn = el('button', {
 const scratchBlock = el('div', {
   style: 'display:flex;flex-direction:column;border-top:1px solid oklch(1 0 0 / 10%)',
 },
+  FIXTURE ? null : scratchGrip,
   scratchTa,
   el('div', { style: 'display:flex;gap:6px;padding:5px 12px 7px;background:oklch(0.11 0.004 228.8)' },
     scratchCopyBtn, scratchSendBtn),
@@ -814,6 +893,14 @@ export function renderTabs(host) {
   const scratchText = state.scratchText || '';
   if (scratchTa.defaultValue !== scratchText) scratchTa.defaultValue = scratchText;
   if (scratchTa.value !== scratchText) scratchTa.value = scratchText;
+  /* The drawer's height, real mode only. The style ATTRIBUTE keeps the prototype's string; only the
+   * resolved `height` property is written, so the fixture render — which never reaches here — stays
+   * byte-identical to the design. Written on every paint rather than only on resize, because the
+   * restored value has to land on the first one. */
+  if (!FIXTURE) {
+    const h = clampScratchH(state.scratchH || SCRATCH_DEFAULT) + 'px';
+    if (scratchTa.style.height !== h) scratchTa.style.height = h;
+  }
   scratchCopyLabel.textContent = state.scratchCopied ? 'copied ✓' : '⧉ copy';
   const canSend = !!(act && act.kind === 'term');
   scratchSendLabel.textContent = canSend ? '⇥ send to terminal' : 'open a terminal to send';

package/workspace/public/pm/state.js

@@ -88,6 +88,10 @@ function initial() {
     newSessIsolate: null, newSessError: null, newSessBusy: false,
     newSessBranches: null, preflightProfile: null, profiles: null, branchInfo: null,
     col0: true, col1: true, col2: true, scratchOpen: false, scratchText: '', copied: false,
+    /* The scratchpad drawer's height in px (panel-tabs.js). 96 is the prototype's literal and stays
+     * the default; the PM can drag it, and the drag is clamped there rather than here — this store
+     * only has to refuse a value that could not have come from the clamp. */
+    scratchH: 96,
     flowsMap: null, schedList: null, agentList: null, memory: null,
     savedDocs: {}, scratchCopied: false,
     /* The scratchpad is ONE PAD PER SESSION, not one per page (see panel-tabs.js). `scratchPads`
@@ -169,6 +173,12 @@ const PERSIST = {
   active: isSlug,
   splitId: isSlug,
   scratchOpen: isBool,
+  /* A restored height is re-validated on the way IN, not merely on the way out: a corrupted or
+   * hand-edited record must not be able to render a drawer with no textarea in it, or one taller
+   * than any window it could be restored into. The upper bound here is deliberately generous (the
+   * real ceiling is 70% of panel 4, which this module cannot measure) — panel-tabs.js clamps the
+   * value again against the live panel before it reaches the DOM. */
+  scratchH: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 56 && v <= 4000,
 };
 
 /** What is WRITTEN for a key, when it is not the live value verbatim. */

package/workspace/server.js

@@ -1051,6 +1051,11 @@ const ROLE_BY_DIR = {
   // the only artifact that exists for work backfilled from a merge. Before it was a role, a record
   // with no sibling PRD landed in `ungrouped` and the initiative was invisible here.
   initiatives: 'record',
+  // A story file that does NOT wear one of the suffixes above — `planning/stories/checkout.md` —
+  // was role `doc` and therefore indistinguishable from a stray note. These two directory names are
+  // the same set `scripts/frontmatter_lint.py` holds to `type: Story`; the board and the gate are
+  // deliberately one definition of what a story is.
+  stories: 'user stories', 'user-stories': 'user stories',
 };
 // ── D60 specimens: prototype/<id>/, deliberately OUTSIDE planning/ ───────────────────────────
 // The planning walk cannot reach them (planningRoots only finds `planning`), so a prototype leg was
@@ -1120,8 +1125,44 @@ function parseHead(full) {
     recordId: rid ? rid[1] : null,
     title: h1 ? h1[1].replace(/^(PRD|Eval Rubric|Design Brief)\s*:\s*/i, '').trim() : null,
     kr: clean(kr), lane: clean(lane),
+    dest: frontmatterDest(head),
   };
 }
+
+/* ── the destination a document declares about ITSELF ────────────────────────────────────────
+ * A user story is written to be handed to a tracker, and until now the only place that tie could
+ * live was `artifact-links.jsonl` in the workspace's runtime state directory — outside the
+ * repository, invisible to git, invisible to an agent reading the file, and absent on every other
+ * machine that opens the same repo. A key in the file's own frontmatter puts the fact where the
+ * artifact is.
+ *
+ * IT IS A DECLARATION AND NOTHING MORE. This is the same claim `state: 'declared'` makes in the
+ * store: the author says this file corresponds to that record. PMOS has not looked, holds no
+ * credential, and makes no request — only a session carrying the PM's own MCP can produce
+ * `resolved` (D53), and nothing on this path can. The panel attributes the row to the file so the
+ * two are never confused, which is the whole lesson of the predecessor initiative: a row that said
+ * `connected` about a record nobody had checked.
+ *
+ * ONE destination, in LINK_KINDS order, because the artifact row draws one pill. A file declaring
+ * two has declared the first; that is a smaller surprise than silently drawing the second.
+ * The target is capped at 300 characters — the same cap the store's own validator applies to a
+ * typed one — and is rendered as text, never as a link target.
+ */
+const FRONTMATTER_DEST = [
+  ['jira', /^\s*[-*]?\s*jira\s*:\s*(.+?)\s*$/mi],
+  ['confluence', /^\s*[-*]?\s*confluence\s*:\s*(.+?)\s*$/mi],
+  ['google', /^\s*[-*]?\s*(?:google_doc|google-doc|gdoc)\s*:\s*(.+?)\s*$/mi],
+];
+function frontmatterDest(head) {
+  for (const [kind, re] of FRONTMATTER_DEST) {
+    const m = String(head || '').match(re);
+    if (!m) continue;
+    const target = m[1].replace(/^["']|["']$/g, '').trim().slice(0, 300);
+    if (!target) continue;
+    return { kind, target, origin: 'frontmatter', state: 'declared' };
+  }
+  return null;
+}
 function roleAndStem(rel, base) {
   const stem = base.replace(/\.md$/, '');
   for (const [suf, role] of ROLE_SUFFIXES) {
@@ -1145,6 +1186,7 @@ function docMeta(root, full) {
     initiative: head.initiative || (role === 'record' ? head.recordId : null) || null,
     stem, title: head.title || null,
     kr: head.kr || null, lane: head.lane || null,
+    dest: head.dest || null,
   };
   metaCache.set(full, meta);
   return meta;
@@ -1230,7 +1272,7 @@ function initiativeIndex(root) {
   };
   for (const m of metas) {
     const k = keyFor(m);
-    const art = { name: m.name, path: m.path, role: m.role, title: m.title };
+    const art = { name: m.name, path: m.path, role: m.role, title: m.title, dest: m.dest || null };
     if (!k) { ungrouped.push(art); continue; }
     if (!groups.has(k)) groups.set(k, { id: k, title: null, kr: null, lane: null, artifacts: [] });
     const g = groups.get(k);
@@ -1242,7 +1284,11 @@ function initiativeIndex(root) {
     if (m.kr && (m.role === 'record' || !g.kr)) g.kr = m.kr;
     if (m.lane && (m.role === 'record' || !g.lane)) g.lane = m.lane;
   }
-  const ROLE_ORDER = ['record', 'PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
+  // `user stories` sits directly after `PRD` because that is what it IS: the spec decomposed into
+  // the units of work someone builds. It was absent from this list, so `indexOf` returned -1, the
+  // comparator mapped it to 99, and an initiative's stories sorted below every artifact they
+  // decompose — into the trailing alphabetical block with `doc` and `research`.
+  const ROLE_ORDER = ['record', 'PRD', 'user stories', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
   const initiatives = [...groups.values()].map((g) => {
     g.artifacts.sort((a, b) => {
       const ia = ROLE_ORDER.indexOf(a.role), ib = ROLE_ORDER.indexOf(b.role);
@@ -1468,7 +1514,7 @@ function surfaceInitiatives(root, w) {
       accepted: state === 'accepted',
       delivered: state === 'accepted' || state === 'delivered',
       delivery_evidence: deliveredBy,
-      artifacts: g.artifacts.map((a2) => ({ role: a2.role, name: a2.name, path: a2.path })),
+      artifacts: g.artifacts.map((a2) => ({ role: a2.role, name: a2.name, path: a2.path, dest: a2.dest || null })),
       // NET-NEW state — not on disk yet, so null (the surface renders "— not tracked", never a guess)
       rice: null, effort: null, milestones: null, progress: null, tracked: false,
     };