create-pmos 0.134.0 → 0.135.0

package/workspace/lib/engine/breakdown-ops.js

@@ -0,0 +1,180 @@
+'use strict';
+/*
+ * breakdown-ops.js — Breakdown is PMOS-only, non-development work (console3 wave E1b; HANDOFF 14f). Tickets are Jira only.
+ *
+ * Three phases (discovery, design, launch); each item has a source (local, figma, calendar, gmail, notes), an owner and points.
+ * An item can wait on a Jira ticket: a `dependency` event holds the ticket key, and planInput() turns the items into the
+ * { id: { deps, dur } } shape that scripts/derived/plan.js plan() reads (so release notes wait on the audit ticket).
+ *
+ * STORE. One append-only JSONL, <root>/breakdown-pmos.jsonl, written only through scripts/trust/ledger.js append. The writer
+ * is apply(); every other function is pure. Lines: { id (ULID), kind: add|edit|delete|undo|dependency, rid, fields?, snapshot?,
+ * corrects?, why, at, by, via }. `by` and `via` come from the call path (the ledger), never from a caller.
+ *
+ * JIRA IS READ-ONLY HERE. Jira-owned fields (title, owner, status) of an item a Jira ticket represents change only as a
+ * PROPOSAL ({ proposal:true }, no event). Such an item cannot be deleted here: the answer is unlink advice. Jira engineering
+ * load enters capacityLoad() as data and is returned as data; no function writes it.
+ */
+const fs = require('fs');
+const path = require('path');
+const ledger = require('./trust/ledger.js');
+
+const PHASES = ['discovery', 'design', 'launch'];
+const SOURCES = ['local', 'figma', 'calendar', 'gmail', 'notes'];
+const JIRA_OWNED = ['title', 'owner', 'status'];
+const UNDO_MS = 8000;
+const DEFAULT_PPW = 5;                 // same default as workspace/lib/routes-forecast.js for an owner with no entry
+const JIRA_KEY = /^[A-Z][A-Z0-9]+-\d+$/;
+const FILE = 'breakdown-pmos.jsonl';
+
+const refuse = (error, extra) => ({ ok: false, error, ...(extra || {}) });
+const pts = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+const fileOf = (root) => path.join(root, FILE);
+const readLines = (root) => { try { return ledger.read(fileOf(root)); } catch { return []; } };
+
+/** fold(lines) -> items in first-add order. delete removes, undo restores the snapshot, dependency edits `deps` (Jira keys). */
+function fold(lines) {
+  const by = new Map();
+  const deletes = new Map();
+  for (const e of lines) {
+    if (!e || !e.rid) continue;
+    if (e.kind === 'add') by.set(e.rid, { rid: e.rid, deps: [], ...e.fields });
+    else if (e.kind === 'edit' && by.has(e.rid)) Object.assign(by.get(e.rid), e.fields);
+    else if (e.kind === 'dependency' && by.has(e.rid) && e.fields && e.fields.jira) {
+      const it = by.get(e.rid), k = e.fields.jira;
+      it.deps = e.fields.remove ? it.deps.filter((d) => d !== k) : [...new Set([...it.deps, k])];
+    } else if (e.kind === 'delete' && by.has(e.rid)) { deletes.set(e.id, e.snapshot || by.get(e.rid)); by.delete(e.rid); }
+    else if (e.kind === 'undo' && deletes.has(e.corrects)) by.set(e.rid, { ...deletes.get(e.corrects) });
+  }
+  return [...by.values()];
+}
+const list = (root) => fold(readLines(root));
+
+function checkFields(f, { partial }) {
+  if ('title' in f || !partial) if (!String(f.title || '').trim()) return 'an item needs a title';
+  if ('phase' in f || !partial) if (!PHASES.includes(f.phase)) return 'phase must be discovery, design or launch';
+  if ('source' in f) {
+    if (String(f.source).toLowerCase() === 'jira') return 'Jira tickets live in Tickets; Breakdown holds PMOS-only work';
+    if (!SOURCES.includes(f.source)) return 'source must be local, figma, calendar, gmail or notes';
+  }
+  if ('points' in f && f.points !== null && !pts(f.points)) return 'points must be a number above 0';
+  return null;
+}
+
+const newRid = () => 'bd-' + ledger.newId().slice(-8).toLowerCase();
+
+/** addItem(items, { title, phase, source?, owner?, points?, initiative?, jira_key? }) -> { ok, rid, events } */
+function addItem(items, input) {
+  const i = input || {};
+  const fields = { title: i.title, phase: i.phase, source: i.source || 'local' };
+  const err = checkFields({ ...fields, ...(i.points != null ? { points: i.points } : {}) }, { partial: false });
+  if (err) return refuse(err);
+  fields.title = String(i.title).trim();
+  for (const k of ['owner', 'points', 'initiative', 'jira_key']) if (i[k] != null && i[k] !== '') fields[k] = i[k];
+  if (fields.jira_key && !JIRA_KEY.test(fields.jira_key)) return refuse('jira_key must look like ABC-123');
+  const rid = i.rid || newRid();
+  if ((items || []).some((x) => x.rid === rid)) return refuse('item exists: ' + rid);
+  return { ok: true, rid, events: [{ kind: 'add', rid, fields, why: 'item added' }] };
+}
+
+/**
+ * editItem(items, rid, fields) -> { ok, events, proposal?, proposals? }
+ * title, owner and status of an item a Jira ticket represents are Jira's: they come back as { proposal:true, proposals:[...] }
+ * with NO event. The other fields (phase, points, source) still apply.
+ */
+function editItem(items, rid, fields) {
+  const it = (items || []).find((x) => x.rid === rid);
+  if (!it) return refuse('no such item: ' + rid);
+  const f = { ...(fields || {}) };
+  delete f.rid; delete f.deps;
+  const out = { ...f };
+  const proposals = [];
+  if (it.jira_key) {
+    for (const k of [...JIRA_OWNED, 'jira_key']) {
+      if (k in out && out[k] !== it[k]) { proposals.push({ field: k, from: it[k] === undefined ? null : it[k], to: out[k] }); }
+      delete out[k];
+    }
+  }
+  const err = checkFields(out, { partial: true });
+  if (err) return refuse(err);
+  const keys = Object.keys(out).filter((k) => out[k] !== it[k]);
+  const events = keys.length ? [{ kind: 'edit', rid, fields: Object.fromEntries(keys.map((k) => [k, out[k]])), why: 'edited ' + keys.join(', ') }] : [];
+  if (!events.length && !proposals.length) return refuse('nothing to change');
+  return { ok: true, events, ...(proposals.length ? { proposal: true, proposals, note: 'Jira owns these fields; the change is a proposal the PM sends by slide, nothing was applied' } : {}) };
+}
+
+/** deleteItem(items, rid, { now }) -> a delete event with a snapshot; undo for UNDO_MS. A Jira-backed item gets unlink advice. */
+function deleteItem(items, rid, opts = {}) {
+  const it = (items || []).find((x) => x.rid === rid);
+  if (!it) return refuse('no such item: ' + rid);
+  if (it.jira_key) return refuse('a Jira ticket represents this item, so it cannot be deleted here', { jira_backed: true, advice: `Unlink ${it.jira_key} from the item, or close the ticket in Jira; Breakdown does not delete what Jira holds` });
+  const now = opts.now || new Date();
+  return { ok: true, events: [{ kind: 'delete', rid, snapshot: { ...it }, why: 'item deleted', at: now.toISOString() }], undo_ms: UNDO_MS };
+}
+
+/** undoEvent(lines, rid, now) -> { ok, events } while the last delete of rid is younger than 8 seconds; else a refusal. */
+function undoEvent(lines, rid, now = new Date()) {
+  const del = [...lines].reverse().find((e) => e && e.rid === rid && (e.kind === 'delete' || e.kind === 'undo'));
+  if (!del || del.kind === 'undo') return refuse('nothing to undo for ' + rid);
+  if (now.getTime() - new Date(del.at).getTime() > UNDO_MS) return refuse('the undo window (8 seconds) has passed', { expired: true });
+  return { ok: true, events: [{ kind: 'undo', rid, corrects: del.id, why: 'delete undone' }] };
+}
+
+/** setDependency(items, rid, jiraKey, { remove }) -> a dependency event; the item then waits on that ticket. */
+function setDependency(items, rid, jiraKey, opts = {}) {
+  const it = (items || []).find((x) => x.rid === rid);
+  if (!it) return refuse('no such item: ' + rid);
+  if (!JIRA_KEY.test(String(jiraKey || ''))) return refuse('a dependency is a Jira ticket key such as ABC-123');
+  const has = it.deps.includes(jiraKey);
+  if (opts.remove ? !has : has) return refuse(opts.remove ? 'no such dependency' : 'already depends on ' + jiraKey);
+  return { ok: true, events: [{ kind: 'dependency', rid, fields: { jira: jiraKey, ...(opts.remove ? { remove: true } : {}) }, why: (opts.remove ? 'stopped waiting on ' : 'waits on ') + jiraKey }] };
+}
+
+/**
+ * planInput(items, jira, { daysPerPoint }) -> { id: { deps, dur } } for scripts/derived/plan.js plan(). `jira` is read-only data,
+ * { 'ABC-1': { days, done } }. A Jira key an item waits on becomes a node with the ticket's remaining days (0 when done or unknown).
+ */
+function planInput(items, jira, opts = {}) {
+  const dpp = opts.daysPerPoint || 1;
+  const s = {};
+  for (const it of items || []) {
+    s[it.rid] = { deps: [...it.deps], dur: it.done ? 0 : (it.points || 1) * dpp };
+    for (const k of it.deps) if (!s[k]) { const j = (jira || {})[k] || {}; s[k] = { deps: [], dur: j.done ? 0 : Number(j.days) || 0 }; }
+  }
+  return s;
+}
+
+/**
+ * capacityLoad(items, people, weeks, jiraLoad) -> [{ person, pmos_points, capacity, jira_points, over, free }]
+ * Compares the PMOS points of each owner to points_per_week * weeks. jiraLoad ({ person: points }) is engineering load, shown
+ * read-only and never subtracted or written. Unassigned points come back as person null.
+ */
+function capacityLoad(items, people, weeks = 2, jiraLoad = {}) {
+  const jira = Object.freeze({ ...jiraLoad });
+  const ppw = new Map((people || []).map((p) => [p.id, Number(p.points_per_week) || DEFAULT_PPW]));
+  const load = new Map();
+  for (const it of items || []) {
+    if (it.done) continue;
+    const who = it.owner || null;
+    load.set(who, (load.get(who) || 0) + (Number(it.points) || 1));
+  }
+  const ids = [...new Set([...ppw.keys(), ...[...load.keys()].filter(Boolean)])];
+  const rows = ids.map((person) => {
+    const capacity = (ppw.get(person) || DEFAULT_PPW) * weeks, used = load.get(person) || 0;
+    return { person, pmos_points: used, capacity, jira_points: jira[person] || 0, over: used > capacity, free: Math.max(0, capacity - used) };
+  });
+  if (load.has(null)) rows.push({ person: null, pmos_points: load.get(null), capacity: 0, jira_points: 0, over: false, free: 0, unassigned: true });
+  return rows;
+}
+
+/** apply(root, events, actor, { now }) -> { ok, written } | { ok:false, error }. The one writer; ledger.append validates each line. */
+function apply(root, events, actor, opts = {}) {
+  const now = opts.now || new Date();
+  fs.mkdirSync(root, { recursive: true });
+  const written = [];
+  try {
+    for (const e of events) written.push(ledger.append(fileOf(root), { id: ledger.newId(), at: now.toISOString(), ...e }, actor));
+  } catch (err) { return { ok: false, error: err.message, written }; }
+  return { ok: true, written };
+}
+
+module.exports = { PHASES, SOURCES, JIRA_OWNED, UNDO_MS, FILE, fileOf, readLines, fold, list, addItem, editItem, deleteItem, undoEvent, setDependency, planInput, capacityLoad, apply };

