create-pmos 0.129.0 → 0.131.0

package/workspace/lib/routes-brief-page.js

@@ -0,0 +1,187 @@
+'use strict';
+/* routes-brief-page.js — GET /api/brief-page[?ws=<id>&now=ISO] (console3 Briefing as the brief, PRD briefing-brief R2, R3, R8).
+ *
+ *   → { ok, date, today: [meeting], needs: [row], decisions_error? }
+ *
+ * READ ONLY, and built only from what PMOS already holds. Nothing is invented.
+ *   today   one row per meeting of the local day, in time order, from the cached calendar events (routes-calendar-import.js readEvents,
+ *           the same source as /api/calendar-views): { id, title, start, end, minutes, people, initiative, prepared, before, state }.
+ *           prepared: [{ kind: 'prep'|'pm-note'|'note'|'last-note', text, id? }] what PMOS holds for the meeting (the agent's prep note,
+ *           the PM's notes on the event, the note linked to it, the last note of an earlier occurrence). before: [{ id, title, due,
+ *           done }] the PM's own open items that name the meeting (item.meeting_id or item.event_id equals the event id, or the title
+ *           contains the meeting's title). state: 'past' | 'now' | 'next' | 'later'.
+ *   needs   decisions only (with ?decisions=1; the page takes them from GET /api/briefing instead) the PM can make (the signal engine's cards that carry options or are Critical), the PM's own items that are
+ *           overdue or due today, and outside-PMOS items (kind 'offline') that await confirmation. Overdue rows come first, the most
+ *           late first, then the items due today, then the offline ones, then the decisions.
+ *           An item row: { key, kind: 'overdue'|'due-today'|'offline', id, headline, due, days_late, priority, person, offline, evidence }.
+ *           evidence is { text, event_id } when the calendar holds a meeting with the person, else null: the page asks the PM to
+ *           confirm it and never marks the item done itself.
+ *           A decision row: { key, kind: 'decision', headline, tag, card }.
+ * Item fields read defensively (a missing field is absent): kind, defer, person, evidence, workPlacement(item, today) when lib/pm-items.js
+ * has it. A deferred item ('Not yet') is left out until its defer date or time. Writes go through the existing pm-items routes. */
+const path = require('path');
+const pmItems = require('./pm-items.js');
+
+const pad = (n) => String(n).padStart(2, '0');
+const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+const DAY = 86400000;
+const norm = (s) => String(s || '').toLowerCase().replace(/\s+/g, ' ').trim();
+const clip = (s, n) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+const hhmm = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+const WD = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+function daysBetween(fromIso, toIso) {
+  const a = Date.parse(fromIso + 'T00:00:00Z'); const b = Date.parse(toIso + 'T00:00:00Z');
+  return Math.round((b - a) / DAY);
+}
+
+function deferred(item, now, todayIso) {
+  const d = item.defer;
+  if (!d) return false;
+  const s = String(d);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s > todayIso;
+  const t = Date.parse(s);
+  return Number.isFinite(t) && t > now.getTime();
+}
+
+/** The meetings of the local day. `notes` is an optional { findByEvent(ev), lastBefore(ev) } so the route can read the notes store. */
+function todayAgenda(events, items, now, notes = {}) {
+  const todayIso = localDate(now);
+  const open = items.filter((i) => !i.done);
+  const rows = (events || []).filter((e) => e && e.at && !Number.isNaN(Date.parse(e.at)) && localDate(new Date(e.at)) === todayIso)
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at) || String(a.id).localeCompare(String(b.id)))
+    .map((e) => {
+      const s = new Date(e.at); const endMs = e.end && Date.parse(e.end) > Date.parse(e.at) ? Date.parse(e.end) : Date.parse(e.at);
+      const prepared = [];
+      if (e.agent_prep_notes && String(e.agent_prep_notes).trim()) prepared.push({ kind: 'prep', text: clip(e.agent_prep_notes, 200) });
+      const pm = Array.isArray(e.pm_notes) ? e.pm_notes : [];
+      if (pm.length) prepared.push({ kind: 'pm-note', text: clip(pm[pm.length - 1].text, 200) });
+      const linked = notes.findByEvent ? notes.findByEvent(e) : null;
+      if (linked) prepared.push({ kind: 'note', text: 'Notes started: ' + clip(linked.title, 80), id: linked.id });
+      const last = notes.lastBefore ? notes.lastBefore(e) : null;
+      if (last) prepared.push({ kind: 'last-note', text: 'Last notes: ' + clip(last.title, 80) + ' (' + String(last.updated_at || last.created_at || '').slice(0, 10) + ')', id: last.id });
+      const t = norm(e.title);
+      const before = open.filter((i) => (i.meeting_id && i.meeting_id === e.id) || (i.event_id && i.event_id === e.id) || (t.length >= 6 && norm(i.title).includes(t)))
+        .map((i) => ({ id: i.id, title: i.title, due: i.due || null, done: !!i.done }));
+      return { id: e.id, title: e.title, start: s.toISOString(), end: new Date(endMs).toISOString(), startLocal: hhmm(s), minutes: Math.max(0, Math.round((endMs - s.getTime()) / 60000)),
+        people: Array.isArray(e.attendees) ? e.attendees.slice(0, 12) : [], initiative: e.initiative || null, prepared, before, _s: s.getTime(), _e: endMs };
+    });
+  let nextDone = false;
+  for (const r of rows) {
+    const nowMs = now.getTime();
+    if (r._e <= nowMs && r._e > r._s) r.state = 'past';
+    else if (r._s <= nowMs && r._e > nowMs) r.state = 'now';
+    else if (r._e === r._s && r._s < nowMs) r.state = 'past';
+    else if (!nextDone) { r.state = 'next'; nextDone = true; } else r.state = 'later';
+  }
+  rows.forEach((r) => { delete r._s; delete r._e; });
+  return rows;
+}
+
+/** A calendar meeting that names the person, from today on: "a meeting with Ana is booked Tue 10:00". */
+function evidenceFor(item, events, now) {
+  if (item.evidence) {
+    const t = Array.isArray(item.evidence) ? item.evidence[0] : item.evidence;
+    const text = typeof t === 'string' ? t : t && t.text;
+    if (text) return { text: clip(text, 160), event_id: (t && t.event_id) || null };
+  }
+  const names = [];
+  if (item.person) names.push(norm(item.person));
+  const title = norm(item.title);
+  const hits = (events || []).filter((e) => e && e.at && Date.parse(e.at) >= now.getTime() - 3600000 && Date.parse(e.at) <= now.getTime() + 21 * DAY)
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  for (const e of hits) {
+    const who = (Array.isArray(e.attendees) ? e.attendees : []).map(norm).filter(Boolean);
+    const hit = who.find((w) => names.some((n) => n && (w.includes(n) || n.includes(w))) || (w.split(' ')[0].length >= 3 && new RegExp('\\b' + w.split(' ')[0].replace(/[^a-z0-9]/g, '') + '\\b').test(title)));
+    if (hit) {
+      const d = new Date(e.at);
+      const who1 = hit.split(' ')[0]; const nice = who1.charAt(0).toUpperCase() + who1.slice(1);
+      return { text: 'a meeting with ' + nice + ' is booked ' + WD[d.getDay()] + ' ' + hhmm(d), event_id: e.id };
+    }
+  }
+  return null;
+}
+
+function needsOf(items, events, cards, now, deps = {}) {
+  const todayIso = localDate(now);
+  const todayDate = new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+  const work = typeof pmItems.workPlacement === 'function' ? pmItems.workPlacement : null;
+  const late = []; const dueToday = []; const offline = [];
+  for (const i of items) {
+    if (!i || i.done || deferred(i, now, todayIso)) continue;
+    const base = { id: i.id, headline: i.title, due: i.due || null, priority: i.priority || null, person: i.person || null };
+    if (i.kind === 'offline') {
+      const late0 = i.due && i.due < todayIso ? daysBetween(i.due, todayIso) : 0;
+      offline.push({ key: 'item:' + i.id, kind: 'offline', ...base, days_late: late0, offline: true, evidence: evidenceFor(i, events, now) });
+      continue;
+    }
+    if (!i.due || i.due > todayIso) continue;
+    if (work) { if (work(i, todayDate) !== 'today') continue; } else if (i.waiting_on || i.parked || i.list_override === 'later') continue;
+    if (i.due < todayIso) late.push({ key: 'item:' + i.id, kind: 'overdue', ...base, days_late: daysBetween(i.due, todayIso), offline: false, evidence: null });
+    else dueToday.push({ key: 'item:' + i.id, kind: 'due-today', ...base, days_late: 0, offline: false, evidence: null });
+  }
+  late.sort((a, b) => b.days_late - a.days_late || String(a.headline).localeCompare(String(b.headline)));
+  offline.sort((a, b) => b.days_late - a.days_late || String(a.headline).localeCompare(String(b.headline)));
+  const byTitle = (a, b) => String(a.headline).localeCompare(String(b.headline));
+  dueToday.sort(byTitle);
+  const decisions = (cards || []).filter((c) => c && (c.move || c.tag === 'Critical')).map((c) => ({ key: 'card:' + c.key, kind: 'decision', headline: c.headline, tag: c.tag, card: c }));
+  return [...late, ...dueToday, ...offline, ...decisions];
+}
+
+/** The pure builder. deps: { events, items (folded), cards, notes } so a test needs no repository. */
+function build(query, deps = {}) {
+  const q = query || {};
+  let now = q.now ? new Date(q.now) : (deps.now ? new Date(deps.now) : new Date());
+  if (Number.isNaN(now.getTime())) now = new Date();
+  const events = deps.events || []; const items = deps.items || [];
+  const body = { ok: true, date: localDate(now), today: todayAgenda(events, items, now, deps.notes || {}), needs: needsOf(items, events, deps.cards || [], now, deps) };
+  if (deps.decisionsError) body.decisions_error = deps.decisionsError;
+  return { status: 200, body };
+}
+
+function notesAdapter(runtimeDir) {
+  let notes; try { notes = require('./notes.js'); } catch { return {}; }
+  const rows = () => { try { const l = notes.list(runtimeDir); return l && l.ok ? l.notes.filter((n) => !n.private) : []; } catch { return []; } };
+  return {
+    findByEvent: (e) => { try { const n = notes.findByEvent(runtimeDir, { event_id: e.id, start: e.at, title: e.title }); return n && !n.private ? { id: n.id, title: n.title || 'Untitled note' } : null; } catch { return null; } },
+    lastBefore: (e) => {
+      const t = norm(e.title);
+      const hits = rows().filter((n) => n.meeting && n.meeting.kind === 'event' && norm(n.meeting.title) === t && Date.parse(n.meeting.start) < Date.parse(e.at))
+        .sort((a, b) => String(b.meeting.start).localeCompare(String(a.meeting.start)));
+      return hits[0] || null;
+    },
+  };
+}
+
+module.exports = {
+  prefixes: ['/api/brief-page'],
+  build, todayAgenda, needsOf, evidenceFor, deferred,
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/brief-page') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    const q = Object.fromEntries(url.searchParams.entries());
+    let now = q.now ? new Date(q.now) : new Date();
+    if (Number.isNaN(now.getTime())) now = new Date();
+    try {
+      const dir = ctx.runtimeDir;
+      const events = dir ? require('./routes-calendar-import.js').readEvents(dir) : [];
+      const items = dir ? pmItems.fold(pmItems.readLines(path.join(dir, 'pm-items', 'items.jsonl'))) : [];
+      // The decisions come from the signal engine, whose repository read is slow. The page already holds them (GET /api/briefing feeds its deck), so the
+      // read is made only when the caller asks (?decisions=1); the items and the agenda never wait for it.
+      let cards = []; let decisionsError = null;
+      if (q.decisions === '1') try {
+        const w = ctx.getWs && ctx.getWs(q.ws || null);
+        const root = (w && w.root) || path.resolve(__dirname, '..', '..');
+        const iso = localDate(now);
+        const facts = await require('./facts-async.js').readFactsAsync(root, { today: iso });
+        const sig = path.resolve(__dirname, '..', '..', 'scripts', 'signals');
+        cards = require(path.join(sig, 'index.js')).present(facts, { lens: 'Unblock', zoom: 'week', today: iso }).cards || [];
+      } catch (e) { decisionsError = 'the decisions could not be read: ' + (e && e.message ? e.message : String(e)); }
+      const out = build({ now: now.toISOString() }, { events, items, cards, decisionsError, notes: dir ? notesAdapter(dir) : {} });
+      ctx.json(res, out.body, out.status);
+    } catch (e) {
+      ctx.json(res, { ok: false, error: 'the brief page could not be built: ' + (e && e.message ? e.message : String(e)) }, 500);
+    }
+    return true;
+  },
+};

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

