create-pmos 0.133.0 → 0.135.0

package/workspace/lib/engine/report-families.js

@@ -0,0 +1,175 @@
+'use strict';
+// console3 wave B4: the four report families, their section builders and the claims check. Pure: no I/O, no send.
+// Evidence labels (HANDOFF section 11): fact | cited | reported | estimate | assumption | judgement.
+const { whoHoldsWhat } = require('./truth-table');
+const TR = require('./derived/trust.js');
+const { CLAIM_RULES } = require('./derived/derive.js');
+
+// BACKED BY THE PM'S SAMPLE: the claims check is derived/trust.js checkReport() under the sample's rules (derive.CLAIM_RULES,
+// gen.js claim-rules.json): label, required fields, destination strictness, untrusted import, source exists, source current,
+// overdue assumption, and the omitted-tripped-signal rule. This file only maps a claim to the sample's shape.
+// REPO-WRITTEN, no sample equivalent: the four families and their variants, the section builders, and the send summary wording.
+
+const LABELS = ['fact', 'cited', 'reported', 'estimate', 'assumption', 'judgement'];
+const REQUIRED = Object.fromEntries(Object.entries(CLAIM_RULES.basis).map(([k, v]) => [k, v.needs.slice()]));   // CHANGED to the sample: assumption needs review_by, judgement needs by
+const present = (v) => v !== undefined && v !== null && String(v).trim() !== '';
+
+// gate: 'block' = an unlabelled or incomplete claim blocks sending; 'strict' = block, and only fact and cited are allowed;
+// 'warn' = internal draft, the check warns and never blocks.
+const FAMILIES = [
+  { id: 'project', name: 'Project', intent: 'Decide and unblock', purpose: 'Let the audience decide something or remove a blocker.',
+    cadence: 'on demand, at each decision point',
+    variants: [
+      { id: 'leadership', name: 'Leadership', audience: 'Leadership', gate: 'block' },
+      { id: 'engineering', name: 'Engineering', audience: 'Engineering', gate: 'warn' },
+      { id: 'customer-success', name: 'Customer success', audience: 'Customer success', gate: 'strict', external: true },
+    ],
+    sections: ['headline', 'progress', 'risks', 'decisions_needed', 'blockers'] },
+  { id: 'product', name: 'Product', intent: 'Align and invest', purpose: 'Align the audience on outcomes and where to invest.',
+    cadence: 'per planning cycle',
+    variants: [
+      { id: 'executives', name: 'Executives', audience: 'Executives', gate: 'block' },
+      { id: 'product-council', name: 'Product council', audience: 'Product council', gate: 'block' },
+      { id: 'team', name: 'Team', audience: 'Team', gate: 'warn' },
+    ],
+    sections: ['outcomes', 'bets', 'tradeoffs', 'investment_asks'] },
+  { id: 'communications', name: 'Communications', intent: 'Inform, enable, ask', purpose: 'Tell people what they need, give them what they need to act, and ask.',
+    cadence: 'on demand',
+    variants: [
+      { id: 'message-queue', name: 'Message queue', audience: 'Per message', gate: 'warn' },
+      { id: 'who-holds-what', name: 'Who holds what', audience: 'PM', gate: 'warn' },
+      { id: 'external', name: 'External message', audience: 'External', gate: 'strict', external: true, needs_approval: true },
+    ],
+    sections: ['message_queue', 'who_holds_what', 'asks'], needs_approval_external: true },
+  { id: 'periodic', name: 'Periodic', intent: 'Rhythm', purpose: 'Keep a steady rhythm; one template, with the change since last time.',
+    cadence: 'weekly, monthly, quarterly, per retro',
+    variants: [
+      { id: 'weekly-digest', name: 'Weekly digest', audience: 'Team', gate: 'warn', cadence: 'weekly' },
+      { id: 'monthly-review', name: 'Monthly review', audience: 'Leadership', gate: 'block', cadence: 'monthly' },
+      { id: 'quarterly-board-update', name: 'Quarterly board update', audience: 'Board', gate: 'block', cadence: 'quarterly' },
+      { id: 'retro', name: 'Retro', audience: 'Team', gate: 'warn', cadence: 'per retro' },
+    ],
+    sections: ['since_last_time', 'highlights', 'metrics', 'next'], template: 'same template; change since last time' },
+];
+
+const familyOf = (id) => FAMILIES.find((f) => f.id === id) || null;
+const variantOf = (f, id) => (f && f.variants.find((v) => v.id === id)) || null;
+
+/* ── section builders: pure, over a facts object the caller supplies ─────────────────────────────────────────────── */
+// facts[<section>] is a list of items { id?, text, label, source, ...label fields, from_import?, stale? }.
+// A builder copies what is given. It never adds a claim and never fills in a label.
+const CLAIM_KEYS = ['id', 'text', 'label', 'source', 'by', 'at', 'method', 'range', 'owner', 'falsifier', 'review_date', 'author', 'from_import', 'stale'];
+const pick = (it) => { const c = {}; for (const k of CLAIM_KEYS) if (it[k] !== undefined) c[k] = it[k]; if (c.label === undefined) c.label = null; if (c.source === undefined) c.source = null; return c; };
+const fromList = (key, title) => (facts = {}) => ({ title, claims: (Array.isArray(facts[key]) ? facts[key] : []).filter((x) => x && typeof x === 'object' && x.text).map(pick) });
+
+// "Since last time": a claim for each id whose value differs between facts.previous and facts.current (both { id: { text, value, source } }).
+function sinceLastTime(facts = {}) {
+  const prev = facts.previous || {}, cur = facts.current || {};
+  const claims = [];
+  for (const id of Object.keys(cur)) {
+    const c = cur[id] || {};
+    if (JSON.stringify(prev[id] && prev[id].value) === JSON.stringify(c.value)) continue;
+    const was = prev[id] ? ` (was ${JSON.stringify(prev[id].value)})` : ' (new)';
+    claims.push({ ...pick({ ...c, id, text: `${c.text || id}: ${JSON.stringify(c.value)}${was}` }), label: c.label === undefined ? null : c.label });
+  }
+  return { title: 'Since last time', claims };
+}
+
+function whoHoldsWhatSection(facts = {}) {
+  const rows = whoHoldsWhat(facts.messages || [], facts.truth || {});
+  const claims = [];
+  for (const p of rows) for (const c of p.claims) {
+    claims.push({ id: `${p.person}:${c.id}`, text: `${p.person} holds "${c.text || c.id}": ${c.state}`, label: 'fact', source: 'truth-table:' + c.id, stale: c.state === 'stale', contradicted: c.state === 'contradicted' });
+  }
+  return { title: 'Who holds what', claims };
+}
+
+const BUILDERS = {
+  headline: fromList('headline', 'Headline'), progress: fromList('progress', 'Progress'), risks: fromList('risks', 'Risks'),
+  decisions_needed: fromList('decisions_needed', 'Decisions needed'), blockers: fromList('blockers', 'Blockers'),
+  outcomes: fromList('outcomes', 'Outcomes'), bets: fromList('bets', 'Bets'), tradeoffs: fromList('tradeoffs', 'Trade-offs'),
+  investment_asks: fromList('investment_asks', 'Investment asks'),
+  message_queue: fromList('message_queue', 'Message queue'), who_holds_what: whoHoldsWhatSection, asks: fromList('asks', 'Asks'),
+  since_last_time: sinceLastTime, highlights: fromList('highlights', 'Highlights'), metrics: fromList('metrics', 'Metrics'), next: fromList('next', 'Next'),
+};
+
+function buildFamily(familyId, facts = {}) {
+  const f = familyOf(familyId);
+  if (!f) throw new Error('unknown family: ' + familyId);
+  return f.sections.map((name) => ({ name, ...BUILDERS[name](facts) }));
+}
+
+/* ── the claims check ────────────────────────────────────────────────────────────────────────────────────────────── */
+// gate 'block' = leadership rules, 'strict' = customer rules, 'warn' = internal-draft rules.
+const DEST = { block: 'leadership', strict: 'customer', warn: 'internal-draft' };
+
+// A repo claim in the sample's shape. The older field names are still read: review_date for review_by, author for by.
+// A stale claim cites its source at revision 1 while the source is at revision 2, which is how the sample marks it stale.
+function toSample(c, opts) {
+  const src = c && present(c.source) ? String(c.source) : '';
+  const stale = !!(c && (c.stale || (opts.staleKeys || []).includes(src)));
+  const absent = (opts.absentKeys || []).includes(src) || (Array.isArray(opts.knownKeys) && !opts.knownKeys.includes(src));
+  const sc = c ? { id: c.id, basis: c.label || undefined, claim: c.text, by: c.by || c.author, at: c.at, method: c.method, range: c.range,
+    owner: c.owner, falsifier: c.falsifier, review_by: c.review_by || c.review_date, covers: c.covers } : {};
+  sc.source = c && c.from_import ? 'import:' + src : (stale && src && !absent ? src + '@1' : src);
+  const docs = src && !absent ? { [src]: { rev: stale ? 2 : 1 } } : (src ? {} : { '': { rev: 0 } });
+  return { sc, docs, stale, src, absent };
+}
+const ctxOf = (docs, opts) => ({ snaps: [], last: '', docs, now: opts.now || '0000-00-00', tripped: opts.tripped || [] });
+
+// opts: { gate, knownKeys?, absentKeys?, staleKeys?, now? }
+function checkClaim(c, opts = {}) {
+  const gate = opts.gate || 'warn';
+  const m = toSample(c, opts);
+  const row = TR.checkReport({ sections: [m.sc] }, CLAIM_RULES, ctxOf(m.docs, opts), DEST[gate] || DEST.warn).rows[0];
+  const why = row.verdict === 'ok' ? '' : row.why;
+  const problems = !why ? [] : /^missing /.test(why) ? why.slice(8).split(', ').map((k) => 'missing ' + k) : [why];
+  const fabricated = row.verdict === 'block' && /does not exist|no such check/.test(why);
+  if (fabricated && m.src && !/not found/.test(why)) problems.push('source not found: ' + m.src);
+  return { ok: row.verdict === 'ok', verdict: row.verdict, problems, fabricated, stale: m.stale && /is now rev/.test(why) };
+}
+
+function claimsCheck(sections = [], opts = {}) {
+  return (sections || []).map((s) => {
+    const out = { name: s.name || null, title: s.title || null, traced: 0, stale_source: 0, needs_input: 0, fabricated: 0, problems: [] };
+    (s.claims || []).forEach((c, i) => {
+      const r = checkClaim(c, opts);
+      if (r.fabricated) out.fabricated++;
+      if (r.ok) out.traced++;
+      else if (r.stale && r.verdict === 'warn') out.stale_source++;      // an internal draft only warns about a stale source
+      else { out.needs_input++; out.problems.push({ index: i, text: (c && c.text) || null, problems: r.problems }); }
+    });
+    return out;
+  });
+}
+
+// Whether sending is blocked, and why. A fabricated source always blocks. Otherwise the variant's gate decides.
+function sendCheck({ family, variant, sections, knownKeys, absentKeys, staleKeys, tripped, now } = {}) {
+  const f = familyOf(family);
+  if (!f) return { ok: false, error: 'unknown family' };
+  const v = variantOf(f, variant) || f.variants[0];
+  const opts = { gate: v.gate, knownKeys, absentKeys, staleKeys, now };
+  const per = claimsCheck(sections, opts);
+  // the sample's bad-news rule: a leadership or customer report must cover every tripped signal (a claim's `covers` list)
+  let omitted = [];
+  if (Array.isArray(tripped) && tripped.length) {
+    const all = (sections || []).flatMap((s) => (s.claims || []).map((c) => toSample(c, opts)));
+    const rows = TR.checkReport({ sections: all.map((m) => m.sc) }, CLAIM_RULES, ctxOf(Object.assign({}, ...all.map((m) => m.docs)), { ...opts, tripped }), DEST[v.gate]).rows;
+    omitted = rows.filter((r) => r.id === 'omitted').map((r) => r.claim);
+  }
+  const fabricated = per.reduce((n, s) => n + s.fabricated, 0);
+  const needs = per.reduce((n, s) => n + s.needs_input, 0);
+  const reasons = [];
+  if (fabricated) reasons.push(`${fabricated} claim${fabricated > 1 ? 's' : ''} cite a source that does not exist`);
+  if (needs && v.gate !== 'warn') reasons.push(`${needs} claim${needs > 1 ? 's' : ''} need input before this ${v.name} report can be sent`);
+  if (omitted.length) reasons.push(omitted[0]);
+  const warnings = [];
+  if (needs && v.gate === 'warn') warnings.push(`${needs} claim${needs > 1 ? 's' : ''} need input (internal draft: warning only)`);
+  const stale = per.reduce((n, s) => n + s.stale_source, 0);
+  if (stale) warnings.push(`${stale} claim${stale > 1 ? 's' : ''} rest on a stale source`);
+  const approval = !!(v.needs_approval || v.external);
+  if (approval) warnings.push('external message: needs the PM approval before it is sent');
+  return { ok: true, family: f.id, variant: v.id, gate: v.gate, sections: per, blocked: reasons.length > 0, reasons, warnings, needs_approval: approval };
+}
+
+module.exports = { LABELS, REQUIRED, FAMILIES, BUILDERS, familyOf, variantOf, buildFamily, checkClaim, claimsCheck, sendCheck };

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

