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

package/src/harness/trace.ts

@@ -0,0 +1,138 @@
+/**
+ * Trace — visualise the whole executed test-design process and tell the end-user
+ * where to focus human-in-the-loop review.
+ *
+ * Aggregates the artifacts the harness already produces:
+ *   - .sungen/ledger/<name>.jsonl    → what ran, in what order, how many repair loops, time
+ *   - .sungen/reports/<name>-audit.json        → gate result, sub-scores, weak sensor (bottleneck)
+ *   - .sungen/reports/<name>-script-check.json  → Gherkin↔script drift
+ *   - features/<name>.feature                   → @manual scenarios (where humans MUST verify)
+ *
+ * Outputs: a text process map + a Mermaid flowchart (paste into any viewer) +
+ * bottleneck analysis + a ranked "human-loop focus" list.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
+
+interface ManualItem { scenario: string; reason: string }
+
+function readJson(p: string): any | null {
+  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null; } catch { return null; }
+}
+
+function readLedger(screen: string): any[] {
+  const p = path.join(process.cwd(), '.sungen', 'ledger', `${screen}.jsonl`);
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+/** Parse @manual scenarios + the explanatory comment line above each. */
+function parseManual(featurePath: string): ManualItem[] {
+  if (!fs.existsSync(featurePath)) return [];
+  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const out: ManualItem[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);
+    if (!m) continue;
+    // look back for tag line + a reason comment
+    let manual = false; let reason = '';
+    for (let j = i - 1; j >= 0 && j >= i - 4; j--) {
+      const l = lines[j].trim();
+      if (/^@/.test(l) && /@manual/.test(l)) manual = true;
+      else if (/^#/.test(l) && !reason) reason = l.replace(/^#+\s*/, '');
+      else if (l === '' || /^Scenario:/.test(l)) break;
+    }
+    if (manual) out.push({ scenario: m[1].trim(), reason: reason || '(no reason noted)' });
+  }
+  return out;
+}
+
+export interface TraceReport {
+  screen: string;
+  runs: number;               // total runs on file (process map shows the latest)
+  ledger: { step: string; ms: number }[];
+  repairRounds: number;
+  totalMs: number;
+  recordedSteps: string[];
+  missingSteps: string[];     // expected phases not recorded in ledger
+  audit: { score?: number; gate?: string; weakest?: string; findings?: number; gaps?: string[] } | null;
+  drift: string | null;
+  manual: ManualItem[];
+  bottlenecks: string[];
+  humanFocus: string[];
+  mermaid: string;
+}
+
+const EXPECTED_PHASES = ['discovery', 'viewpoint', 'gherkin', 'audit', 'repair'];
+
+export function buildTrace(screenDir: string, screenName: string): TraceReport {
+  const allEvents = readLedger(screenName) as LedgerEvent[];
+  const runs = segmentRuns(allEvents).length;
+  const events = latestRunEvents(allEvents);   // scope to the most recent run (P2)
+  const ledger = events.map((e) => ({ step: e.step as string, ms: (e.ms as number) || 0 }));
+  const repairRounds = new Set(events.filter((e) => /^repair/i.test(e.step)).map((e) => e.step)).size;
+  const totalMs = ledger.reduce((n, e) => n + e.ms, 0);
+  const recordedSteps = [...new Set(ledger.map((e) => e.step.replace(/:\d+$/, '')))];
+  const missingSteps = EXPECTED_PHASES.filter((p) => !recordedSteps.includes(p));
+
+  const auditRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${screenName}-audit.json`));
+  let audit: TraceReport['audit'] = null;
+  if (auditRaw) {
+    const subs: Record<string, number> = {
+      coverage: auditRaw.score?.coverage, businessDepth: auditRaw.score?.businessDepth,
+      balance: auditRaw.score?.balance, traceability: auditRaw.score?.traceability,
+    };
+    const weakest = Object.entries(subs).filter(([, v]) => typeof v === 'number').sort((a, b) => a[1] - b[1])[0]?.[0];
+    audit = {
+      score: auditRaw.score?.overall, gate: auditRaw.gateStatus, weakest,
+      findings: (auditRaw.findings || []).length,
+      gaps: (auditRaw.gate?.gaps || []).map((g: any) => `${g.theme} (${g.status})`),
+    };
+  }
+
+  const scRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${screenName}-script-check.json`));
+  const drift = scRaw ? scRaw.drift : null;
+
+  const manual = parseManual(path.join(screenDir, 'features', `${screenName}.feature`));
+
+  // Bottlenecks
+  const bottlenecks: string[] = [];
+  if (repairRounds >= 3) bottlenecks.push(`Repair loop hit ${repairRounds} rounds (near/over budget) → first-pass generation (Guide) is the bottleneck.`);
+  if (audit?.weakest) bottlenecks.push(`Lowest audit dimension: ${audit.weakest} → focus engine improvement there.`);
+  if (audit?.gaps?.length) bottlenecks.push(`Gate gaps: ${audit.gaps.join(', ')}.`);
+  if (drift === 'drift') bottlenecks.push('Spec DRIFT vs Gherkin → regenerate (never hand-edit specs).');
+  if (missingSteps.length) bottlenecks.push(`Ledger missing phases: ${missingSteps.join(', ')} → instrument \`sungen ledger record\` at each phase for full observability.`);
+  if (bottlenecks.length === 0) bottlenecks.push('No bottleneck detected from available signals.');
+
+  // Human-loop focus (where the user must look)
+  const humanFocus: string[] = [];
+  if (manual.length) humanFocus.push(`${manual.length} @manual scenario(s) need HUMAN verification (not automated):`);
+  for (const m of manual.slice(0, 12)) humanFocus.push(`   • ${m.scenario} — ${m.reason}`);
+  if (audit?.gaps?.length) humanFocus.push(`Critical gaps deferred/uncovered: ${audit.gaps.join(', ')} — decide flow vs accept.`);
+  if (humanFocus.length === 0) humanFocus.push('No manual/uncovered items — automation covers the critical viewpoints.');
+
+  // Mermaid flowchart of the executed process
+  const phaseSeq = ledger.length
+    ? ledger.map((e) => e.step)
+    : ['(no ledger — process not instrumented)'];
+  const nodes = phaseSeq.map((s, i) => `  S${i}["${s}${ledger[i] ? ` (${ledger[i].ms}ms)` : ''}"]`).join('\n');
+  const edges = phaseSeq.map((_, i) => (i < phaseSeq.length - 1 ? `  S${i} --> S${i + 1}` : '')).filter(Boolean).join('\n');
+  const mermaid = [
+    'flowchart TD',
+    '  IN["spec / figma / ui / live"] --> DISC[discovery]',
+    '  DISC --> VP[viewpoint overview]',
+    '  VP --> GEN[generate Gherkin]',
+    '  GEN --> AUD{sungen audit gate}',
+    repairRounds ? `  AUD -- FAIL --> REP["repair ×${repairRounds}"]` : '',
+    repairRounds ? '  REP --> AUD' : '',
+    `  AUD -- ${audit?.gate === 'PASS' ? 'PASS' : 'still failing'} --> DONE[converge]`,
+    '  DONE --> SC{script-check 1:1}',
+    `  SC -- ${drift === 'drift' ? 'DRIFT → regenerate' : 'in-sync'} --> OUT[generate → run-test → delivery]`,
+  ].filter(Boolean).join('\n');
+
+  return {
+    screen: screenName, runs, ledger, repairRounds, totalMs, recordedSteps, missingSteps,
+    audit, drift, manual, bottlenecks, humanFocus, mermaid,
+  };
+}

