@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/adopt-detect.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/adopt-detect.js — inspect an EXISTING repo tree so `bongos init --adopt`
+// fits what is already there instead of assuming the reference layout (ADR 0121
+// §Decision 4 / task 2043).
+//
+// WHY. Greenfield init writes into a blank slate. `--adopt` LAYERS onto a real repo,
+// so before it writes anything it must know the shape of that repo: language/runtime,
+// package manager, test + CI setup, source layout, and whether it already carries a
+// migrations dir / .claude/ / config/. This detection is the INPUT the later adopt
+// legs consume: real-state capture (task 2044) uses it to seed the right modules + the
+// interview, and the conflict pre-flight (task 2045) reads hasMigrations / ci / layout
+// to compute the blast radius (migration-namespace + CI-workflow collisions).
+//
+// It only READS (existsSync/readFileSync/readdirSync) — no writes, no network — so it
+// is safe to run first, and returns a plain data object (no I/O side effects) for the
+// caller to print and for 2044/2045 to consume. Every probe degrades to a negative
+// signal on a missing/unreadable file; detectStack never throws on repo contents.
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+
+// A repo's package manager, inferred from its lockfile (the authoritative signal),
+// falling back to npm when a package.json exists with no lockfile at all.
+function detectPackageManager(exists, hasPkg) {
+  if (exists('pnpm-lock.yaml')) return 'pnpm';
+  if (exists('yarn.lock')) return 'yarn';
+  if (exists('bun.lockb')) return 'bun';
+  if (exists('package-lock.json')) return 'npm';
+  return hasPkg ? 'npm' : null;
+}
+
+// Detect the stack + layout of the repo rooted at `dir`. Pure but for the injected
+// (or default node) fs reads. Returns a structured summary.
+function detectStack({ dir, fs = nodeFs, path = nodePath } = {}) {
+  if (!dir) throw new Error('detectStack: dir is required');
+  const at = (rel) => path.join(dir, rel);
+  const exists = (rel) => { try { return fs.existsSync(at(rel)); } catch { return false; } };
+  const readJson = (rel) => { try { return JSON.parse(fs.readFileSync(at(rel), 'utf8')); } catch { return null; } };
+  const listDir = (rel = '.') => { try { return fs.readdirSync(at(rel)); } catch { return []; } };
+  const isDir = (rel) => { try { return fs.statSync(at(rel)).isDirectory(); } catch { return false; } };
+
+  const pkg = readJson('package.json');
+  const deps = { ...((pkg && pkg.dependencies) || {}), ...((pkg && pkg.devDependencies) || {}) };
+
+  // languages / runtime — the marker files each ecosystem leaves at the root.
+  const languages = [];
+  if (pkg || exists('tsconfig.json') || exists('jsconfig.json')) languages.push(exists('tsconfig.json') ? 'typescript' : 'javascript');
+  if (exists('requirements.txt') || exists('pyproject.toml') || exists('setup.py') || exists('Pipfile')) languages.push('python');
+  if (exists('go.mod')) languages.push('go');
+  if (exists('Cargo.toml')) languages.push('rust');
+  if (exists('Gemfile')) languages.push('ruby');
+  if (exists('pom.xml') || exists('build.gradle') || exists('build.gradle.kts')) languages.push('java');
+  if (exists('composer.json')) languages.push('php');
+  const runtime = pkg ? 'node' : exists('go.mod') ? 'go' : languages[0] || 'unknown';
+
+  // test frameworks — from deps, then config-file / marker probes for non-node stacks.
+  const testFrameworks = [];
+  for (const fw of ['jest', 'vitest', 'mocha', 'ava', 'jasmine', 'tap']) {
+    if (deps[fw]) testFrameworks.push(fw);
+  }
+  if (exists('pytest.ini') || exists('tox.ini') || deps.pytest) testFrameworks.push('pytest');
+  const hasTestScript = !!(pkg && pkg.scripts && pkg.scripts.test);
+
+  // CI systems — the workflow file(s) each CI reads.
+  const ci = [];
+  if (isDir('.github/workflows')) {
+    const workflows = listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f)).sort();
+    ci.push({ system: 'github-actions', workflows });
+  }
+  if (exists('.gitlab-ci.yml')) ci.push({ system: 'gitlab-ci' });
+  if (exists('.circleci/config.yml')) ci.push({ system: 'circleci' });
+  if (exists('Jenkinsfile')) ci.push({ system: 'jenkins' });
+  if (exists('azure-pipelines.yml')) ci.push({ system: 'azure-pipelines' });
+
+  // directory layout — top-level dirs minus dotdirs + node_modules; then the common
+  // source roots among them (so a later leg can fit the fitness boundary to reality).
+  const topLevelDirs = listDir('.')
+    .filter((n) => n !== 'node_modules' && !n.startsWith('.') && isDir(n))
+    .sort();
+  const sourceDirs = ['src', 'lib', 'app', 'source', 'packages', 'pkg', 'internal'].filter((d) => topLevelDirs.includes(d));
+
+  // pre-existing surfaces the pre-flight (2045) + layering (2042) care about.
+  const migrationsDirs = ['migrations', 'db/migrations', 'prisma/migrations', 'sql/migrations'].filter((d) => isDir(d));
+  const rootEntries = listDir('.').filter((n) => !n.startsWith('.'));
+
+  return {
+    runtime,
+    languages,
+    packageManager: detectPackageManager(exists, !!pkg),
+    hasPackageJson: !!pkg,
+    packageName: (pkg && pkg.name) || null,
+    testFrameworks,
+    hasTestScript,
+    ci,
+    topLevelDirs,
+    sourceDirs,
+    migrationsDirs,
+    hasMigrations: migrationsDirs.length > 0,
+    hasClaudeDir: exists('.claude'),
+    hasConfigDir: exists('config'),
+    isEmptyRepo: rootEntries.length === 0,
+  };
+}
+
+// Human-readable lines for the adopt report — one bullet each. Kept separate from
+// detectStack so the data + its display are independently testable.
+function formatStackSummary(s) {
+  const lines = [];
+  lines.push(`runtime: ${s.runtime}${s.languages.length ? ` (${s.languages.join(', ')})` : ''}`);
+  lines.push(`package manager: ${s.packageManager || 'none detected'}`);
+  lines.push(`tests: ${s.testFrameworks.length ? s.testFrameworks.join(', ') : s.hasTestScript ? 'test script present' : 'none detected'}`);
+  lines.push(`CI: ${s.ci.length ? s.ci.map((c) => c.system).join(', ') : 'none detected'}`);
+  lines.push(`source dirs: ${s.sourceDirs.length ? s.sourceDirs.join(', ') : s.topLevelDirs.length ? s.topLevelDirs.slice(0, 6).join(', ') : 'none'}`);
+  if (s.hasMigrations) lines.push(`migrations: ${s.migrationsDirs.join(', ')} (the pre-flight step will check for namespace collisions)`);
+  const carries = [];
+  if (s.hasClaudeDir) carries.push('.claude/');
+  if (s.hasConfigDir) carries.push('config/');
+  if (carries.length) lines.push(`already carries: ${carries.join(', ')} (layering leaves pre-existing files untouched)`);
+  return lines;
+}
+
+module.exports = { detectStack, detectPackageManager, formatStackSummary };