@@ -0,0 +1,150 @@
+'use strict';
+/*
+ * roadmap-ops.js — the Roadmap's writes (console3 wave E1b; HANDOFF 14e/14f). Pure functions over the folded bets
+ * (scripts/records/index.js, kind 'bets'); nothing here touches a file except apply(), which goes through
+ * scripts/records, which goes through scripts/trust/ledger.js (the PM's writer).
+ *
+ * A bet: { rid, title, horizon: now|next|later, rank, parent_kr, confidence (0..1), off?, off_reason? }.
+ * Every function returns { ok:false, error } or { ok:true, ... }. A result that writes carries `events`:
+ *   { op:'add', fields, why } | { op:'edit', rid, fields, why }, applied by apply(root, events, actor).
+ * A swap is only a PROPOSAL ({ ok:true, proposal:{...} }, no events). The PM confirms it by calling moveBet again with
+ * { confirmSwap: true }; nothing is moved silently.
+ */
+const path = require('path');
+const records = require('./records/index.js');
+
+const LIMIT = 4;                       // bet limit for Now and Next (HANDOFF 14f)
+const COLUMNS = ['now', 'next', 'later'];
+const HEALTH = /^health:[a-z0-9][a-z0-9-]*$/;
+const KR = /^[A-Za-z0-9._-]+:[A-Za-z0-9._-]+:[A-Za-z0-9._-]+$/;   // q3-2026:o1:kr1
+
+const refuse = (error, extra) => ({ ok: false, error, ...(extra || {}) });
+const live = (bets) => (bets || []).filter((b) => b && !b.off);
+const inColumn = (bets, h) => live(bets).filter((b) => b.horizon === h);
+const nextRank = (bets, h) => inColumn(bets, h).reduce((m, b) => Math.max(m, b.rank || 0), 0) + 1;
+const sure = (b) => (typeof b.confidence === 'number' ? b.confidence : 0.5);   // an unrated bet counts as 50 percent
+
+function anchorOk(anchor, krs) {
+  const a = String(anchor || '').trim();
+  if (!a) return false;
+  if (HEALTH.test(a) || KR.test(a)) return true;
+  return (krs || []).some((k) => (k && (k.id || k.rid || k)) === a);
+}
+
+/** addBet(bets, { title, anchor, horizon, confidence?, initiative? }, { krs?, limit? }) */
+function addBet(bets, input, opts = {}) {
+  const i = input || {};
+  const limit = opts.limit || LIMIT;
+  const title = String(i.title || '').trim();
+  if (!title) return refuse('a bet needs a title');
+  const horizon = i.horizon || 'later';
+  if (!COLUMNS.includes(horizon)) return refuse('horizon must be now, next or later');
+  if (!anchorOk(i.anchor, opts.krs)) return refuse('an unanchored bet is refused: anchor it to a KR or to health:<id>', { field: 'anchor' });
+  if ((horizon === 'now' || horizon === 'next') && inColumn(bets, horizon).length >= limit) {
+    return refuse(`${horizon} already holds ${limit} bets; add it to a later column or move one out first`, { full: horizon });
+  }
+  const fields = { title, horizon, rank: nextRank(bets, horizon), parent_kr: String(i.anchor).trim() };
+  if (typeof i.confidence === 'number') fields.confidence = i.confidence;
+  if (i.initiative) fields.initiative = i.initiative;
+  return { ok: true, events: [{ op: 'add', fields, why: 'bet added to ' + horizon }] };
+}
+
+const back = (h) => (h === 'now' ? 'next' : h === 'next' ? 'later' : null);
+
+/**
+ * moveBet(bets, id, toHorizon, capacity = {now:4,next:4}, { confirmSwap, krs })
+ * Any column to any column. When the target is full: without confirmSwap, a proposal naming the LEAST SURE bet of the
+ * target (lowest confidence; ties go to the lowest-ranked) and where it goes (one column back, cascading when that column is
+ * full too); with confirmSwap, the events for the whole chain.
+ */
+function moveBet(bets, id, toHorizon, capacity, opts = {}) {
+  const cap = { now: LIMIT, next: LIMIT, ...(capacity || {}) };
+  const bet = live(bets).find((b) => b.rid === id);
+  if (!bet) return refuse('no such bet on the roadmap: ' + id);
+  if (!COLUMNS.includes(toHorizon)) return refuse('horizon must be now, next or later');
+  if (bet.horizon === toHorizon) return refuse('the bet is already in ' + toHorizon);
+  const promoting = toHorizon !== 'later';
+  if (promoting && !anchorOk(bet.parent_kr, opts.krs)) return refuse('anchor the bet before it goes to ' + toHorizon, { field: 'anchor' });
+
+  // Build the chain of bets that must step back to make room, working on a copy of the columns.
+  const col = {}; for (const h of COLUMNS) col[h] = inColumn(bets, h).filter((b) => b.rid !== id);
+  const chain = [];
+  let h = toHorizon;
+  while (h !== 'later' && col[h].length >= (cap[h] === undefined ? LIMIT : cap[h])) {
+    const victim = [...col[h]].sort((a, b) => sure(a) - sure(b) || (b.rank || 0) - (a.rank || 0))[0];
+    const to = back(h);
+    chain.push({ id: victim.rid, title: victim.title, confidence: victim.confidence == null ? null : victim.confidence, from: h, to });
+    col[h] = col[h].filter((b) => b.rid !== victim.rid);
+    col[to].push(victim);
+    h = to;
+  }
+  if (chain.length && !opts.confirmSwap) {
+    return { ok: true, proposal: { kind: 'swap', move: { id, title: bet.title, from: bet.horizon, to: toHorizon }, send_back: chain, confirm: 'send { confirmSwap: true } to apply; nothing moved yet' } };
+  }
+  // Apply back to front, so each target column has room when its bet arrives.
+  const events = [];
+  const rank = {}; for (const c of COLUMNS) rank[c] = nextRank(bets, c);
+  const place = (rid, to, why) => events.push({ op: 'edit', rid, fields: { horizon: to, rank: rank[to]++ }, why });
+  for (const c of [...chain].reverse()) place(c.id, c.to, `sent back to ${c.to} to make room for ${bet.title}`);
+  place(id, toHorizon, `moved from ${bet.horizon} to ${toHorizon}`);
+  return { ok: true, events, ...(chain.length ? { swapped: chain } : {}) };
+}
+
+const STOP = new Set(['the', 'a', 'an', 'of', 'to', 'for', 'and', 'in', 'on', 'with', 'by', 'is', 'at', 'or', 'new', 'q1', 'q2', 'q3', 'q4']);
+const words = (s) => new Set(String(s || '').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP.has(w)));
+
+/**
+ * anchorSuggestions(bet, krs, healthBudgets) -> [{ anchor, title, kind, overlap:[words], score }], best first.
+ * krs: [{ id, title }], healthBudgets: [{ id, title }] (id 'tech' or 'health:tech'). Word overlap only; empty when none.
+ */
+function anchorSuggestions(bet, krs, healthBudgets) {
+  const mine = words(bet && bet.title);
+  const out = [];
+  const consider = (anchor, title, kind) => {
+    const overlap = [...words(title)].filter((w) => mine.has(w));
+    if (overlap.length) out.push({ anchor, title, kind, overlap, score: overlap.length });
+  };
+  for (const k of krs || []) consider(k.id || k.rid, k.title || k.metric, 'kr');
+  for (const h of healthBudgets || []) consider(String(h.id).startsWith('health:') ? h.id : 'health:' + h.id, h.title || h.id, 'health');
+  return out.filter((s) => s.anchor).sort((a, b) => b.score - a.score || String(a.anchor).localeCompare(String(b.anchor)));
+}
+
+/** takeOff(bets, id, reason): off the roadmap, with a required reason. The record stays (the fold keeps `off`). */
+function takeOff(bets, id, reason) {
+  const bet = live(bets).find((b) => b.rid === id);
+  if (!bet) return refuse('no such bet on the roadmap: ' + id);
+  const why = String(reason || '').trim();
+  if (!why) return refuse('a reason is required to take a bet off the roadmap', { field: 'reason' });
+  return { ok: true, events: [{ op: 'edit', rid: id, fields: { off: true, off_reason: why, off_from: bet.horizon }, why }] };
+}
+
+/**
+ * capacityLine(bets, people, { limit }) -> bet capacity derived from people capacity (never typed).
+ * people: [{ id, points_per_week }]. Each live Now or Next bet is a share of the team's weekly points.
+ */
+function capacityLine(bets, people, opts = {}) {
+  const limit = opts.limit || LIMIT;
+  const total = (people || []).reduce((s, p) => s + (Number(p.points_per_week) || 0), 0);
+  const now = inColumn(bets, 'now').length, next = inColumn(bets, 'next').length;
+  const active = now + next;
+  return {
+    points_per_week: total, people: (people || []).length,
+    now: { used: now, limit, free: Math.max(0, limit - now) },
+    next: { used: next, limit, free: Math.max(0, limit - next) },
+    per_bet: active ? Math.round((total / active) * 10) / 10 : total,
+    over: now > limit || next > limit,
+  };
+}
+
+/** apply(root, events, actor) -> { ok, written } | { ok:false, reasons }. The only writer here; it is scripts/records. */
+function apply(root, events, actor) {
+  const written = [];
+  for (const e of events) {
+    const r = e.op === 'add' ? records.add(root, 'bets', e.fields, actor, e.why) : records.edit(root, 'bets', e.rid, e.fields, actor, e.why);
+    if (!r.ok) return { ok: false, reasons: r.reasons, written };
+    written.push(r.rid);
+  }
+  return { ok: true, written };
+}
+
+module.exports = { LIMIT, COLUMNS, addBet, moveBet, anchorSuggestions, takeOff, capacityLine, apply, anchorOk, live };

