create-evda 0.1.5 → 0.1.7

package/lib/messages.mjs

@@ -0,0 +1,205 @@
+// Dispatch through the record (HQ-1246): the owner's agent writes a message, the phone app shows it
+// as a card, and the owner's reply comes back as a file the agent reads on its next run.
+//
+// The format, which the phone app (iris-mobile, the EVÐA target) reads exactly:
+//
+//   <messages role>/YYYY-MM-DD-HHMM-<slug>.md          one message, written once by the agent
+//     ---
+//     id: <the filename stem>
+//     from: "<agent name>"
+//     title: "<title>"
+//     date: "<ISO 8601 with offset>"
+//     ---
+//     <markdown body>
+//
+//   <messages role>/<same stem>.reply.md               the owner's reply, written by the app
+//     ---
+//     in_reply_to: <the message id>
+//     date: "<ISO 8601 with offset>"
+//     ---
+//     <reply text>
+//
+//   <messages role>/.seen.json                          { "<id>": "<reply date seen>" }, the agent's
+//
+// The messages role resolves through evda.json like every other role, `messages/` when unmapped. A
+// message is never edited after it is written: a second message in the same minute with the same
+// slug gets `-2`, `-3`, and a file already at a name (a reply, or anything sealed) is never touched.
+// "Answered" is the reply file existing, never a stored flag. What the agent has seen is keyed by the
+// reply's date, so a reply the app rewrites after the agent read it shows again.
+//
+// Replies are read the way every other tool reads (lib/readers.mjs): a sealed reply is in no answer
+// and a sealed section is cut out, a noted reply or one in a circle set to a different reader is held
+// back and named, and nothing held back is marked seen.
+//
+// EVDA_MESSAGES_FALSIFY=<mode,...>, for the tests. Each breaks exactly one rule:
+//   overwrite     a colliding name is written over instead of getting a suffix
+//   orphans       a reply with no message is returned
+//   seen-by-id    a reply whose id was ever seen stays hidden, whatever its date
+//   strict-seen   a .seen.json that does not parse throws instead of reading as empty
+//   no-secrets    the secret check is skipped
+//   default-path  the evda.json mapping is ignored and messages/ is always used
+//   raw-slug      the title goes into the filename unslugged
+//   no-readers    replies are shown without asking lib/readers.mjs
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { resolveRole, agentsFile } from "./roles.mjs";
+import { frontmatterOf } from "./circles.mjs";
+import { readContext, mayRead, heldBack, callerFrom, aiView } from "./readers.mjs";
+import { localDate } from "./day-file.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const MESSAGES_ROLE = "messages";
+export const MESSAGES_DEFAULT = "messages";
+export const SEEN_FILE = ".seen.json";
+export const REPLY_SUFFIX = ".reply.md";
+export const DEFAULT_FROM = "Iris";
+const TITLE_MAX = 200;
+const FROM_MAX = 60;
+const BODY_MAX = 200_000;
+const SLUG_MAX = 60;
+
+export const MESSAGES_FALSIFY_MODES = ["overwrite", "orphans", "seen-by-id", "strict-seen", "no-secrets", "default-path", "raw-slug", "no-readers"];
+const falsified = (mode) => (process.env.EVDA_MESSAGES_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const pad = (n) => String(n).padStart(2, "0");
+const refuse = (message, code) => new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+
+// A local time as ISO 8601 with its offset: 2026-09-25T12:04:00-05:00.
+export function isoLocal(d) {
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? "+" : "-";
+  const a = Math.abs(off);
+  return `${localDate(d)}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${pad(Math.floor(a / 60))}:${pad(a % 60)}`;
+}
+
+// A title as a filename part: accents folded, lowercase ASCII letters and digits joined by single
+// hyphens, at most 60 characters. A title with nothing left (all emoji, all Greek) is "message".
+export function slugify(title) {
+  if (falsified("raw-slug")) return String(title);
+  const s = String(title).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.slice(0, SLUG_MAX).replace(/-+$/, "") || "message";
+}
+
+// Where messages live: the role's mapping, else messages/ at the record root. resolveRole refuses a
+// mapping that leaves the record.
+export function messagesDir(evda) {
+  const r = falsified("default-path") ? { mapped: false } : resolveRole(evda, MESSAGES_ROLE);
+  if (r.mapped) {
+    if (r.exists && !r.isDir) throw refuse(`the messages role is mapped to ${r.rel}, which is a file; it holds a folder.`, "BAD_MAPPING");
+    return { abs: r.abs, rel: r.rel.replace(/\/+$/, "") };
+  }
+  return { abs: join(evda.dir, MESSAGES_DEFAULT), rel: MESSAGES_DEFAULT };
+}
+
+// The agent's name as the operating layer's owner section gives it, else Iris.
+export function agentName(evda) {
+  try {
+    const a = agentsFile(evda);
+    if (!a) return DEFAULT_FROM;
+    const m = /^- \*\*Agent name:\*\*[ \t]*(\S.*)$/m.exec(readFileSync(a.abs, "utf8"));
+    return m?.[1]?.trim() || DEFAULT_FROM;
+  } catch {
+    return DEFAULT_FROM;
+  }
+}
+
+function oneLine(value, name, max) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`evda_message needs "${name}".`, "EMPTY");
+  const v = value.trim();
+  if (/[\r\n]/.test(v)) throw refuse(`evda_message "${name}" is one line.`, "LINES");
+  if (v.length > max) throw refuse(`evda_message "${name}" is ${v.length} characters; at most ${max}.`, "TOO_LONG");
+  return v;
+}
+
+// Write one new message. `refuseSecrets` is passed in by lib/tools.mjs so this module and evda_write
+// refuse with the same check and the same words.
+export function writeMessage(evda, args, { now = new Date(), refuseSecrets } = {}) {
+  const title = oneLine(args.title, "title", TITLE_MAX);
+  if (typeof args.body !== "string" || args.body.trim() === "") throw refuse('evda_message needs "body", what you are telling the owner.', "EMPTY");
+  if (args.body.length > BODY_MAX) throw refuse(`evda_message "body" is ${args.body.length} characters; one message holds at most ${BODY_MAX}.`, "TOO_LONG");
+  const from = args.from === undefined ? agentName(evda) : oneLine(args.from, "from", FROM_MAX);
+  if (!falsified("no-secrets")) for (const s of [title, args.body, from]) refuseSecrets(s, "evda_message");
+  const dir = messagesDir(evda);
+  mkdirSync(dir.abs, { recursive: true });
+  const base = `${localDate(now)}-${pad(now.getHours())}${pad(now.getMinutes())}-${slugify(title)}`;
+  const taken = (stem) => existsSync(join(dir.abs, `${stem}.md`)) || existsSync(join(dir.abs, `${stem}${REPLY_SUFFIX}`));
+  let stem = base;
+  if (!falsified("overwrite")) for (let n = 2; taken(stem); n++) stem = `${base}-${n}`;
+  const abs = join(dir.abs, `${stem}.md`);
+  const text = ["---", `id: ${stem}`, `from: ${JSON.stringify(from)}`, `title: ${JSON.stringify(title)}`, `date: ${JSON.stringify(isoLocal(now))}`, "---", "", args.body.replace(/\n+$/, ""), ""].join("\n");
+  // "wx": never replace a file, even one that appeared between the check and the write.
+  writeFileSync(abs, text, { flag: falsified("overwrite") ? "w" : "wx" });
+  return { id: stem, path: relative(evda.dir, abs).split(sep).join("/") };
+}
+
+// What the agent has seen, as { id: reply date }. Missing, unreadable, or not a JSON object of
+// strings: empty, so every reply shows and the next mark rewrites the file whole.
+export function readSeen(dirAbs) {
+  const p = join(dirAbs, SEEN_FILE);
+  if (!existsSync(p)) return {};
+  let v;
+  try { v = JSON.parse(readFileSync(p, "utf8")); } catch (e) { if (falsified("strict-seen")) throw e; return {}; }
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return {};
+  return Object.fromEntries(Object.entries(v).filter(([, d]) => typeof d === "string"));
+}
+
+function writeSeen(dirAbs, seen) {
+  const p = join(dirAbs, SEEN_FILE);
+  const t = `${p}.tmp-${process.pid}`;
+  writeFileSync(t, JSON.stringify(seen, null, 2) + "\n");
+  renameSync(t, p);
+}
+
+// The text after a file's frontmatter.
+function bodyOf(text) {
+  const lines = text.split("\n");
+  if (lines[0] !== "---") return text;
+  const end = lines.indexOf("---", 1);
+  return end === -1 ? text : lines.slice(end + 1).join("\n");
+}
+
+const dateString = (v) => (v instanceof Date ? v.toISOString() : typeof v === "string" && v.trim() !== "" ? v.trim() : null);
+
+// The owner's replies the agent has not seen: { replies: [{ id, title, reply, date, path }], heldBack,
+// marked }. Marks each one returned as seen unless `peek`. A reply with no message is not one.
+export function unseenReplies(evda, { peek = false } = {}, { caller = callerFrom() } = {}) {
+  const dir = messagesDir(evda);
+  if (!existsSync(dir.abs) || !statSync(dir.abs).isDirectory()) return { replies: [], heldBack: "", marked: 0, dir: dir.rel };
+  const seen = readSeen(dir.abs);
+  const ctx = readContext(evda);
+  const refused = [];
+  let sealed = false;
+  const replies = [];
+  for (const name of readdirSync(dir.abs).sort()) {
+    if (!name.endsWith(REPLY_SUFFIX) || name.startsWith(".")) continue;
+    const id = name.slice(0, -REPLY_SUFFIX.length);
+    const abs = join(dir.abs, name);
+    if (!statSync(abs).isFile()) continue;
+    const msgAbs = join(dir.abs, `${id}.md`);
+    if (!existsSync(msgAbs) && !falsified("orphans")) continue;
+    if (!falsified("no-readers")) {
+      const may = mayRead(ctx, abs, caller);
+      if (!may.ok) { refused.push(may); continue; }
+    }
+    const raw = readFileSync(abs, "utf8");
+    const front = frontmatterOf(raw) ?? {};
+    const date = dateString(front.date) ?? statSync(abs).mtime.toISOString();
+    if (falsified("seen-by-id") ? id in seen : seen[id] === date) continue;
+    const shown = falsified("no-readers") ? { text: raw, sections: 0 } : aiView(raw);
+    if (shown.sections) sealed = true;
+    let title = id;
+    if (existsSync(msgAbs)) {
+      const mraw = readFileSync(msgAbs, "utf8");
+      const mfront = frontmatterOf(mraw);
+      if (typeof mfront?.title === "string" && mfront.title.trim()) title = mfront.title.trim();
+    }
+    replies.push({ id, title, reply: bodyOf(shown.text).replace(/^\n+|\n+$/g, ""), date, path: relative(evda.dir, abs).split(sep).join("/") });
+  }
+  replies.sort((a, b) => (a.date === b.date ? a.id.localeCompare(b.id) : a.date.localeCompare(b.date)));
+  if (!peek && replies.length) {
+    for (const r of replies) seen[r.id] = r.date;
+    writeSeen(dir.abs, seen);
+  }
+  return { replies, heldBack: heldBack(refused, { sealed }), marked: peek ? 0 : replies.length, dir: dir.rel };
+}

