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

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;
+}

package/src/harness/sensors.ts

@@ -12,6 +12,8 @@ import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
 import { readTextFile } from './read-text';
 import { keywordHit, hasKeyword } from './keyword-match';
+import { parsePriority } from './viewpoint-priority';
+import { countedAssertions } from './counted-assertions';
 
 // Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
 // compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
@@ -634,6 +636,9 @@ export interface TraceResult {
   mappedToOverview: number;
   withVpCodeRatio: number;
   mappedRatio: number;
+  /** Viewpoint IDs read from test-viewpoint.md. 0 = nothing to map to, so `mappedRatio` is not a
+   *  measurement — the scenario IDs were never checked (#832). */
+  overviewIds: number;
   note: string;
 }
 
@@ -645,6 +650,24 @@ export interface TraceResult {
  */
 const unprefixed = (id: string): string => id.replace(/^(?:VP|FL)-/i, '').toUpperCase();
 
+/**
+ * The traceability note, worded from the SAME ratio the audit's TRACE finding fires on —
+ * mapped / ALL scenarios (#852). It used to compare mapped against scenarios WITH an id, so 0 of
+ * 0 (no scenario yet, or none tagged) and 2 of 2 tagged out of 10 all read "Traceable." while
+ * the audit reported `TRACE: Traceable.` for a 0–20% mapping.
+ */
+function traceNote(total: number, withCode: number, mapped: number, declared: number, exampleId?: string): string {
+  if (declared === 0) {
+    return 'No viewpoint ID found in test-viewpoint.md — the file is missing, or none of its sections declares one — so the scenario IDs were not checked. Declarations are read from a `## Priority Viewpoints` table, `### Required / Recommended / Optional` lists, and tables whose first column is a `VP-`/`FL-` ID or an ID of a family declared there (Known Issues / Traceability / References sections are skipped).';
+  }
+  if (total === 0) return 'No scenarios yet — traceability is measured once the feature has scenarios.';
+  if (mapped >= total * 0.5) return 'Traceable.';
+  const example = exampleId ? ` (e.g. \`${exampleId}-001 …\`)` : '';
+  if (withCode === 0) return `No scenario carries a viewpoint ID — start each title with one of the IDs declared in test-viewpoint.md${example}.`;
+  if (mapped < withCode * 0.5) return 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).';
+  return `Only ${mapped} of ${total} scenarios carry a declared viewpoint ID — ${total - withCode} have no ID at all; tag them with the project's IDs${example}.`;
+}
+
 export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
   const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
   const overviewBare = new Set(viewpoints.map((v) => unprefixed(v.id)));
@@ -669,9 +692,10 @@ export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEnt
     mappedToOverview: mapped.length,
     withVpCodeRatio: scenarios.length ? withCode.length / scenarios.length : 0,
     mappedRatio: scenarios.length ? mapped.length / scenarios.length : 0,
-    note: withCode.length && mapped.length < withCode.length * 0.5
-      ? 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).'
-      : 'Traceable.',
+    overviewIds: overviewIds.size,
+    // With no ID read there is nothing to match against: telling the author to re-tag sends them
+    // to change scenarios that may be right (#832). Name the file and the sections read instead.
+    note: traceNote(scenarios.length, withCode.length, mapped.length, overviewIds.size, viewpoints[0]?.id),
   };
 }
 
@@ -733,6 +757,31 @@ const CLAIM_RULES: ClaimRule[] = [
     hint: 'swap `contains {{v}}` for `with {{v}}` on the continuity rows. A substring match cannot distinguish "unchanged" from "changed by adding a prefix" — and if the screen genuinely renders extra text around the value, say so in the title instead of claiming exactness.',
     severity: 'warn',
   },
