@sun-asterisk/sungen 3.2.17 → 3.2.18

package/dist/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -295,6 +295,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
 | `@manual` | Skip in generation |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |

package/dist/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -4,6 +4,28 @@ description: 'Use when create-test needs to translate spec.md/Figma/UI into .fea
 user-invocable: false
 ---
 
+
+## Traceability — tag the requirement each scenario proves
+
+Every requirement id in `requirements/spec.md` (`FR-`/`TR-`/`NFR-`) must be reachable from a
+scenario, and the link must be **written down, not inferred**:
+
+```gherkin
+@high @spec:FR-003
+Scenario: VP-VAL-002 An email in an invalid format shows the format error
+```
+
+- Put `@spec:<id>` on the scenario that actually proves the requirement; repeat the tag when one
+  scenario proves several (`@spec:FR-003 @spec:FR-004`).
+- One requirement may be proved by several scenarios — tag each of them.
+- A requirement you deliberately do not cover here (performance budget, i18n suite, server-side
+  concern) needs no tag; record it later in the delivery map's `requirements:` section with a
+  status and reason.
+- Why it matters: `sungen audit` also counts a requirement as covered when its keywords merely
+  resemble a scenario title, and reports `SPEC-TRACE-IMPLICIT` for those. Delivery's requirement
+  table follows **only** the explicit tag — an untagged requirement reads as an uncovered gap in
+  the customer-facing coverage sheet even when a scenario does prove it.
+
 ## ⚠️ Gotchas — read before generating
 
 - **Field-level test-data follows the Data Factory standard — don't hand-invent values.** When the unit has input fields, the field values (valid / boundary / invalid + error codes) come from the **`sungen-data-factory`** catalog via a field-map + `sungen data gen` (create-test step 5.3), not free-form guessing. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. This skill still owns scenario structure, viewpoints, and non-field oracles.
@@ -318,6 +340,7 @@ Security:         [S1 – admin only]
 `sungen audit` enforces these. Generate compliant output up front:
 
 1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+   - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → propose the diff and ask. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
 2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
    - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.17",
+  "version": "3.2.18",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.17",
-    "@sungen/driver-ui": "3.2.17",
+    "@sungen/driver-data-factory": "3.2.18",
+    "@sungen/driver-ui": "3.2.18",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

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/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;