create-pmos 0.6.3 → 0.7.0

package/README.md

@@ -1,7 +1,7 @@
 ---
 type: Reference
 title: "create-pmos"
-timestamp: 2026-07-23
+timestamp: 2026-07-27
 ---
 
 # create-pmos
@@ -333,6 +333,59 @@ 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.7.0
+
+**The workspace GUI has layouts.** Until now it had exactly one arrangement: a fixed sidebar, the
+terminal, and a right rail. Now it has four you can name, switch between in one act, and then change
+however you like.
+
+- **Named layouts — `focus` · `read` · `compare` · `review`.** Switch from the header or with
+  ⌃1–⌃4. `focus` gives the terminal the window; `read` makes the document the primary column instead
+  of a 400px strip; `compare` puts two sessions side by side; `review` is the arrangement you already
+  had.
+- **Adjust anything, and it's kept.** Drag a pane by its ⠿ grip to a different edge, drag a column's
+  edge to resize it, fold a pane away — whatever you change is written back into the layout you're
+  in. There is no save button, no "unsaved changes", and nothing to manage. Each stock layout has a
+  **restore** in the list for when you want the original back.
+- **Two terminals at once.** `compare` (or the layout menu) splits the terminal into two groups, each
+  with its own tab strip and its own live session — so you can watch two agents work instead of
+  alternating tabs from memory. Closing the split doesn't kill anything; the second session goes back
+  to being a tab.
+- **Make your own.** `＋ new layout from this arrangement` names what you've built; custom layouts can
+  be renamed and deleted.
+- **Layouts belong to the repo you opened.** Each workspace remembers its own, on your machine
+  (`workspace/state/layouts/`) — nothing is sent anywhere.
+- **The sidebar caught up.** Its panes now fold and its width now drags, which only the right rail
+  could do before.
+
+**Upgrade note:** the workspace app ships inside the package; `npx create-pmos@latest workspace`
+installs the new build. If you had already dragged your rail width or hidden it, that carries into
+this workspace's `review` layout on first run — you keep what you had. Your `state/`, `planning/`,
+and `okf/` records are untouched. Phones are unchanged: the single-column switcher still owns the
+layout there, and the layout control is hidden.
+
+**Also in this build, and not yet finished:** a **summoned document review** surface (ask for a
+review of a document, dispose of each finding by Apply / Edit / Dismiss, with every disposition
+recorded as an attributed correction). It rides along because the package bundles the whole
+workspace app — its own build is still open and it has not been through its review gate. Treat it as
+a preview, not a finished feature.
+
+## What's new in 0.6.4
+
+Workspace GUI session controls — two things the PM asked for while working in real terminals.
+
+- **Branch awareness + pick/create at session start.** The header now shows the active repo's current
+  git branch (dirty-marked), and the new-session form lets you start a session on an existing branch
+  or create a new one. It's honest about the shared working tree: switching a branch is repo-wide and
+  moves every session in that repo — the form says so rather than faking per-session isolation.
+- **Scratchpad.** A collapsible drawer at the bottom of the terminal column (toggle from the header or
+  ⌘J) to stage commands and notes before they hit the terminal — it never overlays the terminal or the
+  document reader, persists per workspace, and has **copy** and **→ terminal** (which pastes without
+  pressing enter, so nothing auto-runs).
+
+**Upgrade note:** the workspace app ships inside the package; `npx create-pmos@latest workspace`
+installs the new build. Your `state/`, `planning/`, and `okf/` records are untouched — purely additive.
+
 ## What's new in 0.6.1
 
 A completeness fix: two skills the kit already *pointed at* but didn't *ship*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → 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. `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@f4589bf
-assembled: 2026-07-27
+kernel-source: pmos@a2227ff
+assembled: 2026-07-28
 mode: vendor

package/payload/scripts/gate-initiative.sh

@@ -10,6 +10,8 @@
 #        chore             -> a non-empty `intent:` line in the initiative file; no PRD/rubric
 #        incident          -> prd_path = the incident record, set and exists (post-hoc is sanctioned)
 #        content           -> prd_path = the content brief, set and exists; rubric recommended (D58)
+#        prototype         -> prd_path = the quick prototype brief, set and exists; NO rubric BY
+#                             DESIGN (leg A is grilled as dialogue, never scored — D60)
 #      Unknown/missing type = feature: the strictest lane. Lane variation is never a skip.
 # Escape hatch (explicit, logged): the `no-initiative` label — anchor-free trivia ONLY, real work
 # takes a lane (D56).
