create-pmos 0.4.0 → 0.6.0

package/workspace/lib/remote-access.js

@@ -0,0 +1,235 @@
+'use strict';
+/*
+ * Remote (tailnet) access — the transport half of workspace-remote-tailnet.
+ *
+ * D62 is the locked security boundary: the workspace server owns real PTYs running the PM's
+ * Claude subscription, so it must NEVER be reachable from a public interface. This module makes
+ * "reach the SAME local server from my phone" possible over a PRIVATE Tailscale tailnet only:
+ *
+ *   1. Bind resolution — default is loopback ONLY (unchanged). With the opt-in remote flag on, the
+ *      server binds loopback PLUS the machine's own tailnet IPv4 (Tailscale CGNAT 100.64.0.0/10)
+ *      and NOTHING else. Any requested bind that is not loopback and not in 100.64.0.0/10 (e.g.
+ *      0.0.0.0, ::, a LAN or public IP) makes resolveBinds REFUSE — the server won't start. There
+ *      is no code path that yields a public bind address.
+ *   2. Token guard — when bound beyond loopback a bearer token is REQUIRED. Every non-loopback peer
+ *      (HTTP request or WS upgrade) must present it; loopback peers stay token-free for local dev.
+ *      Comparison is constant-time. The token is generated if not supplied and printed ONCE at
+ *      startup — never logged thereafter, and request headers are never logged (D08).
+ *
+ * Pure and side-effect-light so the guard logic is unit-testable without a live tailnet peer.
+ */
+const crypto = require('crypto');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const LOOPBACK = '127.0.0.1';
+
+// Strip an IPv4-mapped IPv6 prefix (::ffff:100.64.0.1) so one matcher handles both stacks.
+function unmap(addr) { return String(addr || '').replace(/^::ffff:/i, ''); }
+
+function parseIPv4(addr) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(unmap(addr));
+  if (!m) return null;
+  const o = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+  return o.some((n) => n > 255) ? null : o;
+}
+
+// Loopback = 127.0.0.0/8 (IPv4) or ::1 (IPv6). These peers are token-exempt.
+function isLoopbackAddr(addr) {
+  if (!addr) return false;
+  if (unmap(addr) === '::1') return true;
+  const o = parseIPv4(addr);
+  return !!o && o[0] === 127;
+}
+
+// The Tailscale tailnet lives in the CGNAT block 100.64.0.0/10 → first octet 100, second 64..127.
+// This is the ONLY non-loopback range the server is ever permitted to bind or trust.
+function isTailnetIp(addr) {
+  const o = parseIPv4(addr);
+  return !!o && o[0] === 100 && o[1] >= 64 && o[1] <= 127;
+}
+
+// Discover this machine's own tailnet IPv4. Prefers `tailscale ip -4`; falls back to scanning the
+// network interfaces for a 100.64.0.0/10 address; honours an explicit PMOS_TAILNET_IP override.
+// Injectable deps keep it testable and keep the spawn out of the non-remote (default/test) path.
+function detectTailnetIp({ env = process.env, netInterfaces = os.networkInterfaces, exec = spawnSync } = {}) {
+  const override = (env.PMOS_TAILNET_IP || '').trim();
+  if (override) return isTailnetIp(override) ? override : null;   // an explicit non-tailnet override is a mistake, not a fallback
+  try {
+    const r = exec('tailscale', ['ip', '-4'], { encoding: 'utf8', timeout: 4000 });
+    if (r && r.status === 0 && r.stdout) {
+      const ip = String(r.stdout).trim().split(/\s+/).find((x) => isTailnetIp(x));
+      if (ip) return ip;
+    }
+  } catch { /* tailscale not installed — fall through to the interface scan */ }
+  let ifaces = {};
+  try { ifaces = netInterfaces() || {}; } catch { ifaces = {}; }
+  for (const list of Object.values(ifaces)) {
+    for (const ni of (list || [])) {
+      const fam = ni && ni.family;
+      if ((fam === 'IPv4' || fam === 4) && isTailnetIp(ni.address)) return ni.address;
+    }
+  }
+  return null;
+}
+
+function remoteRequested(env) {
+  return env.PMOS_REMOTE === 'tailnet'
+    || env.PMOS_BIND_TAILNET === '1' || env.PMOS_BIND_TAILNET === 'true' || env.PMOS_BIND_TAILNET === 'yes';
+}
+
+// The one function that decides what the server may bind. Fail-closed: anything that is not
+// loopback or a tailnet address REFUSES (the server exits), so a public bind is unreachable by
+// construction. Returns {remote, binds, token, tailnetIp, generated} or {remote, refused:<msg>}.
+function resolveBinds({ env = process.env, detect = detectTailnetIp } = {}) {
+  if (!remoteRequested(env)) {
+    return { remote: false, binds: [LOOPBACK], token: null, tailnetIp: null, generated: false };
+  }
+  // An explicit bind address, when given, must itself be loopback or tailnet — never public.
+  const requested = (env.PMOS_BIND_ADDR || '').trim();
+  if (requested && !isLoopbackAddr(requested) && !isTailnetIp(requested)) {
+    return { remote: true, refused:
+      `refusing to bind "${requested}": only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted — never a public/default-route interface (D62).` };
+  }
+  const ip = (requested && isTailnetIp(requested)) ? requested : detect({ env });
+  if (!ip) {
+    return { remote: true, refused:
+      'PMOS_REMOTE=tailnet is set but no Tailscale tailnet address (100.64.0.0/10) was found. Start Tailscale (`tailscale up`) or set PMOS_TAILNET_IP to your tailnet IP. Refusing to bind any non-tailnet interface (D62).' };
+  }
+  if (!isTailnetIp(ip)) {   // belt-and-suspenders: detect must only ever yield a tailnet IP
+    return { remote: true, refused:
+      `refusing to bind "${ip}": not within the tailnet range 100.64.0.0/10 — never a public interface (D62).` };
+  }
+  const supplied = (env.PMOS_TOKEN || '').trim();
+  const token = supplied || crypto.randomBytes(32).toString('base64url');
+  return { remote: true, binds: [LOOPBACK, ip], token, tailnetIp: ip, generated: !supplied };
+}
+
+// ── Token extraction ──────────────────────────────────────────────────────────────────
+// HTTP: Authorization: Bearer <t>. (Node lowercases header names.)
+function extractHttpToken(headers = {}) {
+  const h = headers.authorization || headers.Authorization || '';
+  const m = /^Bearer\s+(.+)$/i.exec(String(h));
+  return m ? m[1].trim() : null;
+}
+// WS upgrade: a browser cannot set headers on a WebSocket, so accept, in order, an Authorization
+// header (non-browser clients), a ?token=/?access_token= query param, or a `bearer,<t>` subprotocol.
+function extractWsToken(req = {}) {
+  const headers = req.headers || {};
+  const fromHeader = extractHttpToken(headers);
+  if (fromHeader) return fromHeader;
+  try {
+    const u = new URL(req.url || '', 'http://localhost');
+    const q = u.searchParams.get('token') || u.searchParams.get('access_token');
+    if (q) return q.trim();
+  } catch { /* malformed URL → no token */ }
+  const proto = headers['sec-websocket-protocol'];
+  if (proto) {
+    const parts = String(proto).split(',').map((s) => s.trim()).filter(Boolean);
+    const i = parts.findIndex((p) => /^bearer$/i.test(p));
+    if (i >= 0 && parts[i + 1]) return parts[i + 1];
+  }
+  return null;
+}
+
+// ── Origin / Host allowlist (D64 / pivot-workspace-first, Track A1) ─────────────────────
+// The threat: the server owns real PTYs and, for loopback peers, is token-EXEMPT. Without an
+// Origin/Host check, any website the PM has open in their browser can open a WebSocket to
+// ws://127.0.0.1:<port> and send {t:'new'}+{t:'input'} to spawn a shell and type into it — a
+// cross-origin-localhost / DNS-rebinding remote-code-execution vector. These predicates close it:
+//   • a same-origin browser fetch/WS (served BY this server) sends an Origin equal to the Host it
+//     arrived on — allowed;
+//   • a cross-site page sends its OWN (foreign) Origin — rejected;
+//   • a DNS-rebinding attack forces a foreign Host header — rejected (the Host hostname must be
+//     loopback/localhost or a tailnet address, never an attacker's domain);
+//   • a native client / curl sends no Origin — allowed here, then still gated by the token guard.
+// Port-agnostic on purpose: the server may listen on any port, so an Origin is compared to the Host
+// it arrived on (true same-origin) rather than to a hard-coded port. Header VALUES are never logged.
+function hostnameOf(authority) {
+  let h = String(authority == null ? '' : authority).trim().toLowerCase();
+  if (!h) return '';
+  const scheme = h.indexOf('://');
+  if (scheme !== -1) h = h.slice(scheme + 3);
+  if (h[0] === '[') { const i = h.indexOf(']'); return i === -1 ? h.slice(1) : h.slice(1, i); }
+  return h.split('/')[0].split(':')[0];
+}
+function authorityOf(value) {
+  let h = String(value == null ? '' : value).trim().toLowerCase();
+  if (!h || h === 'null') return '';
+  const scheme = h.indexOf('://');
+  if (scheme !== -1) h = h.slice(scheme + 3);
+  return h.split('/')[0];   // host[:port]
+}
+function hostnameAllowed(authority, binds) {
+  const h = hostnameOf(authority);
+  if (!h) return false;
+  if (h === 'localhost') return true;
+  if (isLoopbackAddr(h)) return true;
+  for (const b of (binds || [])) if (isTailnetIp(b) && unmap(h) === unmap(b)) return true;
+  return false;
+}
+// The single decision, called from BOTH the HTTP guard and the WS-upgrade guard. Returns true when
+// the request is allowed to proceed (it may still be rejected by the token guard afterwards).
+function checkHostOrigin({ origin, host, binds }) {
+  // 1. If a Host header is present, its hostname must be loopback/localhost/tailnet (anti-rebinding).
+  if (host != null && host !== '') {
+    if (!hostnameAllowed(host, binds)) return false;
+  }
+  // 2. If an Origin header is present, it must be same-origin with the Host it arrived on, and its
+  //    hostname must itself be in the allowlist. "null"/opaque/garbage Origins are rejected.
+  if (origin != null && origin !== '') {
+    const oa = authorityOf(origin);
+    if (!oa) return false;
+    const ha = authorityOf(host);
+    if (ha && oa !== ha) return false;               // cross-origin → reject
+    if (!hostnameAllowed(oa, binds)) return false;   // Host absent but Origin foreign → reject
+  }
+  return true;
+}
+function isAllowedOrigin(origin, { host, binds } = {}) { return checkHostOrigin({ origin, host, binds }); }
+
+// Constant-time token comparison. Length is checked first (timingSafeEqual throws on a length
+// mismatch); a differing length is already a non-match, so this leaks nothing useful.
+function tokenMatches(presented, expected) {
+  if (!expected || !presented) return false;
+  const a = Buffer.from(String(presented));
+  const b = Buffer.from(String(expected));
+  if (a.length !== b.length) return false;
+  try { return crypto.timingSafeEqual(a, b); } catch { return false; }
+}
+
+// The single authorization decision, PEER-based (what matters is where the request came FROM, not
+// which listener it hit). Loopback is always exempt; every non-loopback peer must present a valid
+// bearer token. Fail-closed: with no token configured, a non-loopback peer is rejected.
+function authorize({ remoteAddress, presentedToken, expectedToken }) {
+  if (isLoopbackAddr(remoteAddress)) return true;
+  return tokenMatches(presentedToken, expectedToken);
+}
+
+// The startup banner lines. This is the ONE place a token may be printed, and ONLY a freshly
+// GENERATED token — a token supplied via PMOS_TOKEN is the PM's own secret and is never echoed.
+// Nothing here (or anywhere in this module) logs request headers (D08).
+function startupLines(bind, port) {
+  if (!bind || !bind.remote) {
+    return [`pmos workspace server — http://${LOOPBACK}:${port}  (loopback only, D62)`];
+  }
+  const lines = [
+    'pmos workspace server — REMOTE (tailnet) mode',
+    `  local:   http://${LOOPBACK}:${port}`,
+    `  tailnet: http://${bind.tailnetIp}:${port}   (private WireGuard net, device-authenticated, never public — D62)`,
+  ];
+  if (bind.generated) {
+    lines.push(`  token (generated — shown ONCE, copy it now): ${bind.token}`);
+    lines.push('  attach with header  Authorization: Bearer <token>   or query  ?token=<token>');
+  } else {
+    lines.push('  token: using PMOS_TOKEN from the environment (not shown)');
+  }
+  lines.push('  loopback requests are token-free; every tailnet request must present the token.');
+  return lines;
+}
+
+module.exports = {
+  LOOPBACK, isLoopbackAddr, isTailnetIp, detectTailnetIp, remoteRequested,
+  resolveBinds, extractHttpToken, extractWsToken, tokenMatches, authorize, startupLines,
+  checkHostOrigin, isAllowedOrigin, hostnameAllowed,
+};

