@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/harness/flow-contract.ts

@@ -40,6 +40,13 @@ export interface FlowDecl {
   reason?: string;
 }
 
+/** One declared journey phase. `scenarios:` is the author naming its evidence directly. */
+export interface FlowPhaseDecl {
+  id: string;
+  description?: string;
+  scenarios?: string[];
+}
+
 const FLOW_STATUSES = new Set(['covered', 'deferred', 'pending-clarification', 'out-of-scope']);
 
 export interface FlowContract {
@@ -58,6 +65,12 @@ export interface FlowContract {
   /** Journey phases this flow declares. Default [HP, ER, EH]; UI is allowed but
    *  never demanded (presentation is the balance axis's business, not coverage's). */
   phases: string[];
+  /**
+   * The phases as DECLARED, when the contract uses the object form. A phase may name the
+   * scenarios that carry it — direct evidence, rather than the harness inferring coverage from
+   * id segments — and that is what a project which writes `phases:` this way is telling us.
+   */
+  phaseDetails?: FlowPhaseDecl[];
   /**
    * The use case's declared flow inventory — the answer to "how many flows does this use
    * case HAVE?". `phases:` alone cannot answer it: a phase is present as soon as ONE
@@ -94,6 +107,8 @@ export interface FlowQualityResult {
   /** Off-goal categories, for the split suggestion ("VP-FILTER-* looks like its own flow"). */
   offGoalCategories: string[];
   phases: { phase: string; covered: boolean; automated: boolean }[];
+  /** Phase-declared scenario refs that match no scenario — a phase whose evidence does not exist. */
+  danglingPhaseRefs: Array<{ phase: string; ref: string }>;
   /** Covered-and-automated phases / declared phases (UI excluded) — the flow coverage axis. */
   phaseRatio: number;
   /** Cross-namespace transitions followed by an assertion / all transitions. */
@@ -130,9 +145,34 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
     errors.push('missing `outcome.screen:` — the screen namespace that carries the final proof');
   }
   if (errors.length > 0) return { contract: null, errors };
-  const phases = Array.isArray(raw.phases) && raw.phases.length > 0
-    ? (raw.phases as unknown[]).map((x) => String(x).toUpperCase())
-    : DEFAULT_PHASES;
+  // `phases:` comes in two shapes, and the loader used to assume the first. A real project
+  // declared the RICHER one — each phase an object with `name`, `description` and an explicit
+  // `scenarios:` list — and `String(x).toUpperCase()` turned every one of them into
+  // `[OBJECT OBJECT]`. Nothing matched, phase coverage read 0%, the score fell to 6.9, and the
+  // report said only that the phases were uncovered. Garbage in place of an error is the worst
+  // of both: the author sees a broken number with no cause (#657).
+  //
+  // The object form is the better declaration — it names the scenarios that carry the phase
+  // instead of leaving the harness to infer them from ids — so it is read, not merely tolerated.
+  const phaseDetails: FlowPhaseDecl[] = Array.isArray(raw.phases)
+    ? (raw.phases as unknown[]).map((x, i) => {
+      if (x !== null && typeof x === 'object') {
+        const o = x as Record<string, unknown>;
+        const name = o.name ?? o.id ?? o.phase;
+        if (name === undefined) {
+          errors.push(`phases[${i}] is an object with no \`name:\` (or \`id:\`) — a phase needs a label`);
+          return { id: `PHASE${i + 1}` };
+        }
+        return {
+          id: String(name).toUpperCase(),
+          description: o.description !== undefined ? String(o.description) : undefined,
+          scenarios: Array.isArray(o.scenarios) ? (o.scenarios as unknown[]).map((v) => String(v)) : undefined,
+        };
+      }
+      return { id: String(x).toUpperCase() };
+    })
+    : [];
+  const phases = phaseDetails.length > 0 ? phaseDetails.map((p) => p.id) : DEFAULT_PHASES;
   return {
     contract: {
       goal: String(raw.goal),
@@ -144,6 +184,7 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       successGuarantee: raw.successGuarantee !== undefined ? String(raw.successGuarantee) : (raw.success_guarantee !== undefined ? String(raw.success_guarantee) : undefined),
       minimalGuarantee: raw.minimalGuarantee !== undefined ? String(raw.minimalGuarantee) : (raw.minimal_guarantee !== undefined ? String(raw.minimal_guarantee) : undefined),
       phases,
+      ...(phaseDetails.some((p) => p.scenarios || p.description) ? { phaseDetails } : {}),
       flows: Array.isArray(raw.flows)
         ? (raw.flows as Array<Record<string, unknown>>)
             .filter((f) => f && typeof f === 'object' && f.id)
@@ -209,8 +250,17 @@ function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
 
 /** Phase of a scenario: its declared phase token (FL-HP-001 / VP-FLOW-ER-02 / MS-EH-005)
  *  when present, else vocabulary detection. */
-export function phaseOf(s: ScenarioInfo, declared: string[]): string | null {
+export function phaseOf(s: ScenarioInfo, declared: string[], details?: FlowPhaseDecl[]): string | null {
   const id = (s.vpId ?? '').toUpperCase();
+  // When a phase NAMES its scenarios, that list is the mapping — the author has already done
+  // the assignment, and inferring it from id segments instead would ignore them. A phase called
+  // "Cross-screen data" shares no token with `VP-LOGIC-002`; only the declaration connects them.
+  for (const ph of details ?? []) {
+    if (ph.scenarios?.some((ref) => {
+      const r = ref.trim().toUpperCase();
+      return r === id || (r.length > 0 && s.name.toUpperCase().includes(r));
+    })) return ph.id;
+  }
   // A DECLARED phase wins, matched on the id's segments with the branch number removed —
   // so the use-case vocabulary (VP-EF01-01, VP-AF02-01: one id per Exception/Alternate
   // Flow) resolves to its phase exactly like the flat HP/ER/EH form does.
@@ -350,7 +400,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   const neutral: FlowQualityResult = {
     hasContract: false, errors, outcomeProven: false, outcomeManualOnly: false,
     offGoal: [], offGoalRatio: 0, offGoalCategories: [],
-    phases: [], phaseRatio: 1, handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [],
+    phases: [], phaseRatio: 1, danglingPhaseRefs: [], handoffs: { total: 0, asserted: 0, ratio: 1 }, sit: [],
   };
   if (!contract) return neutral;
 
@@ -367,7 +417,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   const basic = declaredPhases.filter((p) => p !== 'UI')[0];
   const offGoalScenarios = scenarios.filter((s) => {
     if (touchesOutcome(s, outcomeScreen)) return false;
-    const ph = phaseOf(s, declaredPhases);
+    const ph = phaseOf(s, declaredPhases, contract.phaseDetails);
     // Any NON-basic declared phase (guards, error recovery, alternate branches) legitimately
     // stops before the outcome — that is what a branch IS. Only an unclassified scenario that
     // never reaches the outcome is evidence of a second business goal.
@@ -383,7 +433,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   // phase that must reach the declared outcome, whether the project spells it HP or BF.
   const basicPhase = demanded[0];
   const phases = demanded.map((phase) => {
-    const inPhase = scenarios.filter((s) => phaseOf(s, declaredPhases) === phase);
+    const inPhase = scenarios.filter((s) => phaseOf(s, declaredPhases, contract.phaseDetails) === phase);
     // The basic flow must additionally prove the outcome — a data assertion elsewhere is not the goal.
     const relevant = phase === basicPhase ? inPhase.filter((s) => touchesOutcome(s, outcomeScreen)) : inPhase;
     return {
@@ -396,6 +446,17 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     ? phases.filter((p) => p.covered && p.automated).length / demanded.length
     : 1;
 
+  // A phase that names a scenario which does not exist is a declaration pointing at nothing:
+  // the phase reads covered in the contract and is empty in the suite. Same class as a dangling
+  // traceability ref — the map, not the territory.
+  const known = new Set(scenarios.flatMap((s) => [s.vpId?.toUpperCase(), s.name.toUpperCase()].filter(Boolean) as string[]));
+  const danglingPhaseRefs = (contract.phaseDetails ?? []).flatMap((ph) => (ph.scenarios ?? [])
+    .filter((ref) => {
+      const r = ref.trim().toUpperCase();
+      return !known.has(r) && !scenarios.some((s) => s.name.toUpperCase().includes(r));
+    })
+    .map((ref) => ({ phase: ph.id, ref })));
+
   // --- Handoff integrity: no blind tail after a cross-namespace transition. ---
   // A transition counts as asserted when ANY assertion follows it — in the entered
   // namespace or later. Demanding the assertion in the entered namespace itself
@@ -439,7 +500,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     outcomeProven, outcomeManualOnly,
     offGoal: offGoalScenarios.map((s) => s.name.slice(0, 80)),
     offGoalRatio, offGoalCategories,
-    phases, phaseRatio, handoffs, sit,
+    phases, phaseRatio, danglingPhaseRefs, handoffs, sit,
   };
 }
 
@@ -460,7 +521,24 @@ export interface ContinuityGap { claim: string; missing: 'loss' | 'persistence'
 
 const CONTINUITY_CLAIM = /\b(buffer(?:s|ed|ing)?|persist(?:s|ed|ence)?|round[- ]?trips?|restor(?:e|es|ed|ation)|carr(?:y|ied|ies)|retain(?:s|ed)?|session[- ]?storage|local[- ]?storage)\b/i;
 const SIDE_PERSIST = /\b(restor(?:e|es|ed)|persist(?:s|ed)?|unchanged|same value|round[- ]?trips?|re-?hydrat\w*|still (?:shows|holds)|carr(?:y|ied|ies)|retain(?:s|ed)?|prefilled|pre-?filled)\b/i;
-const SIDE_LOSS = /\b(lose|loses|lost|cleared?|clears|discard\w*|reload\w*|refresh\w*|expire\w*|empty|blank|not restored|no longer|wiped?|reset)\b/i;
+// A LOSS CONSTRUCTION, not a word list. `reset` and `expire` are domain NOUNS — every claim in a
+// password-*reset* flow contains "reset", and every token flow contains "expire", so a bare-word
+// list marked all of them as promising that state is lost and then demanded the missing half.
+// A field report hit exactly that: the two sides of its mechanism were both written (in two
+// different scenarios, which this already handles) and CONTINUITY-ONE-SIDED fired anyway (#630).
+// The state has to be the thing that goes: `is cleared`, `loses the values`, `no longer holds`.
+const SIDE_LOSS = new RegExp([
+  '\\b(?:lose|loses|losing|lost)\\b',
+  '\\b(?:is|are|gets?|got|becomes?|will be|was|were)\\s+(?:lost|cleared|emptied|discarded|wiped|reset|blanked)\\b',
+  '\\b(?:clears|clearing|discards|discarding|wipes|wiping)\\b',
+  '\\b(?:does|do|did)\\s+not\\s+(?:survive|persist|remain|carry)\\b',
+  '\\bnot\\s+(?:restored|retained|preserved|kept)\\b',
+  '\\bno longer\\b',
+  '\\bcomes? up (?:empty|blank)\\b',
+  // The triggers that CAUSE the loss still count when the claim names them as such.
+  '\\b(?:on|after) (?:a )?(?:reload|refresh)\\b',
+  '\\breload(?:ing|s|ed)? (?:the )?(?:page|screen|form|tab)\\b',
+].join('|'), 'i');
 
 /**
  * Continuity claims in the viewpoint file whose feature proves only ONE side.

package/src/harness/parse.ts

@@ -230,7 +230,11 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
       // assert persisted state — without this they'd be scored `shallow`, penalizing
       // exactly the checks the review encourages. `tab order` is a STRUCTURAL
       // assertion (a data table of focus stops) with the same no-{{ref}} property.
-      if (/\{\{|contains|match data|toHaveText|in (local|session) storage|tab order/i.test(step.text)) hasData = true;
+      // `matches "<format>"` belongs here for the same reason: it carries no {{ref}} because
+      // the contract IS the shape ("Format: yyyy/mm/dd ~ yyyy/mm/dd"), and it is a stricter
+      // check than the value assert it replaces — scoring it shallow would penalize the
+      // stronger assertion.
+      if (/\{\{|contains|match data|matches\s+"|toHaveText|in (local|session) storage|tab order/i.test(step.text)) hasData = true;
     }
   }
 

package/src/harness/quality-gates.ts

@@ -14,24 +14,46 @@ import { readTextFile } from './read-text';
 export interface DownstreamResult {
   downstreamRoutes: string[];                 // success/navigation targets ≠ own route
   underCovered: { route: string; slug: string }[]; // referenced only by a bare page-nav
+  /**
+   * Declared navigation targets NO scenario mentions at all. These used to be skipped as "out of
+   * this screen's scope", which is right for a screen and wrong for a FLOW: a field report found a
+   * dashboard whose spec declared four click-through destinations and whose suite tested only the
+   * render conditions of the regions containing them — the navigation itself had no case, and
+   * nothing said so (#630).
+   */
+  absent: { route: string; slug: string }[];
 }
 
 /** Routes the spec hands off to (Navigation Flow / success), other than the screen's own route. */
 function downstreamRoutes(specText: string): string[] {
   const ownRoute = (specText.match(/\*\*Route\*\*\s*:\s*`?(\/[^\s`]+)/) || [])[1] || '';
   const routes = new Set<string>();
+  const negated = new Set<string>();
   for (const line of specText.split('\n')) {
     if (!/success|navigat|to \(|→/i.test(line)) continue;
     // A real route's leading `/` sits at a path boundary (start, whitespace, backtick, quote, paren),
     // NOT after a letter/digit. The lookbehind rejects prose slashes like "text/icon" or
     // "category/brand" that aren't routes at all (H2 — they produced /icon, /button, /brand).
+    let negRun = false;      // inside a "…, not `/a`/`/b`" list
+    let prevEnd = 0;
     for (const m of line.matchAll(/(?<![A-Za-z0-9])(\/[a-z][a-z0-9/_-]+)`?/gi)) {
       const r = m[1];
+      // "the destination is `/a/b` (singular, not `/a/bs` as this spec assumed)" declares ONE
+      // target and CORRECTS another. A spec that says where a route is NOT is doing the reader a
+      // service; extracting the disowned one and demanding a test for it punishes the correction.
+      // The negation carries across a LIST — "not `/x`/`/y`" disowns both, not just the first.
+      const before = line.slice(Math.max(0, m.index - 24), m.index);
+      const gap = line.slice(prevEnd, m.index);
+      prevEnd = m.index + m[0].length;
+      if (/\b(?:not|instead of|rather than|no longer|never|không)\s*[`'"(\[]*\s*$/i.test(before)) negRun = true;
+      else if (negRun && !/^[`'"\s)\]]*[/,]?\s*(?:or|hoặc)?\s*[`'"(\[]*$/i.test(gap)) negRun = false;
+      if (negRun) { negated.add(r); continue; }
       if (r !== ownRoute && r.split('/').length > ownRoute.split('/').length - 0) routes.add(r);
     }
   }
+  for (const n of negated) if (!routes.has(n)) routes.delete(n);
   // keep only routes that extend beyond the own route (a distinct downstream surface)
-  return [...routes].filter((r) => r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
+  return [...routes].filter((r) => !negated.has(r) && r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
 }
 
 /**
@@ -100,9 +122,27 @@ export function sameScreenName(slug: string, label: string): boolean {
   return i >= 5 && i / Math.min(a.length, b.length) >= 0.6;
 }
 
-export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
-  const routes = downstreamRoutes(specText);
+export function downstreamScope(
+  specText: string, scenarios: ScenarioInfo[], featureText = '',
+): DownstreamResult {
+  const all = downstreamRoutes(specText);
+  // A one-segment route that other declared routes are BUILT ON is a prefix, not a destination:
+  // a spec noting that "every route is served under a `/xx/` locale prefix (e.g. `/xx/register`)"
+  // was read as declaring `/xx/` a navigation target, and no suite will ever "navigate to" it.
+  // Structural, so it catches any mount point — locale, tenant, api version — without a list.
+  const mounts = all.filter((r) => {
+    const segs = r.split('/').filter(Boolean);
+    return segs.length === 1 && all.some((o) => o !== r && o.startsWith(r.endsWith('/') ? r : `${r}/`));
+  });
+  // The same destination written twice — once bare, once under the mount the spec documents —
+  // is one navigation target, and reporting both doubles the work it asks for.
+  const routes = all.filter((r) => !mounts.includes(r)
+    && !mounts.some((m) => {
+      const bare = r.slice(m.replace(/\/$/, '').length);
+      return bare.startsWith('/') && all.includes(bare);
+    }));
   const underCovered: { route: string; slug: string }[] = [];
+  const absent: { route: string; slug: string }[] = [];
   for (const route of routes) {
     const slug = (route.split('/').filter(Boolean).pop() || route).toLowerCase();
     // Referenced when the route/slug appears literally, OR when any `[Ref]` in the suite
@@ -112,16 +152,34 @@ export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): Do
     const refs = scenarios.filter((s) =>
       s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()) ||
       labelsOf(s).some((l) => sameScreenName(slug, l)));
-    if (!refs.length) continue; // not referenced at all — out of this screen's scope entirely
+    if (!refs.length) {
+      // A scenario's haystack is its name + steps, so a route documented in a @manual scenario's
+      // tester procedure — a COMMENT — looks like nothing at all. That route is accounted for: a
+      // person has been told to check it. Reporting "no scenario mentions it, add one" over a
+      // deliberate manual deferral is the false positive this whole round is about, so absence is
+      // measured against the feature TEXT, comments included (#651 follow-up).
+      if (!featureText.toLowerCase().includes(route.toLowerCase())) absent.push({ route, slug });
+      continue;
+    }
     // Substantively covered only if some scenario OPERATES on the downstream — i.e. it
     // starts there (`is on [<downstream>]`) — not merely navigates to it as a terminal
     // `see [<downstream>] page` assertion. The latter just proves the transition.
+    // Two shapes prove the screen's CONTENT was checked, not just its route:
+    //   - the suite OPENS ON it (`is on [Registration] page`), and
+    //   - it asserts an element NAMESPACED to it (`see [Registration:Submit] button`) — the
+    //     namespace names the screen, so the assertion is about that screen by construction.
+    // Only the first counted, so a scenario that navigated there and then asserted the screen's
+    // own elements was still reported "covered only by a page-nav assertion" (#630). The field
+    // report's hypothesis — that the parser reads one line after the nav and stops — is still not
+    // what happens: there is no line window, and both shapes are matched over the whole scenario.
     const contentCovered = refs.some((s) =>
       [...s.haystack.matchAll(/\bis on \[([^\]]+)\]/g)]
-        .some((m) => sameScreenName(slug, m[1].split(':')[0])));
+        .some((m) => sameScreenName(slug, m[1].split(':')[0]))
+      || [...s.haystack.matchAll(/\bsee \[([^\]:]+):[^\]]+\]/g)]
+        .some((m) => sameScreenName(slug, m[1])));
     if (!contentCovered) underCovered.push({ route, slug });
   }
-  return { downstreamRoutes: routes, underCovered };
+  return { downstreamRoutes: routes, underCovered, absent };
 }
 
 // ---------- #4 Manual-oracle ----------

package/src/harness/run-manifest.ts

@@ -0,0 +1,254 @@
+/**
+ * Run-manifest — which scenarios does a QA edit actually oblige us to re-run?
+ *
+ * The problem it serves: the JSON reporter writes ONE file per target, named only for the unit +
+ * platform + env, so a subset re-run overwrites the full run's results. `sungen results merge`
+ * restores the lost half, but only if the caller knew to back the file up first — and only after
+ * the caller decided WHICH cases to run. This module answers the second question deterministically
+ * so `run-test --change-only` is a computation, not a guess.
+ *
+ * Sibling of `manifest.ts`, deliberately not an extension of it: that one hashes spec.md sections
+ * to decide what to REGENERATE, this one hashes the compiled inputs to decide what to RE-RUN. Same
+ * conventions (deterministic hashing, `.sungen/` storage, a plan object), different question.
+ *
+ * The bias is fixed and one-directional: when an edit cannot be attributed to specific scenarios,
+ * EVERY scenario is selected. Over-running costs minutes; under-running reports a scenario green
+ * that never re-ran after the change that broke it, which is the failure this whole family of
+ * guards exists to prevent.
+ *
+ * Storage: `.sungen/run-manifest/<slug>.json`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import yaml from 'yaml';
+import { featureFilesFor, reportSlug } from './unit-paths';
+import { readTextFile } from './read-text';
+import { GherkinParser } from '../generators/gherkin-parser';
+
+const sha = (s: string): string => createHash('sha256').update(s).digest('hex').slice(0, 16);
+
+/** Mirrors SelectorResolver.generateKey — a `[Ref]` becomes this before the YAML lookup. */
+const refToKey = (label: string): string => label.normalize('NFC').toLowerCase().trim().replace(/\s+/g, ' ');
+
+export interface RunManifest {
+  unit: string;
+  recordedAt: string;
+  /** scenario title → hash of its whole block (tags + steps) */
+  scenarios: Record<string, string>;
+  /** selectors.yaml key → hash of that entry */
+  selectorKeys: Record<string, string>;
+  /** test-data key → hash of that value */
+  dataKeys: Record<string, string>;
+  /** scenario title → the selector keys and data keys its steps touch */
+  deps: Record<string, { selectors: string[]; data: string[] }>;
+  /** hash of the Background block: a change there reaches every scenario */
+  background: string;
+  /**
+   * PROJECT-level inputs, `qa/<file>` → hash. These reach every scenario of every unit — app.yaml
+   * carries widget recipes and the behaviour profile, datasources.yaml the db/api endpoints,
+   * capabilities.yaml which drivers even load. Per-key attribution is not possible (a recipe change
+   * can alter any step's compilation), so a move here widens to the whole unit. They were the last
+   * known under-selection hole: edit app.yaml and the selection used to report "nothing changed".
+   */
+  globals: Record<string, string>;
+}
+
+export interface ChangeSelection {
+  unit: string;
+  /** scenario titles to re-run, in feature order */
+  scenarios: string[];
+  /** why each was selected — one short clause per title, for the operator */
+  reasons: Record<string, string>;
+  /** true when the whole unit was selected because the change could not be attributed */
+  all: boolean;
+  summary: { total: number; selected: number; firstRun: boolean };
+}
+
+const manifestPath = (cwd: string, unit: string): string =>
+  path.join(cwd, '.sungen', 'run-manifest', `${reportSlug(unit)}.json`);
+
+/** Flatten a YAML mapping to `key → hash(value)`; a non-mapping file yields one whole-file entry. */
+function hashTopLevel(file: string): Record<string, string> {
+  if (!fs.existsSync(file)) return {};
+  const text = readTextFile(file);
+  let doc: unknown;
+  try {
+    doc = yaml.parse(text);
+  } catch {
+    // Unparseable: attribute nothing, and let the caller widen to the whole unit rather than
+    // silently treating a broken file as "no change".
+    return { __unparseable__: sha(text) };
+  }
+  // An empty or comment-only file parses to null. That is an EMPTY mapping — nothing to attribute
+  // and nothing to widen on — not an unrecognised shape. (A test-data file holding only a comment
+  // made the first probe widen to all 18 scenarios.)
+  if (doc === null || doc === undefined) return {};
+  if (typeof doc !== 'object' || Array.isArray(doc)) return { __whole__: sha(text) };
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(doc as Record<string, unknown>)) {
+    out[refToKey(k)] = sha(JSON.stringify(v ?? null));
+  }
+  return out;
+}
+
+/** Read the unit's compiled inputs and fingerprint them. */
+export function buildRunManifest(cwd: string, unitDir: string, unit: string): RunManifest {
+  const parser = new GherkinParser();
+  const scenarios: Record<string, string> = {};
+  const deps: RunManifest['deps'] = {};
+  const bgParts: string[] = [];
+
+  for (const file of featureFilesFor(unitDir, unit)) {
+    const parsed = parser.parseFeatureFile(file);
+    if (parsed.background?.steps?.length) {
+      bgParts.push(parsed.background.steps.map((s) => `${s.keyword} ${s.text}`).join('\n'));
+    }
+    for (const sc of parsed.scenarios) {
+      const block = [...(sc.tags || []), ...sc.steps.map((s) => `${s.keyword} ${s.text}`)].join('\n');
+      scenarios[sc.name] = sha(block);
+      const sel = new Set<string>();
+      const dat = new Set<string>();
+      for (const st of sc.steps) {
+        if (st.selectorRef) sel.add(refToKey(st.selectorRef));
+        if (st.parentRef) sel.add(refToKey(st.parentRef));
+        if (st.childRef) sel.add(refToKey(st.childRef));
+        if (st.dataRef) dat.add(refToKey(st.dataRef));
+      }
+      deps[sc.name] = { selectors: [...sel].sort(), data: [...dat].sort() };
+    }
+  }
+
+  const selDir = path.join(unitDir, 'selectors');
+  const dataDir = path.join(unitDir, 'test-data');
+  const collect = (dir: string): Record<string, string> => {
+    if (!fs.existsSync(dir)) return {};
+    const merged: Record<string, string> = {};
+    for (const f of fs.readdirSync(dir).filter((n) => /\.ya?ml$/.test(n)).sort()) {
+      Object.assign(merged, hashTopLevel(path.join(dir, f)));
+    }
+    return merged;
+  };
+
+  // Project-level config lives beside the units, not inside them.
+  const qaDir = path.join(cwd, 'qa');
+  const globals: Record<string, string> = {};
+  for (const name of ['app.yaml', 'datasources.yaml', 'capabilities.yaml']) {
+    const f = path.join(qaDir, name);
+    if (fs.existsSync(f)) globals[`qa/${name}`] = sha(readTextFile(f));
+  }
+
+  return {
+    unit,
+    recordedAt: new Date().toISOString(),
+    scenarios,
+    selectorKeys: collect(selDir),
+    dataKeys: collect(dataDir),
+    deps,
+    background: sha(bgParts.join('\n---\n')),
+    globals,
+  };
+}
+
+export function readRunManifest(cwd: string, unit: string): RunManifest | null {
+  const p = manifestPath(cwd, unit);
+  // Absent baseline is the FIRST-RUN case, not an error — selectChanged widens to the whole unit.
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(readTextFile(p)) as RunManifest; } catch { return null; }
+}
+
+export function writeRunManifest(cwd: string, unit: string, m: RunManifest): string {
+  const p = manifestPath(cwd, unit);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(m, null, 2));
+  return p;
+}
+
+/** Keys whose hash differs, was added, or disappeared. */
+function movedKeys(before: Record<string, string>, after: Record<string, string>): Set<string> {
+  const moved = new Set<string>();
+  for (const k of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (before[k] !== after[k]) moved.add(k);
+  }
+  return moved;
+}
+
+/**
+ * Which scenarios must re-run, given the recorded manifest and the current inputs.
+ *
+ * A selector key matches a step's `[Ref]` either exactly or as one of the resolver's suffixed
+ * forms (`key--button`, `key--3`), because that is how the lookup itself resolves.
+ */
+export function selectChanged(
+  before: RunManifest | null,
+  after: RunManifest,
+  /**
+   * Run-affecting files an outside source (git) reports as changed. Passed in rather than read here
+   * so this function stays pure and testable; the CLI gathers the evidence. Non-empty + an
+   * otherwise-empty selection means something changed that per-key hashing cannot see (a rename, a
+   * new file shape) — unattributable, so it widens like the other unattributable cases.
+   */
+  externalChanged: string[] = []
+): ChangeSelection {
+  const titles = Object.keys(after.scenarios);
+  const selectAll = (reason: string): ChangeSelection => ({
+    unit: after.unit,
+    scenarios: titles,
+    reasons: Object.fromEntries(titles.map((t) => [t, reason])),
+    all: true,
+    summary: { total: titles.length, selected: titles.length, firstRun: !before },
+  });
+
+  if (!before) return selectAll('no previous run recorded');
+  const movedGlobals = movedKeys(before.globals || {}, after.globals || {});
+  if (movedGlobals.size) {
+    return selectAll(`project config changed (${[...movedGlobals].join(', ')}) — it reaches every scenario`);
+  }
+  if (before.background !== after.background) return selectAll('the Background changed — it runs before every scenario');
+  if (after.selectorKeys.__unparseable__ || after.dataKeys.__unparseable__) {
+    return selectAll('a selectors/test-data file could not be parsed, so the edit cannot be attributed');
+  }
+  if (after.selectorKeys.__whole__ || after.dataKeys.__whole__) {
+    const movedWhole = movedKeys(before.selectorKeys, after.selectorKeys).size
+      || movedKeys(before.dataKeys, after.dataKeys).size;
+    if (movedWhole) return selectAll('a selectors/test-data file is not a key mapping, so the edit cannot be attributed');
+  }
+
+  const movedSel = movedKeys(before.selectorKeys, after.selectorKeys);
+  const movedDat = movedKeys(before.dataKeys, after.dataKeys);
+  const touches = (key: string, dep: string): boolean => key === dep || key.startsWith(`${dep}--`);
+
+  const reasons: Record<string, string> = {};
+  for (const title of titles) {
+    if (before.scenarios[title] !== after.scenarios[title]) {
+      reasons[title] = before.scenarios[title] ? 'its steps or tags changed' : 'new scenario';
+      continue;
+    }
+    const dep = after.deps[title] || { selectors: [], data: [] };
+    const sel = [...movedSel].filter((k) => dep.selectors.some((d) => touches(k, d)));
+    if (sel.length) { reasons[title] = `selector changed: ${sel.slice(0, 3).join(', ')}`; continue; }
+    const dat = [...movedDat].filter((k) => dep.data.some((d) => touches(k, d)));
+    if (dat.length) { reasons[title] = `test-data changed: ${dat.slice(0, 3).join(', ')}`; continue; }
+  }
+
+  let selected = titles.filter((t) => reasons[t]);
+
+  // Git cross-check. Per-key hashing is blind to structural moves — a renamed selectors file, a new
+  // file shape, an encoding change — because the keys simply appear or vanish. When an outside
+  // source reports run-affecting files changed and we attributed NOTHING, that is the same
+  // unattributable case as an unparseable YAML, so it widens rather than reporting "all current".
+  if (!selected.length && externalChanged.length) {
+    return selectAll(
+      `git reports ${externalChanged.length} run-affecting file(s) changed (${externalChanged.slice(0, 3).join(', ')}) `
+      + 'that per-key hashing could not attribute'
+    );
+  }
+
+  return {
+    unit: after.unit,
+    scenarios: selected,
+    reasons,
+    all: false,
+    summary: { total: titles.length, selected: selected.length, firstRun: false },
+  };
+}