create-pmos 0.29.1 → 0.30.1

package/README.md

@@ -333,6 +333,67 @@ 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.1
+
+**Open a markdown file in the workspace and you get the document, not its source. And scrolling
+down stays scrolled down.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **The document pane renders markdown properly.** Bold was asterisks, inline code was backticks, a
+  table was one paragraph per row with the pipes still in it, and a numbered procedure was a single
+  run-on paragraph. An indented sub-bullet was worse than unstyled — it escaped the list it belonged
+  inside and reappeared underneath it. `view` now renders headings 1–6, soft-wrapped paragraphs,
+  ordered / nested / task lists, GFM tables with per-column alignment, fenced code, blockquotes and
+  rules, plus bold, italic, inline code, strikethrough, links and images. Rubrics and skills — the
+  documents this workflow is written in — are readable in the pane for the first time.
+- **A `.md` link opens that document.** Click a link to another file in your repo and it opens as a
+  tab, resolved against the document you are reading (or the repo root for a `/planning/…` path). A
+  link to something the pane cannot open stays as plain text rather than becoming a dead link.
+- **Nothing is fetched because you opened a file.** A repo-relative image is streamed by your own
+  local workspace; a remote or `data:` image stays as its alt text and is never requested. The
+  renderer builds DOM nodes and never assigns HTML, so a `<script>` in a markdown file is characters
+  on the screen, not a script.
+- **Scrolling a document survives a repaint.** The pane rebuilt its scrolling element on every
+  redraw, so anything that changed state anywhere — including the four-second session poll, which
+  fires whenever an agent beside you is working — took a half-read document back to line 1. The
+  scroll element is now kept, per tab and per mode, the same way the edit box keeps your caret.
+  Holds for `view`, `raw` and `diff`.
+- **Not in this release, said plainly:** this is a workspace-app fix. The file-mode kit — skills,
+  scripts, state layout — is unchanged, so `--update` has nothing new to give you. Syntax
+  highlighting inside code fences, footnotes and rendered inline HTML are deliberately not included.
+
+## 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.1",
   "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
-assembled: 2026-08-04
+kernel-source: pmos@f5b480a
+assembled: 2026-08-05
 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.1",
   "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 markdown.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/markdown.js