package/src/orchestrator/ai-rules-updater.ts

@@ -18,21 +18,25 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
   ['claude-cmd-add-flow.md', '.claude/commands/sungen/add-flow.md'],
   ['claude-cmd-create-test.md', '.claude/commands/sungen/create-test.md'],
+  ['claude-cmd-design.md', '.claude/commands/sungen/design.md'],
   ['claude-cmd-run-test.md', '.claude/commands/sungen/run-test.md'],
   ['claude-cmd-review.md', '.claude/commands/sungen/review.md'],
   ['claude-cmd-delivery.md', '.claude/commands/sungen/delivery.md'],
   ['claude-cmd-dashboard.md', '.claude/commands/sungen/dashboard.md'],
   ['claude-cmd-locale.md', '.claude/commands/sungen/locale.md'],
+  ['claude-cmd-feedback.md', '.claude/commands/sungen/feedback.md'],
 
   // Commands — GitHub Copilot
   ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
   ['copilot-cmd-add-flow.md', '.github/prompts/sungen-add-flow.prompt.md'],
   ['copilot-cmd-create-test.md', '.github/prompts/sungen-create-test.prompt.md'],
+  ['copilot-cmd-design.md', '.github/prompts/sungen-design.prompt.md'],
   ['copilot-cmd-run-test.md', '.github/prompts/sungen-run-test.prompt.md'],
   ['copilot-cmd-review.md', '.github/prompts/sungen-review.prompt.md'],
   ['copilot-cmd-delivery.md', '.github/prompts/sungen-delivery.prompt.md'],
   ['copilot-cmd-dashboard.md', '.github/prompts/sungen-dashboard.prompt.md'],
   ['copilot-cmd-locale.md', '.github/prompts/sungen-locale.prompt.md'],