@@ -1,7 +1,8 @@
 '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 }
+ *   → { ok, view, range, cells, unit, gantt, strategy, events_source, today,
+ *       layers, layers_total, layers_note, free, context, context_total }     (the last six: lib/calendar-layers.js)
  *
  * 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:
@@ -13,10 +14,12 @@
  * gets none and says so. */
 const path = require('path');
 const model = require('../../scripts/calendar-model.js');
+const layersLib = require('./calendar-layers.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. */
+/** The pure handler. deps: { readFacts(), readEvents?(range), readKrs?(), today, nowMs?, readDated?(range), readItems?(),
+ *  readContextSources?() } so tests need no repo. A dep that is missing gives its source as empty, said in layers_note. */
 function handle(query, deps = {}) {
   const view = (query && query.view) || 'month';
   const date = (query && query.date) || (deps.today || today());
@@ -33,13 +36,118 @@ function handle(query, deps = {}) {
     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 } };
+    const dated = typeof deps.readDated === 'function' ? (deps.readDated(range) || {}) : {
+      unavailable: { plan_items: 'no reader is wired', releases: 'no reader is wired', reports: 'no reader is wired', own: 'no reader is wired' } };
+    // the initiatives come from the facts this handler already holds, so every caller gets their promised dates
+    if (!dated.initiatives && !(dated.unavailable && dated.unavailable.initiatives)) dated.initiatives = inis;
+    const items = typeof deps.readItems === 'function' ? (deps.readItems() || {}) : {};
+    const src = typeof deps.readContextSources === 'function' ? (deps.readContextSources() || {}) : {};
+    const nowMs = Number.isFinite(deps.nowMs) ? deps.nowMs : (deps.today ? undefined : Date.now());
+    const extra = layersLib.build({ range, today: nowDay, nowMs, events, dated, src, own: items.own, planItemsDue: items.planItems });
+    return { status: 200, body: { ok: true, view, range, unit: b.unit, cells: b.cells, gantt, strategy, events_source: source, today: nowDay, ...extra } };
   } catch (e) {
     return { status: 500, body: { ok: false, error: String(e && e.message || e) } };
   }
 }
 