package/workspace/lib/engine/calendar-import.js

@@ -0,0 +1,84 @@
+'use strict';
+/* calendar-import.js — cached calendar metadata, supplied by a caller (console3 wave E2a).
+ *
+ * PMOS holds no calendar credentials. An agent session with the PM's own connector fetches the events and hands them
+ * here; nothing in this file calls a network. An import is untrusted data (scripts/trust/import-guard.js): hidden text
+ * is stripped, every line is datamarked, the raw text is hashed, and the only claim an import can make is 'reported'.
+ *
+ *   importEvents(rawEvents, { fetchedAt, sensitivity }) → [event]   pure; a missing or unknown sensitivity is refused
+ *   foldEvents(lines)                                   → [event]   current events; the PM's notes survive a refresh
+ *   appendImport(file, events, actor, now)              → lines     ledger append (scripts/trust/ledger.js)
+ *   appendNote(file, eventId, text, actor, now)         → line      a PM note on one event
+ *   readLines(file) · cacheMarkdown(events, dir, now)   the Markdown cache is the PM's trust/import-calendar.js, unchanged
+ */
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+const guard = require('./trust/import-guard.js');
+const L = require('./trust/ledger.js');
+const sampleCache = require('./trust/import-calendar.js');
+
+const SENSITIVITY = Object.freeze(['public', 'internal', 'confidential', 'private']);
+const HIDDEN = [/<!--[\s\S]*?-->/g, /[​-‏⁠]/g, /[\u{E0000}-\u{E007F}]/gu];
+
+const strip = (s) => HIDDEN.reduce((t, re) => t.replace(re, ''), String(s == null ? '' : s));
+const mark = (s) => s.split('\n').map((l) => '▒ ' + l).join('\n');
+const nameOf = (a) => (typeof a === 'string' ? a : (a && (a.name || a.displayName)) || '');
+
+function importEvents(rawEvents, opts = {}) {
+  if (!SENSITIVITY.includes(opts.sensitivity)) throw new Error('an import needs a sensitivity label: ' + SENSITIVITY.join(', '));
+  if (!Array.isArray(rawEvents)) throw new Error('events must be a list');
+  const fetchedAt = opts.fetchedAt || new Date().toISOString();
+  return rawEvents.map((e, i) => {
+    const at = e && (e.at || e.start);
+    if (!e || !e.id || !e.title || !at) throw new Error(`event ${i}: id, title and start are required`);
+    const attendeesRaw = (e.attendees || []).map(nameOf).filter(Boolean);
+    const rawText = [e.title, ...attendeesRaw].join('\n');
+    const findings = guard.scan(rawText);
+    const title = strip(e.title).replace(/\s+/g, ' ').trim();
+    const attendees = attendeesRaw.map((a) => strip(a).replace(/\s+/g, ' ').trim());
+    return {
+      id: String(e.id), at: String(at), end: e.end ? String(e.end) : null, title, attendees,
+      initiative: e.initiative ? String(e.initiative) : null, agent_prep_notes: '',
+      fetched_at: fetchedAt, external: true, sensitivity: opts.sensitivity,
+      label: 'reported', trust: 'untrusted', marked: mark([title, ...attendees].join('\n')),
+      findings, raw_sha256: crypto.createHash('sha256').update(rawText).digest('hex'),
+    };
+  });
+}
+
+// Lines: { kind:'calendar_event', ...event } replaces the cached part; { kind:'calendar_note', event_id, text } adds a PM note.
+function foldEvents(lines) {
+  const by = new Map();
+  for (const l of lines || []) {
+    if (!l) continue;
+    if (l.kind === 'calendar_event' && l.event && l.event.id) {
+      const prev = by.get(l.event.id);
+      by.set(l.event.id, { ...l.event, agent_prep_notes: prev ? prev.agent_prep_notes : l.event.agent_prep_notes || '', pm_notes: prev ? prev.pm_notes : [] });
+    } else if (l.kind === 'calendar_note' && by.has(l.event_id)) {
+      by.get(l.event_id).pm_notes.push({ text: l.text, at: l.at, id: l.id });
+    }
+  }
+  return [...by.values()].sort((a, b) => String(a.at).localeCompare(String(b.at)));
+}
+
+const readLines = (file) => L.read(file);
+
+function appendImport(file, events, actor, now) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  return events.map((event) => L.append(file, { id: L.newId(), kind: 'calendar_event', why: 'calendar import (reported, untrusted)', at: now || new Date().toISOString(), event }, actor));
+}
+
+function appendNote(file, eventId, text, actor, now) {
+  const t = String(text || '').trim();
+  if (!t) throw new Error('the note needs text');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  return L.append(file, { id: L.newId(), kind: 'calendar_note', why: 'PM note on an imported event', event_id: eventId, text: t, at: now || new Date().toISOString() }, actor);
+}
+
+// The PM's Markdown cache writer, unchanged; events are mapped to its shape. (It labels files 'internal'; the ledger holds the real label.)
+function cacheMarkdown(events, dir, now) {
+  return sampleCache.importEvents(events.map((e) => ({ id: e.id, title: e.title, start: e.at, end: e.end || e.at, attendees: e.attendees, initiative: e.initiative })), dir, now);
+}
+
+module.exports = { SENSITIVITY, importEvents, foldEvents, appendImport, appendNote, readLines, cacheMarkdown };