package/workspace/lib/review-gate.js

@@ -0,0 +1,39 @@
+'use strict';
+/*
+ * CANONICAL Review-Gate pass rule — the single source of truth (D64 / pivot-workspace-first, Track D2).
+ *
+ * The rule is:  an explicit verdict DECIDES (pass iff it starts with "pass"); the score is a
+ * fallback used ONLY when no verdict was recorded (score >= 0.85).
+ *
+ * AMENDED 2026-07-26 (blind-plant round 2 finding). The rule was previously
+ * `verdict ILIKE 'pass%' OR score >= 0.85`, and that disjunction was a real leniency hole: a run the
+ * evaluator explicitly FAILED still passed the gate if its weighted score happened to clear 0.85.
+ * Round 2 hit it live — specimen `be58` came back verdict=FAIL score=0.93 and the old rule counted it
+ * pass-side, overriding a FAIL issued under the two-axis rule ("a FAIL on either axis cannot become a
+ * PASS"). A gate whose plumbing can overturn its own judge is not a gate. See
+ * planning/evals/blind-plants/2026-07-26-round2/RESULTS.md.
+ *
+ * Note the fix is NOT a blunt OR->AND: that would wrongly fail a legitimate `PASS` verdict carrying no
+ * recorded score. Verdict-authoritative-with-score-fallback preserves every other case and changes
+ * exactly the one that was broken.
+ *
+ * It was previously duplicated verbatim across SQL views, TS, the workspace JS, and metrics.py, so a
+ * change in one place silently drifted the others. It now lives HERE and is mirrored in exactly one
+ * other place — kit/scripts/metrics.py's `review_gate_pass()` — with a comment pointing back here.
+ * kit/fixtures/test_parsers.py runs BOTH implementations against kit/fixtures/review-gate-pass-rule.json
+ * and fails CI if they ever disagree, so the mirror can never drift unnoticed.
+ */
+const PASS_VERDICT_PREFIX = 'pass';   // ILIKE 'pass%' → lowercased startsWith('pass')
+const SCORE_THRESHOLD = 0.85;
+
+// A recorded verdict is AUTHORITATIVE: the run passes iff that verdict starts with "pass"
+// (PASS / PASS-WITH-FINDINGS / …). An explicit FAIL is never overridden by a high score.
+// Only when NO verdict was recorded (null / "" / whitespace) does the numeric score decide.
+function isReviewPass(verdict, score) {
+  const v = String(verdict == null ? '' : verdict).trim().toLowerCase();
+  if (v) return v.startsWith(PASS_VERDICT_PREFIX);
+  const s = Number(score);
+  return Number.isFinite(s) && s >= SCORE_THRESHOLD;
+}
+
+module.exports = { isReviewPass, PASS_VERDICT_PREFIX, SCORE_THRESHOLD };