package/lib/migrate-people.mjs

@@ -0,0 +1,231 @@
+// Migrate an untyped People doc to a person-profile entry (HQ-1189), by adding frontmatter only.
+//
+// The six rules, each implemented once below:
+//   1. The file is copied to <record root>/.backup/people-migration-<YYYY-MM-DD>/ first.
+//   2. Frontmatter is added and nothing below it changes: kind, id (filename slug), schemaVersion,
+//      name (the H1), observations. A file that already has frontmatter is skipped and reported.
+//   3. One observation per dated H2/H3 heading: text is the heading text, since is its date at the
+//      precision written (day or month). A range uses its start. A year-only heading stays prose.
+//   4. supersededBy only when a heading says it replaces an earlier one AND exactly one earlier
+//      observation fits. Otherwise it stays unlinked and is listed.
+//   5. A quote is attached only when its line names the speaker (`Name: "..."`, `"..." (Name, ...)`
+//      or `"..." -- Name`), only when the section has exactly one such line (an observation holds one
+//      quote), and only when the speaker is the profiled person or the owner, by first or full name.
+//      The owner is provenance owner; the person is provenance person with by naming them.
+//   6. Undated sections stay prose.
+// Before a file is reported done, the bytes after the frontmatter are hashed against the original.
+// A doc with no dated heading is left untouched and reported: a profile needs one observation.
+
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { findRoot, holderOf, readManifest } from "./manifest.mjs";
+import { readEntry } from "./kinds.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { carries, frontmatterOf, heldBy, sealedSections, NOTED, SEALED } from "./circles.mjs";
+
+// The lines of a body with every line of a sealed section blanked, so nothing in one becomes an
+// observation, a name or a quote in frontmatter every reader shows (HQ-1414). Line numbers are kept.
+// EVDA_CARRY_FALSIFY=migrate-people:sealed reads sealed sections like any other line.
+function openLines(text) {
+  const lines = text.split("\n");
+  if (!carries("migrate-people", SEALED)) return lines;
+  for (const s of sealedSections(text)) for (let i = s.start; i <= s.end; i++) lines[i] = "";
+  return lines;
+}
+
+const MONTHS = ["january", "february", "march", "april", "may", "june", "july", "august", "september", "october", "november", "december"];
+const MONTH_WORD = "(Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|Aug(?:ust)?|Sept?(?:ember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\\.?";
+const RANGE_SEP = "\\s*(?:-|\\u2013|\\u2014|to|through)\\s*";
+
+const monthNumber = (word) => MONTHS.findIndex((m) => m.startsWith(word.toLowerCase().replace(/\.$/, "").slice(0, 3))) + 1;
+const two = (n) => String(n).padStart(2, "0");
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+function realDay(y, m, d) {
+  const t = new Date(Date.UTC(y, m - 1, d));
+  return t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+}
+
+// The date a heading carries, at the precision written, or null. Returns { since, at, length }.
+export function headingDate(text) {
+  const found = [];
+  const add = (re, make) => {
+    const m = re.exec(text);
+    if (m) { const since = make(m); if (since) found.push({ since, at: m.index, length: m[0].length }); }
+  };
+  add(/\b(\d{4})-(\d{2})-(\d{2})\b/, (m) => (realDay(+m[1], +m[2], +m[3]) ? `${m[1]}-${m[2]}-${m[3]}` : null));
+  add(/\b(\d{4})-(0[1-9]|1[0-2])\b(?!-\d)/, (m) => `${m[1]}-${m[2]}`);
+  add(new RegExp(`\\b${MONTH_WORD}\\s+(\\d{1,2})(?:st|nd|rd|th)?(?:${RANGE_SEP}\\d{1,2}(?:st|nd|rd|th)?)?,?\\s+(\\d{4})\\b`, "i"), (m) => {
+    const mo = monthNumber(m[1]);
+    return realDay(+m[3], mo, +m[2]) ? `${m[3]}-${two(mo)}-${two(+m[2])}` : null;
+  });
+  add(new RegExp(`\\b${MONTH_WORD}${RANGE_SEP}${MONTH_WORD}\\s+(\\d{4})\\b`, "i"), (m) => `${m[3]}-${two(monthNumber(m[1]))}`);
+  add(new RegExp(`\\b${MONTH_WORD}\\s+(\\d{4})\\b`, "i"), (m) => `${m[2]}-${two(monthNumber(m[1]))}`);
+  if (found.length === 0) return null;
+  // Earliest in the heading wins; at the same position the longest (most specific) match wins.
+  found.sort((a, b) => a.at - b.at || b.length - a.length);
+  return found[0];
+}
+
+// Every H2/H3 heading in a body that carries a date: the same definition planProfile uses for "a
+// dated section" (the rule in CLAUDE.md this migration implements). Shared with doctor.mjs's
+// heading-coverage check, so the two can never disagree about what counts as one.
+export function datedHeadings(text) {
+  const out = [];
+  for (const l of openLines(text)) {
+    const m = /^(#{1,3})\s+(.*?)\s*#*\s*$/.exec(l);
+    if (!m || m[1].length === 1) continue;
+    const date = headingDate(m[2]);
+    if (date) out.push({ text: m[2], since: date.since });
+  }
+  return out;
+}
+
+const REPLACES = /\b(?:no longer (?:holds?|true|applies|stands)|replaces|supersedes|superseded|revises|revised|corrects|corrected|correction to|overturns|instead of)\b/i;
+
+export const slug = (s) => s.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// A line that names its speaker and holds exactly one quoted span. Returns { speaker, words } or null.
+const QUOTED = /["\u201c]([^"\u201c\u201d]+)["\u201d]/g;
+export function speakerQuote(line) {
+  const spans = [...line.matchAll(QUOTED)];
+  if (spans.length !== 1) return null;
+  const words = spans[0][1].trim();
+  if (!words) return null;
+  const before = line.slice(0, spans[0].index);
+  const after = line.slice(spans[0].index + spans[0][0].length);
+  const NAME = "([A-Z][A-Za-z'.]*(?: [A-Z][A-Za-z'.]*)?)";
+  let m = new RegExp(`^\\s*(?:>\\s*)?(?:[-*]\\s+)?\\**${NAME}\\**\\s*:\\s*\\**_?\\*?$`).exec(before);
+  if (m) return { speaker: m[1], words };
+  m = new RegExp(`^\\s*\\*?_?\\s*\\(${NAME}(?:,[^)]*)?\\)`).exec(after);
+  if (m) return { speaker: m[1], words };
+  m = new RegExp(`^\\s*\\*?_?\\s*(?:\\u2014|\\u2013|--?)\\s*${NAME}\\b`).exec(after);
+  if (m) return { speaker: m[1], words };
+  return null;
+}
+
+// Plan the frontmatter for one doc. Pure: reads nothing from disk.
+export function planProfile({ fileName, text, owner }) {
+  const notes = [];
+  // A sealed or just-noted file always has frontmatter, so it is skipped here and never rewritten.
+  // EVDA_CARRY_FALSIFY=migrate-people:noted lets a noted one through, as a migration that read past
+  // its frontmatter would, to show this skip is what keeps it noted.
+  const falsifiedNoted = !carries("migrate-people", NOTED) && frontmatterOf(text)?.[NOTED] === true && !heldBy(frontmatterOf(text), "migrate-people");
+  if (/^---\r?\n/.test(text) && !falsifiedNoted) return { skip: "already has frontmatter" };
+  const lines = openLines(text);
+  const h1 = lines.find((l) => /^# \S/.test(l));
+  if (!h1) return { skip: "has no H1 to take the name from" };
+  const name = h1.slice(2).trim();
+  const first = name.split(/\s+/)[0];
+  const ownerFirst = String(owner).split(/\s+/)[0];
+
+  const headings = [];
+  lines.forEach((l, i) => { const m = /^(#{1,3})\s+(.*?)\s*#*\s*$/.exec(l); if (m) headings.push({ line: i, level: m[1].length, text: m[2] }); });
+
+  const observations = [];
+  const ids = new Set();
+  headings.forEach((h, k) => {
+    if (h.level === 1) return;
+    const date = headingDate(h.text);
+    if (!date) return;
+    let id = slug(h.text) || `o${observations.length + 1}`;
+    for (let n = 2; ids.has(id); n++) id = `${slug(h.text)}-${n}`;
+    ids.add(id);
+    const end = k + 1 < headings.length ? headings[k + 1].line : lines.length;
+    const quotes = [];
+    for (let i = h.line + 1; i < end; i++) { const q = speakerQuote(lines[i]); if (q) quotes.push({ ...q, line: i + 1 }); }
+    observations.push({ obs: { id, since: date.since, text: h.text }, heading: h, date, quotes, order: observations.length });
+  });
+
+  // Rule 5.
+  for (const o of observations) {
+    if (o.quotes.length === 0) continue;
+    if (o.quotes.length > 1) { notes.push(`quote not attached: "${o.heading.text}" has ${o.quotes.length} lines naming a speaker (lines ${o.quotes.map((q) => q.line).join(", ")}), and an observation holds one`); continue; }
+    const q = o.quotes[0];
+    const isOwner = q.speaker === owner || q.speaker === ownerFirst;
+    const isPerson = q.speaker === name || q.speaker === first;
+    if (!isOwner && !isPerson) { notes.push(`quote not attached: "${o.heading.text}" line ${q.line} names ${q.speaker}, who is neither ${name} nor the owner`); continue; }
+    const by = isOwner ? owner : name;
+    o.obs.quote = { words: q.words, provenance: isOwner ? "owner" : "person", by };
+  }
+
+  // Ordering: a month sorts as its first day, for ordering only.
+  const key = (s) => (s.length === 7 ? `${s}-01` : s);
+  // Rule 4.
+  for (const o of observations) {
+    const rest = o.heading.text.slice(0, o.date.at) + " " + o.heading.text.slice(o.date.at + o.date.length);
+    if (!REPLACES.test(rest)) continue;
+    const named = MONTHS.map((m, i) => (new RegExp(`\\b${m[0].toUpperCase()}${m.slice(1)}\\b`).test(rest) ? i + 1 : 0)).filter(Boolean);
+    const earlier = observations.filter((e) => e !== o && key(e.obs.since) < key(o.obs.since));
+    const fits = named.length ? earlier.filter((e) => named.includes(Number(e.obs.since.slice(5, 7)))) : earlier;
+    if (fits.length === 1) {
+      if (fits[0].obs.supersededBy) { notes.push(`unlinked: "${o.heading.text}" fits "${fits[0].heading.text}", which is already superseded`); continue; }
+      fits[0].obs.supersededBy = o.obs.id;
+    } else {
+      notes.push(`unlinked: "${o.heading.text}" says it replaces an earlier section, and ${fits.length} fit${fits.length ? `: ${fits.map((f) => `"${f.heading.text}"`).join(", ")}` : ""}`);
+    }
+  }
+
+  if (observations.length === 0) return { skip: "has no dated H2 or H3 heading, so there is no observation; left as prose" };
+
+  observations.sort((a, b) => (key(a.obs.since) < key(b.obs.since) ? -1 : key(a.obs.since) > key(b.obs.since) ? 1 : a.order - b.order));
+  const entry = {
+    kind: "person-profile",
+    id: slug(fileName.replace(/\.md$/i, "")),
+    schemaVersion: "0.1",
+    name,
+    observations: observations.map((o) => o.obs),
+  };
+  const frontmatter = `---\n${toYaml(entry)}---\n`;
+  const problems = readEntry("person-profile", parseYaml(frontmatter.slice(4, -4)), { owner }).problems;
+  return { entry, frontmatter, notes, problems };
+}
+
+// The body below a written frontmatter is the original, byte for byte.
+export function bodyMatches(original, written, frontmatter) {
+  const head = Buffer.from(frontmatter, "utf8");
+  if (!written.subarray(0, head.length).equals(head)) return false;
+  return sha256(written.subarray(head.length)) === sha256(original);
+}
+
+const today = () => { const d = new Date(); return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`; };
+
+// Migrate files. Returns one result per file: { file, status: done|would|skipped|failed, ... }.
+export function migratePeople(files, { dry = false, date = today(), root = null } = {}) {
+  const results = [];
+  for (const file of files) {
+    const r = { file };
+    results.push(r);
+    if (basename(file) === "README.md") { Object.assign(r, { status: "skipped", why: "is a folder README, not a person profile" }); continue; }
+    const recordRoot = root ?? findRoot(dirname(file));
+    if (!recordRoot) { Object.assign(r, { status: "failed", why: "no evda.json above this file" }); continue; }
+    const owner = (() => { const h = holderOf(readManifest(recordRoot)); return h.id ?? h.name; })();
+    if (!owner) { Object.assign(r, { status: "failed", why: "evda.json names no owner" }); continue; }
+    const original = readFileSync(file);
+    const plan = planProfile({ fileName: basename(file), text: original.toString("utf8"), owner });
+    if (plan.skip) { Object.assign(r, { status: "skipped", why: plan.skip }); continue; }
+    Object.assign(r, { frontmatter: plan.frontmatter, notes: plan.notes, observations: plan.entry.observations.length });
+    if (plan.problems.length) { Object.assign(r, { status: "failed", why: `the frontmatter would not read as a person-profile: ${plan.problems.join("; ")}` }); continue; }
+    const backupDir = join(recordRoot, ".backup", `people-migration-${date}`);
+    r.backup = join(backupDir, basename(file));
+    if (dry) { r.status = "would"; continue; }
+    mkdirSync(backupDir, { recursive: true });
+    if (existsSync(r.backup) && sha256(readFileSync(r.backup)) !== sha256(original)) {
+      Object.assign(r, { status: "failed", why: `a different backup already exists at ${relative(recordRoot, r.backup)}; nothing written` });
+      continue;
+    }
+    copyFileSync(file, r.backup);
+    if (sha256(readFileSync(r.backup)) !== sha256(original)) { Object.assign(r, { status: "failed", why: "the backup does not match the original; nothing written" }); continue; }
+    writeFileSync(file, Buffer.concat([Buffer.from(plan.frontmatter, "utf8"), original]));
+    const written = readFileSync(file);
+    if (!bodyMatches(original, written, plan.frontmatter)) {
+      writeFileSync(file, original);
+      Object.assign(r, { status: "failed", why: "the body below the frontmatter did not hash to the original; restored the original" });
+      continue;
+    }
+    r.bodySha256 = sha256(original);
+    r.status = "done";
+  }
+  return results;
+}