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

package/src/cli/commands/delivery.ts

@@ -6,9 +6,8 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { execSync } from 'child_process';
 import { parse as parseYaml } from 'yaml';
-import { parseFeatureMetadata } from '../../exporters/feature-parser';
+import { isHookScenario, parseFeatureMetadata } from '../../exporters/feature-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
 import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadSelectorKeyMap } from '../../exporters/selector-key-resolver';
@@ -21,12 +20,12 @@ import {
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
-import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet, deliverableXlsxPath } from '../../exporters/xlsx-exporter';
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolveApiEnvironment } from '../../exporters/api-environment';
-import { resolveWebBaseUrl } from '../../exporters/env-qa';
+import { getEnvironment, platformOfResultFile, RunEnvironment } from '../../exporters/run-environment';
 import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 import { mapFilePath } from '../../exporters/matrix/map-loader';
 import {
@@ -39,7 +38,9 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
+import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
+import { readCapabilities } from '../../harness/capability';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -84,6 +85,12 @@ export interface DeliveryTarget {
   isFlow: boolean;
 }
 
+/** The command that regenerates a target's unit — flag by kind, the unit (not feature) name. */
+function generateCommandFor(target: DeliveryTarget): string {
+  const flag = target.kind === 'flow' ? '--flow' : target.kind === 'api' ? '--api' : '--screen';
+  return `sungen generate ${flag} ${target.screen}`;
+}
+
 function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): DeliveryTarget {
   return { screen, featureBaseName, name: featureBaseName, kind, isFlow: kind === 'flow' };
 }
