create-pmos 0.52.0 → 0.53.0

package/workspace/lib/item-cli.js

@@ -0,0 +1,195 @@
+'use strict';
+/* item-cli.js — `pmos item …`: an initiative's breakdown items from a terminal (pm-os-absorb Run 1, PRD R24).
+ *
+ *   pmos item add <initiative> "<title>" --stage <id|label> [--due YYYY-MM-DD] [--start YYYY-MM-DD]
+ *                 [--owner you|agent|person:<name>|tracker:<ref>] [--after <id>[,<id>]] [--milestone] [--note "<text>"] [--json]
+ *   pmos item set <item> [--title ..] [--stage ..] [--due ..|none] [--start ..|none] [--owner ..] [--after ids|none]
+ *                 [--milestone|--no-milestone] [--note ..|none] [--blocked "<reason>"|none] [--json]
+ *   pmos item move <item> <todo|doing|review|done> [--evidence <commit|pr|file|session|note>:<ref>] [--json]
+ *   pmos item withdraw <item> [--json]
+ *   pmos item list <initiative> [--json]
+ *   common: [--root <dir>]
+ *
+ * The SAME writer and the SAME fold the workspace page uses (lib/plan-items.js) — no server is needed, and
+ * the terminal and the page cannot disagree about an item. Who wrote a line is decided by the call path,
+ * never by an argument: `pm:wawan` at an interactive terminal, the bound session from PMOS_SESSION, and
+ * `agent:unknown` otherwise. There is no `keep` verb: Keep is the PM's press on the workspace page.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { item: ['add', 'set', 'move', 'withdraw', 'list'] };
+const USAGE = [
+  'usage: pmos item add|set|move|withdraw|list — an initiative\'s breakdown items',
+  '  pmos item add <initiative> "<title>" --stage <stage> [--due YYYY-MM-DD] [--start YYYY-MM-DD]',
+  '                [--owner you|agent|person:<name>|tracker:<ref>] [--after <item>[,<item>]] [--milestone] [--note "<text>"]',
+  '  pmos item set <item> [--title "<title>"] [--stage <stage>] [--due <date>|none] [--start <date>|none] [--owner <owner>]',
+  '                [--after <items>|none] [--milestone|--no-milestone] [--note "<text>"|none] [--blocked "<reason>"|none]',
+  '  pmos item move <item> todo|doing|review|done [--evidence commit|pr|file|session|note:<ref>]',
+  '  pmos item withdraw <item>',
+  '  pmos item list <initiative>',
+  '  every command: [--json] [--root <dir>]',
+  'An item id is <initiative>.<10 characters>. A stage is an id or a label of the initiative\'s stages.',
+  'Who wrote each line comes from where the command runs: you at a terminal, the agent session otherwise.',
+  'Keep is pressed on the workspace page (Breakdown or Today). This command does not write it.',
+];
+const BOOL = new Set(['json', 'milestone', 'no-milestone', 'help']);
+const VALUE = new Set(['title', 'stage', 'due', 'start', 'owner', 'after', 'note', 'blocked', 'evidence', 'root']);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done', withdrawn: 'Withdrawn' };
+
+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; }
+}
+const shortDate = (d) => { if (!d) return null; const t = new Date(d + 'T00:00:00Z'); return `${t.getUTCDate()} ${MONTHS[t.getUTCMonth()]}`; };
+const csv = (v) => String(v).split(',').map((s) => s.trim()).filter(Boolean);
+
+/** One line about an item, for a person. */
+function describe(it, stageLabel) {
+  const bits = [`${it.id} "${it.title}"`, stageLabel || it.stage, STATE_LABEL[it.state] || it.state];
+  if (it.milestone) bits.push('milestone');
+  if (it.due) bits.push(`due ${shortDate(it.due)}`);
+  if (it.blocked) bits.push(`blocked: ${it.blocked.reason}`);
+  if (it.proposed) bits.push('proposed');
+  return bits.join(' · ');
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now } = {}) {
+  const args = argv[0] === 'item' ? 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;          // asked for help → 0; no command at all → 1, as `pmos kg` does
+  }
+  if (verb === 'keep') { say('Keep is written only from the workspace page (Breakdown or Today).'); return 2; }
+  if (!COMMANDS.item.includes(verb)) { say(`unknown item command "${verb}" — one of ${COMMANDS.item.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 cliOpts = {};
+  if (isTTY !== undefined) cliOpts.isTTY = isTTY;
+  if (env !== undefined) cliOpts.env = env;
+  if (now !== undefined) cliOpts.now = now;
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const stageLabelOf = (initiative, id) => { try { const s = planTree.stagesFor(root, initiative).find((x) => x.id === id); return s ? s.label : id; } catch { return id; } };
+  const fresh = (id) => planItems.readFold(root, { now }).items[id] || null;
+
+  if (verb === 'list') {
+    const initiative = pos[0];
+    if (!initiative) { say('usage: pmos item list <initiative> [--json]'); return 2; }
+    if (!planItems.INIT_RE.test(initiative) || !planTree.recordPath(root, initiative)) return fail(`no initiative ${initiative} in this repository`);
+    const r = planItems.readFold(root, { now });
+    const stages = planTree.stagesFor(root, initiative);
+    const idx = (id) => { const i = stages.findIndex((s) => s.id === id); return i === -1 ? stages.length : i; };
+    const items = r.order.map((id) => r.items[id]).filter((it) => it.initiative === initiative)
+      .sort((a, b) => (idx(a.stage) - idx(b.stage)) || (a.order - b.order) || String(a.createdAt).localeCompare(String(b.createdAt)) || a.id.localeCompare(b.id));
+    const progress = planItems.progressOf(r, initiative);
+    if (json) {
+      const { profile } = planTree.profileAndLane(root, initiative);
+      say(JSON.stringify({ ok: true, initiative, profile, progress, items }));
+      return 0;
+    }
+    say(`${initiative} · ${progress.label}`);
+    for (const s of [...stages, { id: null, label: 'Other' }]) {
+      const mine = items.filter((it) => (s.id === null ? idx(it.stage) === stages.length : it.stage === s.id));
+      if (!mine.length) continue;
+      const real = mine.filter((it) => !it.proposed);
+      say(`  ${s.label}${real.length ? ` · ${real.filter((it) => it.state === 'done').length} of ${real.length}` : ''}`);
+      for (const it of mine) say(`    ${describe(it, s.id ? s.label : it.stage)} · ${it.owner}`);
+    }
+    return 0;
+  }
+
+  let events; let id = null; let before = null;
+  if (verb === 'add') {
+    const [initiative, title] = pos;
+    if (!initiative || title === undefined) { say('usage: pmos item add <initiative> "<title>" --stage <stage> [options]'); return 2; }
+    if (!planItems.INIT_RE.test(initiative) || !planTree.recordPath(root, initiative)) return fail(`no initiative ${initiative} in this repository`);
+    if (!flags.stage) {
+      const stages = planTree.stagesFor(root, initiative);
+      say(`--stage is required — the stages of ${initiative} are: ${stages.map((s) => `${s.id} (${s.label})`).join(', ')}`);
+      return 2;
+    }
+    const ev = { ev: 'planned', initiative, title, stage: flags.stage };
+    if (flags.due) ev.due = flags.due;
+    if (flags.start) ev.start = flags.start;
+    if (flags.owner) ev.owner = flags.owner;
+    if (flags.after) ev.after = csv(flags.after);
+    if (flags.milestone) ev.milestone = true;
+    if (flags.note) ev.note = flags.note;
+    for (const k of ['title', 'blocked', 'evidence', 'no-milestone']) if (k in flags) return fail(`--${k} is not an option of add`, 2);
+    events = [ev];
+  } else {
+    id = pos[0];
+    if (!id) { say(`usage: pmos item ${verb} <item> …`); return 2; }
+    before = (() => { try { return fresh(id); } catch { return null; } })();
+    if (verb === 'set') {
+      const fields = {};
+      if (flags.title) fields.title = flags.title;
+      if (flags.stage) fields.stage = flags.stage;
+      for (const k of ['due', 'start', 'note']) if (flags[k]) fields[k] = flags[k] === 'none' ? null : flags[k];
+      if (flags.owner) fields.owner = flags.owner;
+      if (flags.after) fields.after = flags.after === 'none' ? [] : csv(flags.after);
+      if (flags.milestone) fields.milestone = true;
+      if (flags['no-milestone']) fields.milestone = false;
+      if (flags.milestone && flags['no-milestone']) return fail('--milestone and --no-milestone contradict each other', 2);
+      if (flags.evidence) return fail('--evidence belongs to move', 2);
+      events = [];
+      if (Object.keys(fields).length) events.push({ ev: 'set', item: id, fields });
+      if (flags.blocked) events.push(flags.blocked === 'none' ? { ev: 'flagged', item: id, blocked: false } : { ev: 'flagged', item: id, blocked: true, reason: flags.blocked });
+      if (!events.length) { say('nothing to set — name at least one option (pmos item help)'); return 2; }
+    } else if (verb === 'move') {
+      const to = String(pos[1] || '').toLowerCase();
+      if (!planItems.STATES.includes(to)) { say(`usage: pmos item move <item> ${planItems.STATES.join('|')} [--evidence <kind>:<ref>]`); return 2; }
+      for (const k of Object.keys(flags)) if (!['json', 'root', 'evidence'].includes(k)) return fail(`--${k} is not an option of move`, 2);
+      const ev = { ev: 'moved', item: id, to };
+      if (flags.evidence) ev.evidence = flags.evidence;
+      events = [ev];
+    } else if (verb === 'withdraw') {
+      for (const k of Object.keys(flags)) if (!['json', 'root'].includes(k)) return fail(`--${k} is not an option of withdraw`, 2);
+      events = [{ ev: 'withdrawn', item: id }];
+    }
+  }
+
+  let r;
+  try { r = planItems.appendFromCli(root, events, cliOpts); }
+  catch (e) { return fail('could not record — ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!r.ok) return fail(r.error);
+  const itemId = id || (r.written[0] && r.written[0].item);
+  const after = (() => { try { return fresh(itemId); } catch { return null; } })();
+  const item = after || (before ? { ...before, state: 'withdrawn' } : null);
+  const actor = planItems.actorFromCli({ ...(isTTY !== undefined ? { isTTY } : {}), ...(env !== undefined ? { env } : {}) });
+  if (json) { say(JSON.stringify({ ok: true, item })); return 0; }
+  const by = planTree.byLabel(actor.by);
+  const label = item ? stageLabelOf(item.initiative, item.stage) : '';
+  if (verb === 'add') say(`added ${item.id} "${item.title}" · ${label}${item.due ? ` · due ${shortDate(item.due)}` : ''} · by ${by}`);
+  else if (verb === 'withdraw') say(`withdrew ${itemId}${before ? ` "${before.title}"` : ''} · by ${by}`);
+  else if (verb === 'move') {
+    say(`moved ${item.id} "${item.title}" to ${STATE_LABEL[item.state]}${item.evidence ? ` with evidence ${item.evidence.kind}:${item.evidence.ref}` : ''} · by ${by}`);
+    if (item.noEvidence) say('  no evidence — an agent Done with no evidence goes to the PM. Add --evidence <kind>:<ref>.');
+  } else say(`updated ${describe(item, label)} · by ${by}`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/item-spans.js

@@ -0,0 +1,137 @@
+'use strict';
+// item-spans.js — the dated bars of a breakdown: one span per item from its start and due, and the initiative's span
+// over them (pm-os-absorb, PRD R20, R8 predecessor flag).
+//
+//   spansOf(items, { stages })  → [{ id, stage, start, due, milestone, proposed, overlapsPredecessor, overlap }]
+//   initiativeSpan(spans, { proposed })  → { start, due } | null
+//   stageSpans(spans, { proposed })      → [{ stage, start, due }]   one per stage, in the order of the spans
+//   axisOf(spans, { today })    → { start, end, months: [{ month, start, end }] }   whole months, at least MIN_MONTHS
+//   dayNum(date) · addDays(date, n) · daysBetween(a, b)   calendar-day arithmetic on YYYY-MM-DD, never shifted by a zone
+//
+// `items` is the `items` of a plan-items fold or layout (lib/plan-items.js, lib/plan-tree.js): an object keyed by item
+// id, or a list. Dates are YYYY-MM-DD strings. One engine for Breakdown › Timeline and Initiatives › Timeline (Run 4)
+// and the report's Timeline strip (Run 5). Classic script (a UMD setting window.PMOSItemSpans), served from /lib/, so the
+// bars on the screen and the numbers in a report cannot disagree.
+//
+// The rules (Run 4, slice 4B):
+//   - A withdrawn item has no span. An item with neither date has no span. An item with one date spans that one day.
+//   - Spans come in stage order (`stages`: stage ids or { id } objects, as the layout lists them), then by the item's
+//     `order`, then by start. A stage the list does not name sorts last.
+//   - `milestone` is the item's own flag. A milestone's ◆ sits on its due date.
+//   - `proposed` is the item's own flag: an agent's proposal that the PM has not kept (lib/plan-items.js). It has a span,
+//     but initiativeSpan and stageSpans leave it out unless `{ proposed: true }` is passed, so a batch of proposals
+//     that nobody kept never stretches a stage or an initiative bar. axisOf includes it, so its bar has room.
+//   - `overlapsPredecessor` (R8, at risk): the item starts on or before the day a predecessor ends. A predecessor is an
+//     id in the item's `after` list that is among `items`, live and not Done; it ends on its due date (or its start when
+//     it has no due). An item that is Done is never flagged. `overlap` names the predecessor that ends last, as
+//     { id, due }, so the screen can give the reason; it is null when nothing overlaps.
+//   - A predecessor in another initiative counts only when the caller passes its item too. No date is ever moved here:
+//     the flag shows a clash, and the PM decides (no cascade, PRD R20).
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSItemSpans = api;
+}(typeof self !== 'undefined' ? self : this, function () {
+  const DATE = /^\d{4}-\d{2}-\d{2}$/;
+  const DAY = 86400000;
+  const MIN_MONTHS = 3;
+  const date = (v) => (typeof v === 'string' && DATE.test(v) ? v : null);
+
+  /** Days since 1970-01-01 for a YYYY-MM-DD date (NaN for anything else). */
+  function dayNum(d) {
+    if (!date(d)) return NaN;
+    return Math.round(Date.UTC(Number(d.slice(0, 4)), Number(d.slice(5, 7)) - 1, Number(d.slice(8, 10))) / DAY);
+  }
+  const fromNum = (n) => new Date(n * DAY).toISOString().slice(0, 10);
+  /** The date `n` calendar days after `d` (before it when `n` is negative); null for a bad date. */
+  function addDays(d, n) { const x = dayNum(d); return Number.isNaN(x) ? null : fromNum(x + Math.round(Number(n) || 0)); }
+  /** Whole days from `a` to `b` (b − a). */
+  function daysBetween(a, b) { return dayNum(b) - dayNum(a); }
+
+  const listOf = (items) => (Array.isArray(items) ? items : items && typeof items === 'object' ? Object.values(items) : []);
+
+  function stageRank(stages) {
+    const rank = new Map();
+    (Array.isArray(stages) ? stages : []).forEach((s, i) => {
+      const id = typeof s === 'string' ? s : s && typeof s.id === 'string' ? s.id : null;
+      if (id && !rank.has(id)) rank.set(id, i);
+    });
+    return (id) => (rank.has(id) ? rank.get(id) : rank.size);
+  }
+
+  function spansOf(items, opts) {
+    const rank = stageRank(opts && opts.stages);
+    const live = listOf(items).filter((it) => it && typeof it.id === 'string' && it.state !== 'withdrawn');
+    const byId = new Map(live.map((it) => [it.id, it]));
+    const out = [];
+    for (const it of live) {
+      const start = date(it.start);
+      const due = date(it.due);
+      if (!start && !due) continue;
+      const s = start || due;
+      let overlap = null;
+      if (it.state !== 'done') {
+        for (const pid of Array.isArray(it.after) ? it.after : []) {
+          const p = byId.get(pid);
+          if (!p || p.state === 'done') continue;
+          const end = date(p.due) || date(p.start);
+          if (end && s <= end && (!overlap || end > overlap.due)) overlap = { id: pid, due: end };
+        }
+      }
+      out.push({
+        id: it.id, stage: it.stage || null, start: s, due: due || start, milestone: !!it.milestone, proposed: !!it.proposed,
+        overlapsPredecessor: !!overlap, overlap,
+        _rank: rank(it.stage), _order: Number.isFinite(it.order) ? it.order : Infinity,
+      });
+    }
+    out.sort((a, b) => a._rank - b._rank || a._order - b._order || (a.start < b.start ? -1 : a.start > b.start ? 1 : 0) || (a.id < b.id ? -1 : 1));
+    for (const s of out) { delete s._rank; delete s._order; }
+    return out;
+  }
+
+  const counted = (spans, opts) => listOf(spans).filter((s) => s && date(s.start) && date(s.due) && (!s.proposed || !!(opts && opts.proposed)));
+
+  function initiativeSpan(spans, opts) {
+    const list = counted(spans, opts);
+    if (!list.length) return null;
+    let start = list[0].start;
+    let due = list[0].due;
+    for (const s of list) { if (s.start < start) start = s.start; if (s.due > due) due = s.due; }
+    return { start, due };
+  }
+
+  function stageSpans(spans, opts) {
+    const by = new Map();
+    for (const s of counted(spans, opts)) {
+      const k = s.stage || null;
+      const g = by.get(k);
+      if (!g) by.set(k, { stage: k, start: s.start, due: s.due });
+      else { if (s.start < g.start) g.start = s.start; if (s.due > g.due) g.due = s.due; }
+    }
+    return [...by.values()];
+  }
+
+  /** The time axis for `spans`: whole months from the earliest start to the latest due, with `today` inside it. */
+  function axisOf(spans, opts) {
+    const today = date(opts && opts.today);
+    const whole = initiativeSpan(spans, { proposed: true });
+    let lo = whole ? whole.start : today;
+    let hi = whole ? whole.due : today;
+    if (today) { if (today < lo) lo = today; if (today > hi) hi = today; }
+    if (!lo) return null;
+    const months = [];
+    let y = Number(lo.slice(0, 4));
+    let m = Number(lo.slice(5, 7));
+    const pad = (n) => String(n).padStart(2, '0');
+    for (;;) {
+      const first = `${y}-${pad(m)}-01`;
+      const next = m === 12 ? `${y + 1}-01-01` : `${y}-${pad(m + 1)}-01`;
+      months.push({ month: `${y}-${pad(m)}`, start: first, end: addDays(next, -1) });
+      if (next > hi && months.length >= MIN_MONTHS) break;
+      if (m === 12) { y++; m = 1; } else m++;
+    }
+    return { start: months[0].start, end: months[months.length - 1].end, months };
+  }
+
+  return { spansOf, initiativeSpan, stageSpans, axisOf, dayNum, addDays, daysBetween, MIN_MONTHS };
+}));

package/workspace/lib/measure-cli.js

@@ -0,0 +1,100 @@
+'use strict';
+/* measure-cli.js — `pmos measure …`: record a measured value of a KR or a health budget, with its source (pm-os-absorb
+ * Run 2, PRD R17, R23, R24).
+ *
+ *   pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]
+ *   pmos measure list [<anchor>]
+ *   every command: [--json] [--root <dir>]
+ *
+ * The SAME writer the workspace page uses (lib/measurements.js). A measurement is evidence, not a PM act, so an agent
+ * may write one: the line is attributed by lib/actor.js fromCli (the PM at a terminal, the bound agent session from
+ * PMOS_SESSION, `agent:unknown` otherwise). The source is required: the workspace never computes a KR value, so a
+ * group shows a value only from a line that says where it was read. `--as-of` is today (UTC) when it is not given.
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const actorLib = require('./actor.js');
+const measurements = require('./measurements.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { measure: ['add', 'list'] };
+const USAGE = [
+  'usage: pmos measure add|list — measured values of KRs and health budgets',
+  '  pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]',
+  '  pmos measure list [<anchor>]',
+  '  every command: [--json] [--root <dir>]',
+  'The anchor is the parent_kr an initiative names: a KR such as "KR 2.1", or health:<id>. Quote an anchor with a space.',
+  'The source is the file the value was read from and the commit it was read at, for example planning/okrs/q4.md@1a2b3c4.',
+];
+const BOOL = new Set(['json', 'help']);
+const VALUE = new Set(['source', 'target', 'unit', 'as-of', 'root']);
+
+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; }
+}
+const num = (s) => (typeof s === 'string' && s.trim() !== '' && Number.isFinite(Number(s)) ? Number(s) : NaN);
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now } = {}) {
+  const args = argv[0] === 'measure' ? 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.measure.includes(verb)) { say(`unknown measure command "${verb}" — one of ${COMMANDS.measure.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 fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+
+  if (verb === 'list') {
+    const m = measurements.readMeasurements(root);
+    const anchors = pos[0] ? [pos[0]] : Object.keys(m.byAnchor).sort();
+    if (json) { say(JSON.stringify({ ok: true, byAnchor: Object.fromEntries(anchors.map((a) => [a, (m.byAnchor[a] || []).map((x) => ({ ...x, by: actorLib.pageName(x.by) }))])), flags: m.flags })); return 0; }
+    if (!anchors.length) say('No measurements yet.');
+    for (const a of anchors) {
+      for (const x of m.byAnchor[a] || []) say(`${a} · ${x.value}${x.unit || ''}${x.target === null ? '' : ` → ${x.target}${x.unit || ''}`} on ${x.as_of} · ${x.source} · ${actorLib.pageName(x.by)}`);
+    }
+    for (const f of m.flags) say(`! ${f.why}`);
+    return 0;
+  }
+
+  const [anchor, valueText] = pos;
+  if (!anchor || valueText === undefined) { say(USAGE[1].trim()); return 2; }
+  const value = num(valueText);
+  if (!Number.isFinite(value)) return fail('the value must be a number', 2);
+  const ev = { ev: 'measured', anchor, value };
+  if (flags.target !== undefined) {
+    const t = num(flags.target);
+    if (!Number.isFinite(t)) return fail('--target must be a number', 2);
+    ev.target = t;
+  }
+  if (flags.unit !== undefined) ev.unit = flags.unit;
+  ev.as_of = flags['as-of'] || new Date(now == null ? Date.now() : now).toISOString().slice(0, 10);
+  if (flags.source !== undefined) ev.source = flags.source;
+  const actor = actorLib.fromCli({ isTTY: isTTY === undefined ? !!(process.stdin.isTTY && process.stdout.isTTY) : isTTY, env: env === undefined ? process.env : env });
+  const r = measurements.appendFromCli(root, [ev], { actor, now });
+  if (!r.ok) return fail(r.error);
+  if (json) say(JSON.stringify({ ok: true, written: r.written, eid: r.lines[0].eid }));
+  else say(`✓ ${anchor}: ${value}${ev.unit || ''} on ${ev.as_of} recorded (source ${ev.source})`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/measurements.js

@@ -0,0 +1,189 @@
+'use strict';
+/* measurements.js — THE ONE WRITER and THE ONE FOLD of measurements.jsonl: a measured value of a KR or a health
+ * budget, with its target, its date and its source (pm-os-absorb, PRD R17, R23, R24; D86).
+ *
+ *   readMeasurements(root) → {
+ *     ok: true,
+ *     byAnchor: { [anchor]: [{ value, target, unit, as_of, source, by, at }] },   oldest first; `source` is "path@sha"
+ *     flags: [{ kind, eid, why }],
+ *   }
+ *   latest(result, anchor)                       → the newest measurement of `anchor` by as_of, or null
+ *   appendFromUi(root, events, { actor, now })   → { ok, written, lines } | { ok: false, status, error, index }
+ *   appendFromCli(root, events, { actor, now })  → the same
+ *   checkEvent(ev) → null | error text            the caller-side checks, shared with `pmos measure`
+ *
+ * `anchor` is the initiative's parent_kr as written (a KR id, or `health:<id>`, D59). A measurement needs a source; an
+ * agent may write one (it is evidence, not a PM act), so the actor comes from actor.js, never from the caller.
+ * The workspace never computes a value (PRD Non-goals): a group shows a value only from a line here.
+ *
+ * THE `measured` LINE (the shared contract):
+ *   { v: 1, eid, ev: 'measured', anchor, value: <number>, target: <number> | null, unit?: '%'|…, as_of: 'YYYY-MM-DD',
+ *     source: '<path>@<sha>', by, via, at }
+ *   pmOnly(rec) → false: a measurement is evidence, not a PM act.
+ *
+ * `source` is a repository-relative path, `@`, and a commit sha of 7 to 40 hex characters: the file the number was
+ * read from, at the commit it was read at. The writer does not open it (no read outside the call's own checks), so a
+ * wrong path is the writer's caller's error; scripts/check-measurements.js reports a path that is not in the tree.
+ *
+ * The fold is order-free, like lib/plan-items.js: byte-identical duplicates count once, one eid with two contents keeps
+ * the first. The ledger is one per repository: lib/plan-ledgers.js ledgerPath(root, 'measurements'). Nothing is cached.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ledgers = require('./plan-ledgers.js');
+const actorLib = require('./actor.js');
+const { createSinkGuard } = require('./sink.js');
+
+const MAX_LINES = 50;
+const EID_RE = /^[0-9a-z]{12}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/** A KR id as the OKR files write it, or a health budget or a domain (D59, D67). One line, no control characters. */
+const ANCHOR_RE = /^(?:health:[a-z0-9][a-z0-9-]{0,59}|domain:[a-z0-9][a-z0-9-]{0,59}|[A-Za-z0-9][A-Za-z0-9 .:_-]{0,79})$/;
+const SOURCE_RE = /^([A-Za-z0-9_][A-Za-z0-9_./-]{0,239})@([0-9a-f]{7,40})$/;
+const UNIT_RE = /^[^\s\x00-\x1f]{1,12}$/;
+const WRITER_SET = Object.freeze(['v', 'eid', 'by', 'via', 'at', 'override', 'pm', 'actor', 'nonce']);
+const CALLER_KEYS = Object.freeze(['anchor', 'value', 'target', 'unit', 'as_of', 'source']);
+const STORED_KEYS = Object.freeze(['v', 'eid', 'ev', 'by', 'via', 'at', ...CALLER_KEYS]);
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+const isStr = (v) => typeof v === 'string';
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const dateOk = (v) => isStr(v) && DATE_RE.test(v) && !Number.isNaN(Date.parse(v + 'T00:00:00Z'))
+  && new Date(v + 'T00:00:00Z').toISOString().slice(0, 10) === v;
+
+function newEventId() {
+  let out = '';
+  while (out.length < 12) {
+    for (const b of crypto.randomBytes(24)) {
+      if (b >= 252) continue;
+      out += ALPHABET[b % 36];
+      if (out.length === 12) break;
+    }
+  }
+  return out;
+}
+
+/** The source as { path, sha }, or null when it is not "<repository-relative path>@<sha>". */
+function parseSource(s) {
+  const m = isStr(s) ? SOURCE_RE.exec(s) : null;
+  if (!m) return null;
+  if (m[1].split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) return null;
+  return { path: m[1], sha: m[2] };
+}
+
+/** The checks on what a caller sends (the writer runs them; `pmos measure` runs them before it writes). */
+function checkEvent(ev) {
+  if (!ev || typeof ev !== 'object' || Array.isArray(ev)) return 'each line must be a JSON object';
+  const sent = WRITER_SET.find((k) => has(ev, k));
+  if (sent) return `the writer sets "${sent}"; do not send it`;
+  if (ev.ev !== 'measured') return 'ev must be measured';
+  const extra = Object.keys(ev).filter((k) => k !== 'ev' && !CALLER_KEYS.includes(k));
+  if (extra.length) return `a measured line has no field ${extra.join(', ')}`;
+  if (!isStr(ev.anchor) || !ANCHOR_RE.test(ev.anchor.trim()) || ev.anchor !== ev.anchor.trim()) return 'anchor must be a KR id, health:<id> or domain:<id>';
+  if (typeof ev.value !== 'number' || !Number.isFinite(ev.value)) return 'value must be a number';
+  if (has(ev, 'target') && ev.target !== null && (typeof ev.target !== 'number' || !Number.isFinite(ev.target))) return 'target must be a number, or null';
+  if (has(ev, 'unit') && !(isStr(ev.unit) && UNIT_RE.test(ev.unit))) return 'unit must be a short word with no spaces, like %';
+  if (!dateOk(ev.as_of)) return 'as_of must be YYYY-MM-DD';
+  if (!has(ev, 'source') || ev.source === '' || ev.source == null) return 'a measurement needs a source: <path>@<commit sha>';
+  if (!parseSource(ev.source)) return 'source must be <repository-relative path>@<commit sha of 7 to 40 hex characters>';
+  return null;
+}
+
+/** Why a stored line is not a valid line of this ledger, or null. */
+function lineErr(r) {
+  if (r.v !== 1) return 'v must be 1';
+  if (!isStr(r.eid) || !EID_RE.test(r.eid)) return 'eid must be 12 characters of [0-9a-z]';
+  if (!isStr(r.by) || !actorLib.BY_RE.test(r.by)) return 'by must be pm:<slug>, agent:unknown or agent:<session>';
+  if (!actorLib.VIA.includes(r.via)) return 'via must be ui or cli';
+  if (!isStr(r.at) || !AT_RE.test(r.at)) return 'at must be an ISO UTC time';
+  const extra = Object.keys(r).filter((k) => !STORED_KEYS.includes(k));
+  if (extra.length) return `a measured line has no field ${extra.join(', ')}`;
+  const body = {};
+  for (const k of ['ev', ...CALLER_KEYS]) if (has(r, k)) body[k] = r[k];
+  return checkEvent(body);
+}
+
+function readMeasurements(root) {
+  const out = { ok: true, byAnchor: {}, flags: [] };
+  const { lines, bad } = ledgers.readLines(root, 'measurements');
+  for (const b of bad) out.flags.push({ kind: 'unreadable', eid: null, why: `line ${b.n}: ${b.why}` });
+  const kept = [];
+  for (const { n, rec } of lines) {
+    if (rec.ev !== 'measured') { out.flags.push({ kind: 'invalid', eid: isStr(rec.eid) ? rec.eid : null, why: `line ${n}: ev must be measured` }); continue; }
+    const why = lineErr(rec);
+    if (why) { out.flags.push({ kind: 'invalid', eid: isStr(rec.eid) ? rec.eid : null, why: `line ${n}: ${why}` }); continue; }
+    kept.push({ n, rec });
+  }
+  kept.sort((a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at)) || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0) || (a.n - b.n));
+  const seen = new Map();
+  for (const { n, rec } of kept) {
+    const text = JSON.stringify(rec);
+    if (seen.has(rec.eid)) {
+      if (seen.get(rec.eid) !== text) out.flags.push({ kind: 'duplicate-event', eid: rec.eid, why: `line ${n}: the eid ${rec.eid} is used by two different lines; the first one counts` });
+      continue;
+    }
+    seen.set(rec.eid, text);
+    (out.byAnchor[rec.anchor] = out.byAnchor[rec.anchor] || []).push({
+      value: rec.value, target: Number.isFinite(rec.target) ? rec.target : null, unit: rec.unit || null,
+      as_of: rec.as_of, source: rec.source, by: rec.by, at: rec.at,
+    });
+  }
+  for (const rows of Object.values(out.byAnchor)) rows.sort((a, b) => String(a.as_of).localeCompare(String(b.as_of)) || String(a.at).localeCompare(String(b.at)));
+  return out;
+}
+
+const pmOnly = () => false;
+
+function latest(result, anchor) {
+  const rows = result && result.byAnchor && Object.prototype.hasOwnProperty.call(result.byAnchor, anchor) ? result.byAnchor[anchor] : null;
+  if (!Array.isArray(rows) || !rows.length) return null;
+  return rows.reduce((a, b) => (String(b.as_of) >= String(a.as_of) ? b : a));
+}
+
+const refuse = (status, error, index) => ({ ok: false, status, error, index: index == null ? null : index });
+
+function append(root, events, actor, { now } = {}) {
+  if (!actorLib.valid(actor)) return refuse(500, 'measurements: the caller must pass the actor from pm-guard.js or actor.js', null);
+  if (!Array.isArray(events) || !events.length) return refuse(400, 'send at least one line', null);
+  if (events.length > MAX_LINES) return refuse(413, `send at most ${MAX_LINES} lines at once`, null);
+  for (let i = 0; i < events.length; i++) {
+    const why = checkEvent(events[i]);
+    if (why) return refuse(400, why, i);
+  }
+  const read = ledgers.readLines(root, 'measurements');
+  if (read.bad.some((b) => b.n === 0)) return refuse(500, 'could not read the measurements ledger — nothing was saved: ' + read.bad[0].why.slice(0, 160), null);
+  const clock = now == null ? Date.now() : now;
+  let last = 0;
+  for (const l of read.lines) {
+    const t = isStr(l.rec.at) ? Date.parse(l.rec.at) : NaN;
+    if (Number.isFinite(t) && t <= clock + 1000 && t > last) last = t;
+  }
+  const recs = events.map((ev) => {
+    last = Math.max(clock, last + 1);
+    const rec = { v: 1, eid: newEventId(), ev: 'measured', anchor: ev.anchor, value: ev.value, target: has(ev, 'target') ? ev.target : null };
+    if (has(ev, 'unit')) rec.unit = ev.unit;
+    Object.assign(rec, { as_of: ev.as_of, source: ev.source, by: actor.by, via: actor.via, at: new Date(last).toISOString() });
+    return rec;
+  });
+  let file;
+  try { file = ledgers.ledgerPath(root, 'measurements'); fs.mkdirSync(path.dirname(file), { recursive: true }); }
+  catch { return refuse(500, 'could not record — nothing was saved', null); }
+  const guard = createSinkGuard({ sink: file, what: 'measurements' });
+  let wrote = 0;
+  for (const rec of recs) {
+    try { guard.appendLine(file, rec); wrote++; }
+    catch {
+      return refuse(500, wrote ? `could not record — ${wrote} of ${recs.length} lines were saved before the write failed` : 'could not record — nothing was saved', wrote);
+    }
+  }
+  return { ok: true, written: recs.length, lines: recs.map((r) => ({ eid: r.eid, anchor: r.anchor })) };
+}
+
+/** A page press (requirePagePress's actor). */
+function appendFromUi(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+/** `pmos measure` (actor.fromCli's actor; an agent may write a measurement). */
+function appendFromCli(root, events, { actor, now } = {}) { return append(root, events, actor, { now }); }
+
+module.exports = { MAX_LINES, readMeasurements, latest, pmOnly, checkEvent, parseSource, lineErr, appendFromUi, appendFromCli };