@@ -68,11 +70,12 @@ anchor="$(frontval parent_kr)"
 # Gate); what varies per lane is the spec/eval artifact. In EVERY lane a rubric_path that is set
 # must point at a real file — optional never means dangling.
 case "$lane" in
-  discovery|incident|content)
+  discovery|incident|content|prototype)
     # if-form, not `[ … ] && …`: under set -e a false test as a bare && would kill the script.
     what="spike brief"
     if [ "$lane" = incident ]; then what="incident record (post-hoc within 48h is the sanctioned lane rule)"; fi
     if [ "$lane" = content ]; then what="content brief (rubric recommended, not required — D58)"; fi
+    if [ "$lane" = prototype ]; then what="quick prototype brief (no rubric BY DESIGN — leg A is grilled, never scored; D60)"; fi
     [ -n "$prd" ] || fail "initiative '$id' (type $lane) has no prd_path in $init_file — set it to the $what (see $KIT_ROOT/okf/core/templates/)."
     [ -f "$prd" ] || fail "prd_path '$prd' (from $init_file, type $lane) does not exist in the repo."
     [ -z "$rubric" ] || [ -f "$rubric" ] || fail "rubric_path '$rubric' (from $init_file) does not exist in the repo (a rubric is optional in the $lane lane — set the path only to a real file)."

package/workspace/lib/apply-change.js

