create-pmos 0.38.8 → 0.40.0

package/workspace/lib/doc-profiles.js

@@ -0,0 +1,74 @@
+'use strict';
+/* doc-profiles.js — what KIND of document is this, and what must it agree with? (claims-ledger C1)
+ *
+ * A checker that treats every file the same compares things that have nothing to say about each other. So a file
+ * is classified FIRST, and the class decides what it is checked against. Order of evidence, strongest first:
+ *   1. its frontmatter `type`;
+ *   2. an initiative record that names it (prd_path, rubric_path, explainer_path, brief_path, doc_path);
+ *   3. its filename convention (<id>-prd.md, <id>-eval-rubric.md, <id>-user-stories.md, dNN-*.md …);
+ *   4. a heading signature, only for the two kinds with a distinctive one (PRD, rubric).
+ * A markdown file that matches none is UNCLASSIFIED. It still gets internal checks (its own links, its own
+ * `stale_after`) and is NEVER compared with another file. "Not classified" is an honest answer; guessing is not.
+ *
+ * `REFERENCES` states, per type, which roles the type is compared with. The extraction and the checks live in
+ * lib/claims.js and read this table, so what a type "must agree with" is written down once.
+ */
+const path = require('path');
+
+const IN_SCOPE_EXT = new Set(['md', 'json', 'yaml', 'yml', 'toml']);
+
+/* Types that have a cross-reference set. Any other `type` value is classified (it has a name) but is checked
+ * internally only. */
+const REFERENCES = {
+  Initiative: ['PRD', 'Rubric', 'Reference (explainer)', 'brief or document'],
+  PRD: ['Initiative', 'Rubric', 'decisions it cites'],
+  Rubric: ['PRD', 'Initiative'],
+  Story: ['PRD'],
+  ADR: ['the decisions file'],
+};
+
+const extOf = (rel) => { const b = path.posix.basename(rel).toLowerCase(); const i = b.lastIndexOf('.'); return i > 0 ? b.slice(i + 1) : ''; };
+
+/** Which role does an initiative record give a path? `refs` maps path → [{role, id}]. */
+const ROLE_TYPE = { prd_path: 'PRD', rubric_path: 'Rubric', explainer_path: 'Reference', brief_path: 'Reference', doc_path: 'Reference' };
+
+const NAME_RULES = [
+  [/-eval-rubric\.md$/i, 'Rubric'],
+  [/-prd\.md$/i, 'PRD'],
+  [/-user-stories\.md$/i, 'Story'],
+  [/-surface-explainer\.md$/i, 'Reference'],
+  [/(^|\/)d\d{1,3}-[^/]+\.md$/i, 'ADR'],
+];
+
+function headings(text) {
+  const out = [];
+  for (const m of String(text).matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) out.push(m[1].toLowerCase());
+  return out;
+}
+
+/**
+ * Classify one file.
+ * @param {object} a
+ * @param {string} a.rel        repo-relative path with forward slashes
+ * @param {object} a.fm         parsed frontmatter ({} when none)
+ * @param {string} a.text       file text
+ * @param {Map}    [a.named]    path → [{role, id}] from initiative records
+ * @returns {{type:string|null, via:string, classified:boolean}}
+ */
+function classify({ rel, fm = {}, text = '', named = new Map() }) {
+  const ext = extOf(rel);
+  if (ext !== 'md') return { type: 'Config', via: 'extension', classified: true };
+  // A template is a scaffold with placeholders, not a document that can agree or disagree with anything.
+  if (/(^|\/)templates?\//i.test(rel) || /-template\.md$/i.test(rel)) return { type: 'Template', via: 'path', classified: true };
+  if (fm.type) return { type: String(fm.type), via: 'frontmatter type', classified: true };
+  const roles = named.get(rel);
+  if (roles && roles.length) return { type: ROLE_TYPE[roles[0].role] || 'Reference', via: 'named by initiative ' + roles[0].id, classified: true };
+  for (const [re, type] of NAME_RULES) if (re.test(rel)) return { type, via: 'file name', classified: true };
+  const h = headings(text);
+  const has = (s) => h.some((x) => x.includes(s));
+  if (has('requirements') && has('identity')) return { type: 'PRD', via: 'headings', classified: true };
+  if (has('dimensions') && has('sprint contract')) return { type: 'Rubric', via: 'headings', classified: true };
+  return { type: null, via: 'no evidence', classified: false };
+}
+
+module.exports = { classify, extOf, headings, IN_SCOPE_EXT, REFERENCES, ROLE_TYPE };

package/workspace/lib/initiative-files.js

@@ -12,6 +12,8 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const PK = require('./preview-kind');
+const { previewKind } = PK;
 
 const MAX_FILES = 200;
 const cache = new Map();   // root|id → {head, at, result}
@@ -86,13 +88,13 @@ function filesFor(root, id, opts) {
     }
     // What still exists: the checked-out tree plus the initiative's own branch tip, so a file that lives only on an
     // unmerged branch is listed, and a file deleted since is not. `ls-tree` once per ref, never one spawn per file.
-    const present = new Set();
+    const present = new Set(); const onHead = new Set();
     let treeOk = false;
     for (const ref of ['HEAD', branch].filter(Boolean)) {
       const t = git(root, ['ls-tree', '-r', '--name-only', '-z', ref]);
-      if (t.ok) { treeOk = true; for (const f of t.out.split('\0')) if (f) present.add(f); }
+      if (t.ok) { treeOk = true; for (const f of t.out.split('\0')) if (f) { present.add(f); if (ref === 'HEAD') onHead.add(f); } }
     }
-    base = { commits, via, present: treeOk ? present : null };
+    base = { commits, via, branch: branch || null, present: treeOk ? present : null, onHead: treeOk ? onHead : null };
     cache.set(key, { head, at: Date.now(), result: base });
   }
   const seen = new Map();
