@sabaiway/agent-workflow-kit 10.4.0 → 10.5.0

package/tools/orchestration-config.mjs

@@ -22,6 +22,16 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { ACTIVITIES, SLOT_RECIPES } from './recipes.mjs';
 import { refuseDirectRun } from './direct-run.mjs';
+import { validateRoster } from './review-roster.mjs';
+import {
+  CANON_README,
+  KNOWN_PRIOR_README,
+  normalizeCanonical,
+  refreshIfCanonical,
+  refreshReadme,
+} from './orchestration-readme.mjs';
+
+export { CANON_README, KNOWN_PRIOR_README, normalizeCanonical, refreshIfCanonical, refreshReadme };
 
 // The hand-editable / agent-writable, per-project config (strict JSON). cwd-relative — the error prefix
 // uses this rel path so a user sees a path they can open, never an absolute temp/host path.
@@ -242,10 +252,18 @@ export const validateConfig = (config) => {
           `${CONFIG_REL}: unknown slot "${slot}" for activity "${key}" (${key} slots: ${Object.keys(activityDef.slots).join(', ')})`,
         );
       }
+      if (Array.isArray(recipe) && slotType === 'review') {
+        try {
+          validateRoster(recipe);
+        } catch (error) {
+          throw fail(1, `${CONFIG_REL}: invalid review roster for "${key}.${slot}" (${error.message})`);
+        }
+        continue;
+      }
       if (typeof recipe !== 'string' || !(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
         throw fail(
           1,
-          `${CONFIG_REL}: invalid value "${recipe}" for ${slotType} slot of "${key}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
+          `${CONFIG_REL}: invalid value ${JSON.stringify(recipe)} for ${slotType} slot of "${key}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
         );
       }
     }
@@ -338,83 +356,6 @@ export const serializeConfig = (config) => {
   return `${JSON.stringify(ordered, null, 2)}\n`;
 };
 
