create-pmos 0.133.0 → 0.135.0

package/workspace/lib/engine/plan-forecast.js

@@ -0,0 +1,342 @@
+'use strict';
+/* plan-forecast.js — the forecast, critical path, time machine and capacity load of the Timeline (console3 wave B5).
+ * PURE: no I/O, no clock (today is a parameter). Nothing here is typed by the PM; every date is derived.
+ *
+ * BACKED BY THE PM'S SAMPLE: the forecast dates come from derived/plan.js plan() (end = latest dependency end, or the start,
+ * plus duration), and the critical path is derived/derive.js critical() (the items with slack 0 against the forecast, from
+ * the sample's facts.js). Nothing here re-implements them; this file only adapts repo items to the sample's state shape and
+ * keeps the graph clean (unknown dependencies and cycles are reported in `problems`, where plan.js throws).
+ * REPO-WRITTEN, because the sample has no equivalent: stateAt/replay (the slider stepping over { at, id, op } events),
+ * weeksFrom, progressOf, capacityLoad and rebalanceProposal.
+ *
+ * DECISION CHANGED TO MATCH THE SAMPLE: the older code moved an unfinished item past its planned end to today + remaining
+ * time (the handoff's open question, "decide at build"). plan.js decides otherwise: progress is not an input, so the forecast
+ * ignores status, progress, doneAt and today. `today` now only decides the 'overdue' status label.
+ *
+ * Items: { id, start:'YYYY-MM-DD', due:'YYYY-MM-DD', state|status, after:[ids], owner, points, skill, progress }.
+ * Dependencies: `deps` is { id: [ids it waits for] }, or null to read each item's `after`.
+ */
+const P = require('./derived/plan.js');
+const V = require('./derived/derive.js');
+const DAY = P.D;
+const day = (s) => P.day(String(s).slice(0, 10));
+const fmt = P.fmt;
+const stateOf = (it) => String(it.state || it.status || 'todo');
+const PROGRESS = { todo: 0, doing: 0.5, review: 0.9, done: 1 };
+function progressOf(it) {
+  if (typeof it.progress === 'number' && it.progress >= 0 && it.progress <= 1 && stateOf(it) !== 'done') return it.progress;
+  return PROGRESS[stateOf(it)] == null ? 0 : PROGRESS[stateOf(it)];
+}
+const durOf = (it) => (it.start && it.due ? Math.max(1, Math.round((day(it.due) - day(it.start)) / DAY)) : 1);
+const depsOf = (it, deps) => (deps && deps[it.id] ? deps[it.id] : (!deps && it.after) || []);
+
+/** Clean the graph: unknown dependencies reported, cycles broken at the back edge and reported, topological order. */
+function graph(items, deps) {
+  const by = new Map(items.map((it) => [it.id, it]));
+  const problems = [];
+  const clean = new Map();
+  for (const it of items) {
+    const ok = [];
+    for (const d of depsOf(it, deps)) {
+      if (!by.has(d)) problems.push({ kind: 'unknown-dependency', item: it.id, dependency: d });
+      else if (d === it.id) problems.push({ kind: 'cycle', path: [it.id, it.id] });
+      else ok.push(d);
+    }
+    clean.set(it.id, ok.sort());
+  }
+  const color = new Map();
+  const order = [];
+  const visit = (id, stack) => {
+    color.set(id, 1);
+    const keep = [];
+    for (const d of clean.get(id)) {
+      if (color.get(d) === 1) { problems.push({ kind: 'cycle', path: stack.slice(stack.indexOf(d)).concat(d) }); continue; }
+      keep.push(d);
+      if (!color.get(d)) visit(d, stack.concat(d));
+    }
+    clean.set(id, keep);
+    color.set(id, 2);
+    order.push(id);
+  };
+  for (const id of [...by.keys()].sort()) if (!color.get(id)) visit(id, [id]);
+  return { by, clean, order, problems };
+}
+
+function statusOf(it, slip, end, today) {
+  if (stateOf(it) !== 'done' && it.due && day(it.due) < today) return 'overdue';
+  if (slip <= 0) return 'on time';
+  return slip <= 3 ? 'at risk' : 'delayed';
+}
+
+/** The sample's state shape ({ dur, deps }) over the cleaned graph, and the one start plan.js takes: the earliest planned start. */
+function sampleState(g, today) {
+  const state = {};
+  for (const [id, it] of g.by) state[id] = { dur: durOf(it), deps: g.clean.get(id) };
+  const starts = [...g.by.values()].filter((it) => it.start).map((it) => day(it.start));
+  return { state, start: fmt(starts.length ? Math.min(...starts) : day(today)) };
+}
+
+/** forecast(items, deps, today) → { rows: [{ id, start, end, slip_days, status }], problems }.  `today` is 'YYYY-MM-DD'. */
+function forecast(items, deps, today) {
+  const g = graph(items, deps);
+  if (!items.length) return { rows: [], problems: g.problems };
+  const t = day(today);
+  const { state, start } = sampleState(g, today);
+  const pl = P.plan(state, start);
+  const rows = items.map((it) => {
+    const e = pl.end[it.id];
+    const plannedEnd = it.due ? day(it.due) : e;
+    const slip = Math.round((e - plannedEnd) / DAY);
+    return { id: it.id, start: fmt(e - state[it.id].dur * DAY), end: fmt(e), slip_days: slip, status: statusOf(it, slip, e, t) };
+  });
+  return { rows, problems: g.problems };
+}
+
+/** criticalPath(items, deps) → { ids, days, problems }: every item with slack 0 against the forecast (the sample's rule), in
+ *  end-date then id order. Two equal chains are both critical. days = forecast minus the start. */
+function criticalPath(items, deps) {
+  const g = graph(items, deps);
+  if (!items.length) return { ids: [], days: 0, problems: g.problems };
+  const { state, start } = sampleState(g, '1970-01-01');
+  const pl = P.plan(state, start);
+  const ids = [...V.critical(state, pl)].sort((a, b) => pl.end[a] - pl.end[b] || (a < b ? -1 : 1));
+  return { ids, days: Math.round((pl.forecast - day(start)) / DAY), problems: g.problems };
+}
+
+/** stateAt(events, date) → the items as the fold of events up to and including `date` (the whole day). Events are append-only
+ *  { at, id, op: 'add'|'set'|'remove', fields }; the same events in any order give the same state (sorted by at, then input order). */
+function stateAt(events, date) {
+  const cut = /^\d{4}-\d\d-\d\d$/.test(String(date)) ? date + 'T23:59:59.999Z' : String(date);
+  const sorted = (events || []).map((e, i) => ({ e, i })).filter((x) => String(x.e.at) <= cut)
+    .sort((a, b) => (String(a.e.at) < String(b.e.at) ? -1 : String(a.e.at) > String(b.e.at) ? 1 : a.i - b.i));
+  const s = new Map();
+  for (const { e } of sorted) {
+    if (e.op === 'add') s.set(e.id, { ...(e.fields || {}), id: e.id });
+    else if (e.op === 'set' && s.has(e.id)) Object.assign(s.get(e.id), e.fields || {});
+    else if (e.op === 'remove') s.delete(e.id);
+  }
+  return [...s.values()].sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+/** replay(events, from, to, stepDays) → [{ date, items }] in date order, always ending at `to`. At most 400 steps. */
+function replay(events, from, to, stepDays) {
+  const step = Math.max(1, Math.floor(stepDays) || 1) * DAY;
+  const out = [];
+  for (let d = day(from); d < day(to) && out.length < 399; d += step) out.push({ date: fmt(d), items: stateAt(events, fmt(d)) });
+  out.push({ date: fmt(day(to)), items: stateAt(events, to) });
+  return out;
+}
+
+/** The n week starts (Mondays) from the week that holds `today`. */
+function weeksFrom(today, n) {
+  const d = new Date(day(today));
+  const back = (d.getUTCDay() + 6) % 7;
+  return Array.from({ length: n }, (_, i) => fmt(day(today) - back * DAY + i * 7 * DAY));
+}
+
+/** capacityLoad(items, people, weeks) → { weeks, people: [{ id, points_per_week, skills, weeks: [{ week, load, over, parts }] }], over }.
+ *  weeks: Monday dates. An item's remaining points (points, default 1, x (1 - progress)) spread evenly over its start..end days
+ *  (give it forecast rows' start and end); a week's load is the points falling in it. people: { id, points_per_week, skills }. */
+function capacityLoad(items, people, weeks) {
+  const out = (people || []).map((p) => ({ id: p.id, points_per_week: p.points_per_week, skills: p.skills || [],
+    weeks: weeks.map((w) => ({ week: w, load: 0, over: false, parts: [] })) }));
+  const by = new Map(out.map((p) => [p.id, p]));
+  for (const it of items) {
+    const p = by.get(it.owner);
+    if (!p || stateOf(it) === 'done') continue;
+    const s = day(it.start || it.due); const e = Math.max(day(it.end || it.due), s + DAY);
+    const pts = (typeof it.points === 'number' ? it.points : 1) * (1 - progressOf(it));
+    p.weeks.forEach((w) => {
+      const a = Math.max(s, day(w.week)); const b = Math.min(e, day(w.week) + 7 * DAY);
+      if (b > a) { const part = pts * (b - a) / (e - s); w.load += part; w.parts.push({ item: it.id, points: part, skill: it.skill || null }); }
+    });
+  }
+  const over = [];
+  for (const p of out) for (const w of p.weeks) {
+    w.load = Math.round(w.load * 100) / 100;
+    w.over = w.load > p.points_per_week;
+    if (w.over) over.push({ person: p.id, week: w.week, load: w.load, capacity: p.points_per_week });
+  }
+  return { weeks, people: out, over };
+}
+
+/** rebalanceProposal(load) → { proposal: true, applied: false, moves }. For each over-capacity week (worst first) one item moves
+ *  from the most overloaded person to the least loaded one who has the item's skill, else to the least loaded. A PROPOSAL only:
+ *  this function changes nothing, and the plan changes only through the plan-items writer. */
+function rebalanceProposal(load) {
+  const sim = new Map(load.people.map((p) => [p.id, new Map(p.weeks.map((w) => [w.week, w.load]))]));
+  const moves = [];
+  const todo = load.over.map((o) => ({ ...o, excess: o.load - o.capacity })).sort((a, b) => b.excess - a.excess || (a.person + a.week < b.person + b.week ? -1 : 1));
+  for (const o of todo) {
+    const from = load.people.find((p) => p.id === o.person);
+    const part = from.weeks.find((w) => w.week === o.week).parts.slice().sort((a, b) => b.points - a.points || (a.item < b.item ? -1 : 1))[0];
+    if (!part || moves.some((m) => m.item === part.item)) continue;
+    const others = load.people.filter((p) => p.id !== o.person);
+    const ratio = (p) => sim.get(p.id).get(o.week) / (p.points_per_week || 1);
+    const skilled = part.skill ? others.filter((p) => p.skills.includes(part.skill)) : [];
+    const pool = skilled.length ? skilled : others;
+    const to = pool.slice().sort((a, b) => ratio(a) - ratio(b) || (a.id < b.id ? -1 : 1))[0];
+    if (!to) continue;
+    sim.get(o.person).set(o.week, sim.get(o.person).get(o.week) - part.points);
+    sim.get(to.id).set(o.week, sim.get(to.id).get(o.week) + part.points);
+    moves.push({ item: part.item, from: o.person, to: to.id, week: o.week, points: Math.round(part.points * 100) / 100,
+      reason: skilled.length ? 'least loaded with skill ' + part.skill : 'least loaded' });
+  }
+  return { proposal: true, applied: false, moves };
+}
+
+
+/* ───────────── the Timeline's per-check frames and "what changed" (console3 Timeline, ported from the mockup's tixAt / planOf / revsAt) ─────────────
+ * The mockup replays the plan by folding every ticket's revision history up to a check and re-planning it (tixAt, planOf). These do the same
+ * over the repo's { at, id, op, fields, by, why } events: stateAt() is the fold, plan.js plan() is the plan, and the one difference from
+ * forecast() is the day convention. A bar covers its first and LAST day (the mockup draws due + 1 as the bar's right edge), so a dependency
+ * arrow from the end of one bar meets the start of the next. plan.js treats `end` as the first day AFTER the work, so end(inclusive) = end - 1 day.
+ * An item with its own planned start keeps it: plan.js has one start for the whole plan, so each item gets a zero-dependency "gap" node as long as
+ * the days from the plan start to its own start (a node plan.js plans like any other; its rows are dropped again). Milestones take no time.
+ */
+const dayStr = (n) => fmt(n);
+const addD = (s, n) => fmt(day(s) + n * DAY);
+const gapId = (id) => ' gap:' + id;
+
+/** frameForecast(items, today, opts?) → { rows: [{ id, start, end, slip_days, status }], critical: [ids], forecast_end, problems }.
+ *  items: { id, start, due, after, state, ms? }. Dates are 'YYYY-MM-DD', end is the last day of work (inclusive). today only labels 'overdue'. */
+function frameForecast(items, today) {
+  const g = graph(items, null);
+  if (!items.length) return { rows: [], critical: [], forecast_end: null, problems: g.problems };
+  const starts = items.filter((it) => it.start).map((it) => day(it.start));
+  const base = starts.length ? Math.min(...starts) : day(today);
+  const state = {};
+  for (const [id, it] of g.by) {
+    const ownStart = it.start ? day(it.start) : base;
+    const gap = Math.max(0, Math.round((ownStart - base) / DAY) + (it.ms ? 1 : 0));
+    const dur = it.ms ? 0 : (it.start && it.due ? Math.max(1, Math.round((day(it.due) - day(it.start)) / DAY) + 1) : 1);
+    state[gapId(id)] = { dur: gap, deps: [] };
+    state[id] = { dur, deps: stateOf(it) === 'done' ? [gapId(id)] : [gapId(id), ...g.clean.get(id)] };   // finished work keeps the dates it had
+  }
+  const pl = P.plan(state, fmt(base));
+  const t = day(today);
+  const rows = items.map((it) => {
+    const e = pl.end[it.id];
+    const endDay = e - DAY;                       // plan.js end is the first day after the work: the last day is one before
+    const due = it.due ? day(it.due) : endDay;
+    const slip = Math.max(0, Math.round((endDay - due) / DAY));
+    const startDay = it.ms ? endDay : e - state[it.id].dur * DAY;
+    const done = stateOf(it) === 'done';
+    const status = done ? 'done' : slip <= 0 ? 'on time' : due < t ? 'overdue' : slip <= 3 ? 'at risk' : 'delayed';
+    return { id: it.id, start: fmt(startDay), end: fmt(endDay), slip_days: done ? 0 : slip, status };
+  });
+  const crit = [...V.critical(state, pl)].filter((k) => !k.startsWith(' gap:') && stateOf(g.by.get(k)) !== 'done').sort((a, b) => pl.end[a] - pl.end[b] || (a < b ? -1 : 1));
+  return { rows, critical: crit, forecast_end: fmt(Math.max(...rows.map((r) => day(r.end)))), problems: g.problems };
+}
+
+const ptsOf = (it) => (typeof it.points === 'number' && it.points > 0 ? it.points : 1);
+const sumPts = (items) => items.reduce((a, it) => a + ptsOf(it), 0);
+const depsStr = (a) => (a || []).slice().sort().join(',');
+
+/** whatChanged(a, b, events?) → what differs between two plan states, as the mockup's timeRight reads it: items added, removed, moved
+ *  (start or due, with the days), dependency changes, points and the forecast. a and b are stateAt() arrays (a may be empty or null).
+ *  events: the { at, id, op, fields, by, why } events between the two checks; the last one that touched an item names who and why. */
+function whatChanged(a, b, events) {
+  const A = new Map((a || []).map((it) => [it.id, it]));
+  const B = new Map((b || []).map((it) => [it.id, it]));
+  const last = new Map();
+  for (const e of events || []) last.set(e.id, e);
+  const who = (id) => { const e = last.get(id) || {}; return { by: e.by || null, why: e.why || '' }; };
+  const adds = new Map();
+  for (const e of events || []) if (e.op === 'add' && !adds.has(e.id)) adds.set(e.id, e);
+  const out = { added: [], removed: [], moved: [], deps: [], points: { from: sumPts([...A.values()]), to: sumPts([...B.values()]) } };
+  out.points.delta = out.points.to - out.points.from;
+  for (const [id, it] of B) {
+    if (!A.has(id)) { const e = adds.get(id) || last.get(id) || {}; out.added.push({ id, title: it.title || id, points: ptsOf(it), by: e.by || null, why: e.why || '' }); continue; }
+    const o = A.get(id);
+    for (const f of ['start', 'due']) {
+      if (o[f] && it[f] && o[f] !== it[f]) out.moved.push({ id, title: it.title || id, field: f, from: o[f], to: it[f], days: Math.round((day(it[f]) - day(o[f])) / DAY), ...who(id) });
+    }
+    if (depsStr(o.after) !== depsStr(it.after)) {
+      const was = new Set(o.after || []); const now = new Set(it.after || []);
+      out.deps.push({ id, title: it.title || id, added: [...now].filter((d) => !was.has(d)), removed: [...was].filter((d) => !now.has(d)), ...who(id) });
+    }
+  }
+  for (const [id, it] of A) if (!B.has(id)) out.removed.push({ id, title: it.title || id, ...who(id) });
+  return out;
+}
+
+/** pickChecks(events, today, max?) → [{ date, label }]: the days the plan changed (the first is the baseline), then today. At most `max`
+ *  (default 6): the baseline plus the latest changes. Events marked `synthetic` (a source with no history, such as Jira) never make a check. */
+function pickChecks(events, today, max) {
+  const cap = Math.max(2, max || 6);
+  const real = (events || []).filter((e) => !e.synthetic && e.at && String(e.at).slice(0, 10) <= today);
+  const dates = [...new Set(real.map((e) => String(e.at).slice(0, 10)))].sort();
+  let keep = dates;
+  const hasToday = dates.includes(today);
+  const room = cap - (hasToday ? 0 : 1);
+  if (dates.length > room) keep = [dates[0], ...dates.slice(dates.length - (room - 1))];
+  const titleOf = new Map();
+  for (const e of real) if (e.op === 'add' && e.fields && e.fields.title && !titleOf.has(e.id)) titleOf.set(e.id, e.fields.title);
+  const label = (d, i) => {
+    if (d === today) return 'Today';
+    if (i === 0) return 'Baseline';
+    const adds = real.filter((e) => String(e.at).slice(0, 10) === d && e.op === 'add');
+    const n = real.filter((e) => String(e.at).slice(0, 10) === d).length;
+    return adds.length === 1 && n === 1 ? short(titleOf.get(adds[0].id) || adds[0].id, 24) + ' added' : n + ' change' + (n === 1 ? '' : 's');
+  };
+  const out = keep.map((d, i) => ({ date: d, label: label(d, i) }));
+  if (!hasToday) out.push({ date: today, label: 'Today' });
+  return out;
+}
+const short = (t, n) => { t = String(t); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const dlab = (s) => { const d = new Date(day(s)); return d.getUTCDate() + ' ' + MONTHS[d.getUTCMonth()]; };
+/** One line per item touched between two checks: who (the last to touch it), why, and what changed in words ("Due 24 to 28 Oct"). */
+function describeWindow(win, before, after) {
+  const B = new Map((before || []).map((it) => [it.id, it])); const Af = new Map((after || []).map((it) => [it.id, it]));
+  const order = []; const by = new Map();
+  for (const e of win) { if (!by.has(e.id)) { by.set(e.id, []); order.push(e.id); } by.get(e.id).push(e); }
+  return order.map((id) => {
+    const es = by.get(id); const last = es[es.length - 1]; const a = Af.get(id); const b = B.get(id);
+    const src = a || b || {};
+    const base = { id, key: src.key || null, title: src.title || id, origin: src.origin || null, by: last.by || null, why: (es.slice().reverse().find((x) => x.why) || {}).why || '', at: last.at };
+    if (!a) return { ...base, op: 'remove', tx: 'Removed' };
+    if (!b) return { ...base, op: 'add', tx: '' };
+    const t = [];
+    if (b.start !== a.start && b.start && a.start) t.push('Start ' + dlab(b.start) + ' to ' + dlab(a.start));
+    if (b.due !== a.due && b.due && a.due) t.push('Due ' + dlab(b.due) + ' to ' + dlab(a.due));
+    if (depsStr(b.after) !== depsStr(a.after)) {
+      const was = new Set(b.after || []); const add = (a.after || []).filter((d) => !was.has(d)); const gone = (b.after || []).filter((d) => !(a.after || []).includes(d));
+      if (add.length) t.push('Waits on ' + add.map((d) => (Af.get(d) && Af.get(d).key) || d).join(', '));
+      if (gone.length) t.push('No longer waits on ' + gone.map((d) => (B.get(d) && B.get(d).key) || d).join(', '));
+    }
+    if (b.owner !== a.owner) t.push('Owner ' + (b.owner || 'none') + ' to ' + (a.owner || 'none'));
+    if (b.state !== a.state) t.push('Now ' + a.state);
+    if (ptsOf(b) !== ptsOf(a)) t.push('Points ' + ptsOf(b) + ' to ' + ptsOf(a));
+    if (b.title !== a.title) t.push('Renamed');
+    return { ...base, op: 'edit', tx: t.join(', ') };
+  });
+}
+
+/** checkFrames(events, checks, today) → [{ check, date, label, items, critical, forecast_end, promised, slip_days, points, problems, changes, events }]
+ *  Each frame is the whole plan as it stood at that check, planned with plan.js, so a replay redraws a Gantt per frame. promised: the due date of the
+ *  latest milestone (null when no item is a milestone); the forecast date is that milestone's forecast end, or the latest end when there is none. */
+function checkFrames(events, checks, today) {
+  const out = []; let prev = null;
+  checks.forEach((c, i) => {
+    const items = stateAt(events, c.date);
+    const asOf = c.date > today ? today : c.date;
+    const f = frameForecast(items, asOf);
+    const by = new Map(f.rows.map((r) => [r.id, r]));
+    const crit = new Set(f.critical);
+    const merged = items.map((it) => ({ ...it, forecast: by.get(it.id), critical: crit.has(it.id) }));
+    const ms = items.filter((it) => it.ms && it.due).sort((x, y) => (x.due < y.due ? 1 : x.due > y.due ? -1 : 0))[0];
+    const promised = ms ? ms.due : null;
+    const fe = ms ? by.get(ms.id).end : f.forecast_end;
+    const win = (events || []).filter((e) => !e.synthetic && String(e.at).slice(0, 10) <= c.date && (!prev || String(e.at).slice(0, 10) > prev.date));
+    out.push({ check: i, date: c.date, label: c.label, items: merged, critical: f.critical, forecast_end: fe, promised, slip_days: promised && fe ? Math.round((day(fe) - day(promised)) / DAY) : 0,
+      points: sumPts(items), problems: f.problems, changes: i === 0 ? null : whatChanged(prev.items, items, win), events: describeWindow(win, prev ? prev.items : [], items) });
+    prev = { date: c.date, items };
+  });
+  return out;
+}
+
+module.exports = { describeWindow, frameForecast, whatChanged, pickChecks, checkFrames, timeline: V.timeline, forecast, criticalPath, stateAt, replay, capacityLoad, rebalanceProposal, weeksFrom, progressOf, graph };

package/workspace/lib/engine/promises.js

@@ -0,0 +1,29 @@
+'use strict';
+// The promise ledger, rebased on the PM's ledger (scripts/trust/ledger.js): ULID ids, append-only, and the writer comes
+// from the call path (an actor), never from a field. Events: kind 'promise' and kind 'kept'.
+const L = require('./trust/ledger.js');
+
+function recordPromise({ to, what, by_date, source_entry_hash } = {}) {
+  if (!to || !what) throw new Error('to and what required');
+  if (Number.isNaN(Date.parse(by_date))) throw new Error('by_date must be an ISO date');
+  return { kind: 'promise', to, what, by_date, source_entry_hash: source_entry_hash || null };
+}
+
+const keptEvent = (source_entry_hash) => ({ kind: 'kept', source_entry_hash });
+
+// Append through the ledger: adds id, why and (from the actor) by/via. `actor` is required: L.actorFrom(...) or the server's UI actor.
+function appendPromise(file, event, actor, now = new Date()) {
+  const why = event.kind === 'kept' ? 'promise kept' : 'promise to ' + event.to;
+  return L.append(file, { id: L.newId(), why, at: now.toISOString(), ...event }, actor);
+}
+
+const kindOf = (e) => e.kind || e.event;   // older lines used `event`
+
+// ledger: array of events. A promise is kept when a 'kept' event carries its source_entry_hash.
+function brokenPromises(ledger = [], today = new Date()) {
+  const t = new Date(today).getTime();
+  const kept = new Set(ledger.filter((e) => kindOf(e) === 'kept').map((e) => e.source_entry_hash));
+  return ledger.filter((e) => kindOf(e) === 'promise' && Date.parse(e.by_date) < t && !kept.has(e.source_entry_hash));
+}
+
+module.exports = { recordPromise, keptEvent, brokenPromises, appendPromise };

package/workspace/lib/engine/records/index.js

@@ -0,0 +1,114 @@
+'use strict';
+/*
+ * Record kinds the console3 model lists as "remaining entities": ideas, hypotheses, the decision log, KR metrics, bets.
+ *
+ * FILES. In the real repo each kind is ONE append-only JSONL file: planning/records/<kind>.jsonl (ideas.jsonl,
+ * hypotheses.jsonl, decisions.jsonl, kr-metrics.jsonl, bets.jsonl). Nothing here creates those files in the repo; every
+ * function takes a `root` (tests pass os.tmpdir()). The prototype sample keeps ideas and hypotheses as Markdown; here
+ * they are events so one fold and one writer serve all five kinds (the Markdown form can be derived from the fold).
+ *
+ * EVENTS. Every line is written by scripts/trust/ledger.js append (the PM's validated writer; this file has no appender of
+ * its own). A line is { id (ULID), kind: 'add'|'edit'|'reading', rid, fields, why, by, via }.
+ *   add     creates record `rid` with `fields`            edit     merges `fields` into it (latest edit wins per field)
+ *   reading (kr-metrics only) one actual reading { at, value } of the KR metric `rid`
+ * The actor comes from the call path (ledger.actorFrom), never from a field.
+ *
+ * LINKS. ideas, hypotheses, decisions and bets carry `initiative` (initiative id) and `parent_kr`; signals link by those.
+ */
+const fs = require('fs');
+const path = require('path');
+const ledger = require('../trust/ledger.js');
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+const text = (v) => typeof v === 'string' && v.trim() !== '';
+const HORIZONS = ['now', 'next', 'later'];
+
+// required: name -> predicate and the reason shown when it fails. `fix` rules run on the merged record.
+const KINDS = {
+  ideas: { file: 'ideas.jsonl', required: { title: [text, 'title'], impact: [num, 'impact (number)'], effort: [(v) => num(v) && v > 0, 'effort (number above 0)'], confidence: [(v) => num(v) && v >= 0 && v <= 1, 'confidence (0 to 1)'] } },
+  hypotheses: {
+    file: 'hypotheses.jsonl',
+    required: { title: [text, 'title'], falsifier: [text, 'falsifier (what result would prove it wrong)'], review_by: [(v) => DATE.test(String(v)), 'review_by (YYYY-MM-DD)'] },
+  },
+  decisions: { file: 'decisions.jsonl', required: { case: [text, 'case'], chose: [text, 'chose'], why: [text, 'why'] } },
+  'kr-metrics': {
+    file: 'kr-metrics.jsonl',
+    required: { metric: [text, 'metric'], baseline: [num, 'baseline (number)'], target: [num, 'target (number)'], by: [(v) => DATE.test(String(v)), 'by (YYYY-MM-DD)'] },
+  },
+  bets: {
+    file: 'bets.jsonl',
+    required: { title: [text, 'title'], horizon: [(v) => HORIZONS.includes(v), 'horizon (now, next or later)'], rank: [(v) => Number.isInteger(v) && v >= 1, 'rank (whole number from 1)'] },
+  },
+};
+const kindNames = () => Object.keys(KINDS);
+const spec = (kind) => { if (!KINDS[kind]) throw new Error('unknown record kind: ' + kind); return KINDS[kind]; };
+const fileOf = (root, kind) => path.join(root, spec(kind).file);
+
+/** validate(kind, fields) -> { ok, reasons[] }. `fields` is the whole record (an add) or the merged record (an edit). */
+function validate(kind, fields) {
+  const reasons = [];
+  const f = fields && typeof fields === 'object' ? fields : {};
+  for (const [name, [ok, label]] of Object.entries(spec(kind).required)) {
+    if (!(name in f) || f[name] == null || !ok(f[name])) reasons.push('missing or invalid: ' + label);
+  }
+  if (kind === 'kr-metrics' && f.by && f.baseline === f.target && num(f.baseline)) reasons.push('target equals baseline');
+  return { ok: reasons.length === 0, reasons };
+}
+
+const readLines = (file) => { try { return ledger.read(file); } catch { return []; } };
+
+/** fold(kind, lines) -> list of records, in first-add order. An edit merges; a reading joins `readings` (kr-metrics). */
+function fold(kind, lines) {
+  spec(kind);
+  const by = new Map();
+  for (const e of lines) {
+    if (!e || !e.rid) continue;
+    if (e.kind === 'add') by.set(e.rid, { rid: e.rid, ...e.fields, created: e.id, updated: e.id, readings: [] });
+    else if (e.kind === 'edit' && by.has(e.rid)) Object.assign(by.get(e.rid), e.fields, { updated: e.id });
+    else if (e.kind === 'reading' && by.has(e.rid) && e.fields) by.get(e.rid).readings.push({ at: e.fields.at, value: e.fields.value });
+  }
+  const out = [...by.values()];
+  if (kind !== 'kr-metrics') out.forEach((r) => delete r.readings);
+  else out.forEach((r) => r.readings.sort((a, b) => String(a.at).localeCompare(String(b.at))));
+  return out;
+}
+
+function list(root, kind) { return fold(kind, readLines(fileOf(root, kind))); }
+
+/** The three writers each validate, then go through ledger.append. They return { ok, rid?, line?, reasons? }. */
+function write(root, kind, ev, actor) {
+  fs.mkdirSync(root, { recursive: true });
+  const file = fileOf(root, kind);
+  const line = ledger.append(file, { id: ledger.newId(), ...ev }, actor);
+  return { ok: true, rid: ev.rid, line };
+}
+function add(root, kind, fields, actor, why) {
+  const v = validate(kind, fields);
+  if (!v.ok) return { ok: false, reasons: v.reasons };
+  const rid = (fields && fields.rid) || kind.replace(/s$/, '').replace('kr-metric', 'krm') + '-' + ledger.newId().slice(-8).toLowerCase();
+  const { rid: _r, readings: _x, ...clean } = fields;
+  return write(root, kind, { kind: 'add', rid, fields: clean, why: why || 'added' }, actor);
+}
+function edit(root, kind, rid, fields, actor, why) {
+  const cur = list(root, kind).find((r) => r.rid === rid);
+  if (!cur) return { ok: false, reasons: ['no such record: ' + rid] };
+  const merged = { ...cur, ...fields };
+  const v = validate(kind, merged);
+  if (!v.ok) return { ok: false, reasons: v.reasons };
+  return write(root, kind, { kind: 'edit', rid, fields, why: why || 'edited' }, actor);
+}
+function addReading(root, rid, reading, actor, why) {
+  if (!reading || !DATE.test(String(reading.at)) || !num(reading.value)) return { ok: false, reasons: ['a reading needs at (YYYY-MM-DD) and value (number)'] };
+  if (!list(root, 'kr-metrics').some((r) => r.rid === rid)) return { ok: false, reasons: ['no such KR metric: ' + rid] };
+  return write(root, 'kr-metrics', { kind: 'reading', rid, fields: { at: reading.at, value: reading.value }, why: why || 'reading' }, actor);
+}
+
+/** All five folds for nineStages and readRepoFacts. Missing files give empty lists. */
+function readAll(root) {
+  const out = {};
+  for (const k of kindNames()) out[k] = list(root, k);
+  return out;
+}
+
+module.exports = { KINDS, HORIZONS, kindNames, validate, fold, list, add, edit, addReading, readAll, fileOf, readLines };

package/workspace/lib/engine/releases.js

@@ -0,0 +1,96 @@
+'use strict';
+// Run 5: releases, read side. Pure functions; appendRelease is the only I/O.
+// PMOS never reads Jira: tickets and tags arrive as imports (jira-status.js normaliser) and are passed in.
+// Tickets: { key, initiative_id?, fixVersion? }. fixVersion is a list of names (jira-status.js carries it) or one name.
+const fs = require('fs');
+const path = require('path');
+
+const TYPES = ['deploy', 'customer', 'both'];
+const LABELS = ['fact', 'estimate', 'assumption', 'reported'];
+
+const isoOrNull = (v) => (typeof v === 'string' && !Number.isNaN(Date.parse(v)) ? v : null);
+
+function newRelease({ id, initiative_ids = [], type, deploy_at = null, release_at = null } = {}) {
+  if (!id) throw new Error('release id required');
+  if (!TYPES.includes(type)) throw new Error(`type must be one of ${TYPES.join('|')}`);
+  return {
+    id, initiative_ids: [...initiative_ids], type,
+    deploy_at: isoOrNull(deploy_at), release_at: isoOrNull(release_at),
+    acceptance_required_before_tag: true, // a tag can only be created after the PM's acceptance (field only; creation not built)
+  };
+}
+
+// The Jira tag naming convention is unknown, so this never guesses a pattern.
+function detectTags(release, board) {
+  if (!board) return { detected: [], reason: 'board not set' };
+  const tags = (board.tags || []);
+  const detected = tags.filter((t) => t === release.id || (board.map && board.map[t] === release.id));
+  return { detected, reason: detected.length ? 'matched by release id or board.map' : 'no tag matched' };
+}
+
+const tagsOf = (t) => (Array.isArray(t.fixVersion) ? t.fixVersion : t.fixVersion ? [t.fixVersion] : []);
+
+function gapFlags(release, tickets = []) {
+  const ids = new Set(release.initiative_ids);
+  const tag = release.fix_version || release.id;
+  const flags = [];
+  for (const t of tickets) {
+    const tags = tagsOf(t);
+    if (ids.has(t.initiative_id) && !tags.length) flags.push({ flag: 'initiative_ticket_without_tag', ticket: t.key });
+    if (tags.includes(tag) && !t.initiative_id) flags.push({ flag: 'tagged_ticket_without_initiative', ticket: t.key });
+  }
+  return flags;
+}
+
+function citedSummary(lines = []) {
+  const refused = [];
+  lines.forEach((l, i) => {
+    const src = l && l.source;
+    const ok = typeof src === 'string' && (LABELS.includes(src) || /^[A-Z][A-Z0-9]+-\d+$/.test(src));
+    if (!ok) refused.push(i);
+  });
+  return refused.length ? { ok: false, refused } : { ok: true, lines };
+}
+
+// rule: null (default) or { start, end } ISO strings. No rule exists today.
+function freezeWarning(release, rule = null) {
+  if (!rule) return null;
+  const s = Date.parse(rule.start), e = Date.parse(rule.end);
+  const hits = ['deploy_at', 'release_at'].filter((k) => {
+    const d = release[k] && Date.parse(release[k]);
+    return d && d >= s && d <= e;
+  });
+  return hits.length ? { warning: 'inside change freeze', fields: hits, window: { start: rule.start, end: rule.end } } : null;
+}
+
+function appendRelease(file, event, now = new Date()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify({ ...event, at: now.toISOString() }) + '\n');
+}
+
+// Fold the append-only release lines (objects or JSON strings) into the current releases, in creation order.
+// Events: created {id, ...newRelease fields}, edited {id, fields}, summary {id, lines}, deleted {id}.
+const EDITABLE = ['initiative_ids', 'type', 'deploy_at', 'release_at', 'fix_version', 'accepted'];
+function foldReleases(lines = []) {
+  const byId = new Map();
+  for (let l of lines) {
+    if (typeof l === 'string') { try { l = JSON.parse(l); } catch { continue; } }
+    if (!l || !l.id) continue;
+    if (l.event === 'created') {
+      const { event, at, ...rest } = l;
+      byId.set(l.id, { ...rest, summary: [], created_at: at || null, accepted_at: null });
+    } else if (l.event === 'deleted') byId.delete(l.id);
+    else if (byId.has(l.id) && l.event === 'edited') {
+      const r = byId.get(l.id);
+      for (const k of EDITABLE) {
+        if (!l.fields || !(k in l.fields)) continue;
+        if (k === 'accepted') r.accepted_at = l.fields.accepted ? (l.at || new Date(0).toISOString()) : null;
+        else if (k === 'deploy_at' || k === 'release_at') r[k] = isoOrNull(l.fields[k]);
+        else r[k] = l.fields[k];
+      }
+    } else if (byId.has(l.id) && l.event === 'summary') byId.get(l.id).summary = Array.isArray(l.lines) ? l.lines : [];
+  }
+  return [...byId.values()];
+}
+
+module.exports = { TYPES, LABELS, EDITABLE, newRelease, detectTags, gapFlags, citedSummary, freezeWarning, appendRelease, foldReleases };