create-pmos 0.59.2 → 0.60.0

package/workspace/lib/calendar-memory.js

@@ -0,0 +1,257 @@
+'use strict';
+/* lib/calendar-memory.js — the calendar the Agenda remembers (initiative today-goals, PRD G23 to G25).
+ *
+ *   validateMemory(raw, { now })                 → { ok, memory } | { ok:false, error }
+ *   mergeMemory(stored, memory, { now })         → { ok, memory }   the stored file with the submitted window replaced
+ *   seriesKey(e) · normTitle(title)              → the key that joins the occurrences of one meeting
+ *   kindOf(e) · isImportant(e)                   → 'one' | 'onboard' | 'group' · true | false
+ *   agendaMonth({ memory, brief, month, now })   → the month the Agenda draws: weeks, days with their three answers, series
+ *
+ * The morning-brief session reads the calendar wide (90 days back, 31 ahead) and submits it with the brief. The workspace
+ * checks it here and keeps it in one file. Every answer the month gives is derived here, with no model and no I/O:
+ *   how full    minutes in meetings between 09:00 and 18:00 (overlaps merged), and the free blocks of 90 minutes or more;
+ *   key meeting the one meeting of the day that matters, named only when it is important or its prep is at risk;
+ *   readiness   prep done out of prep needed, for the coming occurrence of each meeting; at risk when the free time left
+ *               before the meeting is shorter than 30 minutes for each step left.
+ * Today's events come from the brief when there is one, so a meeting keeps its purpose, prep and steps.
+ */
+
+const crypto = require('crypto');
+
+const MAX_EVENTS = 1000;
+const MAX_SPAN_DAYS = 140;
+const KEEP_BACK_DAYS = 100;
+const KEEP_AHEAD_DAYS = 45;
+const ROLES = ['present', 'decide', 'attend'];
+const DAY_START = 9 * 60;
+const DAY_END = 18 * 60;
+const FREE_BLOCK = 90;        // a free block worth naming, in minutes
+const PER_STEP = 30;          // minutes a prep step needs
+const PER_DAY = 60;           // minutes of a whole working day before the meeting that count toward its prep
+const ROUTINE_COUNT = 4;      // a group series seen this often, with nothing for the PM, is routine
+const DAY_MS = 86400000;
+
+const sha12 = (s) => crypto.createHash('sha1').update(s).digest('hex').slice(0, 12);
+const pad = (n) => String(n).padStart(2, '0');
+const localDate = (t) => { const d = new Date(t); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; };
+const minuteOfDay = (t) => { const d = new Date(t); return d.getHours() * 60 + d.getMinutes(); };
+const isDate = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(s) && !Number.isNaN(Date.parse(s));
+const dayStartMs = (date) => { const [y, m, d] = date.split('-').map(Number); return new Date(y, m - 1, d).getTime(); };
+const addDays = (date, n) => { const [y, m, d] = date.split('-').map(Number); return localDate(new Date(y, m - 1, d + n).getTime()); };
+const weekday = (date) => { const [y, m, d] = date.split('-').map(Number); return new Date(y, m - 1, d).getDay(); };   // 0 Sunday
+const tooLong = (s, n) => typeof s === 'string' && s.length > n;
+const str = (v, n) => typeof v === 'string' && v.trim() && v.length <= n;
+
+/** The title without numbers and counting words, so "Onboarding: Priya, week 2" and "… week 3" are one meeting. */
+function normTitle(title) {
+  return String(title || '').toLowerCase()
+    .replace(/\b(week|wk|day|session|part|round|sprint|no|#)\s*\d+\b/g, ' ')
+    .replace(/\d+/g, ' ')
+    .replace(/[^a-zÀ-ɏ]+/g, ' ')
+    .replace(/\s+/g, ' ').trim();
+}
+function seriesKey(e) { return e && e.series ? 's:' + e.series : 't:' + normTitle(e && e.title); }
+
+function kindOf(e) {
+  const t = String((e && e.title) || '');
+  if (/onboard/i.test(t)) return 'onboard';
+  if ((e && e.attendees === 2) || /\b1\s*[:/-]\s*1\b|one[- ]on[- ]one/i.test(t)) return 'one';
+  return 'group';
+}
+function isImportant(e) {
+  return !!e && (e.role === 'present' || e.role === 'decide' || e.external === true || e.exec === true || (typeof e.attendees === 'number' && e.attendees >= 8));
+}
+
+/* ── the check ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function validateMemory(raw, { now = Date.now() } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: 'memory is an object: {"from", "to", "events"}' };
+  if (!isDate(raw.from) || !isDate(raw.to)) return { ok: false, error: 'memory needs "from" and "to" as YYYY-MM-DD' };
+  if (raw.from > raw.to) return { ok: false, error: 'memory "from" is after "to"' };
+  const span = Math.round((dayStartMs(raw.to) - dayStartMs(raw.from)) / DAY_MS) + 1;
+  if (span > MAX_SPAN_DAYS) return { ok: false, error: `memory covers ${span} days — at most ${MAX_SPAN_DAYS}` };
+  if (!Array.isArray(raw.events)) return { ok: false, error: 'memory "events" must be a list' };
+  if (raw.events.length > MAX_EVENTS) return { ok: false, error: `memory has ${raw.events.length} events — at most ${MAX_EVENTS}` };
+  const events = [];
+  const ids = new Set();
+  for (let i = 0; i < raw.events.length; i++) {
+    const e = raw.events[i];
+    const at = `memory event ${i + 1}`;
+    if (!e || typeof e !== 'object' || Array.isArray(e)) return { ok: false, error: `${at} is not an object` };
+    if (!str(e.title, 120)) return { ok: false, error: `${at} needs a title of at most 120 characters` };
+    const s = Date.parse(e.start);
+    if (typeof e.start !== 'string' || Number.isNaN(s)) return { ok: false, error: `${at}: start must be a date and time` };
+    const f = e.end === undefined ? s + 30 * 60000 : Date.parse(e.end);
+    if (e.end !== undefined && (typeof e.end !== 'string' || Number.isNaN(f))) return { ok: false, error: `${at}: end must be a date and time` };
+    if (f < s) return { ok: false, error: `${at}: end is before start` };
+    const day = localDate(s);
+    if (day < raw.from || day > raw.to) return { ok: false, error: `${at}: ${day} is outside the window ${raw.from} to ${raw.to}` };
+    if (e.id !== undefined) return { ok: false, error: `${at}: id is derived by the workspace — do not give one` };
+    if (e.series !== undefined && !str(e.series, 200)) return { ok: false, error: `${at}: series is a text of at most 200 characters` };
+    if (e.attendees !== undefined && !(Number.isInteger(e.attendees) && e.attendees >= 0 && e.attendees <= 1000)) return { ok: false, error: `${at}: attendees is a whole number from 0 to 1000` };
+    for (const b of ['external', 'exec']) if (e[b] !== undefined && typeof e[b] !== 'boolean') return { ok: false, error: `${at}: ${b} is true or false` };
+    if (e.role !== undefined && !ROLES.includes(e.role)) return { ok: false, error: `${at}: role is one of ${ROLES.join(', ')}` };
+    const past = f <= now;
+    if (e.notes !== undefined) {
+      if (!str(e.notes, 240)) return { ok: false, error: `${at}: notes is one line of at most 240 characters` };
+      if (!past) return { ok: false, error: `${at}: notes are for a meeting that has ended` };
+    }
+    if (e.open !== undefined && (!Array.isArray(e.open) || e.open.length > 3 || e.open.some((x) => !str(x, 140)))) return { ok: false, error: `${at}: open is a list of at most 3 lines of at most 140 characters` };
+    if (e.prep !== undefined) {
+      if (!Array.isArray(e.prep) || e.prep.length > 6 || e.prep.some((x) => !str(x, 140))) return { ok: false, error: `${at}: prep is a list of at most 6 steps of at most 140 characters` };
+      if (past) return { ok: false, error: `${at}: prep is for a meeting that has not ended` };
+    }
+    if (e.prep_done !== undefined && !(Number.isInteger(e.prep_done) && e.prep_done >= 0 && e.prep_done <= (e.prep || []).length)) return { ok: false, error: `${at}: prep_done is a whole number from 0 to the number of prep steps` };
+    const title = e.title.trim();
+    const id = sha12(`${new Date(s).toISOString()}|${title}`);
+    if (ids.has(id)) return { ok: false, error: `${at}: two events have the same start and title` };
+    ids.add(id);
+    const out = { id, start: new Date(s).toISOString(), end: new Date(f).toISOString(), title };
+    for (const k of ['series', 'attendees', 'external', 'exec', 'role', 'notes', 'open', 'prep', 'prep_done']) if (e[k] !== undefined) out[k] = e[k];
+    events.push(out);
+  }
+  events.sort((a, b) => Date.parse(a.start) - Date.parse(b.start));
+  return { ok: true, memory: { from: raw.from, to: raw.to, events } };
+}
+
+/** The stored memory with the days of the submitted window replaced, trimmed to 100 days back and 45 ahead. */
+function mergeMemory(stored, memory, { now = Date.now() } = {}) {
+  const old = stored && Array.isArray(stored.events) ? stored.events : [];
+  const keepFrom = localDate(now - KEEP_BACK_DAYS * DAY_MS);
+  const keepTo = localDate(now + KEEP_AHEAD_DAYS * DAY_MS);
+  const inWindow = (e) => { const d = localDate(Date.parse(e.start)); return d >= memory.from && d <= memory.to; };
+  const kept = old.filter((e) => !inWindow(e));
+  const events = [...kept, ...memory.events]
+    .filter((e) => { const d = localDate(Date.parse(e.start)); return d >= keepFrom && d <= keepTo; })
+    .sort((a, b) => Date.parse(a.start) - Date.parse(b.start));
+  const from = [stored && stored.from, memory.from].filter(Boolean).sort()[0];
+  const to = [stored && stored.to, memory.to].filter(Boolean).sort().pop();
+  return { ok: true, memory: { from: from < keepFrom ? keepFrom : from, to: to > keepTo ? keepTo : to, updated_at: new Date(now).toISOString(), events } };
+}
+
+/* ── the month ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Minutes in meetings inside the working day, overlaps merged, and the free blocks of FREE_BLOCK minutes or more. */
+function dayLoad(evs) {
+  const iv = evs.map((e) => [Math.max(DAY_START, e.from), Math.min(DAY_END, e.to)]).filter(([a, b]) => b > a).sort((a, b) => a[0] - b[0]);
+  const merged = [];
+  for (const [a, b] of iv) { const last = merged[merged.length - 1]; if (last && a <= last[1]) last[1] = Math.max(last[1], b); else merged.push([a, b]); }
+  const busy = merged.reduce((n, [a, b]) => n + b - a, 0);
+  const gaps = [];
+  let c = DAY_START;
+  for (const [a, b] of merged) { if (a - c >= FREE_BLOCK) gaps.push([c, a]); c = Math.max(c, b); }
+  if (DAY_END - c >= FREE_BLOCK) gaps.push([c, DAY_END]);
+  return { busy, merged, gaps };
+}
+/** Free minutes of a day's working hours between `from` and `until` (minutes of the day). */
+function freeBetween(merged, from, until) {
+  const a = Math.max(DAY_START, from); const b = Math.min(DAY_END, until);
+  if (b <= a) return 0;
+  let busy = 0;
+  for (const [s, e] of merged) busy += Math.max(0, Math.min(e, b) - Math.max(s, a));
+  return b - a - busy;
+}
+
+/** A brief event as an agenda event: its steps before are its prep. */
+function fromBrief(e) {
+  const before = (e.steps && Array.isArray(e.steps.before)) ? e.steps.before : [];
+  const prep = before.length ? before.map((x) => String(x.t || '')) : e.prep ? [String(e.prep)] : [];
+  const done = before.filter((x) => x && x.done).length;
+  return { id: e.id, src: 'brief', start: e.start, end: e.end || new Date(Date.parse(e.start) + 30 * 60000).toISOString(), title: e.title,
+    ...(prep.length ? { prep, prep_done: done } : {}), with: e.with || null, goal: e.goal || null };
+}
+
+/**
+ * The month the Agenda draws. `month` is YYYY-MM (default: this month). Weeks run Monday to Sunday. Each day of the month
+ * carries its events and the three answers; `series` describes every series that has an event in the month.
+ */
+function agendaMonth({ memory, brief, month, now = Date.now() } = {}) {
+  const today = localDate(now);
+  const ym = typeof month === 'string' && /^\d{4}-\d{2}$/.test(month) ? month : today.slice(0, 7);
+  const all = ((memory && memory.events) || []).map((e) => ({ ...e, src: 'memory' }));
+  // today's events come from the brief of today when there is one; memory events of today are then left out
+  const b = brief && brief.date === today && Array.isArray(brief.calendar) ? brief.calendar.map(fromBrief) : null;
+  const events = (b ? [...all.filter((e) => localDate(Date.parse(e.start)) !== today), ...b] : all)
+    .map((e) => { const s = Date.parse(e.start); const f = Date.parse(e.end); return { ...e, s, f, date: localDate(s), from: minuteOfDay(s), to: f - s >= DAY_MS ? DAY_END : (localDate(f) === localDate(s) ? minuteOfDay(f) : DAY_END), key: seriesKey(e), kind: kindOf(e), imp: isImportant(e) }; })
+    .sort((x, y) => x.s - y.s);
+
+  // series over everything remembered, so "held 12 of 13" and "the last time" see beyond the month
+  const series = new Map();
+  for (const e of events) {
+    let x = series.get(e.key);
+    if (!x) { x = { key: e.key, title: e.title, kind: e.kind, count: 0, past: 0, coming: 0, dates: [], last: null, coming_id: null }; series.set(e.key, x); }
+    x.count++; x.dates.push(e.date); x.title = e.title;
+    if (e.f <= now) { x.past++; x.last = e; } else { x.coming++; if (!x.coming_id) x.coming_id = e.id; }
+  }
+  const routine = (e) => !e.imp && e.kind === 'group' && (series.get(e.key).count >= ROUTINE_COUNT) && !(e.prep && e.prep.length && series.get(e.key).coming_id === e.id);
+
+  // the days of the calendar grid: from the Monday on or before the 1st to the Sunday on or after the last day
+  const first = ym + '-01';
+  const [yy, mm] = ym.split('-').map(Number);
+  const last = localDate(new Date(yy, mm, 0).getTime());
+  let start = first; while (weekday(start) !== 1) start = addDays(start, -1);
+  let end = last; while (weekday(end) !== 0) end = addDays(end, 1);
+  const byDay = new Map();
+  for (const e of events) { if (e.date < start || e.date > end) continue; if (!byDay.has(e.date)) byDay.set(e.date, []); byDay.get(e.date).push(e); }
+
+  // working-day free time for readiness: today's from now on, later days' whole hours (capped at PER_DAY each)
+  const nowMin = minuteOfDay(now);
+  const loadOf = new Map();
+  const load = (d) => { if (!loadOf.has(d)) loadOf.set(d, dayLoad(events.filter((e) => e.date === d))); return loadOf.get(d); };
+  const freeBefore = (e) => {
+    let free = freeBetween(load(e.date).merged, e.date === today ? nowMin : DAY_START, e.from);
+    for (let d = today; d < e.date; d = addDays(d, 1)) {
+      const wd = weekday(d); if (wd === 0 || wd === 6) continue;
+      free += Math.min(PER_DAY, freeBetween(load(d).merged, d === today ? nowMin : DAY_START, DAY_END));
+    }
+    return free;
+  };
+
+  const days = {};
+  const weeks = [];
+  let week = [];
+  for (let d = start; d <= end; d = addDays(d, 1)) {
+    const evs = byDay.get(d) || [];
+    const past = d < today;
+    const { busy, merged, gaps } = load(d);
+    let need = 0; let done = 0; let level = null;
+    const out = evs.map((e) => {
+      const ended = e.f <= now;
+      // prep counts on the coming occurrence of a series only: later repeats get their own prep later
+      const coming = !ended && series.get(e.key).coming_id === e.id;
+      const p = coming && Array.isArray(e.prep) ? e.prep.length : 0;
+      const pd = p ? Math.min(e.prep_done || 0, p) : 0;
+      let lv = null;
+      if (p) { need += p; done += pd; lv = pd >= p ? 'ok' : freeBefore(e) < (p - pd) * PER_STEP ? 'risk' : 'warn'; }
+      if (lv === 'risk' || (lv === 'warn' && level !== 'risk') || (lv === 'ok' && !level)) level = lv;
+      const x = series.get(e.key);
+      return { id: e.id, src: e.src, title: e.title, start: e.start, end: e.end, time: `${pad(Math.floor(e.from / 60))}:${pad(e.from % 60)}`, minutes: Math.round((e.f - e.s) / 60000),
+        kind: e.kind, imp: e.imp, key: e.key, repeats: x.count > 1, routine: routine(e), ended, prep: p ? e.prep : null, prep_done: p ? pd : null, ready: lv,
+        notes: e.notes || null, open: e.open || null, role: e.role || null, external: e.external === true, attendees: typeof e.attendees === 'number' ? e.attendees : null, with: e.with || null };
+    });
+    if (need && done >= need) level = 'ok';
+    const score = (e) => (e.imp ? 100 : 0) + (e.ready === 'risk' ? 50 : 0) + (e.prep ? 20 : 0) + (e.repeats ? 0 : 10) + e.minutes / 30 - (e.routine ? 200 : 0);
+    const best = out.filter((e) => !e.routine).sort((a, b) => score(b) - score(a))[0] || null;
+    const key = best && (best.imp || best.ready === 'risk') ? best.id : null;
+    const noNotes = past ? out.filter((e) => e.ended && !e.notes && (e.imp || e.kind === 'one')).length : 0;
+    days[d] = { date: d, in_month: d.slice(0, 7) === ym, past, today: d === today, weekend: [0, 6].includes(weekday(d)), events: out,
+      busy, gaps, blocks: merged, key, need, done, ready: need ? level : null, no_notes: noNotes };
+    week.push(d);
+    if (weekday(d) === 0) { weeks.push(week); week = []; }
+  }
+
+  const ser = {};
+  const seen = new Set(Object.values(days).flatMap((d) => d.events.map((e) => e.key)));
+  for (const k of seen) {
+    const x = series.get(k);
+    ser[k] = { key: k, title: x.title, kind: x.kind, count: x.count, past: x.past, coming: x.coming, dates: [...new Set(x.dates)],
+      last: x.last ? { date: x.last.date, notes: x.last.notes || null, open: x.last.open || null } : null };
+  }
+  return { ok: true, month: ym, today, now: new Date(now).toISOString(), day_start: '09:00', day_end: '18:00', weeks, days, series: ser,
+    memory: memory ? { from: memory.from || null, to: memory.to || null, updated_at: memory.updated_at || null, events: (memory.events || []).length } : null };
+}
+
+module.exports = {
+  validateMemory, mergeMemory, agendaMonth, seriesKey, normTitle, kindOf, isImportant, dayLoad,
+  MAX_EVENTS, MAX_SPAN_DAYS, KEEP_BACK_DAYS, KEEP_AHEAD_DAYS, FREE_BLOCK, PER_STEP,
+};

package/workspace/lib/console-state.js

@@ -190,7 +190,7 @@ function workflow({ root }) {
   const changeRange = engine.commitRange(root);
   // ONE delivery index for the board, built once and shared, exactly as the CLI board does.
   let deliveryIndex = null;
-  try { deliveryIndex = require(path.join(path.dirname(loaded.from), 'delivery-index.js')).deliveryIndex(root, ids); }
+  try { deliveryIndex = require(path.join(path.dirname(loaded.from), 'delivery-index.js')).deliveryIndex(root, ids, { recordsDir: engine.layout(root).initiatives }); }
   catch { deliveryIndex = null; }   // absent → each ladder builds its own; the engine handles it
   const bi = gitInfo.branchInfo(root);
   const scope = {

package/workspace/lib/doc-category.js

@@ -68,7 +68,9 @@ ALIAS.set('designticket', ['ticket', 'design']);
 ALIAS.set('engineeringticket', ['ticket', 'engineering']);
 ALIAS.set('engticket', ['ticket', 'engineering']);
 
-const ROLE_CATEGORY = { prd_path: 'prd', rubric_path: 'spec-artifact' };
+// What a record's path key says about the file it names. scan-consistency R3 adds the keys records use for their other
+// artifacts, so an explainer or a design a record names is categorized by that tie, not left to its file name.
+const ROLE_CATEGORY = { prd_path: 'prd', rubric_path: 'spec-artifact', brief_path: 'spec-artifact', design_path: 'spec-artifact', explainer_path: 'knowledge' };
 
 const RESERVED = /(^|\/)(index|log)\.md$/i;
 const TEMPLATE = /(^|\/)templates?\//i;

package/workspace/lib/engine/delivery-index.js

@@ -5,7 +5,7 @@
  *
  *   const D = require('./delivery-index');
  *   const idx = D.deliveryIndex(root, ids);     // { ok, reason?, byBranch:Set, byMention:Set }
- *   D.attribution(idx, id)                      // 'branch' | 'mention' | null | 'unknown'
+ *   D.attribution(idx, id)                      // 'branch' | 'mention' | 'change' | null | 'unknown'
  *   D.isDeliveryPath('workspace/server.js')     // true — a build path, not planning prose
  *
  * WHY THIS EXISTS. This derivation shipped inside `workspace/server.js` as a module-private
@@ -101,13 +101,13 @@ const deliveryCache = new Map();      // root -> { head, index }
  *                                any commit subject into a delivery claim
  * @returns {{ok:boolean, reason?:string, byBranch:Set<string>, byMention:Set<string>}}
  */
-function deliveryIndex(root, ids) {
+function deliveryIndex(root, ids, opts) {
   const t = trunkRef(root);
   if (!t) {
     return {
       ok: false,
       reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived',
-      byBranch: new Set(), byMention: new Set(),
+      byBranch: new Set(), byMention: new Set(), byChange: new Set(),
     };
   }
   const hit = deliveryCache.get(root);
@@ -119,7 +119,7 @@ function deliveryIndex(root, ids) {
     return {
       ok: false,
       reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`,
-      byBranch: new Set(), byMention: new Set(),
+      byBranch: new Set(), byMention: new Set(), byChange: new Set(),
     };
   }
   const byBranch = new Set();
@@ -137,11 +137,87 @@ function deliveryIndex(root, ids) {
     // the safe direction and the one the surface already errs in.
     for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
   }
-  const index = { ok: true, byBranch, byMention };
+  // 3. THE CHANGE THAT CARRIED THE SPEC (scan-consistency R1). See changeSignal below.
+  const byChange = changeSignal(root, t.head, known, opts);
+  const index = { ok: true, byBranch, byMention, byChange };
   deliveryCache.set(root, { head: t.head, index });
   return index;
 }
 
+/*
+ * THE THIRD SIGNAL — a change on the trunk that touched this initiative's OWN documents and build
+ * paths together (scan-consistency R1).
+ *
+ * Signals 1 and 2 both need the id spelled in a commit message. On this repository most pull
+ * requests ship on `claude/<slug>-<suffix>` branches and their commits name the area (`feat(workspace):
+ * …`), not the id, so 102 of 283 initiatives read `build pending` although their PRD, record and code
+ * merged in one pull request. The tie is concrete and git holds it: the pull request that changed
+ * `planning/initiatives/<id>.md` (or the PRD the record names) ALSO changed build files.
+ *
+ * A UNIT is one first-parent commit of the trunk: a merge commit (its diff against the first parent
+ * is the whole pull request), a squash merge, or a direct commit. Two guards keep it from becoming a
+ * similarity score:
+ *   · the unit must change at least one build path (isDeliveryPath) — a docs-only pull request
+ *     delivers nothing;
+ *   · the unit may touch the documents of at most MAX_CO_INITIATIVES initiatives. A sweep that edits
+ *     forty records while changing a script is evidence for none of them.
+ * A merged branch whose name, less its random suffix, IS a known id (`claude/jira-wbs-kpamaz`) counts
+ * too, when its pull request changed build paths.
+ */
+const MAX_CO_INITIATIVES = 2;
+const RECORD_DIRS = ['planning/initiatives', 'pmos/state/initiatives', 'state/initiatives'];
+/** { [repo-relative path]: Set<id> } — each record and every `*_path` its frontmatter names. */
+function documentOwners(root, ids, recordsDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const dirs = recordsDir ? [recordsDir] : RECORD_DIRS.map((d) => path.join(root, d));
+  const owners = new Map();
+  const add = (rel, id) => {
+    const k = String(rel || '').trim().replace(/^["']|["']$/g, '').replace(/^\.?\//, '');
+    if (!k || /\s/.test(k) || k.includes('..')) return;
+    if (!owners.has(k)) owners.set(k, new Set());
+    owners.get(k).add(id);
+  };
+  for (const id of ids) {
+    for (const dir of dirs) {
+      const file = path.join(dir, id + '.md');
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+      add(path.relative(root, file).split(path.sep).join('/'), id);
+      const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+      if (fm) for (const m of fm[1].matchAll(/^[a-z_]*_path[ \t]*:[ \t]*(\S.*?)[ \t]*$/gm)) add(m[1], id);
+      break;
+    }
+  }
+  return owners;
+}
+function changeSignal(root, head, known, opts) {
+  const out = new Set();
+  if (!known.length) return out;
+  const owners = documentOwners(root, known, opts && opts.recordsDir);
+  const ids = new Set(known);
+  const r = gitCap(root, ['log', '--first-parent', '--diff-merges=first-parent', '--format=%x1e%s%x1f', '--name-only', head]);
+  if (!r.ok) return out;
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const subject = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    if (!files.some(isDeliveryPath)) continue;
+    const touched = new Set();
+    for (const f of files) for (const id of owners.get(f) || []) touched.add(id);
+    if (touched.size && touched.size <= MAX_CO_INITIATIVES) for (const id of touched) out.add(id);
+    const b = /^Merge (?:pull request #\d+ from|branch ')\s*(?:[^/\s]+\/)?(?:claude|feature|feat|fix|chore)\/([A-Za-z0-9][\w.-]*?)'?(?:\s|$)/.exec(subject.trim());
+    if (b) {
+      const slug = b[1];
+      const bare = slug.replace(/-[a-z0-9]{4,8}$/, '');
+      if (ids.has(slug)) out.add(slug);
+      else if (bare !== slug && ids.has(bare)) out.add(bare);
+    }
+  }
+  return out;
+}
+
 /*
  * The branches that actually MERGED — a strictly narrower signal than `byBranch`, and the two are
  * kept apart on purpose.
@@ -251,12 +327,13 @@ function declaredDelivery(root, declared) {
  * caller that collapses the two reports "nothing was delivered" for a repository whose history it
  * failed to read, which is a claim the missing evidence cannot support.
  *
- * @returns {'branch'|'mention'|'unknown'|null}
+ * @returns {'branch'|'mention'|'change'|'unknown'|null}
  */
 function attribution(index, id) {
   if (!index || !index.ok) return 'unknown';
   if (index.byBranch.has(id)) return 'branch';
   if (index.byMention.has(id)) return 'mention';
+  if (index.byChange && index.byChange.has(id)) return 'change';
   return null;
 }
 
@@ -264,6 +341,7 @@ function attribution(index, id) {
 function attributionEvidence(signal, id, extra) {
   if (signal === 'branch') return `an initiative/${id} branch merged to the trunk`;
   if (signal === 'mention') return 'a commit on the trunk names this initiative and changes build files';
+  if (signal === 'change') return 'a change merged to the trunk carried this initiative\'s own documents and build files together';
   if (signal === 'declared') return `delivered_by ${String(extra || '').slice(0, 8)} — verified on the trunk, and it changes build paths`;
   if (signal === 'unknown') return 'the trunk history could not be read — delivery cannot be derived here';
   return 'no commit on the trunk is attributable to this initiative';
@@ -274,5 +352,5 @@ function _resetCache() { deliveryCache.clear(); }
 
 module.exports = {
   deliveryIndex, attribution, attributionEvidence, declaredDelivery, mergedBranches,
-  isDeliveryPath, trunkRef, _resetCache,
+  isDeliveryPath, trunkRef, documentOwners, _resetCache,
 };

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

@@ -438,7 +438,7 @@ function buildCommits(root, range, lane, opts) {
     if (declared && declared.declared && !declared.ok) {
       return { unknown: false, failedDeclaration: declared, first: null, count: 0, sample: null, signal: null, attributed: true };
     }
-    const index = (opts && opts.deliveryIndex) || delivery.deliveryIndex(root, listInitiatives(root));
+    const index = (opts && opts.deliveryIndex) || delivery.deliveryIndex(root, listInitiatives(root), { recordsDir: layout(root).initiatives });
     signal = delivery.attribution(index, id);
     if (declared && declared.ok) {
       // A verified declaration attributes the work regardless of what the conventions found. It is
@@ -478,7 +478,7 @@ function buildCommits(root, range, lane, opts) {
     count++;
     if (first === null) { first = i; sample = hit; }
   }
-  if (whole && id && signal === 'branch' && first === null) {
+  if (whole && id && (signal === 'branch' || signal === 'change') && first === null) {
     // The branch merged and every commit it carried was written on the branch, so no trunk commit
     // subject names the id. The merge itself is the evidence, and saying "0 commits" over a merged
     // branch would be the under-claim in a new place.
@@ -1657,7 +1657,7 @@ function main(argv) {
   // reason the commit range is: `deliveryIndex` memoises per trunk head, so a per-initiative build
   // would be cheap but the intent — one read, shared — is what keeps the rows consistent with each
   // other even if the trunk moved mid-run.
-  const deliveryIdx = delivery.deliveryIndex(root, ids);
+  const deliveryIdx = delivery.deliveryIndex(root, ids, { recordsDir: layout(root).initiatives });
   const rows = ids.map((i) => computeWorkflow(i, { root, range, changeRange, deliveryIndex: deliveryIdx }));
   if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
   if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }

package/workspace/lib/initiative-files.js

@@ -16,6 +16,31 @@ const PK = require('./preview-kind');
 const { previewKind } = PK;
 
 const MAX_FILES = 200;
+// scan-consistency R3 — the shared delivery reader (scripts/delivery-index.js; lib/engine/ in an installed workspace),
+// for the record-owned document map the trunk-unit source below joins on.
+const DELIVERY_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'delivery-index.js'), path.join(__dirname, 'engine', 'delivery-index.js')];
+let delivery;
+function deliveryLib() {
+  if (delivery === undefined) {
+    delivery = null;
+    for (const p of DELIVERY_PATHS) { if (fs.existsSync(p)) { try { delivery = require(p); } catch { delivery = null; } break; } }
+  }
+  return delivery;
+}
+const unitCache = new Map();   // root → { head, units }
+/** The trunk's first-parent units (a merged pull request, a squash merge or a direct commit) as parseLog records. */
+function trunkUnits(root, trunk) {
+  const headR = git(root, ['rev-parse', trunk]);
+  if (!headR.ok) return null;
+  const head = headR.out.trim();
+  const hit = unitCache.get(root);
+  if (hit && hit.head === head) return hit.units;
+  const r = git(root, ['log', '--first-parent', '--diff-merges=first-parent', '-n', '3000', '--name-status', '--format=%x1e%H%x1f%s', head]);
+  if (!r.ok) return null;
+  const units = parseLog(r.out, () => true);
+  unitCache.set(root, { head, units });
+  return units;
+}
 const cache = new Map();   // root|id → {head, at, result}
 const TTL_MS = 30000;
 
@@ -63,6 +88,17 @@ function parseLog(out, keep) {
  * @param {{exclude?:Set<string>}} opts  repo-relative paths the document index already lists
  * @returns {{ok:true, items:Array, total:number, truncated:boolean, via:string[]}|{ok:false, reason:string}}
  */
+/** The ids of the repository's initiative records (planning/initiatives/ or pmos/state/initiatives/). */
+function listRecordIds(root) {
+  for (const d of ['planning/initiatives', 'pmos/state/initiatives', 'state/initiatives']) {
+    try {
+      const names = fs.readdirSync(path.join(root, d)).filter((f) => f.endsWith('.md') && f !== 'README.md' && f !== 'index.md');
+      if (names.length) return names.map((f) => f.slice(0, -3));
+    } catch { /* next */ }
+  }
+  return [];
+}
+
 function filesFor(root, id, opts) {
   const exclude = (opts && opts.exclude) || new Set();
   if (!/^[A-Za-z0-9][\w.-]*$/.test(String(id || ''))) return { ok: false, reason: 'not an initiative id' };
@@ -86,6 +122,25 @@ function filesFor(root, id, opts) {
       const own = git(root, ['log', trunk + '..' + branch, '--no-merges', '--name-status', '--format=%x1e%H%x1f%s']);
       if (own.ok) { const rows = parseLog(own.out, () => true); if (rows.length) { via.push('its branch ' + branch); commits.push(...rows); } }
     }
+    // 3. the trunk's own units that carried this initiative's documents (scan-consistency R3). Most pull requests here
+    // ship on `claude/*` branches whose commits never name the id, and a merged branch is usually deleted, so 1 and 2
+    // find nothing for delivered work. A unit that changed the record or a file the record names, and the documents of
+    // at most one other initiative, is this initiative's work: the same rule delivery-index.js attributes delivery by.
+    const D = deliveryLib();
+    if (trunk && D && typeof D.documentOwners === 'function') {
+      let ids = [];
+      try { ids = listRecordIds(root); } catch { ids = []; }
+      const owners = D.documentOwners(root, ids.length ? ids : [id]);
+      const units = trunkUnits(root, trunk) || [];
+      const known = new Set(commits.map((c) => c.sha));
+      const mine = units.filter((u) => {
+        if (known.has(u.sha)) return false;
+        const touched = new Set();
+        for (const f of u.files) for (const o of owners.get(f) || []) touched.add(o);
+        return touched.has(id) && touched.size <= 2;
+      });
+      if (mine.length) { via.push('changes that carried its documents'); commits.push(...mine); }
+    }
     // What still exists: the checked-out tree plus the initiative's own branch tip, so a file that lives only on an
     // unmerged branch is listed, and a file deleted since is not. `ls-tree` once per ref, never one spawn per file.
     const present = new Set(); const onHead = new Set();
@@ -139,4 +194,7 @@ function readAtRef(root, ref, rel) {
   return { ok: true, kind: known ? kind : 'text', text };
 }
 
-module.exports = { filesFor, groupOf, namesId, readAtRef };
+/** Forget the trunk changes read for `root` (all roots without one): the next read walks the history again. */
+function forget(root) { if (root) unitCache.delete(root); else unitCache.clear(); }
+
+module.exports = { forget, filesFor, groupOf, namesId, readAtRef };

package/workspace/lib/initiative-rows.js

@@ -16,7 +16,7 @@
  *
  * A ROW is one line of `node scripts/workflow-state.js --json` (every record, uncapped), narrowed to what the planning
  * layer reads: { ok, id, title, lane, group, anchor, stage, accepted, stopped, last_activity (ISO), profile, record,
- * next }. `stopped` is the lifecycle fold ({ state, reason, at }) or null.
+ * next, steps: [{ key, status }] }. `stopped` is the lifecycle fold ({ state, reason, at }) or null.
  *
  * WHY A CHILD PROCESS. The engine resolves each artifact's first appearance by running git: about 260 ms per record,
  * so a repository of 100 records takes half a minute (lib/board-cache.js measured it). The board cache is capped at
@@ -71,6 +71,8 @@ function narrow(root, raw) {
     stage: r.stage || null, accepted: !!r.accepted,
     stopped: r.stopped ? { state: r.stopped.state, reason: r.stopped.reason || '', at: r.stopped.at || null } : null,
     last_activity: iso(r.last_activity), profile: r.profile || null, record: r.record || null, next: r.next || null,
+    // key and status of each ladder step, so a row's stage is read by the same rule as the sheet's stepper
+    steps: Array.isArray(r.steps) ? r.steps.filter(Boolean).map((x) => ({ key: x.key, status: x.status })) : null,
   } : { ok: false, id: r && r.id, error: (r && r.error) || 'the row could not be derived' }));
 }
 
@@ -157,6 +159,16 @@ function cachedSig(root) {
   const hit = cache.get(root);
   return hit ? `${hit.sig}@${hit.at}${hit.error ? '!' : ''}` : 'none';
 }
+/** Read `root` again now, whatever the cache holds (POST /api/initiatives/rescan, the PM's Re-scan press). The last
+ *  answer is kept but marked stale, so the page keeps its rows and a poll sees the new derivation land. Starts one
+ *  background derivation; answers { started: false, running: true } when one is already running. */
+function rescan(root) {
+  if (inflight.get(root)) return { started: false, running: true };
+  const hit = cache.get(root);
+  if (hit) hit.at = 0;
+  refresh(root, recordsSig(root));
+  return { started: true, running: true };
+}
 /** Test and maintenance seam. */
 function invalidate(root) { if (root) { cache.delete(root); inflight.delete(root); } else { cache.clear(); inflight.clear(); } }
 
@@ -207,4 +219,4 @@ function anchorsOf(root) {
   return { resolve, period, error, ok: !!(index && index.ok) };
 }
 
-module.exports = { deriveSync, rowsFor, peek, setBackground, isDeriving, deriveNow, answerSig, cachedSig, recordsSig, invalidate, anchorsOf, workGroupOf, periodLabel, narrow };
+module.exports = { deriveSync, rowsFor, rescan, peek, setBackground, isDeriving, deriveNow, answerSig, cachedSig, recordsSig, invalidate, anchorsOf, workGroupOf, periodLabel, narrow };

package/workspace/lib/mobile-nav.js

@@ -74,7 +74,7 @@ const DETAIL_TITLE = {
 const MOBILE_DESTS = ['today', 'initiatives', 'board', 'reports', 'agent'];
 // What each tab and Settings is called. The same words as the desktop bar (public/pm/frame-copy.js COPY.nav), which
 // MOBNAV-P7 holds equal.
-const DEST_TITLE = { today: 'Today', initiatives: 'Initiatives', board: 'Board', reports: 'Reports', agent: 'Agent', settings: 'Settings' };
+const DEST_TITLE = { today: 'Agenda', initiatives: 'Initiatives', board: 'Board', reports: 'Reports', agent: 'Agent', settings: 'Settings' };
 // Every old MODES key has a tab. The suite ITERATES this map, so a mode without a phone path fails.
 const MOBILE_DEST = { product: 'initiatives', scheduled: 'reports', agent: 'agent', memory: 'initiatives',
   workflow: 'initiatives', skills: 'initiatives', knowledge: 'initiatives' };