create-pmos 0.123.0 → 0.125.0

package/workspace/lib/routes-c3-strategy.js

@@ -0,0 +1,169 @@
+'use strict';
+/* routes-c3-strategy.js — read-only data for the Quarter and Year panes of the Calendar on /c3.html. Nothing is written here.
+ *
+ *   GET /api/c3-strategy → { ok, today, north, outcomes, signals, synergy, timeline, maturity, sources }
+ *
+ *   north      the KR metric record that carries `north_star: true`, as monthly points { at:'YYYY-MM', actual, plan, proj }, or null
+ *   outcomes   one row per KR metric record: now, where the straight line from baseline to target says it should be today, and the
+ *              forecast landing from the readings' own slope (null with fewer than two readings)
+ *   signals    open trips of the signal rules (scripts/signal-rules.js), plus a KR that is behind (or ahead of) its line by 10 percent
+ *              of the baseline-to-target span, plus a KR that is behind at three readings in a row and not closing (the pivot rule)
+ *   synergy    bets by key result: a dot where a bet's parent_kr names the key result; a key result with no active bet is a gap
+ *   timeline   bets by quarter from their horizon (now = this quarter, next = the one after, later = the third), and the hypotheses'
+ *              review dates inside the four quarters as checkpoints
+ *   maturity   null: this repository holds no pillar-maturity record, so the page says so
+ *
+ * Sources: planning/records/{kr-metrics,bets,hypotheses}.jsonl through scripts/records, and <runtime>/signals/signals.jsonl. No facts
+ * reader is used, so the route never starts a cold repository read. A number that no record holds is null, never invented. */
+const path = require('path');
+const fs = require('fs');
+const records = require(path.join(__dirname, '..', '..', 'scripts', 'records', 'index.js'));
+const sigRules = require(path.join(__dirname, '..', '..', 'scripts', 'signal-rules.js'));
+const ledger = require(path.join(__dirname, '..', '..', 'scripts', 'trust', 'ledger.js'));
+
+const EARLY = 0.10;     // the repository's early-warning share (scripts/calendar-model.js EARLY_WARNING)
+const OFF = 0.50;       // behind the line by half the span or more reads as off course
+const DAY = 864e5;
+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 fin = (v) => typeof v === 'number' && Number.isFinite(v);
+const r2 = (v) => (fin(v) ? Math.round(v * 100) / 100 : null);
+const rootOf = (ctx) => (ctx && ctx.recordsDir) || path.join((ctx && ctx.repoRoot) || path.join(__dirname, '..', '..'), 'planning', 'records');
+const monthKey = (t) => { const d = new Date(t); return d.getUTCFullYear() + '-' + pad(d.getUTCMonth() + 1); };
+const monthIdx = (k) => Number(k.slice(0, 4)) * 12 + Number(k.slice(5, 7)) - 1;
+const keyOfIdx = (i) => Math.floor(i / 12) + '-' + pad((i % 12) + 1);
+
+/** One KR metric record -> an outcome row. today is 'YYYY-MM-DD'. */
+function outcomeOf(k, today) {
+  const name = String(k.metric || k.rid);
+  const base = Number(k.baseline); const tgt = Number(k.target);
+  const rs = (k.readings || []).filter((x) => fin(Number(x.value)) && isDate(x.at)).map((x) => ({ at: String(x.at).slice(0, 10), v: Number(x.value) })).sort((a, b) => a.at.localeCompare(b.at));
+  const o = { id: k.rid, name, pillar: k.pillar ? String(k.pillar) : '', unit: k.unit ? String(k.unit) : '', start: fin(base) ? base : null, target: fin(tgt) ? tgt : null, by: k.by || null,
+    now: null, expected: null, forecast: null, status: 'unscored', lead: k.note ? String(k.note) : '', reason: '', readings: rs };
+  if (!fin(base) || !fin(tgt) || base === tgt || !isDate(k.by)) { o.reason = 'The record needs a baseline, a different target and a by date.'; return o; }
+  if (!rs.length) { o.reason = 'No reading is recorded yet.'; return o; }
+  const t0 = isDate(k.start) ? ms(k.start) : ms(rs[0].at);
+  const t1 = ms(k.by);
+  const frac = t1 > t0 ? Math.max(0, Math.min(1, (ms(today) - t0) / (t1 - t0))) : 1;
+  const span = tgt - base;
+  const now = rs[rs.length - 1].v;
+  const expected = base + span * frac;
+  const shortfall = (expected - now) / Math.abs(span) * Math.sign(span);
+  o.now = r2(now); o.expected = r2(expected); o.shortfall = r2(shortfall);
+  if (rs.length >= 2) {
+    const a = rs[0]; const b = rs[rs.length - 1];
+    const dt = (ms(b.at) - ms(a.at)) / DAY;
+    if (dt > 0) o.forecast = r2(b.v + (b.v - a.v) / dt * ((t1 - ms(b.at)) / DAY));
+  }
+  o.status = shortfall >= OFF ? 'off' : shortfall >= EARLY ? 'drift' : 'ok';
+  // the pivot rule of scripts/calendar-model.js: at least 3 readings, each behind the line by the early-warning share, and the gap is not closing
+  if (rs.length >= 3) {
+    const sf = rs.map((x) => { const f = t1 > t0 ? Math.max(0, Math.min(1, (ms(x.at) - t0) / (t1 - t0))) : 1; return (base + span * f - x.v) / Math.abs(span) * Math.sign(span); });
+    o.pivot = sf.every((v) => v >= EARLY) && sf[sf.length - 1] >= sf[0];
+  }
+  return o;
+}
+
+/** The north star: monthly points from the first reading to the by date (plan), the readings (actual) and the slope (proj). */
+function northOf(k, o, today) {
+  if (!k || !o || !o.readings.length || o.start === null || o.target === null) return null;
+  const rs = o.readings;
+  const t0 = isDate(k.start) ? ms(k.start) : ms(rs[0].at); const t1 = ms(k.by);
+  const i0 = monthIdx(monthKey(t0)); const i1 = Math.max(monthIdx(monthKey(t1)), monthIdx(today.slice(0, 7)));
+  const byMonth = new Map(); rs.forEach((x) => byMonth.set(x.at.slice(0, 7), x.v));
+  const nowI = monthIdx(rs[rs.length - 1].at.slice(0, 7));
+  const last = rs[rs.length - 1].v;
+  const back = [...byMonth.entries()].filter(([m]) => monthIdx(m) >= nowI - 3 && monthIdx(m) < nowI).sort();
+  const slope = back.length ? (last - back[0][1]) / (nowI - monthIdx(back[0][0])) : null;
+  const pts = [];
+  for (let i = i0; i <= i1; i++) {
+    const key = keyOfIdx(i); const tm = Date.UTC(Math.floor(i / 12), i % 12, 1);
+    const f = t1 > t0 ? Math.max(0, Math.min(1, (tm - t0) / (t1 - t0))) : 1;
+    pts.push({ at: key, actual: byMonth.has(key) ? r2(byMonth.get(key)) : null, plan: r2(o.start + (o.target - o.start) * f), proj: slope !== null && i >= nowI ? r2(last + slope * (i - nowI)) : null });
+  }
+  return { label: o.name, unit: o.unit, now: keyOfIdx(nowI), points: pts, by: k.by };
+}
+
+/** Signals: open rule trips, then the KR-derived ones. */
+function signalsOf(outcomes, sig, readingsByMetric) {
+  const out = [];
+  const SEV = { watch: 'watch', act: 'drift', critical: 'pivot' };
+  for (const t of (sig && sig.open) || []) {
+    const rule = ((sig.rules) || []).find((r) => r.id === t.rule_id) || {};
+    const series = (readingsByMetric[t.reading.metric] || []).slice(-8);
+    out.push({ id: 'rule:' + t.rule_id, sev: SEV[t.severity] || 'watch', t: t.reading.metric + ' ' + t.op + ' ' + t.threshold, ev: 'The latest reading is ' + t.reading.value + (t.reading.at ? ' on ' + String(t.reading.at).slice(0, 10) : '') + '.',
+      thr: 'Rule ' + (rule.id || t.rule_id) + ': severity ' + t.severity, ttt: 'tripped', sp: series, source: 'signal rule' });
+  }
+  for (const o of outcomes) {
+    if (o.status === 'unscored') continue;
+    const sp = o.readings.map((x) => x.v).slice(-8);
+    const u = o.unit.trim();
+    if (o.pivot) out.push({ id: 'kr:' + o.id, sev: 'pivot', t: o.name + ' has been behind the line three readings in a row', ev: 'Now ' + o.now + u + ' against ' + o.expected + u + ' expected today, and the gap is not closing.', thr: 'Pivot rule: 3 readings behind the line and not closing', ttt: 'tripped', sp, source: 'KR metric' });
+    else if (o.status === 'drift' || o.status === 'off') out.push({ id: 'kr:' + o.id, sev: 'drift', t: o.name + ' is behind its line', ev: 'Now ' + o.now + u + ' against ' + o.expected + u + ' expected today' + (o.forecast !== null ? '. At this slope it lands at ' + o.forecast + u + '.' : '.'), thr: 'Early warning: behind the line by 10 percent of the span', ttt: '', sp, source: 'KR metric' });
+    else if (o.shortfall <= -EARLY) out.push({ id: 'kr:' + o.id, sev: 'up', t: o.name + ' is ahead of its line', ev: 'Now ' + o.now + u + ' against ' + o.expected + u + ' expected today.', thr: 'Ahead of the line by 10 percent of the span', ttt: '', sp, source: 'KR metric' });
+  }
+  return out;
+}
+
+function synergyOf(krs, bets) {
+  if (!bets.length) return null;
+  const cols = krs.map((k) => ({ id: k.rid, n: String(k.metric || k.rid), icon: 'target' }));
+  const hit = (b, c) => !!b.parent_kr && (String(b.parent_kr) === c.id || String(b.parent_kr) === c.n);
+  const rows = bets.slice().sort((a, b) => a.rank - b.rank).map((b) => ({ id: b.rid, title: String(b.title), parked: b.horizon === 'later', weights: cols.map((c) => (hit(b, c) ? 1 : 0)), initiative: b.initiative || null }));
+  const notes = [];
+  cols.forEach((c, j) => { if (!rows.some((r) => !r.parked && r.weights[j] > 0)) notes.push({ icon: 'alert', tone: 'bad', text: c.n + ' has no active bet.' }); });
+  rows.forEach((r) => { if (!r.weights.some((w) => w > 0)) notes.push({ icon: 'info', tone: 'warn', text: r.title + ' is not anchored to a KR metric, so it adds to no outcome.' }); });
+  return { columns: cols, rows, notes, unit: 'key results' };
+}
+
+function timelineOf(bets, hyps, today) {
+  if (!bets.length && !hyps.length) return null;
+  const y = Number(today.slice(0, 4)); const q0 = Math.floor((Number(today.slice(5, 7)) - 1) / 3);
+  const qs = [0, 1, 2, 3].map((i) => { const qi = q0 + i; return { y: y + Math.floor(qi / 4), q: qi % 4 }; });
+  const labels = qs.map((x) => 'Q' + (x.q + 1) + " '" + String(x.y).slice(2));
+  const rows = bets.slice().sort((a, b) => a.rank - b.rank).map((b) => ({ id: b.rid, title: String(b.title), sub: b.parent_kr ? String(b.parent_kr) : '', initiative: b.initiative || null, st: 'none',
+    cells: ['', '', '', ''].map((_, i) => (b.horizon === 'now' && i === 0 ? 'c' : b.horizon === 'next' && i === 1 ? 'c' : b.horizon === 'later' && i === 2 ? 'l' : '')) }));
+  const cps = [];
+  hyps.filter((h) => isDate(h.review_by)).forEach((h) => {
+    const d = h.review_by.slice(0, 10); const dy = Number(d.slice(0, 4)); const dq = Math.floor((Number(d.slice(5, 7)) - 1) / 3);
+    const idx = qs.findIndex((x) => x.y === dy && x.q === dq);
+    if (idx < 0) return;
+    const qs0 = Date.UTC(dy, dq * 3, 1); const qe = Date.UTC(dy, dq * 3 + 3, 1);
+    cps.push({ q: idx, f: Math.round((ms(d) - qs0) / (qe - qs0) * 100) / 100, at: d, label: String(h.title) + ', ' + d });
+  });
+  return { quarters: labels, rows, checkpoints: cps.sort((a, b) => a.at.localeCompare(b.at)) };
+}
+
+/** The pure builder: (recordsDir, signalsFile, today) -> body. */
+function build(root, signalsFile, today) {
+  const krs = records.list(root, 'kr-metrics');
+  const bets = records.list(root, 'bets');
+  const hyps = records.list(root, 'hypotheses');
+  const outcomes = krs.map((k) => outcomeOf(k, today));
+  const nk = krs.find((k) => k.north_star === true || k.north_star === 'true');
+  const north = nk ? northOf(nk, outcomes.find((o) => o.id === nk.rid), today) : null;
+  let lines = []; try { lines = fs.existsSync(signalsFile) ? ledger.read(signalsFile) : []; } catch { lines = []; }
+  const sig = sigRules.foldSignals(lines);
+  const byMetric = {};
+  lines.filter((l) => l && l.kind === 'signal_reading').forEach((l) => { (byMetric[l.metric] = byMetric[l.metric] || []).push(Number(l.value)); });
+  return { ok: true, today, north, outcomes: outcomes.map((o) => { const { readings, pivot, shortfall, ...rest } = o; return { ...rest, pivot: !!pivot, shortfall, n_readings: readings.length }; }),
+    signals: signalsOf(outcomes, sig, byMetric), synergy: synergyOf(krs, bets), timeline: timelineOf(bets, hyps, today), maturity: null,
+    sources: { kr_metrics: krs.length, bets: bets.length, hypotheses: hyps.length, signal_rules: sig.rules.length } };
+}
+
+const todayStr = () => { const d = new Date(); return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate()); };
+
+module.exports = {
+  prefixes: ['/api/c3-strategy'],
+  build, outcomeOf, northOf, signalsOf, synergyOf, timelineOf,
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/c3-strategy') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    try {
+      const body = build(rootOf(ctx), path.join(ctx.runtimeDir || '.', 'signals', 'signals.jsonl'), todayStr());
+      ctx.json(res, body, 200);
+    } catch (e) { ctx.json(res, { ok: false, error: String(e && e.message || e) }, 500); }
+    return true;
+  },
+};

