create-pmos 0.13.0 → 0.15.0

package/workspace/lib/handoff.js

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

package/workspace/lib/layout.js

@@ -6,7 +6,7 @@
  * so a layout the client can produce and a layout the server will store can never disagree.
  *
  * A layout is a NAMED STATE TUPLE. The grid template is COMPUTED from it (gridFor) rather than
- * hand-written per layout, because the twelve side×reader combinations are exactly where a
+ * hand-written per layout, because that is exactly where a
  * hand-written template drifts: a column count that no longer matches its area row produces an
  * unusable window, and the PM's live agent sessions are inside it.
  *
@@ -24,24 +24,41 @@
   else root.PMOSLayout = api;
 })(typeof self !== 'undefined' ? self : this, function () {
 
+  /* workspace-viewer-column — `reader` is RETIRED from the tuple.
+   *
+   * It used to hold four positions and decided where a document rendered. Documents, images and
+   * the summoned surfaces now open as tabs in the terminal column, so there is no longer a pane to
+   * position: `#paneDoc`, `#railSplit` and `libSplit` went with it, and `.rail` is the detail panel
+   * alone. Keeping the slot and merely emptying it was the alternative and is the worse one — it
+   * would leave document-shaped content two possible homes and no rule for which.
+   *
+   * What survives is the DETAIL PANEL's column, which still needs a width and keeps its drag
+   * handle — `readW` is renamed `panelW` and old values fall back to it, since it sized the same
+   * column. What does not survive is its POSITION: the panel now always sits between the structure
+   * column and the terminal, because the four positions existed to place a document.
+   *
+   * So the tuple is `{side, split, sideW, panelW, folds}` rather than seven fields.
+   */
   const SIDE = ['left', 'right', 'off'];
-  const READER = ['left', 'right', 'bottom', 'off'];      // FOUR positions (R1) — every position
-  const SPLIT = ['off', 'on'];                            // the state can hold has a control
-  const FOLD_KEYS = ['ws', 'sess', 'lib', 'doc'];
+  const SPLIT = ['off', 'on'];
+  // `doc` retired with the pane it folded. `sess` was already retired (R13) and is likewise ignored
+  // rather than migrated — a stored value for either resolves harmlessly through sanitize.
+  const FOLD_KEYS = ['ws', 'lib'];
+  const RETIRED_FOLD_KEYS = ['sess', 'doc'];
 
   const SIDE_MIN = 160, SIDE_MAX = 520;
-  const READ_MIN = 280, READ_MAX = 1000;
-  const LIB_MIN = 15, LIB_MAX = 80;                       // the library/document divider, percent
-  const BOTTOM_H = 300;                                   // the reader's height when docked bottom
-  const LIB_DEFAULT = 46;
+  const PANEL_MIN = 280, PANEL_MAX = 1000;                // the detail panel's width, still draggable
 
-  // `review` is byte-for-byte the arrangement that shipped before this feature (R2): a PM who
-  // never opens the layout control must see no change at all.
+  // `review` is the DEFAULT — the arrangement a PM who never opens the layout control sees.
+  // With the reader retired, the four stock layouts differ in the two axes that remain: whether the
+  // structure column is present, which side it sits on, and whether the terminal is split. That is
+  // fewer axes than before and they are kept genuinely distinct rather than padded back out to four
+  // by inventing differences the PM would not feel.
   const STOCK = [
-    { id: 'focus',   name: 'focus',   key: 1, side: 'off',  reader: 'off',    split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
-    { id: 'read',    name: 'read',    key: 2, side: 'left', reader: 'left',   split: 'off', sideW: 214, readW: 760, libSplit: LIB_DEFAULT },
-    { id: 'compare', name: 'compare', key: 3, side: 'left', reader: 'off',    split: 'on',  sideW: 214, readW: 400, libSplit: LIB_DEFAULT },
-    { id: 'review',  name: 'review',  key: 4, side: 'left', reader: 'right',  split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
+    { id: 'focus',   name: 'focus',   key: 1, side: 'off',   split: 'off', sideW: 262, panelW: 460 },
+    { id: 'read',    name: 'read',    key: 2, side: 'left',  split: 'off', sideW: 214, panelW: 760 },
+    { id: 'compare', name: 'compare', key: 3, side: 'left',  split: 'on',  sideW: 214, panelW: 420 },
+    { id: 'review',  name: 'review',  key: 4, side: 'left',  split: 'off', sideW: 280, panelW: 560 },
   ];
   const DEFAULT_ID = 'review';
   const STOCK_IDS = STOCK.map((l) => l.id);
@@ -54,7 +71,7 @@
     return Number.isFinite(n) ? n : fallback;
   };
 
-  function defaultFolds() { return { ws: true, sess: true, lib: true, doc: true }; }
+  function defaultFolds() { return { ws: true, lib: true }; }
   function folds(v) {
     const out = defaultFolds();
     if (v && typeof v === 'object') for (const k of FOLD_KEYS) if (typeof v[k] === 'boolean') out[k] = v[k];
@@ -84,15 +101,19 @@
       name: stock ? base.name : name,                       // stock names are not editable (R5)
       key: stock ? base.key : null,                         // ⌃1–⌃4 belong to the stock four
       side: oneOf(r.side, SIDE, base ? base.side : 'left'),
-      reader: oneOf(r.reader, READER, base ? base.reader : 'right'),
       split: oneOf(r.split, SPLIT, base ? base.split : 'off'),
       sideW: Math.round(clamp(num(r.sideW, base ? base.sideW : 262), SIDE_MIN, SIDE_MAX)),
-      readW: Math.round(clamp(num(r.readW, base ? base.readW : 400), READ_MIN, READ_MAX)),
-      // the library/document divider. It lives IN the tuple rather than in localStorage because R8
-      // promises to carry it across the upgrade and dimension 1 counts it as "nothing lost" — a
-      // global client key can satisfy neither: it is not per-workspace, and it goes on being read
-      // from the pre-feature store on every boot, which R8 explicitly forbids.
-      libSplit: Math.round(clamp(num(r.libSplit, base ? base.libSplit : LIB_DEFAULT), LIB_MIN, LIB_MAX) * 10) / 10,
+      // The detail panel keeps a width and keeps its drag handle. A layout stored before this
+      // change has no `panelW`, but it does have the `readW` that used to size the same column —
+      // so that is what it falls back to, and the PM's tuning survives the rename instead of
+      // snapping to a default. This is the one legacy field genuinely worth carrying.
+      panelW: Math.round(clamp(num(r.panelW, num(r.readW, base ? base.panelW : 560)), PANEL_MIN, PANEL_MAX)),
+      // `reader`, `readW` and `libSplit` are DROPPED rather than carried. Every layout persisted
+      // before workspace-viewer-column still holds all three, and they arrive here on every boot in
+      // a live workspace — so the contract that matters is that reading them is harmless, which it
+      // is: unknown keys on `r` are simply not copied out. Dropping is deliberate and not silent —
+      // a value for a pane that no longer exists cannot be honoured, and carrying it forward would
+      // let a later reader resurrect a pane the app can no longer render.
       folds: folds(r.folds),
       lastUsedAt: Math.max(0, Math.round(num(r.lastUsedAt, 0))),
     };
@@ -130,19 +151,17 @@
   /* The computed grid. Returns {columns, rows, areas} as CSS strings.
      INVARIANT: every area row names exactly as many cells as `columns` has tracks. */
   function gridFor(l) {
-    const S = l.sideW + 'px', R = l.readW + 'px';
-    if (l.reader === 'bottom') {
-      const rows = 'minmax(0,1fr) ' + BOTTOM_H + 'px';
-      if (l.side === 'left')  return { columns: S + ' minmax(0,1fr)', rows, areas: '"side term" "side read"' };
-      if (l.side === 'right') return { columns: 'minmax(0,1fr) ' + S, rows, areas: '"term side" "read side"' };
-      return { columns: 'minmax(0,1fr)', rows, areas: '"term" "read"' };
-    }
+    const S = l.sideW + 'px', P = l.panelW + 'px';
+    // The detail panel is no longer independently positionable: it always sits between the
+    // structure column and the terminal, because that is the order the work flows in — pick the
+    // initiative, read its state, act on it. The four positions it used to have existed to place a
+    // DOCUMENT, and documents are tabs in the terminal column now. Hiding the panel is the column
+    // collapse (a 36px labelled rail), which is client state rather than part of the arrangement.
     const cols = [], names = [];
-    if (l.side === 'left')   { cols.push(S); names.push('side'); }
-    if (l.reader === 'left') { cols.push(R); names.push('read'); }
+    if (l.side === 'left')  { cols.push(S); names.push('side'); }
+    cols.push(P); names.push('read');
     cols.push('minmax(0,1fr)'); names.push('term');
-    if (l.reader === 'right'){ cols.push(R); names.push('read'); }
-    if (l.side === 'right')  { cols.push(S); names.push('side'); }
+    if (l.side === 'right') { cols.push(S); names.push('side'); }
     return { columns: cols.join(' '), rows: 'minmax(0,1fr)', areas: '"' + names.join(' ') + '"' };
   }
 
@@ -156,28 +175,31 @@
      The property item 4 actually names — the control that un-hides a pane is itself always
      reachable — is a fact about the DOM (the chip lives in `.bar`, a grid sibling of `#bodyGrid`,
      and the position controls in `.lay-pos` can always restore a pane), and it is asserted where
-     it can genuinely fail: ui-test.js walks all twelve side × reader states in a real engine. */
+     it can genuinely fail: ui-test.js walks every remaining arrangement in a real engine. */
   function hasEscape(l) {
     return gridFor(l).areas.indexOf('term') !== -1;
   }
 
   /* R8 — carry the pre-feature client keys into this workspace's `review` so nobody's tuning is
-     lost on upgrade. Reads the five localStorage values the shipped app wrote:
+     lost on upgrade. It read five localStorage values the shipped app wrote:
      rail(on|off) railw(<n>px) libsplit(<n>%) fold-lib(on|off) fold-doc(on|off).
-     It formerly said "five" and read four — `libsplit` was collected by the caller and dropped
-     here, so R8's promise was false for it and the pre-feature key went on being read at every
-     boot. Review-Gate finding: the comment was the spec, and the code disagreed with it. */
+
+     THREE OF THE FIVE NO LONGER HAVE ANYWHERE TO GO, and that is stated rather than quietly
+     dropped: `rail: off` positioned a pane that is now always a column (hiding it is the column
+     collapse, which is client state and not part of an arrangement); `libsplit` divided a rail that
+     no longer has two halves; `fold-doc` folded `#paneDoc`, which no longer exists. Carrying any of
+     them would mean writing a value no reader can honour.
+
+     `railw` still has a real destination — it sized the same column `panelW` now sizes — so it is
+     the one width that survives, and `fold-lib` still folds the pane it always folded. A PM
+     upgrading from the pre-feature build keeps their column width and their fold; they lose a
+     reader position for a reader that is gone. */
   function migrateLegacy(legacy) {
     const g = (k) => (legacy && typeof legacy === 'object' ? legacy[k] : null);
     const review = stockLayout(DEFAULT_ID);
-    const railOff = g('rail') === 'off';
-    if (railOff) review.reader = 'off';
     const w = num(String(g('railw') || '').replace('px', ''), null);
-    if (w !== null) review.readW = Math.round(clamp(w, READ_MIN, READ_MAX));
-    const ls = num(String(g('libsplit') || '').replace('%', ''), null);
-    if (ls !== null) review.libSplit = Math.round(clamp(ls, LIB_MIN, LIB_MAX) * 10) / 10;
+    if (w !== null) review.panelW = Math.round(clamp(w, PANEL_MIN, PANEL_MAX));
     if (g('fold-lib') === 'off') review.folds.lib = false;
-    if (g('fold-doc') === 'off') review.folds.doc = false;
     const layouts = stockLayouts().map((l) => (l.id === DEFAULT_ID ? review : l));
     return { layouts, currentId: DEFAULT_ID };
   }
@@ -198,8 +220,8 @@
   }
 
   return {
-    SIDE, READER, SPLIT, FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
-    SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, LIB_MIN, LIB_MAX, LIB_DEFAULT, BOTTOM_H,
+    SIDE, SPLIT, FOLD_KEYS, RETIRED_FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
+    SIDE_MIN, SIDE_MAX, PANEL_MIN, PANEL_MAX,
     isStock, stockLayout, stockLayouts, layout, sanitize, gridFor, hasEscape, migrateLegacy,
     loadAction,
   };

package/workspace/lib/mobile-nav.js

@@ -0,0 +1,127 @@
+/* mobile-nav — the phone surface's navigation reducer (workspace-mobile-surface).
+ *
+ * One source of truth for "which screen am I on", used on BOTH sides:
+ *   - the browser loads it as /lib/mobile-nav.js before app.js (window.PMOSMobileNav)
+ *   - test.js requires it, so the whole domain is walkable in node without a browser
+ * exactly as lib/layout.js is. It was written inline in app.js and moved here because the rubric
+ * asks for a pure module and because a reducer that cannot be unit-tested is one whose exclusivity
+ * guarantee is only ever checked by eye.
+ *
+ * DOM-FREE ON PURPOSE. Every function takes a nav state and returns a new one; none touches an
+ * element, a media query, or the app's `state`. That is what makes the four properties below
+ * decidable without a browser:
+ *   P1  exactly one column is shown for any screen — `column` is a function of `kind` alone
+ *   P2  every MODES key has a phone path — the map is iterated, never a literal list
+ *   P3  back never exits the app and never unwinds into another destination
+ *   P4  choosing a destination resets it to its root
+ *
+ * The screen model:
+ *   { dest, kind, mode, id, dk, title, column }
+ *     dest    one of DESTS — which destination this screen belongs to
+ *     kind    'list' | 'detail' | 'terminal' | 'doc' | 'more'
+ *     mode    a MODES key, for kind 'list'
+ *     id      the detail id / session id / viewer id
+ *     dk      the DETAIL kind, for kind 'detail'
+ *     title   only for 'terminal' and 'doc', where the name is not derivable
+ *     column  'side' | 'term' | 'rail' — determined by `kind` and by nothing else
+ *
+ * `column` is the whole of the exclusivity guarantee: the stylesheet shows exactly one of the three
+ * column nodes per value, so P1 is a property of the CSS rather than something this reducer has to
+ * remember to enforce. The columns are never re-parented and never rebuilt, which is what makes the
+ * xterm instance and its PTY socket survive a push, a pop and a destination switch structurally.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSMobileNav = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+// What a LIST screen is called, keyed by mode. This mirrors `MODES[].title` in app.js, and the
+// mirror is deliberate rather than lazy: `titleOf` used to read app.js's `MODE_BY_K` directly,
+// which works in a browser (one global scope) and throws `ReferenceError` the moment the module is
+// required in node — for `kind:'list'`, the root of four of the five destinations. Nothing was red,
+// because nothing called it outside a browser; the header two lines below claimed the whole domain
+// was walkable in node, and it was not. A module that reaches back into its caller for a lookup
+// table is not pure, and the fix for that is to hold the table, not to keep reaching.
+// The drift risk a mirror creates is paid for in the suite: MOBNAV-P6 iterates app.js's own MODES
+// against this map, so a mode added or retitled there and forgotten here fails rather than
+// silently renders a key where a title belongs.
+const MODE_TITLE = {
+  product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
+  knowledge: 'knowledge', agent: 'agents', memory: 'memory',
+};
+// What a DETAIL screen is called. It moved here with the reducer, for the same reason.
+const DETAIL_TITLE = {
+  initiative: 'initiative', repo: 'repository', flow: 'workflow', sched: 'scheduled task',
+  skill: 'skill', know: 'knowledge', agent: 'agent', mem: 'memory',
+  ingest: 'ingest proposal', profiles: 'profiles', connections: 'connections',
+};
+
+const MOBILE_DESTS = ['board', 'scheduled', 'agents', 'memory', 'more'];
+// Every MODES key has an entry. The suite ITERATES `MODES` against this map rather than a literal
+// list, so adding a mode without giving it a phone path fails the suite instead of going silently
+// unreachable — which is the failure P2 exists to catch.
+const MOBILE_DEST = { product: 'board', scheduled: 'scheduled', agent: 'agents', memory: 'memory',
+  workflow: 'more', skills: 'more', knowledge: 'more' };
+const MOBILE_ROOT = {
+  board: { kind: 'list', mode: 'product' },
+  scheduled: { kind: 'list', mode: 'scheduled' },
+  agents: { kind: 'list', mode: 'agent' },
+  memory: { kind: 'list', mode: 'memory' },
+  more: { kind: 'more', mode: null },
+};
+// kind → column. There is no second input, and no screen may carry a column its kind does not give.
+const MOBILE_COLUMN = { list: 'side', more: 'side', detail: 'rail', terminal: 'term', doc: 'term' };
+function mobColumnOf(kind) { return MOBILE_COLUMN[kind] || 'side'; }
+function mobDestForMode(k) { return MOBILE_DEST[k] || null; }
+// Complete a partial screen. The column is derived, never passed in, so a caller cannot put a
+// detail on the terminal column by writing it down.
+function mobScreen(s) {
+  const kind = (s && s.kind) || 'list';
+  return { dest: (s && s.dest) || 'board', kind, mode: (s && s.mode) || null,
+    id: (s && s.id) || null, dk: (s && s.dk) || null, title: (s && s.title) || null,
+    column: mobColumnOf(kind) };
+}
+function mobRootOf(dest) {
+  const r = MOBILE_ROOT[dest] || MOBILE_ROOT.board;
+  return mobScreen({ dest: MOBILE_ROOT[dest] ? dest : 'board', kind: r.kind, mode: r.mode });
+}
+/* The title map. `list` and `more` derive; `detail` reads DETAIL_TITLE (declared far below — this
+ * is only ever called at runtime, long after that const has evaluated); `terminal` and `doc` carry
+ * a title because a session's name and a document's name are not derivable from a screen. */
+function mobTitleOf(s) {
+  if (!s) return '';
+  if (s.kind === 'list') return MODE_TITLE[s.mode] || String(s.mode || '');
+  if (s.kind === 'more') return 'more';
+  if (s.kind === 'detail') return DETAIL_TITLE[s.dk] || 'detail';
+  return s.title || String(s.id || '');
+}
+function mobNavInit(dest) { return { dest: MOBILE_ROOT[dest] ? dest : 'board', stack: [] }; }
+function mobPush(nav, screen) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return { dest: n.dest, stack: n.stack.concat([mobScreen(Object.assign({ dest: n.dest }, screen))]) };
+}
+// Removes EXACTLY one. Back from a destination root is a no-op — it never exits the app and never
+// unwinds into another destination, which is the second half of P3.
+function mobPop(nav) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return n.stack.length ? { dest: n.dest, stack: n.stack.slice(0, -1) } : { dest: n.dest, stack: [] };
+}
+// Choosing a destination RESETS it to its root with an empty stack — the prototype's {tab, stack:[]}.
+function mobSwitchDest(nav, dest) { return mobNavInit(dest); }
+function mobCurrentOf(nav) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return n.stack.length ? n.stack[n.stack.length - 1] : mobRootOf(n.dest);
+}
+/* R11 — the legacy key is read ONCE, for migration, and never written again. Every value the old
+ * three-way switcher could hold, plus anything unrecognised and nothing at all, lands on `board`:
+ * the destination root is the only screen that is safe to draw without re-reading anything. */
+function mobMigrateView(v) { return MOBILE_ROOT[v] ? v : 'board'; }
+
+  return { push: mobPush, pop: mobPop, switchDest: mobSwitchDest, init: mobNavInit,
+    current: mobCurrentOf, titleOf: mobTitleOf, columnOf: mobColumnOf, destForMode: mobDestForMode,
+    MODE_TITLE,
+    migrateView: mobMigrateView, screen: mobScreen, root: mobRootOf,
+    DESTS: MOBILE_DESTS, DEST_FOR_MODE: MOBILE_DEST, ROOTS: MOBILE_ROOT, DETAIL_TITLE };
+});