create-pmos 0.37.0 → 0.38.1

package/payload/scripts/anchor-resolve.js

@@ -82,6 +82,7 @@ const RE_KR_BULLET = new RegExp('^\\s*[-*]\\s*\\*\\*\\s*' + KR_TOKEN + '\\s*[—
 
 // Anchor forms. Order matters only in that the colon forms are tried before the looser ones.
 const RE_HEALTH = /^health:([a-z0-9_-]+)/i;                       // START-anchored — rule 2
+const RE_DOMAIN = /^domain:([a-z0-9][a-z0-9_-]*)/i;               // D67 — the third anchor class
 const RE_COLON_KR = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*):(kr-?[a-z0-9-]+)$', 'i');
 const RE_COLON_OBJ = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*)$', 'i');
 const RE_ARROW = new RegExp('^(?:okrs-)?' + PERIOD + '\\s*(?:→|->)\\s*' + OBJ_TOKEN + '(?:\\.' + KR_TOKEN + ')?$', 'i');
@@ -176,7 +177,11 @@ function parseOkrIndex(root) {
       // A KR with no open objective stays UNATTACHED (rule 3) — never inherited from a previous one.
       if (k && cur && !cur.krs.some((x) => x.id === krId(k[1]))) {
         cur.krs.push({ id: krId(k[1]), token: k[1], name: (k[2] || '').trim() });
+        continue;
       }
+      // the KR's own measure — its `baseline: … → target: …` sub-bullet (overhaul-r2 B4)
+      const bl = /^\s+[-*]\s*baseline\s*:\s*(.+)$/i.exec(line);
+      if (bl && cur && cur.krs.length && !cur.krs[cur.krs.length - 1].line) cur.krs[cur.krs.length - 1].line = bl[1].trim();
     }
   }
   return { ok: true, objectives, files: files.map((f) => path.relative(root, f)), period: period || null, error: null };