@@ -0,0 +1,106 @@
+/* apply-change — turn a proposed change into new file text, or refuse.
+ * (workspace-review-and-edit · R6/R9/R11)
+ *
+ * Pure: text in, text out. It never touches the filesystem, so the path guard stays where it
+ * already lives (insideRoot in server.js) and this module can be unit-tested directly.
+ *
+ * The rule that matters is REFUSE ON MISMATCH. A proposal is anchored to the exact text it
+ * expects to replace; if that text is not present exactly once, the change is rejected rather
+ * than merged, guessed at, or fuzzy-matched. This is what makes the file-changed-under-you case
+ * safe (rubric dim 4 grades it explicitly): the PM opened a finding, the file moved on disk, and
+ * Apply must fail loudly instead of writing a diff the PM never saw.
+ *
+ * It is also the whole of R9. There is no stored diff and no parallel history here — the change
+ * is computed from `before`/`after` at apply time and then it is over. `git log` remains the
+ * record of what changed; the correction record (correction-record.js) holds why and by whom,
+ * which is the part git cannot represent.
+ *
+ * Cancel needs no code: the only write is applyChange()'s caller. Not calling it writes nothing.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.ApplyChange = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  /* Line endings are normalised for MATCHING only, never for writing. A CRLF file must come out
+   * CRLF — silently rewriting every line ending of a document would be a diff the PM never saw,
+   * which is the same defect as a fuzzy match wearing a different hat. */
+  function detectEol(text) {
+    return /\r\n/.test(text) ? '\r\n' : '\n';
+  }
+  const toLf = (s) => String(s).replace(/\r\n/g, '\n');
+
+  function countOccurrences(hay, needle) {
+    if (!needle) return 0;
+    let n = 0, i = 0;
+    for (;;) {
+      const at = hay.indexOf(needle, i);
+      if (at === -1) return n;
+      n++; i = at + needle.length;
+    }
+  }
+
+  /**
+   * Apply one proposal to the current text.
+   *   current  — the file as it is on disk right now
+   *   proposal — { before, after }. Omit `before` for a pure insertion (requires `anchor`).
+   *   opts     — { anchor } text to insert after, when `before` is absent
+   * Returns { ok: true, text, eol } or { ok: false, reason, detail? }. Never throws.
+   */
+  function applyChange(current, proposal, opts) {
+    if (typeof current !== 'string') return { ok: false, reason: 'current-not-text' };
+    if (!proposal || typeof proposal !== 'object') return { ok: false, reason: 'no-proposal' };
+
+    const eol = detectEol(current);
+    const cur = toLf(current);
+    const before = proposal.before == null ? null : toLf(proposal.before);
+    const after = proposal.after == null ? '' : toLf(proposal.after);
+    const anchor = opts && opts.anchor != null ? toLf(opts.anchor) : null;
+
+    // ── replacement / deletion ────────────────────────────────────────────────
+    if (before != null && before !== '') {
+      const n = countOccurrences(cur, before);
+      // 0 ⇒ the file moved under the PM. >1 ⇒ we cannot know which one they meant. Both refuse:
+      // an ambiguous apply is a silent wrong edit, and this surface's whole value is being trusted.
+      if (n === 0) return { ok: false, reason: 'stale', detail: 'the text this change replaces is no longer in the file' };
+      if (n > 1) return { ok: false, reason: 'ambiguous', detail: `the anchor text appears ${n} times` };
+      const out = cur.replace(before, after);
+      return { ok: true, text: eol === '\n' ? out : out.replace(/\n/g, eol), eol };
+    }
+
+    // ── pure insertion ────────────────────────────────────────────────────────
+    if (!after) return { ok: false, reason: 'empty-change' };
+    if (anchor == null || anchor === '') return { ok: false, reason: 'no-anchor', detail: 'an insertion must say what it follows' };
+    const n = countOccurrences(cur, anchor);
+    if (n === 0) return { ok: false, reason: 'stale', detail: 'the anchor this change follows is no longer in the file' };
+    if (n > 1) return { ok: false, reason: 'ambiguous', detail: `the anchor text appears ${n} times` };
+    const at = cur.indexOf(anchor) + anchor.length;
+    const out = cur.slice(0, at) + after + cur.slice(at);
+    return { ok: true, text: eol === '\n' ? out : out.replace(/\n/g, eol), eol };
+  }
+
+  /** Added/removed line counts for the change bar (`+3 −1`). Presentation only. */
+  function changeStat(proposal) {
+    const nl = (s) => (s == null || s === '' ? 0 : toLf(s).split('\n').length);
+    return { added: nl(proposal && proposal.after), removed: nl(proposal && proposal.before) };
+  }
+
+  /**
+   * Guard for the write endpoint: the client must send back the exact diff it rendered, and the
+   * server re-derives it. If the two disagree the request is refused — this is what stops a
+   * tampered or stale client from applying something the PM never looked at (sprint criterion 4).
+   */
+  function matchesRendered(current, proposal, renderedAfterText, opts) {
+    const r = applyChange(current, proposal, opts);
+    if (!r.ok) return { ok: false, reason: r.reason, detail: r.detail };
+    if (typeof renderedAfterText !== 'string') return { ok: false, reason: 'no-rendered-text' };
+    if (toLf(r.text) !== toLf(renderedAfterText)) {
+      return { ok: false, reason: 'diff-mismatch', detail: 'the result does not match what was shown to the PM' };
+    }
+    return { ok: true, text: r.text, eol: r.eol };
+  }
+
+  return { applyChange, changeStat, matchesRendered, detectEol };
+});

package/workspace/lib/correction-record.js

