@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/cli/commands/capability.ts

@@ -9,43 +9,9 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
+import { coreVersion, resolveDriverVersion } from '../../orchestrator/lockstep-version';
 import { findUnitDir, resolveUnit } from '../resolve-unit';
 
-/** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
-function coreVersion(): string {
-  try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
-}
-
-/**
- * Resolve the driver version to install for the running core `core`.
- *
- * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
- * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
- * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
- * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
- * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
- */
-function resolveDriverVersion(pkg: string, core: string): string {
-  if (core === 'latest') return 'beta';
-  try {
-    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
-    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
-    let versions: string[] = [];
-    const parsed = JSON.parse(out.stdout);
-    versions = Array.isArray(parsed) ? parsed : [parsed];
-    if (versions.includes(core)) return core; // exact exists → lockstep
-    const prefix = `${core}-beta.`;
-    const betas = versions
-      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
-      .map((v) => parseInt(v.slice(prefix.length), 10))
-      .filter((n) => Number.isInteger(n));
-    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
-    return 'beta'; // nothing on this line → newest beta dist-tag
-  } catch {
-    return core;
-  }
-}
-
 /**
  * Add `test:mobile` to the project's package.json scripts (if absent).
  * Idempotent — skips if the script is already set.
@@ -140,7 +106,7 @@ export function registerCapabilityCommand(program: Command): void {
         const resolved = resolveUnit(o.screen);
         if (!resolved) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
         // The catalog unit id carries the unit KIND, which gates which drivers can serve it.
-        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId);
+        const plan = buildPlan(resolved.dir, o.screen, resolved.unitId, readCapabilities(process.cwd()).platform);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
@@ -166,9 +132,9 @@ export function registerCapabilityCommand(program: Command): void {
           }
         }
         if (plan.unavailable.length) {
-          L('  Cannot help here (driver does not support this unit kind — do NOT install):');
+          L('  Cannot help here (driver cannot serve this unit kind or platform — do NOT install):');
           for (const r of plan.unavailable) {
-            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` has no ${r.unitKind} support; automate the behaviour on the owning SCREEN unit instead`);
+            L(`     • ${r.count} @manual:${r.reason} → \`${r.driver}\` ${r.why}`);
           }
         }
         if (plan.keep.length) {

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