package/workspace/lib/engine/calendar-model.js

@@ -0,0 +1,185 @@
+'use strict';
+/* calendar-model.js — the pure model behind the Calendar views (console3 wave C2).
+ *
+ *   rangeFor(view, date)                      → { view, date, start, end, days } ; end is the last day, inclusive
+ *   bucketEvents(events, view, date)          → { range, unit, cells: [{ key, start, end, events[] }] }
+ *   ganttRows(initiatives, view, date, opts)  → rows: planned against forecast against promised, with a status
+ *   strategyLens(initiatives, krs, today)     → { north_star, deviations, pivot, reason }
+ *
+ * No I/O and no clock: every date comes in as 'YYYY-MM-DD'. Weeks start on Monday; a quarter is a calendar quarter.
+ * Nothing here invents a number: a plan, a forecast or a KR metric that was not supplied is reported as missing.
+ *
+ * SLIP RULE. slip_days = forecast end minus planned end. Tolerance = the initiative's slip_tolerance_days, else 10 percent
+ * of the planned duration (rounded, at least 1 day when a duration is known). slip <= 0 is on time; 0 < slip < tolerance is
+ * on time; slip = tolerance up to twice tolerance is at risk; slip beyond twice tolerance is delayed. An initiative past
+ * its promised date with no end (not done, no actual end) is overdue, which wins over the slip statuses.
+ *
+ * DEVIATION RULE. A KR's expected value is a straight line from baseline (at start) to target (at date). EARLY_WARNING is
+ * the shortfall, as a share of the baseline-to-target span, at which a KR is flagged: expected minus actual >= 10 percent.
+ * PIVOT RULE. A KR signals a pivot when it carries at least PIVOT_CHECKS (3) dated checks, each behind the line by the
+ * early-warning share, and the latest shortfall is no smaller than the first (it is not closing). */
+
+const V = require('./derived/derive.js');
+
+/* BACKED BY THE PM'S SAMPLE: the slip tolerance (derived/derive.js). REPO-WRITTEN, the sample has no equivalent: the Day to Year
+ * ranges and buckets, the on time / at risk / delayed bands, and the strategy lens (deviation and pivot rules). */
+const DAY = 864e5;
+const EARLY_WARNING = 0.10;
+const PIVOT_CHECKS = 3;
+const VIEWS = ['day', 'week', 'month', 'quarter', 'year'];
+
+const pad = (n) => String(n).padStart(2, '0');
+const isDate = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}/.test(s) && !Number.isNaN(Date.parse(s.slice(0, 10) + 'T00:00:00Z'));
+const ms = (s) => Date.parse(String(s).slice(0, 10) + 'T00:00:00Z');
+const fmt = (t) => new Date(t).toISOString().slice(0, 10);
+const addDays = (s, n) => fmt(ms(s) + n * DAY);
+const diffDays = (a, b) => Math.round((ms(a) - ms(b)) / DAY);
+const ymd = (y, m, d) => `${y}-${pad(m)}-${pad(d)}`;
+const lastOfMonth = (y, m) => fmt(Date.UTC(y, m, 0));   // m is 1-based; day 0 of the next month
+
+function rangeFor(view, date) {
+  if (!VIEWS.includes(view)) throw new Error('unknown view: ' + view);
+  if (!isDate(date)) throw new Error('date must be YYYY-MM-DD');
+  const d = date.slice(0, 10);
+  const y = Number(d.slice(0, 4)); const m = Number(d.slice(5, 7));
+  let start; let end;
+  if (view === 'day') { start = d; end = d; }
+  else if (view === 'week') { const dow = (new Date(ms(d)).getUTCDay() + 6) % 7; start = addDays(d, -dow); end = addDays(start, 6); }
+  else if (view === 'month') { start = ymd(y, m, 1); end = lastOfMonth(y, m); }
+  else if (view === 'quarter') { const q = Math.floor((m - 1) / 3); start = ymd(y, q * 3 + 1, 1); end = lastOfMonth(y, q * 3 + 3); }
+  else { start = ymd(y, 1, 1); end = ymd(y, 12, 31); }
+  return { view, date: d, start, end, days: diffDays(end, start) + 1 };
+}
+
+/* the cell unit of a view: a day view and a week view hold days, a month holds days, a quarter holds weeks, a year months */
+const UNIT = { day: 'day', week: 'day', month: 'day', quarter: 'week', year: 'month' };
+
+function cellsFor(range, unit) {
+  const cells = [];
+  if (unit === 'day') for (let d = range.start; d <= range.end; d = addDays(d, 1)) cells.push({ key: d, start: d, end: d });
+  else if (unit === 'week') {
+    for (let s = rangeFor('week', range.start).start; s <= range.end; s = addDays(s, 7)) cells.push({ key: s, start: s, end: addDays(s, 6) });
+  } else {
+    for (let mo = 1; mo <= 12; mo++) {
+      const y = Number(range.start.slice(0, 4));
+      const s = ymd(y, mo, 1); const e = lastOfMonth(y, mo);
+      if (e >= range.start && s <= range.end) cells.push({ key: s.slice(0, 7), start: s, end: e });
+    }
+  }
+  return cells.map((c) => ({ ...c, events: [] }));
+}
+
+/* An event lands in every cell its span touches: an all-day event (a date with no time) in its day, a multi-day event in
+ * each day it covers. Events with no usable `at` are dropped; events outside the range are not placed. */
+function bucketEvents(events, view, date) {
+  const range = rangeFor(view, date);
+  const unit = UNIT[view];
+  const cells = cellsFor(range, unit);
+  for (const e of events || []) {
+    if (!e || !isDate(e.at)) continue;
+    const a = String(e.at).slice(0, 10);
+    let b = e.end && isDate(e.end) ? String(e.end).slice(0, 10) : a;
+    // an end at exactly 00:00 of a later day is exclusive (the usual all-day convention), so it does not spill into that day
+    if (b > a && /T00:00(:00)?/.test(String(e.end)) ) b = addDays(b, -1);
+    if (b < a) b = a;
+    for (const c of cells) if (a <= c.end && b >= c.start) c.events.push(e);
+  }
+  return { range, unit, cells };
+}
+
+/* The slip tolerance is the sample's (derived/derive.js tolerance, from facts.js): the initiative's own slip_tolerance_days,
+ * else 10 percent of the planned duration, at least 1 day. Called with the planned duration as a start and a promise that far
+ * apart. Unlike the older code, an explicit 0 falls back to the default (the sample reads the field with ||). */
+function toleranceOf(i, plannedDays) {
+  const explicit = i.slip_tolerance_days != null && i.slip_tolerance_days !== '' && Number.isFinite(Number(i.slip_tolerance_days));
+  if (!explicit && plannedDays == null) return null;
+  return V.tolerance(explicit ? i : {}, '1970-01-01', addDays('1970-01-01', plannedDays || 0));
+}
+
+function ganttRows(initiatives, view, date, opts = {}) {
+  const range = rangeFor(view, date);
+  const today = isDate(opts.today) ? opts.today.slice(0, 10) : range.date;
+  const rows = [];
+  for (const i of initiatives || []) {
+    if (!i || !i.id) continue;
+    const promised = isDate(i.promised) ? i.promised.slice(0, 10) : null;
+    let pStart = i.planned && isDate(i.planned.start) ? i.planned.start.slice(0, 10) : (isDate(i.planned_start) ? i.planned_start.slice(0, 10) : null);
+    let pEnd = i.planned && isDate(i.planned.end) ? i.planned.end.slice(0, 10) : (isDate(i.planned_end) ? i.planned_end.slice(0, 10) : promised);
+    const pd = i.plannedDays != null ? Number(i.plannedDays) : (i.planned_days != null ? Number(i.planned_days) : null);
+    if (!pStart && pEnd && Number.isFinite(pd)) pStart = addDays(pEnd, -pd);
+    const fStart = i.forecast && isDate(i.forecast.start) ? i.forecast.start.slice(0, 10) : null;
+    const fEnd = i.forecast && typeof i.forecast === 'object' ? (isDate(i.forecast.end) ? i.forecast.end.slice(0, 10) : null) : (isDate(i.forecast) ? String(i.forecast).slice(0, 10) : null);
+    const duration = pStart && pEnd ? Math.max(0, diffDays(pEnd, pStart)) : (Number.isFinite(pd) ? pd : null);
+    const tol = toleranceOf(i, duration);
+    const slip = pEnd && fEnd ? diffDays(fEnd, pEnd) : 0;
+    const ended = !!(i.done || i.actual_end);
+    let status;
+    if (promised && !ended && promised < today) status = 'overdue';
+    else if (!pEnd || !fEnd) status = 'no plan';
+    else if (slip <= 0) status = 'on time';
+    else if (tol == null || slip < tol) status = 'on time';
+    else if (slip <= 2 * tol) status = 'at risk';
+    else status = 'delayed';
+    // keep a row when its bar touches the range, or when it has no dates at all (so a missing plan is shown, not dropped)
+    const lo = pStart || fStart || pEnd || fEnd || promised; const hi = [pEnd, fEnd, promised].filter(Boolean).sort().pop() || lo;
+    if (lo && !(lo <= range.end && hi >= range.start)) continue;
+    rows.push({
+      id: i.id, title: i.title || i.id,
+      planned: pEnd || pStart ? { start: pStart, end: pEnd } : null,
+      forecast: fEnd || fStart ? { start: fStart || pStart, end: fEnd } : null,
+      promised, status, slip_days: slip, tolerance_days: tol,
+    });
+  }
+  return rows;
+}
+
+function dayOf(x) { return isDate(x) ? String(x).slice(0, 10) : null; }
+
+/* expected value on the straight line from baseline at start to target at date, clamped to the period */
+function expectedAt(kr, at) {
+  const start = dayOf(kr.start) || rangeFor('quarter', kr.date).start;
+  const span = diffDays(kr.date, start);
+  const f = span <= 0 ? 1 : Math.min(1, Math.max(0, diffDays(at, start) / span));
+  return kr.baseline + (kr.target - kr.baseline) * f;
+}
+
+function strategyLens(initiatives, krs, today) {
+  const inis = (initiatives || []).filter(Boolean);
+  const list = Array.isArray(krs) ? krs.filter(Boolean) : [];
+  const out = {
+    north_star: { progress: null, scored: 0, total: list.length, initiatives: { total: inis.length, done: inis.filter((i) => i.done).length } },
+    deviations: [], unscored: [], pivot: { signal: false, reason: '' }, reason: '',
+  };
+  if (!list.length) {
+    out.reason = 'No key results were supplied, so nothing is scored.';
+    out.pivot.reason = out.reason;
+    return out;
+  }
+  const num = (v) => v !== null && v !== undefined && v !== '' && Number.isFinite(Number(v));
+  const progresses = []; const pivotKrs = [];
+  for (const kr of list) {
+    const name = kr.id || kr.title || kr.kr || 'kr';
+    const ok = kr.metric && num(kr.baseline) && num(kr.target) && num(kr.actual) && isDate(kr.date) && Number(kr.target) !== Number(kr.baseline);
+    if (!ok) { out.unscored.push({ kr: name, status: 'no metric' }); continue; }
+    const k = { ...kr, baseline: Number(kr.baseline), target: Number(kr.target), actual: Number(kr.actual) };
+    const at = isDate(today) ? today.slice(0, 10) : k.date;
+    const span = k.target - k.baseline;
+    const expected = expectedAt(k, at);
+    const shortfall = (expected - k.actual) / Math.abs(span) * Math.sign(span);   // positive when behind the line
+    progresses.push(Math.min(1, Math.max(0, (k.actual - k.baseline) / span)));
+    out.deviations.push({ kr: name, metric: k.metric, expected: +expected.toFixed(4), actual: k.actual, shortfall: +shortfall.toFixed(4), early_warning: shortfall >= EARLY_WARNING });
+    const checks = (Array.isArray(kr.checks) ? kr.checks : []).filter((c) => c && isDate(c.date) && num(c.actual)).sort((a, b) => ms(a.date) - ms(b.date));
+    if (checks.length >= PIVOT_CHECKS) {
+      const sf = checks.map((c) => (expectedAt(k, c.date.slice(0, 10)) - Number(c.actual)) / Math.abs(span) * Math.sign(span));
+      if (sf.every((v) => v >= EARLY_WARNING) && sf[sf.length - 1] >= sf[0]) pivotKrs.push(name);
+    }
+  }
+  out.north_star.scored = progresses.length;
+  out.north_star.progress = progresses.length ? +(progresses.reduce((a, b) => a + b, 0) / progresses.length).toFixed(4) : null;
+  if (!progresses.length) out.reason = 'Every key result is missing a metric, so nothing is scored.';
+  if (pivotKrs.length) out.pivot = { signal: true, reason: `${pivotKrs.join(', ')} behind the line at ${PIVOT_CHECKS} or more checks and not closing.` };
+  else out.pivot.reason = progresses.length ? 'No key result has been behind the line at three checks in a row.' : out.reason;
+  return out;
+}
+
+module.exports = { VIEWS, EARLY_WARNING, PIVOT_CHECKS, rangeFor, bucketEvents, ganttRows, strategyLens, cellsFor };