@@ -0,0 +1,127 @@
+/* correction-record — what a PM disposition leaves behind. (workspace-review-and-edit · R8/R9)
+ *
+ * The north star is human correction rate per agent run, and its numerator is currently a
+ * self-reported integer: all four runs in planning/runs/agent-runs.jsonl carry
+ * "human_corrections": 0 with no artifact behind the number. correction-signal-derive.skill
+ * explains why the obvious fix does not reach it — "pre-commit conversational steering is
+ * git-invisible and stays the self-report's lane."
+ *
+ * This module builds the artifact for that lane, under one rule that is not negotiable:
+ *
+ *   ATTRIBUTION IS NEVER INFERRED.
+ *
+ * A record exists only for text an agent PROPOSED in this review and the PM then disposed of.
+ * That is the single case where authorship is known rather than guessed — no git blame, no
+ * "the file changed while session X was live" timing heuristic. correction-signal-derive.skill
+ * states the rule this upholds: "Never guess an attribution. A commit you cannot confidently
+ * classify is ambiguous: flagged to the PM, held OUT of the score." A record that would need
+ * inference is not written at all (sprint criterion 7), because a manufactured attribution
+ * poisons the exact metric this exists to feed.
+ *
+ * It stores WHY and BY WHOM. It does not store the diff (R9) — git already holds what changed.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.CorrectionRecord = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const DISPOSITIONS = new Set(['apply', 'edit', 'dismiss']);
+
+  /* Reasons the PM taps. Deliberately short — a taxonomy nobody can hold in their head gets
+   * skipped, and a skipped reason is a record that teaches nothing. 'other' carries free text. */
+  const REASONS = new Set(['factually-wrong', 'incomplete', 'wrong-scope', 'style', 'not-now', 'other']);
+
+  /* Required on `edit` (the agent was wrong in a way worth knowing) and on `dismiss` only when
+   * the PM chooses to give one (PRD open question 2: optional on dismiss, required on edit —
+   * the most common action must not carry the most friction). Never required on `apply`:
+   * accepting a proposal unchanged is not a correction and must not inflate the numerator. */
+  function reasonRequired(disposition) {
+    return disposition === 'edit';
+  }
+
+  /** Is this a correction at all? Applying an agent's proposal unchanged is agreement. */
+  function isCorrection(disposition) {
+    return disposition === 'edit' || disposition === 'dismiss';
+  }
+
+  const isStr = (v) => typeof v === 'string' && v.trim().length > 0;
+
+  /**
+   * Build a record from a disposition, or refuse.
+   *   input = { run_id, initiative_id, finding, disposition, pm_text?, reason?, reason_note?, pm, at }
+   * Returns { ok: true, record } or { ok: false, errors[] }. Never throws, never guesses.
+   */
+  function buildRecord(input) {
+    const e = [];
+    const i = input || {};
+
+    if (!DISPOSITIONS.has(i.disposition)) e.push(`disposition must be one of ${[...DISPOSITIONS].join(' | ')}`);
+    if (!i.finding || typeof i.finding !== 'object') e.push('finding is required — the record is anchored to what was proposed');
+    if (!isStr(i.pm)) e.push('pm is required');
+    if (!isStr(i.at)) e.push('at (ISO 8601) is required');
+
+    // ── the attribution rule (R8) ───────────────────────────────────────────────
+    // The agent's text must be present and must have come from THIS review's proposal. Anything
+    // else would mean deriving authorship from git or from timing, which is exactly forbidden.
+    const f = i.finding || {};
+    const agentText = f.proposal && f.proposal.after;
+    if (i.disposition !== 'dismiss' && !isStr(agentText)) {
+      e.push('no agent-proposed text on this finding — attribution would have to be inferred, so no record is written (R8)');
+    }
+    if (f.withheld === true) {
+      // A withheld finding was never applyable, so a disposition other than dismiss is incoherent
+      // and would imply the containment guard leaked.
+      if (i.disposition !== 'dismiss') e.push('a withheld finding can only be dismissed — it never offered a change (R7)');
+    }
+
+    if (i.disposition === 'edit' && !isStr(i.pm_text)) {
+      e.push('pm_text is required on an edit — the record exists to hold what the PM wrote instead');
+    }
+    if (reasonRequired(i.disposition) && !REASONS.has(i.reason)) {
+      e.push(`reason is required on an edit and must be one of ${[...REASONS].join(' | ')}`);
+    }
+    if (i.reason != null && !REASONS.has(i.reason)) e.push(`unknown reason '${i.reason}'`);
+    if (i.reason === 'other' && !isStr(i.reason_note)) e.push("reason 'other' requires reason_note");
+
+    if (e.length) return { ok: false, errors: e };
+
+    return {
+      ok: true,
+      record: {
+        run_id: isStr(i.run_id) ? i.run_id : null,
+        initiative_id: isStr(i.initiative_id) ? i.initiative_id : null,
+        file: f.file || null,
+        finding_title: f.title || null,
+        disposition: i.disposition,
+        is_correction: isCorrection(i.disposition),
+        // attribution: known, because the agent proposed it here and the PM answered it here.
+        attribution: 'proposed-in-review',
+        agent_text: isStr(agentText) ? agentText : null,
+        pm_text: isStr(i.pm_text) ? i.pm_text : null,
+        reason: i.reason || null,
+        reason_note: isStr(i.reason_note) ? i.reason_note : null,
+        pm: i.pm,
+        at: i.at,
+      },
+    };
+  }
+
+  /** Roll records up into the numbers the PRD's success signal names. No manual counting
+   *  (sprint criterion 8): both come straight off the records. */
+  function summarise(records) {
+    const r = Array.isArray(records) ? records : [];
+    const total = r.length;
+    const corrections = r.filter((x) => x && x.is_correction).length;
+    const acted = r.filter((x) => x && (x.disposition === 'apply' || x.disposition === 'edit')).length;
+    return {
+      dispositions: total,
+      corrections,
+      action_rate: total === 0 ? null : acted / total,
+      inferred_attributions: r.filter((x) => x && x.attribution !== 'proposed-in-review').length,
+    };
+  }
+
+  return { DISPOSITIONS, REASONS, reasonRequired, isCorrection, buildRecord, summarise };
+});

