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

package/src/harness/sensors.ts

@@ -0,0 +1,279 @@
+/**
+ * Harness Sensors — deterministic quality measurement over test-design artifacts.
+ * Each sensor returns a structured finding the Orchestrator/Repair loop can act on.
+ *
+ * NOTE (honesty): the Viewpoint Gate and Duplicate sensors involve semantics, so
+ * they are HEURISTIC (keyword / skeleton based), not provably exhaustive. They use
+ * a curated seed catalog as the matching reference. See docs/orchestration-spec.md §5.2.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { ScenarioInfo, ViewpointEntry } from './parse';
+
+// Business-critical category codes (project VP-<CAT> prefixes). Configurable later.
+const BUSINESS_CRITICAL_CATS = ['LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER'];
+
+// Buckets for coverage-balance.
+const BUCKETS: Record<string, string[]> = {
+  'business-core': BUSINESS_CRITICAL_CATS,
+  'presentation': ['UI'],
+  'validation-security': ['VAL', 'SEC', 'SUB'],
+  'behavior': ['LOGIC'],
+  'navigation': ['NAV'],
+};
+
+export interface ThemeDepth {
+  requires: string;           // 'data-assertion' → scenarios on this theme must assert DATA
+  cross_screen?: boolean;     // genuine depth needs another screen → flow / @manual-deferred
+  keywords?: string[];        // precise data-noun keywords for depth matching
+  template?: string;          // the deep step the generator should emit by default
+}
+export interface CatalogTheme { theme: string; keywords: string[]; depth?: ThemeDepth }
+export interface Catalog {
+  page_types: Record<string, { detect_keywords: string[]; must_cover: CatalogTheme[] }>;
+  universal: CatalogTheme[];
+}
+
+export function loadCatalog(): Catalog {
+  const p = path.join(__dirname, 'catalog', 'universal-viewpoints.yaml');
+  return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
+}
+
+const has = (haystacks: string[], kw: string) => {
+  const k = kw.toLowerCase();
+  return haystacks.some((h) => h.includes(k));
+};
+
+// ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
+
+export interface GateResult {
+  pageType: string | null;
+  themesTotal: number;
+  themesCovered: number;       // deeply covered (has a data assertion)
+  coverageRatio: number;
+  gaps: { theme: string; keywords: string[]; status: 'missing' | 'shallow' }[];
+  universalGaps: string[];
+}
+
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog): GateResult {
+  const haystacks = [
+    ...scenarios.map((s) => s.haystack),
+    ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
+  ];
+
+  // Detect page-type by detect_keywords hit count
+  let pageType: string | null = null;
+  let best = 0;
+  for (const [pt, def] of Object.entries(catalog.page_types)) {
+    const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
+    if (hits > best) { best = hits; pageType = pt; }
+  }
+
+  const gaps: GateResult['gaps'] = [];
+  let total = 0, covered = 0;
+  if (pageType) {
+    for (const t of catalog.page_types[pageType].must_cover) {
+      total++;
+      // Scenarios that cover this theme by keyword (include @manual — a manual
+      // scenario with a real assertion still covers the viewpoint for design).
+      const coverers = scenarios.filter((s) => t.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
+      const deep = coverers.some((s) => s.hasDataAssertion);
+      if (deep) covered++;
+      else if (coverers.length > 0) gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
+      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' });
+    }
+  }
+
+  const universalGaps = catalog.universal
+    .filter((t) => !t.keywords.some((k) => has(scenarios.map((s) => s.haystack), k)))
+    .map((t) => t.theme);
+
+  return {
+    pageType,
+    themesTotal: total,
+    themesCovered: covered,
+    coverageRatio: total ? covered / total : 1,
+    gaps,
+    universalGaps,
+  };
+}
+
+// ---------- Sensor 2: Assertion depth ----------
+
+export type DepthVerdict = 'pass' | 'warn' | 'fail';
+
+export interface DepthResult {
+  total: number;
+  shallowTotal: number;
+  shallowRatio: number;
+  businessCriticalTotal: number;     // = depth-required scenarios (catalog data-themes)
+  businessCriticalShallow: number;   // = depth-required scenarios that are shallow
+  bcDepthRatio: number;              // fraction of depth-required scenarios with a real data assertion
+  shallowBusinessCritical: { name: string; category?: string }[];
+  // Depth-as-Gate (harness-roadmap P1)
+  focus: string;                     // intent focus driving the threshold
+  threshold: number;                 // required bcDepthRatio for this focus
+  verdict: DepthVerdict;             // pass | warn | fail
+}
+
+// Intent → required depth ratio + whether a miss WARNs (smoke) or FAILs the gate.
+// P3 will read `focus` from qa/context.md; P1 uses 'functional' by default.
+const DEPTH_THRESHOLDS: Record<string, number> = {
+  functional: 0.7, 'e-commerce': 0.7, security: 0.8, smoke: 0.4,
+};
+const WARN_ONLY_FOCUS = new Set(['smoke']);
+
+/**
+ * Depth = do DATA-correctness scenarios actually assert DATA (not just visibility)?
+ * "Depth-required" is CATALOG-DRIVEN: only scenarios matching a theme whose
+ * `depth.requires === 'data-assertion'` are measured. Navigation viewpoints
+ * (category NAV) are excluded — landing on a page IS their correct assertion.
+ * This avoids the old keyword-based false-positives (e.g. "API list page").
+ */
+export function assertionDepth(
+  scenarios: ScenarioInfo[],
+  dataThemes: CatalogTheme[] = [],
+  focus = 'functional',
+): DepthResult {
+  const nonManual = scenarios.filter((s) => !s.manual);
+  const shallow = nonManual.filter((s) => s.shallow);
+
+  // Precise depth keywords come from each data-theme's depth.keywords (fallback: theme keywords).
+  const depthKeywords = dataThemes.flatMap((t) => (t.depth?.keywords?.length ? t.depth.keywords : t.keywords));
+  // Dismiss/close behaviors ("Continue Shopping closes the modal", "Escape dismisses the
+  // dialog") assert a HIDDEN state — that IS the correct, data-light assertion for the
+  // behavior. They only match a data keyword incidentally (e.g. "added"), so exclude them.
+  const isDismissBehavior = (s: ScenarioInfo) =>
+    /\bis hidden\b|\bare hidden\b|\bdismiss|\bdisappear|\bno longer (visible|shown|present|displayed)\b|\bcloses? the (modal|dialog|popup|overlay|panel|menu)\b/.test(s.haystack);
+  const isDepthRequired = (s: ScenarioInfo) =>
+    s.category !== 'NAV' && !isDismissBehavior(s) && depthKeywords.some((k) => s.haystack.includes(k.toLowerCase()));
+
+  const required = nonManual.filter(isDepthRequired);
+  const reqShallow = required.filter((s) => s.shallow);
+  // No data-theme scenarios on this screen → depth is not the binding constraint
+  // (the viewpoint gate already flags missing data themes). Don't double-penalize.
+  const ratio = required.length ? 1 - reqShallow.length / required.length : 1;
+
+  const threshold = DEPTH_THRESHOLDS[focus] ?? DEPTH_THRESHOLDS.functional;
+  let verdict: DepthVerdict = 'pass';
+  if (ratio < threshold) verdict = WARN_ONLY_FOCUS.has(focus) ? 'warn' : 'fail';
+
+  return {
+    total: nonManual.length,
+    shallowTotal: shallow.length,
+    shallowRatio: nonManual.length ? shallow.length / nonManual.length : 0,
+    businessCriticalTotal: required.length,
+    businessCriticalShallow: reqShallow.length,
+    bcDepthRatio: ratio,
+    shallowBusinessCritical: reqShallow.map((s) => ({ name: s.name, category: s.category })),
+    focus,
+    threshold,
+    verdict,
+  };
+}
+
+/** Collect data-correctness themes (depth.requires) for a page-type + universal. */
+export function dataThemesFor(catalog: Catalog, pageType: string | null): CatalogTheme[] {
+  const themes: CatalogTheme[] = [];
+  if (pageType && catalog.page_types[pageType]) themes.push(...catalog.page_types[pageType].must_cover);
+  themes.push(...catalog.universal);
+  return themes.filter((t) => t.depth?.requires === 'data-assertion');
+}
+
+// ---------- Sensor 3: Coverage balance ----------
+
+export interface BalanceResult {
+  byBucket: Record<string, number>;
+  byCategory: Record<string, number>;
+  coreCount: number;
+  secondaryCount: number;
+  imbalanced: boolean;
+  note: string;
+}
+
+export function coverageBalance(scenarios: ScenarioInfo[]): BalanceResult {
+  const byCategory: Record<string, number> = {};
+  const byBucket: Record<string, number> = {};
+  for (const b of Object.keys(BUCKETS)) byBucket[b] = 0;
+  byBucket['other'] = 0;
+
+  for (const s of scenarios) {
+    const cat = s.category || 'NONE';
+    byCategory[cat] = (byCategory[cat] || 0) + 1;
+    const bucket = Object.entries(BUCKETS).find(([, cats]) => cats.includes(cat))?.[0] || 'other';
+    byBucket[bucket]++;
+  }
+
+  const core = byBucket['business-core'];
+  const secondary = byBucket['presentation'] + byBucket['validation-security'];
+  const imbalanced = secondary > core * 1.5 && core > 0;
+  return {
+    byBucket,
+    byCategory,
+    coreCount: core,
+    secondaryCount: secondary,
+    imbalanced,
+    note: imbalanced
+      ? `Secondary viewpoints (presentation+validation/security = ${secondary}) outweigh business-core (${core}) by >1.5x.`
+      : 'Balanced.',
+  };
+}
+
+// ---------- Sensor 4: Duplicate clusters ----------
+
+export interface DuplicateResult {
+  clusters: { skeleton: string; scenarios: string[]; sameDataLikely: boolean }[];
+  exactDuplicateCount: number;
+  sameShapeCount: number;
+}
+
+export function duplicateClusters(scenarios: ScenarioInfo[]): DuplicateResult {
+  const map = new Map<string, ScenarioInfo[]>();
+  for (const s of scenarios) {
+    const arr = map.get(s.stepSkeleton) || [];
+    arr.push(s);
+    map.set(s.stepSkeleton, arr);
+  }
+  const clusters = [...map.entries()]
+    .filter(([, arr]) => arr.length > 1)
+    .map(([skeleton, arr]) => ({
+      skeleton: skeleton.length > 120 ? skeleton.slice(0, 117) + '...' : skeleton,
+      scenarios: arr.map((s) => s.name),
+      // Same skeleton with data placeholders → likely an EP/data family (intentional), not a true dup.
+      sameDataLikely: !skeleton.includes('{}'),
+    }));
+  return {
+    clusters,
+    exactDuplicateCount: clusters.filter((c) => c.sameDataLikely).reduce((n, c) => n + (c.scenarios.length - 1), 0),
+    sameShapeCount: clusters.reduce((n, c) => n + c.scenarios.length, 0),
+  };
+}
+
+// ---------- Sensor 5: Traceability ----------
+
+export interface TraceResult {
+  total: number;
+  withVpCode: number;
+  mappedToOverview: number;
+  withVpCodeRatio: number;
+  mappedRatio: number;
+  note: string;
+}
+
+export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
+  const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
+  const withCode = scenarios.filter((s) => s.vpCode);
+  // A scenario maps to overview if its full VP code OR its category-derived id exists in overview.
+  const mapped = withCode.filter((s) => overviewIds.has(s.vpCode!) || [...overviewIds].some((id) => id.includes(s.category || '###')));
+  return {
+    total: scenarios.length,
+    withVpCode: withCode.length,
+    mappedToOverview: mapped.length,
+    withVpCodeRatio: scenarios.length ? withCode.length / scenarios.length : 0,
+    mappedRatio: scenarios.length ? mapped.length / scenarios.length : 0,
+    note: mapped.length < withCode.length * 0.5
+      ? 'Scenarios use ad-hoc VP-<CAT>-NNN codes not linked to viewpoint-overview ids (weak traceability — see review Gate 4).'
+      : 'Traceable.',
+  };
+}

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

@@ -39,6 +39,9 @@ export class ProjectInitializer {
     // Create directories
     this.createDirectories();
 
+    // Create qa/context.md for QA lead to fill project-wide context
+    this.createContext();
+
     // Ensure package.json and install Playwright
     await this.setupDependencies();
 
@@ -147,10 +150,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)) {
@@ -159,12 +164,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 {
@@ -363,6 +369,23 @@ export class ProjectInitializer {
 
   }
 
+  /**
+   * Create qa/context.md for the QA lead to fill project-wide context
+   * (roles, testing strategy, global rules, error patterns).
+   */
+  private createContext(): void {
+    const contextPath = path.join(this.cwd, 'qa', 'context.md');
+
+    if (fs.existsSync(contextPath)) {
+      this.skippedItems.push('qa/context.md');
+      return;
+    }
+
+    const content = this.readTemplate('qa-context.md');
+    fs.writeFileSync(contextPath, content, 'utf-8');
+    this.createdItems.push('qa/context.md');
+  }
+
   /**
    * Create specs/base.ts for shared browser context
    */