package/workspace/lib/engine/card-state.js

@@ -0,0 +1,92 @@
+'use strict';
+/* card-state.js — the run card's logic, a thin adapter over scripts/reply-contract/reply-contract.js (the PM's sample).
+ * The state is the contract's fold phase, never re-derived here; the moves are the contract's nextMoves; a correction
+ * is the contract's applyMove record. What is local: card shaping, swipes, fallbacks, the coverage share.
+ *   cardFor(runLines, { run, ctx, extra, ended, error }) · nextMoves(result) · correctionEvent(kind, reason, run, now)
+ *   swipeAction(direction, card) · fallbackFor(kind) · coverageShare(runs) · permissionCard · questionCard
+ */
+const C = require('./reply-contract/reply-contract');
+const { foldReplies } = require('./replies');
+
+const REJECT_REASONS = C.REJECT.slice();
+const REVISE_OPTIONS = Object.keys(C.REVISE);
+const COVERAGE_LIMIT = 0.1;
+const DENY_MESSAGE = 'waiting for the PM';
+const PM_PRESS = { by: 'pm', via: 'ui' };
+
+const TITLES = {
+  queued: 'Starting', not_started: 'Not started', working: 'Working', asking: 'Needs your answer', permission: 'Needs your permission',
+  attention: 'Needs the terminal', paused: 'Paused', quiet: 'Quiet', degraded: 'Plain text only', failed: 'Failed', done: 'Result',
+};
+
+// The card for one run. `extra` = lines from other files (the PM's answers); `ended`/`error` close the run from outside.
+function cardFor(runLines = [], { run, ctx, extra = [], ended = false, error = false } = {}) {
+  let lines = runLines.concat(extra);
+  const r = run || require('./replies').runOf(lines);
+  if ((ended || error) && !lines.some((l) => l && l.kind === 'end')) lines = lines.concat([{ kind: 'end', run: r.id, session: r.session, exit: error ? 1 : 0 }]);
+  const vm = foldReplies(lines, r, ctx);
+  const card = {
+    state: vm.phase, title: TITLES[vm.phase] || vm.phase, steps: vm.steps, ask: vm.ask, permission: vm.permission, attention: vm.attention,
+    failure: vm.failure, recover: vm.recover, problems: vm.problems, unlabelled: vm.unlabelled, fallbackText: vm.fallbackText,
+    result: vm.result, claims: (vm.result && vm.result.claims) || [], blocked: vm.failure && vm.failure.code === 'blocked' ? vm.failure.why : null,
+    nextMoves: [], fallback: null,
+  };
+  if (vm.result) { card.nextMoves = nextMoves(vm.result); card.revise = REVISE_OPTIONS; card.reject = REJECT_REASONS; }
+  if (vm.recover.includes('open_session')) card.fallback = fallbackFor(vm.phase === 'degraded' ? 'plain' : 'terminal');
+  return card;
+}
+
+// The moves under a result: { verb, by, label, prompt? }, the contract's own.
+function nextMoves(result, opts) {
+  return C.nextMoves(result || {}, opts).moves;
+}
+
+// An append-only correction event. Every Reject and Revise is one; the caller appends it with appendOutbox.
+function correctionEvent(kind, reason, run, now = new Date()) {
+  if (kind !== 'reject' && kind !== 'revise') throw new Error('a correction is a reject or a revise');
+  const m = C.applyMove(kind, reason, { id: run || null }, PM_PRESS);
+  if (m.error) throw new Error(m.error);
+  return { type: 'correction', kind, reason, run: run || null, counted: true, at: new Date(now).toISOString(), record: m.record };
+}
+
+// Right = the card's primary action; left = open the reply tray. Neither reaches the outbox.
+function swipeAction(direction, card = {}) {
+  if (direction === 'left') return { action: 'open-reply-tray', outward: false };
+  if (direction === 'right') return { action: card.state === 'done' && (card.nextMoves || []).some((m) => m.verb === 'accept') ? 'accept' : 'none', outward: false };
+  return { action: 'none', outward: false };
+}
+
+function fallbackFor(kind) {
+  if (kind === 'plain' || kind === 'tier2' || kind === 2) {
+    return { tier: 2, shown: 'plain text', checked: false, canBackClaim: false, note: 'The agent did not use the format, so nothing here is checked.' };
+  }
+  return { tier: 3, shown: 'terminal only', checked: false, canBackClaim: false, action: 'Open the session' };
+}
+
+// runs: [{ tier: 1|2|3 }]. The PRD: above about 10% the contract is wrong. The number is returned, never hidden.
+function coverageShare(runs = []) {
+  const n = runs.length;
+  const low = runs.filter((r) => r && (r.tier === 2 || r.tier === 3)).length;
+  const share = n ? low / n : 0;
+  return { share, low, runs: n, overLimit: share > COVERAGE_LIMIT, limit: COVERAGE_LIMIT };
+}
+
+function permissionCard(request = {}) {
+  return {
+    kind: 'permission', command: request.command || '', cwd: request.cwd || '', why: request.why || '',
+    options: ['allow once', 'allow always for this branch', 'deny'],
+    onDeny: { behavior: 'deny', message: DENY_MESSAGE }, denyMessage: DENY_MESSAGE,
+  };
+}
+
+// The CLI question tool's input, through the contract's askFromTool (up to 4 questions, 6 options each).
+function questionCard(input = {}) {
+  const qs = Array.isArray(input) ? input : input.questions || [];
+  const r = C.askFromTool({ questions: qs.map((q) => ({ ...q, options: (q.options || []).map((o) => (typeof o === 'string' ? { label: o } : o)) })) });
+  return { kind: 'question', questions: r.asks || [], truncated: qs.length > 4, error: r.error || null, onDeny: { behavior: 'deny', message: DENY_MESSAGE } };
+}
+
+module.exports = {
+  REJECT_REASONS, REVISE_OPTIONS, COVERAGE_LIMIT, DENY_MESSAGE, TITLES,
+  cardFor, nextMoves, correctionEvent, swipeAction, fallbackFor, coverageShare, permissionCard, questionCard,
+};