package/workspace/lib/finding-contract.js

@@ -0,0 +1,162 @@
+/* finding-contract — what a review finding must be, and what the PM may do with it.
+ * (workspace-review-and-edit · R3/R7)
+ *
+ * Used on BOTH sides, like preview-kind:
+ *   - server.js requires it to validate a reviewer skill's output before it reaches the client
+ *   - the browser loads it as /lib/finding-contract.js so the renderer asks the SAME question
+ * so the contract, the endpoint and the UI can never disagree about what is applyable.
+ *
+ * The one security-critical function is isApplyable(). It decides whether an Apply control
+ * exists at all. R7's rule is that a proposal which would close a recorded open question or
+ * overwrite a PM decision is surfaced as CONTEXT with no Apply affordance — the absence of the
+ * control is the mechanism, and a warning label is explicitly not a substitute. The rubric makes
+ * this a hard floor (dim 2 must = 1: zero Apply controls ever rendered for a withheld finding),
+ * so this boolean is the whole containment story and it is unit-tested directly.
+ *
+ * The second load-bearing rule is self_undetectable (R3). A review that emits lint findings
+ * becomes a linter the PM stops reading, and "judgement-grade" is not enforceable by inspecting
+ * the finding's text. So the contract inverts it: every finding must NAME what the artifact
+ * cannot see about itself. A reviewer that cannot fill that line has not found this class of
+ * defect, and the finding is rejected structurally rather than by taste.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.FindingContract = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  /* Finding kinds the review must NOT emit (R3). These are owned by the Frontmatter Gate and the
+   * linters; re-reporting them here is how counsel decays into noise. Declared by the reviewer
+   * and rejected on sight — a blocklist catches the honest mistake, and self_undetectable below
+   * catches the dishonest one. */
+  const MECHANICAL_KINDS = new Set([
+    'frontmatter', 'schema', 'link', 'broken-link', 'missing-path', 'path',
+    'string-match', 'regex', 'count', 'occurrence', 'spelling', 'typo', 'formatting', 'lint',
+  ]);
+
+  const isStr = (v) => typeof v === 'string' && v.trim().length > 0;
+
+  /** Reject a finding that a linter should have owned (R3). Kind is declared, not sniffed. */
+  function isMechanical(f) {
+    return !!f && isStr(f.kind) && MECHANICAL_KINDS.has(f.kind.trim().toLowerCase());
+  }
+
+  /* THE guardrail (R7). An Apply control may exist only when the finding is not withheld AND
+   * actually carries a change to make. Both halves matter: `withheld` is the PM-decision guard,
+   * and a null proposal is the context class (nothing to apply). Anything unexpected — a missing
+   * field, a malformed proposal, a non-boolean withheld — resolves to NOT applyable. This
+   * function fails closed on purpose; an unparseable finding must never grow a button. */
+  function isApplyable(f) {
+    if (!f || typeof f !== 'object') return false;
+    if (f.withheld === true) return false;
+    if (f.withheld !== false) return false;          // must be explicitly declared, never inferred
+    const p = f.proposal;
+    if (!p || typeof p !== 'object') return false;
+    return isStr(p.before) || isStr(p.after);        // a pure insertion has no `before`
+  }
+
+  /** Validate one finding against the contract. Returns { ok, errors[] } — never throws. */
+  function validateFinding(f) {
+    const e = [];
+    if (!f || typeof f !== 'object') return { ok: false, errors: ['finding is not an object'] };
+
+    if (!isStr(f.title)) e.push('title is required');
+    if (!isStr(f.file)) e.push('file is required');
+    if (!isStr(f.argument)) e.push('argument is required — a finding without reasoning is an assertion');
+
+    // R3: name what the artifact cannot see about itself, or this is not the class of defect
+    // this review exists to surface.
+    if (!isStr(f.self_undetectable)) {
+      e.push('self_undetectable is required — name what this artifact cannot detect about itself (R3)');
+    }
+    if (isMechanical(f)) {
+      e.push(`kind '${f.kind}' is mechanically findable and belongs to lint, not to this review (R3)`);
+    }
+
+    // Evidence is file:line, plural, and cited — an un-sourced finding is a guess.
+    if (!Array.isArray(f.evidence) || f.evidence.length === 0) {
+      e.push('evidence[] is required — at least one file:line citation');
+    } else {
+      f.evidence.forEach((ev, i) => {
+        if (!ev || typeof ev !== 'object') { e.push(`evidence[${i}] is not an object`); return; }
+        if (!isStr(ev.file)) e.push(`evidence[${i}].file is required`);
+        if (!Number.isInteger(ev.line) || ev.line < 1) e.push(`evidence[${i}].line must be a positive integer`);
+      });
+    }
+
+    // withheld is declared, never inferred — the containment guard must be explicit (R7).
+    if (typeof f.withheld !== 'boolean') {
+      e.push('withheld must be an explicit boolean (R7) — it is never inferred');
+    }
+    // A withheld finding carries no proposal at all. Carrying one invites a later refactor to
+    // "just render it disabled", which is exactly the failure dim 2 forbids.
+    if (f.withheld === true && f.proposal != null) {
+      e.push('a withheld finding must carry proposal: null — it has no change to offer (R7)');
+    }
+    if (f.withheld === true && !isStr(f.withheld_reason)) {
+      e.push('withheld_reason is required — say why this is yours to settle (R7)');
+    }
+
+    if (f.proposal != null) {
+      const p = f.proposal;
+      if (typeof p !== 'object') e.push('proposal must be an object or null');
+      else {
+        if (p.before != null && typeof p.before !== 'string') e.push('proposal.before must be a string or absent');
+        if (!isStr(p.after) && !isStr(p.before)) e.push('proposal must change something (before and/or after)');
+      }
+    }
+
+    return { ok: e.length === 0, errors: e };
+  }
+
+  /** Validate a whole review payload. One bad finding fails the review — partial trust is worse
+   *  than none on a surface whose only job is to be believed. */
+  function validateReview(r) {
+    const e = [];
+    if (!r || typeof r !== 'object') return { ok: false, errors: ['review is not an object'] };
+    if (!Array.isArray(r.read) || r.read.length === 0) {
+      e.push('read[] is required — the review states what it actually read (R2)');
+    }
+    if (!Array.isArray(r.findings)) {
+      e.push('findings[] is required (an empty array is a valid, and good, review — R10)');
+    } else {
+      r.findings.forEach((f, i) => {
+        const v = validateFinding(f);
+        if (!v.ok) v.errors.forEach((msg) => e.push(`findings[${i}]: ${msg}`));
+      });
+    }
+    return { ok: e.length === 0, errors: e };
+  }
+
+  /** Quiet-rate over a scored corpus (R10, rubric dim 1). Documents read with zero findings
+   *  against them, divided by documents believed clean. The rubric's binding number. */
+  function quietRate(reviewed, cleanPaths) {
+    const clean = new Set(cleanPaths || []);
+    if (clean.size === 0) return null;                  // no clean class ⇒ no valid precision number
+    let quiet = 0;
+    for (const p of clean) {
+      const noisy = (reviewed || []).some((f) => f && f.file === p);
+      if (!noisy) quiet++;
+    }
+    return quiet / clean.size;
+  }
+
+  /** Action rate (PRD success signal): Apply+Edit ÷ all dispositions. Dismiss-heavy means the
+   *  review is noise the PM is politely declining, whatever it scored. */
+  function actionRate(dispositions) {
+    const d = (dispositions || []).filter((x) => x === 'apply' || x === 'edit' || x === 'dismiss');
+    if (d.length === 0) return null;
+    return d.filter((x) => x !== 'dismiss').length / d.length;
+  }
+
+  return {
+    MECHANICAL_KINDS,
+    isMechanical,
+    isApplyable,
+    validateFinding,
+    validateReview,
+    quietRate,
+    actionRate,
+  };
+});