package/workspace/lib/routes-c3-timeline.js

@@ -0,0 +1,191 @@
+'use strict';
+/* routes-c3-timeline.js — the data of the Initiatives Timeline of /c3.html: every check of the plan as a whole frame. READ ONLY.
+ *
+ *   GET /api/c3-timeline?initiative=<id>[&ws=<id>]
+ *        → { ok, initiative, today, checks:[{check,date,label}], frames:[ { check, date, label, items, critical, forecast_end, promised,
+ *            slip_days, points, problems, changes, events } ], sources:{plan,breakdown,jira}, notes:[...] }
+ *   GET /api/c3-timeline?initiatives=a,b,c[&ws=<id>]
+ *        → { ok, today, checks, rows:[{ id, cells:[{ date, forecast_end, promised, slip_days }] }] }   the forecast at each check, per initiative
+ *
+ * ONE Gantt, THREE SOURCES. The frame items are the plan items of the initiative (workspace/lib/plan-items.js ledger), the Breakdown items
+ * (<records>/breakdown-pmos.jsonl, PMOS-only work in Discovery, Design and Launch, with the Jira tickets they wait on) and the Jira tickets of the
+ * initiative (the my-work read). Each frame is the plan as it stood on a check date: the events up to that day folded (scripts/plan-forecast.js
+ * stateAt) and planned with the sample's plan.js (checkFrames). A replay in the page steps through these frames; nothing is fetched per step.
+ *
+ * WHAT IS REAL AND WHAT IS NOT.
+ *   - Plan items: every planned and set line of the ledger carries its dates, owner and dependencies, so a past check shows the dates the plan then
+ *     held. An agent-proposed item enters the plan on the day it was kept. The ledger records no reason for a change; `why` is left empty.
+ *   - Breakdown items: the store has no dates. An item starts the day it was added and lasts its points in days (1 point = 1 day); it
+ *     waits on the Jira tickets named by its dependency lines. `why` and `by` are the ledger's own.
+ *   - Jira tickets: the my-work read gives a due date and no history, so a ticket is drawn on its due day at EVERY check (events marked
+ *     `synthetic`, which never make a check of their own) and no dependencies between tickets are known.
+ * Checks are the days the plan changed (the first is the baseline) and today; at most six. No write route exists.
+ */
+const path = require('path');
+const planItems = require('./plan-items.js');
+const F = require('../../scripts/plan-forecast.js');
+const roadmapOps = require('./routes-roadmap-ops.js');
+const breakdown = require(path.join(__dirname, '..', '..', 'scripts', 'breakdown-ops.js'));
+
+const localYmd = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+const DAY = 86400000;
+const addDays = (s, n) => new Date(Date.parse(s + 'T00:00:00Z') + n * DAY).toISOString().slice(0, 10);
+const FAR_PAST = '1970-01-01T00:00:00.000Z';
+const SRC_LABEL = { local: 'Local', figma: 'Figma', calendar: 'Calendar', gmail: 'Gmail', notes: 'Notes' };
+
+/** Plan items of one initiative → events. `live` = the fold's live items (not proposed, not withdrawn), `lines` = the raw ledger lines. */
+function planEvents(lines, live, initiative) {
+  const out = [];
+  const by = new Map();
+  for (const l of lines || []) {
+    const r = l.rec;
+    if (!r || !r.item || !live.has(r.item)) continue;
+    if (!by.has(r.item)) by.set(r.item, []);
+    by.get(r.item).push(r);
+  }
+  for (const [id, recs] of by) {
+    const it = live.get(id);
+    if (it.initiative !== initiative) continue;
+    recs.sort((a, b) => (String(a.at) < String(b.at) ? -1 : String(a.at) > String(b.at) ? 1 : 0));
+    const planned = recs.find((r) => r.ev === 'planned');
+    if (!planned) continue;
+    const keptAt = it.kept ? ((it.history || []).filter((h) => h.ev === 'kept').map((h) => h.at).sort()[0] || planned.at) : planned.at;
+    const enter = String(keptAt) > String(planned.at) ? keptAt : planned.at;
+    const f = { title: planned.title, start: planned.start || null, due: planned.due || null, after: planned.after || [], owner: planned.owner || null,
+      ms: planned.milestone === true, phase: planned.stage || null, state: 'todo', origin: 'plan', src: 'Plan', key: null, points: typeof planned.points === 'number' ? planned.points : undefined };
+    const later = [];
+    for (const r of recs) {
+      if (r === planned || r.ev === 'kept' || r.ev === 'flagged' || r.ev === 'withdrawn') continue;
+      const fields = r.ev === 'set' ? mapSet(r.fields) : r.ev === 'moved' ? { state: r.to } : null;
+      if (!fields) continue;
+      if (String(r.at) <= String(enter)) Object.assign(f, fields);          // before it entered the plan: part of how it entered
+      else later.push({ at: r.at, id, op: 'set', fields, by: r.by, why: r.note || '' });
+    }
+    out.push({ at: enter, id, op: 'add', fields: f, by: planned.by, why: planned.note || '' }, ...later);
+  }
+  return out;
+}
+function mapSet(fs) {
+  const o = {};
+  for (const k of Object.keys(fs || {})) {
+    if (k === 'milestone') o.ms = fs[k];
+    else if (k === 'stage') o.phase = fs[k];
+    else if (['title', 'owner', 'after', 'start', 'due'].includes(k)) o[k] = fs[k];
+  }
+  return o;
+}
+
+/** Breakdown lines → events (add, edit, dependency, delete, undo), for the items of one initiative. */
+function breakdownEvents(lines, initiative) {
+  const out = [];
+  const deps = new Map(); const mine = new Set(); const deleted = new Map(); const keyOf = new Map();
+  const dateOf = (e) => String(e.at || '').slice(0, 10);
+  const shape = (rid, f, at) => {
+    const pts = typeof f.points === 'number' && f.points > 0 ? f.points : 1;
+    const start = f.start || dateOf({ at });
+    return { title: f.title, start, due: f.due || addDays(start, Math.max(1, Math.ceil(pts)) - 1), owner: f.owner || null, points: pts, after: [...(deps.get(rid) || [])],
+      phase: f.phase || null, state: f.done ? 'done' : 'todo', origin: 'breakdown', src: SRC_LABEL[f.source] || 'Local', key: keyOf.get(rid) };
+  };
+  for (const e of lines || []) {
+    if (!e || !e.rid) continue;
+    if (e.kind === 'add') {
+      if ((e.fields || {}).initiative !== initiative) continue;
+      mine.add(e.rid); deps.set(e.rid, []); keyOf.set(e.rid, 'PM-' + (keyOf.size + 1));
+      out.push({ at: e.at, id: e.rid, op: 'add', fields: shape(e.rid, e.fields, e.at), by: e.by, why: e.why || '' });
+    } else if (!mine.has(e.rid)) continue;
+    else if (e.kind === 'edit') {
+      const f = e.fields || {}; const set = {};
+      if ('title' in f) set.title = f.title;
+      if ('owner' in f) set.owner = f.owner || null;
+      if ('phase' in f) set.phase = f.phase;
+      if ('source' in f) set.src = SRC_LABEL[f.source] || 'Local';
+      if ('points' in f) { const pts = typeof f.points === 'number' && f.points > 0 ? f.points : 1; set.points = pts; }
+      if ('done' in f) set.state = f.done ? 'done' : 'todo';
+      out.push({ at: e.at, id: e.rid, op: 'set', fields: set, by: e.by, why: e.why || '' });
+    } else if (e.kind === 'dependency' && e.fields && e.fields.jira) {
+      const cur = deps.get(e.rid) || [];
+      deps.set(e.rid, e.fields.remove ? cur.filter((d) => d !== e.fields.jira) : [...new Set([...cur, e.fields.jira])]);
+      out.push({ at: e.at, id: e.rid, op: 'set', fields: { after: [...deps.get(e.rid)] }, by: e.by, why: e.why || '' });
+    } else if (e.kind === 'delete') {
+      deleted.set(e.id, e.snapshot || null);
+      out.push({ at: e.at, id: e.rid, op: 'remove', fields: {}, by: e.by, why: e.why || '' });
+    } else if (e.kind === 'undo' && deleted.has(e.corrects)) {
+      const snap = deleted.get(e.corrects) || {};
+      out.push({ at: e.at, id: e.rid, op: 'add', fields: shape(e.rid, snap, e.at), by: e.by, why: e.why || 'restored' });
+    }
+  }
+  return out;
+}
+
+/** Jira tickets of the initiative → events with no history: present at every check (`synthetic`). */
+function jiraEvents(items, initiative, today) {
+  const out = [];
+  for (const j of items || []) {
+    if (j.source !== 'jira' || j.initiative !== initiative) continue;
+    const due = j.due || today;
+    out.push({ at: FAR_PAST, synthetic: true, id: j.key, op: 'add', by: 'Jira', why: '',
+      fields: { title: j.title, start: due, due, after: [], owner: null, points: undefined, state: j.category === 'done' ? 'done' : j.category === 'doing' ? 'doing' : 'todo',
+        origin: 'jira', src: 'Jira', key: j.key, url: j.url || null, status: j.status || null, undated: !j.due } });
+  }
+  return out;
+}
+
+/** The whole answer for one initiative from already-read inputs (pure: the tests call it with fixtures). */
+function buildOne({ planLines, planLive, breakdownLines, jira, initiative, today, checks }) {
+  const ev = [...planEvents(planLines, planLive, initiative), ...breakdownEvents(breakdownLines, initiative), ...jiraEvents(jira, initiative, today)];
+  const cks = checks || F.pickChecks(ev, today, 6);
+  const frames = F.checkFrames(ev, cks, today);
+  const count = (o) => ev.filter((e) => e.op === 'add' && e.fields.origin === o).length;
+  const notes = [];
+  if (count('jira')) notes.push('Jira keeps no history here: its tickets are drawn on their due day at every check.');
+  if (count('breakdown')) notes.push('Breakdown items have no dates: each starts the day it was added and lasts one day per point.');
+  return { events: ev, checks: cks, frames, sources: { plan: count('plan'), breakdown: count('breakdown'), jira: count('jira') }, notes };
+}
+
+function readInputs(w, ctx, now) {
+  const fold = planItems.readFold(w.root, { now });
+  const live = new Map(Object.values(fold.items).filter((it) => !it.proposed).map((it) => [it.id, it]));
+  const lines = planItems.readLines(w.root).lines;
+  let bd = [];
+  try { bd = breakdown.readLines(roadmapOps.rootOf(ctx)); } catch { bd = []; }
+  let jira = [];
+  try { jira = require('./routes-my-work.js').listFor(ctx, now).items.filter((i) => i.source === 'jira'); } catch { jira = []; }
+  return { planLines: lines, planLive: live, breakdownLines: bd, jira };
+}
+
+function build(w, ctx, q, now) {
+  const today = localYmd(new Date(now));
+  const inp = readInputs(w, ctx, now);
+  if (q.initiative) {
+    const r = buildOne({ ...inp, initiative: q.initiative, today });
+    return { ok: true, initiative: q.initiative, today, checks: r.checks, frames: r.frames, sources: r.sources, notes: r.notes };
+  }
+  const ids = String(q.initiatives || '').split(',').map((s) => s.trim()).filter(Boolean).slice(0, 40);
+  const per = ids.map((id) => ({ id, ...buildOne({ ...inp, initiative: id, today }) }));
+  const dates = [...new Set(per.flatMap((p) => p.events.filter((e) => !e.synthetic).map((e) => String(e.at).slice(0, 10))))].sort();
+  const checks = F.pickChecks(dates.map((d) => ({ at: d + 'T00:00:00Z', id: d, op: 'set', fields: {} })), today, 6);
+  const rows = per.map((p) => {
+    const fr = F.checkFrames(p.events, checks, today);
+    return { id: p.id, cells: fr.map((f) => (f.items.length ? { date: f.date, forecast_end: f.forecast_end, promised: f.promised, slip_days: f.slip_days } : null)) };
+  });
+  return { ok: true, today, checks, rows };
+}
+
+module.exports = {
+  prefixes: ['/api/c3-timeline'],
+  planEvents, breakdownEvents, jiraEvents, buildOne, build,
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/c3-timeline') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only: the timeline is derived, and plan changes go through the plan-items writer' }, 405); return true; }
+    const initiative = String(url.searchParams.get('initiative') || '');
+    const initiatives = String(url.searchParams.get('initiatives') || '');
+    if (!initiative && !initiatives) { ctx.json(res, { ok: false, error: 'initiative or initiatives is required' }, 400); return true; }
+    const w = ctx.getWs(String(url.searchParams.get('ws') || ''));
+    if (!w || !w.root) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    let out;
+    try { out = build(w, ctx, { initiative, initiatives }, Date.now()); }
+    catch (e) { out = { ok: false, status: 500, error: 'the timeline could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }; }
+    ctx.json(res, out, out.ok ? 200 : out.status || 500);
+    return true;
+  },
+};

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