package/workspace/lib/engine/derived/derive.js

@@ -0,0 +1,92 @@
+'use strict';
+/* derive.js — the PM's derived-view expressions from sample/reader.js and sample/facts.js, lifted into pure functions.
+ * reader.js is a script that runs on load against one portfolio root; the repo modules need the same expressions over data
+ * they are given. Every expression here is copied from reader.js / facts.js (the section number is named at each one) and
+ * only parameterised. derived.test.js runs both on the generated sample portfolio and asserts they agree, so the two
+ * copies cannot drift. When the sample changes, change reader.js/facts.js first, then this file.
+ */
+const P = require('./plan');
+const { fold, plan, day, fmt, D } = P;
+const days = (a, b) => Math.round((a - b) / D);
+
+/* reader.js section 1: one row per check (snap): forecast date, slip against the promise, scope points. */
+const pts = (s) => Object.values(s).reduce((a, t) => a + t.pts, 0);
+function timeline(events, start, promised) {
+  const snaps = [...new Set(events.map((e) => e.snap))].sort();
+  return snaps.map((c) => { const s = fold(events, c), p = plan(s, start); return { check: c, forecast: fmt(p.forecast), slip: days(p.forecast, day(promised)), points: pts(s) }; });
+}
+
+/* facts.js: the slip tolerance is the initiative's own field, else 10 percent of the planned duration (at least 1 day). */
+const tolerance = (init, start, promised) => +init.slip_tolerance_days || Math.max(1, Math.round(0.1 * Math.round((day(promised) - day(start)) / D)));
+
+/* facts.js: critical path = the tickets with slack 0 against the forecast. */
+function critical(state, fc) {
+  const succ = {};
+  Object.entries(state).forEach(([k, t]) => t.deps.forEach((d) => (succ[d] = succ[d] || []).push(k)));
+  const tail = (k) => Math.max(0, ...(succ[k] || []).map((s) => state[s].dur + tail(s)));
+  return new Set(Object.keys(state).filter((k) => fc.end[k] + tail(k) * D === fc.forecast));
+}
+
+/* facts.js ablate(): remove one event, recompute; the difference is what that event cost. */
+function attribution(events, start, firstSnap) {
+  const fc = plan(fold(events), start);
+  const out = [];
+  for (const e of events) {
+    if (e.snap === firstSnap) continue;
+    try { out.push({ ev: e, days: Math.round((fc.forecast - plan(fold(events.filter((x) => x !== e)), start).forecast) / D) }); } catch { out.push({ ev: e, days: null }); }
+  }
+  return out;
+}
+
+/* reader.js section 3: document graph edges. docs: { id: { type, rev, sources: [{id, rev}], ... } }; findings: open findings. */
+const edgeState = (docs, src, seen) => { const u = docs[src]; if (!u) return 'missing'; if (u.rev <= seen) return 'in sync'; return ['Decision', 'Benchmark'].includes(u.type) ? 'conflict' : 'out of sync'; };
+function docGraph(docs, findings) {
+  const edges = [];
+  for (const [id, d] of Object.entries(docs)) for (const s of d.sources || []) edges.push({ from: s.id, to: id, state: edgeState(docs, s.id, s.rev) });
+  for (const f of (findings || []).filter((x) => x.status === 'open')) {
+    const e = edges.find((x) => x.from === f.vs && x.to === f.doc);
+    if (e) { e.state = 'conflict'; e.reason = 'finding'; } else edges.push({ from: f.vs, to: f.doc, state: 'conflict', reason: 'finding: ' + f.quote });
+  }
+  return edges;
+}
+
+/* reader.js section 4: the six health checks for one document. need: { <type>: [required headings] } (doc-types.json
+ * `required`); readers: doc-readers records { doc, who, rev }; now: 'YYYY-MM-DD'. Doc bodies are in docs[id]._body. */
+function docHealth(id, docs, edges, readers, need, now) {
+  const d = docs[id], my = edges.filter((e) => e.to === id), kind = (i) => (docs[i] || {}).type, chk = {};
+  chk.fresh = !d.stale_after || d.stale_after >= now;
+  chk.decisions = !my.some((e) => kind(e.from) === 'Decision' && e.state !== 'in sync');
+  chk.data = !my.some((e) => kind(e.from) === 'Benchmark' && e.state !== 'in sync') && chk.fresh;
+  chk.complete = (need[d.type] || []).every((h) => (d._body || '').includes('## ' + h));
+  const reachKR = (i, seen = new Set()) => { if (seen.has(i) || !docs[i]) return false; seen.add(i); if (docs[i].type === 'KeyResult') return true; return (docs[i].sources || []).some((x) => reachKR(x.id, seen)); };
+  const citedBy = Object.entries(docs).filter(([, x]) => (x.sources || []).some((y) => y.id === id)).map(([k]) => k);
+  chk.traced = (['Research', 'Benchmark'].includes(d.type) ? citedBy.some((k) => reachKR(k)) : reachKR(id)) && (d.type !== 'PRD' || (d.tickets || []).length > 0);
+  const lastR = {}; (readers || []).filter((r) => r.doc === id).forEach((r) => (lastR[r.who] = r.rev));
+  chk.readers = Object.values(lastR).every((r) => r >= d.rev);
+  return chk;
+}
+
+/* reader.js section 7: what each person was told against what is true now. messages: sent.jsonl records;
+ * pl: plan(state,start) of the current state. Subjects: 'ship-date' and 'ticket:<id>'. */
+const truthOf = (subj, pl) => (subj === 'ship-date' ? fmt(pl.forecast) : subj.startsWith('ticket:') && pl.end[subj.slice(7)] !== undefined ? fmt(pl.end[subj.slice(7)]) : null);
+function heldVsTrue(messages, pl) {
+  const rows = [];
+  for (const m of messages) for (const c of m.claims) {
+    const t = truthOf(c.subject, pl), gap = t == null ? null : days(day(t), day(c.value));
+    rows.push({ to: m.to, subject: c.subject, told: c.value, true: t, gap, state: gap === null ? 'unknown' : gap ? gap + 'd apart' : 'in sync' });
+  }
+  return rows;
+}
+
+/* gen.js shared/trust/claim-rules.json: the evidence labels and the per-destination strictness trust.checkReport reads. */
+const CLAIM_RULES = {
+  basis: {
+    fact: { needs: ['source'] }, cited: { needs: ['source'] }, reported: { needs: ['by', 'at'] }, estimate: { needs: ['method', 'range'] },
+    assumption: { needs: ['owner', 'falsifier', 'review_by'] }, judgement: { needs: ['by'] } },
+  destinations: {
+    leadership: { allow: ['fact', 'cited', 'reported', 'estimate', 'assumption', 'judgement'], unlabelled: 'block', incomplete: 'block', stale: 'block', overdue_assumption: 'block', label_visible: true },
+    customer: { allow: ['fact', 'cited'], unlabelled: 'block', incomplete: 'block', stale: 'block', overdue_assumption: 'block', label_visible: false },
+    'internal-draft': { allow: ['fact', 'cited', 'reported', 'estimate', 'assumption', 'judgement'], unlabelled: 'warn', incomplete: 'warn', stale: 'warn', overdue_assumption: 'warn', label_visible: true } },
+};
+
+module.exports = { timeline, tolerance, critical, attribution, docGraph, docHealth, truthOf, heldVsTrue, CLAIM_RULES, pts };

package/workspace/lib/engine/derived/plan.js

@@ -0,0 +1,3 @@
+'use strict';
+// Re-export: the canonical copy is scripts/trust/plan.js (the PM's sample, ported once).
+module.exports = require('../trust/plan.js');

package/workspace/lib/engine/derived/trust.js

@@ -0,0 +1,3 @@
+'use strict';
+// Re-export: the canonical copy is scripts/trust/trust.js (the PM's sample, ported once).
+module.exports = require('../trust/trust.js');