package/workspace/lib/engine/sessions-list.js

@@ -0,0 +1,27 @@
+'use strict';
+// Run 9: the sessions list. Pure. Session shape: { id, origin, cardId, startedAt, endedAt }; times are ms or ISO.
+// Groups: onCard (running, tied to a card), startedByMe (running, PM-started), past (ended in the last 7 days, newest first),
+// automatic (every automatic origin, running or ended). The UI hides `automatic` unless AUTOMATIC_HIDDEN_BY_DEFAULT is switched off.
+const PAST_DAYS = 7;
+const AUTOMATIC_HIDDEN_BY_DEFAULT = true;
+const t = (v) => (v == null || v === '' ? NaN : new Date(v).getTime());
+const isAutomaticOrigin = (o) => !!o && o !== 'manual' && o !== 'pm';
+
+function groupSessions(sessions, now = Date.now()) {
+  const n = t(now);
+  const out = { onCard: [], startedByMe: [], past: [], automatic: [], automaticHidden: AUTOMATIC_HIDDEN_BY_DEFAULT };
+  for (const s of Array.isArray(sessions) ? sessions : []) {
+    if (!s) continue;
+    if (isAutomaticOrigin(s.origin)) { out.automatic.push(s); continue; }
+    const ended = !Number.isNaN(t(s.endedAt));
+    if (ended) {
+      if (n - t(s.endedAt) <= PAST_DAYS * 864e5) out.past.push(s);
+    } else if (s.cardId) out.onCard.push(s);
+    else out.startedByMe.push(s);
+  }
+  const when = (s) => t(s.endedAt) || t(s.startedAt) || 0;
+  out.past.sort((a, b) => when(b) - when(a));
+  return out;
+}
+
+module.exports = { PAST_DAYS, AUTOMATIC_HIDDEN_BY_DEFAULT, isAutomaticOrigin, groupSessions };