@@ -103,9 +105,38 @@ function filesFor(root, id, opts) {
   }
   const exists = (f) => { if (base.present) return base.present.has(f); try { return fs.existsSync(path.join(root, f)); } catch { return false; } };
   const items = [...seen.values()].filter((x) => exists(x.path))
-    .map((x) => ({ path: x.path, group: groupOf(x.path), commits: x.shas.length, last: x.shas[0].slice(0, 7) }))
+    // `where` says which copy a reader gets: `head` is in the checked-out tree; `branch` exists only on the
+    // initiative's own branch tip, so it has to be read from git, not from the working tree.
+    .map((x) => ({ path: x.path, group: groupOf(x.path), commits: x.shas.length, last: x.shas[0].slice(0, 7),
+      where: base.onHead ? (base.onHead.has(x.path) ? 'head' : 'branch') : 'head', kind: previewKind(x.path) }))
     .sort((a, b) => (a.group + a.path).localeCompare(b.group + b.path));
-  return { ok: true, total: items.length, truncated: items.length > MAX_FILES, items: items.slice(0, MAX_FILES), via: base.via };
+  return { ok: true, total: items.length, truncated: items.length > MAX_FILES, items: items.slice(0, MAX_FILES), via: base.via, branch: base.branch };
 }
 
-module.exports = { filesFor, groupOf, namesId };
+/**
+ * Read one file as it is at `ref` (the initiative's own branch), for a file that is not in the checked-out tree.
+ * Only `initiative/<id>` and `origin/initiative/<id>` are readable, and only text under 2 MB; anything else is a
+ * reason, never a guess.
+ */
+const MAX_BYTES = 2 * 1024 * 1024;
+function readAtRef(root, ref, rel) {
+  if (!/^(origin\/)?initiative\/[A-Za-z0-9][\w.-]*$/.test(String(ref || ''))) return { ok: false, reason: 'only an initiative branch can be read this way' };
+  const p = String(rel || '');
+  if (!p || p.startsWith('/') || p.split('/').some((seg) => seg === '..' || seg === '')) return { ok: false, reason: 'not a path inside the repository' };
+  const kind = previewKind(p);
+  // A type that is binary by nature, or opened another way (image, PDF, workbook), is refused with its reason; any
+  // other file is tried as text, like a read from the working tree (file-viewer-any-text).
+  if (kind === 'image' || kind === 'pdf' || kind === 'sheet') return { ok: false, reason: 'this kind of file is opened another way, not as text' };
+  const known = kind === 'markdown' || kind === 'text' || kind === 'html';
+  if (!known && PK.isKnownBinary(p)) return { ok: false, reason: 'this is a binary file (.' + PK.extOf(p) + ') and cannot be shown as text' };
+  const r = spawnSync('git', ['-C', root, 'show', ref + ':' + p], { encoding: 'buffer', maxBuffer: MAX_BYTES + 1024, timeout: 20000 });
+  if (r.error || r.status !== 0) return { ok: false, reason: 'git has no such file on ' + ref };
+  if (r.stdout.length > MAX_BYTES) return { ok: false, reason: 'the file is larger than 2 MB' };
+  if (r.stdout.indexOf(0) !== -1) return { ok: false, reason: 'the file is binary' };
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(r.stdout); }
+  catch { if (!known) return { ok: false, reason: 'the file is not valid UTF-8 text' }; text = r.stdout.toString('utf8'); }
+  return { ok: true, kind: known ? kind : 'text', text };
+}
+
+module.exports = { filesFor, groupOf, namesId, readAtRef };

package/workspace/lib/judgment.js

