@sun-asterisk/sungen 3.2.2-beta.9 → 3.2.3-beta.3

package/src/harness/journey.ts

@@ -27,6 +27,10 @@ export interface Obligation {
   waivedReason?: string;   // S2 — set when the QA explicitly waived this obligation
 }
 
+/** S5 — a parsed anchor so an IDE can jump straight to what needs review. */
+export interface Anchor { vpId?: string; file?: string; line?: number; }
+export interface ReviewItem { text: string; anchor: Anchor; }
+
 export interface JourneyReport {
   unit: string;
   generatedFrom: string[];          // which artifacts were available
@@ -35,7 +39,7 @@ export interface JourneyReport {
   gateStatus: string | null;
   score: number | null;
   obligations: Obligation[];
-  needsYou: string[];               // located findings / human-judgment items (the review queue seed)
+  needsYou: ReviewItem[];           // S5 — the review queue: human-judgment findings, each with an anchor
   nextSuggested: string;
 }
 
@@ -58,6 +62,13 @@ function isHumanFinding(f: string): boolean {
   return /@manual|MANUAL-|DEPTH-DEFERRED|UNSOURCEABLE|CAPABILITY-SUGGESTION|judgment|oracle|review/i.test(f);
 }
 
+/** S5 — pull an IDE-jumpable anchor out of a finding (VP id, scenario, or `file.ext:line`). */
+function extractAnchor(text: string): Anchor {
+  const vp = text.match(/\bVP-[A-Z0-9-]+\b/);
+  const fl = text.match(/([\w./-]+\.(?:md|feature|ts|yaml)):(\d+)/);
+  return { vpId: vp ? vp[0] : undefined, file: fl ? fl[1] : undefined, line: fl ? Number(fl[2]) : undefined };
+}
+
 const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
 
 function computeFresh(projectRoot: string, unit: string): JourneyReport {
@@ -73,7 +84,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
   const ran = (p: string) => phases.some((s) => s === p || s.startsWith(p));
 
   const obligations: Obligation[] = [];
-  const needsYou: string[] = [];
+  const needsYou: ReviewItem[] = [];
 
   if (!audit) {
     // Nothing measured yet — the journey hasn't really begun.
@@ -105,19 +116,31 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
     detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
   });
 
-  // Human sign-off: always pending until S5 explicit signoff; carries the review-queue count.
-  const manualCount = (audit.manualOracle && audit.manualOracle.total) || 0;
+  // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
+  // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
+  // the aggregate "DEPTH:" finding string (which names no scenario, so points nowhere). Then
+  // supplement with the remaining human-judgment findings.
+  const shallowBC: { name: string; category?: string }[] = (audit.depth && audit.depth.shallowBusinessCritical) || [];
+  for (const s of shallowBC) {
+    needsYou.push({
+      text: `DEEPEN — "${s.name}": assert data, not just visibility (\`… with {{value}}\` / \`see all … contain {{v}}\`), or defer cross-screen with @manual + reason.`,
+      anchor: extractAnchor(s.name),
+    });
+  }
+  const haveStructuredDepth = shallowBC.length > 0;
+  for (const f of (audit.findings || [])) {
+    if (!isHumanFinding(f)) continue;
+    if (haveStructuredDepth && /^\s*DEPTH\b/i.test(f)) continue; // superseded by the per-scenario items above
+    needsYou.push({ text: f, anchor: extractAnchor(f) });
+  }
+
+  // Human sign-off: always pending until S5 explicit signoff; carries the now-final review-queue count.
+  const manualCount = (audit.manualOracle && (audit.manualOracle.manualTotal ?? audit.manualOracle.total)) || 0;
   obligations.push({
     id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
-    detail: `${needsYou.length} item(s) queued for your review (single sign-off at the end)`,
+    detail: `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`,
   });
 
-  // Needs-you: human-judgment findings (the review-queue seed), with their anchors (titles) intact.
-  for (const f of (audit.findings || [])) if (isHumanFinding(f)) needsYou.push(f);
-  // Re-stamp the signoff detail now that needsYou is filled.
-  const signoff = obligations.find((o) => o.id === 'OB-signoff');
-  if (signoff) signoff.detail = `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`;
-
   // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
   const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
   let nextSuggested: string;
@@ -135,7 +158,8 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 // ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
 
 interface Waiver { reason: string; at: string; auditHashAtWaive: string; }
-interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; }
+interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5
+interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; signoff?: Signoff; }
 
 function statePath(projectRoot: string, slug: string): string {
   return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
@@ -181,11 +205,22 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
       ob.waivedReason = w.reason;
       ob.detail = `waived — ${w.reason}`;
     } else {
-      report.needsYou.unshift(`⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`);
+      report.needsYou.unshift({ text: `⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`, anchor: { vpId: ob.id } });
+    }
+  }
+  // S5 — sign-off reconcile: a recorded sign-off satisfies OB-signoff while its evidence holds;
+  // if the audit changed since, the sign-off is STALE → re-surface for re-review (anti-amnesia).
+  const signoffOb = report.obligations.find((o) => o.id === 'OB-signoff');
+  if (signoffOb && state.signoff) {
+    if (state.signoff.auditHashAtSignoff === curHash) {
+      signoffOb.status = 'satisfied';
+      signoffOb.detail = `signed off${state.signoff.by ? ' by ' + state.signoff.by : ''} at ${state.signoff.at}`;
+    } else {
+      report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
     }
   }
   report.nextSuggested = computeNext(report, unit);