@@ -340,34 +347,27 @@ export function hasBlockingMissing(p: PreflightCheck): boolean {
 // Environment
 // ----------------------------------------------------------------------------
 
-function getEnvironment(cwd: string): EnvironmentInfo {
-  let baseURL = '';
-  let projectName = 'chromium';
-  const configPath = path.join(cwd, 'playwright.config.ts');
-  if (fs.existsSync(configPath)) {
-    const c = fs.readFileSync(configPath, 'utf-8');
-    // Both config shapes: the legacy literal `baseURL: 'x'` and the env-aware
-    // `baseURL: resolveBaseUrl('x')` (the quoted value is the static fallback).
-    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
-    if (baseMatch) baseURL = baseMatch[1];
-    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
-    if (projMatch) projectName = projMatch[1];
-  }
-  // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
-  // value — the Test Environment column must show the host the run actually hit.
-  baseURL = resolveWebBaseUrl(cwd, baseURL);
-
-  let executor = process.env.CI_USER || process.env.USER || '';
-  try {
-    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8' }).trim();
-    if (gitUser) executor = gitUser;
-  } catch {
-    // ignore
-  }
+/** The unit's path for the Environment column — a flow records it in its page selector. */
+function targetFeaturePath(target: DeliveryTarget, declared: string | undefined, selectorsFile: string): string | undefined {
+  return declared || (target.isFlow ? readFlowPagePath(selectorsFile) : undefined);
+}
 
-  return { baseURL, projectName, executor };
+/**
+ * Executor + environment for the matrix's run-result rows (#850) — resolved exactly as the
+ * legacy workbook resolves them: the API datasource host for an api unit, and on mobile the
+ * app id of the OS the result file came from (`<f>-test-result.<os>[.<env>].json`).
+ */
+function matrixRunEnv(cwd: string, target: DeliveryTarget, env: EnvironmentInfo, paths: MatrixTargetPaths): RunEnvironment {
+  const base = qaDir(cwd, target);
+  let declared: string | undefined;
+  try { declared = parseFeatureMetadata(paths.featureFile).featurePath; } catch { /* loadMatrixModel reports it */ }
+  const featurePath = targetFeaturePath(target, declared, path.join(base, 'selectors', `${target.featureBaseName}.yaml`));
+  const apiEnv = target.kind === 'api' ? resolveApiEnvironment(cwd, loadApiCatalog(cwd, target.kind, target.screen)) : null;
+  const os = platformOfResultFile(paths.resultsPath) ?? process.env.MOBILE_PLATFORM ?? process.env.SUNGEN_ENV;
+  return { ...env, ...(apiEnv ?? {}), featurePath: resolvePlatformAppId(featurePath, os) };
 }
 
+
 /**
  * True when this is a mobile project (`platform: mobile` in qa/capabilities.yaml).
  * Mobile results are written PER-OS (`<feature>-test-result.android|ios.json`) —
@@ -375,14 +375,11 @@ function getEnvironment(cwd: string): EnvironmentInfo {
  * emits one csv+xlsx per OS and skips the (empty/misleading) base aggregate.
  */
 function isMobileProject(cwd: string): boolean {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (!fs.existsSync(p)) return false;
-    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
-    return parsed?.platform === 'mobile';
-  } catch {
-    return false;
-  }
+  // Reads through `readCapabilities` rather than re-parsing the file: the third copy of this parse
+  // was the third place a malformed capabilities.yaml quietly read as "web". The shared reader
+  // reports the breakage once per process; here it still degrades to web, which is the safe
+  // direction (per-OS delivery is skipped, nothing is deleted).
+  return readCapabilities(cwd).platform === 'mobile';
 }
 
 /**
@@ -406,6 +403,18 @@ function removeBaseDeliverables(cwd: string, featureBaseName: string): void {
 // Per-screen export
 // ----------------------------------------------------------------------------
 
+/**
+ * #810 — a manual oracle that lives only in unlabelled `Tester verifies:` prose is exported
+ * verbatim into Expected (never dropped), and the author is told to structure it.
+ */
+function warnUnlabeledManualOracles(label: string, merged: ReturnType<typeof mergeFeatureAndSpec>): void {
+  const hits = merged.filter((m) => m.unlabeledManualOracle);
+  if (!hits.length) return;
+  log(`${COLOR.yellow}⚠ ${label}: manual oracle found only in an unlabeled comment (${hits.length})${COLOR.reset} — exported verbatim into Expected; write it as numbered "N. Observable: …" lines:`);
+  for (const m of hits.slice(0, 10)) log(`    ${m.feature.name.slice(0, 90)}`);
+  if (hits.length > 10) log(`    … and ${hits.length - 10} more`);
+}
+
 async function exportTarget(
   cwd: string,
   target: DeliveryTarget,
@@ -424,14 +433,12 @@ async function exportTarget(
     const spec = parseSpecFile(specFile);
 
     const merged = mergeFeatureAndSpec(feature, spec);
+    warnUnlabeledManualOracles(label, merged);
     // Screens get their URL path from the .feature file directly. Flows record
     // it in selectors/<feature>.yaml under the page-selector block — fall back
     // to that so the Environment column shows a full URL for flows too.
-    let featurePath = feature.featurePath;
     const selectorsFile = path.join(base, 'selectors', `${target.featureBaseName}.yaml`);
-    if (!featurePath && target.isFlow) {
-      featurePath = readFlowPagePath(selectorsFile);
-    }
+    const featurePath = targetFeaturePath(target, feature.featurePath, selectorsFile);
     const selectorKeyMap = loadSelectorKeyMap(selectorsFile);
 
     const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
@@ -463,6 +470,7 @@ async function exportTarget(
       if (isMobileProject(cwd)) removeBaseDeliverables(cwd, target.featureBaseName);
       const rows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // OS-precise env column: a mobile dual-id Path resolves to just the
         // android package / ios bundle id for SUNGEN_ENV=android|ios.
@@ -521,6 +529,7 @@ async function exportTarget(
         for (const variant of osVariants) {
           const variantRows = buildTestCaseRows({
             screen: label,
+            generateCommand: generateCommandFor(target),
             featureName: feature.featureName,
             featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
             merged,
@@ -573,6 +582,7 @@ async function exportTarget(
       const variantResults = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
       const variantRows = buildTestCaseRows({
         screen: label,
+        generateCommand: generateCommandFor(target),
         featureName: feature.featureName,
         // No-op for web (URL Path); for a mobile fall-through (a no-suffix result
         // json) this collapses the dual-id to the android package so the combined
@@ -674,17 +684,21 @@ async function exportMatrixTarget(
   cwd: string,
   target: DeliveryTarget,
   opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
+  env: EnvironmentInfo,
 ): Promise<MatrixRunSummary | 'skipped' | null> {
   const paths = matrixPathsFor(cwd, target);
+  paths.runEnv = matrixRunEnv(cwd, target, env, paths);
 
   // A feature whose scenarios are ALL @exploration probes has nothing to deliver —
   // skip it quietly (no map required) instead of demanding a reviewed grouping for
   // probes that are, by contract, outside the official suite.
   {
     const featureMeta = parseFeatureMetadata(paths.featureFile);
-    const deliverable = featureMeta.scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
-    if (featureMeta.scenarios.length > 0 && deliverable.length === 0) {
-      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${featureMeta.scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
+    // Hooks are setup/teardown, never test cases — they neither need nor make a deliverable (#880).
+    const scenarios = featureMeta.scenarios.filter((s) => !isHookScenario(s));
+    const deliverable = scenarios.filter((s) => !s.tags.some((t) => /^@exploration\b/i.test(t)));
+    if (scenarios.length > 0 && deliverable.length === 0) {
+      log(`${COLOR.gray}${paths.label}: nothing to deliver — all ${scenarios.length} scenario(s) are @exploration probes (outside the official suite).${COLOR.reset}`);
       return 'skipped';
     }
   }
@@ -704,6 +718,17 @@ async function exportMatrixTarget(
     return null;
   }
 
+  // The tester's recorded Manual results are part of the outcome: read them BEFORE anything is
+  // counted, so this line, the workbook's totals and the summary table all agree (#891). A file
+  // that cannot be read is reported where it matters — when it would be overwritten.
+  const format = opts.format ?? 'xlsx';
+  let prior: PriorManualResults | null = null;
+  let priorError: Error | null = null;
+  try { prior = await readPriorManualResults(deliverableXlsxPath(cwd, paths.unit)); }
+  // A CSV-only export overwrites no workbook, so an unreadable one only means "nothing to carry".
+  catch (e) { if (format !== 'csv') priorError = e as Error; }
+  applyManualCarry(model, prior);
+
   log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), review: ${model.manifest.approvalState} (design), test outcome: ${formatTestOutcome(resultTotals(model.items))}`);
   {
     const mocked = model.items.flatMap((it) => it.variants.filter((v) => v.mocked));
@@ -736,11 +761,21 @@ async function exportMatrixTarget(
     return null;
   }
 
-  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
+  try {
+    if (priorError) throw priorError;
+    deliverables = await writeMatrixDeliverables(paths, model, format, prior);
+  } catch (e) {
+    // The existing workbook could not be read, so writing would destroy its Manual results.
+    log(`  ${COLOR.red}not written:${COLOR.reset} ${(e as Error).message}`);
+    return null;
+  }
+  const { csvPath, xlsxPath, manualCarry } = deliverables;
   const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
   const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
   for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  if (manualCarry) printManualCarry(manualCarry);
   return {
     label: paths.label,
     items: model.manifest.itemCount,
@@ -751,6 +786,23 @@ async function exportMatrixTarget(
   };
 }
 
+/** What happened to the tester's hand-entered Manual results on this write (#756). */
+function printManualCarry(r: ManualCarryReport): void {
+  const kept = r.carried + r.unchecked;
+  if (kept + r.reset.length + r.notPlaced.length + r.duplicates.length === 0) return;
+  const list = (refs: string[]) => `${refs.slice(0, 4).join(', ')}${refs.length > 4 ? ', …' : ''}`;
+  log(`  Manual results: ${kept} kept${r.unchecked > 0 ? ` (${r.unchecked} without a drift check — the file predates the fingerprint stamp)` : ''}`);
+  if (r.reset.length > 0) {
+    log(`  ${COLOR.yellow}reset to Pending${COLOR.reset} — procedure changed since the result was recorded (${r.reset.length}): ${list(r.reset)}; the previous result is kept in Note`);
+  }
+  if (r.notPlaced.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — no matching manual case in the feature any more (${r.notPlaced.length}): ${list(r.notPlaced.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+  if (r.duplicates.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — a second row for the same case; only the first was kept (${r.duplicates.length}): ${list(r.duplicates.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+}
+
 /**
  * One place that accounts for every target the run did NOT write, so a sweep is
  * never silently partial: scaffolds skipped by preflight and units whose gates /
@@ -934,12 +986,9 @@ export function registerDeliveryCommand(program: Command): void {
         // Deliverables are COMMITTED files; delivery is the last stop before a
         // hardcoded credential lands in one. Same scan `generate` runs.
         const scanDirs = [...new Set(toExport.map((t) => qaDir(cwd, t)))];
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) log(`   ${h.file}:${h.line} — ${h.reason}`);
-          log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.\n`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) log(line);
 
         // 3. Export
         const legacy = options.legacy || options.full;
@@ -955,9 +1004,9 @@ export function registerDeliveryCommand(program: Command): void {
               // Same contract as the export path: an all-@exploration feature has no
               // deliverable variants, so there is no map to approve — skip, not an error.
               {
-                const featureMeta = parseFeatureMetadata(paths.featureFile);
-                if (featureMeta.scenarios.length > 0
-                  && featureMeta.scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
+                const scenarios = parseFeatureMetadata(paths.featureFile).scenarios.filter((s) => !isHookScenario(s));
+                if (scenarios.length > 0
+                  && scenarios.every((s) => s.tags.some((t) => /^@exploration\b/i.test(t)))) {
                   log(`${COLOR.gray}${paths.label}: nothing to approve — all scenario(s) are @exploration probes.${COLOR.reset}`);
                   continue;
                 }
@@ -982,10 +1031,11 @@ export function registerDeliveryCommand(program: Command): void {
 
           const matrixSummaries: MatrixRunSummary[] = [];
           const notExported: string[] = [];
+          const env = getEnvironment(cwd);
           for (const target of toExport) {
             const s = await exportMatrixTarget(cwd, target, {
               check: options.check, preview: options.preview, format: format as MatrixFormat,
-            });
+            }, env);
             if (s === 'skipped') continue; // all-@exploration feature — neither exported nor a failure
             if (s) matrixSummaries.push(s);
             else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);

package/src/cli/commands/generate.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
@@ -160,6 +160,17 @@ export function registerGenerateCommand(program: Command): void {
           const cap = readCapabilities(cwd);
           if (cap.platform) {
             platform = cap.platform;
+          } else if (cap.source === 'unreadable') {
+            // The file EXISTS and we failed to parse it. Scaffolding the web default here would
+            // overwrite whatever the user declared — a mobile project's platform, drivers and
+            // verification scope, gone, while the notice claimed the file was missing. Refuse:
+            // the one thing we know is that we do not know what this project is.
+            throw new Error(
+              `qa/capabilities.yaml exists but could not be parsed — fix the YAML and re-run.\n` +
+              `   Refusing to scaffold a default over it: that would discard the platform, drivers ` +
+              `and verification scope it declares.\n` +
+              `   To compile without reading it, pass --framework <web|mobile|…>.`,
+            );
           } else {
             platform = 'web';
             writeCapabilities(cwd, { platform: 'web', enabled: ['web'] });
@@ -225,12 +236,9 @@ export function registerGenerateCommand(program: Command): void {
             if (fs.existsSync(d)) for (const n of fs.readdirSync(d)) scanDirs.push(path.join(d, n));
           }
         }
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          console.log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) console.log(`   ${h.file}:${h.line} — ${h.reason}`);
-          console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) console.log(line);
 
         // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
         // never block generation. Each capability registers its own; the kernel just runs them.

package/src/cli/commands/results-merge.ts

@@ -13,6 +13,7 @@ import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-pa
 import { registerResultsSanitizeCommand } from './results-sanitize';
 import { resolveResultsPath } from '../../exporters/playwright-report-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 interface MergeCliOptions {
   out?: string;
@@ -38,7 +39,7 @@ function readReport(file: string, label: string): any {
  * (flows → screens → api → api flows); the same basename found in more than one
  * place is an ambiguity error, never a silent pick.
  */
-function resolveFeatureDir(cwd: string, name: string): string {
+export function resolveFeatureDir(cwd: string, name: string): string {
   const roots = [
     path.join(cwd, 'specs', 'generated', 'flows'),
     path.join(cwd, 'specs', 'generated'),
@@ -88,6 +89,12 @@ export function runResultsMerge(baseArg: string | undefined, newArg: string | un
     if (!baseFile || path.dirname(baseFile) !== dir) {
       throw new Error(`results merge: no per-target result file for "${opts.screen}" in ${path.relative(cwd, dir)} — nothing to merge into (a first full run writes it directly).`);
     }
+    // Under SUNGEN_ENV the candidate order falls back to the base-locale file when the env file
+    // does not exist yet; merging a `vi` subset there would overwrite `ja`/base results in silence.
+    const env = process.env.SUNGEN_ENV;
+    if (env && !path.basename(baseFile).endsWith(`.${env}.json`)) {
+      throw new Error(`results merge: SUNGEN_ENV=${env} but "${opts.screen}" has no ${env} result file yet (found ${path.basename(baseFile)}) — run the full ${env} suite first; it writes the file directly.`);
+    }
     // Ghost/foreign-title checks need the CURRENT spec titles.
     const specFile = path.join(dir, `${opts.screen}.spec.ts`);
     try { specTitles = parseSpecFile(specFile).tests.map((t) => t.testTitle); } catch { specTitles = null; }
@@ -125,14 +132,7 @@ export function runResultsMerge(baseArg: string | undefined, newArg: string | un
   // that file is the single source of execution truth for delivery/dashboard.
   // (Same-dir rename = same device; concurrent merges are last-rename-wins.)
   const outFile = opts.out ?? baseFile;
-  const tmp = `${outFile}.tmp-${process.pid}`;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
-    fs.renameSync(tmp, outFile);
-  } catch (err) {
-    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-    throw err;
-  }
+  writeFileAtomic(outFile, JSON.stringify(merged, null, 2));
 
   console.log(`✓ merged ${path.basename(newFile)} into ${path.relative(cwd, outFile)} — ${replaced.length} updated, ${added.length} added, ${kept.length} kept`);
   return outFile;

package/src/cli/commands/results-sanitize.ts

@@ -16,6 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
 import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-path-sanitizer';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 /** Where a project keeps the JSON files that carry paths. */
 export const DEFAULT_REPORT_GLOBS = [
@@ -50,15 +51,7 @@ export function runResultsSanitize(files: string[] | undefined, cwd: string = pr
     const root = detectReportRoot(doc) ?? nearestProjectRoot(path.dirname(file)) ?? cwd;
     const { doc: clean, rewritten } = sanitizeReportPaths(doc, { root });
     if (rewritten > 0) {
-      // Atomic write, same as `results merge`: a crash mid-write must never leave a truncated report.
-      const tmp = `${file}.tmp-${process.pid}`;
-      try {
-        fs.writeFileSync(tmp, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
-        fs.renameSync(tmp, file);
-      } catch (err) {
-        try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-        throw err;
-      }
+      writeFileAtomic(file, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
     }
     out.push({ file: path.relative(cwd, file), rewritten });
   }

package/src/cli/commands/select.ts

@@ -0,0 +1,88 @@
+/**
+ * `sungen select` — which tests does a list of test-case IDs name? (#835)
+ *
+ * Backs `run-test --ids`. Like `sungen changed` for `--change-only`, the selection is computed here
+ * so it is deterministic and testable; the workflow only runs it and merges the subset result into
+ * the existing per-feature result file.
+ *
+ * Fails loud: an ID that selects nothing runnable exits non-zero, because a 0-test run reports green.
+ */
+import { Command } from 'commander';
+import * as path from 'path';
+import { findUnitDir } from '../resolve-unit';
+import { loadUnitScenarios } from '../../harness/parse';
+import { parseIdList, selectByIds } from '../../harness/select-by-ids';
+import { resolveFeatureDir } from './results-merge';
+import { readCapabilities } from '../../harness/capability';
+import { projectRootFromScreenDir } from '../../harness/intent';
+
+export function registerSelectCommand(program: Command): void {
+  program
+    .command('select')
+    .description('List the tests a set of test-case IDs selects, grouped per feature (backs run-test --ids)')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api')
+    .requiredOption('--ids <list>', 'Test-case IDs, comma- or space-separated (e.g. VP-UI-001,VP-UI-002)')
+    .option('--json', 'Output the selection as JSON (per feature: spec, ids, titles, grep)')
+    .option('--grep', 'Output ONLY the regex for -g / --mochaOpts.grep (selection must lie in one feature)')
+    .action((options) => {
+      try {
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const dir = findUnitDir(name);
+        if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
+        const ids = parseIdList(options.ids);
+        if (ids.length === 0) throw new Error('--ids is empty — pass at least one test-case ID');
+
+        const cwd = process.cwd();
+        // Same capability set `generate` compiles against: a @requires:<cap> scenario is a skip without it.
+        const enabledCaps = new Set(readCapabilities(projectRootFromScreenDir(path.resolve(dir))).enabled.map((c) => c.toLowerCase()));
+        const selection = selectByIds(loadUnitScenarios(dir, name), ids, name, enabledCaps);
+        // Resolve each feature's compiled spec: a test cannot run before `sungen generate`.
+        const features = selection.features.map((g) => {
+          let spec: string | null = null;
+          try { spec = path.relative(cwd, path.join(resolveFeatureDir(cwd, g.feature), `${g.feature}.spec.ts`)); } catch { /* reported below */ }
+          return { ...g, spec };
+        });
+        const notCompiled = features.filter((f) => !f.spec).map((f) => f.feature);
+        const failed = selection.unknown.length > 0 || selection.notRunnable.length > 0 || notCompiled.length > 0 || features.length === 0;
+
+        if (options.json) {
+          console.log(JSON.stringify({ unit: name, features, unknown: selection.unknown, notRunnable: selection.notRunnable, notCompiled }, null, 2));
+          if (failed) process.exitCode = 1;
+          return;
+        }
+        if (options.grep) {
+          // Only a clean single-feature selection prints a regex; anything else must not be run
+          // as if it were complete, so it prints nothing and exits non-zero.
+          if (failed || features.length !== 1) {
+            console.error(features.length > 1
+              ? `select: the IDs span ${features.length} features (${features.map((f) => f.feature).join(', ')}) — use --json and run each feature on its own.`
+              : 'select: nothing runnable for these IDs — run without --grep to see why.');
+            process.exitCode = 1;
+            return;
+          }
+          console.log(features[0].grep);
+          return;
+        }
+
+        const selected = features.reduce((n, f) => n + f.titles.length, 0);
+        // A @cases scenario expands to one test per dataset row, so this counts scenarios.
+        console.log(`\n  ${selected} scenario(s) selected for ${ids.length} ID(s) in ${name}:\n`);
+        for (const f of features) {
+          console.log(`  ${f.feature} → ${f.spec ?? '(not compiled — run sungen generate first)'}`);
+          for (const t of f.titles) console.log(`    ▶ ${t}`);
+        }
+        for (const u of selection.unknown) {
+          console.log(`  ✗ ${u.id} — no scenario has this ID${u.didYouMean.length ? ` (did you mean ${u.didYouMean.join(', ')}?)` : ''}`);
+        }
+        for (const n of selection.notRunnable) console.log(`  ○ ${n.id} — ${n.reason}`);
+        console.log('');
+        if (failed) process.exitCode = 1;
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/triage.ts

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import { resolveUnit } from '../resolve-unit';
+import { triageUnit, writeTriageReport } from '../../harness/triage-unit';
+import type { TriageClass } from '../../harness/triage';
+
+/** Display order: what needs a decision first, green last. */
+const ORDER: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'blocked-capability', 'known-defect', 'flaky'];
+
+/**
+ * `sungen triage` — classify every red or flaky scenario of the latest run (see harness/triage.ts).
+ * Reports, never gates: always exits 0 once the unit is found.
+ */
+export function registerTriageCommand(program: Command): void {
+  program
+    .command('triage')
+    .description('Classify each red or flaky scenario of the latest run: known-defect, blocked, environment, test-defect, product-candidate, unclassified')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api')
+    .option('--json', 'Output the raw JSON report')
+    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const cwd = process.cwd();
+        const unit = resolveUnit(name, cwd);
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = triageUnit(cwd, unit);
+        if (report.resultFiles.length === 0) {
+          if (o.json) console.log(JSON.stringify(report, null, 2));
+          else console.log(`\n  ${name}: no results — run the tests first.\n`);
+          return;
+        }
+        const saved = writeTriageReport(cwd, report);
+        if (o.json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Triage: ${name} ━━━`);
+        if (report.rows.length === 0) L('  ✓ every scenario passed on its first attempt');
+        for (const cls of ORDER) {
+          const rows = report.rows.filter((r) => r.class === cls);
+          if (rows.length === 0) continue;
+          L(`\n  ${cls} (${rows.length})`);
+          for (const r of rows) {
+            L(`    • ${r.scenario}${r.variant ? ` [${r.variant}]` : ''}${r.defectId ? ` → ${r.defectId}` : ''}`);
+            L(`      ${r.ruleId}: ${r.evidence}`);
+          }
+        }
+        L(`\n  Report: ${path.relative(cwd, saved)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -103,6 +103,9 @@ export function registerUpdateCommand(program: Command): void {
         // playwright.config.ts is written once at init and never re-synced — patch the reporter in.
         const { installReportSanitizeReporter } = require('../../orchestrator/report-sanitize-reporter-install');
         installReportSanitizeReporter(process.cwd(), options.dryRun ?? false);
+        // …and move the old `trace: 'on-first-retry'` default, which never records a trace off CI.
+        const { installTraceMode } = require('../../orchestrator/trace-mode-install');
+        installTraceMode(process.cwd(), options.dryRun ?? false);
       } catch (error) {
         console.error('❌ Update failed:', error);
         process.exit(1);

package/src/cli/commands/viewpoint.ts

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import { resolveUnit } from '../resolve-unit';
+import { scanViewpointUnit, ViewpointScan } from '../../harness/viewpoint-scan';
+
+const SHOWN = 10;
+
+/** `a, b, c … +N more` — a list long enough to scroll past is a count plus a sample. */
+const sample = (xs: string[]): string => (xs.length <= SHOWN ? xs.join(', ') : `${xs.slice(0, SHOWN).join(', ')} … +${xs.length - SHOWN} more`);
+
+function printScan(name: string, s: ViewpointScan): void {
+  const L = console.log;
+  L(`\n━━━ Viewpoint scan: ${name} ━━━`);
+  L(`  mode ${s.mode} (${s.modeReason}) — ${s.mode === 2 ? 'the AI drafts / revises its own draft' : 'review only, the file is never edited'}`);
+  L(`  ${s.vpRows.length} rows (${s.distinctIds} distinct ids)   without Kỳ vọng: ${s.rowsWithoutExpected.length}   manual: ${s.manualRows.length}`);
+  if (s.note) L(`  ⚠ ${s.note}`);
+  if (s.rowsWithoutExpected.length) L(`    no Kỳ vọng: ${sample(s.rowsWithoutExpected)}`);
+  if (s.manualRows.length) L(`    manual: ${sample(s.manualRows)}`);
+  if (s.itemSource === 'none') L('  item source: none (the viewpoint cites no spec id, spec item or UI-NNN)');
+  else L(`  item source: ${s.itemSource}   uncited items: ${s.uncitedItems.length}`);
+  if (s.uncitedItems.length) L(`    ${sample(s.uncitedItems.map((i) => (i.name ? `${i.ref} (${i.name})` : i.ref)))}`);
+  if (s.withoutScenario === null) L('  scenarios: no feature file yet');
+  else L(`  VP ids with no scenario: ${s.withoutScenario.length}${s.withoutScenario.length ? `\n    ${sample(s.withoutScenario)}` : ''}`);
+  L('');
+}
+
+/**
+ * `sungen viewpoint scan` — ids and item refs only. Read-only: no audit finding, no score, no
+ * baseline effect; the file is never edited. What the rows MEAN is the review skill's job.
+ */
+export function registerViewpointCommand(program: Command): void {
+  const viewpoint = program
+    .command('viewpoint')
+    .description('Read a unit\'s requirements/test-viewpoint.md');
+
+  viewpoint
+    .command('scan')
+    .description('List VP rows (full-id first cell), the item numbers they cite, uncited spec items and VP ids no scenario carries — read-only')
+    .option('-s, --screen <name>', 'Screen (or flow) name')
+    .option('--flow <name>', 'Flow name (qa/flows/<name>)')
+    .option('--json', 'Output the scan as JSON')
+    .action((o: { screen?: string; flow?: string; json?: boolean }) => {
+      try {
+        if (o.screen && o.flow) throw new Error('Provide --screen <name> or --flow <name>, not both');
+        const name = o.screen || o.flow;
+        if (!name) throw new Error('Provide --screen <name> or --flow <name>');
+        const unit = resolveUnit(name);
+        if (!unit) throw new Error(`Not found: qa/screens/${name} or qa/flows/${name}`);
+        if (o.flow && unit.kind !== 'flow') throw new Error(`Not a flow: ${name} resolves to qa/${unit.unitId} (use --screen)`);
+
+        const scan = scanViewpointUnit(unit.dir, name);
+        if (o.json) console.log(JSON.stringify(scan, null, 2));
+        else printScan(name, scan);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}