@@ -0,0 +1,65 @@
+'use strict';
+/* judgment.js — typed answers to classify, score and yes-or-no questions.
+ *
+ * The workspace makes no network call and runs no model. When the PM turns judgment on for a run, the PROMPT tells the
+ * session to use the Typesafe skill (https://docs.typesafe.ai/agent-skill; needs TYPESAFE_API_KEY) for these three kinds
+ * of decision, and to print each answer on one line as `JUDGMENT {json}`. This module owns the fragment that says so and
+ * the check of the shape that comes back. An answer in any other shape is rejected, never repaired.
+ *
+ * Off, or without a key, the session is asked for the SAME shape from plain judgment, and the fragment says so — the
+ * PM never gets a different answer format depending on a setting.
+ */
+const KINDS = ['classify', 'score', 'yesno'];
+const LINE = /^JUDGMENT\s+(\{.*\})\s*$/;
+const clip = (s, n) => String(s).slice(0, n);
+
+function fragment(on) {
+  const shape = [
+    'When a step needs you to categorise, score, or decide yes or no, give the answer on its own line, exactly like this, one JSON object per line:',
+    // The examples start with "e.g." so a transcript that echoes this prompt is never read as an answer.
+    '  e.g. JUDGMENT {"kind":"classify","question":"…","label":"<one of your labels>","labels":["…","…"],"confidence":0.0-1.0}',
+    '  e.g. JUDGMENT {"kind":"score","question":"…","score":0.0-1.0,"reason":"…"}',
+    '  e.g. JUDGMENT {"kind":"yesno","question":"…","answer":true|false,"confidence":0.0-1.0,"reason":"…"}',
+  ];
+  if (on) return ['Use the Typesafe skill (/typesafe:typesafe-ai) for those decisions. The question text you send leaves this machine for the Typesafe service and needs TYPESAFE_API_KEY. If the skill or the key is missing, say so and decide yourself.', ...shape].join('\n');
+  return ['Decide those yourself; no outside service is used for this run.', ...shape].join('\n');
+}
+
+const unit = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+
+/** @returns {{ok:true,value:object}|{ok:false,error:string}} */
+function validate(o) {
+  if (!o || typeof o !== 'object' || Array.isArray(o)) return { ok: false, error: 'not an object' };
+  if (!KINDS.includes(o.kind)) return { ok: false, error: `kind must be one of ${KINDS.join(', ')}` };
+  if (typeof o.question !== 'string' || !o.question.trim()) return { ok: false, error: 'question is required' };
+  const base = { kind: o.kind, question: clip(o.question.trim(), 300) };
+  if (o.kind === 'classify') {
+    if (!Array.isArray(o.labels) || o.labels.length < 2 || o.labels.some((l) => typeof l !== 'string' || !l.trim())) return { ok: false, error: 'labels must be a list of at least two strings' };
+    if (typeof o.label !== 'string' || !o.labels.includes(o.label)) return { ok: false, error: 'label must be one of labels' };
+    if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+    return { ok: true, value: { ...base, label: o.label, labels: o.labels.map((l) => clip(l, 60)), confidence: o.confidence } };
+  }
+  if (o.kind === 'score') {
+    if (!unit(o.score)) return { ok: false, error: 'score must be a number from 0 to 1' };
+    if (typeof o.reason !== 'string' || !o.reason.trim()) return { ok: false, error: 'reason is required' };
+    return { ok: true, value: { ...base, score: o.score, reason: clip(o.reason.trim(), 300) } };
+  }
+  if (typeof o.answer !== 'boolean') return { ok: false, error: 'answer must be true or false' };
+  if (!unit(o.confidence)) return { ok: false, error: 'confidence must be a number from 0 to 1' };
+  return { ok: true, value: { ...base, answer: o.answer, confidence: o.confidence, ...(typeof o.reason === 'string' ? { reason: clip(o.reason.trim(), 300) } : {}) } };
+}
+
+/** Every `JUDGMENT {json}` line in a transcript, checked. Returns { valid:[…], invalid:[{line,error}] }. */
+function extract(text) {
+  const valid = []; const invalid = [];
+  for (const raw of String(text == null ? '' : text).split(/\r?\n/)) {
+    const m = LINE.exec(raw.trim());
+    if (!m) continue;
+    let o; try { o = JSON.parse(m[1]); } catch { invalid.push({ line: clip(raw.trim(), 200), error: 'not valid JSON' }); continue; }
+    const v = validate(o);
+    if (v.ok) valid.push(v.value); else invalid.push({ line: clip(raw.trim(), 200), error: v.error });
+  }
+  return { valid, invalid };
+}
+
+module.exports = { KINDS, fragment, validate, extract };

package/workspace/lib/mobile-nav.js

@@ -49,7 +49,7 @@
 // silently renders a key where a title belongs.
 const MODE_TITLE = {
   product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
-  knowledge: 'knowledge', agent: 'agents', memory: 'memory',
+  knowledge: 'knowledge', agent: 'agents', memory: 'memory', portfolio: 'portfolio', guide: 'guide',
 };
 // What a DETAIL screen is called. It moved here with the reducer, for the same reason.
 // The second block is the four-panel surface's `detail.kind` vocabulary (pm/app.js's DETAIL_TITLE).

package/workspace/lib/next-step-actions.js

