@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/harness/parse.ts

@@ -7,7 +7,8 @@
  */
 import * as fs from 'fs';
 import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
-import { readTextFile } from './read-text';
+import { readTextFile, readViewpointText } from './read-text';
+import { parsePriority, toEntryPriority } from './viewpoint-priority';
 import { featureFilesFor } from './unit-paths';
 
 export type Priority = 'high' | 'normal' | 'low' | 'unknown';
@@ -15,15 +16,57 @@ export type Priority = 'high' | 'normal' | 'low' | 'unknown';
 export interface ViewpointEntry {
   id: string;            // e.g. VP-DATA-CONSISTENCY
   priority: 'High' | 'Medium' | 'Low' | 'Unknown';
+  /** The declared priority word as written (`critical` · `high` · `medium` · `med` · `normal` · `low` ·
+   *  `deferred` · `skip`, which also stands for skipped / n/a / none / not applicable), kept because `priority` folds several of them together and the
+   *  PRIORITY-CONTRADICTED check needs them apart. Absent when no priority was declared. */
+  priorityWord?: string;
   reason: string;
   group?: 'Required' | 'Recommended' | 'Optional';
 }
 
+/**
+ * Whole SECTIONS that declare something ABOUT the checklist rather than listing claims or
+ * viewpoints — known issues, spec gaps, traceability indexes, references and appendices, changelogs. Shared by the atomic
+ * ledger (their rows are not claims to prove, #630) and the viewpoint-overview parser (an id
+ * listed there is a reference, not a declaration, #833). `UI Patterns Identified` is the author's
+ * pick of WHICH sungen-viewpoint patterns apply — a `Skip` row there is not a claim to cover (#841).
+ * A `How to run` / `Procedure` section — that exact heading, optionally naming one id — is a manual
+ * check's steps, not claims of its own (#855); `How to test the login flow` stays a normal section.
+ */
+export const NON_DECLARATION_SECTION = /^(?:(?:ui patterns?(?: identified)?|(?:how to (?:run|test|reproduce|verify)|(?:manual )?procedures?)(?:\s+(?:vp|fl)-[^\s:]+)?)\s*:?$|(?:known issues?|open questions?|spec gaps?|appendi(?:x|ces)|phụ lục|deferred|out of scope|viewpoint grouping|traceability|metadata|scope|journey phases?|revision history|references?|sources?|changelog)\b)/i;
+
+/**
+ * Every word a viewpoint row may declare as its priority — ONE list for the overview parser, the
+ * atomic ledger and the integrity checks, which each carried their own copy and all missed the
+ * `Skip` that the `sungen add` / `add-flow` scaffolds themselves suggest (#853). `deferred` and the
+ * not-applicable words are declarations as well: such a row is not a claim to cover.
+ */
+export const PRIORITY_WORDS = 'critical|high|medium|med|normal|low|deferred|skip(?:ped)?|n\\/a|none|not applicable';
+/** "Declared not applicable" — folded to `skip` so every consumer checks one word. */
+const NOT_APPLICABLE = /^(?:skip(?:ped)?|n\/a|none|not applicable)$/i;
+
+// The whole cell must BE the word (emphasis aside), as the old `| VP-… | high |` scan required:
+// "Low risk" or "Not high" declares no priority.
+const PRIORITY_WORD = new RegExp(`^[\\s*_\`]*(${PRIORITY_WORDS})[\\s*_\`.]*$`, 'i');
+/** Header names of a priority column, in the languages viewpoint files are written in. */
+const PRIORITY_HEADER = /^(?:priority|pri|level|severity|優先度?|độ ưu tiên|ưu tiên)(?:\s|\(|$)/i;
+
+/** A priority cell → the folded level plus the word as written. */
+function priorityOf(cell: string): { priority: ViewpointEntry['priority']; priorityWord?: string } {
+  const raw = cell.match(PRIORITY_WORD)?.[1].toLowerCase();
+  const word = raw && NOT_APPLICABLE.test(raw) ? 'skip' : raw;
+  const priority = toEntryPriority(parsePriority(cell));
+  return word ? { priority, priorityWord: word } : { priority };
+}
+
 export interface ScenarioInfo {
   name: string;
   vpCode?: string;       // VP-CART-001 style code in the scenario title
   category?: string;     // CART, LIST, VAL, ... (from the code)
   priority: Priority;
+  /** The priority tag as written, lower-cased, without `@` — keeps `critical` / `medium` / `med`, which
+   *  `priority` has no slot for, so PRIORITY-CONTRADICTED can fold it like the declared word (#861). */
+  priorityTag?: string;
   manual: boolean;
   thenCount: number;
   hasDataAssertion: boolean;  // a Then asserts {{data}} / contains / match data
@@ -39,8 +82,10 @@ export interface ScenarioInfo {
   exploration?: boolean;      // @exploration — a probe outside the official suite, exempt from source tracing
   deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
+  featureManual?: boolean;    // its Feature is tagged @manual — codegen skips the whole file (#835)
   /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
-  steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string }>;
+  /** `arg` = the step's data table, normalised (#817) — absent when the step has none. */
+  steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string; arg?: string }>;
   /**
    * The `.feature` this scenario was read from. A unit may hold several (`add --feature`), and
    * `scenarioIdReuse` scopes its uniqueness check to ONE file — so the sensor needs to know
@@ -106,7 +151,7 @@ function headingParts(line: string): { level: number; text: string } | null {
 
 export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   if (!fs.existsSync(filePath)) return [];
-  const text = readTextFile(filePath);
+  const text = readViewpointText(filePath);
   const lines = text.split('\n');
 
   const entries = new Map<string, ViewpointEntry>();
@@ -125,8 +170,7 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
         // and an id read with its emphasis markers still attached matches no scenario tag.
         const id = cells[0].replace(/[*`]/g, '').trim();
         if (isViewpointId(id) && !/^-+$/.test(cells[1])) {
-          const pr = /high/i.test(cells[1]) ? 'High' : /medium/i.test(cells[1]) ? 'Medium' : /low/i.test(cells[1]) ? 'Low' : 'Unknown';
-          entries.set(id.toUpperCase(), { id: id.toUpperCase(), priority: pr as any, reason: cells[2] });
+          entries.set(id.toUpperCase(), { id: id.toUpperCase(), ...priorityOf(cells[1]), reason: cells[2] });
         }
       }
     }
@@ -179,6 +223,52 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
     }
   }
 
+  // 3) ID-first tables (#833): per-axis tables such as `| ID | Priority | Input | Expected |`.
+  // A row whose FIRST cell is a viewpoint id declares that id — the same rows the
+  // PRIORITY-CONTRADICTED check always read, so the two readers now agree. Kept narrow on purpose,
+  // because a viewpoint file also holds tables that only MENTION ids:
+  //  - the id must be a `VP-`/`FL-` id, or belong to a family this file already declared above
+  //    (`MS-HP` in Priority Viewpoints → `MS-HP-001`); `TC-01`, `FR-001`, `ISO-27001` never are;
+  //  - reference sections (Known Issues, Traceability…) are skipped WITH their subsections, the
+  //    way the ledger inherits the exclusion (#657), and fenced blocks are skipped;
+  //  - the header is the row directly above a `|---|` separator (structure, not guessed words);
+  //    its Priority column (any position, any alias) gives the priority, else column 2 does, as
+  //    the old scan read it;
+  //  - `reason` stays empty: viewpoint reasons feed page-type detection, and these rows were never
+  //    entries before — the page type of an untouched file must not move.
+  const declaredFamilies = [...entries.keys()];
+  const familyOk = (id: string): boolean =>
+    /^(?:VP|FL)-/i.test(id) || declaredFamilies.some((f) => id.startsWith(`${f}-`) || id === f);
+  const isSeparator = (l: string): boolean => /^\|[\s|:-]+\|?$/.test(l) && l.includes('-');
+  let excludedAt: number | null = null;
+  let inFence = false;
+  let priorityCol = 1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (/^(```|~~~)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const head = headingParts(line);
+    if (head) {
+      if (excludedAt !== null && head.level > excludedAt) continue;          // subsection inherits
+      const text = head.text.replace(/[*`]/g, '').trim();
+      excludedAt = /^Priority Viewpoints/i.test(text) || NON_DECLARATION_SECTION.test(text) ? head.level : null;
+      continue;
+    }
+    if (excludedAt !== null || !line.startsWith('|') || isSeparator(line)) continue;
+    const cells = line.split('|').map((c) => c.trim()).filter((_, k, a) => k > 0 && k < a.length - 1);
+    if (isSeparator((lines[i + 1] ?? '').trim())) {                          // header row
+      const col = cells.findIndex((c) => PRIORITY_HEADER.test(c.replace(/[*`]/g, '').trim()));
+      priorityCol = col >= 0 ? col : 1;
+      continue;
+    }
+    const id = (cells[0] ?? '').replace(/[*`]/g, '').trim().toUpperCase();
+    if (!isViewpointId(id) || !familyOk(id)) continue;
+    const declared = priorityOf(cells[priorityCol] ?? '');
+    const existing = entries.get(id);
+    if (!existing) entries.set(id, { id, ...declared, reason: '' });
+    else if (!existing.priorityWord && declared.priorityWord) existing.priorityWord = declared.priorityWord;
+  }
+
   return [...entries.values()];
 }
 
@@ -199,6 +289,25 @@ function withBackground(sc: ParsedScenario, background?: ParsedScenario): Parsed
   return { ...sc, steps: [...bg, ...((sc.steps as ParsedStep[]) || [])] } as ParsedScenario;
 }
 
+/**
+ * The `VP-<CATEGORY>-<n>` / `FL-<PHASE>-<n>` code in a scenario title, and its category — the ONE
+ * reading of it; the manifest kept an older copy of this regex and recorded no code for
+ * VP-I18N-001, VP-LIST-DISPLAY-01, VP-AF02-01 or any FL- id (#889).
+ *
+ * Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
+ * compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
+ * not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
+ * Flows use journey-phase ids (FL-HP-001 / FL-ER-002) — the VP- anchor rejected them, so every
+ * flow scenario had NO category and the whole suite bucketed `other` (taxonomy=0%, #569).
+ * Segments may carry digits: the use-case framework numbers its flows (VP-AF02-01,
+ * VP-EF11-01 — one id per Alternate/Exception Flow), and `[A-Z]+` also silently truncated
+ * VP-I18N-001 to no category at all (the `18` broke the class mid-segment).
+ */
+export function vpCodeOf(title: string): { vpCode?: string; category?: string } {
+  const m = title.match(/\b(?:VP|FL)-([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-\d+/i);
+  return m ? { vpCode: m[0].toUpperCase(), category: m[1].toUpperCase() } : {};
+}
+
 function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const tags = sc.tags || [];
   const deferredToFlow = tags.includes('@deferred:flow');
@@ -223,18 +332,11 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const requiresCaps = tags.filter((t) => /^@requires:/i.test(t)).map((t) => t.slice('@requires:'.length).trim().toLowerCase()).filter(Boolean);
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
+  // Deliberately wider than `priority` (every priority word, any case): only PRIORITY-CONTRADICTED reads
+  // it, so `@critical` / `@High` are judged there without moving what select-by-ids or the score see.
+  const priorityTag = [...tags].reverse().find((t) => /^@(?:critical|high|medium|med|normal|low)$/i.test(t))?.slice(1).toLowerCase();
 
-  // Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
-  // compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
-  // not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
-  // Flows use journey-phase ids (FL-HP-001 / FL-ER-002) — the VP- anchor rejected them, so every
-  // flow scenario had NO category and the whole suite bucketed `other` (taxonomy=0%, #569).
-  // Segments may carry digits: the use-case framework numbers its flows (VP-AF02-01,
-  // VP-EF11-01 — one id per Alternate/Exception Flow), and `[A-Z]+` also silently truncated
-  // VP-I18N-001 to no category at all (the `18` broke the class mid-segment).
-  const codeMatch = sc.name.match(/\b(?:VP|FL)-([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-\d+/i);
-  const vpCode = codeMatch ? codeMatch[0].toUpperCase() : undefined;
-  const category = codeMatch ? codeMatch[1].toUpperCase() : undefined;
+  const { vpCode, category } = vpCodeOf(sc.name);
   // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
   const leadMatch = sc.name.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/);
   const vpId = leadMatch && isIdLike(leadMatch[1]) ? leadMatch[1].toUpperCase() : undefined;
@@ -246,22 +348,20 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const skeletonParts: string[] = [];
   const textParts: string[] = [sc.name];
   const stepTextParts: string[] = [];
-  const orderedSteps: Array<{ bucket: 'given' | 'when' | 'then'; text: string }> = [];
+  const orderedSteps: Array<{ bucket: 'given' | 'when' | 'then'; text: string; arg?: string }> = [];
 
   for (const step of sc.steps as ParsedStep[]) {
     const kw = step.keyword.trim();
     if (kw === 'Given' || kw === 'When' || kw === 'Then') last = kw;
     textParts.push(step.text);
     stepTextParts.push(step.text);
-    orderedSteps.push({ bucket: (kw === 'And' || kw === 'But' ? last : kw).toLowerCase() as 'given' | 'when' | 'then', text: step.text });
-    // normalized skeleton: keep [refs] (distinct targets = distinct tests),
-    // but neutralize {{vars}} and quoted values so EP/data families collapse.
-    const skel = step.text
-      .replace(/\{\{[^}]*\}\}/g, '{}')
-      .replace(/"[^"]*"/g, '""')
-      .replace(/\s+/g, ' ')
-      .trim()
-      .toLowerCase();
+    // The data table is part of what a step says (#817): `User see tab order:` with [FieldA]→[Cancel]
+    // and with [Save]→[Close] are different tests, and comparing step text alone called them exact
+    // duplicates and one oracle asserted N times. Kept OUT of `text`, which the claim/keyword sensors
+    // read as prose.
+    const arg = tableArg(step);
+    orderedSteps.push({ bucket: (kw === 'And' || kw === 'But' ? last : kw).toLowerCase() as 'given' | 'when' | 'then', text: step.text, ...(arg ? { arg } : {}) });
+    const skel = skeletonOf(step.text) + (arg ? ` ${skeletonOf(arg)}` : '');
     skeletonParts.push(`${kw === 'And' || kw === 'But' ? last : kw}:${skel}`);
 
     if (last === 'Then') {
@@ -286,6 +386,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     vpCode,
     category,
     priority,
+    priorityTag,
     manual,
     thenCount,
     hasDataAssertion: hasData,
@@ -309,9 +410,11 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
   if (!fs.existsSync(featurePath)) return [];
   const parser = new GherkinParser();
   const feature = parser.parseFeatureFile(featurePath);
+  // Kept apart from `manual` so the audit's accounting is unchanged; only `select` reads it.
+  const featureManual = (feature.tags || []).some((t: string) => /^@manual\b/i.test(t)) || undefined;
   return (feature.scenarios || [])
     .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
-    .map((s) => ({ ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath }));
+    .map((s) => ({ ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath, featureManual }));
 }
 
 /**
@@ -334,3 +437,24 @@ export function readUnitFeatureText(unitDir: string, unit: string): string {
     .map((p) => readTextFile(p))
     .join('\n');
 }
+
+/**
+ * Normalised skeleton of step text: keep [refs] (distinct targets = distinct tests), but neutralise
+ * {{vars}} and quoted values so EP/data families collapse.
+ */
+function skeletonOf(text: string): string {
+  return text
+    .replace(/\{\{[^}]*\}\}/g, '{}')
+    .replace(/"[^"]*"/g, '""')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+/** A step's data table as one comparable string — `<h1|h2 / c1|c2 / …>` — or undefined. */
+function tableArg(step: ParsedStep): string | undefined {
+  const t = step.dataTable;
+  if (!t || (!t.headers.length && !t.rows.length)) return undefined;
+  const rows = [t.headers, ...t.rows.map((r) => r.cells)].map((cells) => cells.map((c) => c.trim()).join('|'));
+  return `<${rows.join(' / ')}>`;
+}

package/src/harness/perf.ts

@@ -23,10 +23,8 @@
  *   units:
  *     place-order: { scenario_ms: 20000 }
  */
-import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseYaml } from 'yaml';
-import { readTextFile } from './read-text';
+import { readYamlConfig, warnUnreadableConfig } from './config-file';
 
 export interface PerfConfig {
   /** 0..100 — e.g. 75 for p75. */
@@ -51,12 +49,22 @@ export function perfConfigPath(projectRoot: string): string {
   return path.join(projectRoot, 'qa', 'perf.yaml');
 }
 
-/** Absent file → null (perf reporting is opt-in; nothing changes until configured). */
+/**
+ * Absent file → null (perf reporting is opt-in; nothing changes until configured).
+ *
+ * An UNREADABLE file is not that. Returning null for it drops the perf section out of the delivered
+ * matrix (`exporters/matrix/export.ts`) exactly as if no budgets had ever been declared — so a typo
+ * in qa/perf.yaml reads, in the deliverable, as "this project has no performance budgets". Say so.
+ */
 export function loadPerfConfig(projectRoot: string): PerfConfig | null {
   const p = perfConfigPath(projectRoot);
-  if (!fs.existsSync(p)) return null;
-  let raw: Record<string, unknown>;
-  try { raw = parseYaml(readTextFile(p)) as Record<string, unknown>; } catch { return null; }
+  const read = readYamlConfig<Record<string, unknown> | null>(p);
+  if (read.state === 'absent') return null;
+  if (read.state === 'unreadable') {
+    warnUnreadableConfig(p, read.error, 'perf budgets are not applied and the perf section is omitted from the delivered matrix');
+    return null;
+  }
+  const raw = read.value as Record<string, unknown>;
   if (!raw || typeof raw !== 'object') return null;
   const pctRaw = String(raw.percentile ?? 'p75').toLowerCase().replace(/^p/, '');
   const percentile = Math.min(100, Math.max(1, Number(pctRaw) || 75));

package/src/harness/quality-gates.ts

@@ -5,8 +5,10 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
 import { parseManualComments } from '../exporters/scenario-merger';
+import { commentLinesOf, isPresencePlaceholderHybrid, keywordStepsOf } from '../exporters/manual-hybrid-oracle';
 import { readTextFile } from './read-text';
 
 // ---------- #2 Downstream-scope ----------
@@ -57,12 +59,19 @@ function downstreamRoutes(specText: string): string[] {
 }
 
 /**
- * H5 — a @parallel stateful (cart-mutating) flow with NO per-scenario isolation is flaky: scenarios
- * share state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
+ * H5 — a stateful (cart-mutating) flow with NO per-scenario isolation is flaky: scenarios share
+ * state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
  * browser context, or a "Given … empty cart" background. Returns true when the risk is unmitigated.
+ *
+ * #759 — this used to require a literal `@parallel`, which made the gate miss the common case.
+ * Parallel is the DEFAULT (code-generator.ts: `isParallelFeature = !isSerialFeature`); `@parallel`
+ * only NAMES that default and changes no codegen, so an untagged stateful flow is isolated exactly
+ * like a tagged one and carries exactly the same risk. The tag that actually changes the emitted
+ * suite is `@serial` — one shared ordered page, where state carry-over is the point — so that is
+ * what exempts a flow now. Same reading as serialCascadeRisk() below, which already said so.
  */
 export function isolationRisk(featureText: string, stateful: boolean, collection = 'cart'): boolean {
-  if (!stateful || !/@parallel\b/i.test(featureText)) return false;
+  if (!stateful || /@serial\b/i.test(featureText)) return false;
   // What discharges the risk is isolation of THE MUTATED COLLECTION — so the cleanup tag has
   // to name it (`@cleanup:cart` for a cart; `@cleanup:registration` for a registration flow).
   // A cleanup of something else (`@cleanup:overlay`) leaves the shared state shared.
@@ -149,8 +158,12 @@ export function downstreamScope(
     // names the same screen under its human label (register ↔ [Registration]).
     const labelsOf = (s: ScenarioInfo): string[] =>
       [...s.haystack.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1].split(':')[0]);
+    // The slug is the route's last segment — in practice an ordinary noun (`order`, `detail`,
+    // `login`), so it is matched as a WORD (#779). `dis·order` is not a reference to `/account/order`,
+    // and crediting it downgraded a route nothing mentions from `absent` to merely `underCovered`.
+    // The full route stays a literal: a path is an identifier, not prose.
     const refs = scenarios.filter((s) =>
-      s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()) ||
+      keywordHit(s.haystack, slug) || s.haystack.includes(route.toLowerCase()) ||
       labelsOf(s).some((l) => sameScreenName(slug, l)));
     if (!refs.length) {
       // A scenario's haystack is its name + steps, so a route documented in a @manual scenario's
@@ -208,14 +221,15 @@ export function manualOracle(featureText: string): ManualOracleResult {
     //    Observable:/Oracle:/Expected: line (parseManualComments — the SAME parser the
     //    delivery exporter uses, so this gate can't drift from the exported cells).
     //    Prose paragraphs / rationale-only comments export EMPTY Steps + Expected.
+    //  • HAS a Then whose every assertion is a bare presence placeholder, with the real oracle
+    //    in the comments (#810) — the same hybrid wearing a Then (manual-hybrid-oracle.ts, the
+    //    SAME predicate as compile-time SG-W008).
     const hasGherkinSteps = /^\s*(Given|When|Then)\s/m.test(b);
+    const commentLines = commentLinesOf(b);
     let bad: boolean;
     if (hasGherkinSteps) {
-      bad = !/^\s*Then\s/m.test(b);
+      bad = !/^\s*Then\s/m.test(b) || isPresencePlaceholderHybrid(keywordStepsOf(b), commentLines);
     } else {
-      const commentLines = b.split('\n')
-        .filter((l) => /^\s*#/.test(l))
-        .map((l) => l.replace(/^\s*#\s?/, ''));
       const parsed = parseManualComments(commentLines);
       bad = !parsed.steps.length || !parsed.expected.length;
     }

package/src/harness/read-text.ts

@@ -17,12 +17,43 @@ import * as fs from 'fs';
  *
  * A Windows-authored spec is completely normal, so every harness parser that
  * reads a user file must go through here.
+ *
+ * A leading UTF-8 BOM is stripped for the same reason. It is what PowerShell's `Out-File` and
+ * several Windows editors write by default, and it is invisible in every editor — but it breaks a
+ * line-anchored `/^\s*Scenario:/` on line 1, and `JSON.parse` rejects it outright while npm and
+ * most other tools quietly ignore it. A file the rest of the ecosystem reads fine must not read as
+ * corrupt here.
  */
 export function readTextFile(filePath: string): string {
-  return fs.readFileSync(filePath, 'utf-8').replace(/\r\n?/g, '\n');
+  return fs.readFileSync(filePath, 'utf-8').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
 }
 
 /** `readTextFile` split into lines — the common case for line-anchored parsers. */
 export function readTextLines(filePath: string): string[] {
   return readTextFile(filePath).split('\n');
 }
+
+/**
+ * Drop HTML comments (`<!-- … -->`, multi-line too) — they are author notes and scaffold samples,
+ * never content. Newlines inside a comment are kept so every later line keeps its position (#841).
+ *
+ * Only a CLOSED comment is dropped. An unclosed `<!--` (a forgotten `-->`) stays text: dropping it
+ * to the end of the file would silently delete every declaration below it. A fenced code block is
+ * content, and so is a `<!--` written inside backticks: both are how a document SHOWS the syntax.
+ */
+export function stripHtmlComments(text: string): string {
+  // A comment body never holds another `<!--`: an opener with no `-->` before the next opener is
+  // the unclosed one, and must not reach a LATER comment's closer and eat everything between.
+  const blank = (s: string): string => s.replace(/(?<!`)<!--(?:(?!<!--)[\s\S])*?-->/g, (m) => m.replace(/[^\n]/g, ''));
+  // split() with a capture group keeps the fences at the odd indexes.
+  return text.split(/(^```[^\n]*\n[\s\S]*?^```[^\n]*$)/m).map((part, i) => (i % 2 ? part : blank(part))).join('');
+}
+
+/**
+ * `test-viewpoint.md` as every harness sensor must read it: normalised, comments removed, and
+ * '' when the unit has none. `sungen add` scaffolds its samples inside `<!-- -->`; read raw, an
+ * untouched scaffold declared VP-UI/VP-VAL/VP-LOGIC/VP-SEC and carried 12 phantom claims (#841).
+ */
+export function readViewpointText(filePath: string): string {
+  return fs.existsSync(filePath) ? stripHtmlComments(readTextFile(filePath)) : '';
+}

package/src/harness/script-check.ts

@@ -107,6 +107,12 @@ const ASSERTION_STEP_COMMENT = /^\s*\/\/\s*Assert\b/;
 // but as a bare substring it would also exempt a genuinely hollow step whose test-data or step
 // text happened to contain it.
 const NOOP_STEP_MARKER = /^\s*\/\/\s*App launched via wdio capabilities/;
+// The same kind of step on the web adapter, where the explanation IS the step comment: the
+// step-mapper compiles `Given User is on [Edit] dialog` (and its exit) to `// Enter dialog scope:
+// Edit` and no code, because it only re-roots the steps after it — the next assertion runs as
+// `page.getByRole('dialog', …).getByRole(…)`. A field unit reported 13 BYPASS, every one of them
+// this comment, and exited 2 on a correct suite (#881). Anchored to the whole marker line.
+const SCOPE_STEP_MARKER = /^\s*\/\/\s*(?:Enter|Exit) dialog scope(?::\s*.*)?$/;
 
 /** A spec comment line reduced to its text, for comparison against a compiler step comment. */
 const commentText = (line: string): string => line.trim().replace(/^\/\/\s?/, '').trim();
@@ -241,7 +247,7 @@ export function analyzeFaithfulness(
       const hasCode = region.some((l) => !isComment(l) && CODE_LINE.test(l));
       // A documented no-op emits its explanation INTO the step's region, so read the region
       // (not just the marker line) for it — see NOOP_STEP_MARKER.
-      if (hasCode || region.some((l) => NOOP_STEP_MARKER.test(l))) continue;
+      if (hasCode || region.some((l) => NOOP_STEP_MARKER.test(l)) || SCOPE_STEP_MARKER.test(body[markers[s]])) continue;
       if (tailAmbiguous && s === markers.length - 1) continue;
       hollowSteps.push({ test: title, step: body[markers[s]].trim().slice(0, 70) });
     }

package/src/harness/secret-scan.ts

@@ -11,6 +11,19 @@ import * as path from 'path';
 
 export interface SecretHit { file: string; line: number; reason: string }
 
+/** A yaml sink the scanner could not read. Not a hit — the absence of one it cannot vouch for. */
+export interface UnscannedFile { file: string; reason: string }
+
+/**
+ * The scan result, deliberately two lists rather than one.
+ *
+ * This is a security control, and its whole value is that "no hits" means "I looked". A file the
+ * scanner could not read used to be dropped by a bare `catch`, so an unread yaml and a yaml with no
+ * secrets produced the identical answer: clean. Returning `unscanned` alongside makes the caller
+ * hold both facts — what was found, and what the finding does not cover.
+ */
+export interface SecretScanResult { hits: SecretHit[]; unscanned: UnscannedFile[] }
+
 // High-confidence vendor token prefixes (very low false-positive rate).
 const VENDOR_PREFIXES = /\b(figd_[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{12,}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})/;
 // A secret-named key assigned a long, non-placeholder value.
@@ -51,16 +64,59 @@ function scanText(text: string, file: string): SecretHit[] {
 /** Scan a unit dir's committed yaml sinks for likely real secrets: test-data/*.yaml,
  *  mock/*.yaml (mock response bodies are a credential magnet — pasted DevTools
  *  responses carry real tokens), and api/*.yaml (endpoint catalogs carry headers). */
-export function scanTestDataSecrets(baseDir: string): SecretHit[] {
+export function scanTestDataSecrets(baseDir: string): SecretScanResult {
   const hits: SecretHit[] = [];
+  const unscanned: UnscannedFile[] = [];
+  const why = (e: unknown): string => (e instanceof Error ? e.message.split('\n')[0] : String(e));
+
   for (const sub of ['test-data', 'mock', 'api']) {
     const dir = path.join(baseDir, sub);
     if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
+
+    // A directory that cannot be LISTED is a directory that cannot be scanned. This used to throw
+    // out of the scanner and abort the whole `generate`/`delivery` run; report it in the same place
+    // a hit would appear instead, so the operator learns what the clean verdict does not cover
+    // rather than losing the deliverable to an unrelated permission fault.
+    let entries: string[];
+    try { entries = fs.readdirSync(dir); } catch (e) { unscanned.push({ file: sub, reason: why(e) }); continue; }
+
+    for (const f of entries) {
       if (!/\.ya?ml$/i.test(f)) continue;
       const p = path.join(dir, f);
-      try { hits.push(...scanText(fs.readFileSync(p, 'utf-8'), path.join(sub, f))); } catch { /* ignore */ }
+      const rel = path.join(sub, f);
+      let text: string;
+      // `readdirSync` listed this file, so it exists as a name. A read that fails here means a
+      // restricted mount, a dangling symlink, or a file removed between the two calls — never
+      // "there was nothing to read". Silently skipping it let a committed credential ship under an
+      // explicit "clean" verdict.
+      try { text = fs.readFileSync(p, 'utf-8'); } catch (e) { unscanned.push({ file: rel, reason: why(e) }); continue; }
+      hits.push(...scanText(text, rel));
     }
   }
-  return hits;
+  return { hits, unscanned };
+}
+
+/**
+ * The operator-facing lines for a scan result — one renderer, because `generate` and `delivery`
+ * had grown two copies of it and only one of them would have learned about `unscanned`.
+ *
+ * Empty array when there is nothing to say. The unscanned block is NOT folded into the hit block:
+ * "possible secret" and "not examined" are different claims, and printing the second under the
+ * first's heading invites it to be dismissed as another false positive.
+ */
+export function formatSecretScan(result: SecretScanResult, limit = 10): string[] {
+  const out: string[] = [];
+  if (result.hits.length) {
+    out.push('', '⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):');
+    for (const h of result.hits.slice(0, limit)) out.push(`   ${h.file}:${h.line} — ${h.reason}`);
+    if (result.hits.length > limit) out.push(`   … and ${result.hits.length - limit} more`);
+    out.push('   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.');
+  }
+  if (result.unscanned.length) {
+    out.push('', `⚠️  Secret scan could NOT read ${result.unscanned.length} committed yaml file(s) — they are NOT covered by the result above:`);
+    for (const u of result.unscanned.slice(0, limit)) out.push(`   ${u.file} — ${u.reason}`);
+    if (result.unscanned.length > limit) out.push(`   … and ${result.unscanned.length - limit} more`);
+    out.push('   Make them readable and re-run before treating this unit as scanned.');
+  }
+  return out;
 }

package/src/harness/select-by-ids.ts

@@ -0,0 +1,83 @@
+/**
+ * Select scenarios by test-case ID — backs `sungen select` and `run-test --ids` (#835).
+ *
+ * An ID means what it means everywhere else in the harness: `vpId`, the leading ID token of the
+ * scenario title (`VP-UI-001`, `MS-HP-001`, `VP0-001`). Matching is exact and case-insensitive —
+ * `VP-UI-001` never selects `VP-UI-0010` or `VP-UI-001-B` — and every ID that selects nothing
+ * runnable is reported, because the alternative is a 0-test run that reports green.
+ */
+import * as path from 'path';
+import { ScenarioInfo } from './parse';
+
+/**
+ * Escape scenario titles into one `-g` / `--mochaOpts.grep` regex. Full titles, not bare IDs:
+ * a title starts with its own ID, so it can only appear inside its own test's title — and a
+ * `@cases` row test (`<title> — <row label>`) still contains it.
+ */
+export function titlesToGrep(titles: string[]): string {
+  return titles.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+}
+
+export interface IdSelectionGroup {
+  /** Feature basename (`products`, `home-modal`) — names the spec and the result file. */
+  feature: string;
+  ids: string[];
+  titles: string[];
+  grep: string;
+}
+
+export interface IdSelection {
+  features: IdSelectionGroup[];
+  /** IDs no scenario carries, with near matches (`VP-VAL-001` → `VP-VAL-001-B`). */
+  unknown: Array<{ id: string; didYouMean: string[] }>;
+  /** IDs whose every scenario is manual, owned by a flow or waiting on a capability — nothing to run. */
+  notRunnable: Array<{ id: string; reason: string }>;
+}
+
+/** `"VP-UI-001, vp-ui-002 VP-UI-001"` → `['VP-UI-001', 'VP-UI-002']`. */
+export function parseIdList(raw: string): string[] {
+  return [...new Set(raw.split(/[\s,]+/).map((s) => s.trim().toUpperCase()).filter(Boolean))];
+}
+
+/** `VP-C-002.` → `VP-C-002`: the title token may carry trailing punctuation the user never types. */
+const idOf = (s: ScenarioInfo): string | undefined => s.vpId?.replace(/[.-]+$/, '') || undefined;
+
+function notRunnableReason(s: ScenarioInfo, enabledCaps: Set<string>): string | null {
+  if (s.deferredToFlow) return `owned by a flow${s.ownedByFlow ? ` (${s.ownedByFlow})` : ''} — run it there`;
+  if (s.featureManual) return 'its Feature is @manual — no spec is generated for it';
+  if (s.manual) return 'manual — no automated test exists';
+  // Compiled as `test.skip` while the capability is off: the run would report a skip, not a result.
+  const missing = (s.requiresCaps ?? []).filter((c) => !enabledCaps.has(c));
+  if (missing.length) return `needs capability ${missing.join(', ')} — compiled as a skip until \`sungen capability add ${missing.join(' ')}\``;
+  return null;
+}
+
+export function selectByIds(scenarios: ScenarioInfo[], ids: string[], unit: string, enabledCaps: Set<string> = new Set()): IdSelection {
+  const out: IdSelection = { features: [], unknown: [], notRunnable: [] };
+  const groups = new Map<string, IdSelectionGroup>();
+  const allIds = [...new Set(scenarios.map(idOf).filter((v): v is string => !!v))];
+
+  for (const id of ids) {
+    const hits = scenarios.filter((s) => idOf(s) === id);
+    if (hits.length === 0) {
+      const didYouMean = allIds.filter((v) => v.startsWith(`${id}-`) || id.startsWith(`${v}-`)).slice(0, 5);
+      out.unknown.push({ id, didYouMean });
+      continue;
+    }
+    const runnable = hits.filter((s) => !notRunnableReason(s, enabledCaps));
+    if (runnable.length === 0) {
+      out.notRunnable.push({ id, reason: notRunnableReason(hits[0], enabledCaps)! });
+      continue;
+    }
+    for (const s of runnable) {
+      const feature = s.sourceFile ? path.basename(s.sourceFile, '.feature') : unit;
+      const g = groups.get(feature) ?? { feature, ids: [], titles: [], grep: '' };
+      if (!g.ids.includes(id)) g.ids.push(id);
+      if (!g.titles.includes(s.name)) g.titles.push(s.name);
+      groups.set(feature, g);
+    }
+  }
+  for (const g of groups.values()) g.grep = titlesToGrep(g.titles);
+  out.features = [...groups.values()];
+  return out;
+}