package/workspace/lib/git-info.js

@@ -0,0 +1,71 @@
+'use strict';
+// Read-mostly git helpers for the workspace (branch awareness + select/create at session start).
+// Everything here shells `git` via spawnSync with an ARGS ARRAY — never a shell string — so no
+// caller input is ever interpolated into a command line. A workspace's working tree is SHARED by
+// every session in it (D62), so a branch is a property of the REPO, not a session: switching moves
+// every session in that repo. Callers surface that truth; this module never pretends otherwise.
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const GIT_TIMEOUT = 5000;   // never let a slow/hung repo (huge tree, network remote) block the server
+
+function isRepo(root) {
+  // a normal repo has a `.git` dir; a linked worktree has a `.git` FILE — both count.
+  try { return !!root && fs.existsSync(path.join(root, '.git')); } catch { return false; }
+}
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT });
+  return { code: r.status, out: (r.stdout || '').trim(), err: (r.stderr || '').trim(), failed: !!r.error };
+}
+
+// git check-ref-format for a BRANCH name, re-implemented defensively so nothing dubious ever
+// reaches `git` (defense in depth — `git` itself is the final authority and rejects the rest).
+// Rejects: empty, whitespace/control, the special chars ~ ^ : ? * [ \ , the sequences .. and @{,
+// a leading '-' (would be read as a flag), leading/trailing '/' or '.', doubled '/', a trailing
+// '.lock', and the lone '@'. Allows the ordinary set A–Z a–z 0–9 . _ / -, e.g. initiative/foo-bar.
+function validBranchName(name) {
+  if (typeof name !== 'string') return false;
+  const n = name.trim();
+  if (!n || n.length > 200) return false;
+  if (/[\x00-\x20~^:?*[\\\s]/.test(n)) return false;   // control/space + git's forbidden set
+  if (n.includes('..') || n.includes('@{') || n.includes('//')) return false;
+  if (n === '@') return false;
+  if (n.startsWith('-') || n.startsWith('/') || n.startsWith('.')) return false;
+  if (n.endsWith('/') || n.endsWith('.') || n.endsWith('.lock')) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(n)) return false;
+  return true;
+}
+
+// { ok, current, branches[], detached, dirty }. A non-repo or a failed git returns ok:false with a
+// reason — NEVER a fabricated branch (a wrong branch chip is worse than none; anti-drift).
+function branchInfo(root) {
+  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, error: 'git not available' };
+  if (head.code !== 0) return { ok: false, error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  const current = detached ? null : head.out;
+  const refs = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+  const branches = refs.code === 0 && refs.out ? refs.out.split('\n').filter(Boolean) : [];
+  const status = git(root, ['status', '--porcelain']);
+  const dirty = status.code === 0 ? status.out.length > 0 : false;
+  return { ok: true, current, branches, detached, dirty };
+}
+
+// Check out an existing branch, or create one with -b. Confined to `root` by cwd; the name is
+// validated first so nothing malformed reaches git. On any failure returns { ok:false, error } and
+// leaves the caller to NOT spawn a session on the wrong branch (a failed checkout must never spawn).
+function checkout(root, branch, { create = false } = {}) {
+  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
+  if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
+  const args = create ? ['checkout', '-b', branch, '--'] : ['checkout', branch, '--'];
+  const r = git(root, args);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: (r.err || r.out || 'checkout failed').split('\n')[0].slice(0, 200) };
+  const info = branchInfo(root);
+  return { ok: true, current: info.ok ? info.current : branch };
+}
+
+module.exports = { isRepo, validBranchName, branchInfo, checkout };

package/workspace/lib/harness-parse.js

@@ -216,7 +216,11 @@ module.exports = {
   // 30s is a deliberate over-estimate: a false "quiet" is the failure that matters, because the
   // whole feature exists to stop the PM mistaking blocked for busy. Needs one field measurement
   // (the byte rate of a working session) to tighten — carried as an open question in the PRD.
-  QUIET_AFTER_MS: 30_000,
+  // Env-overridable so a suite can reproduce a stale-liveness defect in seconds instead of thirty;
+  // the shipped value is unchanged. The SERVER publishes this number in `hello` and the client
+  // reads it from there — it used to be re-typed as a literal in app.js, which is a threshold that
+  // can silently drift out of agreement with the one actually deriving the state.
+  QUIET_AFTER_MS: Number(process.env.PMOS_QUIET_AFTER_MS || 30_000),
   TAIL_BYTES,
   _internal: { lastWords, toolCounts, modelInfo, contextPct, tailLines, isToolCall, toolName },
 };