@@ -0,0 +1,139 @@
+'use strict';
+/* next-step-actions.js — what a next step can DO, whether it may be started yet, and the prompt a session would get.
+ *
+ * Pure: no I/O, no clock, no model. The server supplies facts (does a file exist, which sources a profile declares) and
+ * this module decides. Three questions, each answered in one place so no panel and no route re-decides them:
+ *
+ *   actFor(item)        what kind of act the step is: open · session · work · gate · lifecycle · none
+ *   refusal(item, ns)   why a `work` step may NOT be started yet, or null when it may
+ *   buildPrompt(...)    the exact first input a session would receive — what the PM is shown before pressing go
+ *
+ * THE BOUNDARY (D12 and the control/factory invariant). A session started from here PROPOSES: it commits to a local
+ * initiative branch or writes draft files. It never accepts, approves a contract, merges, pushes, sends or posts. Acceptance
+ * and the contract approval are `gate` acts and are never turned into `work`.
+ */
+const crypto = require('crypto');
+
+// Ladder steps an agent session can do. `contract`, `accept`, `approved`, `outcome` and `handoff` are the PM's own act.
+const WORK_KEYS = new Set(['route', 'anchor', 'prototype', 'understand', 'spec', 'priors', 'build', 'quality', 'review', 'explain', 'brief', 'draft']);
+const GATE_KEYS = new Set(['contract', 'accept', 'approved', 'outcome', 'handoff']);
+const KNOWN_KEYS = [...WORK_KEYS, ...GATE_KEYS];
+// The act types a step can have (`none` means no action is defined, and is not offered). The user guide names each one.
+const ACT_TYPES = ['open', 'session', 'work', 'gate', 'lifecycle'];
+
+const GATE_WHY = {
+  contract: 'The contract is yours to approve. An agent may draft it; the approval is recorded by you, never by a session.',
+  accept: 'Acceptance is yours and cannot be delegated (D12).',
+  approved: 'Approval is yours.',
+  outcome: 'The outcome check is yours to record.',
+  handoff: 'Handing work to another system is outward-facing, so it is yours to press.',
+};
+
+/** @returns {{type:'open'|'session'|'work'|'gate'|'lifecycle'|'none', why:string, path?:string, sessionId?:string}} */
+function actFor(item) {
+  if (!item || typeof item !== 'object') return { type: 'none', why: 'no step' };
+  const path = typeof item.path === 'string' && item.path ? item.path : null;
+  const withPath = (a) => (path ? { ...a, path } : a);
+  switch (item.kind) {
+    case 'reopen': return { type: 'lifecycle', why: 'Reopen it to put it back on the board.' };
+    case 'session': return item.sid ? { type: 'session', why: 'Switch to the running session.', sessionId: item.sid } : { type: 'none', why: 'the session is not identified' };
+    case 'accept': return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY.accept });
+    case 'needs': return withPath({ type: 'gate', why: 'An open item only you can answer.' });
+    case 'returned': return { type: 'work', why: 'Address the return, then ask for acceptance again.' };
+    case 'step': {
+      if (WORK_KEYS.has(item.key)) return withPath({ type: 'work', why: 'An agent session can do this step.' });
+      if (GATE_KEYS.has(item.key)) return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY[item.key] });
+      return { type: 'none', why: `no action is defined for the step "${item.key}"` };
+    }
+    default: return { type: 'none', why: 'no action is defined for this item' };
+  }
+}
+
+/** Set `act` on every item of a derived next-steps result. Mutates and returns it. */
+function annotate(ns, pathOf) {
+  if (!ns || !Array.isArray(ns.items)) return ns;
+  for (const it of ns.items) {
+    if (typeof pathOf === 'function') { const p = pathOf(it); if (p) it.path = p; }
+    it.act = actFor(it);
+  }
+  return ns;
+}
+
+/** Why this item may not be started as work yet; null when it may. `ns` is the whole derived result. */
+function refusal(item, ns) {
+  if (!item) return { code: 'no-step', why: 'no such step' };
+  const act = item.act || actFor(item);
+  if (ns && ns.state === 'stopped' && item.kind !== 'reopen') {
+    return { code: 'stopped', why: 'This initiative is stopped (held, closed or cancelled). Reopen it first.', first: 'reopen' };
+  }
+  if (ns && ns.state === 'accepted') return { code: 'accepted', why: 'This initiative is accepted. Nothing remains.' };
+  if (act.type !== 'work') return { code: 'not-work', why: act.type === 'gate' ? act.why : `This is not work an agent session can start (${act.type}).` };
+  const items = (ns && ns.items) || [];
+  if (item.kind === 'returned') return null;                      // addressing a return is always the next thing
+  if (item.status === 'blocked') return { code: 'blocked', why: `This step is blocked${item.why ? ' — ' + item.why : ''}.`, first: item.key };
+  if (item.key === 'build') {
+    const contract = items.find((x) => x.kind === 'step' && x.key === 'contract');
+    if (contract) return { code: 'no-contract', why: 'The build cannot start before you approve the pre-run contract. An agent may draft it; you approve it.', first: 'contract' };
+  }
+  if (item.first || item.status === 'current') return null;
+  const first = items.find((x) => x.first) || items[0];
+  return { code: 'not-reached', why: `Not reached yet: step ${first ? first.n : 1} (${first ? first.key : 'the first step'}) comes first.`, first: first ? first.key : null };
+}
+
+// Which read-only sources suit which step. Names are the keys of SOURCE_MCP below.
+const STEP_SOURCES = {
+  route: ['jira', 'slack'], understand: ['wispr', 'confluence', 'jira', 'slack'], spec: ['wispr', 'confluence', 'jira', 'gmail'],
+  priors: ['confluence'], prototype: ['wispr', 'slack'], build: ['jira', 'confluence'], returned: ['wispr', 'slack', 'gmail'],
+  brief: ['wispr', 'calendar', 'gmail'], draft: ['wispr', 'confluence', 'gmail'],
+};
+// MCP server names a profile may declare, per source. A name outside this table names nothing.
+const SOURCE_MCP = {
+  wispr: ['wispr', 'wispr-flow', 'wisprflow'], gmail: ['gmail', 'google-mail'], calendar: ['google-calendar', 'gcal', 'calendar'],
+  confluence: ['confluence', 'atlassian'], jira: ['jira', 'atlassian'], slack: ['slack'],
+};
+const SOURCE_LABEL = { wispr: 'Wispr Flow notes and meetings', gmail: 'Gmail', calendar: 'Google Calendar', confluence: 'Confluence', jira: 'Jira', slack: 'Slack' };
+
+/** The sources the prompt may name: suited to the step AND declared by the chosen profile's `mcp` list. */
+function sourcesFor(item, mcpDeclared) {
+  const declared = new Set((Array.isArray(mcpDeclared) ? mcpDeclared : []).map((s) => String(s).toLowerCase()));
+  const want = STEP_SOURCES[item && item.kind === 'returned' ? 'returned' : item && item.key] || [];
+  return want.filter((s) => (SOURCE_MCP[s] || []).some((n) => declared.has(n))).map((s) => ({ id: s, label: SOURCE_LABEL[s] }));
+}
+
+const RULES = [
+  'Commit only to this local branch, or write draft files in the repository.',
+  'Do not push, open a pull request, send or post anything, create a ticket, record an acceptance, approve a contract, or merge. Those are the PM\'s.',
+  'Do only this step. If you find another problem, write it down and stop.',
+  'When you finish, stop and write a short summary: what you changed, and what you could not verify.',
+];
+
+/**
+ * The exact first input a session would receive.
+ * @param {{initiative:string, title?:string, item:object, branch:string|null, sources:Array, judgment:string}} p
+ */
+function buildPrompt(p) {
+  const it = p.item || {};
+  const lines = [];
+  lines.push(`Work on initiative ${p.initiative}${p.title ? ' — ' + p.title : ''}.`);
+  lines.push(`Step: ${it.key || it.kind}${it.text && it.text !== it.key ? ' — ' + it.text : ''}.`);
+  if (it.action) lines.push(`What is needed: ${it.action}`);
+  if (it.why && it.why !== it.action) lines.push(`Why this step is open: ${it.why}`);
+  lines.push(`You are on ${p.branch ? 'branch ' + p.branch : 'the current branch'}. Read AGENTS.md, then this initiative's record, PRD and rubric in planning/ before you act.`);
+  lines.push('');
+  lines.push('Rules that do not bend:');
+  for (const r of RULES) lines.push('- ' + r);
+  if (p.sources && p.sources.length) {
+    lines.push('');
+    lines.push('You may read these sources for context. They are read-only: look, do not write.');
+    for (const s of p.sources) lines.push('- ' + s.label);
+  }
+  if (p.judgment) { lines.push(''); lines.push(p.judgment); }
+  return lines.join('\n');
+}
+
+/** A short fingerprint of what the PM is shown. Go must carry it back; if anything changed, the start is refused. */
+function planHash(parts) {
+  return crypto.createHash('sha256').update(JSON.stringify([parts.prompt, parts.branch || null, parts.wsId || null, parts.plan || null, !!parts.judgment])).digest('hex').slice(0, 16);
+}
+
+module.exports = { actFor, annotate, refusal, sourcesFor, buildPrompt, planHash, ACT_TYPES, KNOWN_KEYS, WORK_KEYS, GATE_KEYS, RULES, SOURCE_LABEL };