package/workspace/lib/engine/signal-rules.js

@@ -0,0 +1,95 @@
+'use strict';
+/* signal-rules.js — the Signals page records (console3 wave E2a), from STRUCTURE.md: rules, metric readings, trips.
+ *
+ * Append-only lines in one ledger file (scripts/trust/ledger.js):
+ *   { kind:'signal_rule', rule:{id,metric,op,threshold,severity} }   latest line per id wins
+ *   { kind:'signal_reading', metric, value, at }
+ *   { kind:'signal_trip', rule_id, severity, reading:{metric,value,at}, at }   a rule tripping on a reading
+ *
+ *   evaluateRules(rules, readings)      → trips   pure; each rule is tested against the LATEST reading of its metric
+ *   foldSignals(lines)                  → { rules, readings (latest per metric), trips, open }   open = tripping on the latest reading
+ *   tripsSince(trips, date)             → trips at or after date ('YYYY-MM-DD' or ISO)
+ *   trippedSince(trips, date)           → rule ids, de-duplicated: the `tripped` list scripts/report-families.js sendCheck takes,
+ *                                         so a report that omits one is blocked ('Report omits tripped signal')
+ *   appendRule / appendReading          ledger writers; a reading also appends a trip when it starts tripping a rule */
+const fs = require('fs');
+const path = require('path');
+const L = require('./trust/ledger.js');
+
+const OPS = Object.freeze(['<', '<=', '>', '>=', '==']);
+const SEVERITIES = Object.freeze(['watch', 'act', 'critical']);
+const CMP = { '<': (a, b) => a < b, '<=': (a, b) => a <= b, '>': (a, b) => a > b, '>=': (a, b) => a >= b, '==': (a, b) => a === b };
+
+function validateRule(r) {
+  const e = [];
+  if (!r || typeof r !== 'object') return ['a rule is an object'];
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(String(r.id || ''))) e.push('id must be letters, digits, . _ - (max 64)');
+  if (!String(r.metric || '').trim()) e.push('metric is required');
+  if (!OPS.includes(r.op)) e.push('op must be one of ' + OPS.join(' '));
+  if (typeof r.threshold !== 'number' || !Number.isFinite(r.threshold)) e.push('threshold must be a number');
+  if (!SEVERITIES.includes(r.severity)) e.push('severity must be one of ' + SEVERITIES.join(', '));
+  return e;
+}
+const tripsOn = (rule, value) => typeof value === 'number' && Number.isFinite(value) && CMP[rule.op](value, rule.threshold);
+
+function latestByMetric(readings) {
+  const m = new Map();
+  for (const r of readings || []) {
+    if (!r || r.metric == null) continue;
+    const cur = m.get(r.metric);
+    if (!cur || String(r.at) >= String(cur.at)) m.set(r.metric, r);
+  }
+  return m;
+}
+
+function evaluateRules(rules, readings) {
+  const latest = latestByMetric(readings);
+  const out = [];
+  for (const rule of rules || []) {
+    const rd = latest.get(rule.metric);
+    if (rd && tripsOn(rule, rd.value)) out.push({ rule_id: rule.id, severity: rule.severity, op: rule.op, threshold: rule.threshold, reading: { metric: rd.metric, value: rd.value, at: rd.at }, at: rd.at });
+  }
+  return out;
+}
+
+function foldSignals(lines) {
+  const rules = new Map(); const readings = []; const trips = [];
+  for (const l of lines || []) {
+    if (!l) continue;
+    if (l.kind === 'signal_rule' && l.rule) rules.set(l.rule.id, l.rule);
+    else if (l.kind === 'signal_reading') readings.push({ metric: l.metric, value: l.value, at: l.at });
+    else if (l.kind === 'signal_trip') trips.push({ rule_id: l.rule_id, severity: l.severity, reading: l.reading, at: l.at });
+  }
+  const ruleList = [...rules.values()];
+  return { rules: ruleList, readings: [...latestByMetric(readings).values()], trips, open: evaluateRules(ruleList, readings) };
+}
+
+const tripsSince = (trips, date) => (trips || []).filter((t) => t && String(t.at) >= String(date));
+const trippedSince = (trips, date) => [...new Set(tripsSince(trips, date).map((t) => t.rule_id))];
+
+function appendRule(file, rule, actor, now) {
+  const errs = validateRule(rule);
+  if (errs.length) throw new Error(errs.join('; '));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const r = { id: rule.id, metric: String(rule.metric).trim(), op: rule.op, threshold: rule.threshold, severity: rule.severity };
+  return L.append(file, { id: L.newId(), kind: 'signal_rule', why: 'signal rule set by the PM', at: now, rule: r }, actor);
+}
+
+// Appends the reading, then a trip line for each rule that this reading newly trips (it did not trip on the reading before).
+function appendReading(file, reading, actor, now) {
+  if (!String(reading.metric || '').trim()) throw new Error('metric is required');
+  if (typeof reading.value !== 'number' || !Number.isFinite(reading.value)) throw new Error('value must be a number');
+  const at = reading.at || now;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const before = foldSignals(L.read(file));
+  const wasOpen = new Set(before.open.map((t) => t.rule_id));
+  const line = L.append(file, { id: L.newId(), kind: 'signal_reading', why: 'metric reading', metric: reading.metric, value: reading.value, at }, actor);
+  const trips = [];
+  for (const t of evaluateRules(before.rules, [...L.read(file).filter((x) => x.kind === 'signal_reading')])) {
+    if (t.reading.at !== at || t.reading.metric !== reading.metric || wasOpen.has(t.rule_id)) continue;
+    trips.push(L.append(file, { id: L.newId(), kind: 'signal_trip', why: 'rule tripped on a reading', rule_id: t.rule_id, severity: t.severity, reading: t.reading, at }, actor));
+  }
+  return { line, trips };
+}
+
+module.exports = { OPS, SEVERITIES, validateRule, evaluateRules, foldSignals, tripsSince, trippedSince, appendRule, appendReading };

