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

package/src/cli/commands/ledger.ts

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { recordEvent, buildReport } from '../../harness/ledger';
+
+export function registerLedgerCommand(program: Command): void {
+  const ledger = program
+    .command('ledger')
+    .description('Usage ledger: record AI resource per step + report efficiency');
+
+  ledger
+    .command('record')
+    .description('Append a step event to the ledger')
+    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .requiredOption('--step <name>', 'Step name (discovery | viewpoint | gherkin | audit | repair:1 ...)')
+    .option('--run <id>', 'Run id — groups all phases of one create-test invocation (else auto-segmented by time gap)')
+    .option('--model <id>', 'Model id')
+    .option('--tokens-in <n>', 'Input tokens', (v) => parseInt(v, 10))
+    .option('--tokens-out <n>', 'Output tokens', (v) => parseInt(v, 10))
+    .option('--ms <n>', 'Duration in ms', (v) => parseInt(v, 10))
+    .option('--note <text>', 'Free note')
+    .action((o) => {
+      try {
+        recordEvent(o.screen, {
+          step: o.step, runId: o.run, model: o.model, tokensIn: o.tokensIn, tokensOut: o.tokensOut, ms: o.ms, note: o.note,
+        });
+        console.log(`✓ ledger: ${o.screen} · ${o.step}`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+
+  ledger
+    .command('report')
+    .description('Summarise ledger + efficiency verdicts (pulls audit score if present)')
+    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('--all-runs', 'Aggregate ALL runs (default: latest run only)')
+    .option('--json', 'Output raw JSON')
+    .action((o) => {
+      try {
+        const r = buildReport(o.screen, { allRuns: o.allRuns });
+        if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
+        const scope = r.runScope === 'all' ? `all ${r.runs} runs` : `latest run${r.runs > 1 ? ` of ${r.runs}` : ''}`;
+        console.log(`\n━━━ Usage Ledger: ${r.screen} (${r.events} events · ${scope}) ━━━`);
+        if (r.runScope === 'latest' && r.runs > 1) console.log(`  (${r.runs} runs on file — use --all-runs to aggregate)`);
+        console.log(`  total tokens: ${r.totalTokens}   total time: ${(r.totalMs / 1000).toFixed(1)}s   repair rounds: ${r.repairRounds}`);
+        if (r.totalTokens) console.log(`  repair token share: ${(r.repairTokenPct * 100).toFixed(0)}%`);
+        if (r.tokensPerCoveredCritical != null) console.log(`  tokens / covered-critical-viewpoint: ${r.tokensPerCoveredCritical}`);
+        if (r.tokensPerScenario != null) console.log(`  tokens / scenario: ${r.tokensPerScenario}`);
+        console.log('  by step:');
+        for (const [step, v] of Object.entries(r.byStep)) {
+          console.log(`    ${step.padEnd(14)} tokens=${v.tokens}  ms=${v.ms}  events=${v.count}`);
+        }
+        console.log('  verdict:');
+        for (const v of r.verdicts) console.log(`    • ${v}`);
+        console.log('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/manifest.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { buildManifest, diffManifest, loadManifest, saveManifest } from '../../harness/manifest';
+
+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 registerManifestCommand(program: Command): void {
+  program
+    .command('manifest')
+    .description('Spec-fingerprint manifest: build a scenario↔spec-section map, or diff to plan keep/regenerate/retire')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--diff', 'Compare current spec vs stored manifest → change plan')
+    .option('--json', 'Output raw JSON')
+    .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: ${name}`);
+
+        if (options.diff) {
+          const manifest = loadManifest(name);
+          if (!manifest) throw new Error(`No manifest for "${name}". Run \`sungen manifest --screen ${name}\` first.`);
+          const plan = diffManifest(dir, name, manifest);
+          if (options.json) { console.log(JSON.stringify(plan, null, 2)); process.exit(0); }
+          console.log(`\n━━━ Spec-change plan: ${name} ━━━`);
+          console.log(`  keep=${plan.summary.keep}  regenerate=${plan.summary.regenerate}  retire=${plan.summary.retire}  newSections=${plan.summary.newSections}\n`);
+          for (const s of plan.scenarios.filter((x) => x.change !== 'keep')) {
+            console.log(`  ${s.change === 'regenerate' ? '↻ REGENERATE' : '✗ RETIRE'}: ${s.scenario}`);
+            console.log(`      ${s.reason}`);
+          }
+          if (plan.newSections.length) console.log(`\n  ✚ NEW spec sections (no scenario yet): ${plan.newSections.join(', ')}`);
+          if (plan.summary.regenerate + plan.summary.retire + plan.summary.newSections === 0) console.log('  ✓ Spec unchanged — all scenarios still reflect the spec.');
+          console.log('');
+          return;
+        }
+
+        const manifest = buildManifest(dir, name);
+        const out = saveManifest(manifest);
+        if (options.json) { console.log(JSON.stringify(manifest, null, 2)); return; }
+        console.log(`\n✓ Manifest built: ${manifest.entries.length} scenarios across ${Object.keys(manifest.specSections).length} spec sections`);
+        console.log(`  ${path.relative(process.cwd(), out)}\n`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

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

@@ -0,0 +1,50 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runScriptCheck } from '../../harness/script-check';
+
+export function registerScriptCheckCommand(program: Command): void {
+  program
+    .command('script-check')
+    .description('Verify the generated Playwright spec is a faithful 1:1 of the Gherkin feature (no hand-edit / stale drift)')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--json', 'Output raw JSON')
+    .action(async (options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const screen = path.join(process.cwd(), 'qa', 'screens', name);
+        const flow = path.join(process.cwd(), 'qa', 'flows', name);
+        const flowMode = !fs.existsSync(screen) && fs.existsSync(flow);
+        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
+        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+
+        const r = await runScriptCheck(dir, name, flowMode);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, `${name}-script-check.json`), JSON.stringify(r, null, 2), 'utf-8');
+
+        if (options.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.status === 'OK' ? 0 : 2); }
+
+        const L = console.log;
+        L('');
+        L(`━━━ Script-check: ${name} — Gherkin ↔ Playwright 1:1 ━━━`);
+        L('');
+        L(`  status: ${r.status === 'OK' ? '✓ IN SYNC' : '✗ ' + (r.drift === 'drift' ? 'DRIFT' : 'MISMATCH')}`);
+        L(`  scenarios: ${r.automatedScenarios} automated (+${r.manualScenarios} @manual)   spec test() blocks: ${r.specTestBlocks}   count-match: ${r.countMatch ? '✓' : '✗'}`);
+        L(`  drift: ${r.drift}`);
+        if (r.driftHunks.length) { L('  differing lines (committed vs fresh regenerate):'); for (const h of r.driftHunks) L(h); }
+        L('');
+        if (r.findings.length) { L('  findings:'); for (const f of r.findings) L(`    • ${f}`); }
+        else L('  ✓ The test code faithfully reflects the Gherkin (1:1).');
+        L('');
+        if (r.drift === 'drift') L('  → Fix: re-run `sungen generate --screen ' + name + '` (or /sungen:run-test) so the spec matches the feature. Never hand-edit generated specs.');
+        L('');
+        process.exit(r.status === 'OK' ? 0 : 2);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/trace.ts

@@ -0,0 +1,60 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { buildTrace } from '../../harness/trace';
+
+export function registerTraceCommand(program: Command): void {
+  program
+    .command('trace')
+    .description('Visualise the executed test-design process (workflow/skill steps, repair loops), find bottlenecks, and show where to focus human review')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--json', 'Output raw JSON')
+    .option('--mermaid', 'Print only the Mermaid flowchart')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const screen = path.join(process.cwd(), 'qa', 'screens', name);
+        const flow = path.join(process.cwd(), 'qa', 'flows', name);
+        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
+        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+
+        const r = buildTrace(dir, name);
+        if (options.json) { console.log(JSON.stringify(r, null, 2)); return; }
+        if (options.mermaid) { console.log(r.mermaid); return; }
+
+        const L = console.log;
+        L('');
+        L(`━━━ Process Trace: ${name} ━━━`);
+        L('');
+        L(`  ① Executed process (from ledger${r.runs > 1 ? ` — latest of ${r.runs} runs` : ''})`);
+        if (r.ledger.length) {
+          for (const e of r.ledger) L(`     → ${e.step.padEnd(12)} ${e.ms}ms`);
+          L(`     repair rounds: ${r.repairRounds}   total recorded: ${(r.totalMs / 1000).toFixed(1)}s`);
+        } else {
+          L('     (ledger empty — process not instrumented this run)');
+        }
+        if (r.missingSteps.length) L(`     ⚠ phases not recorded: ${r.missingSteps.join(', ')}`);
+        L('');
+        L('  ② Quality signals');
+        if (r.audit) L(`     audit score=${r.audit.score}/10  gate=${r.audit.gate}  weakest=${r.audit.weakest}  findings=${r.audit.findings}`);
+        else L('     (no audit report — run `sungen audit`)');
+        L(`     script-check drift: ${r.drift ?? '(not run)'}`);
+        L('');
+        L('  ③ Bottlenecks / weak points');
+        for (const b of r.bottlenecks) L(`     • ${b}`);
+        L('');
+        L('  ④ HUMAN-LOOP FOCUS — where you (the QA) must look');
+        for (const h of r.humanFocus) L(`     ${h.startsWith('   ') ? h : '• ' + h}`);
+        L('');
+        L('  ⑤ Visual map (Mermaid — paste into mermaid.live or a Markdown viewer)');
+        L('  ```mermaid');
+        for (const line of r.mermaid.split('\n')) L('  ' + line);
+        L('  ```');
+        L('');
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -27,22 +27,35 @@ export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
     .description(
-      'Reinstall @sun-asterisk/sungen@latest + refresh AI rules, commands, and skills',
+      'Reinstall @sun-asterisk/sungen (stable by default, --beta for prerelease) + refresh AI rules, commands, skills',
     )
     .option('--dry-run', 'Show what would be updated without making changes')
+    .option(
+      '--beta',
+      'Switch to the BETA channel (installs @beta — prerelease builds for testing)',
+      false,
+    )
+    .option(
+      '--tag <dist-tag>',
+      'Install a specific npm dist-tag (e.g. latest, beta, next). Overrides --beta.',
+    )
     .option(
       '--skip-npm-install',
-      'Skip the `npm install -g @sun-asterisk/sungen@latest` step (refresh project AI assets only)',
+      'Skip the npm install step (refresh project AI assets only)',
       false,
     )
-    .action(async (options: { dryRun?: boolean; skipNpmInstall?: boolean }) => {
+    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean }) => {
       try {
         const skipNpm =
           Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
 
+        // Channel resolution via npm dist-tags. Default `latest` = official/stable.
+        // `--beta` → beta channel; running plain `sungen update` later switches back to stable.
+        const channel = options.tag || (options.beta ? 'beta' : 'latest');
+
         if (!skipNpm) {
-          reinstallLatestSungen();
-          printCurrentVersion();
+          reinstallSungen(channel);
+          printCurrentVersion(channel);
           reExecUpdateForAIAssets(options.dryRun ?? false);
           return;
         }
@@ -57,22 +70,29 @@ export function registerUpdateCommand(program: Command): void {
     });
 }
 
-function reinstallLatestSungen(): void {
-  console.log('📦 Installing @sun-asterisk/sungen@latest...');
-  const result = spawnSync('npm', ['install', '-g', '@sun-asterisk/sungen@latest'], {
+function reinstallSungen(channel: string): void {
+  const spec = `@sun-asterisk/sungen@${channel}`;
+  const label = channel === 'latest' ? 'stable (latest)' : `${channel} channel`;
+  console.log(`📦 Installing ${spec}  →  ${label}...`);
+  const result = spawnSync('npm', ['install', '-g', spec], {
     stdio: 'inherit',
     shell: true,
   });
   if (result.status !== 0) {
     throw new Error(
-      'npm install -g @sun-asterisk/sungen@latest failed. Run it manually or check your npm setup.',
+      `npm install -g ${spec} failed. Run it manually or check your npm setup.`,
     );
   }
 }
 
-function printCurrentVersion(): void {
+function printCurrentVersion(channel: string): void {
   console.log('\n🔎 Installed version:');
   spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
+  if (channel === 'latest') {
+    console.log('   Channel: stable. To try prereleases:  sungen update --beta');
+  } else {
+    console.log(`   Channel: ${channel} (prerelease). To return to stable:  sungen update`);
+  }
   console.log('');
 }
 

package/src/cli/index.ts

@@ -14,6 +14,14 @@ import { registerDeliveryCommand } from './commands/delivery';
 import { registerFigmaCommand } from './commands/figma';
 import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
+import { registerAuditCommand } from './commands/audit';
+import { registerManifestCommand } from './commands/manifest';
+import { registerLedgerCommand } from './commands/ledger';
+import { registerFeedbackCommand } from './commands/feedback';
+import { registerScriptCheckCommand } from './commands/script-check';
+import { registerTraceCommand } from './commands/trace';
+import { registerChallengeCommand } from './commands/challenge';
+import { registerBlindspotCommand } from './commands/blindspot';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
@@ -40,6 +48,14 @@ async function main() {
   registerFigmaCommand(program);
   registerAddFlowCommand(program);
   registerDashboardCommand(program);
+  registerAuditCommand(program);
+  registerManifestCommand(program);
+  registerLedgerCommand(program);
+  registerFeedbackCommand(program);
+  registerScriptCheckCommand(program);
+  registerTraceCommand(program);
+  registerChallengeCommand(program);
+  registerBlindspotCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/capture-variable.hbs

@@ -0,0 +1 @@
+testData.set('{{varName}}', ((await {{> locator}}.{{capture}}()) ?? '').trim());

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/all-contain-assertion.hbs

@@ -0,0 +1,7 @@
+{
+    const __items_{{stepCounter}} = await {{> locator}}.allInnerTexts();
+    expect(__items_{{stepCounter}}.length, 'Expected at least one [{{selectorRef}}]').toBeGreaterThan(0);
+    for (const __t_{{stepCounter}} of __items_{{stepCounter}}) {
+      expect(__t_{{stepCounter}}).toContain('{{expectedText}}');
+    }
+  }

package/src/generators/test-generator/patterns/capture-patterns.ts

@@ -0,0 +1,59 @@
+import { ParsedStep } from '../../gherkin-parser';
+import { StepPattern, StepTemplateData } from './types';
+
+/**
+ * Capture & collection patterns (P5) — enable cross-screen data consistency and
+ * filter-result correctness that plain single-element assertions can't express.
+ *
+ *  1. Capture:  `User remember [Product Name] text as {{selected_product_name}}`
+ *               → stores the element's text/value into a runtime variable so a
+ *               later step (on another screen) can assert against it.
+ *               REQUIRES runtime data mode (default) — emits `testData.set(...)`.
+ *
+ *  2. List:     `User see all [Product Name] contain {{selected_category}}`
+ *               → asserts EVERY matching element's text contains the value
+ *               (e.g. all products belong to the selected category/brand).
+ */
+export const capturePatterns: StepPattern[] = [
+  {
+    name: 'capture-variable',
+    matcher: (step: ParsedStep) =>
+      /\bremember\b/i.test(step.text) && /\bas\b/i.test(step.text) && !!step.selectorRef && !!step.dataRef,
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(
+        step.selectorRef!, undefined, step.elementType, step.nth,
+      );
+      const varName = step.dataRef!;
+      const isValue = /\bvalue\b/i.test(step.text);
+      // Register so later `{{varName}}` references resolve to testData.get(varName)
+      // and skip YAML validation.
+      context.dataResolver.registerCaptured(varName);
+      return {
+        templateName: 'capture-variable',
+        data: { ...resolved, varName, capture: isValue ? 'inputValue' : 'textContent' },
+        comment: `Remember ${step.selectorRef} ${isValue ? 'value' : 'text'} as ${varName}`,
+      };
+    },
+    priority: 35,
+  },
+  {
+    name: 'all-contain-assertion',
+    matcher: (step: ParsedStep) =>
+      /\b(see|sees)\b/i.test(step.text) &&
+      /\ball\b/i.test(step.text) &&
+      /(contain|contains|match|matches|belong)/i.test(step.text) &&
+      !!step.selectorRef && !!(step.value || step.dataRef),
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(
+        step.selectorRef!, undefined, step.elementType, step.nth,
+      );
+      const expectedText = step.value || context.dataResolver.resolveData(step.dataRef!, context.featureName);
+      return {
+        templateName: 'all-contain-assertion',
+        data: { ...resolved, expectedText, selectorRef: step.selectorRef, stepCounter: context.stepCounter },
+        comment: `Assert all ${step.selectorRef} contain "${step.value || step.dataRef}"`,
+      };
+    },
+    priority: 34,
+  },
+];

package/src/generators/test-generator/patterns/index.ts

@@ -10,6 +10,7 @@ import { keyboardPatterns } from './keyboard-patterns';
 import { scrollPatterns } from './scroll-patterns';
 import { scopePatterns } from './scope-patterns';
 import { tablePatterns } from './table-patterns';
+import { capturePatterns } from './capture-patterns';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -34,6 +35,7 @@ export class PatternRegistry {
     this.patterns.push(...scrollPatterns);
     this.patterns.push(...scopePatterns);
     this.patterns.push(...tablePatterns);
+    this.patterns.push(...capturePatterns);
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));

package/src/generators/test-generator/step-mapper.ts

@@ -90,6 +90,7 @@ export class StepMapper {
     this.inRowScope = false;
     this.rowScopeTable = '';
     this.lastPrimaryKeyword = 'Given';
+    this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
     this.templateEngine.resetBaseContext();
   }
 

package/src/generators/test-generator/utils/data-resolver.ts

@@ -14,6 +14,20 @@ export class DataResolver {
   private screenName?: string;
   private runtimeMode: boolean;
   private flowMode: boolean = false;
+  // Vars captured at runtime via `User remember [X] as {{var}}`. References to
+  // these skip YAML validation (they don't exist in test-data.yaml) and resolve
+  // to testData.get('var') — populated by the capture step's testData.set('var', …).
+  private capturedVars = new Set<string>();
+
+  /** Register a variable name produced by a capture step (scenario-scoped). */
+  registerCaptured(name: string): void {
+    this.capturedVars.add(name);
+  }
+
+  /** Clear captured vars — call at the start of each scenario. */
+  clearCaptured(): void {
+    this.capturedVars.clear();
+  }
 
   constructor(testDataDir?: string, screenName?: string, runtimeMode: boolean = false) {
     this.testDataDir = testDataDir || path.join(process.cwd(), 'qa', 'test-data');
@@ -36,6 +50,12 @@ export class DataResolver {
    * @returns The resolved value
    */
   resolveData(dataRef: string, featureName?: string): string {
+    // Captured vars exist only at runtime → emit a marker (→ testData.get) and
+    // skip YAML validation. Requires runtime mode (capture writes testData.set).
+    if (this.capturedVars.has(dataRef)) {
+      return DataResolver.encodeMarker(dataRef);
+    }
+
     if (this.runtimeMode) {
       this.validateDataRef(dataRef, featureName);
       return DataResolver.encodeMarker(dataRef);

package/src/harness/audit.ts

@@ -0,0 +1,112 @@
+/**
+ * Harness Audit — runs all sensors over a screen's test-design artifacts and
+ * produces a structured report + a business-weighted quality score.
+ *
+ * The score is INTENTIONALLY weighted toward business-critical coverage/depth
+ * (not breadth), so it surfaces the gaps a count-based view hides. See
+ * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
+ */
+import * as path from 'path';
+import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import {
+  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability,
+  GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult,
+} from './sensors';
+import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
+
+export interface AuditReport {
+  screen: string;
+  scenarioCount: number;
+  gate: GateResult;
+  depth: DepthResult;
+  balance: BalanceResult;
+  duplicates: DuplicateResult;
+  trace: TraceResult;
+  score: {
+    overall: number;            // 0..10, business-weighted
+    coverage: number;           // 0..1
+    businessDepth: number;      // 0..1
+    balance: number;            // 0..1
+    traceability: number;       // 0..1
+    formula: string;
+  };
+  gateStatus: 'PASS' | 'FAIL';
+  findings: string[];           // human-actionable, what the Repair loop would target
+  intent: IntentProfile;        // P3 — the intent profile that drove the thresholds
+}
+
+export function runAudit(screenDir: string, screenName: string): AuditReport {
+  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
+
+  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
+  const catalog = loadCatalog();
+
+  const gate = viewpointGate(scenarios, viewpoints, catalog);
+  // P3 — intent profile from qa/context.md drives the depth threshold (focus).
+  const intent = readIntent(projectRootFromScreenDir(screenDir));
+  const depth = assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
+  const balance = coverageBalance(scenarios);
+  const duplicates = duplicateClusters(scenarios);
+  const trace = traceability(scenarios, viewpoints);
+
+  // Sub-scores
+  const coverage = gate.coverageRatio;
+  const businessDepth = depth.bcDepthRatio;
+  const balanceScore = balance.coreCount + balance.secondaryCount > 0
+    ? Math.min(1, balance.coreCount / Math.max(1, balance.secondaryCount))
+    : 1;
+  const traceScore = 0.5 * trace.withVpCodeRatio + 0.5 * trace.mappedRatio;
+
+  // Business-weighted overall (coverage + depth dominate)
+  const overall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
+
+  const findings: string[] = [];
+  for (const g of gate.gaps) {
+    if (g.status === 'shallow') {
+      findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);
+    } else {
+      findings.push(`GATE: critical theme "${g.theme}" for page-type "${gate.pageType}" has NO covering scenario → generate it (often cross-screen → consider add-flow).`);
+    }
+  }
+  if (depth.businessCriticalShallow > 0) {
+    const tag = depth.verdict === 'fail' ? 'DEPTH-FAIL' : depth.verdict === 'warn' ? 'DEPTH-WARN' : 'DEPTH';
+    findings.push(
+      `${tag}: ${depth.businessCriticalShallow}/${depth.businessCriticalTotal} data-correctness scenarios assert only visibility ` +
+      `(ratio ${depth.bcDepthRatio.toFixed(2)} < threshold ${depth.threshold.toFixed(2)} for focus "${depth.focus}") → ` +
+      `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
+    );
+  }
+  if (balance.imbalanced) {
+    findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
+  }
+  if (trace.mappedRatio < 0.5) {
+    findings.push(`TRACE: ${trace.note}`);
+  }
+  if (gate.universalGaps.length) {
+    findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
+  }
+
+  // Gate now spans coverage (viewpoint themes) AND depth (data-correctness).
+  // A depth 'fail' (below the intent threshold) fails the gate; 'warn' does not.
+  const gateStatus: 'PASS' | 'FAIL' =
+    gate.gaps.length === 0 && depth.verdict !== 'fail' ? 'PASS' : 'FAIL';
+
+  return {
+    screen: screenName,
+    scenarioCount: scenarios.length,
+    gate, depth, balance, duplicates, trace,
+    score: {
+      overall: Math.round(overall * 10) / 10,
+      coverage: Math.round(coverage * 100) / 100,
+      businessDepth: Math.round(businessDepth * 100) / 100,
+      balance: Math.round(balanceScore * 100) / 100,
+      traceability: Math.round(traceScore * 100) / 100,
+      formula: 'overall = (0.4*coverage + 0.3*businessDepth + 0.15*balance + 0.15*traceability) * 10',
+    },
+    gateStatus,
+    findings,
+    intent,
+  };
+}

package/src/harness/blindspot.ts

@@ -0,0 +1,51 @@
+/**
+ * Blind-Spot Memory (harness-roadmap P5).
+ *
+ * A deterministic harness reliably repeats whatever its rules/viewpoints miss. When
+ * a QA (or the challenge critic) finds a recurring gap, don't just patch one test —
+ * promote it to a reusable PATTERN here. Loop 1 (generation pre-gate) and Loop 2
+ * (challenge critic) read these so the same blind spot doesn't come back.
+ *
+ * Store: .sungen/blindspots/blindspots.jsonl (append-only, project-local).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface Blindspot {
+  ts: string;
+  pattern: string;    // short name, e.g. "add-action-no-duplicate-check"
+  rule: string;       // the generalised rule to apply next time
+  example?: string;   // a concrete instance that motivated it
+  screen?: string;    // where it was first noticed
+  source?: string;    // 'qa' | 'challenge' | 'feedback'
+}
+
+function storePath(): string {
+  return path.join(process.cwd(), '.sungen', 'blindspots', 'blindspots.jsonl');
+}
+
+export function addBlindspot(entry: Omit<Blindspot, 'ts'> & { ts?: string }): string {
+  const p = storePath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const full: Blindspot = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+  fs.appendFileSync(p, JSON.stringify(full) + '\n', 'utf-8');
+  return p;
+}
+
+export function listBlindspots(): Blindspot[] {
+  const p = storePath();
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l) as Blindspot; } catch { return null; }
+  }).filter(Boolean) as Blindspot[];
+}
+
+/** Compact bullet list for injecting into generator / critic prompts. */
+export function blindspotsForPrompt(): string {
+  const all = listBlindspots();
+  if (!all.length) return '';
+  // De-dupe by pattern (latest rule wins).
+  const byPattern = new Map<string, Blindspot>();
+  for (const b of all) byPattern.set(b.pattern, b);
+  return [...byPattern.values()].map((b) => `- [${b.pattern}] ${b.rule}`).join('\n');
+}