+/* ── the readers behind the layers, free time and context (each source on its own: one that cannot be read is named in
+ *    layers_note and gives nothing; it never takes the answer down) ────────────────────────────────────────────────── */
+const reason = (e) => String((e && e.message) || e).slice(0, 160);
+
+function readers(root, runtimeDir) {
+  let plan = null;
+  const planFold = () => { if (!plan) plan = require('./plan-items.js').readFold(root); return plan; };
+  const planRows = () => Object.values(planFold().items).filter((p) => !(p.proposed && !p.kept));
+  let ownLines = null;
+  const ownRows = () => {
+    if (!ownLines) ownLines = require('./pm-items.js').readLines(path.join(runtimeDir, 'pm-items', 'items.jsonl'));
+    return require('./pm-items.js').fold(ownLines);
+  };
+  const planItem = (p) => ({ id: p.id, initiative: p.initiative, title: p.title, due: p.due, milestone: !!p.milestone, state: p.state });
+  return {
+    readDated(range) {
+      const unavailable = {};
+      const out = { unavailable };
+      try { out.planItems = planRows().map(planItem); } catch (e) { unavailable.plan_items = 'the plan ledger could not be read: ' + reason(e); }
+      try {
+        const R = require('../../scripts/releases.js');
+        const f = path.join(runtimeDir, 'releases', 'releases.jsonl');
+        let lines = []; try { lines = require('fs').readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { lines = []; }
+        out.releases = R.foldReleases(lines);
+      } catch (e) { unavailable.releases = 'the releases file could not be read: ' + reason(e); }
+      try {
+        const RN = require('./report-needs.js');
+        out.reports = RN.reportsOf(root).reports.map((r) => ({ cadence: r.cadence, slot: r.slot, issued: r.issued ? { at: r.issued.at } : null }));
+        out.reportSchedules = reportSchedules(RN, range);
+      } catch (e) { unavailable.reports = 'the report folders could not be read: ' + reason(e); }
+      try { out.own = ownRows().map((o) => ({ id: o.id, title: o.title, due: o.due, done: !!o.done })); } catch (e) { unavailable.own = 'your items could not be read: ' + reason(e); }
+      return out;
+    },
+    readItems() {
+      const out = { own: [], planItems: [] };
+      try { out.planItems = planRows().map(planItem); } catch { /* the plan ledger is named in layers_note */ }
+      try { out.own = ownRows().map((o) => ({ id: o.id, title: o.title, due: o.due, done: !!o.done, priority: o.priority || null })); } catch { /* likewise */ }
+      return out;
+    },
+    readContextSources() {
+      const src = { notes: [], planItems: [], ownItems: [] };
+      try { src.planItems = planRows().map((p) => ({ id: p.id, initiative: p.initiative, title: p.title, createdAt: p.createdAt, doneAt: p.doneAt })); } catch { /* no plan ledger: no moved items */ }
+      try { src.ownItems = ownRows().map((o) => ({ id: o.id, title: o.title, initiative: o.initiative || null, created_at: o.created_at || null, done_at: o.done_at || null })); } catch { /* no own items */ }
+      try { src.notes = linkedNotes(runtimeDir); } catch { /* no notes: no decisions or actions */ }
+      return src;
+    },
+  };
+}
+
+/** The dates a report schedule fires on, from the range start, using the same slot math the scheduler runs on. */
+function reportSchedules(RN, range) {
+  const logic = require('./schedule-logic.js');
+  const out = [];
+  const t0 = new Date();
+  const today = `${t0.getFullYear()}-${String(t0.getMonth() + 1).padStart(2, '0')}-${String(t0.getDate()).padStart(2, '0')}`;
+  const first = range && range.start > today ? range.start : today;
+  const from = new Date(Number(first.slice(0, 4)), Number(first.slice(5, 7)) - 1, Number(first.slice(8, 10)));
+  for (const s of RN.readSchedules()) {
+    if (!s || !s.enabled) continue;
+    const cadence = RN.cadenceOfSchedule(s);
+    if (!cadence) continue;
+    const dates = [];
+    let at = from;
+    for (let i = 0; i < 62; i++) {
+      const next = logic.nextRun(s, at);
+      if (!next) break;
+      const d = new Date(next);
+      const ds = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+      if (range && ds > range.end) break;
+      dates.push(ds);
+      at = new Date(d.getTime() + 1000);
+    }
+    out.push({ id: String(s.id || s.name || cadence), name: s.name, cadence, dates: [...new Set(dates)] });
+  }
+  return out;
+}
+
+/** Notes linked to a calendar event, read straight from the notes folder (no import, no write). */
+function linkedNotes(runtimeDir) {
+  const fs = require('fs');
+  const dir = path.join(runtimeDir, 'notes');
+  const out = [];
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json'))) {
+    let n; try { n = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { continue; }
+    if (!n || !n.id || !n.meeting || n.meeting.kind !== 'event') continue;
+    const fin = n.final_notes && typeof n.final_notes === 'object' ? n.final_notes : null;
+    const sec = n.summary && n.summary.sections ? n.summary.sections : null;
+    const pick = (a, b) => (Array.isArray(a) && a.length ? a : Array.isArray(b) ? b : []);
+    out.push({ id: n.id, title: n.title || '', private: !!n.private, initiative: n.initiative && n.initiative.id ? String(n.initiative.id) : null,
+      meeting: { event_id: n.meeting.event_id || null, start: n.meeting.start, title: n.meeting.title },
+      decisions: pick(fin && fin.decisions, sec && sec.decisions).map((x) => ({ text: x && x.text })),
+      actions: pick(fin && fin.actions, sec && sec.actions).map((x) => ({ text: x && x.text, owner: x && x.owner || null, due: x && x.due || null })) });
+  }
+  return out;
+}
+
 module.exports = {
+  readers,
   prefixes: ['/api/calendar-views'],
   handlePure: handle,
   handle: async (req, res, url, ctx) => {
@@ -54,6 +162,7 @@ module.exports = {
     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),
+      ...readers(root, ctx.runtimeDir),
     });
     ctx.json(res, out.body, out.status);
     return true;

package/workspace/lib/routes-pm-items.js

@@ -1,13 +1,29 @@
 'use strict';
-/* routes-pm-items.js — the PM's own work items and jobs to be done (planning-flows run 1 and 2, UI slice).
+/* routes-pm-items.js — the PM's own work items and jobs to be done (planning-flows run 1 and 2, UI slice; the
+ * console3 Work page: lib/pm-items.js workPlacement, lib/work-focus.js).
  *
- *   GET  /api/pm-items                     → { ok, today, lists: { waiting, today, week, triage, later }, jobs, items }
+ *   GET  /api/pm-items                     → { ok, today, lists: { waiting, today, week, triage, later }, jobs, items,
+ *                                              work: { inbox, today, upcoming, waiting, someday }  open items, placed once here
+ *                                              review, review_days: 7        open items untouched 7 days, most stale first
+ *                                              focus: { suggestions, accepted }   at most 3 suggestions: { key, title, why, item_ids, job }
+ *                                              counts: { inbox, today, upcoming, waiting, someday, review } }
  *   POST /api/pm-items/add    { line }     → { ok, item }            one line: the parser (lib/pm-items.js) reads the parts
- *   POST /api/pm-items/edit   { id, fields }→ { ok, item }            fields: title, due, priority, waiting_on, job
+ *   POST /api/pm-items/edit   { id, fields }→ { ok, item }            fields: title, due, priority, waiting_on, job,
+ *                                              defer, flagged, resolves, kind, person, evidence, outcome
  *   POST /api/pm-items/remove { id }       → { ok, undo_ms }         deleted (created here) or dropped (imported)
  *   POST /api/pm-items/undo   { id }       → { ok, item } | 409      restores the last removal inside the 8 s window
- *   POST /api/pm-items/done   { id }       → { ok }                  folds to item.done + done_at;  /reopen undoes it
+ *   POST /api/pm-items/done   { id, outcome? } → { ok }              folds to item.done + done_at (+ outcome, one line);  /reopen undoes it
  *   POST /api/pm-items/park   { id }       → { ok }                  parked: true, placed in Later;  /unpark clears it
+ *   POST /api/pm-items/flag   { id, flagged }       → { ok }         flagged: boolean; a flagged item is in Today
+ *   POST /api/pm-items/defer  { id, until|null }    → { ok }         defer: not before that date (null clears); clears parked
+ *   POST /api/pm-items/someday { id }               → { ok }         parked: true, placed in Someday
+ *   POST /api/pm-items/waiting { id, on|null }      → { ok }         waiting_on and waiting_since (null clears); clears parked
+ *   POST /api/pm-items/notyet { id, when }          → { ok }         when: later-today | tomorrow | next-week; adds 1 to not_yet_count;
+ *                                              tomorrow and next-week set defer (next Monday), later-today sets nudge_at (now + 3 h)
+ *   POST /api/pm-items/keep   { id }                → { ok }         the Review pass kept it: event 'kept', touched_at moves
+ *   POST /api/pm-items/focus/accept  { key, title, why, item_ids, job? } → { ok }   today's Focus (focus.jsonl)
+ *   POST /api/pm-items/focus/dismiss { key }        → { ok }         not suggested again today
+ *   POST /api/pm-items/focus/clear   { key }        → { ok }         forget the accept or the dismissal
  *   POST /api/pm-items/move   { id, list } → { ok }                  list_override, one of the five lists
  *   POST /api/pm-items/steps/add  { id, text, who? } → { ok, step }  outward steps are forced to agent-drafts
  *   POST /api/pm-items/steps/who  { step_id, who }   → { ok, who }
@@ -16,7 +32,7 @@
  *   POST /api/pm-jobs/edit    { id, fields }→ { ok, job }            fields: when, want, so
  *   POST /api/pm-jobs/delete  { id, reassign_to? } → { ok, reassigned }   items move to reassign_to, or to none
  *
- * STATE. Two append-only files under <runtime>/pm-items/: items.jsonl and jobs.jsonl. Every write is one appended line
+ * STATE. Append-only files under <runtime>/pm-items/: items.jsonl, jobs.jsonl, steps.jsonl and focus.jsonl. Every write is one appended line
  * through pm-items.appendEvent, the single writer, and the GET folds the whole file again. Nothing is read from Jira.
  *
  * WHO WRITES. Every POST passes pm-guard requirePagePress: the page only, with the Origin and nonce checks. An agent
@@ -28,9 +44,12 @@ const crypto = require('crypto');
 const guard = require('./pm-guard.js');
 const pmItems = require('./pm-items.js');
 const jobs = require('./jobs-to-be-done.js');
+const workFocus = require('./work-focus.js');
 const steps = require('./item-steps.js');
 
-const FIELDS = ['title', 'due', 'priority', 'waiting_on', 'job'];
+const FIELDS = ['title', 'due', 'priority', 'waiting_on', 'job', 'defer', 'flagged', 'resolves', 'kind', 'person', 'evidence', 'outcome'];
+const STRING_OR_NULL = ['resolves', 'person', 'evidence', 'outcome'];
+const NOT_YET = ['later-today', 'tomorrow', 'next-week'];
 const JOB_FIELDS = ['when', 'want', 'so'];
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -38,17 +57,40 @@ const dirOf = (ctx) => path.join(ctx.runtimeDir, 'pm-items');
 const itemsFile = (ctx) => path.join(dirOf(ctx), 'items.jsonl');
 const stepsFile = (ctx) => path.join(dirOf(ctx), 'steps.jsonl');
 const jobsFile = (ctx) => path.join(dirOf(ctx), 'jobs.jsonl');
+const focusFile = (ctx) => path.join(dirOf(ctx), 'focus.jsonl');
 const newId = (prefix) => `${prefix}-${crypto.randomBytes(6).toString('hex')}`;
 
 // The current view, folded from the files. `now` decides placement, so tests can pin the day.
-function view(itemLines, jobLines, now, stepLines = []) {
+// The titles of the team tasks (plan items) that own items advance, so the page can say "Advances: <title>". Best effort: no workspace, no map.
+function resolvesTitles(items, ctx, url) {
+  const ids = [...new Set((items || []).map((i) => i.resolves).filter(Boolean))];
+  if (!ids.length || typeof ctx.getWs !== 'function') return {};
+  try {
+    const w = ctx.getWs(String(url.searchParams.get('ws') || ''));
+    if (!w || !w.root) return {};
+    const fold = require('./plan-items.js').readFold(w.root);
+    const out = {};
+    for (const id of ids) if (fold.items[id] && fold.items[id].title) out[id] = fold.items[id].title;
+    return out;
+  } catch { return {}; }
+}
+
+function view(itemLines, jobLines, now, stepLines = [], focusLines = []) {
   const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
   const byItem = steps.foldSteps(stepLines).byItem;
   const items = pmItems.fold(itemLines).map((i) => ({ ...i, steps: byItem[i.id] || [] }));
   const currentJobs = jobs.foldJobs(jobLines).map((j) => ({ ...j, ...jobs.progress(j.id, items) }));
   const lists = Object.fromEntries(pmItems.LISTS.map((l) => [l, []]));
   for (const it of items) lists[pmItems.placement(it, today)].push(it);
-  return { ok: true, today: today.toISOString().slice(0, 10), lists, jobs: currentJobs, items };
+  const todayIso = today.toISOString().slice(0, 10);
+  const work = Object.fromEntries(pmItems.WORK_LISTS.map((l) => [l, []]));
+  for (const it of items) if (!it.done) work[pmItems.workPlacement(it, today)].push(it);
+  for (const l of pmItems.WORK_LISTS) work[l] = pmItems.sortWorkList(l, work[l], today);
+  const review = pmItems.reviewQueue(items, now);
+  const state = workFocus.foldFocus(focusLines, todayIso);
+  const focus = { suggestions: workFocus.focusSuggestions(work.today, currentJobs, state, todayIso), accepted: state.accepted };
+  const counts = { ...Object.fromEntries(pmItems.WORK_LISTS.map((l) => [l, work[l].length])), review: review.length };
+  return { ok: true, today: todayIso, lists, jobs: currentJobs, items, work, review, review_days: pmItems.REVIEW_DAYS, focus, counts };
 }
 
 // Each operation returns { status, body, events } and writes nothing itself; the caller appends `events`.
@@ -59,6 +101,12 @@ function checkFields(fields, allowed) {
   }
   if ('due' in fields && fields.due !== null && !DATE_RE.test(String(fields.due))) return 'due must be YYYY-MM-DD or null';
   if ('priority' in fields && fields.priority !== null && !/^P[1-3]$/.test(String(fields.priority))) return 'priority must be P1, P2, P3 or null';
+  if ('defer' in fields && fields.defer !== null && !DATE_RE.test(String(fields.defer))) return 'defer must be YYYY-MM-DD or null';
+  if ('flagged' in fields && typeof fields.flagged !== 'boolean') return 'flagged must be true or false';
+  if ('kind' in fields && fields.kind !== null && fields.kind !== 'offline') return 'kind must be offline or null';
+  for (const k of STRING_OR_NULL) {
+    if (k in fields && fields[k] !== null && typeof fields[k] !== 'string') return `${k} must be a string or null`;
+  }
   return null;
 }
 
@@ -98,7 +146,11 @@ function flagItem(body, itemLines, events) {
   if (!item) return noItem;
   return { status: 200, body: { ok: true }, events: typeof events === 'function' ? events(item) : events };
 }
-const doneItem = (b, l) => flagItem(b, l, [{ event: 'done', id: b.id }]);
+function doneItem(b, l) {
+  if (b.outcome !== undefined && b.outcome !== null && typeof b.outcome !== 'string') return { status: 400, body: { ok: false, error: 'outcome must be a string' } };
+  const outcome = typeof b.outcome === 'string' && b.outcome.trim() ? { outcome: b.outcome.trim() } : {};
+  return flagItem(b, l, [{ event: 'done', id: b.id, ...outcome }]);
+}
 const reopenItem = (b, l) => flagItem(b, l, [{ event: 'reopened', id: b.id }]);
 const parkItem = (b, l) => flagItem(b, l, [{ event: 'edited', id: b.id, fields: { parked: true, list_override: null } }]);
 const unparkItem = (b, l) => flagItem(b, l, [{ event: 'edited', id: b.id, fields: { parked: false } }]);
@@ -107,6 +159,53 @@ function moveItem(b, l) {
   return flagItem(b, l, [{ event: 'edited', id: b.id, fields: { list_override: b.list, parked: false } }]);
 }
 
+// Work page routes. A legacy list_override would beat the new placement, so the routes that place an item clear it.
+const bad = (error) => ({ status: 400, body: { ok: false, error } });
+function flagRoute(b, l) {
+  if (typeof b.flagged !== 'boolean') return bad('flagged must be true or false');
+  return flagItem(b, l, [{ event: 'edited', id: b.id, fields: { flagged: b.flagged } }]);
+}
+function deferItem(b, l) {
+  if (b.until !== null && !DATE_RE.test(String(b.until))) return bad('until must be YYYY-MM-DD or null');
+  return flagItem(b, l, [{ event: 'edited', id: b.id, fields: { defer: b.until, parked: false, list_override: null } }]);
+}
+const somedayItem = (b, l) => flagItem(b, l, [{ event: 'edited', id: b.id, fields: { parked: true, list_override: null } }]);
+function waitingItem(b, l, now) {
+  const on = typeof b.on === 'string' ? b.on.trim() : b.on;
+  if (on !== null && (typeof on !== 'string' || !on)) return bad('on must be a name or null');
+  return flagItem(b, l, [{ event: 'edited', id: b.id, fields: { waiting_on: on, waiting_since: on ? now.toISOString() : null, parked: false, list_override: null } }]);
+}
+// "Not yet": tomorrow and next Monday are dates (defer); later today only counts and nudges 3 hours on.
+// Dates follow the server's UTC day, as the placement does.
+function notYetItem(b, l, now) {
+  if (!NOT_YET.includes(b.when)) return bad('when must be one of ' + NOT_YET.join(', '));
+  return flagItem(b, l, (item) => {
+    const fields = { not_yet_count: (item.not_yet_count || 0) + 1 };
+    const day = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    const plus = (n) => new Date(day.getTime() + n * 86400000).toISOString().slice(0, 10);
+    if (b.when === 'later-today') fields.nudge_at = new Date(now.getTime() + 3 * 3600000).toISOString();
+    else {
+      fields.defer = b.when === 'tomorrow' ? plus(1) : plus(((1 - day.getUTCDay() + 7) % 7) || 7);
+      fields.nudge_at = null;
+      fields.list_override = null;
+    }
+    return [{ event: 'edited', id: b.id, fields }];
+  });
+}
+const keepItem = (b, l) => flagItem(b, l, [{ event: 'kept', id: b.id }]);
+
+// Focus events go to focus.jsonl. The day comes from the server date, never from the page.
+function focusEvent(kind, b, now) {
+  if (typeof b.key !== 'string' || !b.key) return bad('key is required');
+  const day = now.toISOString().slice(0, 10);
+  if (kind !== 'accepted') return { status: 200, body: { ok: true }, events: [{ event: kind, key: b.key, day }] };
+  if (typeof b.title !== 'string' || !b.title.trim()) return bad('title is required');
+  if (typeof b.why !== 'string') return bad('why must be a string');
+  if (!Array.isArray(b.item_ids) || b.item_ids.some((x) => typeof x !== 'string')) return bad('item_ids must be a list of item ids');
+  if (b.job !== undefined && b.job !== null && typeof b.job !== 'string') return bad('job must be a string or null');
+  return { status: 200, body: { ok: true }, events: [{ event: 'accepted', key: b.key, title: b.title.trim(), why: b.why, item_ids: b.item_ids, job: b.job || null, day }] };
+}
+
 function addStepRoute(b, itemLines) {
   if (!findItem(itemLines, b.id)) return noItem;
   const id = newId('step');
@@ -172,6 +271,15 @@ const ROUTES = {
   'POST /api/pm-items/park': (b, ctx) => ({ ...parkItem(b, ctx.itemLines), file: 'items' }),
   'POST /api/pm-items/unpark': (b, ctx) => ({ ...unparkItem(b, ctx.itemLines), file: 'items' }),
   'POST /api/pm-items/move': (b, ctx) => ({ ...moveItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/flag': (b, ctx) => ({ ...flagRoute(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/defer': (b, ctx) => ({ ...deferItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/someday': (b, ctx) => ({ ...somedayItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/waiting': (b, ctx) => ({ ...waitingItem(b, ctx.itemLines, ctx.now || new Date()), file: 'items' }),
+  'POST /api/pm-items/notyet': (b, ctx) => ({ ...notYetItem(b, ctx.itemLines, ctx.now || new Date()), file: 'items' }),
+  'POST /api/pm-items/keep': (b, ctx) => ({ ...keepItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/focus/accept': (b, ctx) => ({ ...focusEvent('accepted', b, ctx.now || new Date()), file: 'focus' }),
+  'POST /api/pm-items/focus/dismiss': (b, ctx) => ({ ...focusEvent('dismissed', b, ctx.now || new Date()), file: 'focus' }),
+  'POST /api/pm-items/focus/clear': (b, ctx) => ({ ...focusEvent('cleared', b, ctx.now || new Date()), file: 'focus' }),
   'POST /api/pm-items/steps/add': (b, ctx) => ({ ...addStepRoute(b, ctx.itemLines), file: 'steps' }),
   'POST /api/pm-items/steps/who': (b, ctx) => ({ ...stepWho(b, ctx.stepLines), file: 'steps' }),
   'POST /api/pm-items/steps/plan': (b, ctx) => ({ ...planSteps(b, ctx.itemLines), file: 'steps' }),
@@ -181,17 +289,19 @@ const ROUTES = {
 };
 
 function prepare(ctx, now = new Date()) {
-  return { itemLines: pmItems.readLines(itemsFile(ctx)), jobLines: pmItems.readLines(jobsFile(ctx)), stepLines: pmItems.readLines(stepsFile(ctx)), now };
+  return { itemLines: pmItems.readLines(itemsFile(ctx)), jobLines: pmItems.readLines(jobsFile(ctx)), stepLines: pmItems.readLines(stepsFile(ctx)), focusLines: pmItems.readLines(focusFile(ctx)), now };
 }
 
 module.exports = {
   prefixes: ['/api/pm-items', '/api/pm-jobs'],
-  view, doneItem, reopenItem, parkItem, unparkItem, moveItem, addStepRoute, stepWho, planSteps, addItem, editItem, removeItem, undoItem, addJob, editJob, deleteJob, checkFields, ROUTES, prepare,
+  view, resolvesTitles, flagRoute, deferItem, somedayItem, waitingItem, notYetItem, keepItem, focusEvent, doneItem, reopenItem, parkItem, unparkItem, moveItem, addStepRoute, stepWho, planSteps, addItem, editItem, removeItem, undoItem, addJob, editJob, deleteJob, checkFields, ROUTES, prepare,
   handle: async (req, res, url, ctx) => {
     const p = url.pathname;
     if (p === '/api/pm-items' && req.method === 'GET') {
       const c = prepare(ctx);
-      ctx.json(res, view(c.itemLines, c.jobLines, c.now, c.stepLines));
+      const v = view(c.itemLines, c.jobLines, c.now, c.stepLines, c.focusLines);
+      v.resolves_titles = resolvesTitles(v.items, ctx, url);
+      ctx.json(res, v);
       return true;
     }
     const key = `${req.method} ${p}`;
@@ -207,7 +317,7 @@ module.exports = {
       for (const ev of r.events) {
         const which = ev._file || r.file;
         const { _file, ...line } = ev;
-        pmItems.appendEvent(which === 'jobs' ? jobsFile(ctx) : which === 'steps' ? stepsFile(ctx) : itemsFile(ctx), line, c.now);
+        pmItems.appendEvent(which === 'jobs' ? jobsFile(ctx) : which === 'steps' ? stepsFile(ctx) : which === 'focus' ? focusFile(ctx) : itemsFile(ctx), line, c.now);
       }
     }
     ctx.json(res, r.body, r.status);