@sun-asterisk/sungen 3.2.33 → 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,10 +20,10 @@ 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, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
@@ -39,7 +38,7 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
-import { ManualCarryReport } from '../../exporters/matrix/carry-manual-results';
+import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
 
@@ -86,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' };
 }
@@ -342,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`) —
@@ -405,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,
@@ -423,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) : '';
@@ -462,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.
@@ -520,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,
@@ -572,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
@@ -673,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';
     }
   }
@@ -703,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));
@@ -737,7 +763,8 @@ async function exportMatrixTarget(
 
   let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
   try {
-    deliverables = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+    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}`);
@@ -977,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;
                 }
@@ -1004,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/results-merge.ts

@@ -39,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'),
@@ -89,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; }

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

package/src/cli/index.ts

@@ -24,6 +24,7 @@ import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
 import { registerChangedCommand } from './commands/changed';
+import { registerSelectCommand } from './commands/select';
 import { registerLedgerCommand } from './commands/ledger';
 import { registerFeedbackCommand } from './commands/feedback';
 import { registerQaFeedbackCommand } from './commands/qa-feedback';
@@ -36,8 +37,11 @@ import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
 import { registerContextCommand } from './commands/context';
 import { registerRepairCommand } from './commands/repair';
+import { registerTriageCommand } from './commands/triage';
+import { registerDefectCommand } from './commands/defect';
 import { registerResultsCommand } from './commands/results-merge';
 import { registerLoginCommand } from './commands/login';
+import { registerViewpointCommand } from './commands/viewpoint';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { warnAssetsDrift } from '../orchestrator/assets-drift';
@@ -75,6 +79,7 @@ registerSetupMobileEnvCommand(program);
   registerGateCommand(program);
   registerManifestCommand(program);
   registerChangedCommand(program);
+  registerSelectCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);
   registerQaFeedbackCommand(program);
@@ -87,10 +92,13 @@ registerSetupMobileEnvCommand(program);
   registerFlowCheckCommand(program);
   registerContextCommand(program);
   registerRepairCommand(program);
+  registerTriageCommand(program);
+  registerDefectCommand(program);
   registerResultsCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
   registerLoginCommand(program);
+  registerViewpointCommand(program);
 
   // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
   // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
@@ -123,12 +131,15 @@ registerSetupMobileEnvCommand(program);
     const opts = actionCommand.opts() as Record<string, unknown>;
     const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
       ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
-    handBack = { unit: unit as string | undefined, json: opts.json === true };
+    // `--grep` is machine output too: callers capture it with `$(…)`, and a footer on stdout
+    // became part of the regex — the last alternative of `changed --grep` silently matched
+    // nothing, so `--change-only` skipped its last scenario (#836).
+    handBack = { unit: unit as string | undefined, json: opts.json === true || opts.grep === true };
   });
   process.on('exit', (code) => {
     if (!handBack || code === 1) return;
     const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
-    // stderr under --json so the hand-back never lands in the parsed payload.
+    // stderr under --json / --grep so the hand-back never lands in the captured payload.
     if (handBack.json) process.stderr.write(`${line}\n`);
     else process.stdout.write(`${line}\n`);
   });