package/workspace/lib/next-steps.js

@@ -19,12 +19,18 @@
 
 const REMAINING = new Set(['blocked', 'current', 'pending', 'unknown']);
 
+// Who acts on a step. Acceptance, the contract approval, a document's approval and an outcome check are the PM's;
+// every other ladder step is the agent's. This is the one place that is decided: later work reads `owner`, it
+// does not re-decide it.
+const PM_STEPS = new Set(['accept', 'contract', 'approved', 'outcome']);
+const slug = (t) => String(t == null ? '' : t).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+
 const clip = (s, n = 200) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
 
 function stepItem(s) {
   const unread = s.status === 'unknown';
   return {
-    kind: 'step', key: s.key, status: s.status,
+    kind: 'step', key: s.key, status: s.status, owner: PM_STEPS.has(s.key) ? 'pm' : 'agent', act: null,
     text: unread ? `${s.key} could not be read` : s.key,
     action: clip(s.next || s.evidence || (unread ? 'the workflow engine could not decide this step' : 'no action recorded for this step')),
     why: clip(s.evidence),
@@ -33,6 +39,18 @@ function stepItem(s) {
   };
 }
 
+// A stable id: initiative + kind + the thing it is about (the step key, the session id, the words of an open item).
+function withIds(id, items) {
+  const seen = new Map();
+  for (const it of items) {
+    const tail = it.kind === 'session' ? (it.sid || slug(it.text)) : it.kind === 'needs' ? slug(it.text) : it.key;
+    const base = `${id || 'initiative'}:${it.kind}:${tail}`;
+    const n = (seen.get(base) || 0) + 1; seen.set(base, n);
+    it.id = n > 1 ? `${base}:${n}` : base;
+  }
+  return items;
+}
+
 function deriveNextSteps(input) {
   const i = input || {};
   const row = i.ladder && i.ladder.ok && i.ladder.row ? i.ladder.row : null;
@@ -49,12 +67,13 @@ function deriveNextSteps(input) {
   const stopped = i.lifecycle && i.lifecycle.state && i.lifecycle.state !== 'active' ? i.lifecycle : null;
   if (stopped) {
     const items = [{
-      kind: 'reopen', key: 'reopen', status: 'pending',
+      kind: 'reopen', key: 'reopen', status: 'pending', owner: 'pm', act: null,
       text: `Reopen — it is ${stopped.state}`,
       action: 'Reopen it to put it back on the board and have its steps gate again. Nothing below is required while it is stopped.',
       why: clip(stopped.reason), source: 'lifecycle.jsonl (D70)',
     }, ...ordered.map((s) => ({ ...stepItem(s), held: true }))];
     items.forEach((it, n) => { it.n = n + 1; it.first = n === 0; });
+    withIds(i.id, items);
     return {
       state: 'stopped',
       summary: `Stopped (${stopped.state})${stopped.reason ? ' — ' + clip(stopped.reason, 120) : ''}. It is off the board and not gating. Reopen to continue; the steps it would then owe are listed after.`,
@@ -73,26 +92,26 @@ function deriveNextSteps(input) {
   const hasAcceptStep = steps.some((s) => s.key === 'accept');
   for (const n of (i.needs || [])) {
     items.push({
-      kind: 'needs', key: 'needs', status: 'pending', text: clip(n.question || '(unstated)', 160),
+      kind: 'needs', key: 'needs', status: 'pending', owner: 'pm', act: null, text: clip(n.question || '(unstated)', 160),
       action: 'Answer or clear this open item.', why: '', source: 'needs queue',
     });
   }
   if (i.returned) {
     items.push({
-      kind: 'returned', key: 'returned', status: 'blocked', text: 'The PM returned this at the Acceptance Gate',
+      kind: 'returned', key: 'returned', status: 'blocked', owner: 'pm', act: null, text: 'The PM returned this at the Acceptance Gate',
       action: 'Address the return, then request acceptance again.', why: '', source: 'acceptances.jsonl',
     });
   }
   for (const s of live) {
     items.push({
-      kind: 'session', key: 'session', status: 'current', text: `Session “${clip(s.name, 60)}” is running on it`,
+      kind: 'session', key: 'session', status: 'current', owner: 'agent', act: null, sid: s.id || null, text: `Session “${clip(s.name, 60)}” is running on it`,
       action: 'Let it finish, or end it before accepting.', why: '', source: 'live sessions',
     });
   }
-  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', text: 'PM Acceptance' });
+  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', owner: 'pm', text: 'PM Acceptance' });
   else if (!hasAcceptStep) {
     items.push({
-      kind: 'accept', key: 'accept', status: 'pending', text: 'PM Acceptance',
+      kind: 'accept', key: 'accept', status: 'pending', owner: 'pm', act: null, text: 'PM Acceptance',
       action: 'The PM names one thing verified by hand, then records the acceptance (D12). It is the PM’s and cannot be delegated.',
       why: '', source: 'Acceptance Gate (D12)',
     });
@@ -101,6 +120,7 @@ function deriveNextSteps(input) {
   const engineNext = row.next && row.next.step ? row.next.step : null;
   const firstIdx = engineNext ? Math.max(0, items.findIndex((x) => x.kind === 'step' && x.key === engineNext)) : 0;
   items.forEach((it, n) => { it.n = n + 1; it.first = n === firstIdx; });
+  withIds(i.id, items);
   if (!items.length) return { state: 'open', summary: 'No step is outstanding — the ladder shows every required step done. Acceptance is the PM’s.', items: [] };
   const blockedN = items.filter((x) => x.status === 'blocked').length;
   return {

package/workspace/lib/preview-kind.js

@@ -24,7 +24,7 @@
   // Textual formats shown as ESCAPED source (never executed, R2). Broad on purpose — every entry
   // is escaped text, so breadth adds no risk (PRD open-question resolved: broad allowlist).
   const TEXT_EXT = new Set([
-    'txt', 'text', 'log', 'csv', 'tsv', 'json', 'jsonc', 'json5', 'ndjson',
+    'txt', 'text', 'log', 'csv', 'tsv', 'json', 'jsonc', 'json5', 'ndjson', 'jsonl', 'jsonlines', 'ldjson',
     'yaml', 'yml', 'toml', 'ini', 'cfg', 'conf', 'config', 'properties', 'env', 'example',
     'xml', 'rss', 'atom', // NB: .svg is classified 'image' (IMAGE_MIME, checked first) — it renders, not source
     'sh', 'bash', 'zsh', 'fish', 'ps1', 'bat',
@@ -45,6 +45,18 @@
     ico: 'image/x-icon', apng: 'image/apng',
   };
 
+  // File types that are binary by nature. The reader refuses these as binary WITHOUT reading them, so a
+  // type that is not on any list can still be tried as text (file-viewer-any-text) while these never are.
+  // An unlisted extension that turns out to be binary is still caught by the NUL and UTF-8 checks.
+  const BINARY_EXT = new Set([
+    'doc', 'docx', 'dot', 'dotx', 'ppt', 'pptx', 'potx', 'xls', 'xlsm', 'xltx', 'odt', 'ods', 'odp', 'pages', 'numbers', 'key',
+    'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', 'tar', '7z', 'rar', 'jar', 'war', 'apk', 'iso', 'dmg', 'pkg', 'deb', 'rpm',
+    'exe', 'dll', 'so', 'dylib', 'bin', 'o', 'a', 'class', 'pyc', 'wasm', 'node',
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'mp3', 'mp4', 'm4a', 'mov', 'wav', 'avi', 'mkv', 'webm', 'ogg', 'flac', 'aac',
+    'sqlite', 'sqlite3', 'db', 'mdb', 'psd', 'ai', 'heic', 'tif', 'tiff', 'raw',
+  ]);
+
   // Extension-less files that are really text (open as source).
   const TEXT_BASENAMES = new Set(['dockerfile', 'makefile', 'license', 'licence', 'authors',
     'notice', 'copying', 'changelog', 'procfile', 'brewfile', 'gemfile', 'rakefile', 'vagrantfile']);
@@ -77,6 +89,9 @@
     return 'inert';
   }
 
+  /** true when the extension names a type that is binary by nature (see BINARY_EXT). */
+  function isKnownBinary(name) { return BINARY_EXT.has(extOf(name)); }
+
   /** image MIME for /api/asset, or null when the extension is not an allowlisted image. */
   function imageMime(name) {
     return IMAGE_MIME[extOf(name)] || null;
@@ -105,5 +120,5 @@
   }
 
   return { previewKind, imageMime, assetMime, isTextSource, isRepoRelativeSrc, extOf,
-    MARKDOWN_EXT, TEXT_EXT, HTML_EXT, IMAGE_MIME };
+    isKnownBinary, MARKDOWN_EXT, TEXT_EXT, HTML_EXT, BINARY_EXT, IMAGE_MIME };
 });

package/workspace/lib/proactive-cli.js

@@ -0,0 +1,137 @@
+'use strict';
+/* proactive-cli.js — `pmos proactive …`: the terminal face of Today.
+ *
+ * A thin client of the running workspace server's own routes, like schedule-cli.js: one computation, one
+ * feedback ledger, one settings file. Nothing here writes a file itself, and nothing here starts a session,
+ * sends anything or changes an initiative. With no server running the command says so and exits 1.
+ *
+ *   pmos proactive today
+ *   pmos proactive scan
+ *   pmos proactive settings [--enabled on|off] [--trigger NAME=on|off] [--stalled-days N] [--quiet HH:MM-HH:MM|none] [--pause-learning on|off]
+ *   pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed [--note TEXT]
+ *   pmos proactive feedback --missed TEXT
+ *   pmos proactive brief [show]
+ *   pmos proactive brief submit --file PATH
+ *   pmos proactive brief schedule [--repo PATH]
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief'] };
+const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
+
+async function run(argv, { call, say, cwd = process.cwd() }) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  const fail = (m) => { say('✗ ' + m); return 1; };
+  if (group !== 'proactive' || !verb || flags.help || verb === 'help') { say(`usage: pmos proactive <${COMMANDS.proactive.join('|')}> …`); return verb ? 0 : 1; }
+  if (!COMMANDS.proactive.includes(verb)) return fail(`unknown command "${verb}" — use ${COMMANDS.proactive.join(', ')}`);
+  const probe = await call('GET', '/api/proactive/settings');
+  if (!probe) return fail('the workspace server is not running — start it with: pmos');
+
+  if (verb === 'today') {
+    const t = await call('GET', '/api/proactive/today');
+    if (!t || t.ok === false) return fail((t && t.error) || 'the server did not answer');
+    if (t.off) say('The engine is off. Nothing is scanned automatically.');
+    if (t.quiet) say('Quiet hours: no automatic scans now.');
+    for (const u of t.unreadable || []) say(`not read — ${u.name || u.repo}: ${u.error}`);
+    if (t.empty) say('Nothing is waiting on any repository that was read.');
+    for (const c of t.candidates || []) {
+      say(`${c.id}  ${c.kind}  ${c.owner === 'pm' ? 'yours' : "the agent's"}  ${c.title}`);
+      say(`    ${c.why}${c.evidence ? ' — ' + c.evidence : ''}`);
+    }
+    if (t.dismissed) say(`${t.dismissed} dismissed item(s) hidden for 7 days.`);
+    say(t.note);
+    return 0;
+  }
+  if (verb === 'scan') {
+    const r = await call('POST', '/api/proactive/scan', {});
+    if (!r || r.ok === false) return fail((r && r.error) || 'the scan failed');
+    say(`scanned — ${r.found} waiting, ${r.appended} new${(r.unreadable || []).length ? ', ' + r.unreadable.length + ' repository not read' : ''}`);
+    return 0;
+  }
+  if (verb === 'settings') {
+    const patch = {};
+    if ('enabled' in flags) { const v = onOff(flags.enabled, '--enabled'); if (v.err) return fail(v.err); patch.enabled = v; }
+    if ('pause-learning' in flags) { const v = onOff(flags['pause-learning'], '--pause-learning'); if (v.err) return fail(v.err); patch.pauseLearning = v; }
+    if ('trigger' in flags) {
+      const m = /^([a-z]+)=(on|off)$/.exec(flags.trigger);
+      if (!m) return fail('--trigger takes NAME=on or NAME=off, for example needs=off');
+      patch.triggers = { [m[1]]: m[2] === 'on' };
+    }
+    if ('name' in flags) patch.name = flags.name;
+    if ('brief-scoring' in flags) { const v = onOff(flags['brief-scoring'], '--brief-scoring'); if (v.err) return fail(v.err); patch.briefScoring = v; }
+    if ('brief-source' in flags) {
+      const m = /^([a-z]+)=(on|off)$/.exec(flags['brief-source']);
+      if (!m) return fail(`--brief-source takes NAME=on or NAME=off, where NAME is one of ${BRIEF_SOURCES.join(', ')}`);
+      patch.briefSources = { [m[1]]: m[2] === 'on' };
+    }
+    if ('stalled-days' in flags) patch.stalledDays = Number(flags['stalled-days']);
+    if ('quiet' in flags) {
+      if (flags.quiet === 'none') patch.quiet = null;
+      else { const m = /^(\d\d:\d\d)-(\d\d:\d\d)$/.exec(flags.quiet); if (!m) return fail('--quiet takes HH:MM-HH:MM, or none'); patch.quiet = { start: m[1], end: m[2] }; }
+    }
+    let s = probe.settings;
+    if (Object.keys(patch).length) {
+      const r = await call('POST', '/api/proactive/settings', patch);
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was changed.`);
+      s = r.settings;
+    }
+    say(`engine ${s.enabled ? 'on' : 'off'} · stalled after ${s.stalledDays} days · quiet ${s.quiet ? s.quiet.start + '-' + s.quiet.end : 'none'} · learning ${s.pauseLearning ? 'paused' : 'on'}`);
+    say('brief sources: ' + BRIEF_SOURCES.map((k) => `${k} ${s.briefSources && s.briefSources[k] ? 'on' : 'off'}`).join(', ') + ' · scoring ' + (s.briefScoring ? 'on' : 'off') + (s.name ? ' · name ' + s.name : ''));
+    say('watching: ' + Object.entries(s.triggers).map(([k, v]) => `${k} ${v ? 'on' : 'off'}`).join(', '));
+    return 0;
+  }
+  if (verb === 'brief') {
+    const sub = pos[0] || 'show';
+    if (sub === 'submit') {
+      if (!flags.file) return fail('usage: pmos proactive brief submit --file PATH');
+      let raw; try { raw = JSON.parse(fs.readFileSync(path.resolve(cwd, flags.file), 'utf8')); } catch (e) { return fail(`could not read ${flags.file} as JSON — ${e.message}`); }
+      const r = await call('POST', '/api/proactive/brief', raw);
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was stored.`);
+      say(`stored the brief for ${r.brief.date} — ${r.brief.priorities.length} priorities, ${r.brief.worth_asking.length} worth asking`);
+      return 0;
+    }
+    if (sub === 'schedule') {
+      let root; try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: flags.repo ? path.resolve(cwd, flags.repo) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return fail('this is not inside a git repository — use --repo PATH'); }
+      const wl = await call('GET', '/api/workspaces');
+      const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === path.resolve(root));
+      if (!hit) return fail(`${root} is not a registered workspace — open it with pmos first`);
+      const r = await call('POST', '/api/schedules/seed', { ws: hit.id, set: 'brief' });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}`);
+      if (r.created.length) say(`scheduled: ${r.created[0].name} (${r.created[0].cadence} ${r.created[0].time}) — it runs only while the workspace server runs`);
+      else say(`nothing to add — ${r.kept.map((k) => k.skill + ': ' + k.why).join('; ')}`);
+      return 0;
+    }
+    if (sub !== 'show') return fail('usage: pmos proactive brief [show|submit --file PATH|schedule]');
+    const r = await call('GET', '/api/proactive/brief');
+    if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+    say(r.greeting);
+    if (!r.brief) { say('No brief yet. Schedule one with: pmos proactive brief schedule'); return 0; }
+    if (r.stale) say(`This brief is for ${r.brief.date}, not today (${r.today}). It is out of date.`);
+    say('sources: ' + Object.entries(r.brief.sources).map(([k, v]) => `${k} ${v}`).join(', '));
+    for (const e of r.brief.calendar) say(`${e.start}  ${e.title}${e.with ? ' — ' + e.with : ''}`);
+    for (const x of r.brief.priorities) say(`${x.id}  priority  ${x.owner === 'pm' ? 'yours' : "the agent's"}  ${x.title}  (${x.confidence})\n    ${x.why_now}`);
+    for (const x of r.brief.worth_asking) say(`${x.id}  worth asking  ${x.title}  (${x.confidence})\n    ${x.why_now}`);
+    return 0;
+  }
+  // feedback
+  const body = {};
+  if (flags.note) body.note = flags.note;
+  if (flags.missed) { body.verdict = 'missed'; body.note = flags.missed; }
+  else {
+    const [id, what] = pos;
+    if (!id || !what) return fail('usage: pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed [--note TEXT]   or   --missed TEXT');
+    body.candidate_id = id;
+    if (['opened', 'dismissed', 'acted', 'ignored'].includes(what)) body.event = what; else body.verdict = what;
+  }
+  const r = await call('POST', '/api/proactive/feedback', body);
+  if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was recorded.`);
+  say('recorded');
+  return 0;
+}
+
+module.exports = { run, COMMANDS };