+  {
+    // An ORDER claim ("sorted by date descending", "ties broken by last-updated") is invisible to
+    // a presence check: `see [List] table` passes whatever order the rows are in. It sits ahead of
+    // the generic rules so "all results sorted …" is judged as an ordering claim, not an all-claim.
+    // A tiebreaker is a Tier-1 guard in the tc-generation skill, yet no rule recognised it (#810).
+    claim: 'ordering/sort',
+    title: /\b(ascending|descending|sorted|sorts|sort order|ordered by|order by|in (?:chronological|alphabetical|reverse|numeric) order|(?:newest|oldest|latest|earliest|highest|lowest) first|tie-?break(?:s|er|ers)?|ties?)\b|降順|昇順|並び順|giảm dần|tăng dần|sắp xếp/,
+    proof: /match data|is sorted|sorted (?:ascending|descending)|\brow \d+\b|\.first\.|\.last\.|\[\d+\]\.|order by/,
+    need: 'an order-sensitive assertion (`table match data:` rows in the expected order, `is sorted ascending|descending`, or positional `row N` checks)',
+    hint: 'a presence check passes in any order — assert the rows in their expected sequence (`User see [T] table match data:`), or the column sort state; a tiebreak needs two rows sharing the primary key.',
+    severity: 'fail',
+  },
+  {
+    // A LIMIT claim ("never exceeds 10", "at most 5 files") is a count claim in disguise.
+    // Ahead of 'no-side-effect', whose negation+effect pattern would otherwise swallow
+    // "never exceeds 10 records" and ask for a duplicate-count proof.
+    claim: 'limit/cap',
+    // The quantity must be ≥2 ("at most ONE order" is a no-duplicate claim — left to the rules
+    // below) and not a duration ("up to 30 seconds" is a timing claim, not a cap).
+    title: /\b(?:never exceeds?|(?:does not|doesn['’]t|not) exceed|at most|no more than|up to|capped at|caps? at|maximum of|max(?:imum)?)\s+(?:\d{2,}|[2-9]|two|three|four|five|six|seven|eight|nine|ten)\b(?!\s*(?:ms|milliseconds?|s|secs?|seconds?|mins?|minutes?|hours?|days?)\b)|\b(?:never exceeds?|(?:does not|doesn['’]t) exceed) (?:the )?(?:limit|cap|quota|maximum)\b|以内|上限|tối đa/,
+    proof: /\bcount\b|tohavecount|table with|row with \{\{|match data|is at most|\bexactly\b|field with \{\{|\berror\b|invalid|is disabled/,
+    need: 'a count/boundary assertion (count is N, `is at most`, the N+1th input rejected or truncated)',
+    hint: 'assert the boundary itself — the count at the cap, or the value/error when one more is attempted — not just that the list or field is present.',
+    severity: 'fail',
+  },
   {
     claim: 'all/every/each',
     title: /\b(all|every|each)\b/,
@@ -900,7 +949,14 @@ export interface TaxonomyResult {
 
 const TAXONOMY_KNOWN = new Set(['LIST', 'PRODUCT', 'CART', 'FILTER', 'NAV', 'VAL', 'SEC']);
 
-const CATEGORY_SIGNALS: { cat: string; re: RegExp }[] = [
+/**
+ * Words of ACCESS — a title about who may reach something. They make the robustness/routing words
+ * below security evidence ("deep link without authentication"); alone those words describe routing.
+ */
+const ACCESS_CONTEXT = /\b(xss|sql|injection|without authentication|unauthenticated|unauthori[sz]ed|without an? (?:authenticated|valid|active) \w+|without (?:permission|login|logging in|signing in|an? account|access)|not (?:logged|signed) in|logged[- ]out|direct(?:ly)? access\w*|auth[- ]?guard|forbidden|\b403\b|(?:no|insufficient|missing) permissions?|permission required|session expired|expired session|tamper\w*)\b/;
+
+/** `requires`: the signal counts only when the title ALSO matches it (#888). */
+const CATEGORY_SIGNALS: { cat: string; re: RegExp; requires?: RegExp }[] = [
   { cat: 'FILTER', re: /\b(categor(y|ies)|sub-?categor\w*|expand\w*|collaps\w*|\bfacet\b|filter\w*|belongs? to)\b/ },
   { cat: 'CART', re: /\b(add(ed|ing)? to cart|added (dialog|modal|message|confirmation)|cart (page|table|line|item)|view cart|continue shopping|quantit)\b/ },
   { cat: 'PRODUCT', re: /\b(product detail|product-detail|view product|product page|same product|product name and price|product identity|detail product)\b/ },
@@ -912,9 +968,16 @@ const CATEGORY_SIGNALS: { cat: string; re: RegExp }[] = [
 // SEC, so the linter told QA to re-tag genuine auth-gate tests as navigation — diluting the
 // visibility of the security suite (QA field report, 3.2.23). The guard vocabulary below is
 // what makes the INTENT matchable, and GUARD_INTENT then wins over a mere observable.
-  { cat: 'SEC', re: /\b(xss|sql|injection|payload|without authentication|unauthenticated|without an? (?:authenticated|valid|active) \w+|direct(?:ly)? access\w*|deep[- ]link\w*|auth[- ]?guard|not skippable|without having (?:completed|submitted|logged)|remains? unauthenticated|\binert\b|tamper\w*|malformed|url parameter|query param\w*|falls? back|gracefull?y|without a crash|not[- ]found|\b404\b|special character|abuse)\b/ },
+  { cat: 'SEC', re: /\b(xss|sql|injection|payload|without authentication|unauthenticated|without an? (?:authenticated|valid|active) \w+|direct(?:ly)? access\w*|auth[- ]?guard|not skippable|without having (?:completed|submitted|logged)|remains? unauthenticated|\binert\b|tamper\w*|malformed|special character|abuse)\b/ },
+  // Robustness and routing words are SEC evidence only beside an ACCESS word. Alone they describe
+  // routing — "Unknown route shows the 404 page", "Deep link opens the item", "the tab from the url
+  // parameter" — and the linter told QA to re-tag those navigation tests as VP-SEC (#888).
+  { cat: 'SEC', re: /\b(deep[- ]link\w*|url parameter|query param\w*|falls? back|gracefull?y|without a crash|not[- ]found|\b404\b)\b/, requires: ACCESS_CONTEXT },
 ];
 
+const signalMatches = (c: { re: RegExp; requires?: RegExp }, title: string): boolean =>
+  c.re.test(title) && (!c.requires || c.requires.test(title));
+
 /**
  * Categories whose signal describes the test's INTENT/risk rather than the observable action.
  * When one of these matches, a competing observable-only category (NAV: "redirects", "navigates")
@@ -932,14 +995,19 @@ export function taxonomyLint(scenarios: ScenarioInfo[]): TaxonomyResult {
     if (!cat || !TAXONOMY_KNOWN.has(cat)) continue;
     checked++;
     const title = s.name.toLowerCase();
-    const matched = [...new Set(CATEGORY_SIGNALS.filter((c) => c.re.test(title)).map((c) => c.cat))];
+    const matched = [...new Set(CATEGORY_SIGNALS.filter((c) => signalMatches(c, title)).map((c) => c.cat))];
     if (matched.includes(cat)) continue;             // title supports its own category → fine
+    // A gate (`requires`) only stops a word from SUGGESTING its category. An author who already
+    // chose that category is supported by the word alone: a VP-SEC "Deep link to the filtered
+    // list …" stays SEC instead of being pushed toward FILTER (#888 review).
+    if (CATEGORY_SIGNALS.some((c) => c.cat === cat && c.requires && c.re.test(title))) continue;
     // The declared category may be an INTENT category whose signal this title spells
     // differently; never "correct" it toward a category that only names the observable.
     const suppressed = INTENT_OVER_OBSERVABLE[cat];
     const others = matched.filter((c) => c !== cat && !(suppressed && suppressed.has(c)));
     if (others.length === 1) {                        // unambiguous mismatch
-      const sig = CATEGORY_SIGNALS.find((c) => c.cat === others[0])!;
+      // The entry that MATCHED — a category can have several (SEC: guard words, gated robustness words).
+      const sig = CATEGORY_SIGNALS.find((c) => c.cat === others[0] && signalMatches(c, title))!;
       const m = title.match(sig.re);
       mislabeled.push({ name: s.name, current: cat, suggested: others[0], signal: m ? m[0] : others[0] });
     }
@@ -1011,9 +1079,8 @@ export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: strin
     if (!m) continue;
     const claimed = NUMBER_WORDS[m[1]] ?? Number(m[1]);
     if (!Number.isFinite(claimed) || claimed < 2) continue;
-    // Only value-bearing assertions count: `see [X] … with/contains {{v}}`. A visibility check
-    // does not demonstrate one of N values.
-    const asserted = (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length;
+    // Values, positive states and indicator presence count; plain text visibility does not (#866).
+    const asserted = countedAssertions(s.stepsText);
     if (asserted > 0 && asserted < claimed) out.push({ name: s.name, claimed, asserted, noun: m[2] });
   }
   return out;
@@ -1025,17 +1092,17 @@ export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: strin
  * The Priority-Viewpoints table is where release selection is supposed to come from. When the
  * table says a flow is `Low` and its scenario is tagged `@high`, a smoke run picks up work the QA
  * deliberately deprioritised — and nobody can tell which of the two was the decision (#622).
+ *
+ * Reads the SAME parse traceability does (`parseViewpointOverview`). It used to scan the raw text
+ * for any `| VP-… | high |` row, so one audit run "saw" an id for this check and not for
+ * traceability (#833), and a row in a Known Issues table could raise a contradiction.
  */
 export function priorityMismatches(
-  viewpointText: string, scenarios: ScenarioInfo[],
+  viewpoints: ViewpointEntry[], scenarios: ScenarioInfo[],
 ): Array<{ id: string; declared: string; tagged: string; scenario: string }> {
   const declared = new Map<string, string>();
-  for (const m of viewpointText.matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)) {
-    declared.set(m[1].toUpperCase(), m[2].toLowerCase());
-  }
+  for (const v of viewpoints) if (v.priorityWord) declared.set(v.id.toUpperCase(), v.priorityWord);
   if (declared.size === 0) return [];
-  // `medium` and `normal` are the same rank under different names in real documents.
-  const rank = (p: string): string => (p === 'medium' ? 'normal' : p);
   const out: Array<{ id: string; declared: string; tagged: string; scenario: string }> = [];
   for (const s of scenarios) {
     const id = (s.vpId ?? '').toUpperCase();
@@ -1043,11 +1110,14 @@ export function priorityMismatches(
     // The most specific declared row that prefixes this id.
     const key = [...declared.keys()].filter((k) => id.startsWith(k)).sort((a, b) => b.length - a.length)[0];
     if (!key) continue;
-    const want = rank(declared.get(key)!);
-    const got = rank(String(s.priority).toLowerCase());
-    // `critical` and `deferred` have no tag equivalent — nothing to contradict.
-    if (want === 'critical' || want === 'deferred') continue;
-    if (want !== got) out.push({ id: key, declared: declared.get(key)!, tagged: got, scenario: s.name });
+    // Both sides fold through the one priority reading (`critical` ≡ high, `medium`/`med` ≡ normal).
+    const want = parsePriority(declared.get(key)!);
+    // `deferred` and `skip` (declared not applicable, #853) have no tag equivalent — nothing to contradict.
+    if (want === 'deferred' || want === 'skip') continue;
+    // An untagged scenario states no priority, so it cannot contradict one (#861).
+    const tagged = s.priorityTag ?? (s.priority === 'unknown' ? undefined : String(s.priority));
+    if (!tagged) continue;
+    if (want !== parsePriority(tagged)) out.push({ id: key, declared: declared.get(key)!, tagged, scenario: s.name });
   }
   return out;
 }

package/src/harness/spec-branches.ts

@@ -194,7 +194,7 @@ export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: s
     if (s.manual) continue;                     // a procedure's oracle is prose
     const asserts = [...(s.steps ?? [])]
       .filter((st) => st.bucket === 'then')
-      .map((st) => st.text.toLowerCase().replace(/\s+/g, ' ').trim())
+      .map((st) => `${st.text} ${st.arg ?? ''}`.toLowerCase().replace(/\s+/g, ' ').trim())   // the table is the oracle too (#817)
       .sort();
     if (asserts.length === 0) continue;
     const key = asserts.join(' ; ');

package/src/harness/triage-signals.ts

@@ -0,0 +1,46 @@
+/**
+ * Triage signal library — the ordered message patterns `sungen triage` matches a red scenario's
+ * error against. Seeded from the repair rules (`harness/repair.ts`, driver-mobile `mobile-repair.ts`);
+ * the patterns are COPIED, not imported, because core never loads a driver at runtime. The parity
+ * check in tests/harness/triage-classification.run.ts keeps the environment rules in step.
+ *
+ * Order matters and is the classification order: environment first (nothing about the test or the
+ * app can be judged when the session never started), then test defects (the test never reached the
+ * app). Assertions are decided in triage.ts from the parsed Expected/Received, not here.
+ */
+export type SignalClass = 'environment' | 'test-defect';
+
+export interface TriageSignal {
+  id: string;
+  class: SignalClass;
+  match: RegExp;
+}
+
+export const TRIAGE_SIGNALS: TriageSignal[] = [
+  // --- environment: the run could not reach a usable app/session -----------------------------------
+  { id: 'env-network', class: 'environment', match: /net::ERR_[A-Z_]+|\bECONNREFUSED\b|\bENOTFOUND\b|\bEAI_AGAIN\b|\bETIMEDOUT\b/ },
+  // mirrors mobile-session-not-created
+  { id: 'env-session-not-created', class: 'environment', match: /A new session could not be created|session not created/i },
+  // mirrors mobile-driver-proxy-lost
+  { id: 'env-driver-proxy-lost', class: 'environment', match: /Could not proxy command to (?:the )?remote server|socket hang up|ECONNRESET/ },
+  // mirrors mobile-instrumentation-failed
+  { id: 'env-instrumentation-failed', class: 'environment', match: /instrumentation process (?:cannot|could not) be (?:initialized|started)|Cannot start the instrumentation process/ },
+  // mirrors mobile-chromedriver-mismatch
+  { id: 'env-chromedriver-mismatch', class: 'environment', match: /No Chromedriver found|chromedriver.*(?:version|mismatch)|Chrome version must be/i },
+  // mirrors mobile-webview-context-absent
+  { id: 'env-webview-context-absent', class: 'environment', match: /no WEBVIEW\/CHROMIUM context appeared within/ },
+  { id: 'env-auth-state-missing', class: 'environment', match: /storageState|\.auth\/[\w.-]+\.json|ENOENT[^\n]*\.auth/ },
+  { id: 'env-base-url-unresolved', class: 'environment', match: /Cannot navigate to invalid URL|baseURL (?:is )?(?:not set|undefined)|Invalid URL/ },
+  { id: 'env-browser-closed', class: 'environment', match: /Target page, context or browser has been closed|browserType\.launch/ },
+
+  // --- test defect: the test could not reach the element or its data -------------------------------
+  { id: 'test-strict-mode', class: 'test-defect', match: /strict mode violation/ },
+  { id: 'test-locator-unresolved', class: 'test-defect', match: /locator\.\w+: [^\n]*(?:Timeout|timeout)[^\n]*exceeded[\s\S]*waiting for |resolved to 0 elements/ },
+  { id: 'test-element-absent', class: 'test-defect', match: /no such element|Element not found:|An element could not be located/ },
+  { id: 'test-data-missing', class: 'test-defect', match: /Test data key not found:|@cases dataset "[^"]+" not found/ },
+  { id: 'test-step-unmatched', class: 'test-defect', match: /\[sungen\] step "[^"]*" matched no pattern|\bSG\d{3}\b/ },
+  { id: 'test-tap-intercepted', class: 'test-defect', match: /element click intercepted|is not clickable at point|element is obscured|intercepts pointer events/i },
+];
+
+/** A failure that is only Playwright's test-level timeout — no locator, no assertion detail (→ unclassified). */
+export const BARE_TIMEOUT = /^(?:Error:\s*)?Test timeout of \d+ms exceeded\.?$/;

package/src/harness/triage-unit.ts

@@ -0,0 +1,113 @@
+/**
+ * `sungen triage` IO: find a unit's feature(s) and result file(s), join them on the same seam
+ * delivery and the dashboard use (`mergeFeatureAndSpec` + `resolveResultVariants`), classify each
+ * scenario, and persist `.sungen/triage/<unit>.json`. Read-only apart from that one report file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseFeatureMetadata } from '../exporters/feature-parser';
+import { loadPlaywrightReport, resolveResultsPath } from '../exporters/playwright-report-parser';
+import { collectQaEnvSecretDenylist } from '../exporters/qa-env-secret-denylist';
+import { isSensitiveKey } from '../exporters/sensitive-key';
+import { resolveResultVariants } from '../exporters/result-variants';
+import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
+import { parseSpecFile } from '../exporters/spec-parser';
+import { loadTestData } from '../exporters/test-data-resolver';
+import type { ResolvedUnit } from '../cli/resolve-unit';
+import { classifyScenario, TriageClass, TriageRow } from './triage';
+
+export interface TriageReport {
+  unit: string;
+  generatedAt: string;
+  /** Result files read, relative to the project root. Empty → nothing has run yet. */
+  resultFiles: string[];
+  counts: Partial<Record<TriageClass, number>>;
+  rows: TriageRow[];
+}
+
+/**
+ * Values that must never reach a triage evidence line or a defect record: the resolved `${QA_*}`
+ * secrets AND the literal values of credential-named test-data keys — an assertion on a password
+ * field prints that value in its Expected/Received.
+ */
+export function unitSecrets(testData: Record<string, string>, cwd: string): string[] {
+  const literal = Object.entries(testData)
+    .filter(([k, v]) => isSensitiveKey(k) && typeof v === 'string' && v.length >= 3 && !v.includes('${'))
+    .map(([, v]) => String(v));
+  return [...new Set([...collectQaEnvSecretDenylist(testData, cwd).values, ...literal])].sort((a, b) => b.length - a.length);
+}
+
+function generatedDir(cwd: string, u: ResolvedUnit): string {
+  return path.join(cwd, 'specs', 'generated', u.unitId);
+}
+
+/**
+ * Every result file of one feature, labelled by variant: `<base>-test-result.json` (no label),
+ * `<base>-test-result.<os|env>[.<env>].json` (label = the middle part). A mobile unit has only
+ * per-OS files, so all of them are read rather than the first one found. Falls back to the shared
+ * lookup (incl. `test-results/results.json`) when the generated dir holds none.
+ */
+function resultFilesFor(cwd: string, genDir: string, base: string): Array<{ file: string; variant?: string }> {
+  const prefix = `${base}-test-result`;
+  const own = fs.existsSync(genDir)
+    ? fs.readdirSync(genDir).filter((f) => f.startsWith(prefix) && f.endsWith('.json')).sort()
+    : [];
+  if (own.length > 0) {
+    return own.map((f) => {
+      const variant = f.slice(prefix.length, -'.json'.length).replace(/^\./, '');
+      return { file: path.join(genDir, f), ...(variant ? { variant } : {}) };
+    });
+  }
+  const shared = resolveResultsPath(cwd, genDir, base);
+  return shared ? [{ file: shared }] : [];
+}
+
+export function triageUnit(cwd: string, u: ResolvedUnit): TriageReport {
+  const genDir = generatedDir(cwd, u);
+  const featuresDir = path.join(u.dir, 'features');
+  const features = fs.existsSync(featuresDir) ? fs.readdirSync(featuresDir).filter((f) => f.endsWith('.feature')).sort() : [];
+  const rows: TriageRow[] = [];
+  const resultFiles: string[] = [];
+
+  for (const f of features) {
+    const base = f.replace(/\.feature$/, '');
+    const files = resultFilesFor(cwd, genDir, base);
+    if (files.length === 0) continue;
+    const merged = mergeFeatureAndSpec(parseFeatureMetadata(path.join(featuresDir, f)), parseSpecFile(path.join(genDir, `${base}.spec.ts`)));
+    const dataFile = path.join(u.dir, 'test-data', `${base}.yaml`);
+    const testData = fs.existsSync(dataFile) ? loadTestData(dataFile) : {};
+    const secrets = unitSecrets(testData, cwd);
+
+    for (const { file, variant } of files) {
+      resultFiles.push(path.relative(cwd, file));
+      const results = loadPlaywrightReport(file);
+      for (const m of merged) {
+        for (const v of resolveResultVariants(m, results, testData)) {
+          const r = classifyScenario({ unit: u.unitId, title: `${m.feature.name}${v.nameSuffix}`, tags: m.feature.tags, result: v.result, variant }, secrets);
+          if (r) rows.push(r);
+        }
+      }
+    }
+  }
+
+  const counts: Partial<Record<TriageClass, number>> = {};
+  for (const r of rows) counts[r.class] = (counts[r.class] ?? 0) + 1;
+  return { unit: u.unitId, generatedAt: new Date().toISOString(), resultFiles, counts, rows };
+}
+
+export function triageReportPath(cwd: string, unitId: string): string {
+  return path.join(cwd, '.sungen', 'triage', `${unitId.replace(/\//g, '-')}.json`);
+}
+
+/** The last triage of a unit, or null when `sungen triage` has not run for it. */
+export function readTriageReport(cwd: string, unitId: string): TriageReport | null {
+  try { return JSON.parse(fs.readFileSync(triageReportPath(cwd, unitId), 'utf-8')) as TriageReport; } catch { return null; }
+}
+
+/** Persist under `.sungen/triage/<unit>.json` (a flow `flows/x` → `flows-x.json`); returns the path. */
+export function writeTriageReport(cwd: string, report: TriageReport): string {
+  const out = triageReportPath(cwd, report.unit);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+  return out;
+}

package/src/harness/triage.ts

@@ -0,0 +1,127 @@
+/**
+ * `sungen triage` — classify each red or flaky scenario of a run into exactly one class, with the
+ * rule that fired and one evidence line. Deterministic and read-only; it reports, it never gates.
+ *
+ * Order (first match wins):
+ *   1. known-defect        `@known-defect` / `@known-defect:<id>` — an expected red.
+ *   2. blocked-capability  `@manual:*` / `@requires:*`, or skipped by design.
+ *   3. environment         the session or network never gave the test a usable app.
+ *   4. test-defect         the test could not reach its element or data.
+ *   5. product-candidate   an assertion whose Expected and Received both exist and differ.
+ *   6. unclassified        anything else — left for the agent or QA, with the raw first message.
+ * A `passed` scenario that needed a retry is `flaky` (green, listed separately).
+ *
+ * 5 is tested before 3 and 4 in code: a parsed Expected/Received pair that differs means the app
+ * answered, which outranks any wrapper text (a test timeout around the assertion included).
+ *
+ * A bare test timeout (no locator, no assertion) is `unclassified` too: a slow environment, a page
+ * that hangs on a product bug and a test waiting on the wrong thing all print the same line.
+ *
+ * An assertion on an element that never appeared (`Received: <element(s) not found>`) is NOT a test
+ * defect: a wrong selector and a missing message look identical, so it is left for judgment rather
+ * than hiding a possible product bug behind "fix the selector".
+ */
+import { redactSecrets } from '../exporters/api-testcase-formatter';
+import { parseExpectedReceived } from '../exporters/playwright-report-parser';
+import type { PlaywrightResult } from '../exporters/types';
+import { BARE_TIMEOUT, TRIAGE_SIGNALS } from './triage-signals';
+
+export type TriageClass =
+  | 'known-defect' | 'blocked-capability' | 'environment' | 'test-defect' | 'product-candidate' | 'unclassified' | 'flaky';
+
+export interface TriageInput {
+  unit: string;
+  title: string;
+  tags: string[];
+  result?: PlaywrightResult;
+  /** Result-file variant (`android`, `ios`, an env name) when the unit has several. */
+  variant?: string;
+}
+
+export interface TriageRow {
+  unit: string;
+  scenario: string;
+  variant?: string;
+  class: TriageClass;
+  ruleId: string;
+  evidence: string;
+  ids: string[];
+  legacy: string[];
+  defectId?: string;
+  tracePath?: string;
+  /** product-candidate only: the two halves of the assertion, for a defect draft. */
+  expected?: string;
+  received?: string;
+}
+
+const EVIDENCE_MAX = 200;
+const VIEWPOINT_ID = /\b(?:VP|FL)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
+const ELEMENT_ABSENT = /Received:\s*<element\(s\) not found>/;
+
+/** The part of a message the run itself wrote: before `Call log:`, without `Locator:` echo lines. */
+const runHead = (m: string): string => m.split(/\n\s*Call log:/)[0].replace(/^\s*Locator:.*$/gm, '');
+
+/** Every failure message, stack frames and a leading `Error:` dropped. */
+function messagesOf(result: PlaywrightResult): string[] {
+  const raw = result.errorMessages?.length ? result.errorMessages : [result.error ?? ''];
+  return raw.map((m) => m.split(/\n\s*at\s/)[0].replace(/^Error:\s*/i, '').trim()).filter(Boolean);
+}
+
+function evidenceLine(text: string, secrets: string[]): string {
+  const flat = redactSecrets(text, secrets).replace(/\s+/g, ' ').trim();
+  return flat.length > EVIDENCE_MAX ? `${flat.slice(0, EVIDENCE_MAX - 1)}…` : flat;
+}
+
+/** Classify one scenario. Null when it needs no triage (clean pass, or never ran). */
+export function classifyScenario(input: TriageInput, secrets: string[] = []): TriageRow | null {
+  const { result, tags } = input;
+  if (!result) return null;
+  const base = {
+    unit: input.unit,
+    scenario: input.title,
+    ...(input.variant ? { variant: input.variant } : {}),
+    ids: [...new Set([input.title, ...tags].join(' ').match(VIEWPOINT_ID) ?? [])],
+    legacy: tags.filter((t) => t.startsWith('@legacy:')).map((t) => t.slice('@legacy:'.length)),
+    ...(result.tracePath ? { tracePath: result.tracePath } : {}),
+  };
+  const row = (cls: TriageClass, ruleId: string, evidence: string): TriageRow =>
+    ({ ...base, class: cls, ruleId, evidence: evidenceLine(evidence, secrets) });
+
+  if (result.status === 'passed') {
+    return (result.attempts ?? 1) > 1 ? row('flaky', 'passed-after-retry', `passed on attempt ${result.attempts}`) : null;
+  }
+  const messages = messagesOf(result);
+  const first = messages[0] ?? result.status;
+
+  const known = tags.find((t) => t === '@known-defect' || t.startsWith('@known-defect:'));
+  if (known) {
+    const r = row('known-defect', 'tag-known-defect', first);
+    const id = known.split(':')[1];
+    return id ? { ...r, defectId: id } : r;
+  }
+  if (tags.some((t) => t.startsWith('@manual'))) return row('blocked-capability', 'tag-manual', `${tags.find((t) => t.startsWith('@manual'))} — ${first}`);
+  if (tags.some((t) => t.startsWith('@requires:'))) return row('blocked-capability', 'tag-requires', `${tags.find((t) => t.startsWith('@requires:'))} — ${first}`);
+  if (result.status === 'skipped') return row('blocked-capability', 'status-skipped', 'skipped');
+
+  // An assertion with both halves decides the case even when a timeout wraps it.
+  for (const m of messages) {
+    const { expected, received } = parseExpectedReceived(m);
+    if (expected && received && !ELEMENT_ABSENT.test(m) && expected !== received) {
+      return { ...row('product-candidate', 'assertion-mismatch', `Expected ${expected} · Received ${received}`),
+        expected: evidenceLine(expected, secrets), received: evidenceLine(received, secrets) };
+    }
+  }
+  for (const s of TRIAGE_SIGNALS) {
+    // Environment signals read only what the RUN said, never the test's own selector text that a
+    // message echoes in `Locator:` / `Call log:` — `getByText('Invalid URL')` is a missing message,
+    // not a bad base URL. Test-defect signals need the call log (`waiting for …`), so they read it all.
+    const hit = messages.find((m) => s.match.test(s.class === 'environment' ? runHead(m) : m));
+    if (hit) return row(s.class, s.id, hit);
+  }
+  const absent = messages.find((m) => ELEMENT_ABSENT.test(m));
+  if (absent) return row('unclassified', 'assertion-element-absent', absent);
+  if (messages.length > 0 && messages.every((m) => BARE_TIMEOUT.test(m))) {
+    return row('unclassified', 'bare-timeout', `${first} No locator or assertion detail: a slow environment, a hanging page, or a wait in the test. Re-run once, then read the trace's last action.`);
+  }
+  return row('unclassified', 'no-signal', first);
+}