package/scripts/bongos/adopt-import.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/adopt-import.js — import an existing repo's backlog into GDS tasks so
+// `bongos init --adopt` starts the ledger TRUTHFUL rather than empty (ADR 0121
+// §Decision 3 / task 2044). Sources, in precedence order:
+//   1. GitHub issues — the repo's OPEN issues (via a GitHub token the env supplies)
+//   2. a local backlog file — TODO / ROADMAP / BACKLOG (.md) at the repo root
+//   3. none — the owner captures tasks later (the real version + goal + kickoff still seed)
+//
+// Pure parsers + an injectable fetch keep it testable with no live network. Import is
+// best-effort: a failed/absent GitHub fetch falls through to the local file, and no
+// backlog at all is fine (the ledger still starts with the repo's REAL version/goal).
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+
+const BACKLOG_FILENAMES = ['TODO.md', 'ROADMAP.md', 'BACKLOG.md', 'TODO', 'ROADMAP', 'BACKLOG'];
+const DEFAULT_MAX = 50; // don't flood a fresh ledger; cap the import + report the cap
+
+// PURE — parse a markdown backlog file into task candidates. Recognizes GitHub-style
+// checklist items (- [ ] / - [x]), plain bullet/numbered list items, and uses the
+// nearest preceding heading as light body context. Checked-off items ([x]) are DONE
+// and skipped (a backlog import wants open work). Returns [{ title, body }].
+function parseBacklogFile(text) {
+  const out = [];
+  let heading = '';
+  for (const raw of String(text == null ? '' : text).split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    const h = line.match(/^#{1,6}\s+(.*)$/);
+    if (h) { heading = h[1].trim(); continue; }
+    // - [ ] item | - [x] done | - item | * item | 1. item
+    const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(?:\[([ xX])\]\s+)?(.*\S)\s*$/);
+    if (!m) continue;
+    if (m[1] && m[1].toLowerCase() === 'x') continue; // checked off → done → skip
+    const title = m[2].trim();
+    if (!title) continue;
+    out.push({ title: title.slice(0, 200), body: heading ? `Imported from the repo backlog (under "${heading}").` : 'Imported from the repo backlog.' });
+  }
+  return out;
+}
+
+// Find the first recognized backlog file at the repo root. Returns its basename or null.
+function findBacklogFile(dir, fs = nodeFs, path = nodePath) {
+  for (const name of BACKLOG_FILENAMES) {
+    try {
+      const abs = path.join(dir, name);
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return name;
+    } catch { /* unreadable → skip */ }
+  }
+  return null;
+}
+
+// PURE — GitHub issues API array → task candidates. Filters out pull requests (the
+// issues endpoint returns PRs too, marked by a pull_request key) and non-open issues.
+function parseGitHubIssues(issues) {
+  if (!Array.isArray(issues)) return [];
+  return issues
+    .filter((i) => i && !i.pull_request && (i.state === undefined || i.state === 'open') && i.title)
+    .map((i) => ({ title: String(i.title).slice(0, 200), body: `Imported from ${i.html_url || `issue #${i.number}`}.`, number: i.number }));
+}
+
+// Fetch a repo's OPEN issues via the GitHub REST API. Injectable fetchImpl for tests.
+// Best-effort: any network/auth failure → [] + an onWarn note (never blocks the adopt).
+async function fetchGitHubIssues({ owner, repo, token, fetchImpl = globalThis.fetch, max = DEFAULT_MAX, onWarn = () => {} }) {
+  if (!owner || !repo || !token || typeof fetchImpl !== 'function') return [];
+  try {
+    const url = `https://api.github.com/repos/${owner}/${repo}/issues?state=open&per_page=${Math.min(max, 100)}`;
+    const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'User-Agent': 'bongos-init-adopt' } });
+    if (!res || !res.ok) { onWarn(`GitHub issues fetch failed (${res ? res.status : 'no response'}) — falling back to a local backlog file`); return []; }
+    return parseGitHubIssues(await res.json()).slice(0, max);
+  } catch (e) {
+    onWarn(`GitHub issues fetch error (${e.message}) — falling back to a local backlog file`);
+    return [];
+  }
+}
+
+// Resolve the backlog from the best available source. Precedence: an EXPLICIT file the
+// owner named → GitHub issues → an auto-detected local file → none. Returns
+// { source, tasks:[{ title, kind, description }], truncated }.
+async function resolveBacklogTasks({ dir, repo = {}, githubToken, backlogFile, fetchImpl, fs = nodeFs, path = nodePath, max = DEFAULT_MAX, onWarn = () => {} } = {}) {
+  const toTasks = (cands) => cands.slice(0, max).map((t) => ({ title: t.title, kind: 'unclassified', description: t.body || '' }));
+  const readParse = (abs) => { try { return parseBacklogFile(fs.readFileSync(abs, 'utf8')); } catch { return []; } };
+
+  // 0. an explicit backlog file the owner named (path relative to dir, or absolute).
+  if (backlogFile) {
+    const abs = path.isAbsolute(backlogFile) ? backlogFile : path.join(dir, backlogFile);
+    const parsed = readParse(abs);
+    if (parsed.length) return { source: backlogFile, tasks: toTasks(parsed), truncated: parsed.length > max };
+    onWarn(`backlog file "${backlogFile}" was empty or unreadable — trying other sources`);
+  }
+
+  // 1. GitHub issues (only when we have both a token and the repo coordinates)
+  if (githubToken && repo.owner && repo.name) {
+    const gh = await fetchGitHubIssues({ owner: repo.owner, repo: repo.name, token: githubToken, fetchImpl, max, onWarn });
+    if (gh.length) return { source: 'github-issues', tasks: toTasks(gh), truncated: gh.length >= max };
+  }
+
+  // 2. local backlog file
+  const file = findBacklogFile(dir, fs, path);
+  if (file) {
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, file), 'utf8'); } catch { /* unreadable → empty */ }
+    const parsed = parseBacklogFile(text);
+    if (parsed.length) return { source: file, tasks: toTasks(parsed), truncated: parsed.length > max };
+  }
+
+  // 3. none — the version + goal + kickoff still seed; the owner captures tasks later
+  return { source: 'none', tasks: [], truncated: false };
+}
+
+module.exports = { parseBacklogFile, findBacklogFile, parseGitHubIssues, fetchGitHubIssues, resolveBacklogTasks, BACKLOG_FILENAMES, DEFAULT_MAX };

