create-pmos 0.38.8 → 0.40.0

package/workspace/lib/typesafe.js

@@ -0,0 +1,124 @@
+'use strict';
+/* typesafe.js — the ONE place the workspace server makes an outbound request (D79).
+ *
+ * D69, D70 and D71 say the PMOS server makes no outbound request. D79 narrows that by one named
+ * exception: HTTPS to `api.typesafe.ai`, from this module, and nowhere else. Three properties keep the
+ * exception small, and each has a test:
+ *
+ *   1. ONE HOST, FIXED IN SOURCE. The host is a constant. No argument, setting or environment variable
+ *      names it. A response that redirects is REFUSED, not followed, because a redirect is how a fixed
+ *      host becomes another host.
+ *   2. THE KEY LEAVES THIS PROCESS IN ONE HEADER. It is an argument to `ask`, never stored here, never
+ *      placed in an error, a log line or a returned object.
+ *   3. NO KEY, NO REQUEST. `ask` refuses before opening a socket when the key is absent.
+ *
+ * What Jev is: a classifier. The caller sends text (`state`) and typed questions; it returns answers
+ * with probabilities. It reads no files and takes no action — the caller reads the files.
+ *   Noul    "high means yes"; the single `noul` number is P(yes). There is no separate confidence.
+ *   Score   levels 0..N-1; `score` is the probability-weighted mean; `confidence` is reported.
+ *   Choice  one option plus a distribution.
+ */
+const https = require('https');
+const http = require('http');
+
+const HOST = 'api.typesafe.ai';
+const PATH = '/v1/systemone';
+const DEFAULT_MODEL = 'jev-latest';
+const MAX_STATE_CHARS = 60000;       // a conservative cap; the documentation states no limit
+const MAX_RESPONSE_BYTES = 1 << 20;  // 1 MiB — an answer set is small; anything larger is not one
+const MAX_QUESTIONS = 16;
+
+/* A seam for tests, gated like the sink's. It lets a suite point this module at a loopback stub; it
+ * is unreachable in a production process, so no setting can redirect the key to another host. */
+let endpointForTests = null;
+function __setEndpointForTests(e) {
+  const on = (v) => v === '1' || v === 'true' || v === 'yes';
+  if (process.env.NODE_ENV !== 'test' && !on(process.env.PMOS_TEST)) {
+    throw new Error('__setEndpointForTests is a test seam — set NODE_ENV=test or PMOS_TEST=1 to use it');
+  }
+  endpointForTests = e || null;
+}
+function endpoint() {
+  return endpointForTests || { protocol: 'https:', hostname: HOST, port: 443 };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const retryable = (status) => status === 429 || status === 529 || (status >= 500 && status < 600);
+
+function validKey(key) {
+  return typeof key === 'string' && key.length >= 8 && key.length <= 512 && !/[\s\u0000-\u001f\u007f]/.test(key);
+}
+
+function once({ key, body, timeoutMs }) {
+  const ep = endpoint();
+  const mod = ep.protocol === 'http:' ? http : https;
+  const payload = Buffer.from(body, 'utf8');
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    const req = mod.request({
+      protocol: ep.protocol, hostname: ep.hostname, port: ep.port, path: PATH, method: 'POST',
+      headers: {
+        'Content-Type': 'application/json', 'Content-Length': payload.length,
+        Authorization: 'Bearer ' + key, 'User-Agent': 'pmos-workspace',
+      },
+      timeout: timeoutMs,
+    }, (res) => {
+      const status = res.statusCode || 0;
+      // Refused, not followed: the host is fixed in source and a redirect would change it.
+      if (status >= 300 && status < 400) { res.resume(); return finish({ ok: false, status, reason: 'the service sent a redirect, which is refused' }); }
+      const chunks = []; let size = 0;
+      res.on('data', (c) => {
+        size += c.length;
+        if (size > MAX_RESPONSE_BYTES) { finish({ ok: false, status, reason: 'the response was larger than expected and was dropped' }); req.destroy(); return; }
+        chunks.push(c);
+      });
+      res.on('end', () => {
+        let json = null;
+        try { json = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { /* not JSON */ }
+        if (status >= 200 && status < 300 && json && typeof json.answers === 'object' && json.answers) {
+          return finish({ ok: true, status, model: String(json.model || ''), answers: json.answers, usage: json.usage || null });
+        }
+        const why = status === 401 ? 'the service rejected the key (401)'
+          : status === 422 ? 'the service rejected the request as malformed (422)'
+          : status === 429 ? 'the service rate-limited the request (429)'
+          : status === 529 ? 'the service is overloaded (529)'
+          : `the service answered ${status || 'with something unreadable'}`;
+        finish({ ok: false, status, reason: why });
+      });
+      res.on('error', () => finish({ ok: false, status, reason: 'the connection broke while reading the answer' }));
+    });
+    req.on('timeout', () => { finish({ ok: false, status: 0, reason: 'the service did not answer in time' }); req.destroy(); });
+    req.on('error', (e) => finish({ ok: false, status: 0, reason: 'the service could not be reached (' + String((e && e.code) || 'network error') + ')' }));
+    req.end(payload);
+  });
+}
+
+/**
+ * Ask Jev typed questions about `state`.
+ *
+ * @param {object} a
+ * @param {string} a.key        the API key. Required; no key means no request.
+ * @param {string} a.state      the text to judge. Refused above MAX_STATE_CHARS.
+ * @param {object} a.questions  { name: { type: 'noul'|'score'|'choice', instructions, criteria? } }
+ * @returns {Promise<{ok:true, model, answers, usage}|{ok:false, reason, status?, requested:boolean}>}
+ *   `requested` says whether a request left this process, so a caller can tell a refusal from a failure.
+ */
+async function ask({ key, state, questions, model = DEFAULT_MODEL, timeoutMs = 30000, retries = 2, backoffMs = 600 } = {}) {
+  if (!validKey(key)) return { ok: false, requested: false, reason: 'no TypeSafe key is set' };
+  if (typeof state !== 'string' || !state.trim()) return { ok: false, requested: false, reason: 'there is no text to judge' };
+  if (state.length > MAX_STATE_CHARS) return { ok: false, requested: false, reason: `the text is longer than ${MAX_STATE_CHARS} characters` };
+  const names = questions && typeof questions === 'object' ? Object.keys(questions) : [];
+  if (!names.length || names.length > MAX_QUESTIONS) return { ok: false, requested: false, reason: `between 1 and ${MAX_QUESTIONS} questions are required` };
+  const body = JSON.stringify({ state, model, questions });
+  let last = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    last = await once({ key, body, timeoutMs });
+    if (last.ok) return { ...last, requested: true };
+    if (!(last.status === 0 || retryable(last.status)) || attempt === retries) break;
+    await sleep(backoffMs * Math.pow(2, attempt));
+  }
+  return { ok: false, requested: true, status: last.status, reason: last.reason };
+}
+
+module.exports = { ask, validKey, HOST, PATH, DEFAULT_MODEL, MAX_STATE_CHARS, MAX_QUESTIONS, __setEndpointForTests };