@@ -184,8 +189,36 @@ function parseOkrIndex(root) {
 
 function readBudgets(root) {
   const p = path.join(root, 'planning', 'okrs', 'health-budgets.md');
-  try { return { ok: true, text: fs.readFileSync(p, 'utf8'), path: path.relative(root, p) }; }
-  catch { return { ok: false, text: '', path: path.relative(root, p) }; }
+  let out;
+  try { out = { ok: true, text: fs.readFileSync(p, 'utf8'), path: path.relative(root, p) }; }
+  catch { out = { ok: false, text: '', path: path.relative(root, p) }; }
+  return withDomains(out, path.dirname(p), root);
+}
+
+/**
+ * D67 — the domain registry, `domains.md` beside `health-budgets.md`. Closed and PM-edited, like the
+ * budgets: a domain exists only as a table row `| domain:<id> | standing goal | repositories |`.
+ * It rides on the budgets object every caller already passes, so the gate, the ladder, the sweep and
+ * the workspace all learn the class without a signature change. Absent file = no domains declared
+ * (`ok:false`), which makes any `domain:` anchor `unknown`, never silently resolved.
+ */
+function readDomains(dir, root) {
+  const p = path.join(dir, 'domains.md');
+  const rel = root ? path.relative(root, p) : p;
+  let text;
+  try { text = fs.readFileSync(p, 'utf8'); } catch { return { ok: false, path: rel, rows: [] }; }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const m = /^\|\s*`?domain:([a-z0-9][a-z0-9_-]*)`?\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|/i.exec(line);
+    if (m) rows.push({ id: m[1].toLowerCase(), goal: m[2], repos: m[3] });
+  }
+  return { ok: true, path: rel, rows };
+}
+
+/** Attach the domain registry to a budgets object (callers that build their own budgets use this). */
+function withDomains(budgets, dir, root) {
+  if (!budgets) return budgets;
+  return Object.assign(budgets, { domains: readDomains(dir, root) });
 }
 
 /**
@@ -221,9 +254,24 @@ function unquote(s) {
 
 function resolveAnchor(raw, index, budgets) {
   const original = unquote(String(raw == null ? '' : raw).trim());
-  const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
+  const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null,
+    // separate fields so no client has to parse `reason` (overhaul-r2 B1)
+    objective_name: null, kr_name: null, kr_line: null, domain: null, domain_goal: null };
   if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
 
+  const d = RE_DOMAIN.exec(original);
+  if (d) {
+    const id = d[1].toLowerCase();
+    const out = Object.assign({}, base, { kind: 'domain', domain: id, form: 'domain:<id>' });
+    const reg = budgets && budgets.domains;
+    if (!reg) return Object.assign(out, { status: 'unknown', reason: 'domain registry not supplied to the resolver' });
+    if (!reg.ok) return Object.assign(out, { status: 'unknown', reason: `no domain registry at ${reg.path} — declare the domain there (D67)` });
+    const row = reg.rows.find((r) => r.id === id);
+    return row
+      ? Object.assign(out, { status: 'resolved', domain_goal: row.goal || null, reason: `domain:${id} — ${row.goal || 'no standing goal written'}`.slice(0, 160) })
+      : Object.assign(out, { status: 'unresolvable', reason: `domain:${id} is not a declared domain in ${reg.path} (D67)` });
+  }
+
   // Rule 2: the FORM decides, not a substring. Commentary is stripped only for the OKR branch,
   // because a health anchor's id must sit at the very start of the raw value.
   const h = RE_HEALTH.exec(original);
@@ -269,13 +317,14 @@ function resolveAnchor(raw, index, budgets) {
   }
   if (!out.kr) {
     // Assumption A2: objective-only anchoring is a legitimate resolvable kind, not debt.
-    return Object.assign(out, { status: 'resolved', reason: `objective '${obj.id}' — no KR written (objective-level anchor)` });
+    return Object.assign(out, { status: 'resolved', objective_name: obj.name || null, reason: `objective '${obj.id}' — no KR written (objective-level anchor)` });
   }
   const kr = obj.krs.find((k) => k.id === out.kr);
   if (!kr) {
     return Object.assign(out, { status: 'unresolvable', reason: `objective '${obj.id}' declares no KR '${out.kr}' (has: ${obj.krs.map((k) => k.id).join(', ') || 'none'})` });
   }
-  return Object.assign(out, { status: 'resolved', reason: `${obj.id}/${kr.id} — ${kr.name}`.slice(0, 160) });
+  return Object.assign(out, { status: 'resolved', objective_name: obj.name || null, kr_name: kr.name || null, kr_line: kr.line || null,
+    reason: `${obj.id}/${kr.id} — ${kr.name}`.slice(0, 160) });
 }
 
 /**
@@ -285,6 +334,7 @@ function resolveAnchor(raw, index, budgets) {
 function canonical(resolved, fallbackPeriod) {
   if (!resolved) return null;
   if (resolved.kind === 'health') return resolved.budget ? `health:${resolved.budget}` : null;
+  if (resolved.kind === 'domain') return resolved.domain ? `domain:${resolved.domain}` : null;
   if (resolved.kind !== 'okr' || !resolved.objective) return null;
   const period = resolved.period || fallbackPeriod || null;
   if (!period) return null;
@@ -293,7 +343,7 @@ function canonical(resolved, fallbackPeriod) {
 
 module.exports = {
   unquote,
-  parseOkrIndex, readBudgets, resolveAnchor, canonical,
+  parseOkrIndex, readBudgets, readDomains, withDomains, resolveAnchor, canonical,
   objectiveId, krId, stripCommentary, listOkrFiles,
   ACCEPTED_FORMS,
   // exported for the tests that assert the widening happened together (R-4)

package/payload/scripts/gate-initiative.sh

@@ -86,6 +86,38 @@ anchor="$(frontval parent_kr)"
 # file IS the row, so the gate is where the same rule lands. A KR or health:<id> — never blank.
 [ -n "$anchor" ] || fail "initiative '$id' has no parent_kr in $init_file — anchor it to a KR, or to a declared health budget (parent_kr: health:<id> from $KIT_ROOT/planning/okrs/health-budgets.md, D59). Unanchored work is rejected (D21)."
 
+# ---- D68: the pm-artifacts profile ------------------------------------------
+# A repository whose root holds `.pmos-profile` reading `pm-artifacts` is a PM's documents repo: its
+# lanes are strategy | prd | project-plan | discovery | decision-record | report | chore, and its
+# ladder is brief -> draft -> review -> approved -> handed off. A `light` track (the default for
+# decision-record, report, chore) needs only the anchored record above; a `governed` track (the
+# default for the rest) needs its brief to exist, and a draft it names to exist. Order is the
+# engine's to check (workflow-state.js --gate); this gate checks presence. No rubric, contract or
+# build is asked for in this profile — that is the point of it.
+profile=""
+if [ -f .pmos-profile ]; then profile="$(sed -e 's/#.*$//' -e 's/[[:space:]]//g' .pmos-profile | grep -m1 . || true)"; fi
+if [ "$profile" = "pm-artifacts" ]; then
+  pmlane="$(frontval lane)"; [ -n "$pmlane" ] || pmlane="$lane"
+  case "$pmlane" in
+    strategy|prd|project-plan|discovery|decision-record|report|chore) : ;;
+    *) note "unknown pm-artifacts lane '$pmlane' on '$id' — enforcing a governed prd (the profile's strictest, D68)."; pmlane="prd" ;;
+  esac
+  track="$(frontval track)"
+  case "$track" in
+    light|governed) : ;;
+    *) case "$pmlane" in decision-record|report|chore) track="light" ;; *) track="governed" ;; esac ;;
+  esac
+  if [ "$track" = "governed" ]; then
+    brief="$(frontval brief_path)"; [ -n "$brief" ] || brief="$prd"
+    docp="$(frontval doc_path)"
+    [ -n "$brief" ] || fail "initiative '$id' ($pmlane, governed track) has no brief — set brief_path in $init_file to a short brief (the question, the reader, the decision it informs). A light track needs none: set track: light (D68)."
+    [ -f "$brief" ] || fail "brief_path '$brief' (from $init_file) does not exist in the repo."
+    [ -z "$docp" ] || [ -f "$docp" ] || fail "doc_path '$docp' (from $init_file) does not exist in the repo."
+  fi
+  echo "✅ initiative gate PASSED — '$id' ($pmlane lane, $track track, pm-artifacts profile): $init_file exists and is anchored."
+  exit 0
+fi
+
 # ---- lane-parameterized artifact checks (D56) --------------------------------
 # The kernel invariants already held above (anchored record; the human merge stays the Acceptance
 # Gate); what varies per lane is the spec/eval artifact. In EVERY lane a rubric_path that is set

package/payload/scripts/okf-upgrade.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+'use strict';
+/* okf-upgrade — bring the documents PMOS writes into a TENANT repository to OKF v0.2 (D73).
+ *
+ *   node scripts/okf-upgrade.js <repo>            report what would change (nothing is written)
+ *   node scripts/okf-upgrade.js <repo> --write    apply it
+ *   node scripts/okf-upgrade.js <repo> --check    exit 1 if a document in scope is not conformant
+ *
+ * SCOPE is the documents PMOS or its agents write: requirement notes, report drafts and definitions,
+ * the memory views, the kit's seed documents, and <repo>/reports/. It never touches an initiative,
+ * a ticket, a *.jsonl ledger, needs.json, or any file outside that list, and it refuses PMOS's own
+ * repository (which follows OKF v0.2 itself since D74, with its own gate). Idempotent: a second --write changes nothing.
+ *
+ * HONESTY. `generated.by` is recorded nowhere in an old file, so the tool does not invent it: an
+ * existing `timestamp` is KEPT (OKF tolerates unknown keys) and reported as "author unknown".
+ *
+ * SINGLE-LINE FORM. Five of PMOS's frontmatter readers stop at the first indented line, so a block-style
+ * `generated:` / `sources:` / `verified:` is rewritten to one line (`generated: {by: x, at: "…"}`).
+ */
+const fs = require('fs');
+const path = require('path');
+
+const OKF_VERSION = '0.2';
+const FLOW_KEYS = ['generated', 'sources', 'verified'];
+
+// ── scope ────────────────────────────────────────────────────────────────────────────────────
+function isPmosSelf(root) { return fs.existsSync(path.join(root, 'okf', 'core', 'concepts')); }
+function stateDir(root) {
+  const kit = path.join(root, 'pmos', 'state');
+  if (fs.existsSync(kit)) return kit;
+  const self = path.join(root, 'planning');
+  return fs.existsSync(self) ? self : null;
+}
+function walkMd(dir, out) {
+  let ents = [];
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of ents) {
+    const p = path.join(dir, e.name);
+    if (e.isSymbolicLink()) continue;
+    if (e.isDirectory()) walkMd(p, out);
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(p);
+  }
+}
+function scopeFiles(root) {
+  const s = stateDir(root);
+  const files = [];
+  if (s) {
+    for (const sub of ['requirements', 'reports', 'memory']) walkMd(path.join(s, sub), files);
+    try { for (const n of fs.readdirSync(s)) if (n.endsWith('.md') && !['index.md', 'log.md'].includes(n)) files.push(path.join(s, n)); } catch { /* none */ }
+  }
+  walkMd(path.join(root, 'reports'), files);
+  for (const p of [path.join(root, 'pmos', 'planning', 'evals', 'eval-calibration.md'), path.join(root, 'pmos', 'planning', 'okrs', 'health-budgets.md')]) {
+    if (fs.existsSync(p)) files.push(p);
+  }
+  return [...new Set(files)].filter((f) => !['index.md', 'log.md'].includes(path.basename(f)));
+}
+
+// ── a deliberately small frontmatter reader/writer ───────────────────────────────────────────
+function split(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+  if (!m) return { fm: null, body: text };
+  return { fm: m[1], body: m[2] };
+}
+// Top-level entries as { key, lines[] }: an entry owns its indented continuation lines.
+function entries(fm) {
+  const out = [];
+  for (const line of fm.split(/\r?\n/)) {
+    if (/^\s+\S/.test(line) && out.length) { out[out.length - 1].lines.push(line); continue; }
+    const m = /^([A-Za-z_][\w-]*)\s*:/.exec(line);
+    out.push({ key: m ? m[1] : null, lines: [line] });
+  }
+  return out;
+}
+const q = (s) => (/^[A-Za-z0-9_.\/@+-]+$/.test(s) && !/^(true|false|null|yes|no|\d+)$/i.test(s) ? s : JSON.stringify(s));
+function scalar(v) { return String(v).trim().replace(/^["']|["']$/g, ''); }
+function parseBlock(entry) {
+  const head = entry.lines[0].replace(/^[^:]*:/, '').trim();
+  const rest = entry.lines.slice(1);
+  if (head && !rest.length) return { flow: true };                       // already one line
+  if (head) return null;                                                 // something unexpected
+  const items = []; let cur = null;
+  for (const l of rest) {
+    const li = /^\s+-\s*(.*)$/.exec(l);
+    const kv = /^\s+([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(l);
+    if (li) {
+      const inner = li[1]; const ikv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(inner);
+      cur = ikv ? { [ikv[1]]: scalar(ikv[2]) } : { resource: scalar(inner) };
+      items.push(cur);
+    } else if (kv) {
+      if (cur && items.length) cur[kv[1]] = scalar(kv[2]);
+      else { cur = {}; items.push(cur); cur[kv[1]] = scalar(kv[2]); items.single = true; }
+    }
+  }
+  return { items, single: !!items.single };
+}
+function flowOf(key, parsed) {
+  const obj = (o) => `{${Object.entries(o).map(([k, v]) => `${k}: ${q(String(v))}`).join(', ')}}`;
+  if (key === 'generated') return `generated: ${obj(parsed.items[0] || {})}`;
+  return `${key}: [${parsed.items.map(obj).join(', ')}]`;
+}
+// Parse the items of a one-line flow list `[{k: v, k: "v"}, {…}]` back into objects. Values are bare or JSON-quoted.
+function flowItems(line) {
+  const body = line.replace(/^[^:]*:\s*/, '');
+  const out = [];
+  const objRe = /\{((?:[^{}"]|"(?:[^"\\]|\\.)*")*)\}/g; let m;
+  while ((m = objRe.exec(body))) {
+    const o = {}; const kvRe = /([A-Za-z_][\w-]*)\s*:\s*("(?:[^"\\]|\\.)*"|[^,]*)/g; let kv;
+    while ((kv = kvRe.exec(m[1]))) { let v = kv[2].trim(); if (v.startsWith('"')) { try { v = JSON.parse(v); } catch { /* keep raw */ } } o[kv[1]] = v; }
+    out.push(o);
+  }
+  return out;
+}
+function firstH1(body) { const m = /^#\s+(.+?)\s*$/m.exec(body); return m ? m[1].trim() : null; }
+function titleFromName(file) { return path.basename(file, '.md').replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()); }
+
+// `# Citations` (or ##) list at the end of the body → sources items. Returns null when nothing converts.
+function takeCitations(body) {
+  const m = /(^|\n)#{1,3}\s+Citations\s*\n([\s\S]*?)(?=\n#{1,3}\s|\s*$)/.exec(body);
+  if (!m) return null;
+  const items = []; let unconverted = 0;
+  for (const raw of m[2].split('\n')) {
+    const l = raw.trim(); if (!l) continue;
+    const mm = /^[-*]\s+(?:\[([^\]]*)\]\(([^)]+)\)|(https?:\/\/\S+))(?:\s*[—-]\s*(.*))?$/.exec(l);
+    if (!mm) { unconverted++; continue; }
+    const resource = mm[2] || mm[3]; const title = mm[1] || mm[4] || null;
+    items.push(title ? { resource, title } : { resource });
+  }
+  return { whole: m[0], lead: m[1], items, unconverted };
+}
+
+function upgradeDoc(file, text) {
+  const notes = []; const issues = [];
+  let { fm, body } = split(text);
+  let ents;
+  if (fm === null) {
+    issues.push('no frontmatter');
+    ents = [{ key: 'type', lines: ['type: Reference'] }, { key: 'title', lines: [`title: ${q(firstH1(body) || titleFromName(file))}`] }];
+    notes.push('added type and title (type is a guess: Reference)');
+    body = text;
+  } else {
+    ents = entries(fm);
+    const has = (k) => ents.some((e) => e.key === k);
+    if (!has('type')) { issues.push('no type'); ents.unshift({ key: 'type', lines: ['type: Reference'] }); notes.push('added type: Reference (a guess)'); }
+    if (!has('title')) { issues.push('no title'); ents.splice(1, 0, { key: 'title', lines: [`title: ${q(firstH1(body) || titleFromName(file))}`] }); notes.push('added title from the first heading'); }
+    for (const e of ents) {
+      if (!FLOW_KEYS.includes(e.key) || e.lines.length < 2 && /:\s*\S/.test(e.lines[0])) continue;
+      const parsed = parseBlock(e);
+      if (parsed && parsed.items && parsed.items.length) {
+        issues.push(`block-style ${e.key} (readers stop at the first indented line)`);
+        e.lines = [flowOf(e.key, parsed)]; notes.push(`${e.key} rewritten to one line`);
+      }
+    }
+  }
+  const cit = takeCitations(body);
+  if (cit && cit.items.length) {
+    issues.push('citations in the body (v0.2 keeps them in `sources`)');
+    const src = ents.find((e) => e.key === 'sources');
+    const have = src ? flowItems(src.lines[0]) : [];
+    const merged = [...have];
+    for (const it of cit.items) if (!merged.some((h) => h.resource === it.resource)) merged.push(it);
+    const line = `sources: [${merged.map((o) => `{${Object.entries(o).map(([k, v]) => `${k}: ${q(String(v))}`).join(', ')}}`).join(', ')}]`;
+    if (src) src.lines = [line]; else ents.push({ key: 'sources', lines: [line] });
+    if (!cit.unconverted) body = body.replace(cit.whole, cit.lead ? '\n' : '');
+    else notes.push(`${cit.unconverted} citation line(s) are not links and stay in the body`);
+    notes.push(`${cit.items.length} citation(s) moved to sources`);
+  }
+  const hasTs = ents.some((e) => e.key === 'timestamp'); const hasGen = ents.some((e) => e.key === 'generated');
+  if (hasTs && !hasGen) notes.push('legacy timestamp kept — who generated it is not recorded, so generated.by is not invented');
+  const out = `---\n${ents.map((e) => e.lines.join('\n')).join('\n')}\n---\n${body}`;
+  const final = out.endsWith('\n') ? out : out + '\n';
+  return { text: final, changed: final !== text, issues, notes };
+}
+
+// ── the bundle root ──────────────────────────────────────────────────────────────────────────
+function rootIndex(dir) {
+  const names = []; try { for (const e of fs.readdirSync(dir, { withFileTypes: true })) if (!e.name.startsWith('.') && (e.isDirectory() || e.name.endsWith('.md'))) names.push(e); } catch { /* none */ }
+  const lines = ['---', `okf_version: "${OKF_VERSION}"`, '---', '', '# Knowledge bundle', '', 'Documents PMOS and its agents write in this repository (OKF v0.2, D73).', ''];
+  for (const e of names.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (['index.md', 'log.md'].includes(e.name)) continue;
+    lines.push(e.isDirectory() ? `- [${e.name}/](/${e.name}/)` : `- [${e.name}](/${e.name})`);
+  }
+  return lines.join('\n') + '\n';
+}
+function rootFiles(root) {
+  const dir = stateDir(root); const todo = []; const issues = [];
+  if (!dir) return { todo, issues, dir };
+  const idx = path.join(dir, 'index.md'); const log = path.join(dir, 'log.md');
+  let idxText = null; try { idxText = fs.readFileSync(idx, 'utf8'); } catch { /* absent */ }
+  if (idxText === null) { issues.push('no bundle-root index.md'); todo.push({ file: idx, text: rootIndex(dir), note: 'created index.md with okf_version "0.2"' }); }
+  else if (!new RegExp(`^okf_version:\\s*["']?${OKF_VERSION.replace('.', '\\.')}["']?\\s*$`, 'm').test(split(idxText).fm || '')) {
+    issues.push(`bundle-root index.md does not declare okf_version "${OKF_VERSION}"`);
+    const { fm, body } = split(idxText);
+    todo.push({ file: idx, text: fm === null ? `---\nokf_version: "${OKF_VERSION}"\n---\n${idxText}` : `---\n${fm.replace(/^okf_version:.*$/m, '').replace(/\n+$/, '')}\nokf_version: "${OKF_VERSION}"\n---\n${body}`.replace(/^---\n\n/, '---\n'), note: 'set okf_version "0.2" on index.md' });
+  }
+  if (!fs.existsSync(log)) {
+    issues.push('no log.md');
+    const day = new Date().toISOString().slice(0, 10);
+    todo.push({ file: log, text: `# Log\n\nNewest first, ISO dates.\n\n## ${day}\n\n- Adopted OKF v0.2 (D73).\n`, note: 'created log.md' });
+  }
+  return { todo, issues, dir };
+}
+
+function run(root, { write = false } = {}) {
+  if (isPmosSelf(root)) return { ok: false, error: 'this is PMOS\'s own repository, which has its own Frontmatter Gate (D74) — okf-upgrade is for tenant repositories' };
+  if (!stateDir(root)) return { ok: false, error: 'no pmos/state/ or planning/ directory here — nothing to upgrade' };
+  const files = scopeFiles(root); const results = [];
+  for (const f of files) {
+    const text = fs.readFileSync(f, 'utf8');
+    const r = upgradeDoc(f, text);
+    results.push({ file: path.relative(root, f), ...r });
+    if (write && r.changed) fs.writeFileSync(f, r.text);
+  }
+  const rf = rootFiles(root);
+  for (const t of rf.todo) { results.push({ file: path.relative(root, t.file), changed: true, issues: [], notes: [t.note], rootFile: true }); if (write) fs.writeFileSync(t.file, t.text); }
+  const issues = results.flatMap((r) => r.issues.map((i) => ({ file: r.file, issue: i }))).concat(rf.issues.map((i) => ({ file: path.relative(root, path.join(rf.dir, 'index.md')), issue: i })));
+  return { ok: true, write, scanned: files.length, results, issues, changed: results.filter((r) => r.changed).length };
+}
+
+function main(argv) {
+  const a = argv.slice(2); const flags = a.filter((x) => x.startsWith('--')); const pos = a.filter((x) => !x.startsWith('--'));
+  const root = path.resolve(pos[0] || process.cwd());
+  const write = flags.includes('--write'); const check = flags.includes('--check');
+  const r = run(root, { write: write && !check });
+  if (!r.ok) { process.stderr.write(`okf-upgrade: ${r.error}\n`); return 2; }
+  if (flags.includes('--json')) { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); return check && r.issues.length ? 1 : 0; }
+  for (const x of r.results) if (x.changed || x.issues.length) process.stdout.write(`${x.changed ? (write && !check ? 'upgraded' : 'would change') : 'ok'}  ${x.file}\n${x.notes.map((n) => `    · ${n}`).join('\n')}${x.notes.length ? '\n' : ''}`);
+  process.stdout.write(`\n${r.scanned} document(s) in scope · ${r.issues.length} not conformant · ${check ? 'check only' : write ? `${r.changed} written` : `${r.changed} would change — nothing written; add --write to apply`}\n`);
+  return check && r.issues.length ? 1 : 0;
+}
+
+module.exports = { run, upgradeDoc, scopeFiles, isPmosSelf, OKF_VERSION };
+if (require.main === module) process.exit(main(process.argv));