+  ['copilot-cmd-feedback.md', '.github/prompts/sungen-feedback.prompt.md'],
 
   // Skills — Claude Code
   ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -42,6 +46,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-test-design-techniques.md', '.claude/skills/sungen-test-design-techniques/SKILL.md'],
   ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
+  ['claude-skill-harness-audit.md', '.claude/skills/sungen-harness-audit/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
   ['claude-skill-viewpoint-group-a-data-entry.md', '.claude/skills/sungen-viewpoint/group-a-data-entry.md'],
   ['claude-skill-viewpoint-group-b-data-ops.md', '.claude/skills/sungen-viewpoint/group-b-data-ops.md'],
@@ -50,14 +55,19 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-viewpoint-group-e-identity.md', '.claude/skills/sungen-viewpoint/group-e-identity.md'],
   ['claude-skill-delivery.md', '.claude/skills/sungen-delivery/SKILL.md'],
   ['claude-skill-dashboard.md', '.claude/skills/sungen-dashboard/SKILL.md'],
-  ['claude-skill-capture-figma.md', '.claude/skills/sungen-capture-figma/SKILL.md'],
-  ['claude-skill-capture-local.md', '.claude/skills/sungen-capture-local/SKILL.md'],
-  ['claude-skill-capture-live.md', '.claude/skills/sungen-capture-live/SKILL.md'],
-  ['claude-skill-figma-source.md', '.claude/skills/sungen-figma-source/SKILL.md'],
+  // sungen-capture — router skill (1 SKILL.md + 4 mode files). Replaces the former
+  // capture-figma / capture-live / capture-local / figma-source standalone skills.
+  ['claude-skill-capture.md', '.claude/skills/sungen-capture/SKILL.md'],
+  ['claude-skill-capture-mode-figma-mcp.md', '.claude/skills/sungen-capture/mode-figma-mcp.md'],
+  ['claude-skill-capture-mode-figma-pat.md', '.claude/skills/sungen-capture/mode-figma-pat.md'],
+  ['claude-skill-capture-mode-live.md', '.claude/skills/sungen-capture/mode-live.md'],
+  ['claude-skill-capture-mode-local.md', '.claude/skills/sungen-capture/mode-local.md'],
   ['claude-skill-locale.md', '.claude/skills/sungen-locale/SKILL.md'],
 
-  // Skills — Copilot (prompt-based)
-  ['copilot-skill-figma-source.md', '.github/prompts/sungen-figma-source.prompt.md'],
+  // Agents — Claude Code sub-agents (isolated context). Copilot runs these inline.
+  ['claude-agent-reviewer.md', '.claude/agents/sungen-reviewer.md'],
+  ['claude-agent-discovery.md', '.claude/agents/sungen-discovery.md'],
+  ['claude-agent-challenge.md', '.claude/agents/sungen-challenge.md'],
 
   // Skills — GitHub Copilot
   ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -67,6 +77,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-test-design-techniques.md', '.github/skills/sungen-test-design-techniques/SKILL.md'],
   ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
+  ['github-skill-sungen-harness-audit.md', '.github/skills/sungen-harness-audit/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
   ['github-skill-sungen-viewpoint-group-a-data-entry.md', '.github/skills/sungen-viewpoint/group-a-data-entry.md'],
   ['github-skill-sungen-viewpoint-group-b-data-ops.md', '.github/skills/sungen-viewpoint/group-b-data-ops.md'],
@@ -75,13 +86,29 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-viewpoint-group-e-identity.md', '.github/skills/sungen-viewpoint/group-e-identity.md'],
   ['github-skill-sungen-delivery.md', '.github/skills/sungen-delivery/SKILL.md'],
   ['github-skill-sungen-dashboard.md', '.github/skills/sungen-dashboard/SKILL.md'],
-  ['github-skill-sungen-capture-figma.md', '.github/skills/sungen-capture-figma/SKILL.md'],
-  ['github-skill-sungen-capture-local.md', '.github/skills/sungen-capture-local/SKILL.md'],
-  ['github-skill-sungen-capture-live.md', '.github/skills/sungen-capture-live/SKILL.md'],
-  ['github-skill-sungen-figma-source.md', '.github/skills/sungen-figma-source/SKILL.md'],
+  ['github-skill-sungen-capture.md', '.github/skills/sungen-capture/SKILL.md'],
+  ['github-skill-sungen-capture-mode-figma-mcp.md', '.github/skills/sungen-capture/mode-figma-mcp.md'],
+  ['github-skill-sungen-capture-mode-figma-pat.md', '.github/skills/sungen-capture/mode-figma-pat.md'],
+  ['github-skill-sungen-capture-mode-live.md', '.github/skills/sungen-capture/mode-live.md'],
+  ['github-skill-sungen-capture-mode-local.md', '.github/skills/sungen-capture/mode-local.md'],
   ['github-skill-sungen-locale.md', '.github/skills/sungen-locale/SKILL.md'],
 ];
 
+// Skill/asset directories retired in a previous refactor. `sungen update` removes
+// these so already-initialized projects don't keep loading stale skill descriptions.
+// (v3.0: the four capture/figma skills were merged into the `sungen-capture` router.)
+export const STALE_AI_RULES_PATHS: string[] = [
+  '.claude/skills/sungen-capture-figma',
+  '.claude/skills/sungen-capture-live',
+  '.claude/skills/sungen-capture-local',
+  '.claude/skills/sungen-figma-source',
+  '.github/skills/sungen-capture-figma',
+  '.github/skills/sungen-capture-live',
+  '.github/skills/sungen-capture-local',
+  '.github/skills/sungen-figma-source',
+  '.github/prompts/sungen-figma-source.prompt.md',
+];
+
 export class AIRulesUpdater {
   private cwd: string;
   private aiTemplateDir: string;
@@ -133,11 +160,31 @@ export class AIRulesUpdater {
       }
     }
 
+    // Remove retired skills/assets so stale descriptions stop loading.
+    const removed: string[] = [];
+    for (const staleRelPath of STALE_AI_RULES_PATHS) {
+      const stalePath = path.join(this.cwd, staleRelPath);
+      if (fs.existsSync(stalePath)) {
+        if (!dryRun) {
+          fs.rmSync(stalePath, { recursive: true, force: true });
+        }
+        removed.push(staleRelPath);
+      }
+    }
+
     // Print results
     if (dryRun) {
       console.log('📋 Dry run — no files changed\n');
     }
 
+    if (removed.length > 0) {
+      console.log(`🗑️  Removed retired assets (${removed.length}):`);
+      for (const f of removed) {
+        console.log(`   ${f}`);
+      }
+      console.log();
+    }
+
     if (updated.length > 0) {
       console.log(`✏️  Updated (${updated.length}):`);
       for (const f of updated) {

package/src/orchestrator/figma/spec-figma-renderer.ts

@@ -5,7 +5,7 @@
  * auto-gen banner, Frame metadata, Screenshots, and a SYNTHESIS marker.
  * Narrative sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
  * Data Columns, Navigation) are appended BELOW the marker by the
- * sungen-figma-source skill, which reads the raw cached node JSON.
+ * sungen-capture skill (mode figma-pat), which reads the raw cached node JSON.
  *
  * Section renderers live in spec-figma-section-renderers.ts.
  *
@@ -55,7 +55,7 @@ export interface RenderSpecFigmaInput {
 
 /**
  * Render the deterministic envelope for spec_figma.md.
- * The LLM synthesis step (sungen-figma-source skill) appends the narrative
+ * The LLM synthesis step (sungen-capture skill (mode figma-pat)) appends the narrative
  * sections AFTER the SYNTHESIS_MARKER comment. Re-synthesis replaces
  * everything from the marker to EOF.
  *

package/src/orchestrator/figma/spec-figma-section-renderers.ts

@@ -5,7 +5,7 @@
  * needs: frontmatter, Frame metadata, Screenshots, and the SYNTHESIS marker.
  * All prose sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
  * Data Columns, Navigation) are appended below the marker by the
- * sungen-figma-source skill.
+ * sungen-capture skill (mode figma-pat).
  *
  * Pure — no I/O.
  */

package/src/orchestrator/project-initializer.ts

@@ -42,6 +42,9 @@ export class ProjectInitializer {
     // Create qa/context.md for QA lead to fill project-wide context
     this.createContext();
 
+    // Create qa/capabilities.yaml — the platform driver profile (default: web/Playwright)
+    this.createCapabilities();
+
     // Ensure package.json and install Playwright
     await this.setupDependencies();
 
@@ -150,10 +153,12 @@ export class ProjectInitializer {
     const gitignorePath = path.join(this.cwd, '.gitignore');
     const sungenEntries = [
       '# Sungen generated files',
-      'specs/.auth/',
+      'specs/.auth/',          // session storage state = cookies/tokens (sensitive)
       'test-results/',
       'playwright-report/',
-      '.playwright-mcp/'
+      '.playwright-mcp/',
+      '.sungen/figma-cache/',  // raw Figma node JSON (design IP)
+      '.sungen/feedback/',     // local QA feedback (may contain product-sensitive notes)
     ];
 
     if (!fs.existsSync(gitignorePath)) {
@@ -162,12 +167,13 @@ export class ProjectInitializer {
       fs.writeFileSync(gitignorePath, content, 'utf-8');
       this.createdItems.push('.gitignore');
     } else {
-      // Append Sungen entries if not already present
+      // Append any Sungen entries that are missing (idempotent — covers projects
+      // created before new sensitive paths were added).
       let content = fs.readFileSync(gitignorePath, 'utf-8');
-      const needsUpdate = !content.includes('specs/.auth/');
-      
-      if (needsUpdate) {
-        content += '\n' + sungenEntries.join('\n') + '\n';
+      const missing = sungenEntries.filter((e) => e.startsWith('#') ? false : !content.includes(e));
+      if (missing.length) {
+        const block = content.includes('# Sungen generated files') ? missing : ['# Sungen generated files', ...missing];
+        content += '\n' + block.join('\n') + '\n';
         fs.writeFileSync(gitignorePath, content, 'utf-8');
         this.createdItems.push('.gitignore (updated)');
       } else {
@@ -383,6 +389,26 @@ export class ProjectInitializer {
     this.createdItems.push('qa/context.md');
   }
 
+  /**
+   * Create qa/capabilities.yaml — the platform driver profile (Phase 2a).
+   * Defaults to `web` (Playwright). Mobile/API projects switch via `sungen capability add`.
+   */
+  private createCapabilities(): void {
+    const p = path.join(this.cwd, 'qa', 'capabilities.yaml');
+    if (fs.existsSync(p)) {
+      this.skippedItems.push('qa/capabilities.yaml');
+      return;
+    }
+    const content =
+      '# Sungen capability profile — which runtime/drivers this project uses.\n' +
+      '# platform: the runtime adapter — web → Playwright, mobile → Appium.\n' +
+      '# enabled: drivers turned on (add more via `sungen capability add <driver>`).\n\n' +
+      'platform: web\n' +
+      'enabled:\n  - web\n';
+    fs.writeFileSync(p, content, 'utf-8');
+    this.createdItems.push('qa/capabilities.yaml');
+  }
+
   /**
    * Create specs/base.ts for shared browser context
    */

package/src/orchestrator/templates/ai-instructions/claude-agent-challenge.md

@@ -0,0 +1,46 @@
+---
+name: sungen-challenge
+description: Exploration/Challenge critic (Loop 2). Does NOT regenerate the suite — it ATTACKS the existing one to surface blind spots and propose a few high-value novelty candidates. Advisory only; never edits files, never auto-merges. Run after create-test converges, or on demand via `sungen challenge`.
+tools: Read, Grep, Glob, Bash
+---
+
+You are an **exploration critic** — the antidote to "the harness always outputs the same thing". Production mode (create-test → audit gate → repair) is deterministic by design; your job is to find what that determinism reliably **misses**. You do **not** rewrite the suite — you challenge it and hand back candidates for the QA to accept or reject.
+
+## First, run the deterministic spine
+Run `sungen challenge --screen <name>` (Bash) and read its report (`.sungen/reports/<name>-challenge.md`). It already gives you: title↔assertion collection gaps, over-covered/shallow areas, and novelty prompts. Build on it — don't repeat it.
+
+## Inputs (read)
+- `qa/<screens|flows>/<name>/features/<name>.feature` — the suite under attack.
+- `requirements/spec.md` + `test-viewpoint.md` — source of truth + intended viewpoints.
+- `.sungen/reports/<name>-audit.json` — what the gate already measured.
+- Blind-spot patterns — run `sungen blindspot list --prompt` (Bash) and check the suite against each known pattern.
+
+## Three critics
+
+1. **Coverage critic** — viewpoints that are missing or covered only shallowly; areas over-covered with low value (e.g. many subscription edge cases while cart correctness is thin). Recommend rebalancing, not just adding.
+2. **Business-Depth critic** — scenarios whose **title claims more than the steps prove** (a set/collection asserted by one element; "correct X" asserted by mere visibility). For each, give the exact deep step to add. Confirm or dismiss the deterministic flags from `sungen challenge`.
+3. **Novelty critic** — 3–5 **non-obvious, valuable** scenarios outside the existing pattern, via risk lenses (double-submit, partial-load, boundary/unusual data, concurrency/back-button, historical incidents). Each must map to a risk or viewpoint and explain why it isn't a duplicate.
+
+## Guardrails (hard)
+- **Read-only.** Never edit the feature or any file. You return findings; the QA/orchestrator decides.
+- **No auto-merge.** Novelty candidates are proposals, capped at **≤ 20%** of the official scenario count.
+- Each candidate is classified **Required / Recommended / Optional** and must not reduce traceability of the official suite.
+
+## Output (Challenge Report — Markdown, to the caller)
+```
+# Challenge Report — <name>
+## Summary
+- Official score: <from audit>  · depth gaps confirmed: <n>  · novelty candidates: <n>
+## Weak / missing viewpoints
+| Viewpoint | Issue | Severity | Recommendation |
+## Shallow assertions (title > steps)
+| Scenario | Claim in title | Current assertion | Suggested deep step |
+## Over-covered (low value)
+| Area | Why | Suggested action |
+## Novelty candidates (≤20%, no auto-merge)
+| Candidate | Related risk/viewpoint | Why valuable | Why not a duplicate | Required/Recommended/Optional |
+## Blind-spot patterns worth storing
+| Pattern | General rule | Example from this screen |
+```
+
+Keep it tight and actionable. End by reminding the QA: these are **advisory** — adopt selectively; promoting a recurring miss to `.sungen/blindspots/` (via `sungen blindspot add`) stops it recurring.

package/src/orchestrator/templates/ai-instructions/claude-agent-discovery.md

@@ -0,0 +1,32 @@
+---
+name: sungen-discovery
+description: Context explorer for test design. Reads ALL provided sources (spec.md, spec_figma.md, ui/* images, optional live page) in an isolated context and returns a COMPACT discovery report — sources, completeness, conflicts, recommended route, key facts — so the orchestrator's context stays lean for generation. Read-only. Invoked by create-test/design at the discovery step.
+tools: Read, Grep, Glob, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot
+---
+
+You are a **test-design context explorer**. You run in an **isolated context** so the orchestrator that generates test cases stays uncluttered. Read everything relevant, then return a **compact, structured report** — not raw dumps.
+
+## Explore (do NOT ask the user to pick a source — read all that exist)
+- `requirements/spec.md` — primary behavior source.
+- `requirements/spec_figma.md` — Figma supplement (if present; do NOT call Figma MCP when this exists).
+- `requirements/ui/*` images — layout/visual context.
+- Live page — only if a base URL is configured and reachable: `browser_navigate` + `browser_snapshot` for real element roles/names. Fall back gracefully if it requires login / fails.
+
+## Cross-check
+Flag any **conflicts** between sources (field names, labels, behavior, states that disagree). `spec.md` is authoritative; design/figma/live supplement.
+
+## Output (compact — this is your only deliverable)
+```
+SOURCES: spec=<yes/no, completeness high|med|low> | figma=<...> | ui=<n images> | live=<reached|offline>
+PAGE TYPE: <e.g. ecommerce-list / form / auth / ...>
+RECOMMENDED ROUTE: <spec-first | source-first | ...> — authoritative source: <which>
+CONFLICTS: <list, or "none">
+KEY FACTS (condensed):
+  - Sections: <list>
+  - Fields/validation: <key constraints + exact error messages>
+  - Business rules: <bullets>
+  - States: <lifecycle / empty / error / success>
+ASSUMPTIONS / MISSING INFO: <what's unknown — to be marked in output>
+```
+
+Keep it tight. Do not generate test cases — that is the orchestrator's job. Do not write files.

package/src/orchestrator/templates/ai-instructions/claude-agent-reviewer.md

@@ -0,0 +1,37 @@
+---
+name: sungen-reviewer
+description: Independent QA reviewer for generated Gherkin. Judges SEMANTIC quality the deterministic `sungen audit` cannot — does each scenario's steps PROVE its title/viewpoint, are Thens observable, are business-critical assertions deep. Returns a verdict; does NOT edit files. Invoked by create-test/design during the gate+repair step.
+tools: Read, Grep, Glob, Bash
+---
+
+You are an **independent Senior QA Reviewer**. You did **not** write these tests — your job is to find where they are weak, not to defend them. You complement the deterministic gate (`sungen audit`), which already checks structural coverage; you judge the **semantics** it cannot.
+
+## Inputs (read them)
+- `qa/<screens|flows>/<name>/features/<name>.feature` — the scenarios under review.
+- `qa/<screens|flows>/<name>/requirements/test-viewpoint.md` — the viewpoint overview (priority).
+- `qa/<screens|flows>/<name>/requirements/spec.md` — source of truth for behavior.
+- `.sungen/reports/<name>-audit.json` — the deterministic findings (don't repeat them; go deeper).
+
+## What to judge (semantic — the gate misses these)
+1. **Title ↔ steps proof.** For every scenario, do the **steps actually prove the title/viewpoint**? Flag "title claims X but steps only assert Y". (e.g. title "adds the selected product, not a random one" but Then only `see [Added] modal`.)
+2. **Observable Then.** Is each `Then` an **observable outcome**, not a restated action or a tautology (e.g. `Then User see [Carousel] section` after clicking next — proves nothing changed)?
+3. **Business-critical depth.** For cart / product-detail / filter / list viewpoints, do steps assert **DATA** (name, price, quantity, all-items-belong) — not just page/modal visibility? Recommend the concrete deep step: `User remember [X] text as {{v}}` + `... with {{v}}`, or `User see all [X] contain {{v}}`.
+4. **@manual justification.** Is each `@manual` genuinely unautomatable (cross-screen/external/visual) — or a cop-out to dodge the gate? Cross-screen → should be a flow.
+5. **Meaning-level duplicates & missing criticals** the keyword gate can't see.
+
+## Output (do NOT edit any file)
+Return a concise verdict:
+
+```
+VERDICT: PASS | NEEDS-REPAIR
+SCORE: <0-10> (semantic quality; be strict on business value)
+
+ISSUES (most important first):
+1. [<scenario id>] <problem in one line>
+   FIX: <the exact Gherkin step(s) to add/change>
+2. ...
+
+STRENGTHS: <1-2 lines, what is genuinely good>
+```
+
+Be specific and actionable — every issue must have a concrete FIX the generator can apply. Limit to the ~8 highest-impact issues. Do not rewrite the feature file; the orchestrator applies repairs.

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-flow.md

@@ -48,9 +48,9 @@ Record the screen list — you will need it for:
 ### 2. Capture visual source
 
 Use `AskUserQuestion`: *"Pick a visual source for this flow's screens:"*
-- **Figma designs** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill for each screen
-- **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill for each screen URL
-- **Local images** — invoke `sungen-capture-local` skill to load from `requirements/ui/`
+- **Figma designs** (Recommended for pre-launch) — invoke `sungen-capture` skill (mode figma-mcp) for each screen
+- **Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live) for each screen URL
+- **Local images** — invoke `sungen-capture` skill (mode local) to load from `requirements/ui/`
 - **Skip** — user will drop images manually into `requirements/ui/` later
 
 Each capture skill writes outputs into `qa/flows/<name>/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill so behavior stays consistent with `/sungen:create-test`.

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -45,7 +45,7 @@ sungen add --screen <screen> --feature <name> [--path <path>]
 
 **Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
 
-Invoke the `sungen-figma-source` skill by running:
+Invoke the `sungen-capture` skill (mode figma-pat) by running:
 ```bash
 sungen add --screen <screen> --figma '<url>' [--path <path>] [--feature <name>] [--refresh] [--scale <n>]
 # Single-quote the URL — Figma links contain `&` which bash otherwise treats as a background operator.
@@ -71,7 +71,7 @@ In that case, guide the user to run `sungen figma auth set` and retry.
 
 ### 1a. Synthesize narrative sections (Figma branch only)
 
-After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is deterministic but the narrative below the `<!-- SYNTHESIS-BELOW -->` marker is empty. Invoke the `sungen-figma-source` skill to fill it:
+After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is deterministic but the narrative below the `<!-- SYNTHESIS-BELOW -->` marker is empty. Invoke the `sungen-capture` skill (mode figma-pat) to fill it:
 
 1. Read `qa/screens/<screen>/requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter.
 2. Read the cached raw node JSON at `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores).
@@ -88,11 +88,11 @@ After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is determin
 
 **If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Use `AskUserQuestion` to offer:
 - **Continue** — Figma visuals are enough (Recommended)
-- **Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture-live` skill)
+- **Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture` skill (mode live))
 
 **If standard path (no `--figma`)** → go straight to source selection. Use `AskUserQuestion`: *"Pick a visual source for this screen:"*
-- **Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
-- **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+- **Figma design** (Recommended for pre-launch) — invoke `sungen-capture` skill (mode figma-mcp)
+- **Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live)
 - **Skip** — user will drop images manually into `requirements/ui/` later
 
 Each capture skill writes outputs into `qa/screens/<screen>/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill so behavior stays consistent with `/sungen:create-test`.