-// ── canonical-refresh (shared by the _README refresh + the injected-slot refresh) ───
-// normalizeCanonical: trim + LF-normalize (handles the CRLF / trailing-whitespace trap) so a byte-noisy
-// copy of a canonical string still matches. refreshIfCanonical: replace `current` with `next` IFF it
-// normalize-equals ANY known prior canonical; otherwise return `current` UNCHANGED (preserve a
-// customization). Pure; no fs. Used for the orchestration `_README` and the two injected pointers.
-
-export const normalizeCanonical = (s) => String(s).replace(/\r\n/g, '\n').trim();
-
-export const refreshIfCanonical = (current, knownPriorCanonicals, next) => {
-  const cur = normalizeCanonical(current);
-  return knownPriorCanonicals.some((prior) => normalizeCanonical(prior) === cur) ? next : current;
-};
-
-// ── canonical `_README` (drift-guarded, append-only known-prior set) ─────────────────
-// CANON_README is the CURRENT onboarding note — what the templates ship + what a refresh installs. It
-// frames hand-edit as a still-available option AND points at the set-recipe writer (no "never written
-// for you"). KNOWN_PRIOR_README is the APPEND-ONLY set of every PREVIOUS canonical note: any release
-// that changes CANON_README must FIRST append the outgoing string here, so an immediately-previous
-// deployment still normalize-matches and gets refreshed (a customized note never matches → preserved).
-export const CANON_README =
-  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. " +
-  "Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, " +
-  "previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you " +
-  "prefer; that option never goes away. Three activities are configured independently, and so is each slot " +
-  "within them: 'plan-authoring' (slots author, review), 'plan-execution' (slots execute, review) and " +
-  "'routine' (slots carrier, parallel). A slot's value is a recipe: a 'review' slot accepts " +
-  "solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an " +
-  "'execute' slot accepts solo | delegated | subagent (you implement / a backend runs a bounded sub-task / a " +
-  "full-tool frontier subagent carries a bounded slice you verify); the carrier slots 'plan-authoring.author' " +
-  "and 'routine.carrier' accept solo | subagent. 'routine.parallel' is a flag rather than a recipe: it accepts " +
-  "on | off and decides whether file-disjoint subagent slices dispatch concurrently. The default below is " +
-  "'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required. " +
-  "Raise a slot to reviewed or council for a second " +
-  "opinion, or to delegated to hand off execution; those need an execution backend set up first. 'subagent' " +
-  "needs the executor vehicle placed in this project — the composition root's `agents` writer places it; without " +
-  "it the slot resolves to solo with the reason stated. Remove a slot's line, or a whole activity block (or " +
-  "run `set-recipe --unset <activity>.<slot>`), to fall back to the computed default: reviewed when a review " +
-  "backend is ready and otherwise solo for a review slot, solo for author, execute and carrier, on for " +
-  "parallel. Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for " +
-  "your environment. Strict JSON — no comments.";
-
-export const KNOWN_PRIOR_README = [
-  // v1 (pre-set-recipe) — the "Hand-edit this file — it is never written for you" note. APPEND-ONLY.
-  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
-  // v2 (two activities, an `execute` slot without a carrier) — the note that shipped before AD-124.
-  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell " +
-  "the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, " +
-  "and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option " +
-  "never goes away. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is " +
-  "each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you " +
-  "self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | " +
-  "delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no " +
-  "execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand " +
-  "off execution; those need an execution backend set up first. Remove a slot's line (or run `set-recipe --unset " +
-  "<activity>.<slot>`) to fall back to the computed default (reviewed when a review backend is ready, otherwise " +
-  "solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your " +
-  "environment. Strict JSON — no comments.",
-];
-
-// refreshReadme(config) → { config, changed }: refresh ONLY the `_README` value when it normalize-
-// matches a known prior canonical (preserve a customized note untouched); seed it when absent. The
-// stamp-independent config-ensure (kit fallback + memory delegated upgrade paths) uses this so an
-// install-base deployment gains the new note without a migration file — never clobbering a customization.
-export const refreshReadme = (config) => {
-  if (config == null || typeof config !== 'object' || Array.isArray(config)) {
-    return { config, changed: false };
-  }
-  const had = config._README;
-  const nextReadme = had === undefined ? CANON_README : refreshIfCanonical(had, KNOWN_PRIOR_README, CANON_README);
-  if (nextReadme === had) return { config, changed: false };
-  const next = { _README: nextReadme };
-  for (const [k, v] of Object.entries(config)) {
-    if (k !== '_README') next[k] = v;
-  }
-  return { config: next, changed: true };
-};
-
 // The canonical seed file body (what `init` deploys + what serializeConfig round-trips byte-identically).
 export const SEED_CONFIG = { _README: CANON_README, 'plan-authoring': { review: 'solo' }, 'plan-execution': { execute: 'solo', review: 'solo' } };
 

package/tools/orchestration-readme.mjs