@@ -0,0 +1,60 @@
+'use strict';
+/* routes-calendar-import.js — cached calendar events, supplied by a session (console3 wave E2a).
+ *
+ *   GET  /api/calendar-import/events → { ok, events }           the folded cache
+ *   POST /api/calendar-import/events { events, sensitivity }    → { ok, count }   page press; sensitivity is required
+ *   POST /api/calendar-import/note   { event_id, text }         → { ok }          the PM's note on an event
+ *
+ * Nothing here fetches a calendar: PMOS holds no credentials. Events come in the body. Imports are untrusted data
+ * (scripts/calendar-import.js through scripts/trust/import-guard.js). Writes pass pm-guard requirePagePress, so an agent
+ * token is refused (403). readEvents(runtimeDir) is for routes-calendar-views.js.
+ * File: <runtime>/calendar-import/events.jsonl (append only, scripts/trust/ledger.js). */
+const path = require('path');
+const guard = require('./pm-guard.js');
+const CI = require('../../scripts/calendar-import.js');
+const L = require('../../scripts/trust/ledger.js');
+
+const fileOf = (runtimeDir) => path.join(runtimeDir, 'calendar-import', 'events.jsonl');
+const fail = (status, error) => ({ status, body: { ok: false, error } });
+
+function readEvents(runtimeDir) { return CI.foldEvents(CI.readLines(fileOf(runtimeDir))); }
+
+function list(runtimeDir) { return { status: 200, body: { ok: true, events: readEvents(runtimeDir) } }; }
+
+function importRoute(req, body, runtimeDir, now = new Date()) {
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) return fail(g.status, g.error);
+  let evs;
+  try { evs = CI.importEvents(body.events, { fetchedAt: now.toISOString(), sensitivity: body.sensitivity }); }
+  catch (e) { return fail(400, e.message); }
+  try { CI.appendImport(fileOf(runtimeDir), evs, L.actorFrom({ ui: true }), now.toISOString()); }
+  catch (e) { return fail(500, e.message); }
+  return { status: 200, body: { ok: true, count: evs.length } };
+}
+
+function noteRoute(req, body, runtimeDir, now = new Date()) {
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) return fail(g.status, g.error);
+  if (!readEvents(runtimeDir).some((e) => e.id === body.event_id)) return fail(404, 'no such event');
+  try { CI.appendNote(fileOf(runtimeDir), body.event_id, body.text, L.actorFrom({ ui: true }), now.toISOString()); }
+  catch (e) { return fail(400, e.message); }
+  return { status: 200, body: { ok: true } };
+}
+
+const ROUTES = { 'POST /api/calendar-import/events': importRoute, 'POST /api/calendar-import/note': noteRoute };
+
+module.exports = {
+  prefixes: ['/api/calendar-import'],
+  readEvents, list, importRoute, noteRoute, ROUTES, fileOf,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p === '/api/calendar-import/events' && req.method === 'GET') { const r = list(ctx.runtimeDir); ctx.json(res, r.body, r.status); return true; }
+    const fn = ROUTES[`${req.method} ${p}`];
+    if (!fn) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const r = fn(req, got.body || {}, ctx.runtimeDir);
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};