-  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers });
+  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers, signoff: state.signoff });
   return report;
 }
 
@@ -210,6 +245,25 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
   return runJourney(projectRoot, unit);
 }
 
+/**
+ * Sign off — the single human gate (S5). Allowed ONLY when every other deliver-required
+ * obligation is satisfied or waived (you cannot sign off an unclean suite). Records who/when +
+ * the evidence cursor; reconcile invalidates it (stale → re-review) if the suite later changes.
+ */
+export function signoff(projectRoot: string, unit: string, by?: string): JourneyReport {
+  const before = runJourney(projectRoot, unit);
+  const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived');
+  if (blockers.length) {
+    throw new Error(`Cannot sign off — still open: ${blockers.map((b) => b.id).join(', ')}. Fix, or waive each with a reason, first.`);
+  }
+  const slug = reportSlug(unit);
+  const sp = statePath(projectRoot, slug);
+  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
+  state.signoff = { by, at: new Date().toISOString(), auditHashAtSignoff: auditHashOf(projectRoot, slug) };
+  saveState(sp, state);
+  return runJourney(projectRoot, unit);
+}
+
 const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
 
 export function renderJourneyBoard(r: JourneyReport): string {
@@ -222,9 +276,14 @@ export function renderJourneyBoard(r: JourneyReport): string {
   L.push('## What must still be true');
   for (const o of r.obligations) L.push(`- ${ICON[o.status]} **${o.title}** — ${o.detail}`);
   L.push('');
-  L.push(`## 🔎 Needs your judgment (${r.needsYou.length})`);
-  if (r.needsYou.length) for (const f of r.needsYou.slice(0, 20)) L.push(`- ${f}`);
-  else L.push('- (nothing queued)');
+  L.push(`## 🔎 Review queue — needs your judgment (${r.needsYou.length})`);
+  if (r.needsYou.length) {
+    for (const it of r.needsYou.slice(0, 20)) {
+      const a = it.anchor;
+      const tag = [a.vpId, a.file && `${a.file}${a.line ? ':' + a.line : ''}`].filter(Boolean).join(' · ');
+      L.push(`- ${it.text}${tag ? `  〔${tag}〕` : ''}`);
+    }
+  } else L.push('- (nothing queued)');
   L.push('');
   L.push(`## → Next`);
   L.push(`${r.nextSuggested}`);
@@ -255,8 +314,8 @@ const PHASE_REQUIRED: Record<GatePhase, string[]> = {
   create: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace'],
   // post-run: the design gates + automation coverage.
   run: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation'],
-  // pre-delivery: everything automated (human sign-off is the separate S5 gate).
-  deliver: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation'],
+  // pre-delivery: everything automated PLUS the single human sign-off (S5).
+  deliver: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation', 'OB-signoff'],
 };
 
 export function runGate(projectRoot: string, unit: string, phase: GatePhase): GateVerdict {
@@ -284,3 +343,92 @@ export function renderGate(v: GateVerdict): string {
   L.push('');
   return L.join('\n');
 }
+
+// ---------------- #409: project-level roll-up across all units ----------------
+//
+// Multi-unit fan-out PARALLELISES generation but human review/sign-off must stay SERIAL — you can't
+// judge N boards at once. This roll-up is that serial surface: one row per unit (gate · score · phase
+// · what it still needs), and a single "review this next" pointer. The per-unit board is unchanged;
+// this only aggregates the same read-only `runJourney` synthesis.
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+export interface UnitSummary {
+  unit: string;
+  kind: UnitKind;
+  score: number | null;
+  gateStatus: string | null;
+  youAreHere: string;
+  obligationsOpen: number;   // non-satisfied, non-waived (excludes OB-signoff)
+  reviewQueue: number;
+  signedOff: boolean;
+  started: boolean;          // has an audit report yet
+}
+
+/** Discover every unit under qa/screens, qa/flows, and qa/api top-level areas. */
+export function listUnits(projectRoot: string): { unit: string; kind: UnitKind }[] {
+  const out: { unit: string; kind: UnitKind }[] = [];
+  const scan = (sub: string, kind: UnitKind) => {
+    const d = path.join(projectRoot, 'qa', sub);
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      // 'flows' under qa/api is a container for api-flows (a nested tier) — not a unit itself.
+      if (e.isDirectory() && !(sub === 'api' && e.name === 'flows')) out.push({ unit: e.name, kind });
+    }
+  };
+  scan('screens', 'screen');
+  scan('flows', 'flow');
+  scan('api', 'api');
+  return out;
+}
+
+/** Roll up every unit's journey into one table of summaries (serial review surface). */
+export function rollupJourney(projectRoot: string): UnitSummary[] {
+  return listUnits(projectRoot).map(({ unit, kind }) => {
+    const r = runJourney(projectRoot, unit);
+    const signedOff = r.obligations.find((o) => o.id === 'OB-signoff')?.status === 'satisfied';
+    const obligationsOpen = r.obligations.filter(
+      (o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived',
+    ).length;
+    return {
+      unit, kind, score: r.score, gateStatus: r.gateStatus, youAreHere: r.youAreHere,
+      obligationsOpen, reviewQueue: r.needsYou.length, signedOff,
+      started: r.generatedFrom.includes('audit'),
+    };
+  });
+}
+
+function unitStatusLabel(r: UnitSummary): string {
+  if (!r.started) return '◻️ not started';
+  if (r.signedOff) return '✅ signed off';
+  if (r.obligationsOpen > 0) return `⏳ ${r.obligationsOpen} obligation(s) open`;
+  if (r.reviewQueue > 0) return `🔎 review ${r.reviewQueue} item(s)`;
+  return '🟡 ready to sign off';
+}
+
+export function renderRollupBoard(rows: UnitSummary[]): string {
+  const L: string[] = [];
+  L.push('# Journey roll-up — all units');
+  L.push('');
+  if (!rows.length) {
+    L.push('No units found under `qa/screens`, `qa/flows`, or `qa/api`.');
+    return L.join('\n');
+  }
+  L.push('| Unit | Kind | Score | Gate | Phase | Needs |');
+  L.push('|---|---|---|---|---|---|');
+  for (const r of rows) {
+    L.push(`| ${r.unit} | ${r.kind} | ${r.score ?? '—'} | ${r.gateStatus ?? '—'} | ${r.youAreHere} | ${unitStatusLabel(r)} |`);
+  }
+  L.push('');
+  const blocked = rows.filter((r) => r.started && (r.obligationsOpen > 0));
+  const toReview = rows.filter((r) => r.started && r.obligationsOpen === 0 && !r.signedOff && r.reviewQueue >= 0);
+  const notStarted = rows.filter((r) => !r.started);
+  L.push(`**${rows.filter((r) => r.signedOff).length}/${rows.length} signed off** · ${blocked.length} with open obligations · ${notStarted.length} not started.`);
+  L.push('');
+  L.push('## → Next (review is serial — one unit at a time)');
+  const next = blocked[0] || toReview[0] || notStarted[0];
+  if (!next) L.push('All units signed off — `sungen delivery` to export.');
+  else if (!next.started) L.push(`Generate **${next.unit}** — \`/sungen:create-test ${next.unit}\`.`);
+  else L.push(`Review **${next.unit}** (${unitStatusLabel(next)}) — \`sungen journey --screen ${next.unit}\`, then sign off.`);
+  L.push('');
+  return L.join('\n');
+}

package/src/harness/quality-gates.ts

@@ -42,6 +42,26 @@ export function isolationRisk(featureText: string, stateful: boolean): boolean {
   return !/@cleanup:cart\b|@isolate\b|empty cart|fresh (?:browser )?context|new context/i.test(featureText);
 }
 
+/**
+ * #414 — the complement of isolationRisk. Per-scenario isolation is the DEFAULT now, so untagged
+ * suites can't cascade. `@serial` opts INTO a shared-page `test.describe.serial` suite, whose
+ * Playwright semantics SKIP every test after the first failure. That is correct ONLY for a genuinely
+ * stateful ordered sequence; for INDEPENDENT scenarios — each re-establishing its own start state via
+ * a navigating Background — `@serial` buys no correctness, only a cascade that *masks* failures (one
+ * early red turns the rest into greens-by-omission). Returns the scenario count when `@serial` should
+ * be dropped (the default isolation is safer), else 0.
+ *
+ * Conservative on purpose — only fires on `@serial` suites whose every scenario provably restarts (a
+ * `Background` that navigates `on [..] page`), so a real stateful sequence keeps its `@serial`.
+ */
+export function serialCascadeRisk(featureText: string, scenarioCount: number): number {
+  if (!/@serial\b/i.test(featureText)) return 0;        // isolated by default → no cascade
+  if (scenarioCount < 8) return 0;                      // small blast radius — not worth the churn
+  const navBackground = /Background:[\s\S]*?\bon \[[^\]]+\] page\b/i.test(featureText);
+  if (!navBackground) return 0;                         // no per-scenario reset → genuinely stateful; @serial is right
+  return scenarioCount;
+}
+
 export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
   const routes = downstreamRoutes(specText);
   const underCovered: { route: string; slug: string }[] = [];

package/src/harness/sensors.ts

@@ -59,9 +59,17 @@ export function loadCatalog(): Catalog {
   return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
 }
 
+// Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
+// simple plural/verb suffixes) but NOT as a substring of a larger word — e.g. `form` must not
+// match inside `Format` or `@platform`, while `product` still matches `products`. Multi-word
+// keywords ("add to cart", "is hidden") match the phrase with a boundary at each end.
+const wordRe = (kw: string) => {
+  const esc = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${esc}(?:s|es|ed|ing)?\\b`);
+};
 const has = (haystacks: string[], kw: string) => {
-  const k = kw.toLowerCase();
-  return haystacks.some((h) => h.includes(k));
+  const re = wordRe(kw);
+  return haystacks.some((h) => re.test(h));
 };
 
 // ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
@@ -75,16 +83,21 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog): GateResult {
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
   ];
 
-  // Detect page-type by detect_keywords hit count
+  // Detect page-type by detect_keywords hit count. `mobile-*` page-types are candidates ONLY for
+  // mobile targets; web targets never consider them. Mobile targets still consider the web types
+  // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
+  // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
+  // null → no themes required → the gate passes leniently rather than false-FAILing.
   let pageType: string | null = null;
   let best = 0;
   for (const [pt, def] of Object.entries(catalog.page_types)) {
+    if (pt.startsWith('mobile-') && !isMobile) continue;
     const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
     if (hits > best) { best = hits; pageType = pt; }
   }
@@ -97,10 +110,14 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
       // 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' });
+      if (coverers.length === 0) { gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' }); continue; }
+      // A theme WITHOUT `depth:` is visibility/navigation — landing/seeing/leaving IS the
+      // assertion, so mere presence covers it. Only DATA-correctness themes (depth.requires:
+      // data-assertion) need a data assertion to count as deeply covered.
+      const needsDepth = t.depth?.requires === 'data-assertion';
+      if (!needsDepth) { covered++; continue; }
+      if (coverers.some((s) => s.hasDataAssertion)) covered++;
+      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
     }
   }
 

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

@@ -6,106 +6,15 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { buildOutputs } from './ai-skills/build';
+import { applyOutputs } from './ai-skills/writer';
+import { AdapterKey } from './ai-skills/adapters';
 
-// File mapping: [templateFile, outputPath]
-// Shared with project-initializer.ts
-export const AI_RULES_FILE_MAPPING: [string, string][] = [
-  // Config
-  ['claude-config.md', 'CLAUDE.md'],
-  ['copilot-config.md', '.github/copilot-instructions.md'],
-
-  // Commands — Claude Code
-  ['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'],
-  ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
-  ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
-  ['claude-skill-tc-generation.md', '.claude/skills/sungen-tc-generation/SKILL.md'],
-  ['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-api-design.md', '.claude/skills/sungen-api-design/SKILL.md'],
-  ['claude-skill-ingest-legacy.md', '.claude/skills/sungen-ingest-legacy/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'],
-  ['claude-skill-viewpoint-group-c-data-explore.md', '.claude/skills/sungen-viewpoint/group-c-data-explore.md'],
-  ['claude-skill-viewpoint-group-d-display.md', '.claude/skills/sungen-viewpoint/group-d-display.md'],
-  ['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'],
-  // 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'],
-  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
-  ['claude-skill-mobile-gestures.md', '.claude/skills/sungen-mobile-gestures/SKILL.md'],
-  ['claude-skill-capture-mobile.md', '.claude/skills/sungen-capture-mobile/SKILL.md'],
-  ['claude-skill-selector-fix-mobile.md', '.claude/skills/sungen-selector-fix-mobile/SKILL.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'],
-  ['claude-agent-generator.md', '.claude/agents/sungen-generator.md'],
+function sungenVersion(): string {
+  try { return require(path.join(__dirname, '..', '..', 'package.json')).version || '0.0.0'; }
+  catch { return '0.0.0'; }
+}
 
-  // Skills — GitHub Copilot
-  ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
-  ['github-skill-sungen-selector-keys.md', '.github/skills/sungen-selector-keys/SKILL.md'],
-  ['github-skill-sungen-error-mapping.md', '.github/skills/sungen-error-mapping/SKILL.md'],
-  ['github-skill-sungen-tc-generation.md', '.github/skills/sungen-tc-generation/SKILL.md'],
-  ['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-api-design.md', '.github/skills/sungen-api-design/SKILL.md'],
-  ['github-skill-sungen-ingest-legacy.md', '.github/skills/sungen-ingest-legacy/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'],
-  ['github-skill-sungen-viewpoint-group-c-data-explore.md', '.github/skills/sungen-viewpoint/group-c-data-explore.md'],
-  ['github-skill-sungen-viewpoint-group-d-display.md', '.github/skills/sungen-viewpoint/group-d-display.md'],
-  ['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.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'],
-  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
-  ['github-skill-sungen-mobile-gestures.md', '.github/skills/sungen-mobile-gestures/SKILL.md'],
-  ['github-skill-sungen-capture-mobile.md', '.github/skills/sungen-capture-mobile/SKILL.md'],
-  ['github-skill-sungen-selector-fix-mobile.md', '.github/skills/sungen-selector-fix-mobile/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.
@@ -124,119 +33,48 @@ export const STALE_AI_RULES_PATHS: string[] = [
 
 export class AIRulesUpdater {
   private cwd: string;
-  private aiTemplateDir: string;
 
   constructor(cwd: string) {
     this.cwd = cwd;
-    this.aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
   }
 
-  async update(dryRun: boolean): Promise<void> {
-    console.log('🔄 Updating AI rules, commands, and skills...\n');
-
-    const updated: string[] = [];
-    const created: string[] = [];
-    const unchanged: string[] = [];
-    const missing: string[] = [];
-
-    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
-      const templatePath = path.join(this.aiTemplateDir, templateFile);
-      const outputPath = path.join(this.cwd, outputRelPath);
-
-      if (!fs.existsSync(templatePath)) {
-        missing.push(templateFile);
-        continue;
-      }
-
-      const newContent = fs.readFileSync(templatePath, 'utf-8');
-
-      if (fs.existsSync(outputPath)) {
-        const currentContent = fs.readFileSync(outputPath, 'utf-8');
-        if (currentContent === newContent) {
-          unchanged.push(outputRelPath);
-          continue;
-        }
-
-        if (!dryRun) {
-          fs.writeFileSync(outputPath, newContent, 'utf-8');
-        }
-        updated.push(outputRelPath);
-      } else {
-        if (!dryRun) {
-          const outputDir = path.dirname(outputPath);
-          if (!fs.existsSync(outputDir)) {
-            fs.mkdirSync(outputDir, { recursive: true });
-          }
-          fs.writeFileSync(outputPath, newContent, 'utf-8');
-        }
-        created.push(outputRelPath);
-      }
-    }
-
-    // Remove retired skills/assets so stale descriptions stop loading.
+  /**
+   * Refresh AI rules/commands/skills from the single-source generator.
+   * @param dryRun show changes without writing
+   * @param opts.agents which assistants to install (default: claude — decision T5)
+   * @param opts.force overwrite user config files (CLAUDE.md/AGENTS.md/copilot-instructions)
+   */
+  async update(dryRun: boolean, opts: { agents?: AdapterKey[]; force?: boolean } = {}): Promise<void> {
+    const agents = opts.agents && opts.agents.length ? opts.agents : (['claude'] as AdapterKey[]);
+    console.log(`🔄 Updating AI rules for: ${agents.join(', ')}${dryRun ? ' (dry-run)' : ''}\n`);
+
+    // One-time legacy cleanup for projects created before the manifest existed.
     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 });
-        }
+        if (!dryRun) fs.rmSync(stalePath, { recursive: true, force: true });
         removed.push(staleRelPath);
       }
     }
 
-    // Print results
-    if (dryRun) {
-      console.log('📋 Dry run — no files changed\n');
+    const outputs = buildOutputs(agents);
+    const r = applyOutputs(this.cwd, outputs, { version: sungenVersion(), dryRun, force: opts.force });
+
+    if (dryRun) console.log('📋 Dry run — no files changed\n');
+    if (removed.length) console.log(`🗑️  Removed retired assets (${removed.length})`);
+    if (r.deletedOrphans.length) console.log(`🗑️  Removed orphans (${r.deletedOrphans.length}): ${r.deletedOrphans.join(', ')}`);
+    if (r.created.length) console.log(`✨ Created (${r.created.length})`);
+    if (r.overwritten.length) console.log(`✏️  Updated (${r.overwritten.length})`);
+    if (r.skippedConfig.length) console.log(`⏭️  Config preserved (use --force to overwrite): ${r.skippedConfig.join(', ')}`);
+    if (r.handEditWarnings.length) {
+      console.log(`\n⚠️  Overwrote files that look hand-edited (sungen owns these — version-managed):`);
+      for (const f of r.handEditWarnings) console.log(`   ${f}`);
     }
 
-    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) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (created.length > 0) {
-      console.log(`✨ Created (${created.length}):`);
-      for (const f of created) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (unchanged.length > 0) {
-      console.log(`✅ Already up to date (${unchanged.length}):`);
-      for (const f of unchanged) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    if (missing.length > 0) {
-      console.log(`⚠️  Template not found (${missing.length}):`);
-      for (const f of missing) {
-        console.log(`   ${f}`);
-      }
-      console.log();
-    }
-
-    const totalChanges = updated.length + created.length;
-    if (totalChanges === 0) {
-      console.log('All AI rules are up to date. No changes needed.');
-    } else if (dryRun) {
-      console.log(`${totalChanges} file(s) would be changed. Run without --dry-run to apply.`);
-    } else {
-      console.log(`${totalChanges} file(s) updated successfully.`);
-    }
+    const total = r.created.length + r.overwritten.length;
+    if (total === 0 && !removed.length && !r.deletedOrphans.length) console.log('All AI rules are up to date. No changes needed.');
+    else if (dryRun) console.log(`\n${total} file(s) would change. Run without --dry-run to apply.`);
+    else console.log(`\n${total} file(s) updated for ${agents.join(', ')}.`);
   }
 }