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

package/src/harness/defects.ts

@@ -0,0 +1,94 @@
+/**
+ * Defect records — `qa/defects/DEF-NNN-<slug>.md`, one project-wide folder. A scenario points at a
+ * record with `@known-defect:DEF-NNN`; the record points back at units, scenarios, claims and legacy
+ * TCs in its frontmatter. This module reads the records and checks both directions of that link.
+ * Drafting a record from a triage row lives in defect-draft.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export const DEFECT_STATUSES = ['open', 'fixed', 'verified', 'closed', 'wont-fix'] as const;
+export type DefectStatus = typeof DEFECT_STATUSES[number];
+
+export interface DefectRecord {
+  id: string;
+  title: string;
+  severity: string;
+  status: string;
+  units: string[];
+  scenarios: string[];
+  /** Project-relative path of the record file. */
+  file: string;
+}
+
+const DEF_FILE = /^(DEF-(\d+))-.*\.md$/;
+const KNOWN_DEFECT_TAG = /@known-defect:(DEF-\d+)\b/g;
+
+export function defectsDir(cwd: string): string {
+  return path.join(cwd, 'qa', 'defects');
+}
+
+function defectFiles(cwd: string): string[] {
+  const dir = defectsDir(cwd);
+  return fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => DEF_FILE.test(f)).sort() : [];
+}
+
+/** The next free id: one above the highest number on disk, zero-padded to 3. */
+export function nextDefectId(cwd: string): string {
+  const max = defectFiles(cwd).reduce((m, f) => Math.max(m, Number(f.match(DEF_FILE)![2])), 0);
+  return `DEF-${String(max + 1).padStart(3, '0')}`;
+}
+
+const list = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : []);
+
+/** Every record whose frontmatter parses; a malformed file is skipped, never thrown on. */
+export function readDefects(cwd: string): DefectRecord[] {
+  const out: DefectRecord[] = [];
+  for (const f of defectFiles(cwd)) {
+    const file = path.join(defectsDir(cwd), f);
+    try {
+      const fm = parseYaml(fs.readFileSync(file, 'utf-8').split(/^---\s*$/m)[1] ?? '') as Record<string, unknown> | null;
+      if (!fm || typeof fm !== 'object') continue;
+      out.push({
+        id: String(fm.id ?? f.match(DEF_FILE)![1]),
+        title: String(fm.title ?? ''),
+        severity: String(fm.severity ?? ''),
+        status: String(fm.status ?? ''),
+        units: list(fm.units),
+        scenarios: list(fm.scenarios),
+        file: path.relative(cwd, file),
+      });
+    } catch {
+      // unreadable frontmatter: not a record we can reason about
+    }
+  }
+  return out;
+}
+
+/**
+ * Advisory audit findings for one unit (never scored):
+ *   DEFECT-REF-MISSING     a `@known-defect:DEF-NNN` tag with no record file.
+ *   DEFECT-ORPHAN (info)   an OPEN record of this unit names a scenario the unit no longer has.
+ */
+export function defectLinkFindings(cwd: string, unitId: string, featureText: string, scenarioNames: string[]): string[] {
+  const records = readDefects(cwd);
+  const findings: string[] = [];
+  const known = new Set(records.map((r) => r.id));
+  const tagged = new Set([...featureText.matchAll(KNOWN_DEFECT_TAG)].map((m) => m[1]));
+  for (const id of tagged) {
+    if (!known.has(id)) {
+      findings.push(`DEFECT-REF-MISSING: \`@known-defect:${id}\` has no record in qa/defects/ — draft it with \`sungen defect draft --screen ${unitId}\`, or correct the id.`);
+    }
+  }
+  const names = new Set(scenarioNames);
+  for (const r of records) {
+    if (r.status !== 'open' || !r.units.includes(unitId)) continue;
+    for (const s of r.scenarios) {
+      if (!names.has(s)) {
+        findings.push(`DEFECT-ORPHAN (info): ${r.id} is open and names scenario "${s}", which ${unitId} no longer has — update the record's scenarios, or close it.`);
+      }
+    }
+  }
+  return findings;
+}

package/src/harness/manifest.ts

@@ -13,6 +13,7 @@ import * as path from 'path';
 import { createHash } from 'crypto';
 import { featureFilesFor, reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
+import { vpCodeOf } from './parse';
 
 export interface SpecSection { name: string; hash: string }
 export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string }
@@ -90,8 +91,7 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
     const s = line.match(/^Scenario:\s*(.*)$/);
     if (s) {
       const name = s[1].trim();
-      const code = name.match(/\bVP-[A-Z]+-\d+/i)?.[0];
-      out.push({ scenario: name, vpCode: code, section });
+      out.push({ scenario: name, vpCode: vpCodeOf(name).vpCode, section });
     }
   }
   return out;

package/src/harness/next-step.ts

@@ -16,9 +16,12 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
 import { reportSlug, featureFilesFor } from './unit-paths';
 import { readTextFile } from './read-text';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
