create-pmos 0.29.0 → 0.30.0

package/README.md

@@ -333,6 +333,83 @@ 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.**
+Run `npx create-pmos@latest workspace`.
+
+- **If you are on 0.28.0, 0.29.0 never upgraded you.** The launcher decides whether to reinstall by
+  comparing the bundled workspace-app version against the installed one, and 0.29.0 shipped with the
+  app version left at `0.28.0` — so the comparison came out equal and the upgrade was silently
+  skipped. Everything listed below was in the 0.29.0 tarball and unreachable from an existing
+  install. 0.29.1 bumps both versions together, which is what actually delivers it.
+- **The check that catches this already existed and did not run.** An assertion pins the two versions
+  in lockstep; CI only ran it when `workspace/**` changed, and a release PR touches
+  `npm-pkg/package.json`. The path filter now includes it, so the guard runs on the diff that breaks
+  it. This is the second time a version bump has shipped without reaching adopters (0.9.1 was the
+  first), and the first time the repo could have known.
+
+**What 0.29.0 carried, now actually delivered:**
+
+- **A skipped Review Gate no longer shows as a green tick.** `workflow-state.js` rendered a
+  `SKIPPED` verdict — a row that says *judging did not happen* — with the same ✓ it uses for a real
+  pass, and a `FAIL` likewise. A skip is now `pending` and a fail is `blocked`. If your board looked
+  greener than your ledger, this is why.
+- **A chore that carries a rubric now shows its Review Gate.** The rung decided from the
+  initiative's **lane**, so any lane that *may* skip a rubric could never surface a verdict it
+  actually had — the ladder printed *"chore lane carries no rubric"* while a verdict sat unread. It
+  reads the rubric now, in every lane. This is how a real initiative reached `accept` with its gate
+  never run.
+- **`evaluator.skill`'s final step is runnable.** It told you to persist the verdict through
+  `save_eval` — a hosted-backend tool that **does not exist in file mode**, which is the mode the kit
+  runs in. The last instruction of the Review Gate could not be followed. It now names the writer for
+  your context: `pmos/scripts/pmos-log.sh eval …`.
+- **`pmos-log.sh` can record a skipped gate.** Its verdict enum was `PASS|PASS-WITH-FINDINGS|FAIL`,
+  while `AGENTS.md` tells you *"a gate that was skipped is recorded as skipped — never leave a missing
+  eval to be read as a pass."* Following that instruction hit an error, and the only compliant option
+  was to edit the ledger by hand. Now: `pmos-log.sh eval <run> <initiative> SKIPPED "<reason>"`,
+  which requires the reason and records `score: null`.
+- **The kit build now refuses to ship a skill that names a tool you do not have.** That class had
+  already shipped twice in the same sentence of the same skill. The check runs at build time and
+  fails the build; its one bound (per-reference, not per-line) is documented in `build-kit.sh`.
+
+*Not in this release, stated so you do not go looking:* the same upstream round hardened two modules
+that the kit does not run — `drive-guard.js` ships inside the workspace bundle but nothing requires
+it, and `record-eval.js` is not in the payload at all. Those fixes are real, and they are not
+something your kit was relying on.
+
 ## What's new in 0.28.0
 
 **`search everything…` now searches every file in the folder, and any file it finds opens in a tab.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.29.0",
+  "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@4104fde
+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/drive-guard.js