@@ -0,0 +1,70 @@
+export const normalizeCanonical = (value) => String(value).replace(/\r\n/gu, '\n').trim();
+
+export const refreshIfCanonical = (current, knownPriorCanonicals, next) => {
+  const normalized = normalizeCanonical(current);
+  return knownPriorCanonicals.some((prior) => normalizeCanonical(prior) === normalized) ? next : current;
+};
+
+const V1_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). " +
+  "The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.";
+
+const V2_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell " +
+  "the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, " +
+  "and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option " +
+  "never goes away. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is " +
+  "each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you " +
+  "self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | " +
+  "delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no " +
+  "execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand " +
+  "off execution; those need an execution backend set up first. Remove a slot's line (or run `set-recipe --unset " +
+  "<activity>.<slot>`) to fall back to the computed default (reviewed when a review backend is ready, otherwise " +
+  "solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your " +
+  "environment. Strict JSON — no comments.";
+
+const V3_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. " +
+  "Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, " +
+  "previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you " +
+  "prefer; that option never goes away. Three activities are configured independently, and so is each slot " +
+  "within them: 'plan-authoring' (slots author, review), 'plan-execution' (slots execute, review) and " +
+  "'routine' (slots carrier, parallel). A slot's value is a recipe: a 'review' slot accepts " +
+  "solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an " +
+  "'execute' slot accepts solo | delegated | subagent (you implement / a backend runs a bounded sub-task / a " +
+  "full-tool frontier subagent carries a bounded slice you verify); the carrier slots 'plan-authoring.author' " +
+  "and 'routine.carrier' accept solo | subagent. 'routine.parallel' is a flag rather than a recipe: it accepts " +
+  "on | off and decides whether file-disjoint subagent slices dispatch concurrently. The default below is " +
+  "'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required. " +
+  "Raise a slot to reviewed or council for a second " +
+  "opinion, or to delegated to hand off execution; those need an execution backend set up first. 'subagent' " +
+  "needs the executor vehicle placed in this project — the composition root's `agents` writer places it; without " +
+  "it the slot resolves to solo with the reason stated. Remove a slot's line, or a whole activity block (or " +
+  "run `set-recipe --unset <activity>.<slot>`), to fall back to the computed default: reviewed when a review " +
+  "backend is ready and otherwise solo for a review slot, solo for author, execute and carrier, on for " +
+  "parallel. Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for " +
+  "your environment. Strict JSON — no comments.";
+
+const ROSTER_README = V3_README.replace(
+  "a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize)",
+  "a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize), or an explicit roster array such as [\"codex-review\", \"agy-review\", \"review-lens\"] in hand-edit form",
+);
+
+export const CANON_README = ROSTER_README
+  .replace("'plan-authoring' (slots author, review)", "'plan-authoring' (slots author, fold, review)")
+  .replace("the carrier slots 'plan-authoring.author' and 'routine.carrier'", "the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier'")
+  .replace('solo for author, execute and carrier', 'solo for author, fold, execute and carrier');
+
+export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README]);
+
+export const refreshReadme = (config) => {
+  if (config == null || typeof config !== 'object' || Array.isArray(config)) return { config, changed: false };
+  const current = config._README;
+  const readme = current === undefined
+    ? CANON_README
+    : refreshIfCanonical(current, KNOWN_PRIOR_README, CANON_README);
+  if (readme === current) return { config, changed: false };
+  const next = { _README: readme };
+  for (const [key, value] of Object.entries(config)) if (key !== '_README') next[key] = value;
+  return { config: next, changed: true };
+};

