create-pmos 0.47.0 → 0.49.0

package/payload/scripts/workflow-state.js

@@ -54,6 +54,13 @@ const anchors = require('./anchor-resolve');
  * server. It is shared now, for the same reason `anchor-resolve` is.
  */
 const delivery = require('./delivery-index');
+/*
+ * Three flags the ladder cannot see (status-from-artifacts, Run 1): a spec file changed after an
+ * approval, requirement ids the rubric never cites, and `status:` prose the ladder contradicts. They
+ * sit BESIDE the steps. They never change a step, the stage, a colour or a count, and they write
+ * nothing. See scripts/status-facts.js.
+ */
+const statusFacts = require('./status-facts');
 
 // The OKR documents and the budget registry are read once per root, not once per initiative: the
 // board derives ~100 ladders in a single pass and re-reading the same three files each time is the
@@ -791,7 +798,7 @@ function computeWorkflowDerived(id, opts) {
 
   // ── D68: the pm-artifacts ladder replaces everything after the anchor ─────────────────────────
   if (pmProfile) {
-    return pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity });
+    return pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity, opts });
   }
 
   const prd = String(fm.prd_path || '').trim();
@@ -1235,10 +1242,15 @@ function computeWorkflowDerived(id, opts) {
     || steps.find((s) => s.status === 'pending' && s.next)
     || null;
 
+  // `opts.facts === false` exists so a test can prove the flags change nothing else in the ladder.
+  const facts = (opts && opts.facts === false) ? {}
+    : statusFacts.compute({ root, L, id, fm, lane: effLane, stage, runs, accepted });
+
   return {
     ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
     last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
     title: fm.title || id, anchor: fm.parent_kr || null, profile: 'product-code',
+    ...facts,
     steps, blockers: blockers.map((s) => s.key), gate_failures: gateFailures.map((s) => s.rule || s.key),
     next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
     range: range.ok ? { base: range.base, commits: range.shas.length, whole_history: !!range.wholeHistory } : { error: range.reason },
@@ -1262,7 +1274,7 @@ function computeWorkflowDerived(id, opts) {
  * existence and their order fail CI for a non-legacy record). Review, approval and handoff are never
  * CI-blocking in either track: none can be true before the PR exists.
  */
-function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity }) {
+function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, recRel, range, inChange, lastActivity, opts }) {
   const declared = String(fm.track || '').trim().toLowerCase();
   const track = declared === 'light' || declared === 'governed' ? declared
     : (laneDefs.laneDef('pm-artifacts', effLane) || laneDefs.laneDef('pm-artifacts', 'prd')).track;
@@ -1336,10 +1348,15 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   const blockers = steps.filter((x) => x.status === 'blocked');
   const gateFailures = blockers.filter((x) => x.blocking);
   const next = steps.find((x) => x.status === 'blocked') || steps.find((x) => x.status === 'pending' && x.next) || null;
+  // status-from-artifacts: a document repository gets the one fact that applies to it — the brief or the deliverable
+  // changed after the PM accepted it. Coverage and the status-line check are product-code facts and stay null here.
+  const facts = (opts && opts.facts === false) ? {}
+    : statusFacts.computeArtifacts({ root, L, fm, accepted });
   return {
     ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
     last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
     title: fm.title || id, anchor: fm.parent_kr || null, profile: 'pm-artifacts', track,
+    ...facts,
     steps, blockers: blockers.map((x) => x.key), gate_failures: gateFailures.map((x) => x.rule || x.key),
     next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
     range: range.ok ? { base: range.base, commits: range.shas.length, whole_history: !!range.wholeHistory } : { error: range.reason },
@@ -1390,6 +1407,44 @@ function brief(s, n) {
   return t.length > n ? `${t.slice(0, n - 1)}…` : t;
 }
 
+/**
+ * The three status-from-artifacts lines, one plain sentence each with its basis. A flag, never a
+ * step: nothing here is a state, and a missing basis prints nothing (never a pass).
+ */
+function renderFacts(w) {
+  const out = [];
+  const sa = w.since_approval;
+  if (sa) {
+    if (sa.status === 'unknown') out.push(`  ${c(90, '?')} since approval ${c(90, `cannot tell — ${sa.reason}`)}`);
+    else {
+      for (const a of sa.approvals) {
+        const what = a.kind === 'contract' ? 'the contract was approved' : 'the PM accepted';
+        if (a.status === 'unknown') out.push(`  ${c(90, '?')} since approval ${c(90, `${what} (${a.run_id || 'no run id'}) — ${a.reason}`)}`);
+        else if (!a.changed.length) out.push(`  ${c(90, '·')} since approval ${c(90, `no spec file changed since ${what} (${a.approved_sha})`)}`);
+        else {
+          const files = [...new Set(a.changed.map((x) => x.file))].join(', ');
+          const last = a.changed[a.changed.length - 1];
+          out.push(`  ${c(33, '!')} since approval ${files} changed after ${what} (${a.approved_sha}); ${a.changed_total} commit(s), latest ${last.sha} ${last.date || ''}`);
+        }
+      }
+    }
+  }
+  const cv = w.coverage;
+  if (cv) {
+    if (cv.status === 'unknown') out.push(`  ${c(90, '?')} coverage      ${c(90, `cannot tell — ${cv.reason}`)}`);
+    else if (!cv.uncited.length && !cv.orphan_citations.length) out.push(`  ${c(90, '·')} coverage      ${c(90, `all ${cv.requirements} requirement ids are cited in the rubric`)}`);
+    else {
+      const bits = [];
+      if (cv.uncited.length) bits.push(`${cv.uncited.join(', ')} not cited in the rubric`);
+      if (cv.orphan_citations.length) bits.push(`${cv.orphan_citations.join(', ')} cited but not in the PRD`);
+      out.push(`  ${c(33, '!')} coverage      ${bits.join('; ')} (cited is not graded)`);
+    }
+  }
+  const rs = w.record_says;
+  if (rs) out.push(`  ${c(33, '!')} record says    status: ${rs.reason}`);
+  return out;
+}
+
 function renderLadder(w) {
   if (!w.ok) return c(31, `✗ ${w.error}`);
   const out = [];
@@ -1403,6 +1458,8 @@ function renderLadder(w) {
     out.push(`  ${mark(s.status)} ${s.status === 'na' || s.status === 'pending' ? c(90, label) : label} ${brief(s.evidence, 110)}`);
     if (s.next) out.push(`    ${c(90, '→')} ${c(s.status === 'blocked' ? 33 : 90, brief(s.next, 150))}`);
   }
+  const flags = renderFacts(w);
+  if (flags.length) { out.push(`  ${c(90, '─'.repeat(78))}`); out.push(...flags); }
   out.push('');
   if (w.next) out.push(`  ${c(1, 'next:')} ${w.next.action}`);
   else out.push(`  ${c(32, 'nothing blocking — the ladder is complete')}`);

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-04T10:38:12Z"}
+generated: {by: process:create-pmos, at: "2026-10-05T00:43:02Z"}
 status: stable
 ---
 

package/payload/state/log.md

@@ -2,6 +2,6 @@
 
 Newest first, ISO dates.
 
-## 2026-10-04
+## 2026-10-05
 
 - Adopted OKF v0.2 (D73).

package/workspace/README.md

@@ -1,7 +1,7 @@
 ---
 type: Reference
 title: "PMOS Terminal Workspace"
-timestamp: 2026-07-30
+timestamp: 2026-10-04
 ---
 
 # PMOS Terminal Workspace
@@ -140,7 +140,7 @@ The three-column layout is retired. The surface is now **four collapsible panels
 - **Documents read like documents** — the identity block becomes a card, tables are tables, nested/ordered/task lists survive, and a relative `.md` link opens that document in the reader.
 - **Preview more than markdown** — `.skill` files render as markdown; text/config files open as escaped source; `.html` opens as source with an opt-in **sandboxed** render (scripts + network denied); markdown renders **repo-relative images inline**. A remote `![](https://…)` image is never fetched (no zero-click beacon); a binary stays listed but inert (open it in your editor).
 
-**Fixture mode.** `?fixture=proto` renders the whole surface from a bundled seed file, with the server unable to read any repository — that is how the design comparison is run (`npm run test:parity`), and it is never the default.
+**Fixture mode.** `?fixture=cockpit` and `?fixture=proto` render the whole surface from a bundled seed file, with the server unable to read any repository. `?fixture=cockpit` holds the seed of the cockpit mockup, and `npm run test:parity` compares it with the mockup board WsA (the blocking CI step). `?fixture=proto` holds the seed of the four-panel prototype that the cockpit replaced, and `npm run test:parity:four-panel` compares it with that prototype. Fixture mode is never the default.
 
 ## Artifact links are declarations, not integrations
 The PMOS server makes no outbound request and holds no credential, with one named exception ([D79](/okf/products/pmos/adr/d79-typesafe-validation-egress.md)): when you save a TypeSafe key and turn validation on for a repository, the **validate** page sends that repository's document text to `api.typesafe.ai`, from one module, only after you confirm the plan. With no key, nothing is sent. The key stays on this machine, is never shown again, and is never given to a terminal. The consistency checks at the top of the **validate** page are local: they read files and git and send nothing. Automatic checking is off until you switch it on for a repository, and then the workspace appends problems to that repository's `claims.jsonl`. A second switch, **check with Jev automatically** ([D80](/okf/products/pmos/adr/d80-jev-claim-pairs.md)), is also off; only when a key, validation, automatic checking and that switch all hold does the workspace send pairs of short claim texts that changed, after a first pass that records what exists and sends nothing. The workspace makes no request you did not ask for. Its git network verbs are named and press-only: `Sync` runs `fetch`, a fast-forward or an own-commit rebase, a commit of record paths, and `push` — only when you press it, never on a timer or on load, never forced ([D70](/okf/products/pmos/adr/d70-stopped-initiatives-and-sync.md)). A web page opens in a tab only when you type or click its address, and a restored web tab loads only when you press "load this page" ([D69](/okf/products/pmos/adr/d69-web-tab.md)). Linking an artifact to an external destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to `pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector configured its summary line says exactly that: *no connector configured — nothing was read, and nothing will be written*, with the approval buttons disabled. A difference summary it never read would be the watermelon this repo has a word for.

package/workspace/bin/live-notes.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/* live-notes — Run 1 of jev-live-notes: place the talking points of a conversation against a repository's open
+ * initiatives, as proposals. No page, no microphone, no audio, no network call.
+ *
+ *   node bin/live-notes.js run --repo <dir> [--segments <file>|-] [--answers <file>] [--session <id>] [--anchor <a>] [--json]
+ *   node bin/live-notes.js decide --repo <dir> --session <id> --segment <id> --action accept|change|reject [--initiative <id>] [--relation <word>]
+ *   node bin/live-notes.js close --repo <dir> --session <id>
+ *   node bin/live-notes.js ingest --repo <dir> --transcript <file> --source <name> --session <id>   a transcript, only what is new (Run 4)
+ *   node bin/live-notes.js list  --repo <dir> --session <id> [--json]       the ranked list (Run 2)
+ *   node bin/live-notes.js rate  --repo <dir> --session <id>
+ *   node bin/live-notes.js plan  --repo <dir> --session <id> [--json]       what an agent should write, on which tier (Run 3)
+ *   node bin/live-notes.js context --repo <dir> --session <id> --answers <file>   LIVECONTEXT and LIVECANDIDATE lines (Run 3)
+ *   node bin/live-notes.js switch --repo <dir> on|off [--retention-days <n>]
+ *
+ * Segments are one per line: plain text, or a JSON object {"text","at","speaker","source","private"}.
+ * Without `--answers`, each point is left `pending` and the prompt for an agent session is printed; the agent's
+ * `LIVENOTE {json}` lines go back in with `--answers`. When all three gates hold (a key, consent for the repository,
+ * and `switch on`), the prompt asks that agent session to make the two choices with the Typesafe skill (Run 5). This
+ * command sends nothing itself and injects no sender. The key is never read, only whether one exists.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const live = require('../lib/live-notes');
+const settings = require('../lib/typesafe-settings');
+const { defaultRoot } = require('../lib/state-root');
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const opt = (n, d = null) => { const i = argv.indexOf('--' + n); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const flag = (n) => argv.includes('--' + n);
+const die = (m, c = 2) => { console.error('live-notes: ' + m); process.exit(c); };
+
+if (!['run', 'decide', 'close', 'rate', 'switch', 'plan', 'context', 'ingest', 'list'].includes(cmd)) die('commands: run, ingest, list, decide, close, rate, switch, plan, context (see the header of this file)');
+const root = path.resolve(opt('repo', process.cwd()));
+if (!fs.existsSync(root)) die('no such directory: ' + root);
+const runtimeDir = defaultRoot();
+const exclude = settings.getRepo(runtimeDir, root).exclude;
+const consent = settings.getRepo(runtimeDir, root).consent;
+const sw = live.getSwitch(runtimeDir, root);
+live.purgeExpired(runtimeDir);
+
+function session(id, extra = {}) {
+  return live.openSession({ root, runtimeDir, session: id, key: settings.status(runtimeDir, process.env).present ? 'present' : null,
+    flags: { consent, live: sw.live }, exclude, anchor: opt('anchor'), ask: null, ...extra });
+}
+
+(async () => {
+  try {
+    if (cmd === 'switch') {
+      const pos = argv.filter((x, i) => !x.startsWith('--') && !(argv[i - 1] || '').startsWith('--'));
+      const on = pos[1] === 'on' ? true : pos[1] === 'off' ? false : null;
+      if (on === null && !opt('retention-days')) die('say on or off, or --retention-days <n>');
+      const r = live.setSwitch(runtimeDir, root, { live: on === null ? undefined : on, retention_days: opt('retention-days') ? Number(opt('retention-days')) : undefined });
+      console.log(`live notes may use Jev: ${r.live ? 'on' : 'off'} · raw transcript kept ${r.retention_days ? r.retention_days + ' day(s) after close' : 'only until close'}`);
+      return;
+    }
+    const id = opt('session');
+    if (cmd === 'run' || cmd === 'ingest') {
+      const src = cmd === 'ingest' ? opt('transcript') : opt('segments');
+      if (cmd === 'ingest' && !src) die('--transcript <file> is required');
+      if (!src && !opt('answers')) die('give --segments <file>|- , --answers <file>, or both');
+      const probe = session(id);
+      const out = { session: probe.id, path: probe.path, gates_missing: probe.gates.missing, withheld: [], pending: [], error: null, rows: [], rejected: [] };
+      let prompt = null;
+      let s = probe;
+      if (src) {
+        const text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
+        const sourceName = opt('source') || (src === '-' ? 'stdin' : path.basename(src));
+        const raw = cmd === 'ingest' ? live.segmentsFromTranscript(text, { source: sourceName }) : text.split(/\r?\n/).filter((l) => l.trim()).map((l) => { if (l.trim().startsWith('{')) { try { return JSON.parse(l); } catch { /* plain */ } } return l; });
+        const r = await s.add(raw, { source: sourceName, dedupe: cmd === 'ingest' });
+        out.skipped_duplicates = r.skipped_duplicates;
+        Object.assign(out, { withheld: r.withheld, pending: r.pending, error: r.error || null, rows: r.rows });
+        prompt = r.prompt;
+      }
+      if (opt('answers')) {
+        const ans = live.parseAgentAnswers(fs.readFileSync(opt('answers'), 'utf8'), s.items.map((i) => i.id));
+        out.rejected = ans.rejected;
+        const r = s.answer(ans.answers);
+        out.rows = out.rows.concat(r.answered);
+        out.pending = out.pending.filter((x) => !r.answered.some((a) => a.segment === x));
+        if (r.unknown.length) out.unknown_segments = r.unknown;
+        if (r.answered.length) prompt = null;
+      }
+      if (flag('json')) { console.log(JSON.stringify({ ...out, prompt }, null, 2)); return; }
+      const why = out.path === 'jev-agent' ? 'the prompt asks your agent session to use the Typesafe skill; this command sends nothing itself' : live.gateSentence(out.gates_missing) || 'all gates are open';
+      console.log(`session ${out.session} · path: ${out.path} (${why})`);
+      if (out.error) console.log('stopped: ' + out.error);
+      if (out.skipped_duplicates) console.log(`skipped ${out.skipped_duplicates} point(s) already in this session`);
+      if (out.rejected.length) console.log(`rejected ${out.rejected.length} off-shape answer line(s): ${out.rejected.join(', ')}`);
+      for (const x of out.rows) console.log(`  ${x.segment}: ${x.status === 'proposed' ? `${x.relation} ${x.initiative} (${x.relation_band}) · ${x.confidence}${x.in_scope === false ? ' · outside scope' : ''}` : x.status}`);
+      for (const w of out.withheld) console.log(`  ${w.id}: withheld — ${w.reason}`);
+      if (prompt) console.log('\nGive this to an agent session, then pass its LIVENOTE lines back with --answers <file> --session ' + out.session + ':\n\n' + prompt);
+      return;
+    }
+    if (!id) die('--session <id> is required');
+    { const known = live.apiList({ root, session: id }); if (!known.ok) die(known.error, 1); }   // a command on a session that does not exist creates nothing
+    const s = session(id);
+    if (cmd === 'decide') { const row = s.decide({ segment: opt('segment'), action: opt('action'), initiative: opt('initiative'), relation: opt('relation') }); console.log(`recorded: ${row.action} ${row.segment}${row.overridden ? ' (override)' : ''}`); return; }
+    if (cmd === 'close') { const r = s.close({ retentionDays: sw.retention_days }); console.log(r.already ? 'already closed' : `closed · note: ${r.note} · raw transcript: ${r.transcript}`); return; }
+    if (cmd === 'list') {
+      const r = live.apiList({ root, session: id });
+      if (!r.ok) die(r.error, 1);
+      if (flag('json')) { console.log(JSON.stringify(r.ranked, null, 2)); return; }
+      const k = r.ranked;
+      console.log(`session ${id} · path: ${k.path}${k.closed ? ' · closed' : ''} · ${k.counts.points} point(s), ${k.counts.pending} not yet answered, ${k.withheld} withheld${k.paused ? ' · PAUSED: ' + k.paused.reason : ''}`);
+      for (const sec of k.sections) {
+        console.log(`\n${sec.title}`);
+        for (const x of sec.items) console.log(`  ${x.segment}: "${x.quote}"${x.initiative && x.initiative !== 'none' ? ` — ${x.relation} ${x.initiative} (${x.relation_band})` : ''}${x.in_scope === false ? ' · outside scope' : ''}${x.decision ? ' · PM: ' + x.decision.action : ''}${x.context ? ' · note: ' + x.context.note : ''}`);
+      }
+      if (k.candidates.length) { console.log('\nPossible new initiatives'); for (const c of k.candidates) console.log(`  ${c.candidate}: ${c.draft ? '"' + c.draft.title + '" (' + c.draft.lane + ')' : c.topic_terms.join(', ')} · ${c.segments.length} points · prior-rejection check found ${c.prior_rejection_found}`); }
+      return;
+    }
+    if (cmd === 'plan') {
+      const p = s.plan();
+      if (flag('json')) { console.log(JSON.stringify(p, null, 2)); return; }
+      console.log(`tagging: ${p.tagging_tier} tier · ${p.context.filter((x) => !x.done).length} context note(s) and ${p.candidates.filter((x) => !x.done).length} candidate draft(s) to write`);
+      for (const x of p.context) console.log(`  ${x.done ? '✓' : '·'} ${x.segment} [${x.tier}] ${x.reasons.join('; ')} — read ${x.read.join(', ')}`);
+      for (const x of p.candidates) console.log(`  ${x.done ? '✓' : '·'} ${x.candidate} [${x.tier}] ${x.topic_terms.join(', ')}`);
+      return;
+    }
+    if (cmd === 'context') {
+      if (!opt('answers')) die('--answers <file> is required');
+      const text = fs.readFileSync(opt('answers'), 'utf8');
+      const c = s.addContext(live.parseContext(text).entries);
+      const d = s.addDrafts(live.parseDrafts(text).entries);
+      console.log(`accepted ${c.accepted.length} context note(s) and ${d.accepted.length} candidate draft(s)`);
+      for (const r of c.rejected.concat(d.rejected)) console.log(`  rejected ${r.segment || r.candidate || '?'}: ${r.reason}`);
+      return;
+    }
+    if (cmd === 'rate') { console.log(JSON.stringify(live.overrideRate(s.ledger()), null, 2)); return; }
+  } catch (e) { die(e.message, 1); }
+})();