create-pmos 0.52.0 → 0.53.1

package/workspace/lib/initiative-cli.js

@@ -0,0 +1,222 @@
+'use strict';
+/* initiative-cli.js — `pmos initiative …`: initiatives and their place on the Roadmap from a terminal (pm-os-absorb
+ * Run 2, PRD R16, R20 A, R23, R24, R25; D86 point 4).
+ *
+ *   pmos initiative new "<title>" --lane <lane> --anchor <KR|health:id> [--intent "<text>"] [--id <id>]
+ *   pmos initiative new --from capture-YYYY-MM-DD-<n> [--anchor …] [--lane …] [--title "…"]
+ *   pmos initiative now <id>                     PM only: type the id to confirm
+ *   pmos initiative next|later <id> [--top]      to the end of that horizon, or its top
+ *   pmos initiative top|up|down <id>             reorder inside its horizon (in Now: PM only)
+ *   pmos initiative check-by <id> <YYYY-MM-DD|none>
+ *   pmos initiative adopt <proposal-eid>         PM only: type the eid to confirm
+ *   pmos initiative drop <proposal-eid>
+ *   pmos initiative list
+ *   pmos initiative export <id>                  the breakdown as markdown on stdout; nothing is written
+ *   every command: [--json] [--root <dir>]
+ *
+ * The SAME writers the workspace page uses (lib/initiative-writer.js, lib/placements.js) — no server is needed. Who
+ * wrote a line comes from the call path, never from an argument: a PM-only act (Move to Now, adopt, and any line into
+ * Now) goes through lib/pm-guard.js requirePmCli — an interactive terminal with no agent session, and the PM types the
+ * confirmation; every other command takes lib/actor.js fromCli: the PM at a terminal, the bound agent session from
+ * PMOS_SESSION, `agent:unknown` otherwise. An agent's placement is written as a proposal (`proposed: true`).
+ * Work lanes only (D86 point 4): `list` and `export` leave document-lane initiatives out.
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const placements = require('./placements.js');
+const writer = require('./initiative-writer.js');
+const rowsLib = require('./initiative-rows.js');
+const planRules = require('./plan-rules.js');
+const breakdownExport = require('./breakdown-export.js');
+const triage = require('./triage.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { initiative: ['new', 'now', 'next', 'later', 'top', 'up', 'down', 'check-by', 'adopt', 'drop', 'list', 'export'] };
+const USAGE = [
+  'usage: pmos initiative new|now|next|later|top|up|down|check-by|adopt|drop|list|export — initiatives on the Roadmap',
+  '  pmos initiative new "<title>" --lane <lane> --anchor <KR|health:id> [--intent "<text>"] [--id <id>]',
+  '  pmos initiative new --from capture-YYYY-MM-DD-<n> [--anchor <anchor>] [--lane <lane>] [--title "<title>"]',
+  '  pmos initiative now <id>                 move it into Now (you only; type the id to confirm)',
+  '  pmos initiative next|later <id> [--top]  move it to the end of Next or Later, or to its top',
+  '  pmos initiative top|up|down <id>         reorder it inside its horizon',
+  '  pmos initiative check-by <id> <YYYY-MM-DD|none>',
+  '  pmos initiative adopt <proposal>         keep an agent proposal (you only; type the proposal to confirm)',
+  '  pmos initiative drop <proposal>          close an agent proposal',
+  '  pmos initiative list                     Now, Next and Later, in order',
+  '  pmos initiative export <id>              the breakdown as markdown on stdout',
+  '  every command: [--json] [--root <dir>]',
+  'An agent session writes a placement as a proposal for you to keep or drop. A new initiative lands in Later.',
+];
+const BOOL = new Set(['json', 'top', 'help']);
+const VALUE = new Set(['lane', 'anchor', 'intent', 'id', 'from', 'title', 'root']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now, ask } = {}) {
+  const args = argv[0] === 'initiative' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags } = parse(args.slice(1));
+  const json = !!flags.json;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) {
+    for (const l of USAGE) say(l);
+    return verb ? 0 : 1;
+  }
+  if (!COMMANDS.initiative.includes(verb)) { say(`unknown initiative command "${verb}" — one of ${COMMANDS.initiative.join(', ')}`); return 2; }
+  if ('by' in flags || 'via' in flags) { say(`attribution is set from the call path; --${'by' in flags ? 'by' : 'via'} is not accepted`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const who = { isTTY: isTTY === undefined ? !!(process.stdin.isTTY && process.stdout.isTTY) : isTTY, env: env === undefined ? process.env : env };
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const done = (obj, line) => { if (json) say(JSON.stringify({ ok: true, ...obj })); else say(line); return 0; };
+  const pmPress = (act, expect) => guard.requirePmCli({ act, expect, isTTY: who.isTTY, env: who.env, ask: ask || guard.askAtTerminal });
+  const order = () => {
+    const d = rowsLib.deriveSync(root);
+    if (!d.ok) return { error: d.error };
+    return { placed: placements.readPlacements(root, { now: now == null ? Date.now() : now, rules: planRules.readRules(root), records: d.rows }), rows: d.rows };
+  };
+  const write = (events, actor) => placements.appendFromCli(root, events, { actor, now });
+  const said = (r, what) => (r.lines && r.lines[0] && r.lines[0].proposed ? `${what} — written as a proposal for the PM to keep or drop` : what);
+
+  if (verb === 'new') {
+    let input = {};
+    if (flags.from) {
+      const p = triage.proposalFor(root, flags.from);
+      if (!p) return fail(`no capture ${flags.from} in this repository`);
+      if (p.done) return fail(`${flags.from} was added already, as ${p.initiative}`);
+      if (p.empty) return fail(`${flags.from} holds no text; write the idea in the note first`);
+      input = { title: p.title, lane: p.lane, from: p.capture };
+      if (p.anchor) input.anchor = p.anchor;
+      if (p.rejection && !json) say(`! ${flags.from} matches an earlier rejection: ${p.rejection.path}. Read it before you add this.`);
+    } else {
+      if (!pos[0]) { say('usage: pmos initiative new "<title>" --lane <lane> --anchor <anchor> [--intent "<text>"] [--id <id>]'); return 2; }
+      input.title = pos[0];
+    }
+    if (flags.title) input.title = flags.title;
+    for (const k of ['lane', 'anchor', 'intent', 'id']) if (flags[k]) input[k] = flags[k];
+    const r = writer.createInitiative(root, input, { actor: actorLib.fromCli(who), now });
+    if (!r.ok) return fail(r.error);
+    return done({ id: r.id, path: r.path }, `✓ ${r.id} added to Later (${r.path}). Commit the record to keep it.`);
+  }
+
+  if (verb === 'list') {
+    const o = order();
+    if (o.error) return fail(o.error);
+    const titles = new Map(o.rows.map((r) => [r.id, r.title || r.id]));
+    if (json) { say(JSON.stringify({ ok: true, order: o.placed.order, byInit: o.placed.byInit, proposals: o.placed.proposals.map((p) => ({ ...p, by: actorLib.pageName(p.by) })) })); return 0; }
+    for (const h of placements.HORIZONS) {
+      const ids = o.placed.order[h];
+      const dormant = h === 'later' ? ids.filter((id) => o.placed.byInit[id].dormant).length : 0;
+      say(`${h[0].toUpperCase()}${h.slice(1)} · ${ids.length}${dormant ? ` (${dormant} dormant)` : ''}`);
+      for (const id of ids) {
+        const p = o.placed.byInit[id];
+        const bits = [];
+        if (h === 'now' && !p.confirmed) bits.push('unconfirmed');
+        if (p.check_by) bits.push(`check by ${p.check_by}`);
+        if (p.dormant) bits.push('dormant');
+        say(`  ${p.rank + 1}. ${id} — ${titles.get(id)}${bits.length ? ' · ' + bits.join(' · ') : ''}`);
+      }
+    }
+    for (const p of o.placed.proposals) say(`proposal ${p.eid}: ${p.init} to ${p.horizon} · ${actorLib.pageName(p.by)}`);
+    return 0;
+  }
+
+  if (verb === 'export') {
+    const id = pos[0];
+    if (!id) { say('usage: pmos initiative export <id>'); return 2; }
+    const r = breakdownExport.exportBreakdown(root, id);
+    if (!r.ok) return fail(r.error);
+    if (json) say(JSON.stringify({ ok: true, id, markdown: r.markdown })); else say(r.markdown);
+    return 0;
+  }
+
+  if (verb === 'adopt' || verb === 'drop') {
+    const eid = pos[0];
+    if (!eid) { say(`usage: pmos initiative ${verb} <proposal>`); return 2; }
+    let actor;
+    if (verb === 'adopt') {
+      const g = await pmPress('adopt', eid);
+      if (!g.ok) return fail(g.error);
+      actor = g.actor;
+    } else actor = actorLib.fromCli(who);
+    const r = write([{ ev: verb === 'adopt' ? 'adopted' : 'dropped', proposal: eid }], actor);
+    if (!r.ok) return fail(r.error);
+    return done({ written: r.written }, `✓ proposal ${eid} ${verb === 'adopt' ? 'kept' : 'dropped'}`);
+  }
+
+  const id = pos[0];
+  if (!id) { say(`usage: pmos initiative ${verb} <id>${verb === 'check-by' ? ' <YYYY-MM-DD|none>' : ''}`); return 2; }
+
+  if (verb === 'now' || verb === 'next' || verb === 'later') {
+    // After the last line of that horizon in the LEDGER's order, so no workflow derivation is needed (fast). Day one's
+    // rows are seeded before the lines (placements.js), so the ones no line was placed after sort below it. --top puts
+    // it first.
+    const ledgerOnly = placements.readPlacements(root);
+    const list = ledgerOnly.order[verb].filter((x) => x !== id);
+    const after = flags.top ? null : (list.length ? list[list.length - 1] : null);
+    let actor;
+    if (verb === 'now') {
+      const g = await pmPress('now', id);
+      if (!g.ok) return fail(g.error);
+      actor = g.actor;
+    } else actor = actorLib.fromCli(who);
+    const r = write([{ ev: 'placed', initiative: id, horizon: verb, after }], actor);
+    if (!r.ok) return fail(r.error);
+    return done({ written: r.written, proposed: r.lines[0].proposed }, said(r, `✓ ${id} moved to ${verb[0].toUpperCase()}${verb.slice(1)}${flags.top ? ', at the top' : ''}`));
+  }
+
+  // top | up | down | check-by: the whole order, day one included.
+  const o = order();
+  if (o.error) return fail(o.error);
+  const cur = o.placed.byInit[id];
+  if (!cur) return fail(`no work-lane initiative ${id} in this repository`);
+  const list = o.placed.order[cur.horizon];
+  const i = list.indexOf(id);
+  const ev = { ev: 'placed', initiative: id, horizon: cur.horizon };
+  let what;
+  if (verb === 'check-by') {
+    const v = pos[1];
+    if (!v || !(v === 'none' || DATE_RE.test(v))) { say('usage: pmos initiative check-by <id> <YYYY-MM-DD|none>'); return 2; }
+    ev.after = i > 0 ? list[i - 1] : null;
+    ev.check_by = v === 'none' ? null : v;
+    what = v === 'none' ? `✓ ${id}: check-by cleared` : `✓ ${id}: check by ${v}`;
+  } else if (verb === 'top' || verb === 'up') {
+    if (i === 0) return done({ written: 0 }, `${id} is at the top of ${cur.horizon} already`);
+    ev.after = verb === 'top' || i === 1 ? null : list[i - 2];
+    what = `✓ ${id} moved ${verb === 'top' ? 'to the top' : 'up'}`;
+  } else {
+    if (i === list.length - 1) return done({ written: 0 }, `${id} is at the end of ${cur.horizon} already`);
+    ev.after = list[i + 1];
+    what = `✓ ${id} moved down`;
+  }
+  let actor;
+  if (cur.horizon === 'now') {
+    const g = await pmPress('now', id);
+    if (!g.ok) return fail(g.error);
+    actor = g.actor;
+  } else actor = actorLib.fromCli(who);
+  const r = write([ev], actor);
+  if (!r.ok) return fail(r.error);
+  return done({ written: r.written, proposed: r.lines[0].proposed }, said(r, what));
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/initiative-display.js

@@ -0,0 +1,183 @@
+'use strict';
+// initiative-display.js — the words an initiative shows: one derived word, the stage, who it waits on and line 2
+// (pm-os-absorb, PRD R3, R5, R13). Nobody types a status: every field is read from a workflow row and the ledgers.
+//
+//   displayOf(row, ctx) → { word, stage, waitingOn: 'pm'|'agent'|null, act, idleDays, line2 }
+//   idleDays(lastActivity, now) → whole days since the last evidence, or null when there is none
+//
+// `row` is a workflow row (scripts/workflow-state.js computeWorkflow). `ctx` may carry
+// { lifecycle, acceptance, handoff, fold, placement, rules, now }; a missing field is read as unknown, never as a state.
+// THE ctx SUB-SHAPES (frozen; the producers 2C and 5A assemble them, 2D's rules read them):
+//   lifecycle  : { state: 'active'|'held'|'closed'|'cancelled', reason, at } | null   the server's lifecycle fold for this
+//                id (the same object lib/next-steps.js reads as `lifecycle`); null = active
+//   acceptance : { at, by } | null                       the PM's Acceptance record for this id (by mapped via actor.pageName)
+//   handoff    : { item, session } | null                a live Hand-to-agent session for one of this id's plan items:
+//                item = plan item id, session = 'agent:sess-<n>' (actor.pageName)
+//   fold       : { items, order, batches, flags }        lib/plan-items.js readFold(root) narrowed to this initiative
+//   placement  : placements.readPlacements(root).byInit[id] | null
+//   rules      : lib/plan-rules.js readRules(root)
+//   now        : epoch milliseconds
+// Two optional keys let a caller that knows the lane word the stage and the document step the way the Breakdown does:
+//   stageLabel : the stage's label ("PRD") for `word`; without it the stage id, capitalised ("Build")
+//   stepNoun   : { brief, draft } the lane's own nouns for those two steps, as lib/plan-tree.js nounFor reads them
+//
+// One mapping for every surface: the Initiatives views and the report blocks (Runs 2 and 5) and, when Run 3 swaps the
+// old surfaces, the cockpit, Today and the status banner. Classic script (a UMD setting window.PMOSInitiativeDisplay)
+// like status-groups.js, served from /lib/, so the same words are walkable in node over every record.
+//
+// THE RULES (PRD R3), in the order they are tried:
+//   1. a lifecycle line that is not `active` reads On hold, Closed or Cancelled, and nothing else is shown;
+//   2. an initiative with an acceptance reads Accepted (code profile) or Handed off (pm-artifacts, once no Handoff step is
+//      open), whatever its next step: leftover ladder steps are History notes (leftoverSteps), never an act it owes;
+//   3. anything else reads stage · waiting on · act ("Build · waiting on you: approval"). The owed step is the first open
+//      step of the ladder: a step that reads `na`, `unknown` or `done` neither blocks nor counts as owed.
+// An initiative counts as moving only with evidence within `stall_days`: a live session, an item in Doing or Review, or a
+// commit or ledger event (the row's last_activity, or an item's last write). Without it, line 2 ends "idle 12 d".
+// Nothing here reads a `status:` line; chores keep writing it because the gate reads it, and it never reaches the display.
+//
+// Used by 2C's route rows and 5A's blocks, and by the Initiatives views through those rows. Run 3 points the old surfaces
+// here. `STEP_ACT` and `PM_STEPS` mirror lib/plan-tree.js (STEP_NOUN, OWED_ACTOR) and lib/next-steps.js (PM_STEPS):
+// this file is served to the page and cannot require them, and r3-display.test.js fails when the three drift apart.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSInitiativeDisplay = api;
+}(typeof self !== 'undefined' ? self : this, function () {
+  const DAY = 86400000;
+  const DEFAULT_STALL_DAYS = 5;
+
+  // The noun of the owed step, as the Breakdown's owed row names it (lib/plan-tree.js STEP_NOUN).
+  const STEP_ACT = Object.freeze({
+    route: 'routing', anchor: 'anchor', prototype: 'prototype', understand: 'explainer', spec: 'spec', priors: 'priors',
+    contract: 'contract', build: 'build', quality: 'checks', review: 'review', explain: 'run explainer', accept: 'acceptance',
+    outcome: 'outcome check', brief: 'brief', draft: 'draft', approved: 'approval', handoff: 'handoff',
+  });
+  // The steps only the PM can do: the gate on a contract, a document or an acceptance, an outcome check, a handoff.
+  const PM_STEPS = Object.freeze(['accept', 'contract', 'approved', 'outcome', 'handoff']);
+  const LIFECYCLE_WORD = Object.freeze({ held: 'On hold', 'on-hold': 'On hold', closed: 'Closed', cancelled: 'Cancelled' });
+  const OPEN_STATUS = (s) => s !== 'done' && s !== 'na' && s !== 'unknown';
+
+  /** A time as epoch milliseconds: an ISO string, a number of milliseconds, or the engine's epoch seconds. */
+  function toMs(t) {
+    if (typeof t === 'number' && Number.isFinite(t)) return t < 1e11 ? t * 1000 : t;
+    const n = Date.parse(String(t || ''));
+    return Number.isFinite(n) ? n : null;
+  }
+
+  function idleDays(lastActivity, now) {
+    const t = toMs(lastActivity);
+    const n = typeof now === 'number' ? now : Date.now();
+    if (t === null) return null;
+    return Math.max(0, Math.floor((n - t) / DAY));
+  }
+
+  const itemsOf = (fold) => {
+    const it = fold && fold.items;
+    return Array.isArray(it) ? it : it && typeof it === 'object' ? Object.values(it) : [];
+  };
+  const mine = (it, id) => !id || !it.initiative || it.initiative === id;
+
+  /**
+   * The evidence an initiative has: { at, moving }. `at` is the latest time of a commit or ledger event (the row's
+   * last_activity, an item's last write), in epoch milliseconds, or null. `moving` is true for a live session or an item
+   * in Doing or Review, which is evidence now whatever the clock says.
+   */
+  function evidenceOf(row, ctx) {
+    const r = row || {};
+    const c = ctx || {};
+    let at = toMs(r.last_activity);
+    let moving = !!c.handoff;
+    for (const it of itemsOf(c.fold)) {
+      if (!it || !mine(it, r.id) || it.state === 'withdrawn' || it.proposed) continue;
+      if (it.state === 'doing' || it.state === 'review') moving = true;
+      const t = toMs(it.updatedAt);
+      if (t !== null && (at === null || t > at)) at = t;
+    }
+    return { at, moving };
+  }
+
+  const stallDays = (ctx) => {
+    const n = ctx && ctx.rules && ctx.rules.stall_days;
+    return Number.isInteger(n) && n > 0 ? n : DEFAULT_STALL_DAYS;
+  };
+
+  /** True when an initiative has no evidence within stall_days (R3). One with no evidence at all is idle too. */
+  function isIdle(row, ctx) {
+    const ev = evidenceOf(row, ctx);
+    if (ev.moving) return false;
+    const days = idleDays(ev.at, ctx && typeof ctx.now === 'number' ? ctx.now : undefined);
+    return days === null || days >= stallDays(ctx);
+  }
+
+  /** "idle 12 d", or "idle" when there is no evidence at all, or null when the initiative has evidence within stall_days. */
+  function idleLabel(row, ctx) {
+    if (!isIdle(row, ctx)) return null;
+    const ev = evidenceOf(row, ctx);
+    const d = idleDays(ev.at, ctx && typeof ctx.now === 'number' ? ctx.now : undefined);
+    return d === null ? 'idle' : `idle ${d} d`;
+  }
+
+  /** The steps still owed, in ladder order: not done, `na` or `unknown`. */
+  function owedSteps(row) {
+    const steps = row && Array.isArray(row.steps) ? row.steps : [];
+    return steps.filter((s) => s && OPEN_STATUS(s.status));
+  }
+
+  /** The owed step the engine names as next, else the first open one, or null. */
+  function owedStep(row) {
+    const open = owedSteps(row);
+    const named = row && row.next && row.next.step;
+    return open.find((s) => s.key === named) || open[0] || null;
+  }
+
+  /** What an accepted or handed-off initiative still carries on its ladder: History notes, never owed acts. */
+  function leftoverSteps(row) { return owedSteps(row).map((s) => s.key); }
+
+  const isPmProfile = (row) => !!row && row.profile === 'pm-artifacts';
+  const capital = (s) => (s ? s.charAt(0).toUpperCase() + s.slice(1) : s);
+
+  function finished(row, ctx) {
+    const accepted = !!(row && row.accepted) || !!(ctx && ctx.acceptance);
+    if (!accepted) return null;
+    if (!isPmProfile(row)) return 'Accepted';
+    const handoff = (row.steps || []).find((s) => s && s.key === 'handoff');
+    return handoff && OPEN_STATUS(handoff.status) ? null : 'Handed off';
+  }
+
+  /** "Waiting on you: approval", "Waiting on agent: build", or '' when nothing is owed. */
+  function waitingLine(on, act) {
+    return on && act ? `Waiting on ${on === 'pm' ? 'you' : 'agent'}: ${act}` : '';
+  }
+
+  function displayOf(row, ctx) {
+    const r = row || {};
+    const c = ctx || {};
+    const stage = typeof r.stage === 'string' && r.stage ? r.stage : null;
+    const out = { word: '', stage, waitingOn: null, act: null, idleDays: null, line2: '' };
+    const ev = evidenceOf(r, c);
+    out.idleDays = idleDays(ev.at, c.now);   // days since the last commit or ledger event; a live session does not reset it
+
+    const lc = c.lifecycle && c.lifecycle.state ? c.lifecycle : null;
+    if (lc && LIFECYCLE_WORD[lc.state]) {
+      out.word = LIFECYCLE_WORD[lc.state];
+      out.line2 = lc.reason ? String(lc.reason) : '';
+      return out;
+    }
+    const done = finished(r, c);
+    if (done) { out.word = done; return out; }
+
+    out.word = (typeof c.stageLabel === 'string' && c.stageLabel) || capital(stage) || 'Unknown';
+    const step = owedStep(r);
+    if (step) {
+      out.waitingOn = PM_STEPS.includes(step.key) ? 'pm' : 'agent';
+      out.act = (step.key === 'brief' || step.key === 'draft') && c.stepNoun && c.stepNoun[step.key] ? c.stepNoun[step.key] : (STEP_ACT[step.key] || step.key);
+    }
+    const parts = [waitingLine(out.waitingOn, out.act)];
+    const idle = idleLabel(r, c);
+    if (idle) parts.push(idle);
+    out.line2 = parts.filter(Boolean).join(' · ');
+    return out;
+  }
+
+  return { displayOf, idleDays, idleLabel, evidenceOf, isIdle, owedSteps, owedStep, leftoverSteps, STEP_ACT, PM_STEPS };
+}));

