create-pmos 0.132.0 → 0.133.0

package/workspace/lib/vendor/scripts/onboarding/scan.js

@@ -0,0 +1,859 @@
+'use strict';
+/* scan.js: the READ-ONLY, deterministic first scan of an existing product folder (onboarding-scan-and-map, slice 1).
+ *
+ *   const { scan } = require('./onboarding/scan.js');
+ *   scan(root, { domain, today })  ->  { classes, totals, candidates, capped, ... }
+ *
+ * What it does: it runs the layout classifier (scripts/migrate-layout.js plan, in-place strategy), reads the prose
+ * documents the classifier found, and turns what the files SAY into candidates. A candidate is a PROPOSAL, never a change:
+ * { id, kind, title, proposed, evidence[{file,line,quote}], confidence, source, label, supply, needs_pm, detail }.
+ *
+ * What it never does: write into the folder it scans, call a model, guess a person's name from free text, read a file over
+ * the size limit, or read a binary. It runs `git log` (a read) for last-commit dates.
+ * Every extractor below is a pure function over file text, so it can be tested alone.
+ * Text from the folder is untrusted data (scripts/trust/import-guard.js): evidence quotes are cut at 160 characters, a
+ * quote that looks like an instruction is flagged in `detail.guard`, and no text from a file is ever treated as a command.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const cp = require('child_process');
+const migrate = require('../migrate-layout.js');
+const guard = require('../trust/import-guard.js');
+const briefLib = require('./brief.js');
+
+const KINDS = ['INITIATIVE', 'OBJECTIVE', 'KR', 'DEADLINE', 'DECISION', 'PERSON', 'RISK', 'OPEN_QUESTION', 'STALE', 'DUPLICATE', 'BROKEN_LINK', 'MISSING_ANCHOR', 'DOCUMENT'];
+const DEFAULT_CAPS = { INITIATIVE: 80, OBJECTIVE: 40, KR: 80, DEADLINE: 120, DECISION: 80, PERSON: 60, RISK: 80, OPEN_QUESTION: 80, STALE: 80, DUPLICATE: 60, BROKEN_LINK: 80, MISSING_ANCHOR: 60, DOCUMENT: 300 };
+const CONF_RANK = { high: 0, medium: 1, low: 2 };
+const LANES = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'];
+const DEFAULT_MAX_TEXT = 1024 * 1024; // a document over 1 MB is not read
+const STALE_DAYS = 90;
+const DAY = 86400000;
+const MONTHS = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const MON_RE = '(Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)';
+
+// ── small helpers ───────────────────────────────────────────────────────────────────────────────────────────────
+const posix = (p) => p.split(path.sep).join('/');
+const quote = (s) => String(s).trim().replace(/\s+/g, ' ').slice(0, 160);
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const iso = (y, m, d) => `${String(y).padStart(4, '0')}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+const validYmd = (y, m, d) => { const t = new Date(Date.UTC(y, m - 1, d)); return t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d; };
+const lastDay = (y, m) => new Date(Date.UTC(y, m, 0)).getUTCDate();
+const daysBetween = (isoDate, today) => Math.round((Date.parse(isoDate + 'T00:00:00Z') - Date.parse(today + 'T00:00:00Z')) / DAY);
+const isReserved = (rel) => /^(index|log)\.md$/i.test(path.posix.basename(rel));
+const mdFile = (rel) => /\.(md|markdown)$/i.test(rel);
+const stem = (rel) => path.posix.basename(rel).replace(/\.[^.]+$/, '');
+
+/** Lines of `text` that are inside a fenced code block (1-based set). Code is not a deadline or a risk. */
+function fencedLines(lines) {
+  const set = new Set(); let open = null;
+  lines.forEach((l, i) => {
+    const m = /^\s*(```+|~~~+)/.exec(l);
+    if (m) { if (open === null) { open = m[1][0]; } else if (m[1][0] === open) { open = null; } set.add(i + 1); return; }
+    if (open !== null) set.add(i + 1);
+  });
+  return set;
+}
+
+// ── frontmatter with line numbers (parseFrontmatter in migrate-layout has no lines and ignores lists) ───────────────
+function fmInfo(text) {
+  const lines = String(text).split('\n');
+  if (!lines.length || lines[0].trim() !== '---') return { fm: null, end: 0, lines, keyLine: {}, lists: {} };
+  const fm = {}; const keyLine = {}; const lists = {}; let lastKey = null; let end = 0;
+  for (let i = 1; i < lines.length; i++) {
+    const l = lines[i];
+    if (l.trim() === '---') { end = i + 1; break; }
+    const m = /^([A-Za-z0-9_-]+):\s?(.*)$/.exec(l);
+    if (m) {
+      lastKey = m[1];
+      let v = m[2].trim();
+      if (/^(".*"|'.*')$/.test(v)) v = v.slice(1, -1);
+      if (!(lastKey in fm)) { fm[lastKey] = v; keyLine[lastKey] = i + 1; }
+      const inl = /^\[(.*)\]$/.exec(v);
+      if (inl) lists[lastKey] = inl[1].split(',').map((x) => ({ value: x.trim().replace(/^["']|["']$/g, ''), line: i + 1 })).filter((x) => x.value);
+    } else {
+      const li = /^\s+-\s+(.+?)\s*$/.exec(l);
+      if (li && lastKey) { (lists[lastKey] = lists[lastKey] || []).push({ value: li[1].replace(/^["']|["']$/g, ''), line: i + 1 }); }
+    }
+  }
+  if (!end) return { fm: null, end: 0, lines, keyLine: {}, lists: {} }; // unterminated
+  return { fm, end, keyLine, lists, lines };
+}
+
+const EMPTYISH = new Set(['', 'null', 'none', 'tbd', 'n/a', 'na', '~', '-', 'unknown', '<id>', 'todo']);
+const emptyish = (v) => v === undefined || v === null || EMPTYISH.has(String(v).trim().toLowerCase());
+
+// ── extractor 1: initiative records ─────────────────────────────────────────────────────────────────────────────
+const INITIATIVE_RECORD_RE = /(^|\/)(state|planning)\/initiatives\/[^/]+\.md$/;
+const isInitiativeRecordPath = (rel) => INITIATIVE_RECORD_RE.test(rel) && !/\/archive\//.test(rel) && !/^(README|index)\.md$/i.test(path.posix.basename(rel));
+const isArchivedRecordPath = (rel) => /(^|\/)(state|planning)\/initiatives\/archive\/[^/]+\.md$/.test(rel) && !/^(README|index)\.md$/i.test(path.posix.basename(rel));
+
+/** An initiative record: frontmatter with an id (or a file name). Returns null when the file has no frontmatter. */
+function extractInitiativeRecord(text, rel) {
+  const info = fmInfo(text);
+  if (!info.fm) return null;
+  const fm = info.fm;
+  const id = !emptyish(fm.id) ? fm.id : stem(rel);
+  const laneRaw = fm.lane || fm.type || '';
+  const status = fm.status || '';
+  const ev = [];
+  const add = (key) => { if (info.keyLine[key]) ev.push({ line: info.keyLine[key], quote: quote(info.lines[info.keyLine[key] - 1]) }); };
+  add('id'); add('title'); add('parent_kr'); add('status');
+  if (!ev.length) ev.push({ line: 1, quote: quote(info.lines[0]) });
+  return {
+    id, title: fm.title || id, lane: LANES.includes(laneRaw) ? laneRaw : null, lane_raw: laneRaw || null,
+    parent_kr: emptyish(fm.parent_kr) ? null : fm.parent_kr, status, owner: emptyish(fm.owner) ? null : fm.owner,
+    jira_epic: emptyish(fm.jira_epic) ? null : fm.jira_epic, evidence: ev, anchored: !emptyish(fm.parent_kr),
+    anchor_line: info.keyLine.parent_kr || null, id_line: info.keyLine.id || 1,
+  };
+}
+
+/** A document that declares `initiative_id` (frontmatter or the kit's `- initiative_id:` prose line in the first 30 lines). */
+function extractDeclaredInitiativeId(text) {
+  const lines = String(text).split('\n');
+  for (let i = 0; i < Math.min(lines.length, 40); i++) {
+    const m = /^[-*\s]*initiative_id:\s*(.+?)\s*$/i.exec(lines[i]);
+    if (m) { const v = m[1].replace(/\s+#.*$/, '').replace(/\s*\*?\(.*$/, '').replace(/^["'`]+|["'`*]+$/g, '').trim(); if (!emptyish(v) && /^[A-Za-z0-9][A-Za-z0-9._\/-]{1,60}$/.test(v)) return { id: v, line: i + 1, quote: quote(lines[i]) }; }
+  }
+  return null;
+}
+
+/** Jira epic keys: `jira_epic:` in frontmatter, or a line that says "epic" next to a KEY-123 (used for files under jira/). */
+function extractJiraEpics(text) {
+  const lines = String(text).split('\n'); const out = []; const fenced = fencedLines(lines);
+  const info = fmInfo(text);
+  lines.forEach((l, i) => {
+    if (fenced.has(i + 1)) return;
+    const inFm = info.end && i + 1 <= info.end;
+    if (inFm) { const m = /^jira_epic:\s*["']?([A-Z][A-Z0-9]{1,9}-\d+)/.exec(l); if (m) out.push({ key: m[1], line: i + 1, quote: quote(l), via: 'frontmatter' }); return; }
+    if (!/\bepic\b/i.test(l)) return;
+    const m = /\b([A-Z][A-Z0-9]{1,9}-\d+)\b/.exec(l);
+    if (m) out.push({ key: m[1], line: i + 1, quote: quote(l), via: 'text' });
+  });
+  return out;
+}
+
+// ── extractor 2: objectives and key results ─────────────────────────────────────────────────────────────────────
+const OBJ_HEAD_ID = /^#{1,6}\s*\**\s*(O-?(?:[A-Z]|\d{1,2}))\b\**\s*[—:–.-]+\s*(.+?)\s*$/; // O-A, O1: an uppercase letter or digits, so "Open" is not an objective
+const OBJ_HEAD = /^#{1,6}\s*\**\s*(Objective\s*[A-Za-z0-9]{0,3})\b\**\s*[—:–.-]+\s*(.+?)\s*$/i;
+const OBJ_LINE = /^[\s>*+-]*\**\s*(Objective\s*[A-Za-z0-9]{0,3})\b\**\s*[:—–-]\s*(.+?)\s*$/i;
+const KR_LINE = /^[\s>*+-]*(?:\[[ xX]\]\s*)?\**\s*((?:O-?[A-Za-z0-9]{1,3}\.)?KR[-\s]?[A-Za-z]?-?\d+(?:\.\d+)*|Key Results?\s*\d+)\b\**\s*[—:–.\-]*\s*(.*)$/i;
+const NUM = '(-?\\d[\\d,]*\\.?\\d*)';
+const numOf = (s) => { const v = parseFloat(String(s).replace(/,/g, '')); return Number.isFinite(v) ? v : null; };
+
+/** Parse baseline, target and a by-date out of a KR paragraph. Only what is written; nothing is inferred. */
+function parseMetric(par) {
+  const s = String(par).replace(/\*+/g, '').replace(/`/g, '');
+  const out = { baseline: null, target: null, unit: null, by: null, by_iso: null };
+  let m = new RegExp('\\bfrom\\s+[^0-9]{0,30}?' + NUM + '\\s*(%|[a-z]{1,4}\\b)?[^.]{0,60}?\\bto\\s+(?:[≥≤<>~]=?\\s*)?' + NUM + '\\s*(%|[a-z]{1,4}\\b)?', 'i').exec(s);
+  if (m) { out.baseline = numOf(m[1]); out.target = numOf(m[3]); out.unit = m[4] === '%' || m[2] === '%' ? '%' : null; }
+  else {
+    const b = new RegExp('\\bbaseline[^0-9]{0,25}' + NUM, 'i').exec(s);
+    const t = new RegExp('\\btarget[^0-9]{0,25}' + NUM, 'i').exec(s) || new RegExp('(?:≥|>=|≤|<=)\\s*' + NUM + '\\s*(%)?', 'i').exec(s);
+    if (b) out.baseline = numOf(b[1]);
+    if (t) { out.target = numOf(t[1]); if (/%/.test(s.slice(t.index, t.index + t[0].length + 2))) out.unit = '%'; }
+  }
+  const by = new RegExp('\\bby\\s+(?:end of\\s+)?(' + MON_RE + '\\.?\\s+\\d{4}|\\d{4}-\\d{2}-\\d{2}|Q[1-4]\\s*\\d{4})', 'i').exec(s);
+  if (by) {
+    out.by = by[1];
+    const d = parseDates(by[0], '2000-01-01', { requireTrigger: false })[0];
+    if (d && !d.assumed_year) out.by_iso = d.iso;
+  }
+  return out;
+}
+
+function extractOkr(text) {
+  const lines = String(text).split('\n'); const fenced = fencedLines(lines);
+  const objectives = []; const krs = [];
+  lines.forEach((l, i) => {
+    if (fenced.has(i + 1)) return;
+    let m = OBJ_HEAD_ID.exec(l) || OBJ_HEAD.exec(l) || OBJ_LINE.exec(l);
+    if (m && !KR_LINE.test(l)) { objectives.push({ id: m[1].replace(/\s+/g, '').replace(/^objective/i, 'O'), title: quote(m[2].replace(/\*+/g, '').replace(/\.$/, '')), line: i + 1, quote: quote(l) }); return; }
+    m = KR_LINE.exec(l);
+    if (!m) return;
+    const par = [l]; for (let j = i + 1; j < Math.min(lines.length, i + 6); j++) { if (!lines[j].trim() || KR_LINE.test(lines[j]) || /^#{1,6}\s/.test(lines[j]) || OBJ_LINE.test(lines[j])) break; par.push(lines[j]); }
+    const rest = m[2] || '';
+    let title = rest.split('**')[0] || rest; title = title.replace(/\*+/g, '').replace(/[.\s]+$/, '').trim();
+    krs.push({ id: m[1].replace(/\s+/g, '').replace(/^Key Results?/i, 'KR'), title: quote(title) || m[1], line: i + 1, quote: quote(l), metric: parseMetric(par.join(' ')) });
+  });
+  return { objectives, krs };
+}
+
+// ── extractor 3: deadlines ──────────────────────────────────────────────────────────────────────────────────────
+const STRONG = /\b(due|deadline|go[- ]?live|ETA|cut-?over)\b/i;
+const WEAK = /\b(launch(?:es|ing)?|release[sd]?|ship(?:s|ping)?|GA|target(?:ed)?|milestone|freeze|expir\w*|renewal|deliver(?:y|ed|s)?|kick-?off|by)\b/i;
+const PAST_TENSE = /\b(released|launched|shipped|delivered|went live|completed|closed|done)\b/i;
+
+// Fiscal quarters. fyStart is the month number the fiscal year starts in. A fiscal year is named by the year it ENDS in
+// (FY2026 starting October runs Oct 2025 to Sep 2026): that is a convention, so every date it makes is labelled an assumption.
+function quarterEndFromFy(n, fyStart, fyStartYear) {
+  const startIdx = (fyStart - 1) + 3 * (n - 1); // months since January of fyStartYear
+  const endIdx = startIdx + 2; const y = fyStartYear + Math.floor(endIdx / 12); const mo = (endIdx % 12) + 1;
+  return { iso: iso(y, mo, lastDay(y, mo)) };
+}
+function fiscalQuarterOf(todayIso, fyStart) {
+  const y = +todayIso.slice(0, 4); const mo = +todayIso.slice(5, 7);
+  const fyStartYear = mo >= fyStart ? y : y - 1; const off = ((mo - fyStart) % 12 + 12) % 12;
+  return { n: Math.floor(off / 3) + 1, fyStartYear };
+}
+function fiscalQuarterEnd(n, fyStart, year, todayIso) {
+  if (year) return quarterEndFromFy(n, fyStart, fyStart === 1 ? year : year - 1);
+  return quarterEndFromFy(n, fyStart, fiscalQuarterOf(todayIso, fyStart).fyStartYear);
+}
+/** The month the fiscal year starts in, from 1..12, a month name ("Oct") or null. */
+function monthNumber(v) {
+  if (v === null || v === undefined || v === '') return null;
+  if (Number.isInteger(+v) && +v >= 1 && +v <= 12) return +v;
+  const k = String(v).slice(0, 3).toLowerCase(); return MONTHS[k] || null;
+}
+
+/** Dates in one line: ISO, "30 Oct 2026", "Oct 30, 2026", "30 Oct", "Oct 2026" (month end), "Q4 2026" / "Q4" (quarter end). */
+function dateTokens(line, todayYear, ctx) {
+  const out = []; let s = line;
+  const take = (re, fn) => { s = s.replace(re, (...a) => { const r = fn(a); const idx = a[a.length - (typeof a[a.length - 1] === 'object' ? 3 : 2)]; if (r) out.push(Object.assign({ index: idx, raw: a[0] }, r)); return ' '.repeat(a[0].length); }); };
+  take(/\b(\d{4})-(\d{2})-(\d{2})\b/g, (a) => (validYmd(+a[1], +a[2], +a[3]) ? { iso: iso(+a[1], +a[2], +a[3]), precision: 'day', assumed_year: false } : null));
+  take(new RegExp('\\b(\\d{1,2})(?:st|nd|rd|th)?\\s+' + MON_RE + '\\.?,?\\s+(\\d{4})\\b', 'gi'), (a) => { const mo = MONTHS[a[2].slice(0, 3).toLowerCase()]; return validYmd(+a[3], mo, +a[1]) ? { iso: iso(+a[3], mo, +a[1]), precision: 'day', assumed_year: false } : null; });
+  take(new RegExp('\\b' + MON_RE + '\\.?\\s+(\\d{1,2})(?:st|nd|rd|th)?,?\\s+(\\d{4})\\b', 'gi'), (a) => { const mo = MONTHS[a[1].slice(0, 3).toLowerCase()]; return validYmd(+a[3], mo, +a[2]) ? { iso: iso(+a[3], mo, +a[2]), precision: 'day', assumed_year: false } : null; });
+  take(new RegExp('\\b' + MON_RE + '\\.?\\s+(\\d{4})\\b', 'gi'), (a) => { const mo = MONTHS[a[1].slice(0, 3).toLowerCase()]; return { iso: iso(+a[2], mo, lastDay(+a[2], mo)), precision: 'month', assumed_year: false }; });
+  if (ctx && ctx.fyStart) { // fiscal quarters, and the user's own quarter names; every such date is an assumption
+    const names = ctx.quarterNames && ctx.quarterNames.length === 4 ? ctx.quarterNames.map((x) => String(x).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) : null;
+    const qre = names ? '(?:' + names.map((n, i) => '(?<q' + (i + 1) + '>' + n + ')').join('|') + '|Q(?<qn>[1-4]))' : 'Q(?<qn>[1-4])';
+    take(new RegExp('\\b' + qre + "\\s*['’]?\\s*(\\d{4})?\\b", 'g'), (a) => {
+      const g = a[a.length - 1]; const grp = g || {}; let n = grp.qn ? +grp.qn : 0;
+      if (!n) for (let i = 1; i <= 4; i++) if (grp['q' + i]) n = i;
+      if (!n) return null;
+      const yr = a.slice(1, a.length - 3).filter((x) => /^\d{4}$/.test(x || ''))[0];
+      return Object.assign({ precision: 'quarter', assumed_year: true, fiscal: true }, fiscalQuarterEnd(n, ctx.fyStart, yr ? +yr : null, ctx.todayIso));
+    });
+    if (ctx.todayIso) {
+      take(/\b(next|this)\s+quarter\b/gi, (a) => { const cur = fiscalQuarterOf(ctx.todayIso, ctx.fyStart); const n = /^next/i.test(a[1]) ? cur.n + 1 : cur.n; const nn = ((n - 1) % 4) + 1; const fy = cur.fyStartYear + Math.floor((n - 1) / 4); return Object.assign({ precision: 'quarter', assumed_year: true, fiscal: true }, quarterEndFromFy(nn, ctx.fyStart, fy)); });
+    }
+  }
+  take(/\bQ([1-4])\s*['’]?\s*(\d{4})\b/g, (a) => { const mo = +a[1] * 3; return { iso: iso(+a[2], mo, lastDay(+a[2], mo)), precision: 'quarter', assumed_year: false }; });
+  take(/\bQ([1-4])\b/g, (a) => { const mo = +a[1] * 3; return { iso: iso(todayYear, mo, lastDay(todayYear, mo)), precision: 'quarter', assumed_year: true }; });
+  take(new RegExp('\\b(\\d{1,2})(?:st|nd|rd|th)?\\s+' + MON_RE + '\\b(?!\\.?,?\\s+\\d{4})', 'gi'), (a) => { const mo = MONTHS[a[2].slice(0, 3).toLowerCase()]; return validYmd(todayYear, mo, +a[1]) ? { iso: iso(todayYear, mo, +a[1]), precision: 'day', assumed_year: true } : null; });
+  return out;
+}
+
+/** Deadline hits in a document. A date counts only next to a trigger word on its line (due, deadline, launch, release,
+ * go-live, by, ETA ...). `today` only fixes the year of a date that gives none. Returns [{line, quote, iso, precision,
+ * assumed_year, trigger, strength}]. */
+function parseDates(line, today, { requireTrigger = true, ctx = null } = {}) {
+  const yr = +String(today).slice(0, 4);
+  const toks = dateTokens(line, yr, ctx);
+  if (!toks.length) return [];
+  if (!requireTrigger) return toks.map((t) => ({ iso: t.iso, precision: t.precision, assumed_year: t.assumed_year, fiscal: !!t.fiscal, trigger: null, strength: 'strong' }));
+  // a date counts only when a trigger word is close to IT: up to 60 characters before it or 25 after it, on the same line
+  const trigs = []; const re = new RegExp(STRONG.source + '|' + WEAK.source, 'gi'); let m;
+  while ((m = re.exec(line))) trigs.push({ word: m[0], index: m.index, end: m.index + m[0].length, strong: STRONG.test(m[0]) });
+  const out = [];
+  for (const t of toks) {
+    const tEnd = t.index + t.raw.length; let best = null;
+    for (const g of trigs) {
+      const before = t.index - g.end; const after = g.index - tEnd;
+      if (/^by$/i.test(g.word)) { if (!(before >= 0 && before <= 16 && /\bby\s+(?:the\s+)?(?:end of\s+)?$/i.test(line.slice(g.index, t.index)))) continue; }
+      let d = before >= 0 && before <= 60 ? before : after >= 0 && after <= 25 ? after : null;
+      if (d === null) continue;
+      if (!best || d < best.d || (d === best.d && g.strong)) best = { g, d };
+    }
+    if (best) out.push({ iso: t.iso, precision: t.precision, assumed_year: t.assumed_year, fiscal: !!t.fiscal, trigger: best.g.word, strength: best.g.strong ? 'strong' : 'weak' });
+  }
+  return out;
+}
+
+const FM_DEADLINE_KEYS = /^(due|due_date|deadline|launch|launch_date|go_live|golive|eta|release|release_date|target|target_release|target_date|target_window|next_milestone)$/i;
+
+function extractDeadlines(text, rel, today, ctx) {
+  const info = fmInfo(text); const lines = info.lines; const fenced = fencedLines(lines); const out = []; const seen = new Set();
+  lines.forEach((l, i) => {
+    const n = i + 1;
+    if (fenced.has(n) || /^\s*\|?\s*:?-{2,}/.test(l) || /^\s*<!--/.test(l) || /placeholder/i.test(l) || /\b(dropped|removed|voided?|cancell?ed|superseded|no longer|was dropped|no launch date)\b/i.test(l)) return; // a date that was dropped is not a deadline
+    let hits;
+    if (info.end && n <= info.end) {
+      const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(l);
+      if (!m || !FM_DEADLINE_KEYS.test(m[1])) return;
+      hits = parseDates(l, today, { requireTrigger: false, ctx }).map((h) => Object.assign(h, { trigger: m[1], strength: /^(due|due_date|deadline|eta|go_live|golive)$/i.test(m[1]) ? 'strong' : 'weak' }));
+    } else {
+      if (PAST_TENSE.test(l) && !STRONG.test(l)) { // "released 2026-05-01" is a fact about the past, not a deadline
+        hits = parseDates(l, today, { ctx }).filter((h) => daysBetween(h.iso, today) >= 0);
+      } else hits = parseDates(l, today, { ctx });
+    }
+    for (const h of hits) {
+      const k = h.iso + '|' + n; if (seen.has(k)) continue; seen.add(k);
+      out.push(Object.assign(h, { line: n, quote: quote(l) }));
+    }
+  });
+  return out;
+}
+
+/** past | in_30 | in_90 | later, against a fixed today. The keys keep their historical names: in_30 is the near window (30 days, or
+ * the brief's horizonDays) and in_90 is beyond it up to the far window (90 days, or 3 times horizonDays). */
+function classifyDeadline(isoDate, today, win) {
+  const near = (win && win.near) || 30; const far = (win && win.far) || 90;
+  const d = daysBetween(isoDate, today);
+  return { days: d, bucket: d < 0 ? 'past' : d <= near ? 'in_30' : d <= far ? 'in_90' : 'later' };
+}
+
+// ── extractor 3b: initiatives in the user's own words (brief.vocabulary.initiative) ─────────────────────────────────
+const escRe = (w) => String(w).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** A heading, a frontmatter key or a line start that uses one of the user's initiative words ("epic", "bet") and names the thing. */
+function extractVocabInitiatives(text, words) {
+  const ws = (words || []).map((w) => String(w).trim()).filter(Boolean); if (!ws.length) return [];
+  const alt = ws.map(escRe).join('|'); const info = fmInfo(text); const lines = info.lines; const fenced = fencedLines(lines); const out = [];
+  const headRe = new RegExp('^#{1,6}\\s*\\**\\s*(' + alt + ')\\b\\**\\s*[A-Za-z0-9.-]{0,12}\\s*[—:–-]+\\s*(.+?)\\s*$', 'i');
+  const lineRe = new RegExp('^[\\s>*+-]*\\**(' + alt + ')\\**\\s*[:—–]\\s*(.+?)\\s*$', 'i');
+  lines.forEach((l, i) => {
+    const n = i + 1; if (fenced.has(n)) return;
+    if (info.end && n <= info.end) { const m = /^([A-Za-z0-9_-]+):\s*(.+)$/.exec(l); if (m && ws.some((w) => w.toLowerCase() === m[1].toLowerCase()) && !emptyish(m[2])) out.push({ word: m[1], title: m[2].replace(/^["']|["']$/g, ''), line: n, quote: quote(l), via: 'frontmatter' }); return; }
+    const m = headRe.exec(l) || lineRe.exec(l);
+    if (m) out.push({ word: m[1], title: m[2].replace(/\*+/g, '').replace(/[.\s]+$/, ''), line: n, quote: quote(l), via: /^#/.test(l) ? 'heading' : 'line' });
+  });
+  return out;
+}
+
+/** The user's own goal words ("North Star", "goal") read like Objective/KR lines. Returns [{word,title,line,quote,metric}]. */
+function extractGoalWords(text, words) {
+  const ws = (words || []).map((w) => String(w).trim()).filter((w) => w && !/^(okrs?|krs?|objectives?|key results?)$/i.test(w)); if (!ws.length) return [];
+  const alt = ws.map(escRe).join('|'); const lines = String(text).split('\n'); const fenced = fencedLines(lines); const out = [];
+  const re = new RegExp('^(?:#{1,6}\\s*|[\\s>*+-]*\\**\\s*)(' + alt + ')\\b\\**\\s*[A-Za-z0-9.-]{0,8}\\**\\s*[—:–-]\\s*(.+?)\\s*$', 'i');
+  lines.forEach((l, i) => {
+    if (fenced.has(i + 1)) return; const m = re.exec(l); if (!m) return;
+    const par = [l]; for (let j = i + 1; j < Math.min(lines.length, i + 4); j++) { if (!lines[j].trim() || /^#{1,6}\s/.test(lines[j])) break; par.push(lines[j]); }
+    out.push({ word: m[1], title: quote(m[2].replace(/\*+/g, '').replace(/[.\s]+$/, '')), line: i + 1, quote: quote(l), metric: parseMetric(par.join(' ')) });
+  });
+  return out;
+}
+
+/** Known initiatives (brief.knownInitiatives): which names or aliases a path, a heading or a frontmatter value contains. */
+function matchKnown(known, text, rel) {
+  const out = []; const info = fmInfo(text); const lines = info.lines;
+  const res = known.map((k) => ({ k, re: new RegExp('(?<![\\p{L}\\p{N}])(?:' + [k.name, ...(k.aliases || [])].filter(Boolean).map(escRe).join('|') + ')(?![\\p{L}\\p{N}])', 'iu') }));
+  for (const { k, re } of res) {
+    const base = rel.replace(/[-_]+/g, ' ');
+    let m = re.exec(base);
+    if (m) out.push({ name: k.name, line: 0, quote: 'file name: ' + rel, matched: m[0], basis: 'file-name' });
+    lines.forEach((l, i) => {
+      const n = i + 1; const inFm = info.end && n <= info.end;
+      if (!inFm && !/^#{1,6}\s/.test(l)) return;
+      m = re.exec(l); if (m) out.push({ name: k.name, line: n, quote: quote(l), matched: m[0], basis: inFm ? 'frontmatter' : 'heading' });
+    });
+  }
+  return out;
+}
+
+// ── extractor 4: decisions ──────────────────────────────────────────────────────────────────────────────────────
+const DECISION_HEAD = /^(#{1,6})\s*\**\s*(Decisions?|ADR[-\s]?\d*|Decision log|D\d{1,3})\b\**\s*[—:–.-]*\s*(.*)$/i;
+/** Decisions in one document: the document itself (type ADR/Decision, an adr/decisions path or name) and its Decision headings. */
+function extractDecisions(text, rel) {
+  const info = fmInfo(text); const lines = info.lines; const fenced = fencedLines(lines); const out = [];
+  const ty = info.fm && info.fm.type;
+  if (ty && /^(ADR|Decision)$/i.test(ty)) out.push({ level: 'doc', basis: 'type', line: info.keyLine.type, quote: quote(lines[info.keyLine.type - 1]), confidence: 'high' });
+  else if (/(^|\/)(adr|adrs|decisions?)(\/|\.md$)/i.test(rel) || /^(adr|decision)[-_0-9]/i.test(path.posix.basename(rel))) {
+    const h1 = lines.findIndex((l) => /^#\s+/.test(l));
+    out.push({ level: 'doc', basis: 'name', line: h1 >= 0 ? h1 + 1 : 1, quote: quote(lines[h1 >= 0 ? h1 : 0] || ''), confidence: 'medium' });
+  }
+  lines.forEach((l, i) => {
+    if (fenced.has(i + 1)) return;
+    const m = DECISION_HEAD.exec(l); if (!m) return;
+    const singular = !/^Decisions$/i.test(m[2]) && (m[3] || '').trim().length > 3;
+    out.push({ level: 'heading', basis: 'heading', line: i + 1, quote: quote(l), confidence: singular ? 'medium' : 'low', title: (m[3] || m[2]).trim() });
+  });
+  return out;
+}
+
+// ── extractor 5: people, from structured places only ────────────────────────────────────────────────────────────
+const PERSON_KEYS = /^(owner|author|authors|attendees|participants|assignee|reviewer|approver|stakeholders|requester|lead)$/i;
+const NOT_NAMES = new Set(['tbd', 'n/a', 'na', 'none', 'null', 'unknown', 'team', 'me', 'all', 'pm', 'everyone', 'tba', 'agent', 'claude', 'user', 'owner', 'name', 'role', 'you']);
+/** A person's name or handle from a structured value, or null. Never called on free text. */
+function cleanName(v) {
+  let s = String(v).trim().replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/\*+/g, '').replace(/^@/, '').replace(/^human:/i, '').replace(/\s*[(<].*$/, '').trim();
+  if (!s || s.length > 40 || NOT_NAMES.has(s.toLowerCase())) return null;
+  if (!/^[\p{L}][\p{L}\p{M}.'’ -]{1,39}$/u.test(s)) return null;
+  return s;
+}
+function splitTableRow(l) { return l.replace(/^\s*\|/, '').replace(/\|\s*$/, '').split('|').map((c) => c.trim()); }
+function extractPeople(text) {
+  const info = fmInfo(text); const lines = info.lines; const out = [];
+  if (info.fm) {
+    for (const [k, v] of Object.entries(info.fm)) {
+      if (!PERSON_KEYS.test(k)) continue;
+      const items = info.lists[k] ? info.lists[k] : (v ? v.split(/[,;]/).map((x) => ({ value: x.trim(), line: info.keyLine[k] })) : []);
+      for (const it of items) { const name = cleanName(it.value); if (name) out.push({ name, role: k.toLowerCase(), line: it.line, quote: quote(lines[it.line - 1]), via: 'frontmatter', confidence: 'high' }); }
+    }
+  }
+  const fenced = fencedLines(lines);
+  for (let i = 0; i < lines.length - 2; i++) {
+    if (fenced.has(i + 1) || !/^\s*\|/.test(lines[i]) || !/^\s*\|?\s*:?-{2,}/.test(lines[i + 1])) continue;
+    const head = splitTableRow(lines[i]).map((c) => c.toLowerCase().replace(/\*+/g, ''));
+    const roleCol = head.findIndex((c) => /^(role|responsibility)$/.test(c));
+    const nameCol = head.findIndex((c) => /^(name|person|who|owner|stakeholder|member)$/.test(c));
+    if (roleCol < 0 || nameCol < 0) continue;
+    for (let j = i + 2; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
+      const cells = splitTableRow(lines[j]); const name = cleanName(cells[nameCol] || '');
+      if (name) out.push({ name, role: quote(cells[roleCol] || '').replace(/\*+/g, '') || null, line: j + 1, quote: quote(lines[j]), via: 'roles-table', confidence: 'medium' });
+    }
+  }
+  return out;
+}
+
+// ── extractor 6: risks, open questions, blocked ─────────────────────────────────────────────────────────────────
+const RISK_HEAD = /^(#{1,6})\s*(.*?)\b(risks?|open questions?|blocked|blockers?)\b/i;
+/** Lines under a Risk, Open questions or Blocked heading (bullets and table rows), plus lines that start with "Risk:" or "Blocked:". */
+function extractRisks(text) {
+  const info = fmInfo(text); const lines = info.lines; const fenced = fencedLines(lines); const out = [];
+  let sec = null; // { level, kind, heading }
+  const bodyStart = info.end || 0;
+  for (let i = bodyStart; i < lines.length; i++) {
+    const l = lines[i]; const n = i + 1;
+    if (fenced.has(n)) continue;
+    const h = /^(#{1,6})\s+(.*)$/.exec(l);
+    if (h) {
+      const m = RISK_HEAD.exec(l);
+      if (m) sec = { level: h[1].length, kind: /open question/i.test(m[3]) ? 'open-question' : 'risk', heading: quote(l), inTable: false, seenSep: false };
+      else if (sec && h[1].length <= sec.level) sec = null;
+      continue;
+    }
+    if (sec) {
+      let item = null;
+      const b = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?(.+)$/.exec(l);
+      if (b) item = b[1];
+      else if (/^\s*\|/.test(l)) {
+        if (/^\s*\|?\s*:?-{2,}/.test(l)) { sec.seenSep = true; continue; }
+        if (sec.seenSep) item = splitTableRow(l).filter(Boolean).join(' | ');
+      }
+      if (item && item.replace(/[\s*_`|]/g, '').length > 5) { out.push({ kind: sec.kind, line: n, quote: quote(l), heading: sec.heading, basis: 'heading', confidence: 'medium' }); continue; }
+    }
+    const inl = /^[\s>*+-]*\**(Risk|Open question|Blocked(?: by| on)?)\**\s*[:—–]\s*\S/i.exec(l);
+    if (inl) out.push({ kind: /^open/i.test(inl[1]) ? 'open-question' : 'risk', line: n, quote: quote(l), heading: null, basis: 'line-prefix', confidence: 'low', blocked: /^blocked/i.test(inl[1]) });
+  }
+  return out;
+}
+
+// ── references and titles used by cross-document checks ─────────────────────────────────────────────────────────
+function docTitle(text) {
+  const info = fmInfo(text);
+  if (info.fm && !emptyish(info.fm.title)) return { title: info.fm.title, line: info.keyLine.title };
+  const i = info.lines.findIndex((l, k) => k >= (info.end || 0) && /^#\s+\S/.test(l));
+  return i >= 0 ? { title: info.lines[i].replace(/^#\s+/, '').trim(), line: i + 1 } : null;
+}
+
+/** Paths an initiative record points at, by a frontmatter value or a markdown link. Resolved against `fileSet`. */
+function recordRefs(text, rel, fileSet) {
+  const found = new Set(); const info = fmInfo(text);
+  const resolve = (v) => {
+    const c = String(v).trim().replace(/^["'`]|["'`]$/g, '').replace(/#.*$/, ''); if (!c || /^[a-z][a-z0-9+.-]*:/i.test(c)) return null;
+    const dir = path.posix.dirname(rel); const kit = rel.startsWith('pmos/') ? 'pmos/' : '';
+    for (const x of [c.replace(/^\//, ''), path.posix.join(dir, c), kit + c.replace(/^\//, '')]) { const nx = path.posix.normalize(x); if (fileSet.has(nx)) return nx; }
+    return null;
+  };
+  if (info.fm) for (const v of Object.values(info.fm)) { const r = resolve(v); if (r && r !== rel) found.add(r); }
+  for (const l of migrate.extractLinks(text)) { if (l.kind !== 'md') continue; let p = l.raw.split('#')[0]; try { p = decodeURI(p); } catch { /* keep */ } const r = resolve(p); if (r && r !== rel) found.add(r); }
+  return [...found].sort();
+}
+
+// ── candidate construction ──────────────────────────────────────────────────────────────────────────────────────
+function mk(c) {
+  const evidence = (c.evidence || []).map((e) => ({ file: e.file, line: e.line, quote: quote(e.quote || '') }));
+  const target = (c.proposed && (c.proposed.where || c.proposed.becomes)) || '';
+  const id = 'p_' + sha1([c.kind, target, c.key || '', JSON.stringify(evidence.map((e) => [e.file, e.line, e.quote]))].join('|')).slice(0, 12);
+  const g = []; for (const e of evidence) for (const f of guard.scan(e.quote)) g.push(f.k);
+  return {
+    id, kind: c.kind, title: quote(c.title).slice(0, 120), proposed: c.proposed, evidence, confidence: c.confidence, source: c.source,
+    label: c.label, supply: c.supply, needs_pm: !!c.needs_pm, detail: c.detail || {},
+    untrusted: true, guard: [...new Set(g)],
+  };
+}
+const ev1 = (file, h) => ({ file, line: h.line, quote: h.quote });
+
+// ── git facts: last commit date per file (read-only) ────────────────────────────────────────────────────────────
+function gitDates(root) {
+  const dates = new Map();
+  if (!fs.existsSync(path.join(root, '.git'))) return { dates, available: false };
+  try {
+    const out = cp.execFileSync('git', ['-C', root, '--no-optional-locks', 'log', '--no-renames', '--format=%x01%cs', '--name-only'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    let date = null;
+    for (const line of out.split('\n')) { if (line.startsWith('\x01')) { date = line.slice(1); continue; } if (line && !dates.has(line)) dates.set(line, date); }
+    return { dates, available: true };
+  } catch { return { dates, available: false }; }
+}
+
+const CLOSED = /^(closed|done|shipped|accepted|archived|cancelled|canceled|killed|complete|completed|abandoned)\b/i;
+const isOpenStatus = (s) => !CLOSED.test(String(s || '').trim());
+
+// ── the onboarding brief as hard limits ─────────────────────────────────────────────────────────────────────────────
+const LOCAL_KINDS = briefLib.LOCAL_KINDS || ['folder', 'repo'];
+/** Turn a brief's sources, exclude and doNotRead into a skip function the walker calls BEFORE it opens anything.
+ * A file or folder that matches doNotRead, or an exclude of every source that covers it, or that no local source covers, is never
+ * opened (not read, not hashed). Sources of other kinds (jira, confluence, drive ...) are not scannable here and are listed. */
+function briefRules(brief, root) {
+  const doNot = (brief && brief.doNotRead) || [];
+  const all = ((brief && brief.sources) || []);
+  const local = [];
+  const unscannable = [];
+  for (const s of all) {
+    if (LOCAL_KINDS.includes(s.kind || 'folder')) {
+      let ref = String(s.ref || '').trim();
+      if (path.isAbsolute(ref)) { const r = posix(path.relative(root, ref)); ref = r.startsWith('..') ? null : r; }
+      ref = ref === null ? null : ref.replace(/^\.?\//, '').replace(/\/+$/, '');
+      if (ref === null) { unscannable.push({ kind: s.kind, ref: s.ref, why: 'a local path outside the scanned folder' }); continue; }
+      local.push({ ref: ref === '.' ? '' : ref, include: s.include || [], exclude: s.exclude || [], sensitivity: s.sensitivity || null });
+    } else unscannable.push({ kind: s.kind, ref: s.ref, why: 'not a local folder: its content arrives through an agent session with the user\'s own connection, not through this scan' });
+  }
+  const under = (rel, ref) => !ref || rel === ref || rel.startsWith(ref + '/');
+  const above = (rel, ref) => !ref || ref.startsWith(rel + '/');
+  const incl = (rel, s) => !s.include.length || briefLib.matchesAny(s.include, rel) || (s.ref && briefLib.matchesAny(s.include, rel.slice(s.ref.length + 1)));
+  const sourceFor = (rel) => local.find((s) => under(rel, s.ref) && incl(rel, s) && !briefLib.matchesAny(s.exclude, rel)) || null;
+  const skip = (rel, isDir) => {
+    const g = doNot.find((x) => briefLib.matchGlob(x, rel)); if (g) return 'doNotRead: ' + g;
+    if (!local.length) return null;
+    if (isDir) {
+      const cover = local.filter((s) => under(rel, s.ref) || above(rel, s.ref)); if (!cover.length) return 'outside every source in the brief';
+      if (cover.every((s) => under(rel, s.ref) && briefLib.matchesAny(s.exclude, rel))) return 'excluded by the brief';
+      return null;
+    }
+    if (sourceFor(rel)) return null;
+    const cover = local.filter((s) => under(rel, s.ref));
+    if (!cover.length) return 'outside every source in the brief';
+    if (cover.some((s) => briefLib.matchesAny(s.exclude, rel))) { const x = cover.flatMap((s) => s.exclude).find((e) => briefLib.matchGlob(e, rel)); return 'excluded by the brief: ' + x; }
+    return 'not matched by any include in the brief';
+  };
+  return { skip, sourceFor, unscannable, local };
+}
+
+// ── the scan ────────────────────────────────────────────────────────────────────────────────────────────────────
+function scan(rootArg, opts = {}) {
+  const root = path.resolve(rootArg);
+  const today = opts.today || new Date().toISOString().slice(0, 10);
+  const maxText = opts.maxTextBytes || DEFAULT_MAX_TEXT;
+  const caps = Object.assign({}, DEFAULT_CAPS, opts.caps || {});
+  const brief = opts.brief || null;
+  const rules = briefRules(brief, root);
+  const read = opts.reader || ((f) => fs.readFileSync(f, 'utf8'));
+  const vocab = (brief && brief.vocabulary) || {};
+  const fyStart = monthNumber(vocab.fiscalYearStartMonth) || monthNumber(vocab.quarterStart);
+  const ctx = brief ? { fyStart, quarterNames: vocab.quarterNames, todayIso: today } : null;
+  const near = brief && brief.horizonDays > 0 ? Math.round(brief.horizonDays) : 30; const win = { near, far: brief && brief.horizonDays > 0 ? near * 3 : 90 };
+  const m = migrate.plan(root, { domain: opts.domain, strategy: 'in-place', skip: brief ? rules.skip : null });
+  const entries = m.entries;
+  const byFrom = new Map(entries.map((e) => [e.from, e]));
+  const fileSet = new Set(entries.map((e) => e.from));
+  const git = gitDates(root);
+  let layout = null; try { const p = require('../signals/layout-paths.js').pathsFor(root); layout = { kit: p.kit, recordsDir: path.relative(root, p.recordsDir) || '.' }; } catch { layout = { kit: false, recordsDir: 'planning/records' }; }
+  const recordsDir = layout.recordsDir;
+
+  // the prose documents: markdown, not kit, readable, within the size limit
+  const docs = []; const unread = [];
+  for (const e of entries) {
+    if (e.class === 'kit' || !mdFile(e.from) || e.action === 'upgrade') continue;
+    if (e.size > maxText) { unread.push({ file: e.from, reason: `over the text size limit (${e.size} > ${maxText} bytes)` }); continue; }
+    let text; try { text = read(path.join(root, e.from)); } catch { continue; }
+    if (text.includes('\0')) { unread.push({ file: e.from, reason: 'not readable as text' }); continue; }
+    docs.push({ rel: e.from, text, entry: e });
+  }
+  const nonReserved = docs.filter((d) => !isReserved(d.rel));
+  // generated output (the kit's reports and live notes) restates other records; reading claims out of it would count them twice
+  const skipDoc = (d) => d.entry.class === 'kit' || /(^|\/)state\/(reports|live-notes)\//.test(d.rel);
+  const cands = [];
+  const totals = { files: entries.length, documents: 0, documents_with_frontmatter: 0, attachments: 0 };
+
+  // — initiative records, missing anchors —
+  const records = [];
+  for (const d of docs) {
+    const archived = isArchivedRecordPath(d.rel);
+    if (!isInitiativeRecordPath(d.rel) && !archived) continue;
+    const r = extractInitiativeRecord(d.text, d.rel);
+    if (!r) continue;
+    records.push(Object.assign(r, { rel: d.rel, archived, open: !archived && isOpenStatus(r.status) }));
+  }
+  const live = records.filter((r) => !r.archived);
+  const idSet = new Set(records.map((r) => r.id));
+  const known = ((brief && brief.knownInitiatives) || []).filter((k) => k && k.name);
+  const knownOf = (...strs) => { for (const k of known) { const re = new RegExp('(?<![\\p{L}\\p{N}])(?:' + [k.name, ...(k.aliases || [])].filter(Boolean).map(escRe).join('|') + ')(?![\\p{L}\\p{N}])', 'iu'); if (strs.some((x) => x && re.test(String(x).replace(/[-_]+/g, ' ')))) return k.name; } return null; };
+  const prior = (title) => { try { const I = require('../intake.js'); const a = I.priorRejections(root, title); const b = I.priorRejections(path.join(root, 'pmos'), title); return [...a, ...b]; } catch { return []; } };
+  for (const r of records) {
+    const lane = r.lane;
+    cands.push(mk({
+      kind: 'INITIATIVE', key: r.id, title: `${r.title}${r.archived ? ' (archived)' : ''}`, evidence: r.evidence.map((e) => ev1(r.rel, e)),
+      confidence: r.archived ? 'medium' : 'high', source: 'mechanical', label: 'cited', supply: 'mechanical-transform', needs_pm: !lane || r.archived,
+      proposed: { becomes: 'initiative', where: r.rel + ' (in place)', summary: `Register ${r.id} as an initiative${lane ? ' in lane ' + lane : ' (lane not stated; the PM names it)'}; its record stays where it is, frontmatter is added only.`, fields: { id: r.id, lane, parent_kr: r.parent_kr, status: r.status || null } },
+      detail: { id: r.id, record: r.rel, lane, lane_raw: r.lane_raw, parent_kr: r.parent_kr, anchored: r.anchored, status: r.status || null, owner: r.owner, jira_epic: r.jira_epic, archived: r.archived, open: r.open, known_name: knownOf(r.id, r.title) },
+    }));
+    if (!r.anchored && !r.archived) {
+      const line = r.id_line;
+      cands.push(mk({
+        kind: 'MISSING_ANCHOR', key: r.id, title: `${r.id} has no parent_kr`, evidence: [{ file: r.rel, line: r.anchor_line || line, quote: r.anchor_line ? r.evidence.find((e) => e.line === r.anchor_line).quote : (fmInfo(d0(docs, r.rel)).lines[line - 1] || '') }],
+        confidence: 'high', source: 'mechanical', label: 'fact', supply: 'pm-only', needs_pm: true,
+        proposed: { becomes: 'anchor', where: r.rel + ' (parent_kr)', summary: `Name a KR or a health budget (health:<id>) for ${r.id}. PMOS rejects unanchored work; the PM chooses, nothing is guessed.` },
+        detail: { id: r.id, status: r.status || null, open: r.open },
+      }));
+    }
+  }
+  totals.initiatives = live.length;
+  totals.initiatives_anchored = live.filter((r) => r.anchored).length;
+  totals.initiatives_archived = records.length - live.length;
+  totals.missing_anchor = live.filter((r) => !r.anchored).length;
+
+  // — initiative clusters with no record: declared initiative_id, Jira epics, document folders, briefs —
+  const clusters = new Map(); // key -> {title, basis, evidence[], confidence}
+  const addCluster = (key, c, e) => { if (!clusters.has(key)) clusters.set(key, Object.assign({ evidence: [] }, c)); const k = clusters.get(key); if (k.evidence.length < 5) k.evidence.push(e); };
+  const epicOfRecord = new Set(records.map((r) => r.jira_epic).filter(Boolean));
+  for (const d of nonReserved) {
+    if (records.some((r) => r.rel === d.rel)) continue;
+    const di = extractDeclaredInitiativeId(d.text);
+    if (di && !idSet.has(di.id)) addCluster('id:' + di.id, { title: di.id, basis: 'declared initiative_id that matches no record', confidence: 'medium', via: 'initiative_id' }, { file: d.rel, line: di.line, quote: di.quote });
+    if (/(^|\/)jira\//.test(d.rel)) for (const ep of extractJiraEpics(d.text)) {
+      if (epicOfRecord.has(ep.key)) continue;
+      addCluster('epic:' + ep.key, { title: `Jira epic ${ep.key}`, basis: 'a Jira epic key in a jira/ file', confidence: ep.via === 'frontmatter' ? 'medium' : 'low', via: 'jira' }, { file: d.rel, line: ep.line, quote: ep.quote });
+    }
+  }
+  if ((vocab.initiative || []).length) for (const d of nonReserved) {
+    if (d.entry.class === 'kit' || records.some((r) => r.rel === d.rel)) continue;
+    for (const h of extractVocabInitiatives(d.text, vocab.initiative)) addCluster('vocab:' + h.title.toLowerCase(), { title: h.title, basis: `a ${h.via} that uses your word "${h.word}"`, confidence: 'medium', via: 'vocabulary:' + h.word }, { file: d.rel, line: h.line, quote: h.quote });
+  }
+  // folders: three or more prose documents under one folder, not covered by a record or a known system folder
+  const SYSTEM_DIR = /^(pmos|briefs|reports|prototype|tools|node_modules|state|planning|okf|me|inbox)(\/|$)/i;
+  const byDir = new Map();
+  for (const d of nonReserved) { if (d.entry.class === 'kit') continue; const dir = path.posix.dirname(d.rel); if (dir === '.' || SYSTEM_DIR.test(dir) || /\/(archive|drafts|sources)(\/|$)/.test(dir)) continue; if (!byDir.has(dir)) byDir.set(dir, []); byDir.get(dir).push(d); }
+  const claimedByRecord = new Set(); for (const r of records) for (const p of recordRefs(d0(docs, r.rel), r.rel, fileSet)) claimedByRecord.add(path.posix.dirname(p));
+  for (const [dir, list] of [...byDir.entries()].sort()) {
+    if (list.length < 3 || claimedByRecord.has(dir)) continue;
+    const first = list[0]; const h = docTitle(first.text);
+    addCluster('dir:' + dir, { title: path.posix.basename(dir), basis: `${list.length} documents share the folder ${dir}/ and no initiative record names it`, confidence: 'low', via: 'folder' }, { file: first.rel, line: h ? h.line || 1 : 1, quote: h ? h.title : first.rel });
+  }
+  // briefs: a document named *brief* that is not a dated daily brief
+  for (const d of nonReserved) {
+    const b = stem(d.rel);
+    if (!/brief/i.test(b) || /^\d{4}-\d{2}-\d{2}$/.test(b) || /^brief-config$/i.test(b) || records.some((r) => r.rel === d.rel) || d.entry.class === 'kit' || /(^|\/)(briefs|pmos\/planning\/briefs)\/(drafts|sources)\//.test(d.rel)) continue;
+    const h = docTitle(d.text);
+    addCluster('brief:' + d.rel, { title: h ? h.title : b, basis: 'a brief that no initiative record names', confidence: 'low', via: 'brief' }, { file: d.rel, line: h && h.line ? h.line : 1, quote: h ? h.title : b });
+  }
+  const clusterCands = [];
+  for (const [key, c] of clusters) {
+    const I = (() => { try { return require('../intake.js').parseIntakeLine(c.title); } catch { return { lane_guess: null, confidence: 0.2 }; } })();
+    const pr = prior(c.title);
+    clusterCands.push(mk({
+      kind: 'INITIATIVE', key, title: c.title, evidence: c.evidence, confidence: c.confidence, source: 'heuristic', label: 'assumption', supply: 'agent-drafted', needs_pm: true,
+      proposed: { becomes: 'initiative', where: 'new initiative record (in place: the documents stay)', summary: `Possible initiative "${c.title}": ${c.basis}. An agent grouping later decides whether it is one; the PM decides now.`, fields: { id: null, lane: I.lane_guess, parent_kr: null } },
+      detail: { basis: c.basis, via: c.via, lane_guess: I.lane_guess, lane_confidence: I.confidence, prior_rejections: pr, record: null },
+    }));
+  }
+  cands.push(...clusterCands);
+  // known initiatives from the brief: matched against file names, headings and frontmatter first
+  const knownHits = new Map(known.map((k) => [k.name, []]));
+  if (known.length) for (const d of nonReserved) { if (d.entry.class === 'kit') continue; for (const h of matchKnown(known, d.text, d.rel)) { const a = knownHits.get(h.name); if (a.length < 5) a.push({ file: d.rel, line: h.line, quote: h.quote, basis: h.basis, matched: h.matched }); } }
+  for (const k of known) {
+    const hits = knownHits.get(k.name); const rec = live.find((r) => knownOf(r.id, r.title) === k.name);
+    const strong = hits.some((h) => h.basis === 'frontmatter') || !!rec;
+    cands.push(mk({ kind: 'INITIATIVE', key: 'known:' + k.name, title: k.name, evidence: hits.length ? hits : [{ file: '(brief)', line: 0, quote: 'named in the onboarding brief: ' + k.name }],
+      confidence: strong ? 'high' : hits.length ? 'medium' : 'low', source: 'mechanical', label: hits.length ? 'cited' : 'reported', supply: 'mechanical-transform', needs_pm: !rec,
+      proposed: { becomes: 'initiative', where: rec ? rec.rel + ' (in place)' : 'new initiative record (in place: the documents stay)', summary: hits.length ? `You named "${k.name}"; ${hits.length} place(s) in the folder use that name or an alias. The documents that name it would be linked to it.` : `You named "${k.name}" but no file name, heading or frontmatter value uses it or an alias.`, fields: { id: rec ? rec.id : null, lane: rec ? rec.lane : null, parent_kr: rec ? rec.parent_kr : null } },
+      detail: { known: true, name: k.name, aliases: k.aliases || [], matched_places: hits.length, record: rec ? rec.rel : null, matched_text: [...new Set(hits.map((h) => h.matched).filter(Boolean))] } }));
+  }
+  totals.known_initiatives = known.length;
+  totals.initiative_clusters = clusterCands.length;
+
+  // — objectives and key results —
+  const goalWords = vocab.goal || [];
+  const okrLike = (d) => /okr|objective|key[-_ ]result/i.test(d.rel) || (goalWords.length && extractGoalWords(d.text, goalWords).length > 0) || (fmInfo(d.text).fm || {}).type === 'OKR' || /^#{1,6}\s*\**\s*O-?(?:[A-Z]|\d{1,2})\b\s*[—:–.-]/m.test(d.text) || /^#{1,6}\s*\**\s*Objective\b/im.test(d.text);
+  const seenObj = new Set(); const seenKr = new Set(); let krTotal = 0; let objTotal = 0;
+  for (const d of [...nonReserved].sort((a, b) => Number(okrLike(b)) - Number(okrLike(a)) || (a.rel < b.rel ? -1 : 1))) {
+    if (skipDoc(d) || /\/(templates?)\//.test(d.rel)) continue;
+    const like = okrLike(d); const { objectives, krs } = extractOkr(d.text);
+    if (goalWords.length) for (const g of extractGoalWords(d.text, goalWords)) {
+      const mt = g.metric; const has = mt.baseline !== null || mt.target !== null;
+      if (has) krs.push({ id: g.word.replace(/\s+/g, '') + ':' + g.title.slice(0, 24), title: g.title, line: g.line, quote: g.quote, metric: mt, viaWord: g.word });
+      else objectives.push({ id: g.word.replace(/\s+/g, '') + ':' + g.title.slice(0, 24), title: g.title, line: g.line, quote: g.quote, viaWord: g.word });
+    }
+    if (!like && !krs.length) continue;
+    if (like) for (const o of objectives) {
+      if (seenObj.has(o.id)) continue; seenObj.add(o.id); objTotal++;
+      cands.push(mk({ kind: 'OBJECTIVE', key: o.id, title: `${o.id}: ${o.title}`, evidence: [ev1(d.rel, o)], confidence: 'high', source: 'mechanical', label: 'cited', supply: 'mechanical-transform', needs_pm: false,
+        proposed: { becomes: 'objective', where: d.rel + ' (in place; it is the OKR document)', summary: `Objective ${o.id} from ${d.rel}.` }, detail: { id: o.id } }));
+    }
+    for (const k of krs) {
+      if (seenKr.has(k.id)) continue;
+      if (!like && !k.viaWord && !/^KR-?[A-Za-z]?-?\d/i.test(k.id)) continue;
+      seenKr.add(k.id); krTotal++;
+      const mt = k.metric; const both = mt.baseline !== null && mt.target !== null;
+      cands.push(mk({ kind: 'KR', key: k.id, title: `${k.id}: ${k.title}`, evidence: [ev1(d.rel, k)], confidence: !like ? 'low' : both ? 'high' : (mt.baseline !== null || mt.target !== null) ? 'medium' : 'low',
+        source: 'mechanical', label: 'cited', supply: both ? 'mechanical-transform' : 'agent-drafted', needs_pm: !both,
+        proposed: { becomes: 'kr-metrics record', where: recordsDir + '/kr-metrics.jsonl', summary: both ? `KR ${k.id}: baseline ${mt.baseline}${mt.unit || ''} to target ${mt.target}${mt.unit || ''}${mt.by ? ' by ' + mt.by : ''}.` : `KR ${k.id}: the metric is not fully written (${mt.baseline === null ? 'no baseline' : 'baseline ' + mt.baseline}, ${mt.target === null ? 'no target' : 'target ' + mt.target}); the PM or an agent drafts the rest.`, fields: { metric: k.title, baseline: mt.baseline, target: mt.target, by: mt.by_iso } },
+        detail: Object.assign({ id: k.id, in_okr_doc: like }, mt) }));
+    }
+  }
+  totals.objectives = objTotal; totals.krs = krTotal;
+
+  // — deadlines —
+  const dl = []; const ownerByDoc = new Map();
+  const recByRel = new Map(records.map((r) => [r.rel, r]));
+  for (const d of nonReserved) {
+    if (skipDoc(d)) continue;
+    const info = fmInfo(d.text); const docOwner = (info.fm && (!emptyish(info.fm.owner) ? info.fm.owner : !emptyish(info.fm.author) ? info.fm.author : null)) || null;
+    ownerByDoc.set(d.rel, docOwner);
+    const archived = /\/archive\//.test(d.rel);
+    for (const h of extractDeadlines(d.text, d.rel, today, ctx)) {
+      const c = classifyDeadline(h.iso, today, win);
+      const day = h.precision === 'day';
+      let confidence = day && !h.assumed_year ? (h.strength === 'strong' ? 'high' : 'medium') : 'low';
+      if (c.bucket === 'past' && c.days < -30 && confidence !== 'high') confidence = 'low';
+      if (archived) confidence = 'low';
+      const rec = recByRel.get(d.rel);
+      dl.push({ d, h, c, confidence, owner: docOwner, rec, label: h.assumed_year || !day ? 'assumption' : 'cited' });
+    }
+  }
+  const dTotals = { total: dl.length, past: 0, in_30: 0, in_90: 0, later: 0, in_next_90: 0 };
+  for (const x of dl) { dTotals[x.c.bucket]++; if (x.c.bucket === 'in_30' || x.c.bucket === 'in_90') dTotals.in_next_90++; }
+  dTotals.windows = win; totals.deadlines = dTotals;
+  for (const x of dl) {
+    cands.push(mk({ kind: 'DEADLINE', key: x.h.iso, title: `${x.h.iso} (${x.h.trigger}) ${x.d.rel}`, evidence: [ev1(x.d.rel, x.h)], confidence: x.confidence, source: 'mechanical', label: x.label, supply: 'mechanical-transform', needs_pm: x.confidence !== 'high' || !x.owner,
+      proposed: { becomes: 'dated milestone on a plan item', where: (x.rec ? x.rec.rel : x.d.rel) + ' (due date)', summary: `${x.h.precision === 'day' ? 'Due' : x.h.precision === 'month' ? 'By the end of the month' : 'By the end of the quarter'} ${x.h.iso}${x.h.assumed_year ? ' (' + (x.h.fiscal ? 'fiscal quarter by the brief: a convention' : 'year not written: ' + today.slice(0, 4) + ' assumed') + ')' : ''}; ${x.c.bucket === 'past' ? Math.abs(x.c.days) + ' days ago' : 'in ' + x.c.days + ' days'}.` },
+      detail: { iso: x.h.iso, precision: x.h.precision, assumed_year: x.h.assumed_year, fiscal: !!x.h.fiscal, trigger: x.h.trigger, bucket: x.c.bucket, days: x.c.days, owner: x.owner, initiative: x.rec ? x.rec.id : null } }));
+  }
+
+  // — decisions —
+  const decDocs = new Set(); let decTotal = 0;
+  for (const d of nonReserved) {
+    if (skipDoc(d)) continue;
+    const hits = extractDecisions(d.text, d.rel); if (!hits.length) continue;
+    const title = (docTitle(d.text) || { title: stem(d.rel) }).title;
+    // follow-up: another document names this file, or this document itself names an initiative or a ticket
+    const bn = path.posix.basename(d.rel);
+    const followups = nonReserved.filter((o) => o.rel !== d.rel && o.text.includes(bn)).length + (extractDeclaredInitiativeId(d.text) || /\b[A-Z][A-Z0-9]{1,9}-\d+\b/.test(d.text) ? 1 : 0);
+    for (const h of hits) {
+      decTotal++; decDocs.add(d.rel);
+      cands.push(mk({ kind: 'DECISION', key: h.level + ':' + (h.title || ''), title: h.level === 'doc' ? title : `${title}: ${h.title || 'Decisions'}`, evidence: [ev1(d.rel, h)], confidence: h.confidence, source: h.basis === 'type' ? 'mechanical' : 'heuristic', label: 'cited', supply: 'agent-drafted', needs_pm: true,
+        proposed: { becomes: 'decision record (case, chose, why)', where: recordsDir + '/decisions.jsonl', summary: h.level === 'doc' ? `The document ${d.rel} is a decision (${h.basis === 'type' ? 'its type says so' : 'its name or folder says so'}). An agent drafts case, chose and why from it; the PM confirms.` : `A Decision heading in ${d.rel}: an agent reads what follows it and drafts the record.` },
+        detail: { file: d.rel, level: h.level, basis: h.basis, followups } }));
+    }
+  }
+  totals.decisions = decTotal;
+
+  // — people (structured places only) —
+  const people = new Map();
+  for (const bp of ((brief && brief.people) || [])) { const name = cleanName(bp.name); if (!name) continue; people.set(name.toLowerCase(), { name, roles: new Set(bp.role ? [bp.role] : ['named in the brief']), evidence: [{ file: '(brief)', line: 0, quote: 'brief: ' + name + (bp.role ? ', ' + bp.role : '') }], confidence: 'high' }); }
+  for (const d of nonReserved) {
+    if (skipDoc(d)) continue;
+    for (const p of extractPeople(d.text)) {
+      const k = p.name.toLowerCase(); if (!people.has(k)) people.set(k, { name: p.name, roles: new Set(), evidence: [], confidence: p.confidence });
+      const x = people.get(k); x.roles.add(p.role); if (p.confidence === 'high') x.confidence = 'high';
+      if (x.evidence.length < 3) x.evidence.push({ file: d.rel, line: p.line, quote: p.quote });
+    }
+  }
+  totals.people = people.size;
+  for (const [, x] of [...people.entries()].sort()) {
+    cands.push(mk({ kind: 'PERSON', key: x.name.toLowerCase(), title: x.name, evidence: x.evidence, confidence: x.confidence, source: 'mechanical', label: 'cited', supply: 'mechanical-transform', needs_pm: true,
+      proposed: { becomes: 'person (stakeholder)', where: 'people list (me/people or the domain stakeholders)', summary: `${x.name}, named in a structured field (${[...x.roles].join(', ')}). The PM links the name to an identity; a name is never guessed from prose.` }, detail: { roles: [...x.roles] } }));
+  }
+
+  // — risks and open questions —
+  const rk = []; for (const d of nonReserved) { if (skipDoc(d) || /\/templates?\//.test(d.rel)) continue; for (const h of extractRisks(d.text)) rk.push({ d, h }); }
+  totals.risks = rk.filter((x) => x.h.kind === 'risk').length; totals.open_questions = rk.filter((x) => x.h.kind === 'open-question').length;
+  const perDoc = new Map();
+  for (const x of rk) {
+    const n = (perDoc.get(x.d.rel) || 0) + 1; perDoc.set(x.d.rel, n); if (n > 8) continue;
+    const r = x.h.kind === 'risk';
+    cands.push(mk({ kind: r ? 'RISK' : 'OPEN_QUESTION', key: x.h.line + '', title: x.h.quote.replace(/^[\s>*+\-\d.)|]+/, '').replace(/\*+/g, ''), evidence: [ev1(x.d.rel, x.h)], confidence: x.h.confidence, source: 'heuristic', label: 'reported', supply: 'agent-drafted', needs_pm: true,
+      proposed: { becomes: r ? 'risk note (issue) on the initiative that owns this document' : 'open question on the initiative that owns this document', where: recordsDir + '/../issues.jsonl', summary: `${r ? (x.h.blocked ? 'A blocker' : 'A risk') : 'An open question'} reported in ${x.d.rel}${x.h.heading ? ' under "' + x.h.heading.replace(/^#+\s*/, '') + '"' : ''}.` },
+      detail: { heading: x.h.heading, basis: x.h.basis, blocked: !!x.h.blocked, file: x.d.rel } }));
+  }
+
+  // — stale documents —
+  const refsByRecord = new Map(); // doc path -> open initiative ids that cite it
+  for (const r of live) { if (!r.open) continue; for (const p of recordRefs(d0(docs, r.rel), r.rel, fileSet)) { if (!refsByRecord.has(p)) refsByRecord.set(p, []); refsByRecord.get(p).push(r.id); } }
+  const stale = [];
+  if (git.available) for (const d of nonReserved) {
+    if (skipDoc(d) || /\/archive\//.test(d.rel) || recByRel.has(d.rel)) continue;
+    const last = git.dates.get(d.rel); if (!last) continue;
+    const age = -daysBetween(last, today); if (age > STALE_DAYS) stale.push({ d, last, age });
+  }
+  totals.stale = stale.length; totals.git_history = git.available;
+  for (const x of stale) {
+    cands.push(mk({ kind: 'STALE', key: x.last, title: `${x.d.rel} untouched for ${x.age} days`, evidence: [{ file: x.d.rel, line: 0, quote: `git last commit ${x.last} (${x.age} days before ${today})` }], confidence: 'high', source: 'mechanical', label: 'fact', supply: 'derived', needs_pm: false,
+      proposed: { becomes: 'stale flag (frontmatter timestamp stays; no change to the file)', where: x.d.rel + ' (flag only)', summary: `Last commit ${x.last}, ${x.age} days ago. The PM keeps, refreshes or retires it.` },
+      detail: { last_commit: x.last, age_days: x.age, cited_by: refsByRecord.get(x.d.rel) || [] } }));
+  }
+
+  // — duplicates: identical content, or the same title in two places —
+  const byHash = new Map();
+  for (const e of entries) { if (e.class === 'kit' || !e.sha256 || e.size < 20 || /(^|\/)\.gitkeep$/.test(e.from) || isReserved(e.from)) continue; if (!byHash.has(e.sha256)) byHash.set(e.sha256, []); byHash.get(e.sha256).push(e.from); }
+  const dupGroups = [];
+  for (const [h, files] of [...byHash.entries()].sort()) if (files.length > 1) dupGroups.push({ basis: 'identical content (sha256 ' + h.slice(0, 12) + ')', files: files.sort(), confidence: 'high' });
+  const inHash = new Set(dupGroups.flatMap((g) => g.files));
+  const GENERIC = new Set(['readme', 'index', 'overview', 'changelog', 'notes', 'untitled', 'template', 'summary', 'introduction']);
+  const byTitle = new Map();
+  for (const d of nonReserved) { if (d.entry.class === 'kit' || inHash.has(d.rel)) continue; const t = docTitle(d.text); if (!t) continue; const k = t.title.toLowerCase().replace(/\s+/g, ' ').trim(); if (k.length < 8 || GENERIC.has(k)) continue; if (!byTitle.has(k)) byTitle.set(k, []); byTitle.get(k).push({ rel: d.rel, line: t.line || 1, title: t.title }); }
+  for (const [k, list] of [...byTitle.entries()].sort()) if (list.length > 1) dupGroups.push({ basis: 'the same title in two places', files: list.map((x) => x.rel).sort(), confidence: 'medium', titled: list });
+  totals.duplicates = dupGroups.length;
+  for (const g of dupGroups) {
+    const evid = g.files.slice(0, 4).map((f) => { const d = docs.find((x) => x.rel === f); const t = d ? docTitle(d.text) : null; return { file: f, line: t && t.line ? t.line : 1, quote: t ? t.title : f }; });
+    cands.push(mk({ kind: 'DUPLICATE', key: g.files.join(','), title: `${g.files.length} copies: ${g.files[0]}`, evidence: evid, confidence: g.confidence, source: 'mechanical', label: 'fact', supply: 'derived', needs_pm: true,
+      proposed: { becomes: 'duplicate flag (no file is deleted or merged)', where: g.files.join(', '), summary: `${g.basis}: ${g.files.join(', ')}. The PM names the canonical one.` }, detail: { basis: g.basis, files: g.files } }));
+  }
+
+  // — broken links (the classifier already found them) —
+  const brk = (m.already_broken_links || []).filter((b) => { const e = byFrom.get(b.file); return e && e.class !== 'kit'; });
+  totals.broken_links = brk.length;
+  const seenBrk = new Set();
+  for (const b of brk) {
+    const k = b.file + '|' + b.href; if (seenBrk.has(k)) continue; seenBrk.add(k);
+    const d = docs.find((x) => x.rel === b.file); const lines = d ? d.text.split('\n') : []; let li = lines.findIndex((l) => l.includes(b.href)); li = li < 0 ? 0 : li;
+    cands.push(mk({ kind: 'BROKEN_LINK', key: b.href, title: `${b.file} links to ${b.href}`, evidence: [{ file: b.file, line: li + 1, quote: lines[li] || b.href }], confidence: 'high', source: 'mechanical', label: 'fact', supply: 'derived', needs_pm: false,
+      proposed: { becomes: 'link repair list', where: b.file + ' (no edit in this slice)', summary: `The ${b.kind} link ${b.href} points at no file in this folder.` }, detail: { href: b.href, link_kind: b.kind } }));
+  }
+
+  // — documents and the frontmatter each would gain —
+  let docsCount = 0; let docsWithFm = 0;
+  for (const d of nonReserved) {
+    const e = d.entry; if (e.class === 'kit') continue;
+    docsCount++;
+    const add = e.frontmatter_add || {}; const gains = Object.keys(add);
+    if (!gains.length) { docsWithFm++; continue; }
+    const t = docTitle(d.text);
+    cands.push(mk({ kind: 'DOCUMENT', key: d.rel, title: (t && t.title) || stem(d.rel), evidence: [{ file: d.rel, line: 1, quote: (t && t.title) || stem(d.rel) }], confidence: (e.notes || []).length ? 'medium' : 'high', source: 'mechanical', label: 'fact', supply: 'mechanical-transform', needs_pm: false,
+      proposed: { becomes: 'frontmatter added (the body is never edited)', where: d.rel + ' (in place)', summary: `Gains ${gains.join(', ')}.`, frontmatter_add: add },
+      detail: { category: e.category || null, owner_suggestion: e.suggested_owner || [], notes: e.notes || [] } }));
+  }
+  for (const e of entries) if (e.action === 'sidecar') {
+    totals.attachments++;
+    cands.push(mk({ kind: 'DOCUMENT', key: e.from, title: path.posix.basename(e.from), evidence: [{ file: e.from, line: 0, quote: `${path.extname(e.from)} file, ${e.size} bytes (not read; a sidecar note would carry the frontmatter)` }], confidence: 'high', source: 'mechanical', label: 'fact', supply: 'mechanical-transform', needs_pm: false,
+      proposed: { becomes: 'sidecar note', where: e.sidecar_to, summary: 'The file stays where it is; a sidecar .md beside it carries type, title and timestamp.', frontmatter_add: e.sidecar_frontmatter || {} }, detail: { attachment: true } }));
+  }
+  totals.documents = docsCount; totals.documents_with_frontmatter = docsWithFm;
+
+  // — sort, cap, report what the cap hid —
+  const byKind = {}; for (const k of KINDS) byKind[k] = [];
+  for (const c of cands) byKind[c.kind].push(c);
+  const candidates = []; const capped = {};
+  for (const k of KINDS) {
+    const list = byKind[k].sort((a, b) => CONF_RANK[a.confidence] - CONF_RANK[b.confidence] || (a.evidence[0].file < b.evidence[0].file ? -1 : a.evidence[0].file > b.evidence[0].file ? 1 : a.evidence[0].line - b.evidence[0].line) || (a.id < b.id ? -1 : 1));
+    capped[k] = { total: list.length, shown: Math.min(list.length, caps[k]) };
+    candidates.push(...list.slice(0, caps[k]));
+  }
+  if (brief) for (const c of candidates) {
+    const f = c.evidence[0] && c.evidence[0].file; const src = f && f !== '(brief)' ? rules.sourceFor(f) : null;
+    if (src && src.sensitivity) { c.detail.sensitivity = src.sensitivity; if (src.sensitivity === 'personal') for (const e of c.evidence) e.quote = '[personal source: quote withheld; read ' + e.file + (e.line ? ':' + e.line : '') + ']'; }
+  }
+  const skippedByRule = m.skipped_by_rule || [];
+  const briefApplied = brief ? {
+    skipped_files: skippedByRule.reduce((n, x) => n + x.files, 0),
+    skipped_by_reason: skippedByRule.reduce((a, x) => { const k = x.reason.replace(/:.*$/, '') + (/^doNotRead/.test(x.reason) ? ': ' + x.reason.slice(11) : ''); a[k] = (a[k] || 0) + x.files; return a; }, {}),
+    skipped: skippedByRule.slice(0, 100), unscannable_sources: rules.unscannable,
+    honoured: ['sources[folder,repo].ref/include/exclude/sensitivity', 'doNotRead', 'vocabulary.initiative', 'vocabulary.goal', 'vocabulary.fiscalYearStartMonth (and quarterStart)', 'vocabulary.quarterNames', 'knownInitiatives', 'horizonDays', 'people', 'goals (echoed to first-look)'],
+    goals: brief.goals || [], vocabulary: { initiative: vocab.initiative || [], goal: vocab.goal || [], fiscalYearStartMonth: fyStart, quarterNames: vocab.quarterNames || [] },
+  } : null;
+  const scanId = sha1(root + '|' + (opts.at || new Date().toISOString())).slice(0, 12);
+  return {
+    schema: 'pmos-onboarding-scan/1', scan_id: scanId, root, tenant_name: path.basename(root), domain: m.domain, today, scanned_at: opts.at || new Date().toISOString(),
+    read_only: true, layout,
+    classes: { by_class: m.summary.by_class, by_action: m.summary.by_action, mode: m.mode, strategy: m.strategy, kit_dir: m.summary.kit_dir, files: m.summary.files, skipped: m.skipped.length },
+    totals, capped, candidates, unread, git_history: git.available, windows: win, brief: briefApplied,
+  };
+}
+// the text of a doc by path (records were already read into `docs`)
+function d0(docs, rel) { const d = docs.find((x) => x.rel === rel); return d ? d.text : ''; }
+
+module.exports = {
+  scan, KINDS, DEFAULT_CAPS, quote, fmInfo, classifyDeadline, parseDates, parseMetric, cleanName, isOpenStatus,
+  briefRules, extractVocabInitiatives, extractGoalWords, matchKnown, monthNumber, fiscalQuarterEnd,
+  extractInitiativeRecord, extractDeclaredInitiativeId, extractJiraEpics, extractOkr, extractDeadlines, extractDecisions, extractPeople, extractRisks, docTitle, recordRefs,
+};