package/workspace/lib/routes-calendar-views.js

@@ -0,0 +1,61 @@
+'use strict';
+/* routes-calendar-views.js — GET /api/calendar-views?view=day|week|month|quarter|year&date=YYYY-MM-DD&ws=<id> (console3 wave C2).
+ *
+ *   → { ok, view, range, cells, unit, gantt, strategy, events_source }
+ *
+ * READ ONLY. Initiatives come from the signal engine's repo reader (scripts/signals/facts.js readRepoFacts), required inside
+ * the handler so a failure answers 500 { ok:false } and never reaches the server. The date and the plan come from the records:
+ * the planned end is the promised date, the planned start is that date minus planned_days; no forecast is invented, so an
+ * initiative without one shows as 'no plan' (or 'overdue' past its promise).
+ *
+ * EVENTS: lib/calendar-memory.js has validate, merge and month functions only; no reader of the stored calendar is exported.
+ * Until one is, events = [] and events_source is 'none'. KRS: no KR metric series is stored in the repo, so the strategy lens
+ * gets none and says so. */
+const path = require('path');
+const model = require('../../scripts/calendar-model.js');
+
+const today = () => { const d = new Date(); const p = (n) => String(n).padStart(2, '0'); return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`; };
+
+/** The pure handler. deps: { readFacts(root), readEvents?(range), readKrs?(), today } so tests need no repo. */
+function handle(query, deps = {}) {
+  const view = (query && query.view) || 'month';
+  const date = (query && query.date) || (deps.today || today());
+  if (!model.VIEWS.includes(view)) return { status: 400, body: { ok: false, error: 'view must be one of ' + model.VIEWS.join(', ') } };
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || Number.isNaN(Date.parse(date + 'T00:00:00Z'))) return { status: 400, body: { ok: false, error: 'date must be YYYY-MM-DD' } };
+  try {
+    const facts = deps.readFacts ? deps.readFacts() : { inis: [] };
+    const inis = facts.inis || [];
+    const range = model.rangeFor(view, date);
+    let events = []; let source = 'none';
+    if (typeof deps.readEvents === 'function') { events = deps.readEvents(range) || []; source = 'calendar-memory'; }
+    const krs = typeof deps.readKrs === 'function' ? deps.readKrs() : [];
+    const b = model.bucketEvents(events, view, date);
+    const nowDay = deps.today || today();
+    const gantt = model.ganttRows(inis, view, date, { today: nowDay });
+    const strategy = view === 'quarter' || view === 'year' ? model.strategyLens(inis, krs, nowDay) : null;
+    return { status: 200, body: { ok: true, view, range, unit: b.unit, cells: b.cells, gantt, strategy, events_source: source, today: nowDay } };
+  } catch (e) {
+    return { status: 500, body: { ok: false, error: String(e && e.message || e) } };
+  }
+}
+
+module.exports = {
+  prefixes: ['/api/calendar-views'],
+  handlePure: handle,
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/calendar-views') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    const w = ctx.getWs(url.searchParams.get('ws'));
+    if (!w) { ctx.json(res, { ok: false, error: 'no workspace is registered' }, 404); return true; }
+    const root = path.resolve(w.root);
+    let facts;
+    try { facts = await require('./facts-async.js').readFactsAsync(root); }
+    catch (e) { ctx.json(res, { ok: false, error: 'the calendar could not read the repository: ' + (e && e.message ? e.message : String(e)) }, 500); return true; }
+    const out = handle({ view: url.searchParams.get('view') || undefined, date: url.searchParams.get('date') || undefined }, {
+      readFacts: () => facts,
+      readEvents: () => require('./routes-calendar-import.js').readEvents(ctx.runtimeDir),
+    });
+    ctx.json(res, out.body, out.status);
+    return true;
+  },
+};

package/workspace/lib/routes-doc-health.js

@@ -0,0 +1,79 @@
+'use strict';
+/* routes-doc-health.js — console3 wave B2: document health, read side.
+ *
+ *   POST /api/doc-health/check { path, ws?, context? } → { ok, path, health }   health = scripts/doc-health.js healthOf
+ *
+ * A read: nothing is written and no page press is needed. The file is read from the repository (or the named workspace's
+ * root) and refused when it resolves outside that root. From git it derives: the last change of the file, the last change
+ * of every relative Markdown link it cites, and the last change of each ADR a `D<n>` id in its text names. Everything
+ * else (requiredHeadings, data, readers, current, staleAfterDays) comes only from `context` in the body; a check without
+ * its input answers "not enough input". No write routes in this wave.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const H = require('../../scripts/doc-health.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const bad = (error, status = 400) => ({ status, body: { ok: false, error } });
+
+function inside(root, full) {
+  try {
+    const r = fs.realpathSync(root), f = fs.realpathSync(full);
+    return f === r || f.startsWith(r + path.sep);
+  } catch { return false; }
+}
+function gitChanged(root, rel) {
+  const r = spawnSync('git', ['log', '-1', '--format=%cI', '--', rel], { cwd: root, encoding: 'utf8' });
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+function adrFor(root, id) {
+  const dir = path.join(root, 'okf/products/pmos/adr');
+  const n = String(id).slice(1);
+  try { return fs.readdirSync(dir).find((f) => new RegExp('^d0*' + n + '-', 'i').test(f)) || null; } catch { return null; }
+}
+
+function check(root, body) {
+  const rel = typeof body.path === 'string' ? body.path : '';
+  if (!rel) return bad('path is required');
+  const full = path.resolve(root, rel);
+  if (!inside(root, path.dirname(full)) || !full.startsWith(path.resolve(root) + path.sep)) return bad('outside workspace', 404);
+  let text;
+  try { if (!inside(root, full)) return bad('outside workspace', 404); text = fs.readFileSync(full, 'utf8'); } catch { return bad('file not found', 404); }
+  const relOut = path.relative(root, full);
+  const changed = gitChanged(root, relOut);
+  const sources = [];
+  for (const m of text.matchAll(/\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g)) {
+    if (/^[a-z]+:/i.test(m[1])) continue;
+    const sp = m[1].startsWith('/') ? m[1].slice(1) : path.relative(root, path.resolve(path.dirname(full), m[1]));
+    if (sp.startsWith('..') || sources.some((s) => s.path === sp)) continue;
+    sources.push({ path: sp, changed: gitChanged(root, sp) });
+  }
+  const decisionChanges = {};
+  for (const id of new Set(text.match(/\bD\d{1,3}\b/g) || [])) {
+    const f = adrFor(root, id);
+    const at = f && gitChanged(root, 'okf/products/pmos/adr/' + f);
+    if (at) decisionChanges[id] = at;
+  }
+  const given = body.context && typeof body.context === 'object' ? body.context : {};
+  const context = { ...given, sources: sources.length ? sources : given.sources,
+    decisionChanges: Object.keys(decisionChanges).length ? decisionChanges : given.decisionChanges };
+  const doc = { text, type: given.type || body.type, changed };
+  return { status: 200, body: { ok: true, path: relOut, health: H.healthOf(doc, context) } };
+}
+
+module.exports = {
+  prefixes: ['/api/doc-health'],
+  check,
+  handle: async (req, res, url, ctx) => {
+    if (req.method !== 'POST' || url.pathname !== '/api/doc-health/check') return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const body = got.body || {};
+    const w = body.ws && ctx.getWs ? ctx.getWs(body.ws) : null;
+    if (body.ws && !w) { ctx.json(res, { ok: false, error: 'no workspace' }, 404); return true; }
+    const r = check(w ? w.root : (ctx.root || ROOT), body);
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};