create-pmos 0.61.1 → 0.63.0

package/workspace/lib/people-cli.js

@@ -0,0 +1,135 @@
+'use strict';
+/* people-cli.js — `pmos people`: the people the PM works with in this repository, from a terminal
+ * (initiative people-directory, PRD R2, R9, R14, proposed D90).
+ *
+ *   pmos people [list] [--json]                       each person: name, role, last interaction, tone; and the review list
+ *   pmos people show <person> [--json]                one person's page: interactions, tone, shared work, notes, handles
+ *   pmos people record --file <sightings.json>        (agent session) append what the session saw
+ *   pmos people settings [--json]                     whether calendar attendee names are kept
+ *
+ * The same module the People place reads (lib/people-store.js), so a terminal line and the page cannot disagree.
+ * No command adds a person, merges, sets a tone or writes a note: those are the PM's presses in People (D90).
+ * `record` must name who recorded: the session's PMOS_SESSION token, or `--by <profile>` outside the workspace.
+ *
+ * Exit codes: 0 done, 1 refused, 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const store = require('./people-store');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { people: ['list', 'show', 'record', 'settings'] };
+const USAGE = [
+  'usage: pmos people [list|show|record|settings] — the people you work with in this repository',
+  '  pmos people [list] [--json]                 each person, and what waits for you in the review list',
+  '  pmos people show <person> [--json]          one person: interactions, tone, shared work, notes and handles',
+  '  pmos people record --file <sightings.json>  (agent session) record the people a session saw',
+  '  pmos people settings [--json]               whether calendar attendee names are kept (calendar names: on|off)',
+  'Nothing here adds a person, merges, sets a tone or writes a note. Do that in People.',
+];
+const BOOL = new Set(['json', 'help']);
+
+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 } };
+}
+/** The repository holding `cwd`: the nearest folder with a .git entry. No process is started (R16). */
+function repoRoot(cwd) {
+  for (let d = path.resolve(cwd); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) return d;
+    if (path.dirname(d) === d) return cwd;
+  }
+}
+/** Who is recording: the workspace session's token names it; outside the workspace, the profile the PM names. */
+function whoOf(flags, env) {
+  const tok = String(env.PMOS_SESSION || '').trim();
+  if (tok) return 'session:' + tok.split('.')[0].slice(0, 60);
+  if (flags.by) return 'profile:' + String(flags.by).slice(0, 60);
+  return null;
+}
+const toneWord = (t) => (t.confirmed ? t.confirmed : t.proposed ? `${t.proposed} (proposed)` : 'no tone yet');
+const handleText = (h) => `${h.kind} ${h.value}`;
+
+async function run(argv, { say = console.log, cwd = process.cwd(), env = process.env, now = Date.now() } = {}) {
+  const { pos, flags } = parse(argv.slice(1));
+  const sub = pos[0] || 'list';
+  if (flags.help || sub === 'help') { USAGE.forEach((l) => say(l)); return 0; }
+  const json = !!flags.json;
+  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 (sub === 'list') {
+    const v = store.view(root, { now });
+    if (!v.ok) return fail(v.error);
+    if (json) { say(JSON.stringify({ ok: true, people: v.people, review: v.review, settings: v.settings, counts: v.counts })); return 0; }
+    const r = v.review;
+    say(`People · ${v.people.length} ${v.people.length === 1 ? 'person' : 'people'} · ${r.new.length} new · ${r.merges.length} possible duplicate${r.merges.length === 1 ? '' : 's'} · ${r.tones.length} tone${r.tones.length === 1 ? '' : 's'} to confirm`);
+    if (!v.people.length && !r.new.length) { say('Nobody yet. Agent sessions record the people they see; you add them in People.'); return 0; }
+    for (const p of v.people) {
+      say(`${p.name}  (${p.id})  ${[p.role, p.org].filter(Boolean).join(' · ') || p.group}  · ${p.count} interaction${p.count === 1 ? '' : 's'}${p.last ? ' · last ' + p.last : ''} · ${toneWord(p.tone)}`);
+    }
+    if (r.new.length) {
+      say('New, waiting for you in People:');
+      for (const f of r.new) say(`  ${f.name}  ${handleText(f.handle)}  · ${f.count} sighting${f.count === 1 ? '' : 's'} from ${f.sources.join(', ')}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const id = pos[1];
+    if (!id) return fail('usage: pmos people show <person>', 2);
+    const v = store.view(root, { now });
+    if (!v.ok) return fail(v.error);
+    const q = String(id).toLowerCase();
+    const p = v.people.find((x) => x.id === q) || v.people.find((x) => x.name.toLowerCase() === q);
+    if (!p) return fail(`no person ${id} — pmos people list names everyone`);
+    if (json) { say(JSON.stringify({ ok: true, person: p })); return 0; }
+    say(`${p.name}  (${p.id})  ${[p.role, p.org].filter(Boolean).join(' · ')}  ${p.group}`);
+    const mix = Object.entries(p.tone.mix).map(([t, n]) => `${n} ${t}`).join(', ');
+    say(`Tone: ${toneWord(p.tone)}${mix ? ' · ' + mix : ''}`);
+    say(`Interactions (${p.count}):`);
+    for (const i of p.interactions.slice(0, 20)) say(`  ${i.date}  ${i.kind.padEnd(7)} ${i.text}${i.tone ? ' [' + i.tone + ']' : ''}  — ${i.source}: ${i.pointer}`);
+    const s = p.shared;
+    if (s.initiatives.length) say(`Initiatives: ${s.initiatives.map((g) => `${g.id} (${g.count})`).join(', ')}`);
+    for (const it of s.items) say(`  Owns ${it.id} ${it.title || ''} · ${it.state}${it.blocked ? ' · Blocked' + (it.reason ? ': ' + it.reason : '') : ''}`);
+    for (const m of s.meetings) say(`  Meeting ${String(m.start).slice(0, 16).replace('T', ' ')} ${m.title}`);
+    if (p.notes.length) { say('Notes:'); for (const n of p.notes) say(`  ${n.text}`); }
+    say(`Handles: ${p.handles.map(handleText).join(' · ')}`);
+    return 0;
+  }
+
+  if (sub === 'settings') {
+    const s = store.settings(root);
+    if (!s.ok) return fail(s.error);
+    if (json) say(JSON.stringify({ ok: true, calendar_names: s.calendar_names }));
+    else say(`calendar names: ${s.calendar_names ? 'on' : 'off'}`);
+    return 0;
+  }
+
+  if (sub === 'record') {
+    if (!flags.file) return fail('usage: pmos people record --file <sightings.json>', 2);
+    const by = whoOf(flags, env);
+    if (!by) return fail('a sighting must name who recorded it: run it in a workspace session, or add --by <profile>');
+    let parsed;
+    try { parsed = JSON.parse(fs.readFileSync(path.resolve(cwd, flags.file), 'utf8')); }
+    catch (e) { return fail(`could not read ${flags.file}: ${String((e && e.message) || e).slice(0, 160)}`); }
+    const sightings = Array.isArray(parsed) ? parsed : (parsed && parsed.sightings) || [];
+    const merges = (!Array.isArray(parsed) && parsed && parsed.merges) || [];
+    const r = store.record(root, { by, sightings, merges, now });
+    if (json) { say(JSON.stringify(r)); return r.ok ? 0 : 1; }
+    if (!r.ok && r.recorded === undefined) return fail(r.error);
+    say(`${r.recorded || 0} sighting(s) recorded · ${r.duplicates || 0} already recorded · ${r.proposals || 0} merge proposal(s) · ${(r.refused || []).length} refused`);
+    for (const x of r.refused || []) say(`✗ ${x.index !== undefined ? 'sighting ' + x.index : 'merge ' + x.merge}: ${x.error}`);
+    if (!r.ok) say(`✗ ${r.error}`);
+    return r.ok ? 0 : 1;
+  }
+  return fail(`pmos people ${sub} is not a command. ${USAGE[0]}`, 2);
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/people-store.js

@@ -0,0 +1,123 @@
+'use strict';
+/* people-store.js — the file side of People (initiative people-directory, PRD R1 to R10, proposed D90).
+ *
+ * lib/people.js decides; this module reads and appends. The `pmos people` verb and the /api/people routes both call
+ * it, so the terminal and the People place cannot hold two opinions about a person.
+ *
+ *   view(root, { now, meetings })            → { ok, people, review, settings, counts, file }
+ *   record(root, { by, sightings, merges, now }) → { ok, recorded, duplicates, refused[], error? }
+ *   decide(root, { actor, body, now })       → { ok, row } | { ok:false, error }   one PM page press
+ *   settings(root)                           → { ok, calendar_names, file }
+ *
+ * Every write is an append through people.js's validators, so a refused row is never on disk. No network, no process.
+ */
+const crypto = require('crypto');
+const P = require('./people');
+const fourPanel = require('./four-panel');
+const consoleState = require('./console-state');
+
+const MAX_PER_RECORD = 500;
+
+function stateDir(root) {
+  const e = consoleState.loadEngine();
+  if (!e.ok) return { ok: false, error: e.error };
+  const dir = fourPanel.storeDir(e.engine, root);
+  return dir ? { ok: true, dir } : { ok: false, error: 'this repository has no file-mode state directory' };
+}
+function readRows(root) {
+  const s = stateDir(root);
+  if (!s.ok) return s;
+  const r = fourPanel.readDeclarations(s.dir, P.LEDGER);
+  if (!r.ok) return { ok: false, error: r.error };
+  return { ok: true, dir: s.dir, file: r.file, rows: r.rows };
+}
+/** The plan items, for shared work (R10). A repository without a plan gives none. */
+function planItems(root) {
+  try { return Object.values(require('./plan-items').readFold(root).items || {}); } catch { return []; }
+}
+
+function view(root, { now = Date.now(), meetings = [] } = {}) {
+  const r = readRows(root);
+  if (!r.ok) return r;
+  const v = P.fold(r.rows, { now, items: planItems(root), meetings });
+  return { ok: true, ...v, file: r.file };
+}
+
+function settings(root) {
+  const r = readRows(root);
+  if (!r.ok) return r;
+  return { ok: true, calendar_names: P.fold(r.rows).settings.calendar_names, file: r.file };
+}
+
+const stamp = (row, by, now) => ({ v: 1, ...row, by, at: new Date(now).toISOString() });
+const sightKey = (r) => [P.handleKey(r.handle), r.interaction ? r.interaction.date : '', r.interaction ? r.interaction.pointer : '', r.interaction ? r.interaction.text : ''].join('\u0000');
+
+/**
+ * Append what an agent session saw. `by` names who recorded it (a session token or a profile); it is required.
+ * A calendar sighting is refused while the PM's calendar setting is off (R3). A sighting already on disk is skipped.
+ */
+function record(root, { by, sightings = [], merges = [], now = Date.now() } = {}) {
+  if (typeof by !== 'string' || !/^(session|profile):\S{1,60}$/.test(by)) return { ok: false, error: 'a sighting must name who recorded it' };
+  if (!Array.isArray(sightings) || !Array.isArray(merges)) return { ok: false, error: 'sightings and merges must be lists' };
+  if (sightings.length + merges.length > MAX_PER_RECORD) return { ok: false, error: `at most ${MAX_PER_RECORD} rows in one record` };
+  const r = readRows(root);
+  if (!r.ok) return r;
+  const calendarOn = P.fold(r.rows).settings.calendar_names;
+  const seen = new Set(r.rows.filter((x) => x && x.kind === 'sighting').map(sightKey));
+  const refused = [];
+  let recorded = 0; let duplicates = 0;
+  for (let i = 0; i < sightings.length; i++) {
+    const c = P.checkSighting(sightings[i]);
+    if (!c.ok) { refused.push({ index: i, error: c.error }); continue; }
+    if (c.row.source === 'calendar' && !calendarOn) { refused.push({ index: i, error: 'calendar names are off for this repository (Settings → People)' }); continue; }
+    const k = sightKey(c.row);
+    if (seen.has(k)) { duplicates++; continue; }
+    const w = fourPanel.appendDeclaration(r.dir, P.LEDGER, stamp(c.row, by, now));
+    if (!w.ok) return { ok: false, error: w.error, recorded, duplicates, refused };
+    seen.add(k); recorded++;
+  }
+  let proposals = 0;
+  for (let i = 0; i < merges.length; i++) {
+    const c = P.checkMergeProposal(merges[i]);
+    if (!c.ok) { refused.push({ merge: i, error: c.error }); continue; }
+    const w = fourPanel.appendDeclaration(r.dir, P.LEDGER, stamp(c.row, by, now));
+    if (!w.ok) return { ok: false, error: w.error, recorded, duplicates, refused };
+    proposals++;
+  }
+  return { ok: true, recorded, proposals, duplicates, refused };
+}
+
+/** A new note id: n- and eight letters or digits. */
+const noteId = () => 'n-' + crypto.randomBytes(6).toString('base64').replace(/[^0-9a-z]/gi, '').toLowerCase().slice(0, 8).padEnd(8, '0');
+
+/**
+ * One PM press. `actor` is requirePagePress's actor ({ by: 'pm:<slug>' }); the route has already checked the press.
+ * Add refuses a handle that a person already holds; merge, tone and notes refuse a person who does not exist.
+ */
+function decide(root, { actor, body, now = Date.now() } = {}) {
+  const by = actor && typeof actor.by === 'string' ? actor.by : null;
+  if (!by || !/^pm:/.test(by)) return { ok: false, error: 'only the PM decides who is a person' };
+  const b = body && typeof body === 'object' ? { ...body } : {};
+  if (b.act === 'note' && !b.id) b.id = noteId();
+  const c = P.checkDecision(b);
+  if (!c.ok) return c;
+  const r = readRows(root);
+  if (!r.ok) return r;
+  const v = P.fold(r.rows);
+  const row = c.row;
+  if (row.person && !v.people.some((p) => p.id === row.person)) return { ok: false, error: `no person ${row.person}` };
+  if (row.kind === 'add' && v.people.some((p) => p.handles.some((h) => P.handleKey(h) === P.handleKey(row.handle)))) {
+    return { ok: false, error: 'a person already holds that handle' };
+  }
+  const w = fourPanel.appendDeclaration(r.dir, P.LEDGER, stamp(row, by, now));
+  if (!w.ok) return { ok: false, error: w.error };
+  let person = row.person || null;
+  if (row.kind === 'add') {
+    const after = P.fold([...r.rows, stamp(row, by, now)]);
+    const p = after.people.find((x) => x.handles.some((h) => P.handleKey(h) === P.handleKey(row.handle)));
+    person = p ? p.id : null;
+  }
+  return { ok: true, row: w.recorded, person };
+}
+
+module.exports = { view, record, decide, settings, stateDir, readRows };

package/workspace/lib/people.js

@@ -0,0 +1,399 @@
+'use strict';
+/* people.js — the people the PM works with in a repository: the row rules and the one fold (initiative people-directory,
+ * PRD R1 to R10, proposed D90).
+ *
+ *   checkSighting(s)                 → { ok, row } | { ok:false, error }   one sighting an agent session records
+ *   checkMergeProposal(m)            → { ok, row } | { ok:false, error }
+ *   checkDecision(body)              → { ok, row } | { ok:false, error }   one PM press (add, ignore, merge, keep-separate,
+ *                                                                           edit, tone, note, note-remove, setting)
+ *   fold(rows, { now, items, meetings }) → { people, review, settings, counts }
+ *   handleKey(h) · slugOf(name) · toneProposal(interactions) · matchPeople(people, text)
+ *   SOURCES · HANDLE_KINDS · INTERACTION_KINDS · TONES · ACTS · LEDGER
+ *
+ * Pure: no file, no clock unless given, no network. lib/people-store.js reads and appends; the route, the CLI and the
+ * People place all answer from fold(), so the terminal and the page cannot hold two opinions about a person.
+ *
+ * WHO DECIDES (D90). A sighting row is anyone's: an agent session records it through `pmos people record`. Every
+ * decision row (a person added, a handle ignored or merged, a tone, a note, the calendar setting) counts only when its
+ * `by` is the PM (`pm:<slug>`), which only a page press writes. A decision row with any other `by` is skipped and
+ * counted in counts.skipped, so a hand-appended line cannot make an agent's choice the PM's.
+ *
+ * CALENDAR NAMES (R3). The setting is off until the PM turns it on. While it is off, the store refuses a calendar
+ * sighting, and this fold also drops the calendar sightings recorded while it was on.
+ */
+
+const LEDGER = 'people.jsonl';
+const SOURCES = Object.freeze(['gather', 'calendar', 'live', 'jira']);
+const HANDLE_KINDS = Object.freeze(['mail', 'slack', 'jira', 'confluence', 'speaker', 'name']);
+const INTERACTION_KINDS = Object.freeze(['Mail', 'Chat', 'Meeting', '1:1', 'Jira', 'Doc', 'Call', 'Mention']);
+const TONES = Object.freeze(['warm', 'neutral', 'cautious', 'tense']);
+const ACTS = Object.freeze(['add', 'ignore', 'merge', 'keep-separate', 'edit', 'tone', 'note', 'note-remove', 'setting']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,59}$/;
+const NOTE_ID_RE = /^n-[0-9a-z]{4,16}$/;
+const PM_BY_RE = /^pm:[a-z0-9_-]{1,40}$/;
+const TONE_WINDOW = 10;
+
+const isObj = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
+const str = (v) => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim() : '');
+/** A text field: a string of 1 to `max` characters after its spaces are folded, or null when absent and optional. */
+function text(v, max, what, { required = false } = {}) {
+  if (v === undefined || v === null || v === '') return required ? { error: `${what} is required` } : { value: null };
+  if (typeof v !== 'string') return { error: `${what} must be text` };
+  const s = str(v);
+  if (!s) return required ? { error: `${what} is required` } : { value: null };
+  if (s.length > max) return { error: `${what} is over ${max} characters` };
+  return { value: s };
+}
+
+/** The key a handle is known by: its kind and its value, lower-cased. Two sightings of one key are one handle. */
+function handleKey(h) {
+  if (!isObj(h)) return '';
+  return `${String(h.kind || '')}:${str(h.value).toLowerCase()}`;
+}
+function checkHandle(h, what = 'handle') {
+  if (!isObj(h)) return { error: `${what} must be { kind, value }` };
+  if (!HANDLE_KINDS.includes(h.kind)) return { error: `${what}.kind must be one of: ${HANDLE_KINDS.join(', ')}` };
+  const v = text(h.value, 120, `${what}.value`, { required: true });
+  if (v.error) return v;
+  return { value: { kind: h.kind, value: v.value } };
+}
+
+/** "Mei Lin" → "mei-lin". A name with no letter or digit gives "person". */
+function slugOf(name) {
+  const s = str(name).toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50);
+  return s || 'person';
+}
+
+/** One sighting, as `pmos people record` takes it. Returns the row to append, without v, at or by (the store adds them). */
+function checkSighting(s) {
+  if (!isObj(s)) return { ok: false, error: 'a sighting must be an object' };
+  if (!SOURCES.includes(s.source)) return { ok: false, error: `source must be one of: ${SOURCES.join(', ')}` };
+  const h = checkHandle(s.handle);
+  if (h.error) return { ok: false, error: h.error };
+  const name = text(s.name, 80, 'name', { required: true });
+  if (name.error) return { ok: false, error: name.error };
+  const role = text(s.role, 120, 'role');
+  if (role.error) return { ok: false, error: role.error };
+  const org = text(s.org, 80, 'org');
+  if (org.error) return { ok: false, error: org.error };
+  if (s.external !== undefined && typeof s.external !== 'boolean') return { ok: false, error: 'external must be true or false' };
+  const row = { kind: 'sighting', source: s.source, handle: h.value, name: name.value };
+  if (role.value) row.role = role.value;
+  if (org.value) row.org = org.value;
+  if (s.external === true) row.external = true;
+  if (s.interaction !== undefined && s.interaction !== null) {
+    const i = s.interaction;
+    if (!isObj(i)) return { ok: false, error: 'interaction must be an object' };
+    if (typeof i.date !== 'string' || !DATE_RE.test(i.date.slice(0, 10))) return { ok: false, error: 'interaction.date must be YYYY-MM-DD' };
+    if (!INTERACTION_KINDS.includes(i.kind)) return { ok: false, error: `interaction.kind must be one of: ${INTERACTION_KINDS.join(', ')}` };
+    const t = text(i.text, 200, 'interaction.text', { required: true });
+    if (t.error) return { ok: false, error: t.error };
+    const p = text(i.pointer, 200, 'interaction.pointer', { required: true });
+    if (p.error) return { ok: false, error: p.error };
+    if (i.tone !== undefined && i.tone !== null && !TONES.includes(i.tone)) return { ok: false, error: `interaction.tone must be one of: ${TONES.join(', ')}` };
+    if (i.initiative !== undefined && i.initiative !== null && (typeof i.initiative !== 'string' || !ID_RE.test(i.initiative))) return { ok: false, error: 'interaction.initiative must be an initiative id' };
+    row.interaction = { date: i.date.slice(0, 10), kind: i.kind, text: t.value, pointer: p.value };
+    if (i.tone) row.interaction.tone = i.tone;
+    if (i.initiative) row.interaction.initiative = i.initiative;
+  }
+  return { ok: true, row };
+}
+
+function checkMergeProposal(m) {
+  if (!isObj(m)) return { ok: false, error: 'a merge proposal must be an object' };
+  const a = checkHandle(m.a, 'a');
+  if (a.error) return { ok: false, error: a.error };
+  const b = checkHandle(m.b, 'b');
+  if (b.error) return { ok: false, error: b.error };
+  if (handleKey(a.value) === handleKey(b.value)) return { ok: false, error: 'a merge proposal needs two different handles' };
+  const why = text(m.why, 200, 'why', { required: true });
+  if (why.error) return { ok: false, error: why.error };
+  return { ok: true, row: { kind: 'merge-proposal', a: a.value, b: b.value, why: why.value } };
+}
+
+/** One PM press. The route passes the request body; the store adds v, at and by. */
+function checkDecision(body) {
+  if (!isObj(body)) return { ok: false, error: 'the body must be an object' };
+  const act = body.act;
+  if (!ACTS.includes(act)) return { ok: false, error: `act must be one of: ${ACTS.join(', ')}` };
+  const person = () => (typeof body.person === 'string' && ID_RE.test(body.person) ? body.person : null);
+  if (act === 'setting') {
+    if (typeof body.calendar_names !== 'boolean') return { ok: false, error: 'calendar_names must be true or false' };
+    return { ok: true, row: { kind: 'setting', calendar_names: body.calendar_names } };
+  }
+  if (act === 'add') {
+    const h = checkHandle(body.handle);
+    if (h.error) return { ok: false, error: h.error };
+    const name = text(body.name, 80, 'name', { required: true });
+    if (name.error) return { ok: false, error: name.error };
+    return { ok: true, row: { kind: 'add', handle: h.value, name: name.value } };
+  }
+  if (act === 'ignore') {
+    const h = checkHandle(body.handle);
+    if (h.error) return { ok: false, error: h.error };
+    return { ok: true, row: { kind: 'ignore', handle: h.value } };
+  }
+  if (act === 'merge') {
+    const h = checkHandle(body.handle);
+    if (h.error) return { ok: false, error: h.error };
+    if (!person()) return { ok: false, error: 'say which person the handle joins' };
+    return { ok: true, row: { kind: 'merge', person: person(), handle: h.value } };
+  }
+  if (act === 'keep-separate') {
+    const a = checkHandle(body.a, 'a');
+    if (a.error) return { ok: false, error: a.error };
+    const b = checkHandle(body.b, 'b');
+    if (b.error) return { ok: false, error: b.error };
+    return { ok: true, row: { kind: 'keep-separate', a: a.value, b: b.value } };
+  }
+  if (!person()) return { ok: false, error: 'say which person' };
+  if (act === 'edit') {
+    const row = { kind: 'edit', person: person() };
+    for (const [k, max] of [['name', 80], ['role', 120], ['org', 80]]) {
+      if (body[k] === undefined) continue;
+      if (body[k] === null || body[k] === '') { if (k === 'name') return { ok: false, error: 'name is required' }; row[k] = null; continue; }
+      const t = text(body[k], max, k, { required: k === 'name' });
+      if (t.error) return { ok: false, error: t.error };
+      row[k] = t.value;
+    }
+    if (body.external !== undefined) {
+      if (typeof body.external !== 'boolean') return { ok: false, error: 'external must be true or false' };
+      row.external = body.external;
+    }
+    if (Object.keys(row).length === 2) return { ok: false, error: 'nothing to change' };
+    return { ok: true, row };
+  }
+  if (act === 'tone') {
+    if (body.tone !== null && !TONES.includes(body.tone)) return { ok: false, error: `tone must be one of: ${TONES.join(', ')}, or null to clear it` };
+    return { ok: true, row: { kind: 'tone', person: person(), tone: body.tone } };
+  }
+  if (act === 'note') {
+    const t = text(body.text, 500, 'note', { required: true });
+    if (t.error) return { ok: false, error: t.error };
+    if (typeof body.id !== 'string' || !NOTE_ID_RE.test(body.id)) return { ok: false, error: 'the note needs an id (n- and 4 to 16 letters or digits)' };
+    return { ok: true, row: { kind: 'note', person: person(), id: body.id, text: t.value } };
+  }
+  // note-remove
+  if (typeof body.id !== 'string' || !NOTE_ID_RE.test(body.id)) return { ok: false, error: 'say which note' };
+  return { ok: true, row: { kind: 'note-remove', person: person(), id: body.id } };
+}
+
+/** The proposed overall tone: the most frequent tone of the latest TONE_WINDOW toned interactions; the latest of the
+ * tied tones wins a tie. `interactions` is newest first. null when no interaction has a tone. */
+function toneProposal(interactions) {
+  const toned = (interactions || []).filter((i) => i && TONES.includes(i.tone)).slice(0, TONE_WINDOW);
+  if (!toned.length) return null;
+  const n = {};
+  for (const i of toned) n[i.tone] = (n[i.tone] || 0) + 1;
+  const top = Math.max(...Object.values(n));
+  return toned.find((i) => n[i.tone] === top).tone;
+}
+
+const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Does `hay` name `needle` as a whole word, ignoring case? */
+function names(hay, needle) {
+  const n = str(needle);
+  if (n.length < 2) return false;
+  return new RegExp(`(^|[^\\p{L}\\p{N}])${escRe(n)}($|[^\\p{L}\\p{N}])`, 'iu').test(String(hay || ''));
+}
+/** The words a person is matched by in free text: the full name, a first name of three letters or more, and the
+ * values of their name and speaker handles. */
+function matchWords(p) {
+  const w = new Set();
+  const full = str(p.name);
+  if (full) w.add(full);
+  const first = full.split(' ')[0];
+  if (first && first.length >= 3 && first !== full) w.add(first);
+  for (const h of p.handles || []) if (h.kind === 'name' || h.kind === 'speaker' || h.kind === 'slack' || h.kind === 'jira') w.add(str(h.value).replace(/^@/, ''));
+  return [...w].filter((x) => x.length >= 2);
+}
+/** The people a free-text line names (an Agenda `with`, an item owner), each once, in list order. */
+function matchPeople(people, hay) {
+  if (!hay) return [];
+  return (people || []).filter((p) => matchWords(p).some((w) => names(hay, w)));
+}
+
+const sightKey = (r) => [handleKey(r.handle), r.interaction ? r.interaction.date : '', r.interaction ? r.interaction.pointer : '', r.interaction ? r.interaction.text : ''].join('\u0000');
+const pairKey = (a, b) => [handleKey(a), handleKey(b)].sort().join('\u0000');
+const isPm = (r) => typeof r.by === 'string' && PM_BY_RE.test(r.by);
+const DECISION_KINDS = new Set(['add', 'ignore', 'merge', 'keep-separate', 'edit', 'tone', 'note', 'note-remove', 'setting']);
+
+/**
+ * The one fold. `rows` are the ledger's rows in file order (torn lines already dropped). `items` are plan items (the
+ * plan-items fold's values) and `meetings` the coming calendar events ({ start, title, with }); both are optional.
+ */
+function fold(rows, { now = Date.now(), items = [], meetings = [] } = {}) {
+  const counts = { rows: 0, skipped: 0, duplicates: 0, hiddenCalendar: 0 };
+  const settings = { calendar_names: false };
+  const people = new Map();       // id -> person
+  const owner = new Map();        // handle key -> person id
+  const ignored = new Set();      // handle keys
+  const closed = new Set();       // merge-proposal pair keys the PM kept separate
+  const sightings = [];
+  const proposals = [];
+
+  // 1 · decisions, in file order; the calendar setting first so the sightings below read the final value
+  for (const r of rows || []) {
+    if (!isObj(r)) continue;
+    counts.rows++;
+    if (DECISION_KINDS.has(r.kind) && !isPm(r)) { counts.skipped++; continue; }
+    if (r.kind === 'setting' && typeof r.calendar_names === 'boolean') settings.calendar_names = r.calendar_names;
+  }
+  const attach = (id, h) => {
+    const k = handleKey(h);
+    const prev = owner.get(k);
+    if (prev && prev !== id && people.has(prev)) { const pp = people.get(prev); pp.handles = pp.handles.filter((x) => handleKey(x) !== k); }
+    owner.set(k, id);
+    ignored.delete(k);
+    const p = people.get(id);
+    if (!p.handles.some((x) => handleKey(x) === k)) p.handles.push({ kind: h.kind, value: h.value });
+  };
+  for (const r of rows || []) {
+    if (!isObj(r)) continue;
+    if (r.kind === 'sighting') {
+      const c = checkSighting(r);
+      if (c.ok) sightings.push({ ...c.row, at: r.at || null });
+      continue;
+    }
+    if (r.kind === 'merge-proposal') {
+      const c = checkMergeProposal(r);
+      if (c.ok) proposals.push({ ...c.row, at: r.at || null });
+      continue;
+    }
+    if (!DECISION_KINDS.has(r.kind) || !isPm(r) || r.kind === 'setting') continue;
+    const c = checkDecision({ ...r, act: r.kind });
+    if (!c.ok) { counts.skipped++; continue; }
+    const d = c.row;
+    if (d.kind === 'add') {
+      const k = handleKey(d.handle);
+      if (owner.has(k) && people.has(owner.get(k))) continue;
+      let id = slugOf(d.name);
+      for (let n = 2; people.has(id); n++) id = `${slugOf(d.name).slice(0, 56)}-${n}`;
+      people.set(id, { id, name: d.name, role: null, org: null, external: null, handles: [], tone: null, notes: new Map(), addedAt: r.at || null, edited: {} });
+      attach(id, d.handle);
+    } else if (d.kind === 'ignore') {
+      const k = handleKey(d.handle);
+      if (!owner.has(k)) ignored.add(k);
+    } else if (d.kind === 'merge') {
+      if (people.has(d.person)) attach(d.person, d.handle);
+    } else if (d.kind === 'keep-separate') {
+      closed.add(pairKey(d.a, d.b));
+    } else if (people.has(d.person)) {
+      const p = people.get(d.person);
+      if (d.kind === 'edit') {
+        for (const k of ['name', 'role', 'org', 'external']) if (d[k] !== undefined) { p[k] = d[k]; p.edited[k] = true; }
+      } else if (d.kind === 'tone') p.tone = d.tone;
+      else if (d.kind === 'note') p.notes.set(d.id, { id: d.id, text: d.text, at: r.at || null });
+      else if (d.kind === 'note-remove') p.notes.delete(d.id);
+    }
+  }
+
+  // 2 · sightings: dedup, drop calendar ones while the setting is off, then hand each to its person or the review list
+  const seen = new Set();
+  const fresh = new Map();   // handle key -> { handle, name, role, org, external, count, sources, last }
+  const interactions = new Map();   // person id -> []
+  for (const s of sightings) {
+    const key = sightKey(s);
+    if (seen.has(key)) { counts.duplicates++; continue; }
+    seen.add(key);
+    if (s.source === 'calendar' && !settings.calendar_names) { counts.hiddenCalendar++; continue; }
+    const k = handleKey(s.handle);
+    const id = owner.get(k);
+    if (id && people.has(id)) {
+      const p = people.get(id);
+      for (const f of ['role', 'org']) if (s[f] && !p.edited[f]) p[f] = s[f];
+      if (s.external === true && !p.edited.external) p.external = true;
+      if (s.interaction) {
+        if (!interactions.has(id)) interactions.set(id, []);
+        interactions.get(id).push({ ...s.interaction, source: s.source, handle: s.handle, at: s.at });
+      }
+      continue;
+    }
+    if (ignored.has(k)) continue;
+    const f = fresh.get(k) || { handle: s.handle, name: s.name, role: null, org: null, external: false, count: 0, sources: [], last: null };
+    f.name = s.name;
+    if (s.role) f.role = s.role;
+    if (s.org) f.org = s.org;
+    if (s.external) f.external = true;
+    f.count++;
+    if (!f.sources.includes(s.source)) f.sources.push(s.source);
+    const d = s.interaction ? s.interaction.date : (s.at || '').slice(0, 10);
+    if (d && (!f.last || d > f.last)) f.last = d;
+    fresh.set(k, f);
+  }
+
+  // 3 · each person's page
+  const today = new Date(now).toISOString().slice(0, 10);
+  const list = [...people.values()].filter((p) => p.handles.length).map((p) => {
+    const ints = (interactions.get(p.id) || []).sort((a, b) => (b.date < a.date ? -1 : b.date > a.date ? 1 : String(b.at || '').localeCompare(String(a.at || ''))));
+    const mix = {};
+    for (const i of ints) if (i.tone) mix[i.tone] = (mix[i.tone] || 0) + 1;
+    const proposed = toneProposal(ints);
+    const inits = new Map();
+    for (const i of ints) if (i.initiative) {
+      const g = inits.get(i.initiative) || { id: i.initiative, count: 0, last: null };
+      g.count++; if (!g.last || i.date > g.last) g.last = i.date;
+      inits.set(i.initiative, g);
+    }
+    const person = {
+      id: p.id, name: p.name, role: p.role || null, org: p.org || null, external: p.external === true,
+      group: p.external === true ? 'External' : 'Team',
+      handles: p.handles.slice(),
+      interactions: ints,
+      tone: { proposed, confirmed: p.tone || null, mix, pending: !!proposed && !p.tone },
+      notes: [...p.notes.values()],
+      last: ints.length ? ints[0].date : (p.addedAt ? String(p.addedAt).slice(0, 10) : null),
+      count: ints.length,
+      shared: { initiatives: [...inits.values()].sort((a, b) => b.count - a.count || a.id.localeCompare(b.id)), items: [], meetings: [] },
+    };
+    return person;
+  });
+
+  // 4 · shared work from the repository: plan items owned by the person, and coming meetings that name them
+  for (const it of items || []) {
+    if (!it || it.state === 'withdrawn' || typeof it.owner !== 'string' || !it.owner.startsWith('person:')) continue;
+    const who = it.owner.slice(7);
+    for (const p of matchPeople(list, who)) {
+      p.shared.items.push({ id: it.id, title: it.title, initiative: it.initiative, state: it.state, blocked: !!it.blocked, reason: (it.blocked && ((typeof it.blocked === 'object' && it.blocked.reason) || it.reason)) || null, due: it.due || null });
+    }
+  }
+  if (settings.calendar_names) {
+    for (const m of meetings || []) {
+      if (!m || !m.with || !m.start || String(m.start).slice(0, 10) < today) continue;
+      for (const p of matchPeople(list, m.with)) if (p.shared.meetings.length < 5) p.shared.meetings.push({ start: m.start, title: m.title || '', with: m.with });
+    }
+    for (const p of list) p.shared.meetings.sort((a, b) => String(a.start).localeCompare(String(b.start)));
+  }
+  list.sort((a, b) => String(b.last || '').localeCompare(String(a.last || '')) || a.name.localeCompare(b.name));
+
+  // 5 · the review list: new handles, open merge proposals, tones the PM has not confirmed
+  const merges = [];
+  const shown = new Set();
+  for (const m of proposals) {
+    const pk = pairKey(m.a, m.b);
+    if (closed.has(pk) || shown.has(pk)) continue;
+    const oa = owner.get(handleKey(m.a)); const ob = owner.get(handleKey(m.b));
+    if (oa && ob && oa === ob) continue;
+    // Merge needs a person to join: the one holding a (or else b). Two handles nobody holds wait in "new" instead.
+    const into = oa && people.has(oa) ? oa : ob && people.has(ob) ? ob : null;
+    if (!into) continue;
+    const other = into === oa ? m.b : m.a;
+    if (ignored.has(handleKey(other))) continue;
+    shown.add(pk);
+    merges.push({ a: m.a, b: m.b, why: m.why, person: into, personName: people.get(into).name, handle: other });
+  }
+  const freshList = [...fresh.values()].sort((a, b) => String(b.last || '').localeCompare(String(a.last || '')) || b.count - a.count);
+  const tones = list.filter((p) => p.tone.pending).map((p) => p.id);
+  return {
+    people: list,
+    review: { new: freshList, merges, tones, count: freshList.length + merges.length + (tones.length ? 1 : 0) },
+    settings,
+    counts,
+  };
+}
+
+module.exports = {
+  LEDGER, SOURCES, HANDLE_KINDS, INTERACTION_KINDS, TONES, ACTS, TONE_WINDOW,
+  checkSighting, checkMergeProposal, checkDecision, fold, handleKey, slugOf, toneProposal, matchPeople, matchWords,
+};