@sun-asterisk/sungen 3.2.16 → 3.2.18-beta.1

package/src/cli/commands/audit.ts

@@ -1,8 +1,9 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { runAudit, AuditReport } from '../../harness/audit';
+import { runAudit, AuditReport, catalogIdFromScreenDir } from '../../harness/audit';
 import { reportSlug } from '../../harness/unit-paths';
+import { acceptViewpointBaseline } from '../../harness/viewpoint-baseline';
 
 function findScreenDir(name: string): string | null {
   // `name` may be a bare screen/flow/area, or an api unit id (`api/<area>`, `api/flows/<flow>`).
@@ -78,7 +79,12 @@ function render(r: AuditReport): void {
   if (r.calibration) {
     const ax = Object.entries(r.calibration.axes).map(([k, v]) => `${k}=${(v * 100).toFixed(0)}%`).join(' · ');
     L(`  ⑨ Calibration — ${ax}`);
+    const na = r.calibration.notApplicable ?? [];
+    if (na.length) L(`      not scored (no evidence in this unit): ${na.join(', ')}`);
     L(`      weakest: ${r.calibration.weakest.axis} ${(r.calibration.weakest.value * 100).toFixed(0)}%${r.calibration.inflated ? '  ⚠ SCORE-INFLATED-BY-BREADTH' : ''}`);
+    if (r.calibration.cappedAt !== undefined) {
+      L(`      ⚠ score held at ${r.calibration.cappedAt.toFixed(1)} by the weakest axis — fix it to lift the number`);
+    }
     L('');
   }
   L('  ── Findings (Repair targets) ──');
@@ -95,6 +101,7 @@ export function registerAuditCommand(program: Command): void {
     .option('--api <name>', 'API-first area or api flow to audit (e.g. orders, flows/signup)')
     .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output the raw JSON report')
+    .option('--accept-viewpoint', 'Accept the current test-viewpoint.md as the baseline the suite is measured against')
     .action((options) => {
       try {
         const name = options.screen || options.api || options.area;
@@ -104,6 +111,21 @@ export function registerAuditCommand(program: Command): void {
 
         const report = runAudit(dir, name);
 
+        // The baseline is only ever written HERE, never by the measurement itself:
+        // a first sighting has nothing to compare against, and any later change is
+        // a human decision (`--accept-viewpoint`) — see harness/viewpoint-baseline.ts.
+        const unitId = catalogIdFromScreenDir(dir);
+        const vb = report.viewpointBaseline;
+        if (vb.status === 'new' || (options.acceptViewpoint && vb.status === 'changed')) {
+          acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids });
+          if (options.acceptViewpoint && !options.json) {
+            console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
+            console.log('    Re-run the audit to score atomicLedger + traceability against it.\n');
+          }
+        } else if (options.acceptViewpoint && !options.json) {
+          console.log(`\n  ○ nothing to accept for ${name} — the viewpoint baseline is ${vb.status}.\n`);
+        }
+
         // Persist report under .sungen/reports/ (flat slug: api flow `flows/x` → `flows-x-audit.json`).
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });

package/src/cli/commands/delivery.ts

@@ -23,8 +23,20 @@ import {
 } from '../../exporters/csv-exporter';
 import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
 import { loadApiCatalog } from '../../exporters/api-catalog-loader';
+import { resolveApiEnvironment } from '../../exporters/api-environment';
 import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
+import { mapFilePath } from '../../exporters/matrix/map-loader';
+import {
+  MatrixTargetPaths,
+  loadMatrixModel,
+  approveMatrix,
+  writeMatrixDeliverables,
+  MatrixFormat,
+  hasErrors,
+  hasReview,
+} from '../../exporters/matrix/export';
+import { MatrixFinding } from '../../exporters/matrix/types';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -421,6 +433,15 @@ async function exportTarget(
     const apiCatalog = loadApiCatalog(cwd, target.kind, target.screen);
     const hasApiCatalog = target.kind === 'api' && Object.keys(apiCatalog).length > 0;
 
+    // API units call the datasource base_url (datasources.yaml + .env.qa), NOT the web
+    // baseURL from playwright.config.ts — the two hosts routinely differ, and an
+    // API-only project has no web baseURL at all. Resolve the real environment for the
+    // Test Environment cell; on any gap (no datasources.yaml / no base_url) keep the
+    // generic env unchanged. Shared with the dashboard so both surfaces agree.
+    const unitEnv = target.kind === 'api'
+      ? { ...env, ...(resolveApiEnvironment(cwd, apiCatalog) ?? {}) }
+      : env;
+
     // Decide between single-locale and aggregated multi-locale flows.
     //   • SUNGEN_ENV set → single locale (existing behaviour, no change)
     //   • SUNGEN_ENV unset → discover every *-test-result*.json variant.
@@ -440,7 +461,7 @@ async function exportTarget(
         merged,
         testData: loadTestData(testDataFile),
         results: resolveResultsPath(cwd, target) ? loadPlaywrightReport(resolveResultsPath(cwd, target)!) : null,
-        env,
+        env: unitEnv,
         selectorKeyMap,
         kind: target.kind,
         apiCatalog,
@@ -500,7 +521,7 @@ async function exportTarget(
             // showed base-language values in the Test Data column.
             testData: loadTestData(testDataFile, variant.overlay ?? null),
             results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
-            env,
+            env: unitEnv,
             selectorKeyMap,
             kind: target.kind,
             apiCatalog,
@@ -551,7 +572,7 @@ async function exportTarget(
         merged,
         testData: variantTestData,
         results: variantResults,
-        env,
+        env: unitEnv,
         selectorKeyMap,
         kind: target.kind,
         apiCatalog,
@@ -597,6 +618,129 @@ async function exportTarget(
   }
 }
 
+// ----------------------------------------------------------------------------
+// Matrix export (Delivery v2 — the default; --legacy keeps the classic workbook)
+// ----------------------------------------------------------------------------
+
+function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths {
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  return {
+    cwd,
+    unit: target.featureBaseName,
+    label: target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName,
+    featureFile: path.join(base, 'features', `${target.featureBaseName}.feature`),
+    testDataFile: resolveTestDataPathForTarget(cwd, target),
+    specFile: path.join(genBase, `${target.featureBaseName}.spec.ts`),
+    specMdFile: path.join(base, 'requirements', 'spec.md'),
+    resultsPath: resolveResultsPath(cwd, target),
+    mapFile: mapFilePath(base, target.featureBaseName),
+  };
+}
+
+function printFindings(findings: MatrixFinding[]): void {
+  const icon = { error: `${COLOR.red}✗`, review: `${COLOR.yellow}⚠`, warning: `${COLOR.gray}·` } as const;
+  for (const f of findings) {
+    log(`  ${icon[f.severity]} [Gate ${f.gate}]${COLOR.reset} ${f.ref ? `${f.ref}: ` : ''}${f.message}`);
+  }
+}
+
+interface MatrixRunSummary {
+  label: string;
+  items: number;
+  variants: number;
+  passed: number;
+  failed: number;
+  file: string;
+}
+
+/**
+ * Matrix-mode export of one target. Returns null when blocked (missing map,
+ * gate errors, or unapproved groups without --preview) — the caller aggregates
+ * a non-zero exit.
+ */
+async function exportMatrixTarget(
+  cwd: string,
+  target: DeliveryTarget,
+  opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
+): Promise<MatrixRunSummary | null> {
+  const paths = matrixPathsFor(cwd, target);
+  const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
+
+  if (mapMissing) {
+    log(`${COLOR.yellow}${paths.label}: no delivery map${COLOR.reset} (${path.relative(cwd, paths.mapFile)})`);
+    log(`  The matrix needs the reviewed grouping (target / intent / oracle per delivery item).`);
+    log(`  ${COLOR.cyan}→ run /sungen:delivery ${target.screen} so the map is proposed for your review${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ or export the classic per-scenario workbook: sungen delivery ${target.screen} --legacy${COLOR.reset}`);
+    return null;
+  }
+  if (mapErrors.length > 0 || !model) {
+    log(`${COLOR.red}${paths.label}: delivery map is invalid${COLOR.reset}`);
+    for (const e of mapErrors) log(`  - ${e}`);
+    return null;
+  }
+
+  log(`${COLOR.bold}${paths.label}${COLOR.reset} — ${model.manifest.itemCount} delivery item(s), ${model.manifest.variantCount} coverage variant(s), state: ${model.manifest.approvalState}`);
+  printFindings(model.findings);
+
+  if (opts.check) {
+    // Gates-only run: the summary IS the output; exit code reflects errors.
+    return hasErrors(model.findings)
+      ? null
+      : { label: paths.label, items: model.manifest.itemCount, variants: model.manifest.variantCount, passed: 0, failed: 0, file: '(check only)' };
+  }
+  if (hasErrors(model.findings)) {
+    log(`  ${COLOR.red}blocked:${COLOR.reset} fix the Gate errors above, then re-run.`);
+    return null;
+  }
+  if (hasReview(model.findings) && !opts.preview) {
+    log(`  ${COLOR.yellow}not approved for official delivery.${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ approve the reviewed grouping: sungen delivery ${target.screen} --approve${COLOR.reset}`);
+    log(`  ${COLOR.cyan}→ or render a watermarked draft:  sungen delivery ${target.screen} --preview${COLOR.reset}`);
+    return null;
+  }
+
+  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  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}`);
+  return {
+    label: paths.label,
+    items: model.manifest.itemCount,
+    variants: model.manifest.variantCount,
+    passed,
+    failed,
+    file: written.join(' + '),
+  };
+}
+
+/**
+ * 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 /
+ * missing map stopped the export.
+ */
+function printSkipSummary(skipped: string[], notExported: string[]): void {
+  if (skipped.length === 0 && notExported.length === 0) return;
+  log(`${COLOR.gray}Not exported (${skipped.length + notExported.length}):${COLOR.reset}`);
+  for (const s of skipped) log(`  ${COLOR.gray}· ${s}${COLOR.reset}`);
+  for (const n of notExported) log(`  ${COLOR.gray}· ${n} (see the message above)${COLOR.reset}`);
+  log('');
+}
+
+function printMatrixSummaryTable(summaries: MatrixRunSummary[]): void {
+  log(`\n${COLOR.bold}Delivery matrix export complete${COLOR.reset}\n`);
+  const colWidth = Math.max(20, ...summaries.map((s) => s.label.length)) + 1;
+  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File(s)`);
+  log('  ' + '-'.repeat(colWidth + 50));
+  for (const s of summaries) {
+    log(
+      `  ${s.label.padEnd(colWidth)}${String(s.items).padStart(5)}  ${String(s.variants).padStart(8)}  ${String(s.passed).padStart(6)}  ${String(s.failed).padStart(6)}  ${s.file}`
+    );
+  }
+  log(`\n${COLOR.gray}Items = review rows (one target + intent + oracle family). Variants = execution units — use variant counts for progress.${COLOR.reset}\n`);
+}
+
 // ----------------------------------------------------------------------------
 // Reporter
 // ----------------------------------------------------------------------------
@@ -667,23 +811,41 @@ function printSummaryTable(summaries: ScreenSummary[]): void {
 export function registerDeliveryCommand(program: Command): void {
   program
     .command('delivery')
-    .description('Export Gherkin + Playwright results → CSV test case deliverable')
+    .description('Export the Test Case & Coverage Matrix (Gherkin + results). --legacy keeps the classic per-scenario workbook.')
     .argument('[names...]', 'Specific screen or flow names. Omit to process all.')
     .option('--skip-preflight', 'Skip pre-flight checks (not recommended)')
     .option('--continue-on-missing', 'Skip targets with blocking misses instead of aborting')
     .option('--env <env>', 'Environment/locale of the run to deliver (sets SUNGEN_ENV; e.g. dev, staging, ja, dev-ja)')
-    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean; env?: string }) => {
+    .option('--legacy', 'Classic per-scenario-steps workbook (BM-2-901-13 layout)')
+    .option('--full', 'Alias of --legacy')
+    .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
+    .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
+    .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
+    .action(async (names: string[], options: {
+      skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
+      legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
+      format?: string;
+    }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
         // locale pairing, and test-data overlays all key off this one string.
         if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
+        // Matrix output format — one artifact by default (xlsx); csv/both on request.
+        const format = (options.format ?? 'xlsx').toLowerCase();
+        if (!['xlsx', 'csv', 'both'].includes(format)) {
+          console.error(`${COLOR.red}Invalid --format "${options.format}"${COLOR.reset} — use xlsx | csv | both`);
+          process.exit(1);
+        }
+
         // 1. Scope detection — each positional name expands into one target
         //    per `.feature` file inside that screen/flow. Passing a specific
         //    feature basename (e.g. `home-modal`) narrows to that one file.
         let targets: DeliveryTarget[];
-        if (names && names.length > 0) {
+        const explicitScope = !!(names && names.length > 0);
+        if (explicitScope) {
           targets = names.flatMap((n) => resolveTargetsFromArg(cwd, n));
         } else {
           targets = listAllTargets(cwd);
@@ -696,8 +858,13 @@ export function registerDeliveryCommand(program: Command): void {
         const labels = targets.map((t) => t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName);
         log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targets.length} feature(s): ${labels.join(', ')}\n`);
 
-        // 2. Pre-flight
+        // 2. Pre-flight — strictness follows the SCOPE. Naming a unit means "I want
+        //    this one" (fail loudly); a no-argument sweep means "export everything
+        //    that is ready", so scaffolded units (added but not yet authored) are
+        //    skipped with a note instead of aborting the whole run — otherwise one
+        //    untouched scaffold in a work-in-progress project produces zero files.
         let toExport: DeliveryTarget[];
+        const skipped: string[] = [];
         if (options.skipPreflight) {
           toExport = targets;
         } else {
@@ -706,28 +873,79 @@ export function registerDeliveryCommand(program: Command): void {
 
           const blockers = checks.filter(hasBlockingMissing);
           if (blockers.length > 0) {
-            if (options.continueOnMissing) {
-              const passedScreens = new Set(
-                checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
-              );
-              toExport = targets.filter((t) => {
-                const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
-                return passedScreens.has(label);
-              });
-              log(`${COLOR.yellow}Continuing with ${toExport.length} ready target(s).${COLOR.reset}\n`);
-            } else {
+            if (explicitScope && !options.continueOnMissing) {
               console.error(
-                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} target(s) have blocking issues.\n` +
+                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} named target(s) have blocking issues.\n` +
                 `Run the suggested commands above, or use ${COLOR.cyan}--continue-on-missing${COLOR.reset} to skip them.`
               );
               process.exit(1);
             }
+            const readyLabels = new Set(
+              checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
+            );
+            toExport = targets.filter((t) => {
+              const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
+              return readyLabels.has(label);
+            });
+            for (const b of blockers) skipped.push(`${b.screen} (not authored yet — run /sungen:create-test)`);
+            log(`${COLOR.yellow}Skipping ${blockers.length} target(s) that have no test cases yet; continuing with ${toExport.length}.${COLOR.reset}\n`);
           } else {
             toExport = targets;
           }
         }
 
         // 3. Export
+        const legacy = options.legacy || options.full;
+        if (!legacy) {
+          // Matrix mode (the default). --approve is its own sub-action.
+          if (options.approve !== undefined) {
+            const ids = typeof options.approve === 'string'
+              ? options.approve.split(',').map((s) => s.trim()).filter(Boolean)
+              : undefined;
+            let blocked = false;
+            for (const target of toExport) {
+              const paths = matrixPathsFor(cwd, target);
+              try {
+                const { findings, approved } = approveMatrix(paths, ids);
+                if (approved.length === 0) {
+                  log(`${COLOR.red}${paths.label}: approval blocked by Gate errors${COLOR.reset}`);
+                  printFindings(findings);
+                  blocked = true;
+                } else {
+                  log(`${COLOR.green}${paths.label}: approved ${approved.length} group(s)${COLOR.reset} — fingerprints stamped in ${path.relative(cwd, paths.mapFile)}`);
+                }
+              } catch (e) {
+                log(`${COLOR.red}${paths.label}:${COLOR.reset} ${e instanceof Error ? e.message : e}`);
+                blocked = true;
+              }
+            }
+            if (blocked) process.exit(1);
+            return;
+          }
+
+          const matrixSummaries: MatrixRunSummary[] = [];
+          const notExported: string[] = [];
+          for (const target of toExport) {
+            const s = await exportMatrixTarget(cwd, target, {
+              check: options.check, preview: options.preview, format: format as MatrixFormat,
+            });
+            if (s) matrixSummaries.push(s);
+            else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);
+          }
+          if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
+          printSkipSummary(skipped, notExported);
+          // A named target that produced nothing is a failure. A sweep is a failure
+          // only when it produced nothing at all — units still waiting for a map or
+          // an approval are the normal state of a live project. Preflight skips are
+          // not counted here: reaching this point in an explicit scope means
+          // --continue-on-missing was passed, which IS the opt-in to tolerate them.
+          const failed = explicitScope
+            ? notExported.length > 0
+            : matrixSummaries.length === 0;
+          if (failed) process.exit(1);
+          return;
+        }
+
         const env = getEnvironment(cwd);
         const summaries: ScreenSummary[] = [];
         for (const target of toExport) {
@@ -737,6 +955,10 @@ export function registerDeliveryCommand(program: Command): void {
 
         // 4. Summary
         printSummaryTable(summaries);
+        printSkipSummary(skipped, []);
+        // Same rule as the matrix path: every attempted target in an explicit scope
+        // must have produced a file; a sweep only fails when nothing was written.
+        if (explicitScope ? summaries.length < toExport.length : summaries.length === 0) process.exit(1);
       } catch (err) {
         console.error(`${COLOR.red}Fatal:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
         process.exit(1);

package/src/cli/commands/ingest.ts

@@ -1,14 +1,24 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { parseLegacyFile, listSheets, baselineAudit, BaselineReport, LegacyInventory, inventoryToGherkin, reconcileViewpoints, renderViewpointOverview, fetchGoogleSheet } from '../../ingest';
+import { parseLegacyFile, listSheets, baselineAudit, BaselineReport, LegacyInventory, inventoryToGherkin, reconcileViewpoints, renderViewpointOverview, fetchGoogleSheet, parseCSV } from '../../ingest';
+
+// A tab name that contains commas must round-trip through the quote-aware
+// --sheets parser — wrap it in doubled quotes inside the single-quoted shell arg.
+const quoteTab = (name: string) => (name.includes(',') ? `""${name}""` : name);
 
 function renderInventoryMd(inv: LegacyInventory, r: BaselineReport): string {
   const lines: string[] = [];
   lines.push(`# Legacy Testcase Inventory — ${inv.source.file}`, '');
   lines.push(`Total testcases: **${r.total}**`, '');
   lines.push('## Sheets', '', '| Sheet | Type | Rows |', '|---|---|---|');
-  for (const s of r.sheets) lines.push(`| ${s.name} | ${s.type} | ${s.rows} |`);
+  // Non-testcase tabs (Overview/SQL/review notes…) are classified but NEVER read —
+  // say so, or the listing reads as if their content was ingested.
+  for (const s of r.sheets) lines.push(s.type === 'testcase'
+    ? `| ${s.name} | ${s.type} | ${s.rows} |`
+    : `| ${s.name} | ${s.type} | — (skipped) |`);
+  const skipped = r.sheets.filter((s) => s.type !== 'testcase').length;
+  if (skipped) lines.push('', `_${skipped} non-testcase tab(s) skipped — no content read._`);
   lines.push('', '## By category', '');
   for (const [k, v] of Object.entries(r.byCategory).sort((a, b) => b[1] - a[1])) lines.push(`- ${k}: ${v}`);
   lines.push('', `Depth: **${(r.depthRatio * 100).toFixed(0)}%** (${r.deepCount}/${r.total} assert a concrete expected value)`, '');
@@ -22,7 +32,10 @@ function render(inv: LegacyInventory, r: BaselineReport): void {
   L(`━━━ Legacy Ingest — ${inv.source.file} ━━━`);
   L('');
   L(`  Sheets:`);
-  for (const s of r.sheets) L(`    • ${s.name} — ${s.type} (${s.rows})`);
+  for (const s of r.sheets)
+    L(`    • ${s.name} — ${s.type}${s.type === 'testcase' ? ` (${s.rows})` : ' → skipped (no content read)'}`);
+  const skipped = r.sheets.filter((s) => s.type !== 'testcase').length;
+  if (skipped) L(`    (${skipped} non-testcase tab(s) skipped)`);
   L('');
   L(`  TOTAL testcases: ${r.total}`);
   L('');
@@ -88,13 +101,52 @@ export function registerIngestCommand(program: Command): void {
           console.log('  Tabs found:');
           for (const s of sheets) console.log(`    • ${s.name} — ${s.type} (${s.rows} rows)`);
           console.log('');
-          console.log(`  Ingest the testcase tab(s) with: --sheets "${sheets.filter((s) => s.type === 'testcase').map((s) => s.name).join(',')}"`);
+          const quoted = sheets.filter((s) => s.type === 'testcase').map((s) => quoteTab(s.name)).join(',');
+          console.log(`  Ingest the testcase tab(s) with: --sheets '${quoted}'`);
           console.log('');
           return;
         }
 
-        const onlySheets: string[] | undefined = options.sheets ? String(options.sheets).split(',') : undefined;
+        // --sheets: legacy tab names may CONTAIN commas (field workbook:
+        // "EX-0403,0404,0405,0407-SearchRe"), so a bare split(',') shredded them and
+        // silently ingested nothing. Resolution order:
+        //   1. the WHOLE string equals one real tab name → that single tab;
+        //   2. else parse as a quote-aware CSV line ("Tab, with commas",Other);
+        //   3. any part matching NO real tab → exit non-zero listing the tabs —
+        //      an empty inventory must never be produced silently.
+        let onlySheets: string[] | undefined;
+        if (options.sheets) {
+          const raw = String(options.sheets);
+          const available = (await listSheets(files)).map((sh) => sh.name);
+          const byLower = new Map(available.map((n) => [n.trim().toLowerCase(), n]));
+          const whole = byLower.get(raw.trim().toLowerCase());
+          if (whole) {
+            onlySheets = [whole];
+          } else {
+            const parts = (parseCSV(raw)[0] || []).map((p) => p.trim()).filter(Boolean);
+            const misses = parts.filter((pt) => !byLower.has(pt.toLowerCase()));
+            if (misses.length) {
+              throw new Error(
+                `--sheets: no tab named ${misses.map((m) => `"${m}"`).join(', ')}.\n` +
+                `  Available tabs:\n${available.map((n) => `    • ${n}`).join('\n')}\n` +
+                `  Tip: quote a tab name that contains commas: --sheets '"${available[0] || 'Tab, name'}"'`
+              );
+            }
+            onlySheets = parts.map((pt) => byLower.get(pt.toLowerCase())!);
+          }
+        }
         const inv = await parseLegacyFile(files, onlySheets);
+        for (const w of inv.warnings ?? []) console.warn(`  \u26a0 ${w}`);
+        // Merge guard: without --sheets, EVERY tab that classifies as testcase is merged
+        // into one inventory. Field workbooks carry tabs for several screens (plus
+        // deprecated "Old\u2026" copies) \u2014 merging them silently poisons a per-screen
+        // inventory, so say it loudly and hand over the ready-made --sheets line.
+        if (!options.sheets) {
+          const tcTabs = inv.sheets.filter((sh) => sh.type === 'testcase');
+          if (tcTabs.length > 1) {
+            console.warn(`  \u26a0 ${tcTabs.length} testcase tabs merged into ONE inventory \u2014 if they belong to different screens, scope with: --sheets '${tcTabs.map((sh) => quoteTab(sh.name)).join(',')}'`);
+          }
+        }
         const report = baselineAudit(inv);
         fs.writeFileSync(path.join(outDir, 'inventory.json'), JSON.stringify({ inventory: inv, baseline: report }, null, 2));
         fs.writeFileSync(path.join(outDir, 'inventory.md'), renderInventoryMd(inv, report));

package/src/cli/index.ts

@@ -35,6 +35,7 @@ import { registerRepairCommand } from './commands/repair';
 import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
+import { warnAssetsDrift } from '../orchestrator/assets-drift';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
@@ -88,6 +89,11 @@ async function main() {
     for (const registerCommand of cap.cliCommands ?? []) registerCommand(program);
   }
 
+  // Every command warns once when the project's AI assets came from a different
+  // build — `update` is the only thing that refreshes them, and nothing used to
+  // say so (stderr, so `--json` output stays parseable).
+  program.hook('preAction', () => { warnAssetsDrift(process.cwd()); });
+
   await program.parseAsync(process.argv);
 }
 

package/src/dashboard/snapshot-builder.ts

@@ -23,6 +23,7 @@ import { loadPlaywrightReport, resolveResultsPath } from '../exporters/playwrigh
 import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
 import { buildScreenSnapshot } from '../exporters/json-exporter';
 import { loadApiCatalog } from '../exporters/api-catalog-loader';
+import { resolveApiEnvironment } from '../exporters/api-environment';
 import { buildApiDetailRows } from '../exporters/xlsx-exporter';
 import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { discoverLocaleVariants, LocaleVariant } from '../exporters/locale-variants';
@@ -132,9 +133,15 @@ function buildOneScreen(
   // shared+unit merge delivery.ts uses — so Steps/Expected cells and the API
   // detail sheet match the delivery CSV/XLSX exactly.
   const apiCatalog = loadApiCatalog(cwd, target.kind, target.name);
+  // API units call the datasource base_url, not the web baseURL from
+  // playwright.config.ts — same Test-Environment override as delivery.ts, so the
+  // dashboard's Suites/Export cells never disagree with the CSV/XLSX deliverable.
+  const unitEnv = target.kind === 'api'
+    ? { ...env, ...(resolveApiEnvironment(cwd, apiCatalog) ?? {}) }
+    : env;
   const features: FeatureSnapshot[] = [];
   for (const featureBaseName of featureBaseNames) {
-    features.push(...buildOneFeature(cwd, target, featureBaseName, env, specLink, mobile, apiCatalog));
+    features.push(...buildOneFeature(cwd, target, featureBaseName, unitEnv, specLink, mobile, apiCatalog));
   }
   if (features.length === 0) return null;