mandrel 1.57.0

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -0,0 +1,310 @@
+/**
+ * bdd-scenario-scanner.js — Gherkin scenario index for /epic-plan Phase 7.
+ *
+ * Story #2637 (sibling to #2634 codebase-snapshot, #2635 spec-freshness,
+ * #2636 file-assumption gate). The Acceptance Engineer step of
+ * `epic-plan-spec-author` currently writes ACs from PRD/Tech Spec narrative
+ * alone — it never inspects the consumer project's existing `.feature`
+ * files. Planned ACs frequently duplicate scenarios that already exist or
+ * re-specify behaviour the codebase already proves; the duplication is
+ * only discovered (at best) during `/story-deliver` or (at worst) after
+ * a redundant PR ships.
+ *
+ * `scanBddScenarios` walks every configured feature root, parses each
+ * `.feature` file with a Gherkin-aware regex pass (deliberately not a
+ * full Gherkin AST — keep the scanner cheap and dependency-free), and
+ * returns one entry per scenario with its file path, line number,
+ * scenario title, tag list, and an extracted set of outcome keywords
+ * (action verb + objects from the "Then" clauses). The keyword set is
+ * the fuzzy-match surface the planner uses to spot ACs that already
+ * have a matching scenario.
+ *
+ * Determinism is load-bearing: the matcher is keyword-based, not
+ * embedding-based, so re-running `/epic-plan` against the same
+ * acceptance spec produces the same disposition annotations.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { Logger } from './Logger.js';
+
+/**
+ * Recursively list every file with a `.feature` extension under one of
+ * the given roots. Returns absolute paths; never throws on permission
+ * errors — unreadable directories are simply skipped.
+ *
+ * @param {string[]} roots
+ * @param {{ logger?: { debug: Function } }} [opts]
+ * @returns {string[]}
+ */
+export function listFeatureFiles(roots, opts = {}) {
+  const logger = opts.logger ?? Logger;
+  const out = [];
+  for (const root of roots ?? []) {
+    walk(root, out, logger);
+  }
+  return out;
+}
+
+function walk(dir, acc, logger) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    logger.debug(
+      `[bdd-scenario-scanner] readdir failed for ${dir}: ${err?.message ?? err}`,
+    );
+    return;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(abs, acc, logger);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!abs.toLowerCase().endsWith('.feature')) continue;
+    try {
+      const stat = statSync(abs);
+      if (stat.size > 256 * 1024) continue; // skip obviously bogus inputs
+    } catch (err) {
+      logger.debug(
+        `[bdd-scenario-scanner] stat failed for ${abs}: ${err?.message ?? err}`,
+      );
+      continue;
+    }
+    acc.push(abs);
+  }
+}
+
+/**
+ * English stop words that carry no outcome semantics. Stripped from
+ * extracted keywords so "the invoice appears in the outbox" reduces to
+ * `{invoice, appears, outbox}` rather than including `{the, in}`.
+ *
+ * Kept short on purpose — false-negative pruning here is preferable to
+ * over-pruning a verb the matcher needs.
+ */
+const STOP_WORDS = new Set([
+  'a',
+  'an',
+  'the',
+  'is',
+  'are',
+  'be',
+  'to',
+  'of',
+  'in',
+  'on',
+  'at',
+  'and',
+  'or',
+  'with',
+  'for',
+  'by',
+  'as',
+  'that',
+  'this',
+  'their',
+  'there',
+  'it',
+  'its',
+  'should',
+  'will',
+  'has',
+  'have',
+  'been',
+  'was',
+  'were',
+]);
+
+/**
+ * Reduce a free-text outcome ("the invoice appears in the outbox") to a
+ * deterministic, lower-case keyword set ("invoice", "appears", "outbox").
+ * Words of length 1 are dropped; common stop words are filtered.
+ *
+ * Exported so the matcher and downstream tests can share the exact
+ * tokenisation contract.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function extractOutcomeKeywords(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const tokens = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s_-]+/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+  return Array.from(new Set(tokens));
+}
+
+const TAG_LINE_RE = /^\s*@([\w@\s-]+)\s*$/;
+const SCENARIO_LINE_RE = /^\s*Scenario(?: Outline)?\s*:\s*(.+?)\s*$/;
+const THEN_LINE_RE = /^\s*(?:Then|And|But)\s+(.+?)\s*$/i;
+const STEP_KEYWORD_RE = /^\s*(?:Given|When|Then|And|But|\*)\s+/i;
+
+/**
+ * Parse a single `.feature` file body into an array of scenario rows.
+ * The parser is deliberately minimal:
+ *
+ *   - `@tag` lines preceding a `Scenario:` are attached to that scenario.
+ *   - `Scenario:` and `Scenario Outline:` both produce a row.
+ *   - `Then` / `And` / `But` lines following the scenario (until the
+ *     next scenario or EOF) feed the `outcomeKeywords` set.
+ *
+ * The Background block is recognised but its steps are NOT folded into
+ * outcomeKeywords — Background carries setup, not outcomes.
+ *
+ * @param {string} body
+ * @returns {Array<{ scenarioTitle: string, line: number, tags: string[], outcomeKeywords: string[] }>}
+ */
+export function parseFeatureBody(body) {
+  if (typeof body !== 'string') return [];
+  const lines = body.split(/\r?\n/);
+  const scenarios = [];
+  let pendingTags = [];
+  let current = null;
+  let inBackground = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const tagMatch = raw.match(TAG_LINE_RE);
+    if (tagMatch) {
+      for (const t of tagMatch[1].split(/\s+/)) {
+        if (t.length > 0) pendingTags.push(`@${t.replace(/^@/, '')}`);
+      }
+      continue;
+    }
+    if (/^\s*Background\s*:/.test(raw)) {
+      inBackground = true;
+      continue;
+    }
+    const scenarioMatch = raw.match(SCENARIO_LINE_RE);
+    if (scenarioMatch) {
+      if (current) scenarios.push(finalize(current));
+      current = {
+        scenarioTitle: scenarioMatch[1].trim(),
+        line: i + 1,
+        tags: pendingTags.slice(),
+        thenLines: [],
+      };
+      pendingTags = [];
+      inBackground = false;
+      continue;
+    }
+    if (current && !inBackground) {
+      const thenMatch = raw.match(THEN_LINE_RE);
+      if (thenMatch) current.thenLines.push(thenMatch[1]);
+    }
+    // Reset pendingTags when a step keyword in the body appears with no
+    // scenario yet — stray tags before a Feature: header don't bind.
+    if (current === null && STEP_KEYWORD_RE.test(raw)) {
+      pendingTags = [];
+    }
+  }
+  if (current) scenarios.push(finalize(current));
+  return scenarios;
+}
+
+function finalize(scenario) {
+  const kw = new Set();
+  for (const line of scenario.thenLines) {
+    for (const tok of extractOutcomeKeywords(line)) kw.add(tok);
+  }
+  return {
+    scenarioTitle: scenario.scenarioTitle,
+    line: scenario.line,
+    tags: scenario.tags,
+    outcomeKeywords: Array.from(kw).sort(),
+  };
+}
+
+/**
+ * Scan every `.feature` file under the configured feature roots and
+ * return the full scenario index. Each row carries the absolute path,
+ * the 1-based line number of the `Scenario:` keyword, the title, the
+ * tag list, and the deterministic outcome-keyword set. Returns an
+ * empty array when no roots exist or no scenarios are found — the
+ * caller (the spec-author skill) uses emptiness to know the project
+ * hasn't adopted BDD, no warning required.
+ *
+ * @param {{ featureRoots: string[] }} opts
+ * @returns {Array<{ file: string, line: number, scenarioTitle: string, tags: string[], outcomeKeywords: string[] }>}
+ */
+export function scanBddScenarios(opts = {}) {
+  const { featureRoots = [] } = opts;
+  const logger = opts.logger ?? Logger;
+  const files = listFeatureFiles(featureRoots, { logger });
+  const out = [];
+  for (const file of files) {
+    let body;
+    try {
+      body = readFileSync(file, 'utf8');
+    } catch (err) {
+      logger.debug(
+        `[bdd-scenario-scanner] readFile failed for ${file}: ${err?.message ?? err}`,
+      );
+      continue;
+    }
+    const scenarios = parseFeatureBody(body);
+    for (const sc of scenarios) {
+      out.push({
+        file,
+        line: sc.line,
+        scenarioTitle: sc.scenarioTitle,
+        tags: sc.tags,
+        outcomeKeywords: sc.outcomeKeywords,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Score the overlap between an acceptance criterion's outcome string
+ * and a scenario's outcome-keyword set. The score is the count of
+ * keywords the AC outcome shares with the scenario, normalised by the
+ * smaller of the two sets so single-word ACs aren't penalised against
+ * verbose scenarios (and vice versa).
+ *
+ * @param {string} acOutcome
+ * @param {{ outcomeKeywords: string[] }} scenario
+ * @returns {number} Score in [0, 1].
+ */
+export function scoreMatch(acOutcome, scenario) {
+  const acTokens = new Set(extractOutcomeKeywords(acOutcome));
+  const scTokens = new Set(scenario.outcomeKeywords ?? []);
+  if (acTokens.size === 0 || scTokens.size === 0) return 0;
+  let overlap = 0;
+  for (const t of acTokens) {
+    if (scTokens.has(t)) overlap += 1;
+  }
+  return overlap / Math.min(acTokens.size, scTokens.size);
+}
+
+/**
+ * Find the best matching scenario for one AC outcome string, if any.
+ * Returns `null` when no scenario scores above `minScore` (default
+ * `0.5`). The matcher is intentionally conservative — false positives
+ * cost the planner more (rewriting the spec to "refine" a scenario
+ * that doesn't actually exist) than false negatives (writing a new
+ * scenario the operator can later dedupe).
+ *
+ * @param {string} acOutcome
+ * @param {Array<{ outcomeKeywords: string[] }>} scenarios
+ * @param {{ minScore?: number }} [opts]
+ * @returns {{ scenario: object, score: number } | null}
+ */
+export function findBestScenarioMatch(acOutcome, scenarios, opts = {}) {
+  const minScore = opts.minScore ?? 0.5;
+  let best = null;
+  for (const sc of scenarios ?? []) {
+    const score = scoreMatch(acOutcome, sc);
+    if (score >= minScore && (best === null || score > best.score)) {
+      best = { scenario: sc, score };
+    }
+  }
+  return best;
+}

package/.agents/scripts/lib/bootstrap/baselines-layout-migration.js

@@ -0,0 +1,202 @@
+/**
+ * bootstrap/baselines-layout-migration — Story #1401 (Epic #1386),
+ * re-targeted by Story #1467 (Epic #1179).
+ *
+ * Idempotent helper that brings a project's per-Epic ratchet snapshots into
+ * the `temp/epic/<id>/baselines/` namespace. Three legacy shapes are
+ * recognised and migrated:
+ *
+ *   1. Loose per-Epic snapshots at the baselines root
+ *      (`baselines/epic-<id>-{maintainability,crap}.json`).
+ *   2. The flat prototype `baselines/snapshots/<id>/` tree.
+ *   3. The committed `baselines/epic/<id>/` subdirectory shape that the
+ *      original Story #1396 introduced (now superseded — committed snapshots
+ *      accumulated obsolete entries forever because nothing pruned them).
+ *
+ * All three shapes are relocated under `<repoRoot>/temp/epic/<id>/baselines/`,
+ * where they inherit the existing per-epic temp-tree cleanup contract:
+ * `/epic-deliver` reaps `temp/epic/<id>/` on merge, so the ratchet snapshots
+ * are ephemeral scratch state — never committed, no manual prune.
+ *
+ * The main-tracked `baselines/{maintainability,crap}.json` files are NOT
+ * touched — they remain at the root as the `main`-baseline contract
+ * specifies.
+ *
+ * Pruning committed leftovers
+ * ---------------------------
+ * When the legacy `baselines/epic/<id>/` subdirectory shape is detected, the
+ * helper invokes `git rm -r --quiet baselines/epic/<id>` (with
+ * `--ignore-unmatch` for the untracked case) so the now-empty committed tree
+ * is removed in the same operation. Callers commit the resulting working-tree
+ * delta; on a clean repo (no committed `baselines/epic/`) the helper is a
+ * filesystem-only no-op.
+ *
+ * The helper reports the per-Epic outcome so the workflow can summarise
+ * exactly which snapshots moved and which were already in the target
+ * shape. Re-running on an already-migrated tree produces zero mutations.
+ *
+ * @module bootstrap/baselines-layout-migration
+ */
+
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BASELINE_FILE_RE = /^(maintainability|crap)\.json$/;
+const LOOSE_FILE_RE = /^epic-(\d+)-(maintainability|crap)\.json$/;
+
+/**
+ * Move a single snapshot file to its temp-namespace target. When the target
+ * already holds a canonical copy, the source is discarded instead of
+ * overwriting.
+ */
+function moveOneSnapshot({ from, to, label, moves }) {
+  if (fs.existsSync(to)) {
+    fs.rmSync(from);
+    moves.push({ from, to, action: 'discarded-superseded' });
+    return;
+  }
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+  moves.push({ from, to, action: label });
+}
+
+/**
+ * Drop a directory if it exists on disk and is empty.
+ */
+function dropEmptyDir(absDir) {
+  if (fs.existsSync(absDir) && fs.readdirSync(absDir).length === 0) {
+    fs.rmdirSync(absDir);
+  }
+}
+
+/**
+ * Walk a per-Epic source directory (`<srcRoot>/<id>/*.json`) and migrate
+ * each baseline file into `<tempEpicRoot>/<id>/baselines/`. Returns the
+ * Epic dirs that were touched so the caller can run per-Epic cleanup
+ * (e.g. `git rm` for the committed shape).
+ */
+function migrateEpicDir({ srcRoot, tempEpicRoot, label, moves }) {
+  const touched = [];
+  if (!fs.existsSync(srcRoot) || !fs.statSync(srcRoot).isDirectory()) {
+    return touched;
+  }
+  for (const epicEnt of fs.readdirSync(srcRoot, { withFileTypes: true })) {
+    if (!epicEnt.isDirectory() || !/^\d+$/.test(epicEnt.name)) continue;
+    const epicId = epicEnt.name;
+    const fromDir = path.join(srcRoot, epicId);
+    const toDir = path.join(tempEpicRoot, epicId, 'baselines');
+    for (const fileEnt of fs.readdirSync(fromDir, { withFileTypes: true })) {
+      if (!fileEnt.isFile() || !BASELINE_FILE_RE.test(fileEnt.name)) continue;
+      moveOneSnapshot({
+        from: path.join(fromDir, fileEnt.name),
+        to: path.join(toDir, fileEnt.name),
+        label,
+        moves,
+      });
+    }
+    dropEmptyDir(fromDir);
+    touched.push({ epicId, fromDir });
+  }
+  return touched;
+}
+
+/**
+ * Migrate shape 1: loose per-Epic snapshots at the root of `baselines/`.
+ */
+function migrateLooseShape({ baselinesDir, tempEpicRoot, moves }) {
+  for (const ent of fs.readdirSync(baselinesDir, { withFileTypes: true })) {
+    if (!ent.isFile()) continue;
+    const m = ent.name.match(LOOSE_FILE_RE);
+    if (!m) continue;
+    const [, epicId, gate] = m;
+    moveOneSnapshot({
+      from: path.join(baselinesDir, ent.name),
+      to: path.join(tempEpicRoot, epicId, 'baselines', `${gate}.json`),
+      label: 'relocated-loose',
+      moves,
+    });
+  }
+}
+
+/**
+ * Stage the prune of a now-empty committed `baselines/epic/<id>/` via
+ * `git rm -r --quiet --ignore-unmatch`. `--ignore-unmatch` keeps the call
+ * safe when the path is not tracked (fresh-clone case).
+ */
+function pruneCommittedEpic({ fromDir, repoRoot, spawnSync, prunedDirs }) {
+  const epicRelPath = path
+    .relative(repoRoot, fromDir)
+    .split(path.sep)
+    .join('/');
+  const rm = spawnSync(
+    'git',
+    ['rm', '-r', '--quiet', '--ignore-unmatch', '--', epicRelPath],
+    { cwd: repoRoot, encoding: 'utf-8', stdio: 'pipe', shell: false },
+  );
+  prunedDirs.push({ path: epicRelPath, gitStatus: rm.status ?? null });
+}
+
+/**
+ * Detect and migrate any legacy per-Epic snapshot under `baselinesDir` into
+ * the `temp/epic/<id>/baselines/` shape under `repoRoot`. Returns one of
+ * three actions per discovered snapshot.
+ *
+ * @param {object} args
+ * @param {string} args.baselinesDir - Absolute path to the project's
+ *   `baselines/` directory (the legacy source-of-snapshots locator).
+ * @param {string} [args.repoRoot] - Absolute path to the project root.
+ *   Defaults to `path.dirname(baselinesDir)` so existing callers that only
+ *   pass `baselinesDir` continue to work for repos where `baselines/` sits
+ *   directly under the repo root (the canonical layout).
+ * @param {typeof defaultSpawnSync} [args.spawnSync] - Injected for tests.
+ */
+export function migrateBaselinesLayout(args) {
+  const baselinesDir = args.baselinesDir;
+  const repoRoot = args.repoRoot ?? path.dirname(baselinesDir);
+  const spawnSync = args.spawnSync ?? defaultSpawnSync;
+  const moves = [];
+  const prunedDirs = [];
+
+  if (!fs.existsSync(baselinesDir)) {
+    return { action: 'no-baselines-dir', moves, prunedDirs };
+  }
+
+  const tempEpicRoot = path.join(repoRoot, 'temp', 'epic');
+
+  // Shape 1: loose per-Epic snapshots at the root.
+  migrateLooseShape({ baselinesDir, tempEpicRoot, moves });
+
+  // Shape 2: prototype `baselines/snapshots/<id>/` tree.
+  const protoRoot = path.join(baselinesDir, 'snapshots');
+  migrateEpicDir({
+    srcRoot: protoRoot,
+    tempEpicRoot,
+    label: 'relocated-prototype',
+    moves,
+  });
+  dropEmptyDir(protoRoot);
+
+  // Shape 3: committed `baselines/epic/<id>/` subdirectory layout (the
+  // shape Story #1396 introduced; superseded by the temp-namespace
+  // contract in Story #1467). Move snapshots OUT to temp, prune each
+  // committed per-Epic dir via `git rm`, then drop the parent.
+  const committedEpicRoot = path.join(baselinesDir, 'epic');
+  const touched = migrateEpicDir({
+    srcRoot: committedEpicRoot,
+    tempEpicRoot,
+    label: 'relocated-committed',
+    moves,
+  });
+  for (const { fromDir } of touched) {
+    pruneCommittedEpic({ fromDir, repoRoot, spawnSync, prunedDirs });
+  }
+  dropEmptyDir(committedEpicRoot);
+
+  return {
+    action:
+      moves.length > 0 || prunedDirs.length > 0 ? 'migrated' : 'no-change',
+    moves,
+    prunedDirs,
+  };
+}