@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/verification/registry.js

@@ -0,0 +1,130 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The registry-driven layer's own registry: loads and validates `core/registry/verification.json`
+ * (plan task C.2, design C7) into the shape `VerificationEngine` (in `verification.js`) compiles
+ * contracts against.
+ *
+ * Validation is deliberately strict and throws rather than degrading: a registry that half-loads
+ * produces a gate that verifies half of what it claims, which is the failure mode the whole
+ * verification module exists to prevent.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const { parseYamlFile } = require('../capability-router.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const REGISTRY_FILENAME = 'verification.json';
+
+/** Tier-level outcomes. `UNRESOLVED` is the load-bearing one: it says "this tier was required and
+ * nothing was evaluated for it", and it is what keeps a report off PASS. */
+const TIER_RESOLUTIONS = Object.freeze([
+  'RESOLVED',
+  'UNRESOLVED',
+  'SUBSUMED',
+  'NOT_APPLICABLE',
+  'SKIPPED',
+]);
+
+const TIER_STATUSES = Object.freeze([
+  'PASS',
+  'FAIL',
+  'UNRESOLVED',
+  'SUBSUMED',
+  'NOT_APPLICABLE',
+  'SKIPPED',
+  'NOT_RUN',
+]);
+
+/** Outcomes of a bounded recovery loop. */
+const RECOVERY_OUTCOMES = Object.freeze([
+  'PASS',
+  'ABORTED',
+  'NO_CHANGE',
+  'NO_PROGRESS',
+  'NO_REMEDIATION',
+]);
+
+function assert(condition     , message        )       {
+  if (!condition) throw new Error(`verification.json is invalid: ${message}`);
+}
+
+/**
+ * Loads and validates the verification registry.
+ *
+ * Validation is deliberately strict and throws rather than degrading: a registry that half-loads
+ * produces a gate that verifies half of what it claims, which is the failure mode this whole module
+ * exists to prevent.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.repoRoot]
+ * @param {string} [options.registryDir]
+ * @param {string} [options.registryPath]
+ * @param {Object} [options.registry] pre-parsed registry, bypassing the filesystem (test seam)
+ * @param {Object} [options.fsImpl]
+ * @returns {Object} the validated registry
+ */
+function loadVerificationRegistry(options      = {})      {
+  let data = options.registry;
+  if (!data) {
+    const repoRoot = options.repoRoot || REPO_ROOT;
+    const registryDir = options.registryDir || path.join(repoRoot, 'core', 'registry');
+    const registryPath = options.registryPath || path.join(registryDir, REGISTRY_FILENAME);
+    data = parseYamlFile(registryPath, options.fsImpl || nodeFs);
+  }
+
+  assert(data && typeof data === 'object', 'root must be an object');
+  assert(Array.isArray(data.tiers) && data.tiers.length > 0, 'tiers must be a non-empty array');
+  assert(data.riskLevels && typeof data.riskLevels === 'object', 'riskLevels must be an object');
+
+  const policy = data.policy || {};
+  // FR-009 states this as a MUST, so it is enforced at load rather than trusted at call sites.
+  assert(policy.modelReviewIsPrimaryProof === false, 'policy.modelReviewIsPrimaryProof must be false');
+
+  const seen = new Set        ();
+  let previousOrder = -Infinity;
+  let lastNonModelOrder = -Infinity;
+  let firstModelOrder = Infinity;
+
+  for (const tier of data.tiers) {
+    assert(tier && typeof tier.id === 'string' && tier.id !== '', 'every tier needs an id');
+    assert(!seen.has(tier.id), `duplicate tier id '${tier.id}'`);
+    seen.add(tier.id);
+    assert(Number.isFinite(tier.order), `tier '${tier.id}' needs a numeric order`);
+    assert(tier.order > previousOrder, `tier '${tier.id}' is declared out of order; tiers must be listed cheapest-first`);
+    previousOrder = tier.order;
+    if (tier.modelBased) {
+      firstModelOrder = Math.min(firstModelOrder, tier.order);
+      assert(tier.canEstablishPass === false, `model-based tier '${tier.id}' must declare canEstablishPass: false`);
+    } else {
+      lastNonModelOrder = Math.max(lastNonModelOrder, tier.order);
+    }
+  }
+  // "Deterministic checks MUST run before any model-based review" (FR-009) is a structural property
+  // of the registry, so it is checkable here instead of being re-asserted in prose.
+  assert(firstModelOrder > lastNonModelOrder, 'every model-based tier must be ordered after every deterministic tier');
+
+  for (const [level, def] of Object.entries(data.riskLevels)                   ) {
+    assert(def && Array.isArray(def.requiredTiers), `risk level '${level}' needs requiredTiers`);
+    for (const id of def.requiredTiers.concat(def.advisoryTiers || [])) {
+      assert(seen.has(id), `risk level '${level}' references unknown tier '${id}'`);
+    }
+    assert(
+      Number.isInteger(def.maxRecoveryIterations) && def.maxRecoveryIterations > 0,
+      `risk level '${level}' needs a positive integer maxRecoveryIterations`,
+    );
+  }
+
+  return data;
+}
+
+module.exports = {
+  loadVerificationRegistry,
+  TIER_RESOLUTIONS,
+  TIER_STATUSES,
+  RECOVERY_OUTCOMES,
+  REGISTRY_FILENAME,
+};

package/src/runtime/verification/scope-bound.js

@@ -0,0 +1,418 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { resolveActiveFeature } = require('../feature-resolve.js');
+const { resolveBashHelper } = require('../../helper/bash-helper.js');
+const { listCheckouts } = require('../checkouts.js');
+
+// The change-scope bound of a planned feature, and the baseline a change is measured from
+// (feature 045, IC-003 / IC-004).
+//
+// The change-scope tier compares what a change touched against a bound declared before
+// implementation. Nothing declared one, so the tier read UNRESOLVED for every feature. The plan
+// already names the files each task will touch, so the bound is derived from it; there is no
+// extra step an agent has to remember.
+
+/** `- [ ] A.1 ...` / `- [x] B.2 ...`: a checklist task line, as plan.md writes them. */
+const TASK_LINE = /^\s*-\s*\[[ xX]\]\s+[A-Za-z]+\.\d+\b/;
+
+/** `files:` (any case) as a field of its own: at the start of the line, after whitespace or after a `;`. A word
+ * that merely ends in it (`profiles:`) is not the field. */
+const FILES_FIELD = /(?:^|[;\s])files:/gi;
+
+/** A `files:` value that says the task touches no file: `none`, alone or followed by an aside. */
+const NONE_FIELD = /^none(?=$|[\s(;,`])/i;
+
+/**
+ * Paths a plan's task lines name after `files:`, in order, without duplicates.
+ *
+ * The field is the last `files:` on the task line (a description may mention the word earlier). It
+ * runs to the next `;` or the end of the line; a list that ends with `,` continues on the next
+ * indented line, which is how a long list is wrapped.
+ * @param {string} planText
+ * @returns {Array<string>}
+ */
+function taskFilesFromPlan(planText     )           {
+  const lines = String(planText || '').split('\n');
+  const paths           = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!TASK_LINE.test(lines[i])) continue;
+    let at = -1;
+    for (const m of lines[i].matchAll(FILES_FIELD)) at = (m.index          ) + m[0].length;
+    if (at === -1) continue;
+    let rest = lines[i].slice(at);
+    // `files: none (...)` states that a task changes no file; its words are not paths.
+    if (NONE_FIELD.test(rest.trim().replace(/^`+/, ''))) continue;
+    for (;;) {
+      const semicolon = rest.indexOf(';');
+      const field = semicolon === -1 ? rest : rest.slice(0, semicolon);
+      for (const raw of field.split(',')) {
+        // A leading `./` is the same path: changed files are reported without it.
+        const entry = raw.trim().replace(/^`+|`+$/g, '').trim().replace(/^(\.\/)+/, '');
+        if (entry) paths.push(entry);
+      }
+      const wraps = semicolon === -1 && field.trimEnd().endsWith(',')
+        && i + 1 < lines.length && /^\s+\S/.test(lines[i + 1]) && !TASK_LINE.test(lines[i + 1]);
+      if (!wraps) break;
+      i += 1;
+      rest = lines[i];
+    }
+  }
+  return [...new Set(paths)];
+}
+
+const folderOf = (slug               ) => (slug ? `agent-docs/doflow/${slug}/` : null);
+
+function isFile(file        )          {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDirectory(dir        )          {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Why no other checkout was consulted, in the words a reason text lists. */
+function noMainCheckout(checkouts     )         {
+  if (!checkouts.ok) {
+    if (checkouts.reason === 'not-a-git-repository') return 'not a git repository';
+    if (checkouts.reason === 'git-unavailable') return 'git is not available';
+    return `git worktree list failed: ${checkouts.detail || 'no detail'}`;
+  }
+  if (checkouts.sandbox) return 'a DoFlow sandbox sees no other checkout';
+  if (checkouts.mainReason === 'bare') return 'the repository is bare';
+  if (checkouts.mainReason === 'missing') return 'the main checkout no longer exists';
+  return 'this directory is the main checkout';
+}
+
+/**
+ * The plan that bounds a change, taken from stated sources in a stated order: `--plan-path`, else
+ * the feature folder in this checkout, else that folder in the main checkout when this is a linked
+ * worktree. The first folder that exists wins, an explicit slug is never replaced by the branch's,
+ * and a named plan that does not exist stops the search rather than falling through to a guess.
+ * Every source consulted is listed in `searched`. Reads files and copies nothing.
+ * @param {Object} options
+ * @param {string} options.projectRoot
+ * @param {string|null} [options.slug]
+ * @param {string|null} [options.planPath] as the caller wrote it, relative to projectRoot
+ * @param {Function} [options.exec] spawnSync-compatible, for the one `git worktree list`
+ * @returns {{plan: string|null, planRel: string|null, origin: string|null, root: string|null, slug: string|null,
+ *   folderRel: string|null, hasRegister: boolean, searched: Array<{place: string, result: string}>, reason: string|null}}
+ */
+function resolvePlanSource({ projectRoot, slug = null, planPath = null, exec = spawnSync }   
+                      
+                       
+                           
+             
+ )      {
+  const searched        = [];
+  const result = (fields     ) => ({
+    plan: null, planRel: null, origin: null, root: null, slug: null, folderRel: null, hasRegister: false, searched, reason: null, ...fields,
+  });
+  const resolve = (s               ) => {
+    try {
+      return resolveActiveFeature({ projectRoot, slug: s });
+    } catch (error     ) {
+      return { error: 'resolver-failed', message: `could not run the feature resolver: ${error.message}` };
+    }
+  };
+
+  if (planPath) {
+    const abs = path.resolve(projectRoot, planPath);
+    const exists = isFile(abs);
+    searched.push({ place: `--plan-path ${planPath}`, result: exists ? 'found' : 'does not exist' });
+    if (!exists) return result({ planRel: planPath, origin: 'plan-path', reason: 'plan-path-missing' });
+    // The flag is its own opt-in: no register is needed for a plan the caller named.
+    let s = slug;
+    if (!s) {
+      const branch = resolve(null);
+      if (!branch.error && branch.paths && branch.paths.feature_slug) s = branch.paths.feature_slug;
+    }
+    const parent = path.dirname(abs);
+    if (!s && path.dirname(parent).split(path.sep).slice(-2).join('/') === 'agent-docs/doflow') s = path.basename(parent);
+    return result({ plan: abs, planRel: planPath, origin: 'plan-path', slug: s || null, folderRel: folderOf(s), hasRegister: true });
+  }
+
+  const found = resolve(slug);
+  if (found.error || !found.paths || !found.paths.feature_slug) {
+    searched.push({ place: 'this checkout', result: found.message || 'the feature resolver named no feature' });
+    return result({ reason: 'no-feature' });
+  }
+  const s = found.paths.feature_slug;
+  const folderRel = folderOf(s);
+  const withFolder = (fields     ) => {
+    const plan = path.resolve(fields.root, fields.planRel);
+    let reason = null;
+    if (!isFile(plan)) reason = 'no-plan';
+    else if (!fields.hasRegister) reason = 'no-register';
+    return result({ ...fields, plan, slug: s, folderRel, reason });
+  };
+
+  const here = isDirectory(found.featureDir);
+  searched.push({ place: `this checkout ${found.repoRoot}`, result: here ? `${folderRel} found` : `no ${folderRel}` });
+  if (here) {
+    return withFolder({
+      origin: 'current-checkout', root: found.repoRoot, planRel: found.paths.plan || `${folderRel}plan.md`, hasRegister: found.paths.has_decisions === true,
+    });
+  }
+
+  const checkouts = listCheckouts({ cwd: projectRoot, exec });
+  if (!checkouts.isLinked) {
+    searched.push({ place: 'main checkout', result: noMainCheckout(checkouts) });
+    return result({ slug: s, folderRel, reason: 'none' });
+  }
+  const folder = path.join(checkouts.main, 'agent-docs', 'doflow', s);
+  const there = isDirectory(folder);
+  searched.push({ place: `main checkout ${checkouts.main}`, result: there ? `${folderRel} found` : `no ${folderRel}` });
+  if (!there) return result({ slug: s, folderRel, reason: 'none' });
+  return withFolder({
+    origin: 'main-checkout', root: checkouts.main, planRel: `${folderRel}plan.md`, hasRegister: isFile(path.join(folder, 'decisions', 'register.json')),
+  });
+}
+
+/** Why a declared-scope token is refused, or null when it is a repository-relative path. */
+function refusedToken(token        )                {
+  if (token === '') return 'it is empty';
+  if (/[\s\\\0]/.test(token)) return 'it contains whitespace';
+  if (token.startsWith('/') || token.startsWith('~') || /^[A-Za-z]:/.test(token)) return 'it is absolute';
+  if (token === '.') return 'it names the whole repository';
+  const segments = token.split('/');
+  if (segments[segments.length - 1] === '') segments.pop();
+  if (segments.some((seg) => seg === '.' || seg === '..')) return 'it climbs out with ..';
+  return null;
+}
+
+/**
+ * A declared scope: one comma-separated list of repository-relative paths, a trailing `/` meaning
+ * a directory. One refused token refuses the whole text, so a typo never shrinks the bound
+ * silently. Duplicates are dropped and order is kept.
+ * @param {string} text
+ * @returns {{paths: Array<string>, reason: null}|{paths: null, reason: string}}
+ */
+function parseDeclaredScope(text     )      {
+  const paths           = [];
+  for (const raw of String(text).trim().split(',')) {
+    const written = raw.trim();
+    const token = written.replace(/^(\.\/)+/, '');
+    // `./` alone strips to nothing, but what it names is the repository root, not an empty entry.
+    const why = written !== '' && token === '' ? 'it names the whole repository' : refusedToken(token);
+    if (why) return { paths: null, reason: `'${written}' is not a repository-relative path: ${why}` };
+    if (!paths.includes(token)) paths.push(token);
+  }
+  return { paths, reason: null };
+}
+
+/**
+ * The change-scope bound: the plan's task files plus its feature folder, unioned with a declared
+ * scope, plan entries first. Neither narrows the other, and nothing is derived from the changed
+ * files. With neither, `bound` is null and `reason` is the first source that failed.
+ * @param {Object} options
+ * @param {string} options.projectRoot
+ * @param {string|null} [options.slug]
+ * @param {string|null} [options.planPath]
+ * @param {{paths: Array<string>, origin: 'verify-flag'|'readiness-record', record?: string}|null} [options.declared]
+ * @param {Function} [options.exec]
+ * @returns {{bound: Object|null, reason: string|null, searched: Array<Object>, planSource: Object}}
+ */
+function resolveScopeBound({ projectRoot, slug = null, planPath = null, declared = null, baselineRef = null, exec = spawnSync }   
+                      
+                       
+                           
+                 
+                              
+             
+ )      {
+  const planSource = resolvePlanSource({ projectRoot, slug, planPath, exec });
+  let reason = planSource.reason;
+  const allowed           = [];
+  const sources        = [];
+  if (reason === null) {
+    let text                = null;
+    try {
+      text = fs.readFileSync(planSource.plan, 'utf8');
+    } catch {
+      reason = 'no-plan';
+    }
+    const files = text === null ? [] : taskFilesFromPlan(text);
+    if (text !== null && files.length === 0) reason = 'no-task-files';
+    if (files.length > 0) {
+      allowed.push(...files);
+      if (planSource.folderRel) allowed.push(planSource.folderRel);
+      sources.push({ kind: 'plan', path: planSource.planRel, origin: planSource.origin, root: planSource.root });
+    }
+  }
+  if (declared && Array.isArray(declared.paths) && declared.paths.length > 0) {
+    allowed.push(...declared.paths);
+    sources.push({ kind: 'declared', paths: [...declared.paths], origin: declared.origin, ...(declared.record ? { record: declared.record } : {}) });
+  }
+
+  let baseline      = null;
+  if (baselineRef !== null && baselineRef !== undefined) {
+    const res = resolveExplicitBaseline({ cwd: projectRoot, ref: baselineRef, exec });
+    if (!res.ok) {
+      return {
+        bound: null,
+        reason: 'baseline-invalid',
+        unresolvedReason: `change-scope: ${res.reason}. Nothing was changed.`,
+        searched: planSource ? planSource.searched : [],
+        planSource,
+      };
+    }
+    baseline = res;
+  }
+
+  if (allowed.length === 0) return { bound: null, reason, searched: planSource.searched, planSource };
+  const source = sources[0].kind === 'plan' ? planSource.planRel : (declared.record || '--scope');
+  return {
+    bound: {
+      allowedPaths: [...new Set(allowed)],
+      source,
+      sources,
+      ...(baseline ? { baseline: 'explicit', baselineRef: baseline.ref, baselineSha: baseline.sha } : { baseline: 'integration' }),
+    },
+    reason: null,
+    searched: planSource.searched,
+    planSource,
+  };
+}
+
+/**
+ * The bound a plan declares, as 1.21.0 returned it: `{allowedPaths, source}`, or null.
+ * @param {Object} options
+ * @param {string} options.projectRoot
+ * @param {string|null} [options.slug]
+ * @returns {{allowedPaths: Array<string>, source: string}|null}
+ */
+function buildScopeBound({ projectRoot, slug = null }                                               )      {
+  const { bound } = resolveScopeBound({ projectRoot, slug });
+  return bound ? { allowedPaths: bound.allowedPaths, source: bound.source } : null;
+}
+
+function originText(origin               , root               )         {
+  if (origin === 'main-checkout') return `main checkout ${root}`;
+  if (origin === 'plan-path') return '--plan-path';
+  return 'current checkout';
+}
+
+/**
+ * The change-scope tier's reason when nothing bounds the change: where was looked and the command
+ * that bounds it.
+ * @param {Object} options
+ * @param {string} options.reason a `resolveScopeBound` reason
+ * @param {string} options.taskId
+ * @param {Object} options.planSource the `resolvePlanSource` result
+ * @returns {string}
+ */
+function scopeReasonText({ reason, taskId, planSource }                                                     )         {
+  const places = planSource.searched.map((s     ) => `${s.place}: ${s.result}`).join('; ');
+  const where = `${planSource.folderRel} (${originText(planSource.origin, planSource.root)})`;
+  switch (reason) {
+    case 'no-plan':
+      return `change-scope: the feature folder ${where} has no plan.md, so nothing bounds this change. Looked in: ${places}. Pass --scope <path>[,<path>...] or --plan-path <plan.md>. Nothing was changed.`;
+    case 'no-register':
+      return `change-scope: the feature folder ${where} has no decisions/register.json, so its plan bounds nothing (features from before the register keep that behaviour). Pass --scope <path>[,<path>...] or --plan-path <plan.md> to bound this change. Nothing was changed.`;
+    case 'no-task-files':
+      return `change-scope: ${planSource.planRel} names no files: in any task, so it bounds nothing. Add files: to its tasks or pass --scope <path>[,<path>...]. Nothing was changed.`;
+    case 'plan-path-missing':
+      return `change-scope: --plan-path ${planSource.planRel} does not exist; no other source is consulted when a plan is named. Pass an existing plan.md or drop --plan-path. Nothing was changed.`;
+    default:
+      return `change-scope: no plan or declared scope bounds this change. Looked in: ${places}. A change with no plan needs a declared scope: doflow-run verify --task-id ${taskId} --scope <path>[,<path>...] (a trailing / is a directory); to use a plan, pass --plan-path <plan.md> or --slug <feature>. Nothing was changed.`;
+  }
+}
+
+/**
+ * Where a resolved bound came from, as the `bound:` line prints it.
+ * @param {Array<Object>} sources a bound's `sources`
+ * @returns {string}
+ */
+function boundSourcesText(sources       )         {
+  return sources.map((s     ) => (s.kind === 'plan'
+    ? `plan ${s.path} (${originText(s.origin, s.root)})`
+    : `declared ${s.paths.join(',')} (${s.origin === 'readiness-record' ? `readiness record ${s.record}` : '--scope'})`)).join(' + ');
+}
+
+/**
+ * The commit a change is measured from: the merge base of HEAD and the integration ref that
+ * `do-git-state.sh` reports. `{ref, mergeBase}` when it resolves, else `{reason, note?}` saying why not;
+ * `note` is the tier detail when the reason has wording of its own (a missing integration branch).
+ * @param {Object} options
+ * @param {string} options.cwd
+ * @param {Function} [options.exec] spawnSync-compatible
+ * @returns {{ref: string, mergeBase: string}|{reason: string}}
+ */
+function resolveIntegrationBase({ cwd, exec = spawnSync }                             )      {
+  const run = (cmd        , args          ) => {
+    try {
+      return exec(cmd, args, { cwd, encoding: 'utf8', timeout: 30000 });
+    } catch (error     ) {
+      return { error };
+    }
+  };
+  const gitState = resolveBashHelper('do-git-state.sh');
+  const state = gitState ? run('bash', [gitState, '--json']) : null;
+  let ref                = null;
+  if (state && !state.error && state.status === 0) {
+    try { ref = JSON.parse(state.stdout).integration_ref || null; } catch { /* reported below */ }
+  }
+  if (!ref) return { reason: gitState ? 'no integration ref could be resolved' : 'the DoFlow helper scripts are missing from this install (do-git-state.sh)' };
+  const exists = run('git', ['rev-parse', '--verify', '--quiet', ref]);
+  if (!exists || exists.error || exists.status !== 0) {
+    return { reason: `integration branch '${ref}' not found`, note: `integration branch '${ref}' not found; working tree only` };
+  }
+  const base = run('git', ['merge-base', ref, 'HEAD']);
+  const mergeBase = base && !base.error && base.status === 0 ? String(base.stdout || '').trim() : '';
+  if (!mergeBase) return { reason: `no merge base with '${ref}'` };
+  return { ref, mergeBase };
+}
+
+/**
+ * An explicit `--baseline-ref` (IC-022): resolved once to a commit SHA, and required to be an ancestor of
+ * HEAD so the measured diff is the whole of what happened since it. Anything else is unresolved with its
+ * reason; there is no fallback to the working tree, which would report committed work as a clean scope.
+ * @param {Object} options
+ * @param {string} options.cwd
+ * @param {string} options.ref commit or ref the caller pinned
+ * @param {Function} [options.exec] spawnSync-compatible
+ * @returns {{ok: true, ref: string, sha: string}|{ok: false, ref: string, reason: string}}
+ */
+function resolveExplicitBaseline({ cwd, ref, exec = spawnSync }                                          )      {
+  const fail = (reason        ) => ({ ok: false, ref, reason });
+  if (typeof ref !== 'string' || ref.trim() === '' || ref.startsWith('-')) {
+    return fail(`baseline ref '${ref}' is not a usable commit or ref`);
+  }
+  const run = (args          ) => {
+    try { return exec('git', args, { cwd, encoding: 'utf8', timeout: 30000 }); } catch (error     ) { return { error }; }
+  };
+  const parsed = run(['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`]);
+  const sha = parsed && !parsed.error && parsed.status === 0 ? String(parsed.stdout || '').trim() : '';
+  if (!/^[0-9a-f]{40,64}$/.test(sha)) return fail(`baseline ref '${ref}' does not name a commit`);
+  const ancestry = run(['merge-base', '--is-ancestor', sha, 'HEAD']);
+  if (!ancestry || ancestry.error || (ancestry.status !== 0 && ancestry.status !== 1)) {
+    return fail(`could not check whether ${sha} is an ancestor of HEAD`);
+  }
+  if (ancestry.status === 1) return fail(`baseline ${sha} is not an ancestor of HEAD, so the change since it cannot be measured`);
+  return { ok: true, ref, sha };
+}
+
+module.exports = {
+  buildScopeBound,
+  taskFilesFromPlan,
+  resolveIntegrationBase,
+  resolveExplicitBaseline,
+  resolvePlanSource,
+  parseDeclaredScope,
+  resolveScopeBound,
+  scopeReasonText,
+  boundSourcesText,
+};