package/workspace/lib/schedule-logic.js

@@ -0,0 +1,132 @@
+'use strict';
+/* schedule-logic.js — the pure cadence math for scheduled tasks.
+ *
+ * Harvested from pm-os `do-worker/src/schedule-logic.mjs`: no I/O, no globals, importable by the
+ * server tick AND (conceptually) the GUI's "next run" preview — so what the PM is shown is exactly
+ * what will fire. Window-based due-ness, NO catch-up (a missed slot is skipped, per the PRD): a
+ * schedule is due iff a scheduled slot falls in the interval (lastRun, now].
+ *
+ * A schedule: { cadence:'daily'|'weekly'|'bi-weekly'|'monthly', day:'Mon'..'Sun' (weekly/bi-weekly),
+ *   dayOfMonth:1..28 (monthly), time:'HH:MM', enabled, lastRun:ISO|null }. Times are host-local (v1).
+ */
+
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];   // JS getDay() index
+const CADENCES = ['daily', 'weekly', 'bi-weekly', 'monthly'];
+
+function parseTime(t) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(t || '09:00'));
+  if (!m) return { h: 9, m: 0 };
+  return { h: Math.min(23, +m[1]), m: Math.min(59, +m[2]) };
+}
+function atTime(d, time) {
+  const { h, m } = parseTime(time);
+  const x = new Date(d);
+  x.setHours(h, m, 0, 0);
+  return x;
+}
+function dayIndex(day) { const i = DAYS.indexOf(String(day)); return i < 0 ? 1 : i; }   // default Mon
+
+// The most recent scheduled slot at or before `now` (Date), or null if none exists yet.
+function lastSlot(schedule, now) {
+  const cad = schedule.cadence;
+  if (cad === 'daily') {
+    const today = atTime(now, schedule.time);
+    return today <= now ? today : addDays(today, -1);
+  }
+  if (cad === 'weekly' || cad === 'bi-weekly') {
+    // walk back from today to the most recent matching weekday at time
+    const want = dayIndex(schedule.day);
+    let d = atTime(now, schedule.time);
+    for (let i = 0; i < 8; i++) {
+      if (d.getDay() === want && d <= now) return d;
+      d = addDays(d, -1);
+    }
+    return null;
+  }
+  if (cad === 'monthly') {
+    const dom = Math.min(28, Math.max(1, +schedule.dayOfMonth || 1));
+    let d = atTime(now, schedule.time); d.setDate(dom);
+    if (d > now) { d = new Date(d); d.setMonth(d.getMonth() - 1); d.setDate(dom); }
+    return d;
+  }
+  return null;
+}
+// The next scheduled slot strictly after `now`.
+function nextSlot(schedule, now) {
+  const cad = schedule.cadence;
+  if (cad === 'daily') {
+    const today = atTime(now, schedule.time);
+    return today > now ? today : addDays(today, 1);
+  }
+  if (cad === 'weekly' || cad === 'bi-weekly') {
+    const want = dayIndex(schedule.day);
+    let d = atTime(now, schedule.time);
+    for (let i = 0; i < 8; i++) {
+      if (d.getDay() === want && d > now) return d;
+      d = addDays(d, 1);
+    }
+    return null;
+  }
+  if (cad === 'monthly') {
+    const dom = Math.min(28, Math.max(1, +schedule.dayOfMonth || 1));
+    let d = atTime(now, schedule.time); d.setDate(dom);
+    if (d <= now) { d = new Date(d); d.setMonth(d.getMonth() + 1); d.setDate(dom); }
+    return d;
+  }
+  return null;
+}
+function addDays(d, n) { const x = new Date(d); x.setDate(x.getDate() + n); return x; }
+
+// Is the schedule due to fire at `now`? Enabled + a slot in (lastRun, now]. For bi-weekly, also
+// require ≥ 13 days since lastRun (weekly slots, fired every other week).
+function isDue(schedule, now = new Date()) {
+  if (!schedule || !schedule.enabled) return false;
+  const slot = lastSlot(schedule, now);
+  if (!slot) return false;
+  const last = schedule.lastRun ? new Date(schedule.lastRun) : null;
+  if (last && last >= slot) return false;
+  if (schedule.cadence === 'bi-weekly' && last) {
+    if ((now - last) / 86400000 < 13) return false;
+  }
+  return true;
+}
+// The next fire time as an ISO string (or null).
+function nextRun(schedule, now = new Date()) {
+  const s = nextSlot(schedule, now);
+  return s ? s.toISOString() : null;
+}
+// A short human phrase for the pane, e.g. "every Fri at 09:00".
+function humanCadence(schedule) {
+  const t = schedule.time || '09:00';
+  switch (schedule.cadence) {
+    case 'daily': return `every day at ${t}`;
+    case 'weekly': return `every ${schedule.day || 'Mon'} at ${t}`;
+    case 'bi-weekly': return `every other ${schedule.day || 'Mon'} at ${t}`;
+    case 'monthly': return `monthly on day ${schedule.dayOfMonth || 1} at ${t}`;
+    default: return schedule.cadence || '';
+  }
+}
+// Validate/normalize a schedule submitted by the client. Returns { ok, schedule } or { ok:false, error }.
+function normalizeSchedule(input) {
+  const s = input || {};
+  if (!s.name || !String(s.name).trim()) return { ok: false, error: 'name is required' };
+  if (!CADENCES.includes(s.cadence)) return { ok: false, error: 'invalid cadence' };
+  if (!s.skill || !String(s.skill).trim()) return { ok: false, error: 'a skill-backed task is required' };
+  return {
+    ok: true,
+    schedule: {
+      name: String(s.name).trim().slice(0, 80),
+      cadence: s.cadence,
+      day: s.day || 'Mon',
+      dayOfMonth: Math.min(28, Math.max(1, +s.dayOfMonth || 1)),
+      time: parseTimeStr(s.time),
+      tz: s.tz || 'local',
+      task: s.task || s.skill,
+      skill: String(s.skill).trim(),
+      enabled: s.enabled !== false,
+    },
+  };
+}
+function parseTimeStr(t) { const { h, m } = parseTime(t); return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`; }
+
+module.exports = { CADENCES, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };

package/workspace/lib/skill-store.js

@@ -0,0 +1,143 @@
+'use strict';
+/* skill-store.js — file-driven skills. ONE user-facing concept.
+ *
+ * A "skill" is a named, repeatable task with a consistent-output contract. HOW it runs — the server
+ * derives it instantly, or a `claude` PTY session reasons through it — is an INTERNAL field (`run:`)
+ * the picker never exposes. That collapses the old deterministic-vs-agent "kind" leak the PM (rightly)
+ * found confusing (workspace-skill-authoring): from the user's view there is just a skill.
+ *
+ * A skill file (`*.skill`) is frontmatter + a body procedure:
+ *   - frontmatter: name, description, and an `output` list = the section keys it ALWAYS produces
+ *     (the consistency contract, mirroring the surface-contract shape check).
+ *   - body: the procedure. For an agent skill this is the prompt fed to the session; for a built-in
+ *     deterministic skill the body is documentation (the server derives the output from `surface`).
+ *
+ * Built-in skills ship committed under workspace/skills/; user-authored skills are scaffolded by the
+ * New Skill flow into a writable dir (state/skills/, gitignored like other state). Pure of the network
+ * (D54) — fs only, no deps, unit-testable directly.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// A skill name is a short slug — it is both the id and the filename stem, so it must be path-safe.
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+const MAX_OUTPUT = 20;
+
+function slugify(s) {
+  return String(s || '').toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+}
+function titleCase(s) {
+  return String(s || '').replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function stripQuotes(v) { return String(v).replace(/^["']|["']$/g, ''); }
+
+// A permissive mini-parser: an optional leading `---` frontmatter block (scalar `key: value` and
+// one-level `- ` lists), then the body. No YAML dependency — the format is deliberately tiny and
+// self-explanatory (the ACI design principle, D19). Unknown keys are tolerated.
+function parseSkill(text) {
+  const src = String(text || '');
+  const fm = {}; const lists = {};
+  let body = src.trim();
+  const lines = src.split('\n');
+  if (lines[0] && lines[0].trim() === '---') {
+    let curList = null; let closed = false; let bodyStart = 1;
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.trim() === '---') { bodyStart = i + 1; closed = true; break; }
+      const item = line.match(/^\s*-\s+(.*)$/);
+      if (item && curList) { lists[curList].push(item[1].trim()); continue; }
+      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+      if (kv) {
+        const key = kv[1]; const val = kv[2].trim();
+        if (val === '') { curList = key; lists[key] = lists[key] || []; }
+        else { fm[key] = stripQuotes(val); curList = null; }
+      }
+    }
+    if (closed) body = lines.slice(bodyStart).join('\n').trim();
+  }
+  const name = fm.name || '';
+  // `run` is the ONLY internal signal: deterministic (server fast-path) vs agent (a PTY session).
+  const run = /^det/i.test(fm.run || '') ? 'deterministic' : 'agent';
+  return {
+    name,
+    label: fm.label || titleCase(name),
+    description: fm.description || '',
+    run,
+    surface: fm.surface || null,
+    agent: fm.agent || 'claude',
+    output: (lists.output || []).filter(Boolean).slice(0, MAX_OUTPUT),
+    body,
+  };
+}
+
+function loadDir(dir, source) {
+  const out = [];
+  let ents = [];
+  try { ents = fs.readdirSync(dir); } catch { return out; }
+  for (const f of ents.sort()) {
+    if (!f.endsWith('.skill')) continue;
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    const s = parseSkill(text);
+    const id = s.name || f.replace(/\.skill$/, '');
+    if (!NAME_RE.test(id)) continue;   // an unparseable/hostile filename never becomes a skill
+    out.push({ ...s, name: id, id, skill: id, source, file: path.join(dir, f) });
+  }
+  return out;
+}
+
+// Merge a list of {dir, source} — LATER dirs override earlier by id. Callers pass user dirs first and
+// built-ins last, so a built-in's load-bearing fast-path can never be shadowed by a user file.
+function loadSkills(dirs) {
+  const byId = new Map();
+  for (const { dir, source } of dirs) for (const s of loadDir(dir, source)) byId.set(s.id, s);
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// Scaffold a well-formed user skill file from the New Skill flow's fields. Returns { ok, slug, content }
+// or { ok:false, error }. User skills default to run:agent — a user-authored skill reasons through a
+// claude session (the existing agent path); the deterministic fast-path is reserved for the built-ins.
+function scaffoldSkill({ name, description, output, body } = {}) {
+  const slug = slugify(name);
+  if (!NAME_RE.test(slug)) return { ok: false, error: 'name must be a short slug (letters, digits, hyphens)' };
+  const label = titleCase(name) || slug;
+  const desc = String(description || '').replace(/[\r\n]+/g, ' ').trim().slice(0, 240);
+  let out = Array.isArray(output) ? output : String(output || '').split(/[\n,]/);
+  out = out.map((x) => String(x).replace(/\s+/g, ' ').trim()).filter(Boolean).slice(0, MAX_OUTPUT);
+  if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
+  const proc = String(body || '').trim() || defaultBody(label, desc, out);
+  const content = [
+    '---',
+    `name: ${slug}`,
+    `label: ${JSON.stringify(label)}`,
+    `description: ${JSON.stringify(desc)}`,
+    'run: agent',
+    'agent: claude',
+    'output:',
+    ...out.map((o) => `  - ${o}`),
+    '---',
+    '',
+    proc,
+    '',
+  ].join('\n');
+  return { ok: true, slug, label, description: desc, output: out, content };
+}
+
+function defaultBody(label, desc, out) {
+  return [
+    `You are running the "${label}" skill in this PMOS workspace (local, file mode).`,
+    '',
+    `Goal: ${desc || '(describe what this skill should do)'}`,
+    '',
+    'Produce a deliverable with EXACTLY these sections — the consistency contract, the same shape',
+    'every run:',
+    ...out.map((o) => `  - ${o}`),
+    '',
+    'Ground everything in this repository\'s own local files and tools only (no network). When you are',
+    'done, write the deliverable and file a short note to needs-you so the PM sees the result.',
+  ].join('\n');
+}
+
+module.exports = { NAME_RE, slugify, titleCase, parseSkill, loadDir, loadSkills, scaffoldSkill };

package/workspace/lib/surface-contract.js

@@ -0,0 +1,79 @@
+'use strict';
+/* surface-contract.js — the deliverable contract for on-demand workspace surfaces.
+ *
+ * Harvested from pm-os `do-worker/src/deliverable-contract.mjs` (the pm-os intake, Cluster J / J1):
+ * each surface TYPE declares the shape it must carry, and a deterministic check validates a surface
+ * BEFORE it renders — so "reliable when the PM needs it" is ENFORCED, not hoped. Pure: no I/O, no
+ * DOM, no deps, importable by the server and unit-tested directly.
+ *
+ * A required item FIELD may be null — that means "not tracked in state yet" (RICE/effort/…), and the
+ * renderer shows "— not tracked" for it. The contract only insists the KEY exists, so the surface can
+ * never silently drop a field; it can only honestly say it doesn't have the value. The `min` on the
+ * primary collection is the "can't-produce" floor: a surface with nothing to show fails the contract
+ * and the client renders the explicit can't-produce state instead of a blank or partial view.
+ */
+
+const CONTRACTS = Object.freeze({
+  initiatives: {
+    label: 'Initiative list',
+    top: ['initiatives', 'pulse', 'needs'],
+    item: { key: 'initiatives', min: 1, fields: ['id', 'status', 'phase'] },
+  },
+  roadmap: {
+    label: 'Roadmap',
+    top: ['groups'],
+    item: { key: 'groups', min: 1, fields: ['label', 'items'] },
+  },
+  okr: {
+    label: 'OKR + levers',
+    top: ['objectives'],
+    item: { key: 'objectives', min: 1, fields: ['id', 'krs'] },
+  },
+  report: {
+    label: 'Report',
+    top: ['cadence', 'sections'],
+    item: { key: 'sections', min: 3, fields: ['heading'] },
+  },
+});
+
+function checkSurface(type, data) {
+  const c = CONTRACTS[type];
+  if (!c) {
+    return { pass: false, missing: ['contract'],
+      checks: [{ name: 'known-type', pass: false, reason: `no contract for surface "${type}"` }] };
+  }
+  data = data || {};
+  const checks = [];
+  const missing = [];
+
+  // 1) required top-level keys are present
+  for (const k of c.top) {
+    const present = data[k] !== undefined && data[k] !== null;
+    checks.push({ name: `has:${k}`, pass: present, reason: present ? 'present' : 'absent' });
+    if (!present) missing.push(k);
+  }
+
+  // 2) the primary collection carries at least `min` items (the can't-produce floor)
+  const it = c.item;
+  const arr = Array.isArray(data[it.key]) ? data[it.key] : [];
+  const enough = arr.length >= it.min;
+  checks.push({ name: `min:${it.key}`, pass: enough, reason: `${arr.length} / ${it.min} required` });
+  if (!enough) missing.push(it.key);
+
+  // 3) every item carries its required field KEYS (a null value = "not tracked", still valid)
+  let fieldOk = true;
+  let offendingField = null;
+  for (const item of arr) {
+    for (const f of it.fields) {
+      if (!item || !Object.prototype.hasOwnProperty.call(item, f)) { fieldOk = false; offendingField = f; break; }
+    }
+    if (!fieldOk) break;
+  }
+  checks.push({ name: 'item-fields', pass: fieldOk,
+    reason: fieldOk ? `every item carries ${it.fields.join(', ')}` : `an item is missing "${offendingField}"` });
+  if (!fieldOk) missing.push('item-fields');
+
+  return { pass: checks.every((x) => x.pass), missing, checks };
+}
+
+module.exports = { CONTRACTS, checkSurface };