@sun-asterisk/sungen 2.7.0-beta.1 → 3.0.0-beta.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.7.0-beta.1",
+  "version": "3.0.0-beta.72",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,10 +9,11 @@
   },
   "scripts": {
     "build": "tsc && npm run copy-templates",
-    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html",
+    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd dashboard && npm install --silent && npm run build && cd .. && cp dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "tsx tests/golden/run.ts",
+    "test:update": "tsx tests/golden/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
   "keywords": [
@@ -26,7 +27,7 @@
     "automation",
     "qa"
   ],
-  "author": "ee team (engineer-excellence) — Sun Asterisk",
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -47,7 +48,7 @@
     "handlebars": "^4.7.8",
     "ora": "^9.0.0",
     "plop": "^4.0.4",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "yaml": "^2.8.2",
     "zod": "^4.1.13"
   },
@@ -67,11 +68,15 @@
   },
   "overrides": {
     "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "tmp": "^0.2.6",
+    "esbuild": "^0.28.1"
   },
   "resolutions": {
     "brace-expansion": "^5.0.6",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "tmp": "^0.2.6",
+    "esbuild": "^0.28.1"
   },
   "files": [
     "dist",

package/src/cli/commands/add.ts

@@ -66,15 +66,15 @@ export function registerAddCommand(program: Command): void {
               console.log(`  qa/screens/${options.screen}/requirements/spec.md (stub created)`);
             }
 
-            // Loud banner: Tell the calling agent to
-            // invoke the `sungen-figma-source` skill to synthesize the narrative sections in spec_figma.md, since
+            // Loud banner: Tell the calling agent to invoke the `sungen-capture` skill
+            // (mode figma-pat) to synthesize the narrative sections in spec_figma.md, since
             // the CLI cannot do this (synthesis is LLM-driven off the cached raw JSON).
             console.log('');
             console.log('==============================================================');
             console.log('  NEXT STEP (REQUIRED — DO NOT SKIP)');
             console.log('==============================================================');
             console.log('  spec_figma.md envelope is written but narrative is EMPTY.');
-            console.log('  Invoke the `sungen-figma-source` skill NOW to synthesize');
+            console.log('  Invoke `sungen-capture` (mode figma-pat) NOW to synthesize');
             console.log('  the 7 sections (Purpose / ASCII Layout / Regions / Actions /');
             console.log('  Form Fields / Data Columns / Navigation) below the');
             console.log('  `<!-- SYNTHESIS-BELOW -->` marker.');

package/src/cli/commands/audit.ts

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runAudit, AuditReport } from '../../harness/audit';
+
+function findScreenDir(name: string): string | null {
+  const screen = path.join(process.cwd(), 'qa', 'screens', name);
+  if (fs.existsSync(screen)) return screen;
+  const flow = path.join(process.cwd(), 'qa', 'flows', name);
+  if (fs.existsSync(flow)) return flow;
+  return null;
+}
+
+function bar(ratio: number, width = 20): string {
+  const n = Math.round(ratio * width);
+  return '█'.repeat(n) + '░'.repeat(width - n);
+}
+
+function render(r: AuditReport): void {
+  const L = console.log;
+  L('');
+  L(`━━━ Harness Audit: ${r.screen} (${r.scenarioCount} scenarios) ━━━`);
+  L('');
+  L(`  Quality score (business-weighted): ${r.score.overall}/10   [Viewpoint Gate: ${r.gateStatus}]`);
+  L(`  Intent: focus=${r.intent.focus} · depth threshold ${r.depth.threshold.toFixed(2)} (${r.intent.source})`);
+  L(`    coverage      ${bar(r.score.coverage)} ${(r.score.coverage * 100).toFixed(0)}%`);
+  L(`    businessDepth ${bar(r.score.businessDepth)} ${(r.score.businessDepth * 100).toFixed(0)}%  [${r.depth.verdict.toUpperCase()}]`);
+  L(`    balance       ${bar(r.score.balance)} ${(r.score.balance * 100).toFixed(0)}%`);
+  L(`    traceability  ${bar(r.score.traceability)} ${(r.score.traceability * 100).toFixed(0)}%`);
+  L(`    (${r.score.formula})`);
+  L('');
+  L(`  ① Viewpoint Gate — page-type: ${r.gate.pageType ?? 'unknown'} — themes ${r.gate.themesCovered}/${r.gate.themesTotal} covered`);
+  if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
+  else L('      ✓ all critical themes covered (with data assertions)');
+  L('');
+  L(`  ② Assertion depth — ${r.depth.businessCriticalShallow}/${r.depth.businessCriticalTotal} business-critical scenarios are shallow (visibility/nav only)`);
+  for (const s of r.depth.shallowBusinessCritical.slice(0, 8)) L(`      ⚠ ${s.category}: ${s.name}`);
+  if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);
+  L('');
+  L(`  ③ Coverage balance — ${r.balance.imbalanced ? '⚠ IMBALANCED' : '✓ balanced'}`);
+  L(`      buckets: ${Object.entries(r.balance.byBucket).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  L('');
+  L(`  ④ Duplicate — ${r.duplicates.clusters.length} same-shape cluster(s), ${r.duplicates.exactDuplicateCount} likely exact dup(s)`);
+  for (const c of r.duplicates.clusters.slice(0, 3)) {
+    L(`      ${c.sameDataLikely ? '✗ exact' : '○ EP/data family'} (${c.scenarios.length}): ${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}`);
+  }
+  L('');
+  L(`  ⑤ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
+  L(`      ${r.trace.note}`);
+  L('');
+  L('  ── Findings (Repair targets) ──');
+  if (r.findings.length === 0) L('      ✓ none — output passes the harness');
+  for (const f of r.findings) L(`      • ${f}`);
+  L('');
+}
+
+export function registerAuditCommand(program: Command): void {
+  program
+    .command('audit')
+    .description('Harness: measure test-design quality (viewpoint gate, depth, balance, duplicates, traceability)')
+    .option('-s, --screen <name>', 'Screen or flow name to audit')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const dir = findScreenDir(name);
+        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${name} or qa/flows/${name}`);
+
+        const report = runAudit(dir, name);
+
+        // Persist report under .sungen/reports/
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = path.join(outDir, `${name}-audit.json`);
+        fs.writeFileSync(outPath, JSON.stringify(report, null, 2), 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          render(report);
+          console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
+          console.log('');
+        }
+        // Non-zero exit when the gate fails — usable in CI / repair loop.
+        process.exit(report.gateStatus === 'FAIL' ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/blindspot.ts

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import { addBlindspot, listBlindspots, blindspotsForPrompt } from '../../harness/blindspot';
+
+export function registerBlindspotCommand(program: Command): void {
+  const bs = program
+    .command('blindspot')
+    .description('Blind-Spot Memory: reusable patterns so the harness stops repeating a known miss');
+
+  bs
+    .command('add')
+    .description('Record a blind-spot pattern (promote a recurring miss to a reusable rule)')
+    .requiredOption('--pattern <name>', 'Short pattern name, e.g. "add-action-no-duplicate-check"')
+    .requiredOption('--rule <text>', 'The generalised rule to apply next time')
+    .option('--example <text>', 'A concrete instance that motivated it')
+    .option('--screen <name>', 'Where it was first noticed')
+    .option('--source <who>', 'qa | challenge | feedback', 'qa')
+    .action((o) => {
+      try {
+        addBlindspot({ pattern: o.pattern, rule: o.rule, example: o.example, screen: o.screen, source: o.source });
+        console.log(`✓ blindspot recorded: [${o.pattern}]`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  bs
+    .command('list')
+    .description('List recorded blind-spot patterns')
+    .option('--prompt', 'Output the compact bullet form used in generator/critic prompts')
+    .action((o) => {
+      try {
+        if (o.prompt) { const s = blindspotsForPrompt(); console.log(s || '(none)'); return; }
+        const all = listBlindspots();
+        if (!all.length) { console.log('No blind-spots recorded yet. Add one with `sungen blindspot add`.'); return; }
+        console.log(`\n━━━ Blind-Spot Memory (${all.length}) ━━━`);
+        for (const b of all) {
+          console.log(`  • [${b.pattern}]${b.screen ? ` (${b.screen})` : ''}`);
+          console.log(`      rule: ${b.rule}`);
+          if (b.example) console.log(`      e.g.: ${b.example}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/capability.ts

@@ -0,0 +1,160 @@
+import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  readCapabilities, writeCapabilities, loadDriverCatalog, driverMeta,
+} from '../../harness/capability';
+import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
+import { adapterRegistry } from '../../generators/test-generator/adapters';
+
+function findScreenDir(name: string): string | null {
+  const s = path.join(process.cwd(), 'qa', 'screens', name);
+  if (fs.existsSync(s)) return s;
+  const f = path.join(process.cwd(), 'qa', 'flows', name);
+  if (fs.existsSync(f)) return f;
+  return null;
+}
+
+export function registerCapabilityCommand(program: Command): void {
+  const cap = program
+    .command('capability')
+    .description('Manage execution drivers (platform + capability) — opt-in, installed only on consent');
+
+  // ── list ────────────────────────────────────────────────────────────────
+  cap
+    .command('list')
+    .description('Show the project platform + enabled drivers + the available driver catalog')
+    .action(() => {
+      try {
+        const cwd = process.cwd();
+        const profile = readCapabilities(cwd);
+        const catalog = loadDriverCatalog();
+        console.log('\n━━━ Capabilities ━━━');
+        console.log(`  platform: ${profile.platform ?? '(none — run `sungen capability add web|mobile`)'}`);
+        console.log(`  enabled:  ${profile.enabled.length ? profile.enabled.join(', ') : '(none)'}  [${profile.source}]`);
+        console.log('\n  Available drivers (install with `sungen capability add <id>`):');
+        for (const d of Object.values(catalog)) {
+          const on = profile.enabled.includes(d.id) ? '●' : '○';
+          const unblocks = d.unblocks?.length ? `  unblocks ${d.unblocks.join('/')}` : '';
+          console.log(`    ${on} ${d.id.padEnd(13)} [${d.kind}] ${d.package}${unblocks}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  // ── plan (Planner — recommend-only, no install) ──────────────────────────
+  cap
+    .command('plan')
+    .description('Capability Planner: classify execution modes + @manual reasons (M1–M9) + recommend drivers (no install)')
+    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('--json', 'Output the raw plan JSON')
+    .action((o: { screen: string; json?: boolean }) => {
+      try {
+        const dir = findScreenDir(o.screen);
+        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
+        const plan = buildPlan(dir, o.screen);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = path.join(outDir, `${o.screen}-plan.json`);
+        fs.writeFileSync(outPath, JSON.stringify(plan, null, 2), 'utf-8');
+        if (o.json) { console.log(JSON.stringify(plan, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Capability Plan: ${plan.screen} (${plan.total} scenarios) ━━━`);
+        L(`  Execution modes: ${Object.entries(plan.modes).map(([m, n]) => `${m} ${n}`).join(' · ')}`);
+        const reasons = Object.entries(plan.byReason).sort().map(([c, n]) => `${c}×${n}`).join('  ') || '(no manual)';
+        L(`  Manual by reason: ${reasons}`);
+        if (plan.modes['manual']) {
+          L(`    capability-manual: ${plan.capabilityManual} (${plan.capabilityManualPct}%)   judgment-manual: ${plan.judgmentManual}   cross-screen→flow: ${plan.crossScreen}`);
+        }
+        if (plan.crossScreen) {
+          L(`  Cross-screen (XS×${plan.crossScreen}): automate via a flow — \`/sungen:add-flow\` (not a single-screen driver gap).`);
+        }
+        if (plan.recommendations.length) {
+          L('  Recommendations (recommend-only — install with `sungen capability add`):');
+          for (const r of plan.recommendations) {
+            L(`     • ${r.count} @manual:${r.reason} → enable \`${r.driver}\` (${r.pkg}) → would unblock ${r.count}`);
+          }
+        }
+        if (plan.keep.length) {
+          L(`  Keep manual (judgment floor — do NOT automate): ${plan.keep.map((k) => `${k.code}×${k.count} (${MANUAL_REASONS[k.code].label})`).join(', ')}`);
+        }
+        if (plan.unclassified.length) {
+          L(`  ⚠ Unclassified (add @manual:Mx or a clearer reason): ${plan.unclassified.length}`);
+          for (const u of plan.unclassified.slice(0, 8)) L(`     - ${u.name}`);
+        }
+        L(`\n  Report: ${path.relative(process.cwd(), outPath)}\n`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  // ── add (the consent action) ─────────────────────────────────────────────
+  cap
+    .command('add <driver>')
+    .description('Enable a driver: install its package (if external) + record it in qa/capabilities.yaml')
+    .option('--skip-install', 'Only record in the profile; do not run npm install')
+    .action((driver: string, o: { skipInstall?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        const meta = driverMeta(driver);
+        if (!meta) {
+          throw new Error(`Unknown driver "${driver}". Known: ${Object.keys(loadDriverCatalog()).join(', ')}`);
+        }
+        const adapterName = meta.adapter || meta.id;
+        const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
+
+        if (!bundled && !o.skipInstall) {
+          console.log(`📦 Installing ${meta.package} (dev dependency)...`);
+          const r = spawnSync('npm', ['install', '-D', meta.package], { stdio: 'inherit', shell: true });
+          if (r.status !== 0) throw new Error(`npm install -D ${meta.package} failed.`);
+        } else if (bundled) {
+          console.log(`✓ ${driver} is built-in (no install needed).`);
+        }
+
+        // Verify it can load (skip for bundled — already registered).
+        if (!bundled) {
+          adapterRegistry.loadDriver(adapterName, meta.package, cwd); // throws if not loadable
+        }
+
+        const profile = readCapabilities(cwd);
+        const enabled = Array.from(new Set([...profile.enabled, driver]));
+        const platform = meta.kind === 'platform' ? driver : profile.platform;
+        writeCapabilities(cwd, { platform, enabled });
+        console.log(`✓ capability "${driver}" enabled${meta.kind === 'platform' ? ` (platform=${driver})` : ''}.`);
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  // ── remove ─────────────────────────────────────────────────────────────
+  cap
+    .command('remove <driver>')
+    .description('Disable a driver in qa/capabilities.yaml (optionally uninstall the package)')
+    .option('--uninstall', 'Also run npm uninstall for the driver package')
+    .action((driver: string, o: { uninstall?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        const profile = readCapabilities(cwd);
+        const enabled = profile.enabled.filter((d) => d !== driver);
+        const platform = profile.platform === driver ? undefined : profile.platform;
+        writeCapabilities(cwd, { platform, enabled });
+        const meta = driverMeta(driver);
+        if (o.uninstall && meta && !adapterRegistry.hasAdapter(meta.adapter || meta.id)) {
+          spawnSync('npm', ['uninstall', meta.package], { stdio: 'inherit', shell: true });
+        }
+        console.log(`✓ capability "${driver}" disabled.`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/challenge.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { buildChallenge, renderChallengeMarkdown } from '../../harness/challenge';
+
+function findScreenDir(name: string): string | null {
+  const screen = path.join(process.cwd(), 'qa', 'screens', name);
+  if (fs.existsSync(screen)) return screen;
+  const flow = path.join(process.cwd(), 'qa', 'flows', name);
+  if (fs.existsSync(flow)) return flow;
+  return null;
+}
+
+export function registerChallengeCommand(program: Command): void {
+  program
+    .command('challenge')
+    .description('Exploration mode (Loop 2): attack the existing suite for blind spots — advisory, never auto-merges')
+    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('--json', 'Output the raw JSON report')
+    .action((o) => {
+      try {
+        const dir = findScreenDir(o.screen);
+        if (!dir) throw new Error(`Screen/flow not found: qa/screens/${o.screen} or qa/flows/${o.screen}`);
+        const report = buildChallenge(dir, o.screen);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const md = renderChallengeMarkdown(report);
+        const outPath = path.join(outDir, `${o.screen}-challenge.md`);
+        fs.writeFileSync(outPath, md, 'utf-8');
+
+        if (o.json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Challenge (exploration mode): ${report.screen} ━━━`);
+        L('  Advisory — does NOT change the official suite; surfaces what production missed.\n');
+        L('  ① Depth — title claims a collection but asserts a single element');
+        if (report.collectionClaimSingular.length) {
+          for (const f of report.collectionClaimSingular) L(`     ⚠ ${f.scenario}\n        → ${f.suggestion}`);
+        } else L('     ✓ none');
+        L('  ② Coverage — over-covered / shallow');
+        if (report.overCovered.length) for (const o2 of report.overCovered) L(`     • ${o2.bucket}: ${o2.note}`);
+        if (report.shallowThemes.length) L(`     • shallow themes: ${report.shallowThemes.join(', ')}`);
+        if (!report.overCovered.length && !report.shallowThemes.length) L('     ✓ balanced');
+        L('  ③ Novelty — prompts for the `sungen-challenge` agent (≤20% of official, no auto-merge)');
+        for (const p of report.noveltyPrompts) L(`     • ${p}`);
+        L('  ── Exploration readiness ──');
+        for (const e of report.explorationReadiness) L(`     • ${e}`);
+        L(`\n  Report: ${path.relative(process.cwd(), outPath)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/feedback.ts

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { recordFeedback, summarize, FeedbackType, FeedbackDecision } from '../../harness/feedback';
+
+const TYPES = ['test-design', 'product', 'other'];
+const DECISIONS = ['accept', 'reject', 'edit', 'add', 'none'];
+
+export function registerFeedbackCommand(program: Command): void {
+  const fb = program
+    .command('feedback')
+    .description('Local-first QA feedback (test-design knowledge + product telemetry). Synced later when a server exists.');
+
+  fb
+    .command('record')
+    .description('Record a feedback entry')
+    .requiredOption('--message <text>', 'The feedback')
+    .option('--type <t>', `Feedback type (${TYPES.join('|')})`, 'test-design')
+    .option('-s, --screen <name>', 'Screen/flow the feedback relates to')
+    .option('--target <ref>', 'What it is about (viewpoint id / scenario / command / artifact)')
+    .option('--decision <d>', `QA decision (${DECISIONS.join('|')})`, 'none')
+    .option('--reason <text>', 'Why')
+    .option('--source <who>', 'Who gave the feedback', 'qa')
+    .action((o) => {
+      try {
+        if (!TYPES.includes(o.type)) throw new Error(`--type must be one of ${TYPES.join(', ')}`);
+        if (!DECISIONS.includes(o.decision)) throw new Error(`--decision must be one of ${DECISIONS.join(', ')}`);
+        const p = recordFeedback({
+          type: o.type as FeedbackType,
+          screen: o.screen,
+          target: o.target,
+          decision: o.decision as FeedbackDecision,
+          message: o.message,
+          reason: o.reason,
+          source: o.source,
+        });
+        console.log(`✓ feedback recorded (${o.type}${o.screen ? ' · ' + o.screen : ''}) → ${p}`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  fb
+    .command('list')
+    .description('List / summarise recorded feedback')
+    .option('-s, --screen <name>', 'Filter by screen')
+    .option('--type <t>', 'Filter by type')
+    .option('--json', 'Output raw JSON')
+    .action((o) => {
+      try {
+        const s = summarize({ screen: o.screen, type: o.type });
+        if (o.json) { console.log(JSON.stringify(s, null, 2)); return; }
+        console.log(`\n━━━ Feedback (${s.total}) ━━━`);
+        console.log(`  by type: ${Object.entries(s.byType).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}`);
+        console.log(`  by decision: ${Object.entries(s.byDecision).map(([k, v]) => `${k}=${v}`).join('  ') || '—'}\n`);
+        for (const e of s.entries.slice(-20)) {
+          console.log(`  [${e.type}${e.decision && e.decision !== 'none' ? '/' + e.decision : ''}] ${e.screen ? e.screen + ' · ' : ''}${e.target ? e.target + ' — ' : ''}${e.message}`);
+          if (e.reason) console.log(`      reason: ${e.reason}`);
+        }
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/flow-check.ts

@@ -0,0 +1,97 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildFlowCheck } from '../../harness/flow-check';
+import { buildFlowPlan } from '../../harness/flow-plan';
+
+export function registerFlowCheckCommand(program: Command): void {
+  registerFlowPlan(program);
+  program
+    .command('flow-check')
+    .description('Flow first-class: verify screen→flow deferrals are really covered + surface the run-test contract')
+    .option('--flow <name>', 'Limit the run-test contract checks to one flow')
+    .option('--json', 'Output the raw JSON report')
+    .action((o: { flow?: string; json?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        const r = buildFlowCheck(cwd, o.flow);
+
+        const outDir = path.join(cwd, '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, 'flow-check.json'), JSON.stringify(r, null, 2), 'utf-8');
+        if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
+
+        const L = console.log;
+        L('\n━━━ Flow Check ━━━');
+        L(`  screens: ${r.screens.join(', ') || '(none)'}   flows: ${r.flows.join(', ') || '(none)'}`);
+
+        L('\n  ① Deferral integrity (screen → flow)');
+        if (!r.deferrals.length) L('     (no "deferred to a flow" @manual scenarios)');
+        for (const d of r.deferrals) {
+          const icon = d.verdict === 'covered' ? '✓' : d.verdict === 'shallow' ? '◐' : '✗';
+          const note = d.verdict === 'missing'
+            ? `NO flow covers "${d.targets.join('/')}" → false deferral (real manual gap)`
+            : `${d.verdict} by ${d.via}`;
+          L(`     ${icon} ${d.screen} · ${d.scenario.slice(0, 60)} → ${note}`);
+        }
+
+        L('\n  ② Run-test contract (cross-screen proofs)');
+        if (!r.contracts.length) L('     (no contract risks detected)');
+        for (const c of r.contracts) {
+          L(`     ⚠ ${c.kind}${c.scenario ? ` · ${c.scenario.slice(0, 55)}` : ` · ${c.flow}`}\n        ${c.message}`);
+        }
+
+        L(`\n  Report: ${path.relative(cwd, path.join(outDir, 'flow-check.json'))}`);
+        if (r.missing > 0) {
+          L(`\n  ✗ ${r.missing} false deferral(s) — these XS scenarios are NOT actually flow-covered. Add a flow or re-classify.\n`);
+          process.exit(2);
+        }
+        L('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}
+
+function registerFlowPlan(program: Command): void {
+  program
+    .command('flow-plan')
+    .description('Flow Capability Planner: decompose a flow into legs + selector readiness + contract + run-test plan')
+    .requiredOption('--flow <name>', 'Flow name')
+    .option('--json', 'Output the raw JSON plan')
+    .action((o: { flow: string; json?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        if (!fs.existsSync(path.join(cwd, 'qa', 'flows', o.flow))) throw new Error(`Flow not found: qa/flows/${o.flow}`);
+        const p = buildFlowPlan(cwd, o.flow);
+
+        const outDir = path.join(cwd, '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = path.join(outDir, `${o.flow}-flow-plan.json`);
+        fs.writeFileSync(outPath, JSON.stringify(p, null, 2), 'utf-8');
+        if (o.json) { console.log(JSON.stringify(p, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Flow Plan: ${p.flow} (${p.total} scenarios) ━━━`);
+        L('  Legs (screen → selector readiness):');
+        for (const leg of p.legs) {
+          const icon = leg.readiness === 'ready' ? '✓' : leg.readiness === 'partial' ? '◐' : '✗';
+          L(`     ${icon} ${leg.screen.padEnd(10)} ${leg.scenarios} scenarios · ${leg.refs.length} refs · selectors ${leg.readiness.toUpperCase()} (${leg.haveKeys}/${leg.refs.length})`);
+        }
+        const reasons = Object.entries(p.byReason).sort().map(([c, n]) => `${c}×${n}`).join('  ') || '(none)';
+        L(`  Manual by reason: ${reasons}   capability-manual ${p.capabilityManual}   judgment ${p.judgmentManual}`);
+        if (p.contracts.length) {
+          L('  Run-test contract:');
+          for (const c of p.contracts) L(`     ⚠ ${c.kind}${c.scenario ? ` · ${c.scenario.slice(0, 50)}` : ''}`);
+        }
+        L(`  Readiness: ${p.readiness === 'ready' ? '✓ READY' : '✗ NOT READY' + (p.missingLegs.length ? ` — missing: ${p.missingLegs.join(', ')}` : '')}`);
+        L('  Plan:');
+        p.plan.forEach((s, i) => L(`     ${i + 1}. ${s}`));
+        L(`\n  Report: ${path.relative(cwd, outPath)}\n`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}