+import { viewpointFileIsAiDraft } from './viewpoint-draft-header';
+import { readViewpointDeclaration } from './viewpoint-baseline';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -40,6 +43,8 @@ export interface UnitState {
   kind: 'screen' | 'flow' | 'api';
   hasSpec: boolean;
   hasViewpoint: boolean;
+  /** test-viewpoint.md carries `drafted-by: ai` — written by the AI, not yet accepted by a QA. */
+  viewpointIsAiDraft?: boolean;
   hasContract: boolean;
   hasFlowInventory: boolean;
   scenarioCount: number;
@@ -87,6 +92,29 @@ function countScenarios(unitDir: string, unit: string): number {
  * Everything the resolver needs, read from disk. `unitId` is the catalog id
  * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
  */
+const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
+
+/**
+ * Does the selector text resolve at least one element? A scaffold resolves none: the web one holds
+ * only the `page` route, the mobile one only header comments. Matching the WORD "placeholder" was
+ * wrong both ways (#868): it flagged a real file whose key names an input's placeholder text, and
+ * missed both scaffolds, which never contain it.
+ */
+function hasResolvedSelector(selectorText: string): boolean {
+  let doc: unknown;
+  try { doc = parseYaml(selectorText); } catch { return selectorText.trim().length >= 40; }
+  if (!doc || typeof doc !== 'object') return false;
+  // A real cell, not a marker left to be filled in. Numbers count (an id or index can be numeric).
+  const real = (v: unknown): boolean => (typeof v === 'string' || typeof v === 'number')
+    && String(v).trim() !== '' && !/^(?:todo|tbd|placeholder|replace me)$/i.test(String(v).trim());
+  return Object.values(doc as Record<string, unknown>).some((e) => {
+    if (!e || typeof e !== 'object') return false;
+    const { type, value, name, locator } = e as { type?: unknown; value?: unknown; name?: unknown; locator?: unknown };
+    // Every SelectorEntry shape: a CSS `locator`, or a non-page `type` with a value or a role name.
+    return real(locator) || (typeof type === 'string' && type !== 'page' && (real(value) || real(name)));
+  });
+}
+
 export function readUnitState(
   projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'],
 ): UnitState {
@@ -101,7 +129,7 @@ export function readUnitState(
   // `readTextFile` throws on a missing file, and every path here is legitimately absent at some
   // point in a unit's life — the resolver exists to report exactly that, so it must not crash on it.
   const read = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
-  const selectorText = selectorFiles.map((f) => read(path.join(selectorsDir, f))).join('\n');
+  const selectorTexts = selectorFiles.map((f) => read(path.join(selectorsDir, f)));
   const contractPath = path.join(req, 'flow-contract.yaml');
   const contractText = read(contractPath);
 
@@ -116,7 +144,9 @@ export function readUnitState(
   });
   const hasResults = specDirs.some((d) => {
     try {
-      return fs.readdirSync(d).some((f) => f.endsWith('-test-result.json'));
+      // `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env
+      // run (SUNGEN_ENV=staging) the env; both are runs (#868).
+      return fs.readdirSync(d).some((f) => RESULT_FILE.test(f));
     } catch { return false; }
   });
   let hasDeliverable = false;
@@ -131,6 +161,9 @@ export function readUnitState(
     unit, kind,
     hasSpec: exists(path.join(req, 'spec.md')),
     hasViewpoint: exists(path.join(req, 'test-viewpoint.md')),
+    // An id-less draft has nothing to accept: only the missing-yardstick step speaks for it.
+    viewpointIsAiDraft: viewpointFileIsAiDraft(path.join(req, 'test-viewpoint.md'))
+      && readViewpointDeclaration(path.join(req, 'test-viewpoint.md')) !== null,
     hasContract: exists(contractPath),
     // A contract WITHOUT `flows:` can only be scored per phase, which is a materially weaker
     // claim — so it is part of the state, not a detail.
@@ -139,8 +172,7 @@ export function readUnitState(
     hasSelectors: selectorFiles.length > 0,
     // A scaffolded selector file exists but resolves nothing; treating it as "done" is what
     // makes a run look further along than it is.
-    selectorsArePlaceholder: selectorFiles.length > 0
-      && (/TODO|PLACEHOLDER|REPLACE ME/i.test(selectorText) || selectorText.trim().length < 40),
+    selectorsArePlaceholder: selectorFiles.length > 0 && !selectorTexts.some(hasResolvedSelector),
     compiled, hasResults, hasDeliverable,
     assetsDrift: (() => {
       const d = checkAssetsDrift(projectRoot);
@@ -170,6 +202,7 @@ const REPAIRABLE = [
   'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'SPEC-CLAUSE-UNCOVERED',
   'TRIGGER-UNCOVERED', 'PERMISSION-PAIR-MISSING', 'VISIBILITY-PAIR-MISSING',
   'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
+  'UI-INVENTORY-MISSING', 'UI-INVENTORY-INCOMPLETE', 'UI-ITEM-UNCOVERED',
 ];
 
 /**
@@ -219,6 +252,15 @@ export function deriveSteps(s: UnitState): NextStep[] {
     });
     return out;
   }
+  // Before any generation: the AI drafts the viewpoint and audits it BEFORE it writes scenarios, so
+  // this is exactly where a draft would otherwise be accepted by the process that wrote it.
+  if (s.viewpointIsAiDraft) {
+    out.push({
+      kind: 'decide',
+      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
+      because: 'test-viewpoint.md is marked `drafted-by: ai` — nobody has reviewed it, so the ledger and traceability axes are held as unverified. A QA reviews the claims (adds what matters, deletes what does not), then accepts; the command records the baseline and removes the marker. A decision, not a step: an agent presents it and does not run it',
+    });
+  }
   if (s.scenarioCount === 0) {
     out.push({ kind: 'do', command: design, because: 'no scenarios exist yet' });
     return out;
@@ -234,7 +276,7 @@ export function deriveSteps(s: UnitState): NextStep[] {
     out.push({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' });
     return out;
   }
-  if (s.audit.viewpointBaselineStatus === 'changed') {
+  if (s.audit.viewpointBaselineStatus === 'changed' && !s.viewpointIsAiDraft) {   // the draft's own decide step is already above
     out.push({
       kind: 'decide',
       command: `sungen audit --screen ${s.unit} --accept-viewpoint`,

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/quality-gates.ts

@@ -8,6 +8,7 @@ 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 ----------
@@ -220,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

@@ -32,3 +32,28 @@ export function readTextFile(filePath: string): string {
 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) });
     }