package/workspace/lib/engine/signals/cards.js

@@ -0,0 +1,57 @@
+'use strict';
+// Signal engine, step 8: card anatomy. A card is a plain object the UI can render:
+//   tag, headline (computed numbers), hero (one, chosen by data shape), facts (at most 3), move (suggested move
+//   with options, or null), deadline (days + source, falling back to the promise date), why (score terms), absorbs,
+//   kind + tone + template (kinds.js: what this kind must say, the parts it says and the parts it cannot), source.
+
+const { rankOptions } = require('./options');
+const { weakest } = require('./detectors');
+const K = require('./kinds');
+
+// Hero by data shape. A series of 3 or more points is a line; two values to compare are two bars.
+const HERO = { series: 'line', compare: 'two-bars', rows: 'rows', ring: 'ring', bars: 'bars', graph: 'mini-graph', number: 'big-number' };
+function heroFor(head) {
+  if (Array.isArray(head.series) && head.series.length >= 3) return { kind: 'line', points: head.series };
+  if (head.shape === 'series') return { kind: 'big-number' };
+  return { kind: HERO[head.shape] || 'big-number' };
+}
+
+function deadlineOf(c, tolerance) {
+  if (c.needsDeadline) return { days: null, source: 'unknown', text: 'unknown - the agent asks: when does this need deciding?' };
+  const d = c.deadlineDays;
+  const when = d < 1 ? 'within a day' : Math.round(d) + ' days';
+  return { days: d, source: c.deadlineSource, text: `${when} because of ${c.deadlineSource}${c.promiseMissed && tolerance != null ? ` | promise to others missed beyond ${tolerance}d tolerance` : ''}` };
+}
+
+function buildCard(c, ctx) {
+  const head = c.head;
+  const tol = head.tolerance != null ? head.tolerance : null;
+  const w = c.weights;
+  const pinned = ctx.pinned.includes(c);
+  const move = head.options && head.options.length
+    ? rankOptions(head.options, { stance: ctx.stance, holders: (ctx.holdersOf && ctx.holdersOf(head.initiative)) || 0, weak: weakest(ctx.rubric) })
+    : null;
+  const k = K.kindOf(c);
+  const card = {
+    key: c.key, tag: c.tag, kind: k.kind, tone: K.toneOf(c, k), signal: K.baseId(head.id) || null, headline: c.title, hero: heroFor(head),
+    facts: (c.facts || []).filter(Boolean).slice(0, 3),
+    move: move && {
+      suggested: move.rec, options: move.opts, hold: move.hold, moveDate: move.move, closeCall: move.close, stance: ctx.stance,
+      note: 'confidence not shown: no track record for this kind of decision yet',
+    },
+    deadline: deadlineOf(c, tol),
+    waitsFor: c.blockedBy || null,
+    pinned,
+    why: {
+      pinned, impact: c.impact, urgency: c.urgency, irreversible: c.irrev, novelty: c.novelty, lensFit: c.lensFit, positive: c.positive, score: c.score,
+      text: `${pinned ? '[pinned: Critical and due within 3 days] ' : ''}impact ${c.impact.toFixed(2)} x ${w.impact} + urgency ${c.urgency.toFixed(2)} x ${w.urgency} + irreversible ${c.irrev} x ${w.irreversible}, x novelty ${c.novelty} x ${ctx.lens || 'any'} fit ${c.lensFit}${c.positive ? ' x 0.8 (positive)' : ''} = ${c.score}`,
+    },
+    absorbs: c.members.map((m) => m.id),
+    page: c.page, entity: c.entity, score: c.score,
+    source: { page: c.page, entity: c.entity || null },
+  };
+  card.template = { must: k.must, text: k.says, ...K.fillTemplate(card, k.must) };
+  return card;
+}
+
+module.exports = { buildCard, heroFor, deadlineOf };