package/scripts/bongos/adopt-preflight.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/adopt-preflight.js — the conflict PRE-FLIGHT for `bongos init --adopt`
+// (ADR 0121 §Decision 5 / task 2045). Before adopt writes anything, it reports the
+// blast radius the owner must ACCEPT:
+//   • migration-namespace collisions — a repo migration using core's reserved prefix
+//     (ADR 0108 §5, via migration-namespace.js's canonical filenameViolation).
+//   • core<->host fitness-boundary overlaps — repo dirs that shadow core's reserved
+//     src/bongos or modules/ namespaces the fitness gate scans (ADR 0062 §1).
+//   • protected-path landings — incoming files that fall on the trust-boundary hard
+//     floor (ADR 0043, via gate-review.js's canonical matchesHardFloor).
+//   • CI collisions — the repo's workflows vs core's expected unit/secret-scan/
+//     gate-review checks.
+//   • IGNORED incoming files — a pre-existing .gitignore rule that would swallow what
+//     adopt is about to commit (task 1003881). This is the check that was missing when
+//     Cloud Bongos was adopted onto a repo whose .gitignore already carried `.claude/`:
+//     the skills, hooks and settings.json were materialized onto disk and then dropped
+//     by `git add`, so the adopt commit landed 8 files with no methodology surface at
+//     all. Nothing failed, nothing was logged, and every clone of that repo has been
+//     missing its /builder-* commands since. BLOCKING, because the result is a
+//     non-functional instance that looks fine.
+// READ-ONLY: it computes findings; the accept-gate that decides whether to proceed
+// lives in init.js runAdopt. Pure check functions + a thin fs-reading orchestrator.
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { execFileSync: nodeExecFileSync } = require('node:child_process');
+const { filenameViolation, INSTANCE_NS } = require('./migration-namespace');
+const { matchesHardFloor } = require('./gate-review');
+
+const SEV = { BLOCK: 'blocking', WARN: 'warning', INFO: 'info' };
+const CORE_EXPECTED_CHECKS = ['unit', 'secret-scan', 'gate-review']; // the merge-gate checks core adds
+
+// The files `bongos init --adopt` writes/materializes — the "incoming" set the
+// protected-path check runs against (representative globs; the .claude/ trees expand).
+const INCOMING_PATHS = [
+  'config/branding.json', 'config/modules.json', 'config/hierarchy.json',
+  'package.json', '.claude/settings.json', '.claude/hooks/', '.claude/skills/',
+];
+
+// PURE — repo migration basenames → findings. A basename destined for the INSTANCE
+// namespace that violates the namespace rule (e.g. it uses core's reserved `core_`
+// prefix) would collide with core's migrations on the stem-keyed ledger. Bare-numbered
+// files are valid instance migrations and safe.
+function checkMigrationNamespace(basenames = []) {
+  const findings = [];
+  if (!basenames.length) return findings;
+  const reserved = basenames.filter((b) => filenameViolation(INSTANCE_NS, b));
+  for (const b of reserved) {
+    findings.push({ category: 'migration-namespace', severity: SEV.BLOCK, message: `migration "${b}" uses a reserved (core_/module) prefix — it would collide with core's migration namespace (ADR 0108 §5). Renumber it as a bare instance migration.` });
+  }
+  const bare = basenames.length - reserved.length;
+  if (bare > 0) findings.push({ category: 'migration-namespace', severity: SEV.INFO, message: `${bare} existing migration(s) adopt as the INSTANCE namespace (bare-numbered); core uses the core_ prefix, so there is no stem collision (ADR 0108 §5).` });
+  return findings;
+}
+
+// PURE — repo layout → fitness-boundary findings (ADR 0062 §1). A repo that already
+// has a top-level modules/ or a src/bongos/ shadows the namespaces core's fitness gate
+// scans, so its own files there may be flagged after adoption.
+function checkFitnessBoundary({ topLevelDirs = [], hasSrcBongos = false } = {}) {
+  const findings = [];
+  if (topLevelDirs.includes('modules')) findings.push({ category: 'fitness-boundary', severity: SEV.WARN, message: 'the repo has a top-level `modules/` dir — core\'s fitness gate scans modules/** for the module-import boundary (ADR 0062 §1); your files there may be flagged.' });
+  if (hasSrcBongos) findings.push({ category: 'fitness-boundary', severity: SEV.WARN, message: 'the repo has `src/bongos/` — it shadows core\'s reserved kernel namespace scanned by the fitness gate (ADR 0062 §1).' });
+  if (!findings.length) findings.push({ category: 'fitness-boundary', severity: SEV.INFO, message: 'no overlap with core\'s reserved src/bongos or modules/ namespaces.' });
+  return findings;
+}
+
+// PURE — incoming paths → protected-path findings (ADR 0043). Which files adopt writes
+// land on the trust-boundary hard floor (via gate-review's canonical matcher)?
+function checkProtectedPaths(incoming = INCOMING_PATHS) {
+  const hits = incoming.filter((p) => matchesHardFloor(p));
+  if (!hits.length) return [{ category: 'protected-paths', severity: SEV.INFO, message: 'no incoming files land on protected paths.' }];
+  return [{ category: 'protected-paths', severity: SEV.WARN, message: `adopt materializes ${hits.length} core-governed file(s) on protected paths (ADR 0043): ${hits.join(', ')}. Additive only — but these are under the trust boundary, so treat them as core-managed.` }];
+}
+
+// PURE — the repo's CI workflows ([{ name, content }]) → CI-collision findings. Flags a
+// workflow that already references a core-reserved check name (unit / secret-scan /
+// gate-review); otherwise notes that core will add those checks alongside existing ones.
+function checkCiCollisions(workflows = []) {
+  if (!workflows.length) return [{ category: 'ci', severity: SEV.INFO, message: 'no existing CI workflows — core\'s unit/secret-scan/gate-review checks will be the only ones.' }];
+  const collisions = new Set();
+  for (const wf of workflows) {
+    for (const check of CORE_EXPECTED_CHECKS) {
+      if (new RegExp(`\\b${check.replace(/[-]/g, '\\-')}\\b`, 'i').test(wf.content || '')) collisions.add(`${wf.name} → ${check}`);
+    }
+  }
+  if (collisions.size) return [{ category: 'ci', severity: SEV.WARN, message: `existing CI workflow(s) reference core-reserved check name(s): ${[...collisions].join(', ')}. Core adds unit/secret-scan/gate-review — reconcile names so the merge gate keys on the right job.` }];
+  return [{ category: 'ci', severity: SEV.INFO, message: `${workflows.length} existing CI workflow(s); core will ADD its own unit/secret-scan/gate-review checks alongside them — confirm no required-check conflict.` }];
+}
+
+// PURE — [{ path, rule }] of incoming files a .gitignore rule would swallow → findings.
+// BLOCKING: an ignored incoming file is not a style problem, it is silent data loss at
+// `git add` time, and the instance that results is broken in a way nothing reports.
+function checkIgnoredIncoming(ignored = [], { checked = true } = {}) {
+  if (!checked) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'could not run `git check-ignore` here (no git, or not a repo yet) — cannot confirm the incoming files are committable. Re-check after `git init` if adopt lands nothing under .claude/.' }];
+  }
+  if (!ignored.length) {
+    return [{ category: 'ignored-incoming', severity: SEV.INFO, message: 'no existing ignore rule swallows the files adopt writes — they will all reach the commit.' }];
+  }
+  const lines = ignored.map((i) => (i.rule ? `${i.path} (ignored by ${i.rule})` : i.path));
+  return [{
+    category: 'ignored-incoming',
+    severity: SEV.BLOCK,
+    message: `${ignored.length} file(s) adopt writes are IGNORED by this repo and would be silently dropped from the commit: ${lines.join('; ')}. `
+      + 'Adopt would appear to succeed and produce an instance missing that surface — a repo ignoring `.claude/` gets no /builder-* commands on any clone. '
+      + 'Fix the rule (delete it, or add a negation such as `!.claude/` after it), then re-run.',
+  }];
+}
+
+// Which of `incoming` does this repo's ignore rules match? Uses `git check-ignore -v`,
+// which reports the SOURCE RULE for each match, so the finding can name the exact line
+// the owner has to change rather than leaving them to hunt for it.
+//
+// Returns { ignored:[{path, rule}], checked:boolean }. `checked:false` means the probe
+// could not run at all (no git, not a repo) — deliberately distinct from "nothing is
+// ignored", because the two warrant different advice. execFileSync is injectable for
+// tests; git exits 1 when nothing matches, which is a normal answer and not an error.
+function probeIgnoredIncoming({ dir, incoming = INCOMING_PATHS, execFileSync = nodeExecFileSync } = {}) {
+  // Trailing slashes are ours (they mark dirs in the list); git wants plain pathnames.
+  const paths = incoming.map((p) => String(p).replace(/\/+$/, ''));
+  let out = '';
+  try {
+    out = execFileSync('git', ['check-ignore', '-v', '--stdin'], {
+      cwd: dir, input: paths.join('\n'), encoding: 'utf8', timeout: 5000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }) || '';
+  } catch (err) {
+    // Exit 1 = "no path is ignored" (a real answer, stdout empty). Anything else means
+    // the probe itself could not run.
+    if (err && err.status === 1) return { ignored: [], checked: true };
+    return { ignored: [], checked: false };
+  }
+  const ignored = [];
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    // `<source>:<line>:<pattern>\t<pathname>`
+    const tab = line.lastIndexOf('\t');
+    if (tab === -1) continue;
+    const rule = line.slice(0, tab).trim();
+    const pathname = line.slice(tab + 1).trim();
+    ignored.push({ path: pathname, rule });
+  }
+  return { ignored, checked: true };
+}
+
+// Read the repo (migrations, src/bongos, workflows) and run every check. `stack` is the
+// adopt-detect summary (task 2043); we re-read only what the checks need. Returns
+// { findings, counts:{blocking,warning,info}, hasBlocking }.
+function preflightAdopt({ dir, stack = {}, fs = nodeFs, path = nodePath, execFileSync = nodeExecFileSync } = {}) {
+  const listFiles = (rel) => { try { return fs.readdirSync(path.join(dir, rel)).filter((f) => { try { return fs.statSync(path.join(dir, rel, f)).isFile(); } catch { return false; } }); } catch { return []; } };
+  const exists = (rel) => { try { return fs.existsSync(path.join(dir, rel)); } catch { return false; } };
+
+  // migrations across every detected migrations dir
+  const migrationBasenames = (stack.migrationsDirs || []).flatMap((d) => listFiles(d).filter((f) => /\.sql$/i.test(f)));
+
+  // github workflow contents (only when github-actions was detected)
+  const workflows = [];
+  const gh = (stack.ci || []).find((c) => c.system === 'github-actions');
+  if (gh) {
+    for (const wf of gh.workflows || []) {
+      let content = '';
+      try { content = fs.readFileSync(path.join(dir, '.github/workflows', wf), 'utf8'); } catch { content = ''; }
+      workflows.push({ name: wf, content });
+    }
+  }
+
+  const findings = [
+    ...checkMigrationNamespace(migrationBasenames),
+    ...checkFitnessBoundary({ topLevelDirs: stack.topLevelDirs || [], hasSrcBongos: exists('src/bongos') }),
+    ...checkProtectedPaths(INCOMING_PATHS),
+    ...checkCiCollisions(workflows),
+    ...(() => { const { ignored, checked } = probeIgnoredIncoming({ dir, execFileSync }); return checkIgnoredIncoming(ignored, { checked }); })(),
+  ];
+  const counts = { blocking: 0, warning: 0, info: 0 };
+  for (const f of findings) counts[f.severity === SEV.BLOCK ? 'blocking' : f.severity === SEV.WARN ? 'warning' : 'info']++;
+  return { findings, counts, hasBlocking: counts.blocking > 0 };
+}
+
+// Human-readable report lines (one per finding, severity-marked), for the owner to
+// read before accepting. Returns an array of strings.
+function formatPreflight(report) {
+  const mark = { [SEV.BLOCK]: '✗ BLOCK', [SEV.WARN]: '⚠ warn', [SEV.INFO]: '· ok' };
+  return report.findings.map((f) => `  ${mark[f.severity] || '·'}  [${f.category}] ${f.message}`);
+}
+
+module.exports = { preflightAdopt, formatPreflight, checkMigrationNamespace, checkFitnessBoundary, checkProtectedPaths, checkCiCollisions, checkIgnoredIncoming, probeIgnoredIncoming, INCOMING_PATHS, CORE_EXPECTED_CHECKS, SEV };