package/workspace/lib/initiative-needs.js

@@ -0,0 +1,127 @@
+'use strict';
+/* initiative-needs.js — the needs provider of the Initiatives layer (pm-os-absorb Run 2, slice 2C; PRD R12 kinds 6, 7
+ * and 8, R16, R26). lib/needs-providers.js folds these rows into server.js deriveNeeds, and from there into /api/needs
+ * and Today. The row shapes are held to fixtures/today-api/provider-rows.json.
+ *
+ *   kinds: triage (6), cycle-review (7), no-anchor (8)
+ *   rowsFor(w, { lead }) → rows · sig(w) → string
+ *
+ *   triage        one row per capture note not yet added (lib/triage.js): "Proposed: <title> · <lane> · <anchor>".
+ *                 A capture whose words match a file under planning/out-of-scope/ says "matches an earlier rejection"
+ *                 in today.cause and names that file in today.evidence. Act: Add (`pmos initiative new --from …`).
+ *   cycle-review  ONE row (R12 kind 7) while the cycle holds something to confirm: day one's unconfirmed Now
+ *                 initiatives (R26), agent proposals not kept or dropped (R23), and passed check-by dates. 2D draws it.
+ *   no-anchor     one row per work-lane initiative record with no parent_kr (R12 kind 8, "old records have no anchor").
+ *
+ * Every row is repository-wide, so a tree that is not the lead returns []. A row never carries a session token: no
+ * `by` is answered at all. The day-one and no-anchor rows need the workflow rows. They are read with
+ * lib/initiative-rows.js rowsFor(): it answers from the cache at once and starts a derivation in a child process (about
+ * 260 ms per record) when the cache is empty or stale, so no request waits for it. A failed refresh keeps the last good
+ * answer, so once the rows are in they stay on every read. Until the first derivation lands, banner(w) puts a pending
+ * line in Today's state-health banner (lib/needs-providers.js bannersFor), so the rows never pop in unannounced.
+ * sig(w) folds the ledgerSig of placements, measurements and plan-items, the records signature, the cached derivation
+ * (cachedSig: it changes when a derivation lands) and the capture folder, so /api/needs recounts when any of them
+ * changes (seams §4.9).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ledgers = require('./plan-ledgers.js');
+const placements = require('./placements.js');
+const planRules = require('./plan-rules.js');
+const rowsLib = require('./initiative-rows.js');
+const triage = require('./triage.js');
+
+const NAME = 'initiative-needs';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+function ledgerRel(root, name) {
+  try { return path.relative(root, ledgers.ledgerPath(root, name)).split(path.sep).join('/'); } catch { return `planning/runs/${ledgers.LEDGERS[name].file}`; }
+}
+
+function triageRows(root) {
+  const t = triage.triage(root);
+  return t.proposals.map((p) => {
+    const anchor = p.anchor || 'no anchor yet';
+    return {
+      run_id: `${NAME}:triage:${p.capture}`, kind: 'triage', initiative_id: null,
+      question: `Proposed: ${p.title} · ${p.laneLabel} · ${anchor}`, doc: null,
+      today: {
+        kind: 6, source: NAME,
+        cause: p.rejection ? `A capture was triaged; it matches an earlier rejection: ${p.rejection.title}` : 'A capture was triaged',
+        evidence: p.rejection ? p.rejection.path : p.path,
+        act: { label: 'Add', cli: `pmos initiative new --from ${p.capture}` },
+      },
+    };
+  });
+}
+
+function cycleRow(root, records, now) {
+  const rules = planRules.readRules(root);
+  const placed = placements.readPlacements(root, { now, rules, records });
+  const today = new Date(now).toISOString().slice(0, 10);
+  const unconfirmed = placed.order.now.filter((id) => placed.byInit[id].source === 'day-one');
+  const passed = Object.entries(placed.byInit).filter(([, p]) => p.check_by && p.check_by < today).map(([id]) => id);
+  const proposals = placed.proposals.length;
+  if (!unconfirmed.length && !passed.length && !proposals) return [];
+  const parts = [];
+  if (unconfirmed.length) parts.push(`Day one: ${plural(unconfirmed.length, 'initiative reads', 'initiatives read')} Now, unconfirmed`);
+  if (proposals) parts.push(`${plural(proposals, 'agent proposal', 'agent proposals')} to keep or drop`);
+  if (passed.length) parts.push(`${plural(passed.length, 'check-by date', 'check-by dates')} passed`);
+  return [{
+    run_id: `${NAME}:cycle:${today}`, kind: 'cycle-review', initiative_id: null,
+    question: unconfirmed.length ? 'Confirm what is in Now' : 'Review the cycle', doc: null,
+    today: { kind: 7, source: NAME, cause: parts.join('; '), evidence: ledgerRel(root, 'placements'), act: { label: 'Review', cli: null } },
+  }];
+}
+
+function noAnchorRows(root, records) {
+  return records.filter((r) => r.ok !== false && r.group === 'work' && !String(r.anchor || '').trim()).map((r) => ({
+    run_id: `${NAME}:no-anchor:${r.id}`, kind: 'no-anchor', initiative_id: r.id,
+    question: `${r.title || r.id} has no anchor`, doc: null,
+    today: { kind: 8, source: NAME, cause: 'An initiative record names no KR or health budget',
+      evidence: r.record ? String(r.record) : `planning/initiatives/${r.id}.md`, act: { label: 'Add anchor', cli: null } },
+  }));
+}
+
+function rowsFor(w, { lead } = {}) {
+  if (!lead || !w || !w.root) return [];
+  const root = w.root;
+  const out = triageRows(root);
+  // rowsFor() answers at once from the cache and starts the derivation in a child process when there is none or it is
+  // stale; it never blocks this read. A failed refresh keeps the last good answer, so once the rows are in they stay.
+  // Until the first derivation lands, banner(w) says so on Today instead of rows popping in unannounced.
+  const r = rowsLib.rowsFor(root);
+  if (r.ok) {
+    out.push(...cycleRow(root, r.rows, Date.now()));
+    out.push(...noAnchorRows(root, r.rows));
+  }
+  return out;
+}
+
+/** Today's state-health line while the first derivation of the repository is still running (lead tree only). */
+function banner(w, { lead } = {}) {
+  if (!lead || !w || !w.root) return [];
+  // a repository with no initiative record has nothing to read: no notice
+  const hasRecords = ['planning/initiatives', 'pmos/state/initiatives'].some((d) => { try { return fs.readdirSync(path.join(w.root, d)).some((n) => n.endsWith('.md')); } catch { return false; } });
+  if (!hasRecords) return [];
+  const r = rowsLib.peek(w.root);
+  return r.pending ? [{ source: 'initiative rows', error: 'still reading the initiative records; the Cycle review and missing-anchor cards show when that is done' }] : [];
+}
+
+function sig(w) {
+  if (!w || !w.root) return 'none';
+  const root = w.root;
+  let notes = '';
+  try {
+    const dir = path.join(triage.stateDir(root), 'requirements');
+    notes = fs.readdirSync(dir).filter((n) => triage.NOTE_RE.test(n)).sort()
+      .map((n) => { try { const st = fs.statSync(path.join(dir, n)); return `${n}:${st.size}:${st.mtimeMs}`; } catch { return n; } }).join(',');
+  } catch { notes = 'none'; }
+  let oos = '';
+  try { oos = fs.readdirSync(path.join(root, 'planning', 'out-of-scope')).sort().join(','); } catch { oos = 'none'; }
+  const parts = ['placements', 'measurements', 'plan-items'].map((n) => { try { return ledgers.ledgerSig(root, n); } catch { return 'none'; } });
+  return crypto.createHash('sha1').update([...parts, rowsLib.recordsSig(root), rowsLib.cachedSig(root), notes, oos, new Date().toISOString().slice(0, 10)].join('|')).digest('hex');
+}
+
+module.exports = { kinds: ['triage', 'cycle-review', 'no-anchor'], rowsFor, banner, sig, triageRows, cycleRow, noAnchorRows };