package/workspace/lib/validate.js

@@ -0,0 +1,304 @@
+'use strict';
+/* validate.js — judge a repository's documents for reliability, coherence and freshness (D79).
+ *
+ * Order matters, and it is the cost and egress control:
+ *   1. LOCAL FIRST. Links that point nowhere, a `stale_after` date that has passed, and the workflow sweep
+ *      run on this machine and send nothing.
+ *   2. WITHHOLD. Every text is scanned for credential shapes. A text that matches is never sent and is
+ *      listed by file and rule name.
+ *   3. JUDGE. Only what is left goes to Jev, as typed questions, one request per document or per pair.
+ *
+ * Nothing here edits a repository file, a decision or an acceptance. The only write is one append-only
+ * line per finding in a ledger the caller names, through the sink guard.
+ *
+ * What a number means (Jev's own semantics, see lib/typesafe.js): a Noul answer is P(yes) and carries no
+ * separate confidence, so `confidence` here is DERIVED as |2p - 1| and says so. A Score answer reports its
+ * own confidence. Every Noul question is phrased so that a high value means a problem.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const crypto = require('crypto');
+const scanner = require('./secret-scan');
+const settings = require('./typesafe-settings');
+const typesafe = require('./typesafe');
+const { createSinkGuard } = require('./sink');
+
+const MAX_DOCS = 40;               // single-document requests per run
+const MAX_PAIRS = 10;              // two-document requests per run
+const MAX_DOC_BYTES = 200 * 1024;  // a larger document is listed, not sent
+const SNIPPET_DOC = 24000;         // characters of one document in a request
+const SNIPPET_PAIR = 6000;         // characters of each document in a pair request
+const AGING_DAYS = 120;            // git age after which a document is asked whether it is out of date
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'vendor']);
+
+/* ── reading the repository ────────────────────────────────────────────────────────────────── */
+function listMarkdown(root) {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--', '*.md'], { cwd: root, maxBuffer: 32 << 20, stdio: ['ignore', 'pipe', 'ignore'] });
+    const files = out.toString('utf8').split('\0').filter(Boolean);
+    if (files.length) return files.sort();
+  } catch { /* not a git checkout, or git is absent */ }
+  const found = [];
+  (function walk(dir, rel) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name), rel ? rel + '/' + e.name : e.name); }
+      else if (e.name.endsWith('.md')) found.push(rel ? rel + '/' + e.name : e.name);
+    }
+  })(root, '');
+  return found.sort();
+}
+
+function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const fm = {};
+  if (!m) return fm;
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) fm[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+function gitAgeDays(root, rel, now) {
+  try {
+    const out = execFileSync('git', ['log', '-1', '--format=%ct', '--', rel], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    const t = Number(out);
+    return t > 0 ? Math.floor((now - t * 1000) / 86400000) : null;
+  } catch { return null; }
+}
+
+function linksOf(text) {
+  const body = text.replace(/```[\s\S]*?```/g, '');
+  const out = [];
+  const re = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  let m;
+  while ((m = re.exec(body))) out.push(m[1]);
+  return out;
+}
+
+function resolveLink(root, docRel, target) {
+  if (!target || /^(?:[a-z][a-z0-9+.-]*:|#|\/\/)/i.test(target)) return null;
+  const clean = decodeURI(target.split('#')[0].split('?')[0]);
+  if (!clean) return null;
+  const abs = clean.startsWith('/') ? path.join(root, clean) : path.join(root, path.dirname(docRel), clean);
+  const rel = path.relative(root, abs).split(path.sep).join('/');
+  return rel.startsWith('..') ? null : rel;
+}
+
+/* ── the survey: what exists, what is excluded, what is withheld, what is flagged locally ──────── */
+function survey(root, exclude, now) {
+  const all = listMarkdown(root);
+  const docs = [], withheld = [], tooLarge = [];
+  let excluded = 0;
+  for (const rel of all) {
+    if (settings.isExcluded(exclude, rel)) { excluded++; continue; }
+    const full = path.join(root, rel);
+    let st;
+    try { st = fs.lstatSync(full); } catch { continue; }
+    if (!st.isFile()) continue;
+    if (st.size > MAX_DOC_BYTES) { tooLarge.push(rel); continue; }
+    let text;
+    try { text = fs.readFileSync(full, 'utf8'); } catch { continue; }
+    const hits = scanner.scan(text);
+    if (hits.length) { withheld.push({ file: rel, rules: hits }); continue; }
+    docs.push({ rel, text, fm: frontmatter(text) });
+  }
+  const have = new Set(docs.map((d) => d.rel));
+  const deterministic = [];
+  const today = new Date(now).toISOString().slice(0, 10);
+  for (const d of docs) {
+    const broken = [];
+    for (const t of linksOf(d.text)) {
+      const r = resolveLink(root, d.rel, t);
+      if (r && !fs.existsSync(path.join(root, r))) broken.push(t);
+    }
+    for (const t of broken.slice(0, 5)) {
+      deterministic.push({ file: d.rel, rule: 'broken-link', severity: 'medium', detail: `links to ${t}, which does not exist` });
+    }
+    d.flagged = broken.length > 0;
+    if (/^\d{4}-\d{2}-\d{2}/.test(d.fm.stale_after || '') && d.fm.stale_after.slice(0, 10) < today) {
+      deterministic.push({ file: d.rel, rule: 'stale-after-passed', severity: 'medium', detail: `stale_after ${d.fm.stale_after.slice(0, 10)} has passed` });
+      d.flagged = true; d.aging = true;
+    }
+  }
+  return { docs, have, withheld, tooLarge, excluded, deterministic, total: all.length };
+}
+
+/* ── the questions. Every Noul is phrased so that a high value means a problem. ──────────────── */
+const Q = {
+  self_contradiction: { type: 'noul', rule: 'self-contradiction', kind: 'coherence',
+    instructions: 'The document contradicts itself: two of its statements cannot both be true.' },
+  unclear_purpose: { type: 'noul', rule: 'unclear-purpose', kind: 'structure',
+    instructions: 'A reader cannot tell from the opening of this document what it is for or who should read it.' },
+  padding: { type: 'score', rule: 'padding', kind: 'tone',
+    instructions: 'How succinct, specific and direct the writing is.',
+    criteria: ['Rambling, vague, hedged or padded; much could be cut', 'Mostly clear, with some padding or hedging', 'Succinct, specific and direct'] },
+  outdated: { type: 'noul', rule: 'possibly-outdated', kind: 'freshness',
+    instructions: 'The document describes things that are probably out of date: it treats past dates, versions or plans as current.' },
+  conflict: { type: 'noul', rule: 'conflicting-documents', kind: 'coherence',
+    instructions: 'The two documents state conflicting facts about the same thing.' },
+  unsupported: { type: 'noul', rule: 'unsupported-claim', kind: 'reliability',
+    instructions: 'The first document states claims that the second document, which it cites as its source, does not support or contradicts.' },
+};
+const wire = (names) => Object.fromEntries(names.map((n) => {
+  const q = Q[n]; const o = { type: q.type, instructions: q.instructions };
+  if (q.criteria) o.criteria = q.criteria;
+  return [n, o];
+}));
+
+/* ── the plan: what a run WOULD send. No network, no write. ───────────────────────────────────── */
+function buildRequests(root, sv, now) {
+  const docs = sv.docs.slice().sort((a, b) => (b.flagged ? 1 : 0) - (a.flagged ? 1 : 0) || a.rel.localeCompare(b.rel)).slice(0, MAX_DOCS);
+  const requests = [];
+  for (const d of docs) {
+    const age = gitAgeDays(root, d.rel, now);
+    const aging = d.aging || (age != null && age > AGING_DAYS);
+    const names = ['self_contradiction', 'unclear_purpose', 'padding'].concat(aging ? ['outdated'] : []);
+    requests.push({ kind: 'doc', files: [d.rel], names, state: d.text.slice(0, SNIPPET_DOC) });
+  }
+  const pairs = new Map();
+  const add = (a, b, name) => {
+    if (a === b || !sv.have.has(a) || !sv.have.has(b)) return;
+    const key = name === 'unsupported' ? a + '\0' + b : [a, b].sort().join('\0');
+    const p = pairs.get(key) || { a: name === 'unsupported' ? a : key.split('\0')[0], b: name === 'unsupported' ? b : key.split('\0')[1], names: new Set() };
+    p.names.add(name); pairs.set(key, p);
+  };
+  for (const d of sv.docs) {
+    for (const t of linksOf(d.text)) { const r = resolveLink(root, d.rel, t); if (r) add(d.rel, r, 'conflict'); }
+    for (const s of String(d.fm.sources || '').replace(/^\[|\]$/g, '').split(',')) {
+      const r = resolveLink(root, d.rel, s.trim()) || (s.trim() ? s.trim().replace(/^\/+/, '') : null);
+      if (r) add(d.rel, r, 'unsupported');
+    }
+  }
+  const byRel = new Map(sv.docs.map((d) => [d.rel, d]));
+  for (const p of Array.from(pairs.values()).slice(0, MAX_PAIRS)) {
+    const A = byRel.get(p.a), B = byRel.get(p.b);
+    const state = `DOCUMENT 1 (${p.a}):\n${A.text.slice(0, SNIPPET_PAIR)}\n\nDOCUMENT 2 (${p.b}):\n${B.text.slice(0, SNIPPET_PAIR)}`;
+    requests.push({ kind: 'pair', files: [p.a, p.b], names: Array.from(p.names), state });
+  }
+  return requests;
+}
+
+function plan({ root, exclude = [], now = Date.now() }) {
+  const sv = survey(root, exclude, now);
+  const reqs = buildRequests(root, sv, now);
+  return {
+    documents: sv.total, excluded: sv.excluded, eligible: sv.docs.length,
+    withheld: sv.withheld, too_large: sv.tooLarge,
+    local_findings: sv.deterministic.length + sweepFindings(root).length,
+    requests: reqs.length, characters: reqs.reduce((n, r) => n + r.state.length, 0),
+    host: typesafe.HOST,
+  };
+}
+
+/* ── judging the answers ──────────────────────────────────────────────────────────────────────── */
+function judge(name, ans) {
+  const q = Q[name];
+  if (!ans || ans.type !== q.type) return null;
+  if (q.type === 'noul') {
+    const p = Number(ans.noul);
+    if (!Number.isFinite(p) || p < 0.5) return null;
+    const certainty = Math.abs(2 * p - 1);
+    return { value: p, confidence: certainty, confidence_source: 'derived from the noul value',
+      severity: p >= 0.85 ? 'high' : p >= 0.65 ? 'medium' : 'low', probabilities: null };
+  }
+  const s = Number(ans.score), c = Number(ans.confidence);
+  if (!Number.isFinite(s) || s >= 0.7) return null;
+  return { value: s, confidence: Number.isFinite(c) ? c : null, confidence_source: 'reported by the service',
+    severity: s < 0.4 ? 'medium' : 'low', probabilities: ans.probabilities || null };
+}
+
+const nowISO = () => new Date().toISOString();
+
+/* The workflow sweep (D77) is deterministic and read-only; its defects are findings that send nothing. A
+ * repository the sweep cannot read contributes none — that is not an error here. */
+function sweepFindings(root) {
+  try {
+    const a = require('./audit').run(root);
+    if (!a || !a.ok) return [];
+    return (a.defects || []).slice(0, 20).map((d) => ({
+      file: d.file || 'planning/', rule: 'workflow-sweep', severity: 'high', detail: String(d.what || 'a workflow record is inconsistent').slice(0, 300),
+    }));
+  } catch { return []; }
+}
+
+/**
+ * Run one validation. The caller has already checked consent and the key; this refuses if the request
+ * count differs from what the PM confirmed, so the PM never confirms one plan and runs another.
+ *
+ * @returns {Promise<object>} { ok, run_id, asked, raised, failed, withheld, findings_file, ... } or { ok:false, error }
+ */
+async function run({ root, exclude = [], key, findingsFile, expectRequests, ask = typesafe.ask, now = Date.now(), askOpts = {} }) {
+  if (!typesafe.validKey(key)) return { ok: false, error: 'no TypeSafe key is set' };
+  const sv = survey(root, exclude, now);
+  const reqs = buildRequests(root, sv, now);
+  if (!Number.isInteger(expectRequests) || expectRequests !== reqs.length) {
+    return { ok: false, conflict: true, error: `the plan changed — it now has ${reqs.length} request(s), not ${expectRequests}. Review it again.` };
+  }
+  const runId = 'val-' + crypto.randomBytes(6).toString('hex');
+  const at = nowISO();
+  const guard = createSinkGuard({ sink: findingsFile, what: 'validation findings' });
+  const lines = [];
+  const emit = (rec) => lines.push({ type: 'finding', run_id: runId, at: nowISO(), ...rec });
+
+  for (const f of sv.deterministic) emit({ file: f.file, files: [f.file], rule: f.rule, kind: 'deterministic', severity: f.severity, label: 'finding', sent: false, detail: f.detail, model: null });
+  for (const f of sweepFindings(root)) emit({ file: f.file, files: [f.file], rule: f.rule, kind: 'deterministic', severity: f.severity, label: 'finding', sent: false, detail: f.detail, model: null });
+  for (const w of sv.withheld) emit({ file: w.file, files: [w.file], rule: 'withheld-by-secret-scan', kind: 'withheld', severity: 'medium', label: 'finding', sent: false, detail: 'not sent; matched ' + w.rules.join(', '), model: null });
+
+  let asked = 0, raised = 0, failed = 0, aborted = null, model = null, consecutive401 = 0;
+  for (const r of reqs) {
+    const res = await ask({ key, state: r.state, questions: wire(r.names), ...askOpts });
+    if (!res.ok) {
+      failed++;
+      if (res.status === 401) consecutive401++; else consecutive401 = 0;
+      emit({ file: r.files[0], files: r.files, rule: 'request-failed', kind: 'error', severity: 'low', label: 'finding', sent: !!res.requested, detail: res.reason, model: null });
+      if (consecutive401 >= 2) { aborted = 'the service rejected the key twice; the run stopped'; break; }
+      continue;
+    }
+    consecutive401 = 0; asked++; model = res.model || model;
+    for (const n of r.names) {
+      const j = judge(n, res.answers[n]);
+      if (!j) continue;
+      raised++;
+      emit({
+        file: r.files[0], files: r.files, rule: Q[n].rule, kind: 'judged', facet: Q[n].kind,
+        question: Q[n].instructions, answer: { type: Q[n].type, value: j.value, probabilities: j.probabilities },
+        confidence: j.confidence, confidence_source: j.confidence_source, model: res.model || null,
+        severity: j.severity, label: j.confidence != null && j.confidence >= 0.6 ? 'finding' : 'for-your-judgement', sent: true,
+      });
+    }
+  }
+
+  const summary = { type: 'run', run_id: runId, at, host: typesafe.HOST, model, requests: reqs.length, asked, failed, raised,
+    local_findings: lines.filter((l) => l.kind === 'deterministic').length, withheld: sv.withheld.length, too_large: sv.tooLarge.length, excluded: sv.excluded,
+    aborted };
+  try {
+    guard.appendLine(findingsFile, summary);
+    for (const l of lines) guard.appendLine(findingsFile, l);
+  } catch (e) {
+    return { ok: false, error: 'the findings could not be recorded — ' + String((e && e.message) || e).slice(0, 200) };
+  }
+  return { ok: true, run_id: runId, findings_file: findingsFile, ...summary, recorded: lines.length };
+}
+
+/** The latest run's findings (and its summary), newest run only, sorted by severity then confidence. */
+function readFindings(findingsFile, limit = 200) {
+  let raw = '';
+  try { raw = fs.readFileSync(findingsFile, 'utf8'); } catch { return { run: null, findings: [] }; }
+  const recs = [];
+  for (const line of raw.split('\n')) { if (!line) continue; try { recs.push(JSON.parse(line)); } catch { /* a torn line is skipped, not fatal */ } }
+  let lastRun = null;
+  for (const r of recs) if (r.type === 'run') lastRun = r;
+  if (!lastRun) return { run: null, findings: [] };
+  const rank = { high: 0, medium: 1, low: 2 };
+  const findings = recs.filter((r) => r.type === 'finding' && r.run_id === lastRun.run_id)
+    .sort((a, b) => (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3) || (b.confidence || 0) - (a.confidence || 0))
+    .slice(0, limit);
+  return { run: lastRun, findings };
+}
+
+module.exports = { plan, run, readFindings, survey, judge, Q, MAX_DOCS, MAX_PAIRS };

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.38.8",
+  "version": "0.40.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.38.8",
+  "version": "0.40.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,12 +10,12 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js",
+    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
     "doctor": "node doctor.js",
-    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js",
+    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js",
     "test:offline": "node offline-tarball.test.js"
   },
   "engines": {

package/workspace/public/pm/app.js

@@ -33,7 +33,7 @@ import { isMobile, mountMobile, applyMobile } from './mobile.js';
 const MODE_TITLE = {
   product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
   knowledge: 'knowledge', agent: 'agents', memory: 'memory', connect: 'connections', focus: 'focus',
-  portfolio: 'portfolio',
+  portfolio: 'portfolio', guide: 'guide', validate: 'validate', today: 'today',
 };
 const DETAIL_TITLE = {
   init: 'initiative', flow: 'workflow', sched: 'scheduled task', skill: 'skill', know: 'decision',
@@ -47,15 +47,17 @@ const detailTitle = () => DETAIL_TITLE[(state.detail && state.detail.kind) || ''
 /* Panels 1 and 2 are resizable: a drag handle on each right edge. The width is clamped, remembered
  * (state.js PERSIST) and reset by a double-click. Before this the columns were a fixed 210px / 280px and a
  * long repository or branch name was simply cut off. */
-const W0 = { min: 180, max: 520, def: 210 };
-const W1 = { min: 220, max: 560, def: 280 };
+const W0 = { min: 220, max: 560, def: 280 };
 const clampW = (v, r) => (typeof v === 'number' && Number.isFinite(v) ? Math.min(r.max, Math.max(r.min, Math.round(v))) : r.def);
 const col0w = () => clampW(state.col0W, W0);
-const col1w = () => clampW(state.col1W, W1);
 
+/* THREE columns (column-layout): navigation, detail, tabs. Navigation is the repository list with the list of the
+ * current mode UNDER it (initiatives, or memory, skills, knowledge …). The detail opens in the second column, the
+ * tabs fill the rest. The DOM still holds four hosts in the same order — repos, list, detail, tabs — and the grid
+ * puts the list host under the repositories host (see placeHosts). Folded away, the navigation column is a 36px
+ * rail; the list alone folds to a one-line bar under the repositories. */
 const gridCols = () =>
   (state.col0 ? col0w() + 'px' : '36px') + ' ' +
-  (state.col1 ? col1w() + 'px' : '36px') + ' ' +
   (state.col2 ? 'minmax(420px,560px)' : '36px') + ' minmax(0,1fr)';
 
 /** The right-hand 7px of a column is its drag handle. It is a hit-test on the host, not an extra element:
@@ -172,10 +174,11 @@ const statusBar = el('div', {
  * disagree. The implicit ROW is stated explicitly as `minmax(0,1fr)` for the same reason the root's
  * middle track is: an auto row is floored at its items' min-content height, and one tall panel
  * would push the grid taller than the box it was given. */
-const BODY_GRID_STYLE = () =>
-  'display:grid;grid-template-columns:' + gridCols() + ';grid-template-rows:minmax(0,1fr);min-height:0;overflow:hidden';
+// Two rows on a desktop (repositories, then the list under them), one on a phone, where the hosts are shown one at a time.
+const BODY_GRID_STYLE = (phone) =>
+  'display:grid;grid-template-columns:' + gridCols() + ';grid-template-rows:' + (phone ? 'minmax(0,1fr)' : 'auto minmax(0,1fr)') + ';min-height:0;overflow:hidden';
 
-const bodyGrid = el('div', { style: BODY_GRID_STYLE() });
+const bodyGrid = el('div', { style: BODY_GRID_STYLE(false) });
 
 /** The collapsed 36px strip: a full-height button with a rotated vertical-rl label. */
 function makeRail(flag) {
@@ -189,8 +192,14 @@ function makeRail(flag) {
 }
 
 const rail0 = makeRail('col0');
-const rail1 = makeRail('col1');
 const rail2 = makeRail('col2');
+/* The list under the repositories, folded: one line, not a column. */
+const listBar = el('button', {
+  onClick: () => setState((s) => ({ col1: !s.col1 })),
+  title: 'show the list',
+  style: 'background:var(--sidebar);border-right:1px solid var(--border);border-top:1px solid var(--border);display:flex;align-items:center;align-self:start;gap:6px;padding:8px 14px;min-height:34px;font-family:var(--mono);font-size:11px;letter-spacing:.06em;color:var(--muted-foreground);text-align:left',
+  hover: 'background:var(--accent)',
+});
 rail0.label.textContent = 'repositories ⟩';
 /* overhaul-r1 R4: in live mode the collapsed repositories rail also carries one glyph per repository
  * (panel-repos.js#railGlyphs), so a repository is selectable without expanding the panel. The
@@ -208,9 +217,9 @@ const rail0Host = el('div', {
  * two that already carry `overflow-y:auto` get it for free under the spec — stated anyway, because
  * "this one is safe because of a rule elsewhere in the same line" is how the next edit breaks it. */
 const hostRepos = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);display:flex;flex-direction:column;min-width:0;min-height:0;overflow-y:auto' });
-const hostInits = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0;min-height:0' });
+const hostInits = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);border-top:1px solid var(--border);overflow-y:auto;min-width:0;min-height:0' });
 makeEdgeDrag(hostRepos, 'col0W', W0, col0w);
-makeEdgeDrag(hostInits, 'col1W', W1, col1w);
+makeEdgeDrag(hostInits, 'col0W', W0, col0w);
 const hostDetail = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0;min-height:0;display:flex;flex-direction:column' });
 const hostTabs = el('div', { style: 'background:var(--term-bg);display:flex;flex-direction:column;min-width:0;min-height:0;overflow:hidden' });
 
@@ -256,6 +265,27 @@ function railRepos() {
   return rail0Host;
 }
 
+/* Where each host sits in the grid. Desktop: column 1 holds the repositories (row 1) and the list under them (row 2); the
+ * detail and the tabs span both rows. The repositories block is capped so a long list of repositories cannot push the
+ * list off the screen; it scrolls inside its cap. A folded column is a rail spanning both rows. On a phone the placement
+ * is cleared and mobile.css decides which single host is shown. */
+function placeHosts(phone, kids) {
+  const cell = (el0, col, row) => { if (el0) { el0.style.gridColumn = col; el0.style.gridRow = row; } };
+  const clear0 = (el0) => { el0.style.gridColumn = ''; el0.style.gridRow = ''; el0.style.maxHeight = ''; };
+  for (const h of [hostRepos, hostInits, hostDetail, hostTabs, listBar, rail0.btn, rail0Host, rail2.btn]) clear0(h);
+  if (phone) return;
+  if (state.col0) {
+    cell(hostRepos, '1', '1');
+    hostRepos.style.maxHeight = 'calc((100vh - 70px) * .42)';
+    cell(state.col1 ? hostInits : listBar, '1', '2');
+  } else {
+    const rail = kids.includes(rail0Host) ? rail0Host : rail0.btn;
+    cell(rail, '1', '1 / 3');
+  }
+  cell(state.col2 ? hostDetail : rail2.btn, '2', '1 / 3');
+  cell(hostTabs, '3', '1 / 3');
+}
+
 function render() {
   root.setAttribute('data-pm-theme', state.theme);
   themeBtn.textContent = state.theme === 'dark' ? 'theme · dark' : 'theme · light';
@@ -266,26 +296,31 @@ function render() {
 
   // Panel 1's rail is a constant; panels 2 and 3 name whatever is behind them, so a PM who folded
   // a panel away can still see what they folded.
-  rail1.label.textContent = modeTitle() + ' ⟩';
+  listBar.textContent = '▸ ' + modeTitle();
   rail2.label.textContent = detailTitle() + ' ⟩';
 
-  bodyGrid.setAttribute('style', BODY_GRID_STYLE());
+  const phone = isMobile();
+  bodyGrid.setAttribute('style', BODY_GRID_STYLE(phone));
 
   // On a phone there are no rails to collapse into and no second column to fold away: the four
   // hosts all stay mounted, one is DISPLAYED (pm/mobile.css picks it from `data-mpanel`), and the
   // PM's desktop arrangement — col0/col1/col2 — is left exactly as they set it. Mounting all four
   // is also what keeps a live terminal alive: a host dropped from this list would be removed from
   // the document, and panel 4's xterm does not survive that.
-  const phone = isMobile();
-  setChildren(bodyGrid, phone ? [hostRepos, hostInits, hostDetail, hostTabs] : [
+  const listShown = phone || (state.col0 && state.col1);
+  const listHost = phone || state.col1 ? hostInits : listBar;
+  const kids = phone ? [hostRepos, hostInits, hostDetail, hostTabs] : [
     state.col0 ? hostRepos : railRepos(),
-    state.col1 ? hostInits : rail1.btn,
+    // with the navigation column folded away the list goes with it
+    state.col0 ? listHost : null,
     state.col2 ? hostDetail : rail2.btn,
     hostTabs,
-  ]);
+  ].filter(Boolean);
+  setChildren(bodyGrid, kids);
+  placeHosts(phone, kids);
 
   if (phone || state.col0) paint(mods.repos, 'renderRepos', hostRepos);
-  if (phone || state.col1) paint(mods.inits, 'renderInitiatives', hostInits);
+  if (listShown) paint(mods.inits, 'renderInitiatives', hostInits);
   if (phone || state.col2) paint(mods.detail, 'renderDetail', hostDetail);
   paint(mods.tabs, 'renderTabs', hostTabs);
 

package/workspace/public/pm/data.js

@@ -455,6 +455,7 @@ function recordFrom(payload) {
     // R4/R5/R6 — what remains to acceptance, the conversations that belong to it, and the files git says
     // were changed for it. Each arrives already derived by the server; this layer only carries them.
     nextSteps: payload.next_steps || null,
+    lcHistory: payload.lifecycle_history || [],
     convs: Array.isArray(payload.conversations) ? payload.conversations : [],
     gitFiles: payload.files || null,
     eval: evalFor(row && row.steps),
@@ -1424,14 +1425,18 @@ export async function saveScratchpad(key, text) {
 }
 
 /** tab-doc.js — `readDoc(path)`. The raw document body, or a rejected promise carrying the reason. */
-export async function readDoc(path, ws) {
+export async function readDoc(path, ws, ref) {
   if (FIXTURE) return '';
   const p = products.get(currentProductName());
   // `ws` is the tree a search hit came from (overhaul-r1 R1.3) — a branch-only file must be read
   // from its own worktree, not from the product's main tree.
-  const url = '/api/doc?' + q({ ws: ws || state.wsId || (p ? p.ws : ''), path });
+  const url = '/api/doc?' + q({ ws: ws || state.wsId || (p ? p.ws : ''), path, ...(ref ? { ref } : {}) });
   const res = await fetch(url);
-  if (!res.ok) throw new Error(res.status === 404 ? 'not a readable text document in this workspace' : 'HTTP ' + res.status);
+  if (!res.ok) {
+    // The server states why a read was refused (binary, too large, not text, outside the workspace); show that reason.
+    const why = res.status === 404 ? (await res.text().catch(() => '')) : '';
+    throw new Error(res.status === 404 ? (why || 'not a readable text document in this workspace') : 'HTTP ' + res.status);
+  }
   return res.text();
 }
 
@@ -1579,6 +1584,16 @@ if (!FIXTURE) {
  * Each of these is reached only by a PM press. None runs on load, on a timer or as a side effect. */
 export function wsOf(name) { const p = products.get(name); return p ? p.ws : null; }
 
+/* ── next-step actions: prepare, go, review (the routes are in server.js; every one is reached by a PM press) ── */
+export async function nextStepPost(kind, body) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode starts nothing' };
+  return (await postJson('/api/next-step/' + kind, { ws: wsOf(currentProductName()), ...body })) || { ok: false, error: 'the workspace server did not answer' };
+}
+export async function nextStepSummary(session) { return FIXTURE ? { ok: false, error: 'fixture mode' } : getJson('/api/next-step/summary', { session }); }
+export async function nextStepProfiles() { return FIXTURE ? { ok: false, profiles: [] } : getJson('/api/profiles'); }
+/** Re-read one initiative (its next steps, runs and verdicts) after something changed. */
+export async function refreshInitiative(slug) { if (FIXTURE || !slug) return; delete hydrated[slug]; await hydrate(slug); }
+
 /** The lifecycle of every initiative in a repository, from the same surface the board uses. */
 export async function lifecycleMap(name) {
   const ws = wsOf(name);