@@ -202,11 +202,28 @@ const DISPOSITION_INTERNAL_RE = new RegExp(
  */
 const DISPOSITION_VERB = '(?:PROMOTE[SD]?|ITERATE[SD]?|KILL(?:ED|S)?)';
 
-/** Immediately-preceding words that make the verb a modifier or a passive, not an act. */
+/**
+ * DETERMINERS ONLY, and the narrowing is measured rather than argued.
+ *
+ * The first version of this set carried 40 words — determiners, auxiliaries and modals — on the
+ * reasoning that a passive clause ("was killed off upstream") is prose too. A third independent pass
+ * showed what that bought an attacker:
+ *
+ *     status: got PROMOTED by PM wawan on 2026-07-28      prev=refused → PERMITTED
+ *     status: not KILLED — shipped 2026-07-28             prev=refused → PERMITTED
+ *
+ * Neither is prose. Both are forged dispositions wearing an auxiliary. Swept against this
+ * repository's own records, the ONLY genuine prose that needs an exemption at all is
+ * determiner-led — "derived from *the promoted* prototype" — which is exactly the false positive the
+ * previous round was contracted to fix. The auxiliaries were paying for a case the corpus does not
+ * contain, in forgeable forms.
+ *
+ * A status line that reads "if a specimen is promoted" is now REFUSED. That is over-refusal, it is
+ * the safe direction, and it is the trade this guard exists to make: the cost is a driver rephrasing
+ * one status line; the cost of the other direction is a forged PM disposition.
+ */
 const PROSE_LEAD = new Set([
   'the', 'a', 'an', 'this', 'that', 'these', 'those', 'its', 'their', 'our', 'his', 'her',
-  'was', 'were', 'been', 'being', 'is', 'are', 'be', 'get', 'gets', 'got', 'gotten',
-  'not', 'never', 'unless', 'if', 'when', 'would', 'could', 'should', 'may', 'might',
 ]);
 
 /**
@@ -220,8 +237,20 @@ function isDisposition(value) {
   let m;
   while ((m = re.exec(v)) !== null) {
     const before = v.slice(0, m.index + m[1].length);
-    const prior = (before.match(/([A-Za-z']+)[^A-Za-z']*$/) || [])[1];
-    if (prior && PROSE_LEAD.has(prior.toLowerCase())) continue;   // adjectival or passive — prose
+    /* ADJACENT, separated by whitespace and nothing else.
+     *
+     * This was `[^A-Za-z']*$` — "the last run of letters, skipping ANY non-letters" — so a colon, a
+     * comma, a quote or an em dash between the determiner and the verb kept the carve-out firing
+     * while destroying the grammar that justifies it. A third independent pass walked through it:
+     *
+     *     status: CLOSED — verdict is "PROMOTED" (PM wawan)     prev=refused → PERMITTED
+     *     status: CLOSED. Leg A is: PROMOTED 2026-07-28         prev=refused → PERMITTED
+     *
+     * "is" is not modifying "PROMOTED" across a colon and a quote mark; it is a different clause.
+     * An exemption that ignores what sits between its two words is not a grammatical rule, it is a
+     * proximity coincidence. */
+    const prior = (before.match(/([A-Za-z']+)[ \t]*$/) || [])[1];
+    if (prior && PROSE_LEAD.has(prior.toLowerCase())) continue;   // adjectival — prose
     return true;
   }
   return false;
@@ -343,10 +372,26 @@ function carriesDisposition(value, seen) {
     const isStatusKey = k.toLowerCase() === 'status' || k.toLowerCase() === 'disposition';
     if (isStatusKey) {
       // A status value may be a string, a Buffer, or a list of candidate values. All are inspected.
+      /* Judge what will be WRITTEN, not what the value's JS type happens to be.
+       *
+       * `typeof c === 'string'` let two shapes through that both serialize to a real disposition:
+       *
+       *     { status: { toJSON() { return 'PROMOTED'; } } }   →  {"status":"PROMOTED"}
+       *     { status: new String('PROMOTED') }                →  {"status":"PROMOTED"}
+       *
+       * The bytes that land on disk are a forged PM disposition; only the in-memory type differed.
+       * A third independent pass found both, and noted the asymmetry that gives it away: the same
+       * trick aimed at PM_approved was already caught, because THAT check reads the serialized form.
+       * This one now does too. */
       const candidates = Array.isArray(v) ? v : [v];
       for (const c of candidates) {
         if (typeof c === 'string' && isDisposition(c)) return true;
         if (Buffer.isBuffer(c) && isDisposition(c.toString('utf8'))) return true;
+        if (c !== null && typeof c === 'object' && !Buffer.isBuffer(c)) {
+          let ser;
+          try { ser = JSON.stringify(c); } catch { return true; }   // uninspectable → refuse
+          if (typeof ser === 'string' && isDisposition(ser)) return true;
+        }
       }
     }
     if (Buffer.isBuffer(v)) continue;   // a Buffer's numeric indices are not an object graph
@@ -484,6 +529,6 @@ function guardedWriter(write) {
 }
 
 module.exports = {
-  assertWritable, guardedWriter, carriesApproval, carriesDisposition, ForbiddenWrite,
+  assertWritable, guardedWriter, carriesApproval, carriesDisposition, isDisposition, PROSE_LEAD, ForbiddenWrite,
   ALLOWED_DIR_PREFIXES, ALLOWED_BASENAMES, HUMAN_DECISION_SINKS, DISPOSITION_RE,
 };

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

package/workspace/public/pm/data.js

@@ -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

@@ -866,6 +866,25 @@ function searchIndex(root) {
   return entry;
 }
 
+/**
+ * Is the FIRST chunk of this file free of NUL bytes? The bounded form of the reader's own refusal.
+ *
+ * `readTextDoc` scans the whole file, which is right for serving it and wrong for labelling 200
+ * search hits. This reads a fixed head — enough to catch the binary-masquerading-as-text case the
+ * reader refuses on, at a cost that does not scale with file size. A file whose head is clean and
+ * whose tail hides a NUL will still be labelled openable and still fail to open; that is a strictly
+ * smaller lie than labelling every large text file unopenable, and it is stated rather than hidden.
+ */
+function headIsText(full) {
+  let fd = null;
+  try {
+    fd = fs.openSync(full, 'r');
+    const buf = Buffer.alloc(64 * 1024);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    return buf.subarray(0, n).indexOf(0) === -1;
+  } catch { return false; } finally { if (fd !== null) { try { fs.closeSync(fd); } catch { /* ignore */ } } }
+}
+
 /** One matched line, trimmed and centred on the needle, so a minified file cannot flood the row. */
 function searchSnippet(line, at) {
   const s = String(line || '').replace(/\t/g, '  ');
@@ -918,7 +937,13 @@ function searchWorkspace(root, query, limit) {
        * the honest answer is "we did not look", and the safe rendering of that is a hit the PM
        * cannot click into an unknown. */
       const st = fs.statSync(path.join(root, rel));
-      if (!st.isFile() || st.size > SEARCH_CONTENT_BYTES) return false;
+      if (!st.isFile()) return false;
+      /* Past the byte budget we do not READ the file — but "we did not look" is not "the reader
+       * refuses it". Returning false there swapped one false label for its opposite: a legitimate
+       * 316 KB markdown doc reported openable:false while /api/doc served it 200 with 324,017 bytes.
+       * An independent pass measured it. The NUL test only needs the HEAD of the file, so bound the
+       * read instead of abandoning the question. */
+      if (st.size > SEARCH_CONTENT_BYTES) return headIsText(path.join(root, rel));
       return readTextDoc(root, rel) !== null;
     } catch { return false; }
   };
@@ -1026,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
@@ -1095,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) {
@@ -1120,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;
@@ -1205,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);
@@ -1217,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);
@@ -1443,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,
     };