create-pmos 0.131.0 → 0.133.0

package/workspace/lib/vendor/scripts/migrate-layout.js

@@ -0,0 +1,775 @@
+#!/usr/bin/env node
+'use strict';
+/* migrate-layout.js — READ-ONLY dry-run planner for moving a tenant (product DOCS) repo to the PMOS portfolio layout.
+ *
+ *   node scripts/migrate-layout.js plan   <tenantRoot> [--domain general] [--out <manifest.json>]
+ *   node scripts/migrate-layout.js verify <manifest.json> <tenantRoot>
+ *
+ * THE HARD RULE: this tool never writes into the tenant. It reads files, and it runs `git log` (a read) for revision counts
+ * and dates. `--out` is refused when it resolves inside the tenant. There is no `apply` and no `undo` on purpose: see
+ * scripts/migrate-layout-APPLY-DESIGN.md for the apply step that is recommended and what the PM approves before it runs.
+ *
+ * Target layout (prototype/pmos-console-handoff/STRUCTURE.md): products/<domain>/{inbox, ledgers, reports, knowledge,
+ * decisions, strategy, health, initiatives/<slug>/{initiative.md, docs/}}. Paths in `to` are relative to the repo root after
+ * migration. `keep`, `sidecar` and `upgrade` entries do not move: their `to` is the same tenant-relative path.
+ *
+ * Classes: kit | record | document | attachment | code | other.  Actions: move | keep | sidecar | inbox | upgrade.
+ * Ownership is never guessed from a file name: owner evidence is (a) a path an initiative record names in frontmatter or a
+ * markdown link, or (b) an `initiative_id` the document declares that resolves to a record. Anything else goes to
+ * products/<domain>/inbox/ with needs_pm true; a name match is recorded as `suggested_owner` only and is never acted on.
+ * A document body is never planned for rewrite. The only change to a .md is added frontmatter keys. Links that the moves
+ * break are LISTED with the rewrite that fixes them; applying a rewrite is a separate, PM-approved step.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const cp = require('child_process');
+
+const PMOS_ROOT = path.resolve(__dirname, '..');
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+const ATTACH_EXT = new Set(['.docx', '.doc', '.xlsx', '.xls', '.pptx', '.ppt', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.csv', '.gdoc', '.gsheet', '.gslides']);
+const CODE_EXT = new Set(['.py', '.js', '.mjs', '.cjs', '.ts', '.sh', '.bash', '.zsh', '.rb', '.go']);
+const DOC_EXT = new Set(['.md', '.markdown']);
+const RESERVED = new Set(['index.md', 'log.md']);
+const HASH_LIMIT = 50 * 1024 * 1024;
+// What the vendored kit owns: replaced by `create-pmos` upgrade, never moved by hand. Paths are relative to the kit dir.
+const KIT_RE = /^(AGENTS\.md|AGENTS-HUMAN\.md|KIT-VERSION|README\.md|SECURITY\.md|dashboard\.html|mods\/|skills\/|skills-native\/|scripts\/|templates\/|okf\/core\/|okf\/index\.md|okf\/log\.md|state\/skills\/|\.[^/]+)/;
+
+const posix = (p) => p.split(path.sep).join('/');
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+
+// ── frontmatter (a minimal top-level key: value reader, like scripts/frontmatter_lint.py) ───────────────────────────
+function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  if (!lines.length || lines[0].trim() !== '---') return { fm: null, multiline: [], end: -1 };
+  const fm = {}; const multiline = [];
+  let lastKey = null;
+  for (let i = 1; i < lines.length; i++) {
+    const l = lines[i];
+    if (l.trim() === '---') return { fm, multiline, end: i };
+    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 (!(m[1] in fm)) fm[m[1]] = v;
+      if (/^["'][^"']*$/.test(m[2].trim())) multiline.push(m[1]); // opened a quote and did not close it on this line
+    } else if (/^\s+\S/.test(l) && lastKey) {
+      if (!multiline.includes(lastKey)) multiline.push(lastKey); // an indented continuation: not one-line-per-key
+    }
+  }
+  return { fm: null, multiline: [], end: -1 }; // unterminated
+}
+
+let REGISTRY = null;
+function registry() {
+  if (REGISTRY) return REGISTRY;
+  try {
+    REGISTRY = new Set(fs.readFileSync(path.join(PMOS_ROOT, 'scripts', 'frontmatter_registry.txt'), 'utf8')
+      .split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+  } catch { REGISTRY = new Set(['Concept', 'ADR', 'Template', 'Playbook', 'Reference', 'Initiative', 'PRD', 'Story', 'Rubric', 'OKR', 'Radar', 'Checklist', 'Calibration', 'Research', 'Design', 'Prototype', 'Handover', 'Decision', 'Principle', 'Debt', 'Discovery', 'Guide']); }
+  return REGISTRY;
+}
+
+/** A value the file declares in its first 30 lines: `key: v` or a prose `- key: v` (the kit's `## Frontmatter` / `## Identity`). */
+/** Tags from folder words, only when obvious: the parent folder names of a nested file, minus generic ones. */
+function tagsFor(rel) {
+  const generic = new Set(['docs', 'doc', 'files', 'misc', 'other', 'tmp', 'new', 'old', 'src', 'pmos', 'planning', 'okf', 'state']);
+  const parts = path.posix.dirname(rel).split('/').filter((x) => x && x !== '.').map(slug).filter((x) => x && x.length > 2 && !generic.has(x) && !/^\d+$/.test(x));
+  return parts.length ? '[' + parts.slice(-2).join(', ') + ']' : null;
+}
+
+function declared(text, key) {
+  const re = new RegExp('^[-\\s]*' + key + ':\\s*(.+?)\\s*$', 'i');
+  for (const line of text.split('\n').slice(0, 30)) {
+    const m = re.exec(line);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, '');
+  }
+  return null;
+}
+
+/** Type from the path, after backfill_frontmatter.py's infer_type, applied to the tenant's logical path. */
+function inferType(lp, category) {
+  const b = path.posix.basename(lp).toLowerCase();
+  if (/^planning\/evals\//.test(lp)) return /calibration/.test(b) ? 'Calibration' : /rubric/.test(b) ? 'Rubric' : 'Reference';
+  for (const [pre, ty] of [['planning/prd/', 'PRD'], ['planning/research/', 'Research'], ['planning/design/', 'Design'], ['planning/radar/', 'Radar'], ['planning/okrs/', 'OKR']]) {
+    if (lp.startsWith(pre)) return ty;
+  }
+  if (lp.startsWith('prototype/')) return 'Prototype';
+  if (/^okf\/core\/concepts\//.test(lp)) return 'Concept';
+  if (/^planning\/out-of-scope\//.test(lp)) return 'Decision';
+  if (/^state\/initiatives\//.test(lp) || /^planning\/initiatives\//.test(lp)) return 'Initiative';
+  if (category === 'prd') return 'PRD';
+  if (category === 'knowledge') return 'Concept';
+  if (category === 'report') return 'Reference';
+  return 'Reference';
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+const humanize = (rel) => { const s = path.posix.basename(rel).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim(); return s.charAt(0).toUpperCase() + s.slice(1); };
+
+/** Frontmatter keys to ADD (never change). Returns {add, notes}. Reuses the backfill logic: declared > git date > file mtime. */
+function planFrontmatter({ lp, text, fm, git, rel, mtimeIso, category, isRecord }) {
+  const add = {}; const notes = [];
+  const reg = registry();
+  const have = fm || {};
+  if (!have.type) {
+    let dt = declared(text, 'type');
+    if (dt && !reg.has(dt)) { notes.push(`declared type '${dt}' not in registry; inferred`); dt = null; }
+    add.type = dt || inferType(lp, category);
+  } else if (isRecord && have.type && !reg.has(have.type)) {
+    notes.push(`frontmatter type '${have.type}' is the work lane, not an OKF type (not in registry); decision needed: keep the lane key and add an OKF key, or rename`);
+  } else if (!reg.has(have.type)) {
+    notes.push(`type '${have.type}' not in the registry`);
+  }
+  if (!have.title) {
+    let title = null;
+    for (const line of text.split('\n')) { const m = /^#\s+(.+?)\s*$/.exec(line); if (m) { title = m[1]; break; } }
+    if (!title) title = declared(text, 'title');
+    if (!title) { title = humanize(rel); notes.push('title from file name (no H1)'); }
+    add.title = title;
+  }
+  if (!have.timestamp) {
+    let ts = have.created || have.date || declared(text, 'timestamp') || declared(text, 'date');
+    if (!(ts && ISO.test(ts))) ts = null;
+    if (!ts && git.dates.get(rel)) ts = git.dates.get(rel);
+    if (!ts) { ts = mtimeIso; notes.push('timestamp from file mtime (no declared or git date)'); }
+    add.timestamp = ts;
+  }
+  return { add, notes };
+}
+
+// ── reading the repo ────────────────────────────────────────────────────────────────────────────────────────────
+const BUILD_DIRS = new Set(['dist', 'build', 'out', 'target', 'coverage', '__pycache__', '.next', '.cache', 'vendor']);
+/** All files under root. In connect mode (`skipped` given) hidden entries, build output and over-size files are left out and reported. */
+function walk(root, skipped, maxBytes, skipFn, skippedByRule) {
+  const out = [];
+  (function rec(dir) {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    ents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      const rel = posix(path.relative(root, full));
+      if (SKIP_DIRS.has(e.name) && e.isDirectory()) continue;
+      // an optional hard limit from the caller (an onboarding brief's doNotRead/exclude): the entry is never opened, not even stat'ed for a hash
+      if (skipFn) { const why = skipFn(rel, e.isDirectory()); if (why) { if (skippedByRule) skippedByRule.push({ path: rel + (e.isDirectory() ? '/' : ''), reason: why, files: e.isDirectory() ? countNames(full) : 1 }); continue; } }
+      if (skipped) {
+        if (e.name.startsWith('.')) { skipped.push({ path: rel + (e.isDirectory() ? '/' : ''), reason: 'hidden' }); continue; }
+        if (e.isDirectory() && BUILD_DIRS.has(e.name)) { skipped.push({ path: rel + '/', reason: 'build output or vendored dependencies' }); continue; }
+      }
+      if (e.isDirectory()) rec(full);
+      else {
+        if (skipped && !e.isSymbolicLink()) { let sz = 0; try { sz = fs.statSync(full).size; } catch { /* keep 0 */ } if (sz > maxBytes) { skipped.push({ path: rel, reason: `over the size limit (${sz} bytes > ${maxBytes})` }); continue; } }
+        out.push(rel); // files and symlinks (never followed)
+      }
+    }
+  })(root);
+  return out.sort();
+}
+
+/** Count the file names under a folder without opening any file (a directory listing only). */
+function countNames(dir) { let n = 0; try { for (const e of fs.readdirSync(dir, { withFileTypes: true })) n += e.isDirectory() ? countNames(path.join(dir, e.name)) : 1; } catch { /* unreadable */ } return n; }
+
+/** A folder is a PMOS tenant when it holds a vendored kit or PMOS records; anything else is foreign and is connected. */
+function detectMode(root) {
+  const has = (p) => fs.existsSync(path.join(root, p));
+  return has('pmos/KIT-VERSION') || has('pmos/state') || has('planning/initiatives') || has('planning/runs') || has('state/initiatives') ? 'tenant' : 'connect';
+}
+
+function hashFile(full, st) {
+  if (!st.isFile() || st.size > HASH_LIMIT) return null;
+  return crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex');
+}
+
+/** One `git log` pass: commit count and last commit date per file. Read-only; empty maps when there is no history. */
+function gitFacts(root) {
+  const counts = new Map(); const dates = new Map();
+  if (!fs.existsSync(path.join(root, '.git'))) return { counts, 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) continue;
+      counts.set(line, (counts.get(line) || 0) + 1);
+      if (!dates.has(line)) dates.set(line, date); // newest first
+    }
+    return { counts, dates, available: true };
+  } catch { return { counts, dates, available: false }; }
+}
+
+function detectKitDir(root, files) {
+  if (files.includes('pmos/KIT-VERSION')) return 'pmos';
+  if (files.includes('pmos/AGENTS.md') && files.some((f) => f.startsWith('pmos/skills/'))) return 'pmos';
+  return null;
+}
+
+function domainFor(root, explicit) {
+  if (explicit) return explicit;
+  try {
+    const y = fs.readFileSync(path.join(root, 'portfolio.yaml'), 'utf8');
+    const base = path.basename(root);
+    const m = new RegExp('^\\s+' + base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ':\\s*([A-Za-z0-9_-]+)', 'm').exec(y);
+    if (m) return m[1];
+  } catch { /* no portfolio.yaml */ }
+  return 'general';
+}
+
+// ── links ───────────────────────────────────────────────────────────────────────────────────────────────────────
+function stripCode(text) {
+  // blank out fenced code and inline code so a link shown as an example is not counted (positions are kept)
+  return text.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ' ')).replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+}
+const EXTERNAL = /^([a-z][a-z0-9+.-]*:|#|\/\/)/i;
+function safeDecode(s) { try { return decodeURI(s); } catch { return s; } }
+
+/** Every markdown link, reference definition and wiki link in a document. Positions are not needed: rewrites are by text. */
+function extractLinks(text) {
+  const t = stripCode(text);
+  const links = [];
+  const add = (kind, raw) => { links.push({ kind, raw }); };
+  for (const m of t.matchAll(/\]\(\s*<([^>]+)>\s*(?:"[^"]*")?\s*\)/g)) add('md', m[1]);
+  for (const m of t.matchAll(/\]\(\s*([^)\s<>]+)(?:\s+"[^"]*")?\s*\)/g)) add('md', m[1]);
+  for (const m of t.matchAll(/^\s*\[[^\]\n]+\]:\s*<?(\S+?)>?(?:\s+"[^"]*")?\s*$/gm)) add('md', m[1]);
+  for (const m of t.matchAll(/\[\[([^\]|#\n]+)(?:#[^\]|\n]*)?(?:\|[^\]\n]*)?\]\]/g)) add('wiki', m[1].trim());
+  return links;
+}
+
+function splitHref(raw) {
+  const m = /^([^#?]*)((?:[?#].*)?)$/.exec(raw);
+  return { p: m ? m[1] : raw, tail: m ? m[2] : '' };
+}
+
+// ── the planner ─────────────────────────────────────────────────────────────────────────────────────────────────
+function plan(tenantRoot, opts = {}) {
+  const root = path.resolve(tenantRoot);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`not a directory: ${root}`);
+  const domain = slug(domainFor(root, opts.domain)) || 'general';
+  const mode = opts.mode || detectMode(root);
+  const connect = mode === 'connect';
+  const strategy = opts.strategy || (connect ? 'in-place' : 'restructure');
+  if (!['connect', 'tenant'].includes(mode)) throw new Error(`unknown mode: ${mode}`);
+  if (!['in-place', 'restructure'].includes(strategy)) throw new Error(`unknown strategy: ${strategy}`);
+  const maxBytes = opts.maxBytes || 25 * 1024 * 1024;
+  const skipped = [];
+  const skippedByRule = [];
+  const files = walk(root, connect ? skipped : null, maxBytes, opts.skip || null, skippedByRule);
+  const fileSet = new Set(files);
+  const kitDir = detectKitDir(root, files);
+  const git = gitFacts(root);
+  const stat = new Map(); const text = new Map();
+  for (const f of files) {
+    const full = path.join(root, f);
+    const st = fs.lstatSync(full);
+    stat.set(f, st);
+    if (DOC_EXT.has(path.extname(f).toLowerCase()) && st.isFile()) text.set(f, fs.readFileSync(full, 'utf8'));
+  }
+  const kitRel = (f) => (kitDir && f.startsWith(kitDir + '/') ? f.slice(kitDir.length + 1) : null);
+  const isKit = (f) => { const k = kitRel(f); return k !== null && KIT_RE.test(k); };
+  const logical = (f) => { const k = kitRel(f); return k !== null ? k : f; };
+
+  // ── initiative records and what they name ──
+  const initiatives = new Map(); // id -> {rel, fm}
+  const isInitiativeRecord = (f) => {
+    const lp = logical(f);
+    return DOC_EXT.has(path.extname(f).toLowerCase()) && /^(state|planning)\/initiatives\/[^/]+\.md$/.test(lp)
+      && !/^(README|index)\.md$/i.test(path.posix.basename(f)) && !isKit(f);
+  };
+  for (const f of files) {
+    if (!isInitiativeRecord(f)) continue;
+    const { fm } = parseFrontmatter(text.get(f) || '');
+    const id = (fm && fm.id) || path.posix.basename(f, '.md');
+    if (!initiatives.has(id)) initiatives.set(id, { rel: f, fm: fm || {} });
+  }
+  const resolveRef = (from, v) => {
+    const c = String(v).trim().replace(/^["']|["']$/g, '');
+    if (!c) return null;
+    const cand = [c.replace(/^\//, ''), path.posix.join(path.posix.dirname(from), c)];
+    if (kitDir) cand.push(path.posix.join(kitDir, c.replace(/^\//, '')));
+    for (const x of cand) { const n = path.posix.normalize(x); if (fileSet.has(n)) return n; }
+    return null;
+  };
+  const claims = new Map(); // file -> Set(initiative id), strong evidence (frontmatter path key or markdown link)
+  const mentions = new Map(); // file -> Set(initiative id), prose mention only (suggestion, never acted on)
+  const claim = (m, f, id) => { if (!m.has(f)) m.set(f, new Set()); m.get(f).add(id); };
+  for (const [id, { rel, fm }] of initiatives) {
+    const body = text.get(rel) || '';
+    const parsed = parseFrontmatter(body);
+    for (const v of Object.values(fm)) { const r = resolveRef(rel, v); if (r && r !== rel) claim(claims, r, id); }
+    for (const l of extractLinks(body)) {
+      if (l.kind !== 'md' || EXTERNAL.test(l.raw)) continue;
+      const r = resolveRef(rel, safeDecode(splitHref(l.raw).p));
+      if (r && r !== rel) claim(claims, r, id);
+    }
+    const after = parsed.end >= 0 ? body.split('\n').slice(parsed.end + 1).join('\n') : body;
+    for (const m of after.matchAll(/[\w./-]+\/[\w./-]+\.(?:md|docx|xlsx|pdf)/g)) {
+      const r = resolveRef(rel, m[0]);
+      if (r && r !== rel && !(claims.get(r) && claims.get(r).has(id))) claim(mentions, r, id);
+    }
+  }
+  const named = categorizeNamed(initiatives);
+
+  // ── classify every file ──
+  const entries = [];
+  const base = `products/${domain}`;
+  for (const f of files) {
+    const st = stat.get(f);
+    const e = classify(f, st);
+    e.size = st.size;
+    e.sha256 = hashFile(path.join(root, f), st);
+    entries.push(e);
+  }
+
+  function entry(from, cls, action, to, reason, confidence, needsPm, extra) {
+    return Object.assign({ from, class: cls, action, to, reason, confidence, needs_pm: !!needsPm }, extra || {});
+  }
+
+  function ownerOf(f, t) {
+    // evidence a, strong: a record names the path (frontmatter key or link)
+    const strong = claims.get(f) ? [...claims.get(f)] : [];
+    // evidence b: the document declares an initiative_id (frontmatter, or the kit's `## Frontmatter` / `## Identity` prose)
+    const parsed = parseFrontmatter(t || '');
+    const dId = (parsed.fm && parsed.fm.initiative_id) || declared(t || '', 'initiative_id');
+    const declaredId = dId && dId !== '<id>' ? dId : null;
+    const sugg = [];
+    if (declaredId && !initiatives.has(declaredId)) sugg.push({ id: declaredId, evidence: 'declared initiative_id does not resolve to a record' });
+    for (const id of (mentions.get(f) || [])) sugg.push({ id, evidence: 'named in prose by an initiative record' });
+    // a name match is a SUGGESTION only
+    const lpl = logical(f).toLowerCase();
+    for (const id of initiatives.keys()) {
+      if (lpl.split('/').includes(id.toLowerCase()) || path.posix.basename(lpl).startsWith(id.toLowerCase() + '-')) sugg.push({ id, evidence: 'file or folder name matches (a name alone is not ownership)' });
+    }
+    const ids = new Set(strong);
+    if (declaredId && initiatives.has(declaredId)) ids.add(declaredId);
+    if (ids.size === 1) return { owner: [...ids][0], evidence: strong.length ? 'named by an initiative record' + (declaredId && initiatives.has(declaredId) ? ' and declared in the file' : '') : 'declared initiative_id in the file' };
+    if (ids.size > 1) return { conflict: [...ids].sort(), suggested: [] };
+    const seen = new Set(); const uniq = sugg.filter((s) => (seen.has(s.id) ? false : (seen.add(s.id), true)));
+    return { suggested: uniq };
+  }
+
+  function classify(f, st) {
+    const ext = path.extname(f).toLowerCase();
+    const b = path.posix.basename(f);
+    const lp = logical(f);
+    if (st.isSymbolicLink()) return entry(f, 'other', 'keep', f, 'a symbolic link: never followed, left in place', 'high', false);
+    if (connect && /^(planning|okf|products)\//.test(f)) {
+      return entry(f, ext === '.jsonl' ? 'record' : 'document', 'keep', f, 'already follows PMOS conventions: kept as is, only the rest of the folder is converted', 'high', false, { notes: ['PMOS-convention folder'] });
+    }
+    if (st.isFile() && !ATTACH_EXT.has(ext) && DOC_EXT.has(ext) && (text.get(f) || '').includes('\0')) {
+      return entry(f, 'other', 'keep', f, 'named like a document but not readable as text: left alone', 'high', false, { notes: ['unreadable as text'] });
+    }
+    if (ext === '.md' && fileSet.has(f.slice(0, -3)) && (ATTACH_EXT.has(path.extname(f.slice(0, -3)).toLowerCase()) || /\.(txt|html?)$/i.test(f.slice(0, -3)))) {
+      return entry(f, 'document', 'keep', f, 'a sidecar note that already exists beside its file', 'high', false, { notes: ['existing sidecar'] });
+    }
+    if (connect && (ext === '.txt' || ext === '.html' || ext === '.htm')) return textSidecar(f, st, ext);
+    if (isKit(f)) return entry(f, 'kit', 'upgrade', f, `vendored kit (${kitDir}/): replaced by 'create-pmos' upgrade, never moved by hand`, 'high', false);
+    // code and tooling
+    if (CODE_EXT.has(ext) || /^(tools|\.github|\.claude)\//.test(f)) return entry(f, 'code', 'keep', f, 'tool, CI or agent configuration: stays where tooling expects it', 'high', false);
+    if (b === '.DS_Store') return entry(f, 'other', 'keep', f, 'operating-system noise: left alone (candidate for .gitignore)', 'high', false);
+    if (!f.includes('/') && (b === 'CLAUDE.md' || b === 'AGENTS.md' || b.startsWith('.'))) return entry(f, 'other', 'keep', f, 'repo-root agent instruction or dotfile: stays at the root', 'high', false);
+    if (f === 'portfolio.yaml') return entry(f, 'record', 'keep', f, 'repo-to-domain map: input to roots.json, which the apply step writes new; this file is not moved', 'high', false);
+    // attachments stay in place with a sidecar note
+    if (ATTACH_EXT.has(ext)) {
+      const sidecar = f + '.md';
+      const own = (claims.get(f) && claims.get(f).size === 1) ? [...claims.get(f)][0] : null;
+      const title = humanize(f);
+      const ts = git.dates.get(f) || st.mtime.toISOString().slice(0, 10);
+      const fmAdd = { type: 'Reference', title, timestamp: ts, attachment: b };
+      if (own) fmAdd.initiative_id = `${domain}/${own}`;
+      if (fileSet.has(sidecar)) return entry(f, 'attachment', 'keep', f, `${ext} attachment: its sidecar note already exists`, 'high', false, { owner: null, notes: ['sidecar present'] });
+      return entry(f, 'attachment', 'sidecar', f, `${ext} attachment: stays in place; a sidecar note carries the frontmatter`, 'high', false,
+        { owner: own ? `${domain}/${own}` : null, sidecar_to: sidecar, sidecar_frontmatter: fmAdd });
+    }
+    // initiative records and ledgers
+    if (isInitiativeRecord(f)) {
+      const { fm, multiline } = parseFrontmatter(text.get(f) || '');
+      const id = (fm && fm.id) || path.posix.basename(f, '.md');
+      const fa = planFrontmatter({ lp, text: text.get(f) || '', fm, git, rel: f, mtimeIso: st.mtime.toISOString().slice(0, 10), category: null, isRecord: true });
+      return entry(f, 'record', 'move', `${base}/initiatives/${id}/initiative.md`, 'initiative record: becomes initiative.md in its own folder', 'high', false,
+        { owner: `${domain}/${id}`, frontmatter_add: fa.add, multiline_frontmatter: multiline, notes: fa.notes });
+    }
+    if (/^state\/initiatives\/archive\//.test(lp)) {
+      return entry(f, 'record', 'inbox', `${base}/inbox/${lp}`, 'archived initiative record: its consolidated live record is not derivable from the file', 'medium', true, { notes: ['append-only history: keep the file whole'] });
+    }
+    if (/^planning\/(runs\/[^/]+\.jsonl|work-items\.jsonl)$/.test(lp) || (/^state\/.+\.jsonl$/.test(lp))) {
+      const rest = lp.replace(/^(state|planning)\//, '');
+      return entry(f, 'record', 'move', `${base}/ledgers/${rest}`, 'append-only ledger: moved whole (history preserved); splitting per initiative into work.jsonl is a later step', 'high', false, { notes: ['mixed-initiative ledger'] });
+    }
+    if (/^state\/(discoveries\.md)$/.test(lp)) return docRecord(f, lp, `${base}/ledgers/${b}`, 'run and friction log: a record, moved whole');
+    if (/^state\/reports\//.test(lp) && DOC_EXT.has(ext)) return docRecord(f, lp, `${base}/reports/${lp.slice('state/reports/'.length)}`, 'kit-generated report or report definition');
+    if (/^state\/live-notes\//.test(lp)) return entry(f, 'record', 'move', `${base}/ledgers/${lp.slice('state/'.length)}`, 'append-only live-notes ledger', 'high', false);
+    if (/^state\//.test(lp) && ext !== '.md') return entry(f, 'record', 'inbox', `${base}/inbox/${lp}`, 'state file of an unknown kind', 'low', true);
+    if (/^state\//.test(lp)) return docOrInbox(f, st, 'record');
+    // documents
+    if (DOC_EXT.has(ext)) return docOrInbox(f, st, 'document');
+    // everything else: data files, html
+    if ((ext === '.html' || ext === '.htm') && /^prototype\//.test(lp)) return entry(f, 'other', 'keep', f, 'prototype page: prototypes live in their own quarantined folder and never ship', 'high', false);
+    return entry(f, 'other', 'inbox', `${base}/inbox/${lp}`, `${ext || 'extensionless'} file with no known home`, 'low', true);
+  }
+
+  /** .txt and .html cannot carry YAML frontmatter without changing the file, so a sidecar note carries it. */
+  function textSidecar(f, st, ext) {
+    let body = '';
+    try { body = fs.readFileSync(path.join(root, f), 'utf8'); } catch { /* unreadable */ }
+    if (body.includes('\0')) return entry(f, 'other', 'keep', f, 'not readable as text: left alone', 'high', false, { notes: ['unreadable as text'] });
+    let title = null;
+    if (ext !== '.txt') { const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(body) || /<h1[^>]*>([\s\S]*?)<\/h1>/i.exec(body); if (m) title = m[1].replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim(); }
+    else title = (body.split('\n').find((l) => l.trim()) || '').trim().slice(0, 100) || null;
+    const fmAdd = { type: 'Reference', title: title || humanize(f), timestamp: git.dates.get(f) || st.mtime.toISOString().slice(0, 10) };
+    const tg = tagsFor(f); if (tg) fmAdd.tags = tg;
+    return entry(f, 'document', 'sidecar', f, `${ext} prose document: stays; a sidecar note carries the frontmatter (its body is never edited)`, 'high', false,
+      { owner: null, sidecar_to: f + '.md', sidecar_frontmatter: fmAdd });
+  }
+
+  function docRecord(f, lp, to, reason) {
+    const t = text.get(f) || ''; const { fm, multiline } = parseFrontmatter(t);
+    const fa = planFrontmatter({ lp, text: t, fm, git, rel: f, mtimeIso: stat.get(f).mtime.toISOString().slice(0, 10), category: null, isRecord: false });
+    return entry(f, 'record', 'move', to, reason, 'high', false, { frontmatter_add: RESERVED.has(path.posix.basename(f)) ? {} : fa.add, multiline_frontmatter: multiline, notes: fa.notes });
+  }
+
+  function docOrInbox(f, st, cls) {
+    const t = text.get(f) || '';
+    const lp = logical(f);
+    const b = path.posix.basename(f);
+    const { fm, multiline } = parseFrontmatter(t);
+    const cat = require('../workspace/lib/doc-category.js').categorize({ rel: lp, fm: fm || {}, text: t, named });
+    const reserved = RESERVED.has(b);
+    const fa = planFrontmatter({ lp, text: t, fm, git, rel: f, mtimeIso: st.mtime.toISOString().slice(0, 10), category: cat.category, isRecord: false });
+    if (connect && !reserved && !(fm && fm.tags)) { const tg = tagsFor(f); if (tg) fa.add.tags = tg; }
+    const common = { category: cat.category, category_basis: cat.basis, multiline_frontmatter: multiline, notes: fa.notes, frontmatter_add: reserved ? {} : fa.add };
+    const own = ownerOf(f, t);
+    if (own.owner) {
+      const add = Object.assign({}, common.frontmatter_add);
+      const rev = git.counts.get(f);
+      if (!reserved && rev && !(fm && fm.rev)) add.rev = rev;
+      return entry(f, cls === 'record' ? 'record' : 'document', 'move', `${base}/initiatives/${own.owner}/docs/${b}`, `belongs to initiative ${own.owner}: ${own.evidence}`, 'high', false,
+        Object.assign({ owner: `${domain}/${own.owner}` }, common, { frontmatter_add: add }));
+    }
+    // domain-level homes, decided by a documented kit location, never by guessing
+    const dom = domainHome(lp, fm);
+    if (dom) return entry(f, 'document', 'move', `${base}/${dom.dir}`, dom.reason, 'high', false, Object.assign({ owner: null }, common));
+    const tos = `${base}/inbox/${lp}`;
+    const why = own.conflict ? `claimed by several initiatives (${own.conflict.join(', ')}): the PM decides`
+      : (own.suggested && own.suggested.length) ? 'no ownership evidence a tool can act on; a possible owner is suggested for the PM'
+        : 'no owner evidence (no record names it, no initiative_id): the PM decides';
+    return entry(f, cls === 'record' ? 'record' : 'document', 'inbox', tos, why, own.suggested && own.suggested.length ? 'medium' : 'low', true,
+      Object.assign({ owner: null, suggested_owner: (own.suggested || []).map((s) => ({ initiative: `${domain}/${s.id}`, evidence: s.evidence })) }, own.conflict ? { conflict: own.conflict } : {}, common,
+        privateHint(lp, t) ? { sensitivity_review: privateHint(lp, t) } : {}));
+  }
+
+  function privateHint(lp, t) {
+    if (/^briefs\//.test(lp)) return 'daily briefs cite the PM\'s calendar, mail and chat: some of this may belong in me/, not in a shared domain';
+    if (/(gmail|slack|calendar|inbox)\b/i.test(t.slice(0, 600)) && /^(briefs|notes)\//.test(lp)) return 'cites personal sources';
+    return null;
+  }
+
+  function domainHome(lp, fm) {
+    let m;
+    if (lp === 'planning/okrs/health-budgets.md') return { dir: 'health/health-budgets.md', reason: 'health budgets (kit location planning/okrs/health-budgets.md)' };
+    if ((m = /^planning\/okrs\/(.+)$/.exec(lp))) return { dir: `strategy/${m[1]}`, reason: 'OKRs live under strategy/ (kit location planning/okrs/)' };
+    if ((m = /^okf\/product\/(.+)$/.exec(lp))) return { dir: `knowledge/${m[1]}`, reason: "the tenant's own OKF bundle (okf/product/) is the domain's knowledge/" };
+    if ((m = /^planning\/out-of-scope\/(.+)$/.exec(lp))) return { dir: `decisions/out-of-scope/${m[1]}`, reason: 'prior rejections are decisions (kit location planning/out-of-scope/)' };
+    if ((m = /^reports\/(.+)$/.exec(lp))) return { dir: `reports/${m[1]}`, reason: 'a report in the reports/ folder' };
+    if (fm && /^(Decision|ADR)$/.test(fm.type || '')) return { dir: `decisions/${path.posix.basename(lp)}`, reason: `declared type ${fm.type}` };
+    return null;
+  }
+
+  // ── collisions: refuse to plan a clobber ──
+  const taken = new Map(); // target path -> source
+  for (const e of entries) if (e.action === 'keep' || e.action === 'upgrade' || e.action === 'sidecar') taken.set(e.to, e.from);
+  for (const e of entries) if (e.sidecar_to) taken.set(e.sidecar_to, e.from + ' (sidecar)');
+  for (const e of entries) {
+    if (e.action !== 'move' && e.action !== 'inbox') continue;
+    let t = e.to;
+    if (taken.has(t) || fileSet.has(t) && t !== e.from) {
+      const rival = taken.get(t) || t;
+      const ext = path.posix.extname(t); const stem = t.slice(0, t.length - ext.length);
+      let n = 2; while (taken.has(`${stem}-${n}${ext}`) || fileSet.has(`${stem}-${n}${ext}`)) n++;
+      e.collision = true; e.collides_with = rival; e.wanted_to = t;
+      e.to = `${stem}-${n}${ext}`;
+      e.needs_pm = true;
+      e.reason += `; target name was taken by ${rival}, suffixed -${n}`;
+      t = e.to;
+    }
+    taken.set(t, e.from);
+  }
+
+  // ── links ──
+  const dest = new Map(entries.map((e) => [e.from, e.to]));
+  const kitByFrom = new Map(entries.map((e) => [e.from, e.class === 'kit']));
+  const linkIssues = []; const alreadyBroken = []; let linksChecked = 0;
+  const stems = new Map();
+  for (const f of files) if (DOC_EXT.has(path.extname(f).toLowerCase())) { const s = path.posix.basename(f).replace(/\.[^.]+$/, ''); if (!stems.has(s)) stems.set(s, []); stems.get(s).push(f); }
+
+  const bases = ['', ...(kitDir ? [kitDir + '/', kitDir + '/okf/'] : [])];
+  for (const f of files) {
+    if (!text.has(f)) continue;
+    const srcNew = dest.get(f);
+    const srcKit = kitByFrom.get(f);
+    const body = text.get(f);
+    const seen = new Set();
+    const note = (iss) => { const k = iss.kind + '|' + iss.href; if (seen.has(k)) return; seen.add(k); linkIssues.push(Object.assign({ file: f, file_to: srcNew, source_is_kit: !!srcKit }, iss)); };
+    for (const l of extractLinks(body)) {
+      linksChecked++;
+      if (l.kind === 'wiki') {
+        let target = null;
+        const w = l.raw.replace(/\.md$/, '');
+        if (w.includes('/')) { for (const c of [w + '.md', w, ...(kitDir ? [kitDir + '/' + w + '.md'] : [])]) if (fileSet.has(c)) { target = c; break; } }
+        else if (stems.has(w) && stems.get(w).length === 1) target = stems.get(w)[0];
+        if (!target) { alreadyBroken.push({ file: f, href: l.raw, kind: 'wiki' }); continue; }
+        const tNew = dest.get(target);
+        if (tNew === target) continue;
+        if (w.includes('/')) note({ kind: 'wiki', href: l.raw, target, target_to: tNew, rewrite: tNew.replace(/\.md$/, '') });
+        else { const ns = path.posix.basename(tNew).replace(/\.[^.]+$/, ''); if (ns !== w) note({ kind: 'wiki', href: l.raw, target, target_to: tNew, rewrite: ns }); }
+        continue;
+      }
+      if (EXTERNAL.test(l.raw)) continue;
+      const { p, tail } = splitHref(l.raw);
+      if (!p) continue;
+      const dec = safeDecode(p);
+      const abs = dec.startsWith('/');
+      let target = null; let usedBase = '';
+      if (abs) { for (const bs of bases) { const c = path.posix.normalize(bs + dec.slice(1)); if (fileSet.has(c)) { target = c; usedBase = bs; break; } } }
+      else { const c = path.posix.normalize(path.posix.join(path.posix.dirname(f), dec)); if (fileSet.has(c)) target = c; }
+      if (!target) { alreadyBroken.push({ file: f, href: l.raw, kind: 'md' }); continue; }
+      const tNew = dest.get(target);
+      let newHref;
+      if (abs) {
+        // an absolute link stays absolute when its target is still under the same base; otherwise it becomes relative
+        newHref = tNew.startsWith(usedBase) ? '/' + tNew.slice(usedBase.length) : path.posix.relative(path.posix.dirname(srcNew), tNew);
+      } else {
+        newHref = path.posix.relative(path.posix.dirname(srcNew), tNew);
+      }
+      if (newHref === null) { note({ kind: 'md', href: l.raw, target, target_to: tNew, rewrite: null, note: 'the target leaves the bundle this absolute link is rooted in: choose a form by hand' }); continue; }
+      const enc = /%[0-9A-Fa-f]{2}/.test(p) ? encodeURI(newHref) : newHref;
+      if (safeDecode(enc) === dec) continue; // still resolves to the same text
+      note({ kind: 'md', href: l.raw, target, target_to: tNew, rewrite: enc + tail });
+    }
+    // frontmatter path values and bare path mentions in prose
+    const parsed = parseFrontmatter(body);
+    const fmLines = parsed.end >= 0 ? body.split('\n').slice(0, parsed.end + 1) : [];
+    const consumed = new Set();
+    for (const ln of fmLines) {
+      const m = /^([A-Za-z0-9_-]+):\s*(.+)$/.exec(ln);
+      if (!m) continue;
+      const v = m[2].trim().replace(/^["']|["']$/g, '');
+      const r = fileSet.has(v) ? v : (fileSet.has(v.replace(/^\//, '')) ? v.replace(/^\//, '') : null);
+      if (r && dest.get(r) !== r) { note({ kind: 'frontmatter-path', href: v, key: m[1], target: r, target_to: dest.get(r), rewrite: dest.get(r) }); consumed.add(v); }
+    }
+    const rest = parsed.end >= 0 ? body.split('\n').slice(parsed.end + 1).join('\n') : body;
+    for (const m of rest.matchAll(/[\w./-]+\/[\w./-]+\.[A-Za-z0-9]+/g)) {
+      const tok = m[0]; const before = rest.slice(Math.max(0, m.index - 2), m.index);
+      if (before === '](' || before.endsWith('[[') || consumed.has(tok)) continue;
+      const r = fileSet.has(tok) ? tok : null;
+      if (r && dest.get(r) !== r) note({ kind: 'path-mention', href: tok, target: r, target_to: dest.get(r), rewrite: dest.get(r) });
+    }
+  }
+
+  // ── strategies: the plan above is the restructure plan; in-place keeps every file where it is ──
+  const rewritable = (i) => i.rewrite !== null && i.rewrite !== undefined && !i.source_is_kit;
+  const restructureLinks = linkIssues.filter((i) => i.kind !== 'path-mention' && rewritable(i)).length;
+  const restructureMentions = linkIssues.filter((i) => i.kind === 'path-mention' && rewritable(i)).length;
+  const restructureCounts = {
+    moves: entries.filter((e) => e.action === 'move').length,
+    inbox: entries.filter((e) => e.action === 'inbox').length,
+    needs_pm: entries.filter((e) => e.needs_pm).length,
+    collisions: entries.filter((e) => e.collision).length,
+    links_to_rewrite: restructureLinks, path_mentions_to_rewrite: restructureMentions,
+  };
+  const sidecars = entries.filter((e) => e.action === 'sidecar').length;
+  const fmAdds = entries.filter((e) => e.frontmatter_add && Object.keys(e.frontmatter_add).length).length;
+  if (strategy === 'in-place') {
+    for (const e of entries) {
+      if (e.action !== 'move' && e.action !== 'inbox') continue;
+      e.restructure = { action: e.action, to: e.to, needs_pm: e.needs_pm, collision: !!e.collision };
+      e.action = 'keep'; e.to = e.from; e.needs_pm = false; delete e.collision; delete e.collides_with; delete e.wanted_to;
+      e.reason = 'in-place: stays where it is; frontmatter is added. (restructure would: ' + e.restructure.action + ' to ' + e.restructure.to + ')';
+    }
+  }
+  const inPlace = strategy === 'in-place';
+  const keptLinks = inPlace ? [] : linkIssues;
+  let outEntries = entries; let outLinks = keptLinks; let outBroken = alreadyBroken;
+
+  // ── incremental re-scan: only new or changed files, compared by content hash with the previous manifest ──
+  let incremental = null;
+  if (opts.since) {
+    const prev = new Map((opts.since.entries || []).map((e) => [e.from, e.sha256]));
+    const isNew = []; const isChanged = []; let unchanged = 0;
+    for (const e of entries) {
+      if (!prev.has(e.from)) isNew.push(e.from);
+      else if (prev.get(e.from) !== e.sha256) isChanged.push(e.from);
+      else unchanged++;
+    }
+    const listed = new Set([...isNew, ...isChanged]);
+    const nowSet = new Set(entries.map((e) => e.from));
+    incremental = { new: isNew.length, changed: isChanged.length, unchanged, removed: [...prev.keys()].filter((k) => !nowSet.has(k)).sort(), new_files: isNew, changed_files: isChanged };
+    outEntries = entries.filter((e) => listed.has(e.from));
+    outLinks = keptLinks.filter((i) => listed.has(i.file));
+    outBroken = alreadyBroken.filter((i) => listed.has(i.file));
+  }
+
+  // ── summary ──
+  const countBy = (k) => outEntries.reduce((a, e) => { a[e[k]] = (a[e[k]] || 0) + 1; return a; }, {});
+  const outRewritable = (i) => rewritable(i);
+  const summary = {
+    files: outEntries.length,
+    by_class: countBy('class'),
+    by_action: countBy('action'),
+    needs_pm: outEntries.filter((e) => e.needs_pm).length,
+    collisions: outEntries.filter((e) => e.collision).length,
+    links_checked: linksChecked,
+    links_to_rewrite: outLinks.filter((i) => i.kind !== 'path-mention' && outRewritable(i)).length,
+    path_mentions_to_rewrite: outLinks.filter((i) => i.kind === 'path-mention' && outRewritable(i)).length,
+    links_needing_manual_choice: outLinks.filter((i) => i.rewrite === null && !i.source_is_kit).length,
+    links_from_kit_files: outLinks.filter((i) => i.source_is_kit).length,
+    links_already_broken: outBroken.length,
+    multiline_frontmatter_files: outEntries.filter((e) => e.multiline_frontmatter && e.multiline_frontmatter.length).length,
+    initiatives: initiatives.size,
+    kit_dir: kitDir,
+    mode, strategy,
+    skipped: skipped.length,
+    strategies: {
+      'in-place': { moves: 0, frontmatter_additions: fmAdds, sidecars, links_to_rewrite: 0, needs_pm: 0 },
+      restructure: Object.assign({ frontmatter_additions: fmAdds, sidecars }, restructureCounts),
+    },
+  };
+  const registration = {
+    applied: false,
+    note: 'Proposed only. A registration writes to the PM\'s own state and to roots.json; the planner never performs it. The PM applies it after approving this manifest.',
+    roots_json_entry: { name: domain, kind: 'domain', path: root, layout: inPlace ? 'in-place' : 'portfolio-v1', private: false },
+    workspace_registration: { action: 'register-workspace', root, name: path.basename(root), domain, writes: 'the workspace registry in the per-user state dir' },
+  };
+  return {
+    schema: 'pmos-migrate-layout/2',
+    tenant: root, tenant_name: path.basename(root), domain, mode, strategy, git_history: git.available,
+    summary, entries: outEntries, links: outLinks, already_broken_links: outBroken,
+    skipped, skipped_by_rule: skippedByRule, registration, incremental,
+    initiatives: [...initiatives.keys()].sort(),
+  };
+}
+
+function categorizeNamed(initiatives) {
+  const dc = require('../workspace/lib/doc-category.js');
+  return dc.namedFromRecords([...initiatives.values()].map((v) => ({ rel: v.rel, fm: v.fm })));
+}
+
+// ── manifest.md ─────────────────────────────────────────────────────────────────────────────────────────────────
+function renderReport(m, today) {
+  const s = m.summary;
+  const L = [];
+  const row = (...c) => '| ' + c.join(' | ') + ' |';
+  L.push('---', 'type: Reference', `title: "Layout migration plan: ${m.tenant_name}"`, `timestamp: ${today || new Date().toISOString().slice(0, 10)}`, '---', '');
+  L.push(`# Layout migration plan: ${m.tenant_name}`, '');
+  L.push('A dry-run plan. Nothing was written into the tenant. The apply step is not built; see `scripts/migrate-layout-APPLY-DESIGN.md`.', '');
+  L.push(`Tenant: \`${m.tenant}\`. Domain: \`${m.domain}\`. Kit dir: \`${s.kit_dir || 'none'}\`. Git history read: ${m.git_history ? 'yes' : 'no'}.`, '');
+  L.push(`Mode: \`${m.mode}\`. Strategy shown: \`${m.strategy}\`. \`in-place\` leaves every file where it is and only adds frontmatter and sidecars. \`restructure\` moves files into products/${m.domain}/.`, '');
+  if (s.strategies) {
+    const a = s.strategies['in-place']; const r = s.strategies.restructure;
+    L.push('## Strategies side by side', '', row('Measure', 'in-place', 'restructure'), row('---', '---', '---'));
+    L.push(row('file moves', a.moves, r.moves), row('moved to inbox', 0, r.inbox), row('frontmatter additions', a.frontmatter_additions, r.frontmatter_additions), row('sidecar notes', a.sidecars, r.sidecars));
+    L.push(row('needing PM review', a.needs_pm, r.needs_pm), row('name collisions', 0, r.collisions), row('links to rewrite', a.links_to_rewrite, r.links_to_rewrite), row('bare path mentions to rewrite', 0, r.path_mentions_to_rewrite), '');
+  }
+  if (m.incremental) L.push('## Incremental re-scan', '', `Only new or changed files are listed: ${m.incremental.new} new, ${m.incremental.changed} changed, ${m.incremental.unchanged} unchanged, ${m.incremental.removed.length} removed since the previous manifest.`, '');
+  if (m.registration) L.push('## Proposed registration (NOT performed)', '', m.registration.note, '', '```json', JSON.stringify({ roots_json_entry: m.registration.roots_json_entry, workspace_registration: m.registration.workspace_registration }, null, 2), '```', '');
+  if (m.skipped && m.skipped.length) L.push(`## Skipped (${m.skipped.length})`, '', ...m.skipped.slice(0, 60).map((x) => '- `' + x.path + '`: ' + x.reason), '');
+  L.push('## Summary', '', row('Measure', 'Count'), row('---', '---'));
+  L.push(row('files', s.files));
+  for (const [k, v] of Object.entries(s.by_class)) L.push(row('class ' + k, v));
+  for (const [k, v] of Object.entries(s.by_action)) L.push(row('action ' + k, v));
+  L.push(row('needing PM review', s.needs_pm), row('name collisions (suffixed)', s.collisions), row('initiative records', s.initiatives));
+  L.push(row('links that would break (rewrite listed)', s.links_to_rewrite), row('bare path mentions that would go stale', s.path_mentions_to_rewrite));
+  L.push(row('links needing a manual choice', s.links_needing_manual_choice), row('links found inside kit files (kit upgrade owns them)', s.links_from_kit_files));
+  L.push(row('links already broken before any move', s.links_already_broken), row('files with multi-line frontmatter (not one key per line)', s.multiline_frontmatter_files), '');
+  const nonKit = m.entries.filter((e) => e.class !== 'kit');
+  L.push('## Kit (upgrade, never moved by hand)', '');
+  const kit = m.entries.filter((e) => e.class === 'kit');
+  const kitTop = {}; for (const e of kit) { const t = e.from.split('/').slice(0, 2).join('/'); kitTop[t] = (kitTop[t] || 0) + 1; }
+  for (const [k, v] of Object.entries(kitTop).sort()) L.push(`- \`${k}\`: ${v} files`);
+  L.push('');
+  L.push('## Planned moves by destination', '');
+  const dests = {};
+  for (const e of nonKit.filter((x) => x.action === 'move' || x.action === 'inbox')) { const d = e.to.split('/').slice(0, 4).join('/'); dests[d] = (dests[d] || 0) + 1; }
+  for (const [k, v] of Object.entries(dests).sort()) L.push(`- \`${k}\`: ${v}`);
+  L.push('');
+  const review = nonKit.filter((e) => e.needs_pm);
+  L.push(`## PM review queue (${review.length})`, '');
+  L.push(row('From', 'Proposed', 'Why', 'Suggested owner'), row('---', '---', '---', '---'));
+  for (const e of review) L.push(row('`' + e.from + '`', '`' + e.to + '`', (e.collision ? 'COLLISION. ' : '') + e.reason.replace(/\|/g, '/'), (e.suggested_owner || []).map((x) => x.initiative).join(', ') || ''));
+  L.push('');
+  const priv = nonKit.filter((e) => e.sensitivity_review);
+  if (priv.length) { L.push(`## Possible personal content (${priv.length})`, '', priv[0].sensitivity_review, '', ...priv.slice(0, 20).map((e) => '- `' + e.from + '`'), priv.length > 20 ? `- ... and ${priv.length - 20} more` : '', ''); }
+  const coll = nonKit.filter((e) => e.collision);
+  if (coll.length) { L.push(`## Collisions (${coll.length})`, '', row('From', 'Wanted', 'Planned', 'Taken by'), row('---', '---', '---', '---')); for (const e of coll) L.push(row('`' + e.from + '`', '`' + e.wanted_to + '`', '`' + e.to + '`', '`' + e.collides_with + '`')); L.push(''); }
+  const lk = m.links.filter((i) => !i.source_is_kit);
+  L.push(`## Links and references to rewrite (${lk.length})`, '', 'Each row lists the exact text in the file and the text that fixes it. A rewrite edits a body, so it is a separate commit the PM approves; the move commit leaves bodies byte-identical.', '');
+  L.push(row('File (now)', 'Kind', 'Current', 'Rewrite to'), row('---', '---', '---', '---'));
+  for (const i of lk.slice(0, 400)) L.push(row('`' + i.file + '`', i.kind, '`' + i.href + '`', i.rewrite === null ? 'manual: ' + (i.note || '') : '`' + i.rewrite + '`'));
+  if (lk.length > 400) L.push('', `... ${lk.length - 400} more in the JSON manifest.`);
+  L.push('');
+  const fmw = nonKit.filter((e) => e.multiline_frontmatter && e.multiline_frontmatter.length);
+  if (fmw.length) { L.push(`## Frontmatter that is not one key per line (${fmw.length})`, '', 'OKF v0.2 wants keys on one line. The planner adds keys only; it does not reflow these.', '', ...fmw.slice(0, 40).map((e) => '- `' + e.from + '`: ' + e.multiline_frontmatter.join(', ')), ''); }
+  const notes = nonKit.filter((e) => e.notes && e.notes.some((n) => /work lane|not in the registry/.test(n)));
+  if (notes.length) { L.push(`## Frontmatter type conflicts (${notes.length})`, '', ...notes.slice(0, 40).map((e) => '- `' + e.from + '`: ' + e.notes.filter((n) => /work lane|not in the registry/.test(n)).join('; ')), ''); }
+  return L.join('\n') + '\n';
+}
+
+// ── verify ──────────────────────────────────────────────────────────────────────────────────────────────────────
+function verify(manifest, tenantRoot) {
+  const root = path.resolve(tenantRoot);
+  const drift = [];
+  const files = walk(root, manifest.mode === 'connect' ? [] : null, 25 * 1024 * 1024 * 100);
+  const fileSet = new Set(files);
+  const known = new Set(manifest.entries.map((e) => e.from));
+  for (const e of manifest.entries) {
+    if (!fileSet.has(e.from)) { drift.push({ type: 'missing', path: e.from, detail: 'in the plan, not in the repo' }); continue; }
+    const st = fs.lstatSync(path.join(root, e.from));
+    if (e.sha256 && st.isFile() && st.size <= HASH_LIMIT && hashFile(path.join(root, e.from), st) !== e.sha256) drift.push({ type: 'changed', path: e.from, detail: 'content differs from the planned hash' });
+    if ((e.action === 'move' || e.action === 'inbox') && e.to !== e.from && fileSet.has(e.to)) drift.push({ type: 'target-taken', path: e.to, detail: `planned target for ${e.from} now exists` });
+    if (e.sidecar_to && fileSet.has(e.sidecar_to)) drift.push({ type: 'target-taken', path: e.sidecar_to, detail: `sidecar for ${e.from} now exists` });
+  }
+  if (!manifest.incremental) for (const f of files) if (!known.has(f)) drift.push({ type: 'new-file', path: f, detail: 'not in the plan' });
+  return { ok: drift.length === 0, drift, checked: manifest.entries.length };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+function insideDir(child, parent) { const r = path.relative(parent, child); return r === '' || (!r.startsWith('..') && !path.isAbsolute(r)); }
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const flags = {}; const pos = [];
+  for (let i = 0; i < rest.length; i++) { if (rest[i].startsWith('--')) { flags[rest[i].slice(2)] = rest[i + 1]; i++; } else pos.push(rest[i]); }
+  if (cmd === 'plan' && pos[0]) {
+    const root = path.resolve(pos[0]);
+    const since = flags.since ? JSON.parse(fs.readFileSync(path.resolve(flags.since), 'utf8')) : null;
+    const m = plan(root, { domain: flags.domain, mode: flags.mode, strategy: flags.strategy, since, maxBytes: flags['max-mb'] ? Number(flags['max-mb']) * 1024 * 1024 : undefined });
+    if (flags.out) {
+      const out = path.resolve(flags.out);
+      let realRoot = root; try { realRoot = fs.realpathSync(root); } catch { /* keep */ }
+      if (insideDir(out, root) || insideDir(out, realRoot) || insideDir(path.join(fs.existsSync(path.dirname(out)) ? fs.realpathSync(path.dirname(out)) : path.dirname(out), path.basename(out)), realRoot)) {
+        process.stderr.write(`refused: --out is inside the tenant repo (${root}). This tool never writes into a tenant.\n`); return 2;
+      }
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, JSON.stringify(m, null, 2) + '\n');
+      const md = out.replace(/\.json$/i, '') + (/\.json$/i.test(out) ? '.md' : '.manifest.md');
+      fs.writeFileSync(md, renderReport(m));
+      process.stdout.write(`wrote ${out}\nwrote ${md}\n`);
+    }
+    process.stdout.write(JSON.stringify(m.summary, null, 2) + '\n');
+    return 0;
+  }
+  if (cmd === 'verify' && pos[0] && pos[1]) {
+    const manifest = JSON.parse(fs.readFileSync(path.resolve(pos[0]), 'utf8'));
+    const r = verify(manifest, pos[1]);
+    if (r.ok) { process.stdout.write(`clean: ${r.checked} planned entries match the repo\n`); return 0; }
+    process.stdout.write(`DRIFT: ${r.drift.length} difference(s)\n`);
+    for (const d of r.drift) process.stdout.write(`  ${d.type.padEnd(12)} ${d.path}  (${d.detail})\n`);
+    return 1;
+  }
+  process.stderr.write('usage:\n  node scripts/migrate-layout.js plan <folder> [--domain general] [--mode connect|tenant] [--strategy in-place|restructure] [--since <manifest.json>] [--max-mb 25] [--out <manifest.json>]\n  node scripts/migrate-layout.js verify <manifest.json> <tenantRoot>\n(no apply, no undo: see scripts/migrate-layout-APPLY-DESIGN.md)\n');
+  return 2;
+}
+
+module.exports = { plan, verify, renderReport, extractLinks, parseFrontmatter };
+if (require.main === module) process.exitCode = main(process.argv.slice(2));