@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/generators/test-generator/code-generator.ts

@@ -9,6 +9,7 @@ import { parseResetTier, DEFAULT_RESET_TIER } from './reset-tier';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities } from '../../harness/capability';
+import { isHandWritten } from '../../harness/parse';
 import { parseManualComments } from '../../exporters/scenario-merger';
 import { isPresencePlaceholderHybrid } from '../../exporters/manual-hybrid-oracle';
 import { findSyntaxError } from './utils/spec-syntax-check';
@@ -780,6 +781,12 @@ export class CodeGenerator {
 
     const renderedScenarios: Array<{ code: string; authRole?: string; noAuth?: boolean }> = [];
     for (const scenario of feature.scenarios) {
+      // @free / @impl:code / @proposed: implemented by hand-written code and proven by its trace —
+      // never compiled (DOS-14.8). The same predicate script-check uses, so the counts agree.
+      if (!scenario.stepsName && !scenario.hookType && isHandWritten([...(feature.tags || []), ...(scenario.tags || [])], feature.sourceFile)) {
+        console.log(`  ⊘ Skipped hand-written scenario: ${scenario.name}`);
+        continue;
+      }
       if (isManual(scenario.tags)) {
         // SG-W008 — two-direction rule for @manual scenarios:
         //  • HAS Gherkin steps → the Gherkin must be COMPLETE: Given/When/Then. A dangling
@@ -1187,9 +1194,9 @@ export class CodeGenerator {
   ): { preconditions: CapabilityPrecondition[]; casesDataset?: string } {
     this.stepMapper.setScenarioContext(stepsToMap);
 
-    // Data-driven (@cases): the scenario's {{col}} refs that are dataset *row columns* exist
-    // only at runtime — they resolve to a runtime get() (→ rowData.get) instead of a compile-time
-    // YAML lookup. A plain test-data key stays readable at compile time (#950).
+    // Data-driven (@cases): the scenario's {{col}} refs are dataset *row columns* that
+    // exist only at runtime — register them as captured so they resolve to a runtime
+    // get() (→ rowData.get) instead of compile-time YAML lookup.
     const casesTag = scenario.tags.find((t) => t.startsWith('@cases:'));
     const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
     if (casesDataset) {
@@ -1197,7 +1204,7 @@ export class CodeGenerator {
       for (const st of stepsToMap) {
         for (const m of (st.text || '').matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) refs.add(m[1]);
       }
-      this.stepMapper.bindCasesDataset(casesDataset, refs);
+      for (const r of refs) this.stepMapper.registerCaptured(r);
     }
 
     const preconditions = this.capabilityPreconditions(scenario);
@@ -1458,6 +1465,12 @@ export class CodeGenerator {
         console.log(`⊘ Skipped @manual feature: ${feature.name}`);
         continue;
       }
+      // A feature whose scenarios are all hand-written (a derived *.free.feature) emits no spec.
+      const own = feature.scenarios.filter((sc) => !sc.stepsName && !sc.hookType);
+      if (own.length && own.every((sc) => isHandWritten([...(feature.tags || []), ...(sc.tags || [])], feature.sourceFile))) {
+        console.log(`⊘ Skipped hand-written feature: ${feature.name}`);
+        continue;
+      }
 
       try {
         const generatedTest = await this.generateTest(feature, outputDir);

package/src/generators/test-generator/diagnostics.ts

@@ -49,8 +49,7 @@
  *             nothing for the query half to assert, so the step checks the PATH only. Not an
  *             error (the value may legitimately vary per environment), but the step asserts
  *             strictly less than it appears to
- *   SG-W015 — `see [X] card/item with {{n}}` where the value is a bare number (in @cases: on
- *             any row), or `see [X] row with {{n}}` whose @cases rows mix numbers and text: this compiles
+ *   SG-W015 — `see [X] card/item with {{n}}` where the value is a bare number: this compiles
  *             to a TEXT assertion (toHaveText('3')), NOT a count — an author reaching for
  *             "3 cards are shown" gets an assertion that can only pass if the card's text
  *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
@@ -68,18 +67,13 @@
  *   SG-E023 — the step carries an assertion clause (`matches "…"`, `contains`, `has text`, a state)
  *             but the generated code is a BARE VISIBILITY check: the clause was swallowed by the
  *             catch-all and the test would pass whatever the element says. Four separate defects
- *             have arrived this way, so the step compiles to a runtime throw instead. Also a
- *             trailing `is <word>` / `is not <word>` that is no state (`is on`, `is open`,
- *             `is not visible`), other than visibility itself (#911).
+ *             have arrived this way, so the step compiles to a runtime throw instead.
  *   SG-W017 — a step needs a selector-entry field the entry does not declare, so there is nothing
  *             honest to compile. Today: a table paginate step whose table declares no
- *             `pagination.next`/`.prev` (#712); `is expanded`/`is collapsed` on an entry declaring
- *             `expanded.state: none` (#911). The mirror of SG-W004 — that one reports a field
+ *             `pagination.next`/`.prev` (#712). The mirror of SG-W004 — that one reports a field
  *             written that nothing reads, this one a field a consumer needs that nobody wrote.
  *             Compiles the step to a loud runtime throw rather than guessing a locator, which is
  *             the #690 failure (a locator no page has, failing far from the cause).
- *             Also a web `fill [X] date-picker` whose entry locates a `<button>` (a calendar
- *             trigger) and names no `fill` recipe — `.fill()` cannot type into a button (#907).
  *   SG-W018 — a selectors.yaml entry declares an `nth:` the compiler cannot use (#720). `nth:` was
  *             the one entry field whose VALUE nothing checked: the key is known (SG-W004 quiet) and
  *             the `type:` is valid (SG-E027 quiet), so `nth: -1`, `nth: 'last'`, `nth: 1.5` and

package/src/generators/test-generator/patterns/types.ts

@@ -38,8 +38,6 @@ export type StateClause =
   | 'empty'
   | 'loading'
   | 'selected'
-  | 'expanded'
-  | 'collapsed'
   | 'sorted ascending'
   | 'sorted descending';
 

package/src/generators/test-generator/step-mapper.ts

@@ -13,9 +13,6 @@ import { isKnownSelectorType } from './utils/selector-type-validation';
 import { loadAppProfile, ResolvedAppProfile } from './app-profile';
 import { capabilityRegistry } from '../../capabilities/registry';
 
-/** Trailing `is <word>` that a visibility check honestly asserts (SG-E023 lets these through). */
-const VISIBILITY_WORDS = new Set(['visible', 'displayed', 'shown', 'present']);
-
 /**
  * The correction SG-W001 owes a project that gated a platform driver away.
  *
@@ -146,10 +143,6 @@ export class StepMapper {
     this.featurePlatform = featurePlatform;
     this.featurePath = featurePath;
     this.selectorResolver.setFeatureContext(featureName);
-    // Scenario-scoped data state (captured vars, the bound @cases dataset) of the previous feature's
-    // last scenario must not reach this feature's Background, which is mapped before any scenario
-    // resets it: a column `{{k}}` there made a plain `{{k}}` here unreadable (#950).
-    this.dataResolver.clearCaptured();
     // One StepMapper serves every feature in a run, so the step counter that names the
     // generated temporaries (`__t_<n>`) used to carry over between files: a screen's spec
     // then depended on how many steps the PRECEDING files happened to contain — i.e. on
@@ -219,23 +212,6 @@ export class StepMapper {
     this.dataResolver.registerCaptured(name);
   }
 
-  /**
-   * `@cases:<dataset>` — bind the scenario's dataset and register as runtime-only the refs that are
-   * its COLUMNS (each row supplies them). A plain key the base test-data defines stays a normal ref,
-   * so the compiler can still read its value (#950: registering every ref turned
-   * `row with {{rows_per_page}}` into a text assertion). A ref that is neither stays runtime-only,
-   * as before.
-   */
-  bindCasesDataset(dataset: string, refs: Iterable<string>): void {
-    const columns = new Set(this.dataResolver.setCasesDataset(dataset, this.featureName));
-    for (const ref of refs) {
-      const isColumn = columns.has(ref.split(/[.[]/)[0]);
-      if (isColumn || this.dataResolver.peekBaseValue(ref, this.featureName) === undefined) {
-        this.dataResolver.registerCaptured(ref);
-      }
-    }
-  }
-
   /**
    * Register the head of a variable bound by the feature's `@beforeAll` hook. Feature-scoped: it
    * survives setScenarioContext() so every scenario can read `{{head.*}}` as a runtime get().
@@ -315,11 +291,8 @@ export class StepMapper {
         /\bsees?\s+\[/.test(step.text) && /\bwith\b/.test(step.text)) {
       // peekBaseValue reads the literal from test-data even in runtime-data mode,
       // where resolveData returns an opaque marker (never numeric-looking).
-      // Every value the ref takes — a @cases column has one per row (#950).
       let resolvedValue: string | undefined;
-      try {
-        resolvedValue = this.dataResolver.peekValues(step.dataRef, this.featureName)?.find((v) => /^\d+$/.test(v.trim()));
-      } catch { /* unresolved at compile time → cannot judge */ }
+      try { resolvedValue = this.dataResolver.peekBaseValue(step.dataRef, this.featureName); } catch { /* unresolved at compile time → cannot judge */ }
       if (resolvedValue !== undefined && /^\d+$/.test(resolvedValue.trim())) {
         this.diagnostics.add('SG-W015',
           `\`see [${step.selectorRef}] ${step.elementType} with {{${step.dataRef}}}\` compiles to a TEXT assertion toHaveText('${resolvedValue.trim()}'), NOT a count of ${step.elementType}s. For a count use \`see [Ref] row with {{n}}\` / \`see [T] table with {{n}}\` (or a list "should have count"); if '${resolvedValue.trim()}' really is the ${step.elementType}'s text, assert it on a text/label element instead`,
@@ -682,8 +655,7 @@ export class StepMapper {
     if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
     // The base value, never resolveData(): in runtime mode that returns the marker, which carries
     // no query by construction — the diagnostic would then fire on every single step.
-    // Any value the ref takes — a @cases column has one per row (#950); the first without a query.
-    const value = this.dataResolver.peekValues(step.dataRef, this.featureName)?.find((v) => !/[?#]/.test(v));
+    const value = this.dataResolver.peekBaseValue(step.dataRef, this.featureName);
     if (value == null || /[?#]/.test(value)) return;
     this.diagnostics.add('SG-W014',
       `{{${step.dataRef}}} = "${value}" carries no query and no fragment, so this page assertion checks the PATH only. Pass a value like "?q=…" (or drop the "with" and let the step assert a bare page).`,
@@ -884,32 +856,13 @@ export class StepMapper {
       [/\b(?:should\s+have|has)\s+text\b/i, 'has text'],
     ];
     const hit = CLAUSES.find(([re]) => re.test(step.text));
-    // A trailing `is <word>` that is no state reached a bare visibility check the same way:
-    // `see [Start Date] button is expanded` asserted only that the button was shown, and passed with
-    // the calendar closed (#911); `is not visible` even asserted the OPPOSITE. Known states are
-    // SG-E021's (`step.state` is set). Only what a visibility check honestly asserts passes:
-    // `is visible` and its synonyms, and `is not hidden`. Storage's `is not empty` never gets here —
-    // this guard sees bare visibility code only.
-    let state: string | undefined;
-    if (!hit && !step.state) {
-      const m = maskRefsForMatching(step.text).replace(/\s+/g, ' ').replace(/ ?\.$/, '').toLowerCase()
-        .match(/ (?:is|are)( not| no longer)? ([a-z][\w-]*)$/);
-      const honest = m && (m[1] ? m[2] === 'hidden' : VISIBILITY_WORDS.has(m[2]));
-      if (m && !honest) state = `is${m[1] ?? ''} ${m[2]}`;
-    }
-    if (!hit && !state) return null;
-
-    const reason = state
-      ? `step "${step.text}" ends in \`${state}\`, which is not a sungen state, but compiled to a bare `
-        + `visibility check — the words were dropped, so the step would pass whenever the element is `
-        + `shown. Use a state the compiler asserts (is visible / is hidden / is disabled / is enabled / `
-        + `is checked / is unchecked / is selected / is focused / is empty / is expanded / is collapsed …, `
-        + `see the sungen-gherkin-syntax States list), or tag the scenario @manual.`
-      : `step "${step.text}" carries the clause \`${hit![1]}\` but compiled to a bare `
-        + `visibility check — the clause was dropped, so the assertion would pass whatever the element `
-        + `says. Either the phrasing is not the supported one for that clause (see the `
-        + `sungen-gherkin-syntax reference), or this sungen predates the step: check you are running `
-        + `the project-local compiler (\`npx sungen\`), not an older global one.`;
+    if (!hit) return null;
+
+    const reason = `step "${step.text}" carries the clause \`${hit[1]}\` but compiled to a bare `
+      + `visibility check — the clause was dropped, so the assertion would pass whatever the element `
+      + `says. Either the phrasing is not the supported one for that clause (see the `
+      + `sungen-gherkin-syntax reference), or this sungen predates the step: check you are running `
+      + `the project-local compiler (\`npx sungen\`), not an older global one.`;
     this.diagnostics?.add('SG-E023', reason, { feature: this.featureName, step: step.text });
     return {
       code: unsupportedStepCode(reason),

package/src/generators/test-generator/utils/data-resolver.ts

@@ -54,7 +54,6 @@ export class DataResolver {
   /** Clear captured vars — call at the start of each scenario. */
   clearCaptured(): void {
     this.capturedVars.clear();
-    this.casesRows = undefined;
   }
 
   // Vars bound by a `@beforeAll` hook's `@api:`/`@query:` preconditions. The hook runs before every
@@ -132,58 +131,6 @@ export class DataResolver {
     }
   }
 
-  /** The `@cases:<name>` dataset rows of the scenario being compiled (scenario-scoped). */
-  private casesRows?: Array<Record<string, unknown>>;
-
-  /**
-   * Bind the scenario's `@cases` dataset so its values can be judged at compile time, and return its
-   * column names (empty when the dataset cannot be read — the caller then treats every ref as
-   * runtime-only, as before #950).
-   */
-  setCasesDataset(dataset: string | undefined, featureName?: string): string[] {
-    this.casesRows = undefined;
-    if (!dataset || !featureName) return [];
-    try {
-      const rows = this.loadDataFile(featureName, dataset)?.[dataset];
-      if (Array.isArray(rows) && rows.length) {
-        // A scalar row is the `value` column — the runtime cases() wraps it the same way.
-        this.casesRows = rows.map((r) => (r && typeof r === 'object' && !Array.isArray(r) ? r : { value: r }));
-      }
-    } catch {
-      // unreadable dataset → no columns known
-    }
-    return this.casesRows ? [...new Set(this.casesRows.flatMap((r) => Object.keys(r)))] : [];
-  }
-
-  /**
-   * Every value a ref can take at run time, for compile-time judgements: the base value of a plain
-   * key, or — for a column of the scenario's `@cases` dataset — the value on EACH row (a row that
-   * lacks the column falls back to the base key, as `rowData.get()` does). A dataset column used to
-   * be opaque here, so `row with {{n}}` lost its count reading in @cases and the SG-W014 / SG-W015
-   * checks went silent (#950). Undefined when any value cannot be read.
-   */
-  peekValues(dataRef: string, featureName?: string): string[] | undefined {
-    const head = dataRef.split(/[.[]/)[0];
-    if (!this.casesRows?.some((row) => head in row)) {
-      const base = this.peekBaseValue(dataRef, featureName);
-      return base === undefined ? undefined : [base];
-    }
-    const out: string[] = [];
-    for (const row of this.casesRows) {
-      let value: unknown;
-      if (head in row) {
-        value = row;
-        for (const key of dataRef.split('.')) value = value && typeof value === 'object' ? (value as Record<string, unknown>)[key] : undefined;
-      } else {
-        try { value = this.resolveValue(dataRef, featureName); } catch { return undefined; }
-      }
-      if (typeof value === 'number' || typeof value === 'boolean') value = String(value);
-      if (typeof value !== 'string') return undefined;
-      out.push(value);
-    }
-    return out;
-  }
-
   private resolveValue(dataRef: string, featureName?: string): string {
     const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
     const data = this.loadDataFile(fileName, dataRef);

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -1024,8 +1024,8 @@ export class SelectorResolver {
     // `type: locator` had to be used instead, which no page of the reference says (issue #690).
     //
     // Handled HERE, above the generic `locator:`-field branch below, because that branch returns
-    // strategy 'css' — putting `upload` in the switch left the two spellings diverging for any
-    // entry that sets `locator:`. `withExtras` still stamps the declared
+    // strategy 'css' and drops `exact` — putting `upload` in the switch left the two spellings
+    // diverging for any entry that sets `locator:`. `withExtras` still stamps the declared
     // `selectorType`, so a consumer that needs to tell an upload from a plain locator still can.
     //
     // `exact` is inert for the upload action itself (`setInputFiles` takes no text filter), but it
@@ -1049,7 +1049,6 @@ export class SelectorResolver {
         value: locator,
         locator: locator,
         nth,
-        exact,
       });
     }
 
@@ -1114,18 +1113,11 @@ export class SelectorResolver {
           return resolvedRole;
         }
 
-      // `exact` carries no meaning for getByTestId itself, but text assertions on the entry read it
-      // (`label with {{v}}` → toHaveText vs toContainText). Dropping it here made `exact: true`
-      // inert on a testid entry while working on every other identity strategy (#910).
       case 'testid':
-        // `exact` travels with a testid entry too: the getByTestId locator ignores it, but a step
-        // that compares text (`label with {{v}}`) reads it to pick toHaveText over toContainText.
-        // It used to be dropped here alone, so `exact: true` on a testid entry did nothing (#910).
         return withExtras({
           strategy: 'testid',
           value,
           nth,
-          exact,
         });
 
       case 'label':

package/src/graph/board-human-actions.ts

@@ -0,0 +1,80 @@
+/**
+ * The human-only actions the graph does not hold ("Waiting for you", #954) — asked by the journey
+ * board and the delivery's decision check, read through THEIR functions (never restated here):
+ *
+ *   waive          a waiver the board re-surfaces: stale (the audit changed since) or untrusted (not
+ *                  in git HEAD) — readJourneyHumanAsks, the reconcile `runJourney` commits
+ *   decide         a gate-override that relaxes nothing because no human confirmed it (ineffective) —
+ *                  re-recorded with `journey --decide`, superseding it (loadUnitGateOverrides)
+ *   signoff        every other obligation holds — assertCanSignOff, as `journey --signoff` checks it
+ *   accept-in-run  a decision recorded during the run — evaluateDeliveryDecisions, as `delivery` runs it
+ * The sign-off and accept-in-run only once the frontier was not cut (the unit has run and nothing
+ * blocks before it). Read-only and advisory: whatever cannot be read adds nothing.
+ */
+import { formatCommand } from '../decisions/human-confirmation';
+import { waiveCommand } from '../decisions/legacy-waiver-migration';
+import { evaluateDeliveryDecisions } from '../harness/gates/delivery-decision-gate';
+import { IN_RUN_RULE } from '../harness/gates/in-run-decision-check';
+import { loadUnitGateOverrides, unitScopeOfDir } from '../harness/gates/unit-gate-overrides';
+import { readJourneyHumanAsks, signoffCommand } from '../harness/journey';
+import type { UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
+import { unitResultFiles } from './unit-artifact-probes';
+
+function journeyActions(projectRoot: string, s: UnitState, cut: boolean): HumanAction[] {
+  const asks = readJourneyHumanAsks(projectRoot, s.unit);
+  const out: HumanAction[] = asks.redecide.map((w) => ({
+    kind: 'waive',
+    command: waiveCommand(s.unit, w.obligation, w.reason),
+    reason: w.why === 'stale'
+      ? `the waiver on "${w.title}" is stale — the evidence changed since it was given, so it no longer counts; if it still holds, a human gives it again on a terminal (or repair the obligation)`
+      : `the waiver on "${w.title}" is not in git HEAD (decision.in-run), so it is not counted — if it is yours, confirm it on a terminal`,
+  }));
+  if (!cut && asks.canSignOff && asks.signoff.status !== 'given') {
+    out.push({
+      kind: 'signoff',
+      command: signoffCommand(s.unit),
+      reason: asks.signoff.status === 'stale'
+        ? `the sign-off of ${asks.signoff.at} is stale — the suite changed since; review the queue (\`sungen journey --screen ${s.unit}\`) and sign off again`
+        : `every other obligation is satisfied or waived — the human sign-off is the one gate \`sungen gate --phase deliver\` still waits on; review the queue (\`sungen journey --screen ${s.unit}\`, ${asks.report.needsYou.length} item(s)), then sign`,
+    });
+  }
+  return out;
+}
+
+function unconfirmedOverrides(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  return loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, unitDir)).ineffective.map((o) => {
+    const { humanAccepted: _ignored, ...payload } = o.entry.payload ?? {};
+    return {
+      kind: 'decide',
+      command: formatCommand(['sungen', 'journey', '--screen', s.unit, '--decide', 'gate-override', '--text', o.entry.text, '--reason', o.entry.reason,
+        '--payload', JSON.stringify(payload), '--supersedes', o.decisionId]),
+      reason: `the gate-override ${o.decisionId}${o.rule ? ` (${o.rule})` : ''} relaxes nothing: ${o.reason} — if it is meant, a human records it again on a terminal, superseding it`,
+    };
+  });
+}
+
+function inRunActions(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  const files = unitResultFiles(projectRoot, s.unit);
+  const refs = (files.length ? files : [null]).map((resultsPath) => ({ label: s.unit, unitName: s.unit, unitDir, resultsPath }));
+  const inRun = evaluateDeliveryDecisions(projectRoot, refs).inRun;
+  if (!inRun.length) return [];
+  const which = inRun.slice(0, 3).map((d) => `${d.kind} ${d.id}`).join(', ');
+  return [{
+    kind: 'accept-in-run',
+    command: formatCommand(['sungen', 'delivery', s.unit, '--accept-in-run']),
+    reason: `${inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}): ${which}${inRun.length > 3 ? ', …' : ''} — \`sungen delivery\` refuses them until they are committed through review and the tests re-run, or a human accepts them on a terminal`,
+  }];
+}
+
+/** The board's and the delivery's asks of a human for this unit. `cut`: the frontier stopped at a blocking node. */
+export function boardHumanActions(projectRoot: string, unitDir: string, s: UnitState, cut: boolean): HumanAction[] {
+  const out: HumanAction[] = [];
+  const add = (read: () => HumanAction[]): void => {
+    try { out.push(...read()); } catch { /* advisory: an unreadable board or decision adds nothing */ }
+  };
+  add(() => journeyActions(projectRoot, s, cut));
+  add(() => unconfirmedOverrides(projectRoot, unitDir, s));
+  if (!cut) add(() => inRunActions(projectRoot, unitDir, s));
+  return out;
+}

package/src/graph/evaluate-graph.ts

@@ -0,0 +1,97 @@
+/**
+ * The ready frontier of the `sungen next` graph (OES-10.1). Deterministic, read-only: the same
+ * unit state and test-case states always give the same steps, in rank order.
+ *
+ *   open       active ∧ ¬satisfied (a test-case node is open when at least one case is)
+ *   frontier   open ∧ (every `requires` satisfied ∨ ¬blocking)
+ *   cut        an open blocking node ends the walk — nothing ranked after it is offered, except a
+ *              node's instances that `surfacesPastCut` (a hard contract verdict, #940), which follow
+ *              the cutting step and never cut themselves
+ *
+ * `--case <id>` (`testCase` option): the frontier is that case's test-case nodes plus the blocking
+ * unit nodes before them; non-blocking unit advice is left to the unit view. A `caseOnly` test-case
+ * node speaks only there (its unit-level decision is in the unit view already).
+ *
+ * evaluateHumanActions reads the SAME walk for "Waiting for you" (#954): the human-only actions behind
+ * the offered steps, and whether the walk was cut.
+ */
+import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
+import type { NodeDecl, StepCore } from './node-decl';
+import type { TestCaseState } from './test-case-state-shape';
+
+export interface EvaluateOptions {
+  /** Only this test case's nodes (plus the blocking unit nodes before them). */
+  testCase?: string;
+}
+
+function withMeta(node: NodeDecl, core: StepCore, testCase?: string): NextStep {
+  return {
+    ...core,
+    nodeId: node.id,
+    granularity: node.granularity,
+    ...(testCase ? { testCase } : {}),
+    ...(node.gates.length ? { gates: [...node.gates] } : {}),
+  };
+}
+
+/** The cases open at a test-case node, in their given order; none without test-case states. */
+function openCases(node: NodeDecl, s: UnitState, tcStates: TestCaseState[] | undefined, only?: string): TestCaseState[] {
+  if (node.granularity !== 'test-case' || !tcStates) return [];
+  return tcStates.filter((tc) => (!only || tc.id === only) && node.active(s, tc) && !node.satisfied(s, tc));
+}
+
+/** One offered step and what produced it: the node, and the cases open at it (test-case nodes). */
+interface Offered { node: NodeDecl; step: NextStep; cases: TestCaseState[] }
+
+/** The walk both answers share: the offered steps in rank order, and whether an open blocking node cut it. */
+function walkFrontier(nodes: readonly NodeDecl[], s: UnitState, tcStates: TestCaseState[] | undefined, opts: EvaluateOptions): { offered: Offered[]; cut: boolean; cutBy?: NodeDecl } {
+  const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
+  const open = new Set<string>();
+  const offered: Offered[] = [];
+  let cut = false;
+  let cutBy: NodeDecl | undefined;
+  for (const node of ordered) {
+    if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
+    if (cut && !node.surfacesPastCut) continue;
+    let step: NextStep | null = null;
+    let cases: TestCaseState[] = [];
+    if (node.granularity === 'unit') {
+      if (!node.active(s) || node.satisfied(s) || (cut && !node.surfacesPastCut!(s))) continue;
+      if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
+    } else {
+      cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
+      if (!cases.length) continue;
+      const single = Boolean(opts.testCase);
+      step = withMeta(node, node.step(s, cases, single), single ? cases[0].id : undefined);
+    }
+    open.add(node.id);
+    const ready = node.requires.every((r) => !open.has(r));
+    if (step && (cut || ready || !node.blocking)) offered.push({ node, step, cases });
+    if (node.blocking && !cut) { cut = true; cutBy = node; }
+  }
+  return { offered, cut, ...(cutBy ? { cutBy } : {}) };
+}
+
+export function evaluateGraph(
+  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
+): NextStep[] {
+  return walkFrontier(nodes, s, tcStates, opts).offered.map((o) => o.step);
+}
+
+/**
+ * The HUMAN-ONLY actions of the same frontier ("Waiting for you", #954) — never a second walk with
+ * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
+ * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
+ * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title and `heldByCommand`
+ * its offered step's command (#966: "More appear once …" names what to run).
+ */
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string; heldByCommand?: string } {
+  const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
+  const actions = offered.flatMap(({ node, step, cases }) => (node.human
+    ? node.human(s, step, cases)
+    : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
+  const heldByCommand = cutBy ? offered.find((o) => o.node === cutBy)?.step.command : undefined;
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}), ...(heldByCommand ? { heldByCommand } : {}) };
+}

package/src/graph/human-action.ts

@@ -0,0 +1,33 @@
+/**
+ * A HUMAN-ONLY action of a unit — what `sungen next` lists under "Waiting for you" (#954) and `--json`
+ * carries as `humanActions`. An agent presents these and never runs them: they approve, sign, waive,
+ * classify or accept something on a person's behalf, and most refuse without a typed confirmation.
+ *
+ * `command` is canonical (`sungen …`, or a slash command); the text renders it as the project runs
+ * sungen (`npx sungen` with a local install). Placeholders a human fills are quoted (`"<name>"`, `"…"`)
+ * so a copied command never turns into a shell redirection.
+ */
+export type HumanActionKind =
+  | 'contract-approve'   // approve (or re-approve) the Test Contract — `sungen contract approve`
+  | 'accept-opaque'      // accept a reviewed opaque trace step — `contract approve --scenario <id> --accept-opaque`
+  | 'contract-commit'    // commit, or restore, a lock / approval decision through review
+  | 'contract-review'    // read the contract verdict on a terminal (it could not be built)
+  | 'accept-viewpoint'   // accept the changed viewpoint baseline — `sungen audit --accept-viewpoint`
+  | 'defect-draft'       // decide whether a product-defect candidate is a defect — `sungen defect draft`
+  | 'rerun-environment'  // re-run the reds the environment caused, once a human confirms it is up
+  | 'triage-classify'    // classify a red by hand as test-defect / environment — `sungen triage --case --as`
+  | 'signoff'            // the single human gate — `sungen journey --signoff`
+  | 'waive'              // give a waiver again — `sungen journey --waive`
+  | 'decide'             // record a decision — `sungen journey --decide`
+  | 'accept-in-run';     // deliver despite decisions recorded during the run — `sungen delivery --accept-in-run`
+
+export interface HumanAction {
+  command: string;
+  reason: string;
+  kind: HumanActionKind;
+  /**
+   * `command` is an instruction a person carries out by hand (commit through review, restore from git),
+   * not a command line to copy — the block marks it so, and never renders it as one.
+   */
+  instruction?: true;
+}

package/src/graph/locate-finding.ts

@@ -0,0 +1,93 @@
+/**
+ * Audit findings pinned to the test case they name, in the shared trace vocabulary (DOS-12.1, takumi
+ * T7): a citation `repo@SHA:path#Lx-Ly` plus a confidence label.
+ *
+ *   EXTRACTED 0.95  the finding names the case's VP-id, and only that case carries it
+ *   EXTRACTED 0.90  the finding quotes the case's full title, and only that case has it
+ *   INFERRED  0.60  the finding names the id's family (`VP-LOGIC` for `VP-LOGIC-003`), shared by ≤ 3 cases
+ *   AMBIGUOUS 0.40  the id or title it names is carried by several cases — each is cited
+ * A finding that names no case is located nowhere (it stays a unit-level finding).
+ *
+ * SHA is the HEAD commit when the file's bytes equal its HEAD blob; otherwise (no git, uncommitted
+ * edit) it is `worktree`, so a citation never points a commit at lines it does not hold. git runs
+ * twice per unit at most, with fixed arguments and a short timeout; a git failure only means `worktree`.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { gitBlobId, GUARD_GIT_TIMEOUT_MS } from '../contract/contract-git';
+import { idPrefix } from '../harness/parse';
+import type { ConfidenceLabel, LocatedFinding } from './test-case-state-shape';
+
+export interface CitableCase { id: string; unstableId?: true; title: string; absFile: string; lines: [number, number] }
+export interface GitCitationContext { repo: string; repoRoot: string; sha: string | null; headBlobs: Map<string, string> }
+
+/** git reports real paths (macOS `/var` is `/private/var`), so paths are compared real. */
+const real = (p: string): string => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+function git(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GUARD_GIT_TIMEOUT_MS }).toString('utf8');
+  } catch { return null; }
+}
+
+/** HEAD sha, repository root and HEAD blob ids of `files` — or a no-git context. */
+export function gitCitationContext(projectRoot: string, files: string[]): GitCitationContext {
+  const top = git(projectRoot, ['rev-parse', '--show-toplevel', 'HEAD'])?.trim().split('\n');
+  if (!top || top.length < 2 || !/^[0-9a-f]{40,64}$/.test(top[1])) {
+    return { repo: path.basename(projectRoot), repoRoot: real(projectRoot), sha: null, headBlobs: new Map() };
+  }
+  const repoRoot = real(top[0]);
+  const root = real(projectRoot);
+  const rels = files.map((f) => path.relative(root, real(f)));
+  const headBlobs = new Map<string, string>();
+  for (const line of (git(projectRoot, ['ls-tree', 'HEAD', '--', ...rels]) ?? '').split('\n')) {
+    const m = line.match(/^\d+ blob ([0-9a-f]+)\t(.+)$/);
+    if (m) headBlobs.set(path.resolve(root, m[2]), m[1]);
+  }
+  return { repo: path.basename(repoRoot), repoRoot, sha: top[1].slice(0, 12), headBlobs };
+}
+
+export function citationOf(ctx: GitCitationContext, absFile: string, lines: [number, number]): string {
+  const file = real(absFile);
+  let sha = 'worktree';
+  try {
+    if (ctx.sha && ctx.headBlobs.get(file) === gitBlobId(fs.readFileSync(file, 'utf8'))) sha = ctx.sha;
+  } catch { /* unreadable now — cite the working tree */ }
+  const rel = path.relative(ctx.repoRoot, file).split(path.sep).join('/');
+  return `${ctx.repo}@${sha}:${rel}#L${lines[0]}-L${lines[1]}`;
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** `id` as a whole token — `VP-UI-001` in "VP-UI-001 does not…", never inside `VP-UI-0012`. */
+const namesId = (text: string, id: string): boolean => new RegExp(`(?<![A-Za-z0-9-])${escapeRe(id)}(?![A-Za-z0-9-])`).test(text);
+/** A family token standing alone — `VP-LOGIC` but not the start of another case's `VP-LOGIC-004`. */
+const namesFamily = (text: string, family: string): boolean => new RegExp(`(?<![A-Za-z0-9-])${escapeRe(family)}(?![A-Za-z0-9])(?!-[A-Za-z0-9])`).test(text);
+
+/** Which cases a finding names, and how surely. */
+function matchesOf(finding: string, cases: CitableCase[]): { hits: CitableCase[]; label: ConfidenceLabel; score: number } | null {
+  const byId = cases.filter((c) => !c.unstableId && namesId(finding, c.id));
+  if (byId.length) return byId.length === 1 ? { hits: byId, label: 'EXTRACTED', score: 0.95 } : { hits: byId, label: 'AMBIGUOUS', score: 0.4 };
+  const byTitle = cases.filter((c) => c.title.length >= 8 && finding.includes(c.title));
+  if (byTitle.length) return byTitle.length === 1 ? { hits: byTitle, label: 'EXTRACTED', score: 0.9 } : { hits: byTitle, label: 'AMBIGUOUS', score: 0.4 };
+  const byFamily = cases.filter((c) => !c.unstableId && idPrefix(c.id) !== c.id && namesFamily(finding, idPrefix(c.id)));
+  if (byFamily.length && byFamily.length <= 3) return { hits: byFamily, label: 'INFERRED', score: 0.6 };
+  return null;
+}
+
+/** Every finding that names a case, keyed by the case's index in `cases`. */
+export function locateFindings(findings: string[], cases: CitableCase[], ctx: GitCitationContext): Map<number, LocatedFinding[]> {
+  const out = new Map<number, LocatedFinding[]>();
+  for (const text of findings) {
+    if (typeof text !== 'string' || !text.trim()) continue;
+    const m = matchesOf(text, cases);
+    if (!m) continue;
+    const head = text.split(':')[0].trim();
+    const code = /^[A-Z][A-Z0-9-]+$/.test(head) ? head : 'FINDING';
+    for (const c of m.hits) {
+      const i = cases.indexOf(c);
+      out.set(i, [...(out.get(i) ?? []), { code, text, citation: citationOf(ctx, c.absFile, c.lines), confidence: { label: m.label, score: m.score } }]);
+    }
+  }
+  return out;
+}