package/tools/plan-shape-cli.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { plansInFlight, PLANS_REL } from './plan-files.mjs';
+import { buildFacts, openRepo } from './plan-shape-facts.mjs';
+import { checkPlan, checkPlanStructure, formatFindings, parseLedger, PLAN_TITLE_PREFIX, verifyPlan } from './plan-shape.mjs';
+
+const USAGE = `Usage:
+  node plan-shape-cli.mjs --check <plan>
+  node plan-shape-cli.mjs --verify <plan>
+  node plan-shape-cli.mjs --check --in-flight
+  node plan-shape-cli.mjs --verify --in-flight`;
+
+const readPlan = (path) => {
+  const result = readRegularFileNoFollow(path);
+  if (result.outcome !== 'ok') throw new Error(`${path} must be a readable regular plan file (${result.className ?? result.code ?? result.outcome})`);
+  return result.content;
+};
+
+const readPlanEntries = (cwd) => {
+  try {
+    return readdirSync(join(cwd, PLANS_REL), { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw new Error(`${PLANS_REL} could not be read (${error?.code ?? 'fs error'})`);
+  }
+};
+
+const getPaths = (text) => {
+  try {
+    const rows = parseLedger(text).rows.filter((row) => row.valid);
+    return [...rows.map((row) => row.path), ...rows.map((row) => row.anchorPath).filter(Boolean)];
+  } catch {
+    return [];
+  }
+};
+
+const isPlanShape = (text) => {
+  try {
+    const first = tokenizeMarkdown(text, 'the in-flight document').headings[0];
+    return Boolean(first && first.level === 1 && first.text.startsWith(PLAN_TITLE_PREFIX));
+  } catch {
+    return true;
+  }
+};
+
+const writeLine = (write, line) => write(`${line}\n`);
+
+// A facts failure scoped to the plan's own paths is that plan's listed finding, so the other plans
+// are still judged; a repository-level refusal (the practice, a package, its pins) keeps its usage class.
+const buildPlanFacts = (cwd, repo, text) => {
+  try {
+    return { facts: buildFacts(cwd, { paths: getPaths(text), repo }) };
+  } catch (error) {
+    if (error?.scope !== 'plan') throw error;
+    return { findings: [{ line: 1, code: 'facts', message: error.message, rowId: null }], skips: [] };
+  }
+};
+
+const judgeWith = (cwd, repo, text, rules) => {
+  const built = buildPlanFacts(cwd, repo, text);
+  return built.facts ? rules(text, built.facts) : built;
+};
+
+const runExplicit = (cwd, arm, operand, write) => {
+  const text = readPlan(resolve(cwd, operand));
+  const result = judgeWith(cwd, openRepo(cwd), text, arm === '--check' ? checkPlan : verifyPlan);
+  writeLine(write, formatFindings(result, operand));
+  return result.findings.length === 0 ? 0 : 1;
+};
+
+const runInFlight = (cwd, write) => {
+  const entries = readPlanEntries(cwd);
+  const names = plansInFlight(cwd, () => entries);
+  const documents = names.map((name) => {
+    const label = `${PLANS_REL}/${name}`;
+    return { label, text: readPlan(resolve(cwd, label)) };
+  });
+  const judged = documents.filter((document) => isPlanShape(document.text));
+  const repo = openRepo(cwd);
+  const results = judged.map((document) => {
+    const result = judgeWith(cwd, repo, document.text, checkPlanStructure);
+    writeLine(write, formatFindings(result, document.label));
+    return result;
+  });
+  writeLine(write, `plan-shape: judged plans: ${judged.length}`);
+  writeLine(write, `plan-shape: skipped by shape: ${documents.length - judged.length}`);
+  return results.some((result) => result.findings.length > 0) ? 1 : 0;
+};
+
+export const main = (argv = process.argv.slice(2), io = {}) => {
+  const cwd = io.cwd ?? process.cwd();
+  const stdout = io.stdout ?? ((text) => process.stdout.write(text));
+  const stderr = io.stderr ?? ((text) => process.stderr.write(text));
+  const [arm, operand, ...rest] = argv;
+  if (!['--check', '--verify'].includes(arm) || !operand || rest.length > 0) {
+    writeLine(stderr, USAGE);
+    return 2;
+  }
+  try {
+    return operand === '--in-flight' ? runInFlight(cwd, stdout) : runExplicit(cwd, arm, operand, stdout);
+  } catch (error) {
+    writeLine(stderr, `plan-shape: ${error.message}`);
+    return 2;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main();

package/tools/plan-shape-facts.mjs

@@ -0,0 +1,204 @@
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { segmentPrefixOf, validateSourceSizeConfig } from './source-size-config.mjs';
+import { getLineCount, isSweep, resolveAnchorCandidates, unique } from './plan-shape.mjs';
+
+const SOURCE_SIZE_REL = 'docs/ai/source-size.json';
+const PACKAGE_FILE = 'package.json';
+const PIN_FILE = 'package-content.test.mjs';
+const EXCLUDED_DIRECTORIES = new Set(['.git', 'node_modules']);
+const NEGATED_CLASS = /\[[!^]/;
+const UNSUPPORTED_GLOB = /[()\\\u0000-\u001f]/;
+
+const usageError = (message, scope = 'repository') => Object.assign(new Error(message), { exitCode: 2, scope });
+const planError = (message) => usageError(message, 'plan');
+const toPosix = (path) => path.split(sep).join('/');
+const isInside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const isLexicallySafe = (path) => typeof path === 'string' && path.length > 0 && !isAbsolute(path) &&
+  !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..');
+
+const getLstat = (path, fail = usageError) => {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw fail(`cannot inspect ${path} (${error.message})`);
+  }
+};
+
+const walkRegularFiles = (root, directory = root) => readdirSync(directory, { withFileTypes: true })
+  .sort((left, right) => left.name.localeCompare(right.name))
+  .flatMap((entry) => {
+    const path = join(directory, entry.name);
+    const rel = toPosix(relative(root, path));
+    if (entry.isDirectory() && !EXCLUDED_DIRECTORIES.has(entry.name)) return walkRegularFiles(root, path);
+    return entry.isFile() ? [rel] : [];
+  });
+
+const getRealpath = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+const resolveAbsentLeaf = (root, path) => {
+  const rootReal = realpathSync(root);
+  const lexical = resolve(root, path);
+  if (!isInside(resolve(root), lexical)) return { contained: false, resolved: lexical };
+  const findExisting = (candidate, missing) => {
+    const real = getLstat(candidate, planError) ? getRealpath(candidate) : null;
+    if (real) return join(real, ...missing);
+    const parent = dirname(candidate);
+    if (parent === candidate) return candidate;
+    return findExisting(parent, [basename(candidate), ...missing]);
+  };
+  const resolved = findExisting(lexical, []);
+  return { contained: isInside(rootReal, resolved), resolved };
+};
+
+const readJsonNoFollow = (path, label) => {
+  const result = readRegularFileNoFollow(path);
+  if (result.outcome === 'absent') return null;
+  if (result.outcome !== 'ok') throw usageError(`${label} must be a readable regular file (${result.className ?? result.code ?? result.outcome})`);
+  try {
+    const parsed = JSON.parse(result.content);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('the root is not an object');
+    return parsed;
+  } catch (error) {
+    throw usageError(`${label} is not valid JSON (${error.message})`);
+  }
+};
+
+const loadPractice = (root) => {
+  const parsed = readJsonNoFollow(join(root, SOURCE_SIZE_REL), SOURCE_SIZE_REL);
+  if (parsed === null) return { capDeclared: false, cap: null, config: null };
+  try {
+    const config = validateSourceSizeConfig(parsed);
+    return { capDeclared: true, cap: config.defaults.maxLines, config };
+  } catch (error) {
+    throw usageError(`${SOURCE_SIZE_REL} is malformed (${error.message})`);
+  }
+};
+
+const isInScope = (path, config) => Boolean(config &&
+  config.roots.some((root) => segmentPrefixOf(root, path)) &&
+  !config.exclude.some((excluded) => segmentPrefixOf(excluded, path)) &&
+  config.extensions.some((extension) => path.endsWith(extension)));
+
+const expandBraces = (pattern) => {
+  const match = /\{([^{}]+)\}/.exec(pattern);
+  if (!match) return [pattern];
+  return match[1].split(',').flatMap((part) => expandBraces(`${pattern.slice(0, match.index)}${part}${pattern.slice(match.index + match[0].length)}`));
+};
+
+const compileGlob = (pattern) => {
+  if (UNSUPPORTED_GLOB.test(pattern) || NEGATED_CLASS.test(pattern) || /\{[^}]*$|^[^{]*\}/.test(pattern)) return null;
+  try {
+    const alternatives = expandBraces(pattern).map((entry) => entry
+      .replace(/[.+^$|]/g, '\\$&')
+      .replace(/\*\*\//g, '\u0002')
+      .replace(/\*\*/g, '\u0001')
+      .replace(/\*/g, '[^/]*')
+      .replace(/\?/g, '[^/]')
+      .replace(/\u0002/g, '(?:.*/)?')
+      .replace(/\u0001/g, '.*'));
+    return new RegExp(`^(?:${alternatives.join('|')})$`);
+  } catch {
+    return null;
+  }
+};
+
+const matchFilesEntry = (entry, ownedPath) => {
+  const normalized = entry.replace(/^\.\//, '').replace(/\/$/, '');
+  if (normalized === '' || normalized === '.') return { known: true, matches: true };
+  if (!isSweep(normalized)) return { known: true, matches: ownedPath === normalized || ownedPath.startsWith(`${normalized}/`) };
+  const compiled = compileGlob(normalized);
+  return compiled ? { known: true, matches: compiled.test(ownedPath) } : { known: false, matches: false };
+};
+
+const getShipped = (packageJson, ownedPath) => {
+  if (packageJson.private === true) return false;
+  if (!Object.hasOwn(packageJson, 'files')) return true;
+  if (!Array.isArray(packageJson.files) || packageJson.files.some((entry) => typeof entry !== 'string')) return 'unknown';
+  return packageJson.files.reduce((state, rawEntry) => {
+    const excluded = rawEntry.startsWith('!');
+    const entry = excluded ? rawEntry.slice(1) : rawEntry;
+    const result = matchFilesEntry(entry, ownedPath);
+    if (!result.known) return 'unknown';
+    return result.matches ? !excluded : state;
+  }, false);
+};
+
+const findPackage = (root, path, cache) => {
+  const start = resolve(root, dirname(path));
+  const visit = (directory) => {
+    if (!isInside(resolve(root), directory)) return null;
+    const packagePath = join(directory, PACKAGE_FILE);
+    if (getLstat(packagePath)) {
+      const relRoot = toPosix(relative(root, directory)) || '.';
+      if (!cache.has(relRoot)) cache.set(relRoot, readJsonNoFollow(packagePath, toPosix(relative(root, packagePath))));
+      return { root: relRoot, json: cache.get(relRoot) };
+    }
+    return directory === resolve(root) ? null : visit(dirname(directory));
+  };
+  return visit(start);
+};
+
+const getPin = (root, owner, repoFiles, cache) => {
+  const prefix = owner.root === '.' ? '' : `${owner.root}/`;
+  const pins = repoFiles.filter((path) => path.startsWith(prefix) && basename(path) === PIN_FILE &&
+    findPackage(root, path, cache)?.root === owner.root);
+  if (pins.length > 1) throw usageError(`package ${owner.root} has several ${PIN_FILE} files: ${pins.join(', ')}`);
+  return pins[0] ?? null;
+};
+
+const describePinSkip = (owner, shipped, pinTest) => {
+  if (owner === null) return 'package ownership is unknown';
+  if (owner.json.private === true) return `private package ${owner.root}`;
+  if (shipped === 'unknown') return `shipping state is unknown for package ${owner.root}`;
+  return shipped === true && pinTest === null ? `no ${PIN_FILE} under package ${owner.root}` : null;
+};
+
+const describePath = (root, path, practice, repoFiles, packageCache) => {
+  const safe = isLexicallySafe(path);
+  const containment = safe ? resolveAbsentLeaf(root, path) : { contained: false, resolved: resolve(root, path) };
+  const stat = safe ? getLstat(resolve(root, path), planError) : null;
+  const read = stat?.isFile() ? readRegularFileNoFollow(resolve(root, path)) : null;
+  if (read && read.outcome !== 'ok') throw planError(`${path} cannot be read without following it (${read.className ?? read.code ?? read.outcome})`);
+  const kind = stat === null ? 'absent' : stat.isFile() ? 'regular' : 'other';
+  const owner = safe && containment.contained && !isSweep(path) ? findPackage(root, path, packageCache) : null;
+  const ownedPath = owner ? toPosix(relative(owner.root === '.' ? root : join(root, owner.root), resolve(root, path))) : null;
+  const shipped = owner ? getShipped(owner.json, ownedPath) : 'unknown';
+  const pinTest = owner && shipped === true ? getPin(root, owner, repoFiles, packageCache) : null;
+  return {
+    kind,
+    lines: read?.outcome === 'ok' ? getLineCount(read.content) : 0,
+    recordedLines: practice.config?.baseline?.[path]?.lines ?? null,
+    inScope: isInScope(path, practice.config),
+    shipped,
+    pinTest,
+    pinSkip: describePinSkip(owner, shipped, pinTest),
+    contained: containment.contained,
+  };
+};
+
+export const openRepo = (root) => {
+  const repoRoot = realpathSync(root);
+  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), packageCache: new Map() };
+};
+
+export const buildFacts = (root, { paths = [], repo = openRepo(root) } = {}) => {
+  const { repoRoot, repoFiles, practice, packageCache } = repo;
+  const expansions = Object.fromEntries(paths.filter(isSweep).map((pattern) => {
+    const compiled = compileGlob(pattern);
+    if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
+    return [pattern, repoFiles.filter((path) => compiled.test(path))];
+  }));
+  const allPaths = unique([...paths, ...Object.values(expansions).flat()]);
+  const pathFacts = Object.fromEntries(allPaths.map((path) => [path, describePath(repoRoot, path, practice, repoFiles, packageCache)]));
+  const candidates = (suffix, precedingPaths = []) => resolveAnchorCandidates(repoFiles, suffix, precedingPaths);
+  return { capDeclared: practice.capDeclared, cap: practice.cap, pathFacts, expansions, repoFiles, candidates };
+};