@sun-asterisk/sungen 3.2.24 → 3.2.25

package/src/cli/commands/changed.ts

@@ -0,0 +1,104 @@
+/**
+ * `sungen changed` — which scenarios does the current edit oblige a re-run of?
+ *
+ * Backs `run-test --change-only`. The selection is computed here rather than in the AI workflow so
+ * it is deterministic and testable: the same edit always yields the same list, and the list can be
+ * asserted in CI. The workflow's job is only to run it, merge, and record.
+ *
+ * Bias: when an edit cannot be attributed to specific scenarios, EVERY scenario is selected and the
+ * output says so. Over-running costs minutes; under-running reports a scenario green that never
+ * re-ran after the change that broke it.
+ */
+import { Command } from 'commander';
+import { buildRunManifest, readRunManifest, writeRunManifest, selectChanged } from '../../harness/run-manifest';
+import { findUnitDir } from '../resolve-unit';
+import { execFileSync } from 'child_process';
+import * as path from 'path';
+
+/**
+ * Run-affecting files git reports changed for this unit, or [] when git has no usable opinion.
+ *
+ * Deliberately narrow and fail-quiet:
+ *  - not a repo, or the unit is UNTRACKED → [] (git knows nothing; the dogfood project is exactly
+ *    this case, and treating "untracked" as "changed" would widen on every single run);
+ *  - only `features/`, `selectors/`, `test-data/` count — a spec.md or screenshot edit is
+ *    regeneration territory (`sungen manifest --diff`), not a reason to re-run;
+ *  - `diff HEAD` so staged and unstaged edits both count.
+ */
+function gitChangedFiles(unitDir: string): string[] {
+  const rel = path.relative(process.cwd(), unitDir) || '.';
+  const git = (args: string[]): string =>
+    execFileSync('git', args, { cwd: process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+  try {
+    if (!git(['ls-files', rel]).trim()) return [];   // untracked unit → git has no baseline
+    return git(['diff', 'HEAD', '--name-only', '--', rel])
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => /\/(features|selectors|test-data)\//.test(l));
+  } catch {
+    return [];   // no git, no repo, detached weirdness — the fingerprint still decides
+  }
+}
+
+/** Escape a scenario title for a `-g` / `--mochaOpts.grep` regex. */
+const toGrep = (titles: string[]): string =>
+  titles.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+
+export function registerChangedCommand(program: Command): void {
+  program
+    .command('changed')
+    .description('List the scenarios a selectors/test-data/feature edit obliges you to re-run (backs run-test --change-only)')
+    .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 selection as JSON')
+    .option('--grep', 'Output ONLY a regex of the selected titles, for -g / --mochaOpts.grep')
+    .option('--record', 'Record the current inputs as the new baseline (run this AFTER a successful run)')
+    .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 cwd = process.cwd();
+        const after = buildRunManifest(cwd, dir, name);
+
+        if (options.record) {
+          const p = writeRunManifest(cwd, name, after);
+          console.log(`✓ recorded run baseline for ${name} → ${p.replace(`${cwd}/`, '')} (${Object.keys(after.scenarios).length} scenarios)`);
+          return;
+        }
+
+        const selection = selectChanged(readRunManifest(cwd, name), after, gitChangedFiles(dir));
+
+        if (options.grep) {
+          // Empty output is meaningful: nothing to run. A caller must treat "" as "skip the run",
+          // never as "match everything" — an empty grep would run the whole suite.
+          console.log(toGrep(selection.scenarios));
+          return;
+        }
+        if (options.json) { console.log(JSON.stringify(selection, null, 2)); return; }
+
+        const { total, selected, firstRun } = selection.summary;
+        console.log(`\n━━━ Change selection: ${name} ━━━`);
+        if (!selected) {
+          console.log(`  ✓ Nothing changed since the last recorded run — ${total} scenario(s) still current.\n`);
+          return;
+        }
+        if (selection.all) {
+          console.log(`  ⚠ ALL ${total} scenario(s) selected — ${selection.reasons[selection.scenarios[0]]}.`);
+          console.log(firstRun
+            ? '    Record a baseline after this run so the next one can narrow: sungen changed --screen ' + name + ' --record\n'
+            : '    An unattributable edit widens to the whole unit on purpose — a missed scenario would report green without re-running.\n');
+          return;
+        }
+        console.log(`  ${selected} of ${total} scenario(s) need a re-run:\n`);
+        for (const t of selection.scenarios) console.log(`  ↻ ${t}\n      ${selection.reasons[t]}`);
+        console.log('');
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/delivery.ts

@@ -436,7 +436,8 @@ async function exportTarget(
     const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : '';
     const explicitEnv = process.env.SUNGEN_ENV;
 
-    // For api-kind units, load the endpoint catalog so we can add the API detail sheet.
+    // Load the endpoint catalog for every kind: api-kind gets the API detail sheet;
+    // screen/flow rows name their @api precondition endpoints from it.
     const apiCatalog = loadApiCatalog(cwd, target.kind, target.screen);
     const hasApiCatalog = target.kind === 'api' && Object.keys(apiCatalog).length > 0;
 
@@ -672,8 +673,21 @@ async function exportMatrixTarget(
   cwd: string,
   target: DeliveryTarget,
   opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
-): Promise<MatrixRunSummary | null> {
+): Promise<MatrixRunSummary | 'skipped' | null> {
   const paths = matrixPathsFor(cwd, target);
+
+  // 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}`);
+      return 'skipped';
+    }
+  }
+
   const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
 
   if (mapMissing) {
@@ -937,6 +951,16 @@ export function registerDeliveryCommand(program: Command): void {
             let blocked = false;
             for (const target of toExport) {
               const paths = matrixPathsFor(cwd, target);
+              // 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)))) {
+                  log(`${COLOR.gray}${paths.label}: nothing to approve — all scenario(s) are @exploration probes.${COLOR.reset}`);
+                  continue;
+                }
+              }
               try {
                 const { findings, approved } = approveMatrix(paths, ids);
                 if (approved.length === 0) {
@@ -961,6 +985,7 @@ export function registerDeliveryCommand(program: Command): void {
             const s = await exportMatrixTarget(cwd, target, {
               check: options.check, preview: options.preview, format: format as MatrixFormat,
             });
+            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

@@ -200,7 +200,7 @@ export function registerGenerateCommand(program: Command): void {
           console.log(`\n⚠️  Compile diagnostics (${diagnostics.count}):`);
           for (const line of diagnostics.formatLines().slice(0, 20)) console.log(`   ${line}`);
           if (diagnostics.count > 20) console.log(`   … and ${diagnostics.count - 20} more`);
-          console.log(`   Unmatched steps compile to no-op // TODO comments — the test runs weaker than it reads.`);
+          console.log(`   Unsupported steps compile to a runtime throw — the test fails loudly instead of passing having checked nothing.`);
           if (options.strict) {
             console.error(`\n--strict: failing generation on ${diagnostics.count} diagnostic(s).`);
             process.exit(1);

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

@@ -0,0 +1,153 @@
+/**
+ * `sungen results merge` — fold a subset re-run's Playwright JSON report into
+ * the existing per-target result file instead of overwriting it. See
+ * exporters/results-merge.ts for the title-keyed semantics; this command owns
+ * path resolution, validation, ghost warnings, and the atomic write.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Command } from 'commander';
+import { mergeResultsReports, findGhostTitles } from '../../exporters/results-merge';
+import { resolveResultsPath } from '../../exporters/playwright-report-parser';
+import { parseSpecFile } from '../../exporters/spec-parser';
+
+interface MergeCliOptions {
+  out?: string;
+  screen?: string;
+}
+
+function readReport(file: string, label: string): any {
+  if (!fs.existsSync(file)) {
+    throw new Error(`results merge: ${label} file not found: ${file}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`results merge: ${label} file is not valid JSON (${file}): ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/**
+ * Resolve the generated dir that owns FEATURE `name` — by its spec file, not by
+ * unit-dir name: a multi-feature screen keeps `home.spec.ts` AND
+ * `home-modal.spec.ts` in specs/generated/home/, and each feature has its OWN
+ * per-target result file. Kind order mirrors delivery's target resolution
+ * (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 {
+  const roots = [
+    path.join(cwd, 'specs', 'generated', 'flows'),
+    path.join(cwd, 'specs', 'generated'),
+    path.join(cwd, 'specs', 'generated', 'api'),
+    path.join(cwd, 'specs', 'generated', 'api', 'flows'),
+  ];
+  const hits: string[] = [];
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const unit of fs.readdirSync(root)) {
+      const dir = path.join(root, unit);
+      // the middle root also contains flows/ and api/ themselves — units only
+      if (['flows', 'api'].includes(unit) && root.endsWith(path.join('specs', 'generated'))) continue;
+      if (fs.existsSync(path.join(dir, `${name}.spec.ts`)) && !hits.includes(dir)) hits.push(dir);
+    }
+  }
+  if (hits.length === 0) {
+    throw new Error(`results merge: no generated spec named "${name}.spec.ts" found under specs/generated/ — pass the feature basename (a multi-feature screen has one result file PER feature), and run sungen generate first.`);
+  }
+  if (hits.length > 1) {
+    throw new Error(`results merge: "${name}" is ambiguous — found in ${hits.map((h) => path.relative(cwd, h)).join(' and ')}. Use the explicit two-file form.`);
+  }
+  return hits[0];
+}
+
+/**
+ * Runs the merge. Exported for tests; the commander wiring below is a thin
+ * shell around it. Returns the path written.
+ */
+export function runResultsMerge(baseArg: string | undefined, newArg: string | undefined, opts: MergeCliOptions, cwd: string = process.cwd()): string {
+  let baseFile = baseArg;
+  let newFile = newArg;
+  let specTitles: string[] | null = null;
+
+  if (opts.screen) {
+    // Convenience form: `results merge --screen <name> <fresh.json>` — <name> is
+    // the FEATURE basename; its per-target file lives next to its spec, with the
+    // same in-dir candidate order delivery reads.
+    if (baseArg && newArg) throw new Error('results merge: --screen takes ONE report file (the fresh subset run).');
+    newFile = baseArg ?? newArg;
+    if (!newFile) throw new Error('results merge: --screen needs the fresh subset report file as the argument.');
+    const dir = resolveFeatureDir(cwd, opts.screen);
+    baseFile = resolveResultsPath(cwd, dir, opts.screen);
+    // resolveResultsPath falls back to the cwd-global test-results/results.json —
+    // a file shared by EVERY unit. Merging one unit's subset into it would report
+    // success while delivery keeps reading the stale per-target file: refuse.
+    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).`);
+    }
+    // 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; }
+  }
+
+  if (!baseFile || !newFile) {
+    throw new Error('results merge: expected <base.json> <new.json>, or --screen <name> <new.json>.');
+  }
+
+  const base = readReport(baseFile, 'base');
+  const fresh = readReport(newFile, 'new');
+  const { merged, replaced, added, kept } = mergeResultsReports(base, fresh);
+
+  if (specTitles) {
+    // A fresh report whose ADDED titles are unknown to this feature's spec was
+    // produced by a DIFFERENT feature — writing it here would silently corrupt
+    // this file while the right one stays stale. Refuse before writing.
+    const foreign = findGhostTitles(added, specTitles);
+    if (foreign.length > 0) {
+      throw new Error(`results merge: ${foreign.length} title(s) in ${path.basename(newFile)} match no scenario of "${opts.screen}" (e.g. ${foreign[0]}) — is this another feature's report? Base file untouched.`);
+    }
+    const ghosts = findGhostTitles(kept, specTitles);
+    if (ghosts.length > 0) {
+      console.warn(`⚠ ${ghosts.length} result title(s) no longer match any current scenario (renamed by a spec edit?) — kept, not deleted:`);
+      for (const g of ghosts.slice(0, 10)) console.warn(`   - ${g}`);
+      if (ghosts.length > 10) console.warn(`   … and ${ghosts.length - 10} more`);
+    }
+  }
+
+  // Atomic write: a crash mid-write must never leave a truncated result file —
+  // 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;
+  }
+
+  console.log(`✓ merged ${path.basename(newFile)} into ${path.relative(cwd, outFile)} — ${replaced.length} updated, ${added.length} added, ${kept.length} kept`);
+  return outFile;
+}
+
+export function registerResultsCommand(program: Command): void {
+  const results = program
+    .command('results')
+    .description('Operate on per-target Playwright result files');
+
+  results
+    .command('merge [base] [new]')
+    .description('Merge a subset re-run\'s report into an existing result file (same title → new wins; others kept)')
+    .option('-o, --out <file>', 'write the merged report here instead of overwriting the base file')
+    .option('--screen <name>', 'resolve the base file from this FEATURE basename (a multi-feature screen has one result file per feature); pass only the fresh report as the argument')
+    .action((baseArg: string | undefined, newArg: string | undefined, opts: MergeCliOptions) => {
+      try {
+        runResultsMerge(baseArg, newArg, opts);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -1,5 +1,9 @@
 import { Command } from 'commander';
 import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { coreVersion } from '../../orchestrator/lockstep-version';
+import { syncProjectSungenDeps } from '../../orchestrator/project-deps-sync';
 
 /**
  * `sungen update` does two jobs in sequence:
@@ -7,8 +11,12 @@ import { spawnSync } from 'child_process';
  *  1. Reinstall `@sun-asterisk/sungen@latest` globally via npm so the bundled
  *     AI templates are refreshed.
  *  2. Re-execute `sungen update` with the env var `SUNGEN_UPDATE_SKIP_NPM=1`
- *     so the AI rules / commands / skills inside the project get overwritten
- *     from the *new* templates.
+ *     so the *new* binary (a) reconciles the project's own sungen packages onto
+ *     its version line and (b) overwrites the AI rules / commands / skills
+ *     inside the project from the new templates.
+ *
+ * Step 2 runs under the NEW binary on purpose: the version the project should be
+ * pinned to is the one doing the pinning, so the two can never disagree.
  *
  * We use an environment variable (not a CLI flag) for the internal hand-off
  * because Commander throws "unknown option" if the currently-installed
@@ -23,6 +31,12 @@ import { spawnSync } from 'child_process';
 
 const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
 
+/**
+ * Carried to the re-exec as an env var for the same reason as SKIP_NPM_ENV: a flag would crash an
+ * older published binary with "unknown option", an env var is ignored by it.
+ */
+const SKIP_PROJECT_ENV = 'SUNGEN_UPDATE_SKIP_PROJECT';
+
 export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
@@ -48,13 +62,20 @@ export function registerUpdateCommand(program: Command): void {
     )
     .option(
       '--skip-npm-install',
-      'Skip the npm install step (refresh project AI assets only)',
+      'Skip the global npm install step (refresh project AI assets only)',
+      false,
+    )
+    .option(
+      '--skip-project',
+      'Skip reinstalling the project-local sungen packages (AI assets only — leaves node_modules stale)',
       false,
     )
-    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean; assistant?: string[]; force?: boolean }) => {
+    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean; skipProject?: boolean; assistant?: string[]; force?: boolean }) => {
       try {
         const skipNpm =
           Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
+        const skipProject =
+          Boolean(options.skipProject) || process.env[SKIP_PROJECT_ENV] === '1';
 
         // Channel resolution via npm dist-tags. Default `latest` = official/stable.
         // `--beta` → beta channel; running plain `sungen update` later switches back to stable.
@@ -63,10 +84,18 @@ export function registerUpdateCommand(program: Command): void {
         if (!skipNpm) {
           reinstallSungen(channel);
           printCurrentVersion(channel);
-          reExecUpdateForAIAssets(options.dryRun ?? false, options.assistant ?? [], options.force ?? false);
+          reExecUpdateForAIAssets(options.dryRun ?? false, options.assistant ?? [], options.force ?? false, skipProject);
           return;
         }
 
+        // Running under the NEW binary now: pin the project's own copies to THIS version before
+        // refreshing the AI assets, so the compiler the project runs matches the templates it gets.
+        if (skipProject) {
+          console.log('⏭  Skipping project-local package sync (--skip-project).\n');
+        } else {
+          syncProjectSungenDeps(process.cwd(), coreVersion(), options.dryRun ?? false);
+        }
+
         const { resolveAssistants } = require('../../orchestrator/ai-skills/resolve-assistants');
         const { AIRulesUpdater } = require('../../orchestrator/ai-rules-updater');
         const updater = new AIRulesUpdater(process.cwd());
@@ -94,8 +123,15 @@ function reinstallSungen(channel: string): void {
 }
 
 function printCurrentVersion(channel: string): void {
-  console.log('\n🔎 Installed version:');
-  spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
+  console.log('\n🔎 Installed version (global):');
+  // Same PATH caveat as the re-exec: report the version that was just installed globally, not a
+  // project-local copy that happens to shadow it.
+  const entry = globalCoreEntry();
+  if (entry) {
+    spawnSync(process.execPath, [entry, '--version'], { stdio: 'inherit' });
+  } else {
+    spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
+  }
   if (channel === 'latest') {
     console.log('   Channel: stable. To try prereleases:  sungen update --beta');
   } else {
@@ -104,17 +140,40 @@ function printCurrentVersion(channel: string): void {
   console.log('');
 }
 
-function reExecUpdateForAIAssets(dryRun: boolean, assistants: string[], force: boolean): void {
+/**
+ * Absolute path to the globally installed core's CLI entry, or null when it can't be located
+ * (then the caller falls back to a PATH lookup). Asks npm for the global root instead of guessing
+ * a prefix, so nvm / Volta / Windows / custom-prefix installs all resolve correctly.
+ */
+function globalCoreEntry(): string | null {
+  try {
+    const out = spawnSync('npm', ['root', '-g'], { encoding: 'utf-8', shell: true });
+    const root = out.status === 0 ? (out.stdout || '').trim() : '';
+    if (!root) return null;
+    const entry = path.join(root, '@sun-asterisk', 'sungen', 'bin', 'sungen.js');
+    return fs.existsSync(entry) ? entry : null;
+  } catch {
+    return null;
+  }
+}
+
+function reExecUpdateForAIAssets(dryRun: boolean, assistants: string[], force: boolean, skipProject: boolean): void {
   const args = ['update'];
   if (dryRun) args.push('--dry-run');
   if (force) args.push('--force');
   for (const a of assistants) args.push('--assistant', a);
 
-  const result = spawnSync('sungen', args, {
-    stdio: 'inherit',
-    shell: true,
-    env: { ...process.env, [SKIP_NPM_ENV]: '1' },
-  });
+  const env: NodeJS.ProcessEnv = { ...process.env, [SKIP_NPM_ENV]: '1' };
+  if (skipProject) env[SKIP_PROJECT_ENV] = '1';
+
+  // Run the JUST-INSTALLED global entry directly rather than whatever `sungen` resolves to on PATH.
+  // Inside a project, `npx sungen update` / `npm run` put the project's own bin dir FIRST on PATH, so
+  // a PATH lookup here re-executes the OLD local copy — step 2 would then refresh nothing, which is
+  // exactly the "update ran but the project didn't change" failure this flow exists to prevent.
+  const entry = globalCoreEntry();
+  const result = entry
+    ? spawnSync(process.execPath, [entry, ...args], { stdio: 'inherit', env })
+    : spawnSync('sungen', args, { stdio: 'inherit', shell: true, env });
 
   if (result.status !== 0) {
     console.error(

package/src/cli/index.ts

@@ -22,6 +22,7 @@ import { registerGateCommand } from './commands/gate';
 import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
+import { registerChangedCommand } from './commands/changed';
 import { registerLedgerCommand } from './commands/ledger';
 import { registerFeedbackCommand } from './commands/feedback';
 import { registerQaFeedbackCommand } from './commands/qa-feedback';
@@ -34,6 +35,7 @@ import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
 import { registerContextCommand } from './commands/context';
 import { registerRepairCommand } from './commands/repair';
+import { registerResultsCommand } from './commands/results-merge';
 import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
@@ -70,6 +72,7 @@ async function main() {
   registerJourneyCommand(program);
   registerGateCommand(program);
   registerManifestCommand(program);
+  registerChangedCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);
   registerQaFeedbackCommand(program);
@@ -82,6 +85,7 @@ async function main() {
   registerFlowCheckCommand(program);
   registerContextCommand(program);
   registerRepairCommand(program);
+  registerResultsCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
   registerLoginCommand(program);

package/src/exporters/api-catalog-loader.ts

@@ -22,9 +22,17 @@ export function loadApiCatalog(
   kind: 'screen' | 'flow' | 'api',
   screen: string,
 ): Record<string, ApiCatalogEntry> {
-  if (kind !== 'api') return {};
+  // Every kind can carry `@api:` preconditions, and the runtime resolves their
+  // endpoints from the UNIT's own catalog first (qa/screens|flows/<u>/api/apis.yaml)
+  // then the shared one — this loader mirrors that scheme so the deliverable can
+  // name the endpoint a screen/flow scenario actually calls.
+  const unitDir = kind === 'api'
+    ? path.join(cwd, 'qa', 'api', screen)
+    : kind === 'flow'
+      ? path.join(cwd, 'qa', 'flows', screen)
+      : path.join(cwd, 'qa', 'screens', screen);
   const shared = readApiCatalogFile(path.join(cwd, 'qa', 'api', 'apis.yaml'));
-  const unit = readApiCatalogFile(path.join(cwd, 'qa', 'api', screen, 'api', 'apis.yaml'));
+  const unit = readApiCatalogFile(path.join(unitDir, 'api', 'apis.yaml'));
   return { ...shared, ...unit };
 }
 

package/src/exporters/api-testcase-formatter.ts

@@ -98,7 +98,7 @@ function callBlockLines(call: ApiCall, entry: ApiCatalogEntry, localize: (text:
   const filesStr = formatFiles(entry.files, call.args, localize);
   const bodyFileStr = formatBodyFile(entry.bodyFile, call.args, localize);
   // Body is scalar fields; a pure file upload may have none → still show `Body: —` for a stable shape.
-  lines.push(`Body: ${formatBody(entry.body, call.args, localize)}`);
+  lines.push(`Body: ${formatBody(entry.body, call.args, localize, entry)}`);
   if (filesStr) lines.push(`Files: ${filesStr}`);
   if (bodyFileStr) lines.push(`Body file: ${bodyFileStr}`);
   return lines;
@@ -111,6 +111,24 @@ function callBlockLines(call: ApiCall, entry: ApiCatalogEntry, localize: (text:
  * has more than one call — same style as formatApiRequest — which also keeps a
  * deliberately repeated call distinct through the matrix's precondition Set-dedup.
  */
+/**
+ * Terse one-line-per-call summary for a screen/flow row's PRE-CONDITION cell:
+ * `Call API <name> — <METHOD> <path>`. Built on the strict parseApiCalls so the
+ * deliverable never documents a call the runtime silently dropped (a malformed
+ * tag never runs). Only name/method/path from the catalog render — tag args
+ * carry runtime values. A missing endpoint is loud; a present entry missing a
+ * field shows `—` for that field instead of blaming the wrong file.
+ */
+export function formatApiCallSummaryLines(tags: string[], catalog: Record<string, ApiCatalogEntry>): string[] {
+  return parseApiCalls(tags).map(({ name }) => {
+    const entry = catalog[name];
+    if (!entry) return `Call API ${name} — (endpoint not in apis.yaml)`;
+    const method = typeof entry.method === 'string' && entry.method ? entry.method.toUpperCase() : '—';
+    const apiPath = typeof entry.path === 'string' && entry.path ? entry.path : '—';
+    return `Call API ${name} — ${method} ${apiPath}`;
+  });
+}
+
 export function formatApiCallLines(
   calls: ApiCall[],
   catalog: Record<string, ApiCatalogEntry>,
@@ -185,6 +203,38 @@ function bindParams(raw: string, args: Record<string, string>): string {
   });
 }
 
+/**
+ * Whitelist variant for XML string bodies: bind ONLY the declared param names
+ * (longest first, word-boundary guarded) — the generic `:word` scan above would
+ * rewrite namespace prefixes (soapenv:Envelope) into garbage cells. Mirrors the
+ * runtime's whitelist binding.
+ */
+function bindXmlParamsForCell(raw: string, args: Record<string, string>, paramNames: string[]): string {
+  let out = raw;
+  for (const p of [...paramNames].sort((a, b) => b.length - a.length)) {
+    const expr = p in args ? args[p] : `{{${p}}}`;
+    out = out.replace(new RegExp(`:${p}(?![A-Za-z0-9_])`, 'g'), () => unquoteExpr(expr));
+  }
+  return out;
+}
+
+/**
+ * Mask the value of credential-named ELEMENTS inside an XML string body
+ * (`<signature>…</signature>` → `<signature>***</signature>`). The object-body
+ * masking below never sees a string template, so without this the raw signature
+ * from the catalog example would print verbatim in the client's API detail sheet.
+ */
+function maskXmlSensitiveElements(xml: string): string {
+  // The open tag may carry attributes (<signature type="hmac">) and the value may
+  // be a CDATA section — both are common spellings for exactly the credential
+  // elements this masks, so the pattern must accept them or the secret prints raw.
+  return xml.replace(
+    /(<([A-Za-z0-9_.:-]+)(?:\s[^>]*)?>)((?:<!\[CDATA\[[\s\S]*?\]\]>|[^<])*)(<\/\2>)/g,
+    (whole, open: string, tag: string, _value: string, close: string) =>
+      SENSITIVE_NAME.test(tag) ? `${open}***${close}` : whole,
+  );
+}
+
 /** Strip a matching pair of surrounding quotes from a tag-arg literal (`"x"` → `x`). */
 function unquoteExpr(e: string): string {
   const m = e.match(/^"(.*)"$/) || e.match(/^'(.*)'$/);
@@ -230,6 +280,7 @@ function formatHeaders(
 function contentTypeFor(encoding?: string): string {
   if (encoding === 'form') return 'application/x-www-form-urlencoded';
   if (encoding === 'multipart') return 'multipart/form-data';
+  if (encoding === 'xml') return 'application/xml';
   return 'application/json';
 }
 
@@ -247,8 +298,13 @@ function uploadContentType(entry: ApiCatalogEntry): string {
  * that field can be replaced with `***`; otherwise the body resolves wholesale
  * (preserving numbers/nesting exactly as before).
  */
-function formatBody(body: unknown, args: Record<string, string>, localize: (text: string) => string): string {
+function formatBody(body: unknown, args: Record<string, string>, localize: (text: string) => string, entry?: ApiCatalogEntry): string {
   if (body === undefined || body === null) return '—';
+  // XML string template: whitelist-bind declared params, then mask credential elements.
+  if (entry?.encoding === 'xml' && typeof body === 'string') {
+    const names = Array.isArray(entry.params) ? (entry.params as string[]) : [];
+    return localize(maskXmlSensitiveElements(bindXmlParamsForCell(body, args, names)));
+  }
   if (isPlainObject(body)) {
     const obj = body as Record<string, unknown>;
     if (Object.keys(obj).some(isSensitiveField)) {
@@ -321,7 +377,7 @@ function formatBodyFile(bodyFile: unknown, args: Record<string, string>, localiz
  * test-data keys — catches variants like confirmPassword / new_password /
  * password_confirmation / access_token / client_secret / otp / passcode.
  */
-export const SENSITIVE_NAME = /pass(word|code)?|passwd|pwd|secret|token|otp|api[-_]?key|apikey|credential|authorization/i;
+export const SENSITIVE_NAME = /pass(word|code)?|passwd|pwd|secret|token|otp|api[-_]?key|apikey|credential|authorization|signature/i;
 function isSensitiveField(key: string): boolean {
   return SENSITIVE_NAME.test(key);
 }

package/src/exporters/csv-exporter.ts

@@ -23,7 +23,7 @@ import {
   statusToTestResult,
 } from './playwright-report-parser';
 import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
-import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
+import { collectSecretValues, formatApiCallSummaryLines, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 import { formatVariantRow, resolveResultVariants } from './result-variants';
 import { collectQaEnvSecretDenylist, warnIfRedactionIncomplete } from './qa-env-secret-denylist';
@@ -103,9 +103,18 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     };
     const formatStep = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
       localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
+    // `@api:` preconditions on a screen/flow scenario run before its UI steps —
+    // without these lines the deliverable never names the real endpoint (QA
+    // post-processed every export to add them back). They belong in the
+    // PRE-CONDITION cell, the same home Background moved to: inlining setup in
+    // Steps shifts the numbering and every `— after step N` anchor with it.
+    // kind:api keeps its own richer request-block rendering below.
+    const apiCallLines = (input.kind === 'screen' || input.kind === 'flow') && input.apiCatalog && hasApiCalls(m.feature.tags)
+      ? formatApiCallSummaryLines(m.feature.tags, input.apiCatalog)
+      : [];
     const precondition = formatPrecondition(
       authRole,
-      (m.resolvedBackgroundSteps ?? []).map(formatStep).filter(Boolean)
+      [...(m.resolvedBackgroundSteps ?? []).map(formatStep).filter(Boolean), ...apiCallLines]
     );
     const stepLines = m.resolvedSteps.map(formatStep).filter(Boolean);
     // Scenarios whose assertions verify different moments render Expected as