@@ -0,0 +1,420 @@
+/* pm/markdown.js — the doc pane's markdown renderer.
+ *
+ * The doc tab's `view` mode used to render through `fixture.js`'s `mdParse`, which is a
+ * TRANSCRIPTION of the design prototype's parser — four branches (`# `, `## `, `- `, paragraph) and
+ * no inline pass at all. That is exactly big enough for the prototype's four seed documents and
+ * nowhere near big enough for this repository's own artifacts: a rubric IS a GFM table, a skill IS a
+ * numbered procedure, and both reached the PM as literal source with the pipes and the asterisks
+ * still in them. See planning/explainers/workspace-doc-render-surface-explainer.md.
+ *
+ * `mdParse` is not touched — `fixture-parity.test.mjs` pins it byte-for-byte against the prototype
+ * source, and that transcription proof is the reason the design comparator can be trusted. This is a
+ * separate renderer, and `tab-doc.js` chooses it for `view`.
+ *
+ * ── THE PARITY CONTRACT ────────────────────────────────────────────────────────────────────────
+ * The fixture documents contain only `#`, `##`, `- ` and paragraphs, and `design-parity.js` diffs
+ * the app against the prototype on text nodes, computed style, geometry and pixels. So for those
+ * four constructs this renderer emits NODE-FOR-NODE what the old path emitted, including the
+ * wrapping <span> that `iv()` put around unmarked text: an inline run with no markup in it comes
+ * back as exactly one span holding the whole run. A failed marker match does NOT flush the text
+ * buffer — `planning/initiatives/*.md` is one span, not three.
+ *
+ * ── WHAT IT NEVER DOES ─────────────────────────────────────────────────────────────────────────
+ * It builds DOM NODES. No HTML string is constructed anywhere in this file and `innerHTML` is never
+ * assigned, so a `<script>` line in a document is a `<script>` on the screen, as characters, by
+ * construction rather than by remembering to escape (DOC7). And an image is fetched only when it is
+ * repo-relative, through the guarded /api/asset — a remote or `data:` source stays alt text and is
+ * never requested, which is R4: opening a document must not tell anyone it was opened.
+ */
+
+import { el } from './dom.js';
+
+/* ── styles ─────────────────────────────────────────────────────────────────────────────────────
+ * H2, P, UL and LI are the prototype's strings, verbatim, and must stay that way — they are what
+ * the parity diff measures. Everything below them is new surface, styled in the same idiom: the
+ * semantic tokens only, no raw colour anywhere. */
+const ST = {
+  h1: 'font-size:19px;font-weight:600;line-height:1.3;margin:26px 0 10px;text-wrap:balance;font-family:var(--sans)',
+  h2: 'font-size:16px;font-weight:600;line-height:1.35;margin:24px 0 8px;padding-bottom:5px;border-bottom:1px solid var(--border)',
+  h3: 'font-size:14px;font-weight:600;line-height:1.4;margin:20px 0 7px',
+  h4: 'font-size:13px;font-weight:600;line-height:1.4;margin:18px 0 6px',
+  h5: 'font-size:12.5px;font-weight:600;line-height:1.4;margin:16px 0 6px;color:var(--muted-foreground)',
+  h6: 'font-size:12px;font-weight:600;line-height:1.4;margin:16px 0 6px;color:var(--muted-foreground);text-transform:uppercase;letter-spacing:0.04em',
+  p: 'margin:0 0 12px',
+  ul: 'margin:0 0 12px;padding-left:22px',
+  ol: 'margin:0 0 12px;padding-left:24px',
+  subList: 'margin:5px 0 0;padding-left:22px',
+  li: 'margin:0 0 5px;padding-left:2px',
+  taskUl: 'margin:0 0 12px;padding-left:2px;list-style:none',
+  taskLi: 'margin:0 0 5px;display:flex;gap:8px;align-items:baseline',
+  box: 'font-family:var(--mono);font-size:12px;color:var(--muted-foreground);flex:none',
+  boxDone: 'font-family:var(--mono);font-size:12px;color:var(--success);flex:none',
+  code: 'font-family:var(--mono);font-size:0.88em;background:var(--muted);padding:1px 4px;overflow-wrap:anywhere',
+  pre: 'margin:0 0 14px;background:var(--card);border:1px solid var(--border);padding:10px 12px;overflow-x:auto',
+  preCode: 'font-family:var(--mono);font-size:12px;line-height:1.6;white-space:pre;display:block',
+  lang: 'display:block;font-family:var(--mono);font-size:10px;color:var(--muted-foreground);margin-bottom:6px;letter-spacing:0.04em',
+  quote: 'margin:0 0 14px;padding:2px 0 2px 14px;border-left:2px solid var(--border);color:var(--muted-foreground)',
+  hr: 'border:0;border-top:1px solid var(--border);margin:22px 0',
+  tableWrap: 'margin:0 0 14px;overflow-x:auto;border:1px solid var(--border)',
+  table: 'border-collapse:collapse;width:100%;font-size:12.5px',
+  th: 'font-weight:600;padding:7px 10px;border-bottom:1px solid var(--border);background:var(--card);vertical-align:top',
+  td: 'padding:7px 10px;border-bottom:1px solid var(--border);vertical-align:top',
+  a: 'color:var(--brand);text-decoration:underline;text-underline-offset:2px;overflow-wrap:anywhere',
+  img: 'max-width:100%;height:auto;display:block;margin:0 0 14px;border:1px solid var(--border)',
+  imgAlt: 'color:var(--muted-foreground)',
+};
+
+const HEAD_ST = [ST.h1, ST.h2, ST.h3, ST.h4, ST.h5, ST.h6];
+
+/* ── inline ─────────────────────────────────────────────────────────────────────────────────── */
+
+const RE = {
+  code: /^(`+)([\s\S]*?[^`])\1(?!`)/,
+  image: /^!\[([^\]]*)\]\(\s*([^)\s]*)(?:\s+"[^"]*")?\s*\)/,
+  link: /^\[([^\]]+)\]\(\s*([^)\s]*)(?:\s+"[^"]*")?\s*\)/,
+  autolink: /^<((?:https?:\/\/|mailto:)[^>\s]+)>/,
+  strongStar: /^\*\*(?=\S)([\s\S]*?\S)\*\*/,
+  strongUnder: /^__(?=\S)([\s\S]*?\S)__/,
+  emStar: /^\*(?=[^\s*])((?:[^*]|\*\*)+?)\*(?!\*)/,
+  emUnder: /^_(?=[^\s_])([^_]+?)_(?!\w)/,
+  del: /^~~(?=\S)([\s\S]*?\S)~~/,
+};
+
+const isWord = (c) => !!c && /[A-Za-z0-9]/.test(c);
+
+/**
+ * One line (or cell) of markdown → an array of DOM nodes.
+ *
+ * The scan is left-to-right and a marker that does not resolve is just a character: the plain-text
+ * buffer is flushed ONLY when a real node is emitted, which is what keeps an unmarked run a single
+ * text span (the parity contract) and what keeps `a/*.md` and `pre_run_contract` intact.
+ */
+export function inline(src, ctx = {}) {
+  const s = String(src == null ? '' : src);
+  const out = [];
+  let buf = '';
+  const flush = () => { if (buf) { out.push(el('span', null, buf)); buf = ''; } };
+  const push = (node) => { flush(); out.push(node); };
+
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    // Nothing can start here — the common case, and the reason a plain paragraph stays one span.
+    if (c !== '`' && c !== '[' && c !== '!' && c !== '*' && c !== '_' && c !== '~' && c !== '<') {
+      buf += c; i++; continue;
+    }
+    const rest = s.slice(i);
+    const prev = i > 0 ? s[i - 1] : '';
+    let m;
+
+    if (c === '`' && (m = RE.code.exec(rest))) {
+      push(el('code', { style: ST.code }, m[2].replace(/^ (.*) $/, '$1')));
+      i += m[0].length; continue;
+    }
+    if (c === '!' && (m = RE.image.exec(rest))) {
+      push(mdImage(m[1], m[2], ctx));
+      i += m[0].length; continue;
+    }
+    if (c === '[' && (m = RE.link.exec(rest))) {
+      const node = mdLink(m[1], m[2], ctx);
+      if (node) { push(node); i += m[0].length; continue; }
+      // A target that cannot be opened is not offered as a link — its TEXT stays, in the buffer,
+      // so it does not fragment the run around it.
+      buf += m[1]; i += m[0].length; continue;
+    }
+    if (c === '<' && (m = RE.autolink.exec(rest))) {
+      push(mdLink(m[1], m[1], ctx) || el('span', null, m[1]));
+      i += m[0].length; continue;
+    }
+    if (c === '~' && (m = RE.del.exec(rest))) {
+      push(el('del', null, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    if (c === '*' && (m = RE.strongStar.exec(rest))) {
+      push(el('strong', { style: 'font-weight:600' }, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    /* `__` and `_` are word-boundary-only, deliberately. Intraword underscores are how this
+     * repository writes `pre_run_contract` and `parent_kr`, and a renderer that italicised the
+     * middle of them would be a new defect shipped with the fix for an old one. */
+    if (c === '_' && !isWord(prev) && (m = RE.strongUnder.exec(rest))) {
+      const after = s[i + m[0].length];
+      if (!isWord(after)) { push(el('strong', { style: 'font-weight:600' }, inline(m[1], ctx))); i += m[0].length; continue; }
+    }
+    if (c === '*' && !isWord(prev) && (m = RE.emStar.exec(rest))) {
+      push(el('em', null, inline(m[1], ctx)));
+      i += m[0].length; continue;
+    }
+    if (c === '_' && !isWord(prev) && (m = RE.emUnder.exec(rest))) {
+      const after = s[i + m[0].length];
+      if (!isWord(after)) { push(el('em', null, inline(m[1], ctx))); i += m[0].length; continue; }
+    }
+    buf += c; i++;                       // a marker that resolved to nothing is just a character
+  }
+  flush();
+  return out.length ? out : [el('span', null, '')];
+}
+
+/** bundle-relative (`/planning/…`, the OKF convention) or relative to the open document. */
+export function resolvePath(dir, u) {
+  const clean = String(u || '').split('#')[0].split('?')[0];
+  const stack = clean.startsWith('/') ? [] : [...(dir || [])];
+  for (const p of clean.split('/')) {
+    if (!p || p === '.') continue;
+    if (p === '..') stack.pop(); else stack.push(p);
+  }
+  return stack.join('/');
+}
+
+const REMOTE = /^(?:https?:)?\/\//i;
+const MAILTO = /^mailto:/i;
+/* Every extension `previewKind` calls a document, plus the JSONL ledgers panel 3 links to. A link
+ * to something the doc tab cannot open is not made clickable — a dead link is worse than text. */
+const OPENABLE = /\.(md|markdown|mdown|mkd|mdx|skill|txt|json|jsonl|ya?ml|toml|csv|js|mjs|cjs|ts|tsx|py|sh|css|html?)(#.*)?$/i;
+
+function mdLink(txt, url, ctx) {
+  const u = String(url || '').trim();
+  if (!u) return null;
+  if (REMOTE.test(u) || MAILTO.test(u)) {
+    return el('a', {
+      href: u, target: '_blank', rel: 'noopener noreferrer', style: ST.a,
+    }, inline(txt, ctx));
+  }
+  if (u.startsWith('#')) return null;                 // an in-page anchor has nowhere to go here
+  if (!OPENABLE.test(u)) return null;
+  const path = resolvePath(ctx.dir, u);
+  if (!path || !ctx.onDoc) return null;
+  /* Opening a document from inside a document is the one navigation affordance the retired reader
+   * column had and the doc tab never got. `href="#"` keeps it a real link for the keyboard; the
+   * click never navigates the shell. */
+  return el('a', {
+    href: '#', style: ST.a, title: path,
+    onClick: (e) => { e.preventDefault(); ctx.onDoc(path); },
+  }, inline(txt, ctx));
+}
+
+/**
+ * R4, the no-beacon invariant. A repo-relative source is streamed by the workspace's own guarded
+ * /api/asset; ANYTHING else — remote, protocol-relative, data:, any scheme — is never fetched and
+ * renders as its alt text. The classifier is `preview-kind.js`'s, the one both sides of the app
+ * already share, so "what counts as repo-relative" cannot drift; if it did not load, nothing is
+ * fetched at all.
+ */
+function mdImage(alt, src, ctx) {
+  const label = alt || 'image';
+  const PK = typeof window !== 'undefined' ? window.PreviewKind : null;
+  const repoRel = PK && typeof PK.isRepoRelativeSrc === 'function' ? PK.isRepoRelativeSrc(src) : false;
+  const path = repoRel ? resolvePath(ctx.dir, src) : '';
+  if (!path) return el('em', { style: ST.imgAlt }, label);
+  return el('img', {
+    style: ST.img, alt: label, loading: 'lazy',
+    src: '/api/asset?ws=' + encodeURIComponent(ctx.ws || '') + '&path=' + encodeURIComponent(path),
+  });
+}
+
+/* ── blocks ─────────────────────────────────────────────────────────────────────────────────── */
+
+const RE_ITEM = /^(\s*)([-*+]|\d{1,9}[.)])\s+(.*)$/;
+const RE_HR = /^\s{0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+const RE_HEAD = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const RE_FENCE = /^\s*(`{3,}|~{3,})\s*([^\s`]*)/;
+const RE_QUOTE = /^\s{0,3}>/;
+const RE_TASK = /^\[([ xX])\]\s+(.*)$/;
+const RE_DELIM = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
+
+const cells = (row) => String(row).trim().replace(/^\|/, '').replace(/\|$/, '').split(/(?<!\\)\|/)
+  .map((c) => c.trim().replace(/\\\|/g, '|'));
+
+const isTableAt = (lines, i) => lines[i].includes('|')
+  && RE_DELIM.test(lines[i + 1] || '') && (lines[i + 1] || '').includes('-');
+
+/** Frontmatter → `[{k, v}]`, exactly as the pane has always read it. */
+function frontmatter(lines) {
+  const fm = [];
+  if (lines[0] !== '---') return { fm, next: 0 };
+  let i = 1;
+  while (i < lines.length && lines[i] !== '---') {
+    const ix = lines[i].indexOf(':');
+    if (ix > 0) fm.push({ k: lines[i].slice(0, ix).trim(), v: lines[i].slice(ix + 1).trim() });
+    i++;
+  }
+  return { fm, next: i + 1 };
+}
+
+/**
+ * The document → `{ fm, title, titleText, blocks }`.
+ *
+ * `title` is the inline nodes of the FIRST `# ` line — the pane draws it as the document's heading,
+ * the way it always has. A second `# ` is a real h1 in the body rather than silently replacing the
+ * title, which is what the old parser did (last one wins, the earlier ones vanish).
+ *
+ * `ctx` carries what links and images need: `{ dir, ws, onDoc }`.
+ */
+export function mdRender(text, ctx = {}) {
+  const lines = String(text == null ? '' : text).replace(/\r\n?/g, '\n').split('\n');
+  const { fm, next } = frontmatter(lines);
+  const blocks = [];
+  let title = null, titleText = '';
+  let i = next;
+
+  while (i < lines.length) {
+    const ln = lines[i];
+    if (!ln.trim()) { i++; continue; }
+    let m;
+
+    // fenced code — verbatim, never parsed, and an unterminated fence takes the rest of the file
+    if ((m = RE_FENCE.exec(ln))) {
+      const close = new RegExp('^\\s*' + m[1][0] + '{' + m[1].length + ',}\\s*$');
+      const body = [];
+      i++;
+      while (i < lines.length && !close.test(lines[i])) body.push(lines[i++]);
+      i++;
+      blocks.push(el('pre', { style: ST.pre },
+        m[2] ? el('span', { style: ST.lang }, m[2]) : null,
+        el('code', { style: ST.preCode }, body.join('\n'))));
+      continue;
+    }
+
+    if ((m = RE_HEAD.exec(ln))) {
+      const n = m[1].length;
+      const nodes = inline(m[2], ctx);
+      if (n === 1 && title === null) { title = nodes; titleText = m[2]; }
+      else blocks.push(el('h' + n, { style: HEAD_ST[n - 1] }, nodes));
+      i++; continue;
+    }
+
+    if (RE_HR.test(ln)) { blocks.push(el('hr', { style: ST.hr })); i++; continue; }
+
+    // blockquote — its body is markdown, so it is rendered by the same pass
+    if (RE_QUOTE.test(ln)) {
+      const body = [];
+      while (i < lines.length && (RE_QUOTE.test(lines[i])
+        || (body.length && lines[i].trim() && !RE_ITEM.test(lines[i]) && !RE_HEAD.test(lines[i])))) {
+        body.push(lines[i].replace(/^\s{0,3}>\s?/, '')); i++;
+      }
+      const inner = mdRender(body.join('\n'), ctx);
+      blocks.push(el('blockquote', { style: ST.quote },
+        inner.title ? el('h3', { style: ST.h3 }, inner.title) : null, inner.blocks));
+      continue;
+    }
+
+    // GFM table: a header row followed by a delimiter row
+    if (isTableAt(lines, i)) {
+      const head = cells(ln);
+      const align = cells(lines[i + 1]).map((c) => (/^:.*:$/.test(c) ? 'center' : /:$/.test(c) ? 'right' : /^:/.test(c) ? 'left' : ''));
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim()) rows.push(cells(lines[i++]));
+      // Written for every column, not only the aligned ones: a `text-align` that is present on some
+      // cells and inherited on others is how a column silently follows its neighbour's alignment.
+      const al = (n) => ';text-align:' + (align[n] || 'left');
+      blocks.push(el('div', { style: ST.tableWrap },
+        el('table', { style: ST.table },
+          el('thead', null, el('tr', null,
+            head.map((c, n) => el('th', { style: ST.th + al(n) }, inline(c, ctx))))),
+          el('tbody', null, rows.map((r) => el('tr', null,
+            head.map((_, n) => el('td', { style: ST.td + al(n) }, inline(r[n] || '', ctx)))))))));
+      continue;
+    }
+
+    if (RE_ITEM.test(ln)) {
+      const { items, next: after } = listBlock(lines, i);
+      blocks.push(renderLists(items, 0, ctx, true).node);
+      i = after; continue;
+    }
+
+    /* paragraph — consecutive lines are ONE paragraph. The join is what makes a soft-wrapped
+     * sentence read as a sentence; the guards are what stop it swallowing the block that follows. */
+    const para = [];
+    while (i < lines.length && lines[i].trim() && !RE_ITEM.test(lines[i]) && !RE_HR.test(lines[i])
+      && !RE_QUOTE.test(lines[i]) && !RE_HEAD.test(lines[i]) && !RE_FENCE.test(lines[i])
+      && !isTableAt(lines, i)) {
+      para.push(lines[i]); i++;
+    }
+    if (para.length) blocks.push(el('p', { style: ST.p }, inline(para.join(' '), ctx)));
+    else i++;                             // nothing consumed — never spin
+  }
+
+  return { fm, title, titleText, blocks };
+}
+
+/** Collect one list block: its items, their indents, and their wrapped continuation lines. */
+function listBlock(lines, start) {
+  const items = [];
+  let i = start;
+  while (i < lines.length) {
+    const ln = lines[i];
+    const m = RE_ITEM.exec(ln);
+    if (m) {
+      items.push({ indent: m[1].replace(/\t/g, '    ').length, ordered: /\d/.test(m[2]), lines: [m[3]] });
+      i++; continue;
+    }
+    if (!ln.trim()) {
+      const nx = lines[i + 1] || '';
+      if (RE_ITEM.test(nx) || /^\s{2,}\S/.test(nx)) { i++; continue; }    // a loose list
+      break;
+    }
+    /* A fence indented under an item ENDS the list rather than being folded into the item's text.
+     * PMOS's own PRDs write a numbered step and then indent a block of output under it; joining
+     * those lines into the item would put the ``` markers on screen as characters — the exact
+     * defect this renderer exists to remove. The fence then renders as its own block, after the
+     * list: degraded placement, never degraded content. */
+    if (RE_FENCE.test(ln)) break;
+    if (items.length && /^\s+\S/.test(ln)) { items[items.length - 1].lines.push(ln.trim()); i++; continue; }
+    break;
+  }
+  return { items, next: i };
+}
+
+/** Every list at one indent level, as siblings. Returns one node when there is only one list. */
+function renderLists(items, start, ctx, top) {
+  const base = items[start].indent;
+  const nodes = [];
+  let i = start;
+  while (i < items.length && items[i].indent >= base) {
+    const r = renderList(items, i, ctx, top);
+    nodes.push(r.node);
+    if (r.next === i) break;                                             // never spin
+    i = r.next;
+  }
+  return { node: nodes.length === 1 ? nodes[0] : el('div', null, nodes), next: i };
+}
+
+/**
+ * One list. A change of marker type at the same indent — bullet ↔ number, or the first `- [ ]` —
+ * starts a sibling list, the way every markdown renderer does it. A deeper indent is nested INSIDE
+ * the item above it, which is the case the old parser got visibly wrong: an indented sub-bullet did
+ * not match `- `, fell through to the paragraph branch, and was emitted after the list it belonged
+ * inside.
+ */
+function renderList(items, start, ctx, top) {
+  const base = items[start].indent;
+  const { ordered } = items[start];
+  const task = RE_TASK.test(items[start].lines[0]);
+  const lis = [];
+  let i = start;
+  while (i < items.length && items[i].indent >= base) {
+    if (items[i].indent === base
+      && (items[i].ordered !== ordered || RE_TASK.test(items[i].lines[0]) !== task)) break;
+    if (items[i].indent > base) {
+      const sub = renderLists(items, i, ctx, false);
+      if (lis.length) lis[lis.length - 1].appendChild(sub.node);
+      else lis.push(el('li', { style: ST.li }, sub.node));
+      i = sub.next; continue;
+    }
+    const body = items[i].lines.join(' ');
+    const t = RE_TASK.exec(body);
+    if (t) {
+      lis.push(el('li', { style: ST.taskLi },
+        el('span', { style: t[1] === ' ' ? ST.box : ST.boxDone, 'aria-hidden': 'true' }, t[1] === ' ' ? '☐' : '☑'),
+        el('span', null, inline(t[2], ctx))));
+    } else {
+      lis.push(el('li', { style: ST.li }, inline(body, ctx)));
+    }
+    i++;
+  }
+  const style = task ? ST.taskUl : (ordered ? ST.ol : (top ? ST.ul : ST.subList));
+  return { node: el(ordered ? 'ol' : 'ul', { style }, lis), next: i };
+}
+
+export default mdRender;

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/public/pm/tab-doc.js

@@ -22,11 +22,24 @@
  * Every keystroke is a state change, and a state change repaints the panel. A textarea rebuilt on
  * each keystroke loses the caret, so the element is created once per tab and kept; its text is
  * written back only when it actually differs from what the box already holds.
+ *
+ * ── …and why the SCROLLING ELEMENT does too ─────────────────────────────────────────────────
+ * A scroll offset is the same class of state as a caret, and it was not getting the same treatment:
+ * `view`, `raw` and `diff` each built a fresh scrolling div on every paint, so any repaint — the
+ * 4-second session poll included — took a half-read document back to the top. `scrollPane` keeps one
+ * element per tab and mode; see the block comment above it.
+ *
+ * ── What `view` renders it through ──────────────────────────────────────────────────────────
+ * `markdown.js`, not `fixture.js`'s `mdParse`. The latter is a transcription of the design
+ * prototype's four-branch stand-in (`# `/`## `/`- `/paragraph) pinned byte-for-byte by
+ * `fixture-parity.test.mjs`; it stays exactly as it is, and it is not a markdown renderer.
  */
 
 import { el, setChildren } from './dom.js';
 import { state, setState, FIXTURE } from './state.js';
 import * as FX from './fixture.js';
+import { mdRender } from './markdown.js';
+import { openDoc } from './panel-initiatives.js';
 
 /** `{{ expr }}` — one interpolated value in its own span, as the prototype's runtime emits it. */
 const iv = (v) => el('span', null, v === null || v === undefined ? '' : String(v));
@@ -152,36 +165,68 @@ function revert(tab) {
 const FM_K = 'font-size:10.5px;color:var(--muted-foreground);padding-top:2px;font-family:var(--mono)';
 const FM_V = 'overflow-wrap:anywhere;font-family:var(--mono);font-size:11.5px';
 
-function viewBody(text) {
-  const doc = FX.mdParse(text);
-  const fm = [];
-  doc.fm.forEach((fp) => { fm.push(el('span', { style: FM_K }, iv(fp.k)), el('span', { style: FM_V }, iv(fp.v))); });
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);color:var(--foreground);padding:20px 24px 60px;font-size:14px;line-height:1.65',
-  },
-    el('div', { style: 'max-width:72ch' },
+const VIEW_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);color:var(--foreground);padding:20px 24px 60px;font-size:14px;line-height:1.65';
+const RAW_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 16px;font-family:var(--mono);font-size:12px;line-height:1.7';
+const DIFF_ST = 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 0;font-family:var(--mono);font-size:12px;line-height:1.7';
+
+/* ── THE SCROLL POSITION IS STATE, AND IT LIVES ON A NODE ──────────────────────────────────────
+ *
+ * Every `setState` anywhere in the app repaints all four panels, and panel 4 calls `mountDoc` on
+ * every paint. Each body used to be built from scratch, and `setChildren` reconciles by node
+ * IDENTITY — so the div `scrollTop` lives on was removed and a fresh one inserted, and a half-read
+ * document went back to line 1. With a live agent session beside it that fires on the session poll,
+ * at four-second intervals the PM neither caused nor can predict.
+ *
+ * This is the same problem the edit textarea has, and it gets the same answer: the element is
+ * created once per tab and per mode and KEPT. A repaint whose text has not changed hands back the
+ * identical node, which is what `setChildren` needs in order to leave it alone; when the text really
+ * does change the children are rebuilt INSIDE that element and the offset is restored, because the
+ * document being read is still the document being read.
+ *
+ * Keyed on the rendered text, not on the tab alone — that is what makes "changed nothing" decidable
+ * without diffing DOM.
+ */
+const scrollers = new Map();      // tab id -> { view|raw|diff: { key, node } }
+
+function scrollPane(tab, mode, key, style, build) {
+  let per = scrollers.get(tab.id);
+  if (!per) { per = {}; scrollers.set(tab.id, per); }
+  const cur = per[mode];
+  if (cur && cur.key === key) return cur.node;          // nothing changed — the very same element
+  const node = (cur && cur.node) || el('div', { style });
+  const top = node.scrollTop;
+  setChildren(node, build());
+  if (top) node.scrollTop = top;
+  per[mode] = { key, node };
+  return node;
+}
+
+/** What links and images in this document resolve against. `onDoc` opens a .md link as a doc tab. */
+const linkCtx = (tab) => ({
+  dir: String(tab.path || '').split('/').slice(0, -1),
+  ws: wsId(),
+  onDoc: (p) => openDoc(tab.slug, p, 'FILE'),
+});
+
+function viewBody(tab, text) {
+  return scrollPane(tab, 'view', text, VIEW_ST, () => {
+    const doc = mdRender(text, linkCtx(tab));
+    const fm = [];
+    doc.fm.forEach((fp) => { fm.push(el('span', { style: FM_K }, iv(fp.k)), el('span', { style: FM_V }, iv(fp.v))); });
+    return [el('div', { style: 'max-width:72ch' },
       el('div', {
         style: 'border:1px solid var(--border);background:var(--card);padding:10px 12px;margin-bottom:18px;display:grid;grid-template-columns:auto 1fr;gap:4px 14px;font-size:12.5px',
       }, fm),
       el('h1', {
         style: 'font-size:21px;font-weight:600;line-height:1.3;margin:4px 0 12px;text-wrap:balance;font-family:var(--sans)',
-      }, iv(doc.title)),
-      doc.blocks.map((bk) => el('div', null,
-        bk.isH ? el('h2', {
-          style: 'font-size:16px;font-weight:600;line-height:1.35;margin:24px 0 8px;padding-bottom:5px;border-bottom:1px solid var(--border)',
-        }, iv(bk.h)) : null,
-        bk.isP ? el('p', { style: 'margin:0 0 12px' }, iv(bk.p)) : null,
-        bk.isList ? el('ul', { style: 'margin:0 0 12px;padding-left:22px' },
-          bk.items.map((li) => el('li', { style: 'margin:0 0 5px;padding-left:2px' }, iv(li)))) : null,
-      )),
-    ),
-  );
+      }, doc.title || iv('')),
+      doc.blocks.map((bk) => el('div', null, bk)),
+    )];
+  });
 }
 
-function rawBody(text) {
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 16px;font-family:var(--mono);font-size:12px;line-height:1.7',
-  }, text.split('\n').map((l) => {
+function rawBody(tab, text) {
+  return scrollPane(tab, 'raw', text, RAW_ST, () => text.split('\n').map((l) => {
     const ln = FX.rawLine(l);
     return el('div', {
       style: 'color:' + ln.c + ';font-weight:' + ln.w + ';white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
@@ -254,13 +299,18 @@ function htmlFrame(tab, text) {
   return node;
 }
 
-function diffBody(raw, text, dirty) {
-  const rows = dirty ? FX.diffLines(raw, text) : [FX.NO_DIFF_ROW];
-  return el('div', {
-    style: 'flex:1;min-height:0;overflow-y:auto;background:var(--background);padding:14px 0;font-family:var(--mono);font-size:12px;line-height:1.7',
-  }, rows.map((dr) => el('div', {
-    style: 'color:' + dr.c + ';background:' + dr.bg + ';padding:0 16px;white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
-  }, iv(dr.t))));
+/* Two texts joined into one key. The separator is a character no document can contain — the same
+ * reasoning `sessionProjection` uses in data.js — so a change that only moves the boundary between
+ * them cannot fold into an identical key and suppress a rebuild that was real. */
+const SEP = '\u0000';
+
+function diffBody(tab, raw, text, dirty) {
+  return scrollPane(tab, 'diff', dirty ? raw + SEP + text : '', DIFF_ST, () => {
+    const rows = dirty ? FX.diffLines(raw, text) : [FX.NO_DIFF_ROW];
+    return rows.map((dr) => el('div', {
+      style: 'color:' + dr.c + ';background:' + dr.bg + ';padding:0 16px;white-space:pre-wrap;overflow-wrap:anywhere;min-height:1.2em',
+    }, iv(dr.t)));
+  });
 }
 
 /* ── per-tab state that is DOM, not data ───────────────────────────────────────────────────── */
@@ -287,6 +337,7 @@ function editBox(tab) {
 export function disposeDoc(id) {
   boxes.delete(id);
   frames.delete(id);
+  scrollers.delete(id);
 }
 
 /* ── mount ─────────────────────────────────────────────────────────────────────────────────── */
@@ -335,8 +386,8 @@ export function mountDoc(host, tab) {
   );
 
   let body;
-  if (dm === 'raw') body = rawBody(text);
-  else if (dm === 'diff') body = diffBody(raw, text, dirty);
+  if (dm === 'raw') body = rawBody(tab, text);
+  else if (dm === 'diff') body = diffBody(tab, raw, text, dirty);
   else if (dm === 'edit') {
     body = editBox(tab);
     /* `defaultValue` IS the textarea's child text node, and the prototype's runtime keeps it in
@@ -345,7 +396,7 @@ export function mountDoc(host, tab) {
      * genuinely differs, which is what keeps the caret still mid-sentence. */
     if (body.defaultValue !== text) body.defaultValue = text;
     if (body.value !== text) body.value = text;
-  } else body = rendersAsPage(tab) ? htmlFrame(tab, text) : viewBody(text);
+  } else body = rendersAsPage(tab) ? htmlFrame(tab, text) : viewBody(tab, text);
 
   setChildren(host, [modeBar, body]);
   return host;

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,
     };