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

package/src/harness/script-check.ts

@@ -0,0 +1,222 @@
+/**
+ * Script-check — verify the generated Playwright spec is a faithful 1:1 of the
+ * Gherkin feature, i.e. "the testcase and the test code are not two different things".
+ *
+ * Two deterministic checks:
+ *   A. Structural 1:1 — every non-@manual / non-@steps scenario has exactly one
+ *      matching `test('<title>')` block in the committed spec (and no extras).
+ *   B. Drift — regenerate the spec from the SAME .feature + selectors + test-data
+ *      into a temp dir and diff against the committed spec. Any difference means
+ *      the committed spec was hand-edited or is stale (feature changed without a
+ *      regenerate) → the script no longer reflects the testcase.
+ *
+ * Pure-deterministic (reuses the compiler). No AI.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { loadScenarios } from './parse';
+
+export interface ScriptCheckResult {
+  screen: string;
+  specPath: string | null;
+  automatedScenarios: number;   // non-manual, non-steps
+  manualScenarios: number;
+  specTestBlocks: number;
+  countMatch: boolean;
+  missingInSpec: string[];      // scenario titles with no test() block
+  extraInSpec: string[];        // test() titles with no scenario
+  drift: 'in-sync' | 'drift' | 'no-spec';
+  driftHunks: string[];         // sample differing lines (committed vs regenerated)
+  // C. Anti-bypass / faithfulness — a present test that proves nothing.
+  assertionlessTests: string[];                    // non-manual test() with 0 expect()
+  hollowSteps: { test: string; step: string }[];   // a step-comment that emitted no code
+  bypass: boolean;
+  status: 'OK' | 'FAIL';
+  findings: string[];
+}
+
+/** Split a spec into test() blocks (title + body) via brace counting. */
+export function extractTestBlocks(specSrc: string): { title: string; body: string[] }[] {
+  const lines = specSrc.split('\n');
+  const blocks: { title: string; body: string[] }[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/);
+    if (!m) continue;
+    let depth = 0, started = false;
+    const body: string[] = [];
+    for (let j = i; j < lines.length; j++) {
+      for (const ch of lines[j]) { if (ch === '{') { depth++; started = true; } else if (ch === '}') depth--; }
+      body.push(lines[j]);
+      if (started && depth <= 0) break;
+    }
+    blocks.push({ title: m[2].trim(), body });
+  }
+  return blocks;
+}
+
+const CODE_LINE = /\b(await|expect|testData|page\.)\b|=\s*[^=]/;
+
+/**
+ * Faithfulness / anti-bypass: a non-@manual test that performs actions but proves
+ * nothing (0 assertions), or a step-comment that emitted no executable code (hollow
+ * — the testcase step is not run). Structural 1:1 can't see these.
+ */
+export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string>) {
+  const assertionlessTests: string[] = [];
+  const hollowSteps: { test: string; step: string }[] = [];
+  for (const blk of extractTestBlocks(specSrc)) {
+    if (!automatedTitles.has(blk.title)) continue; // only non-@manual scenarios
+    const body = blk.body;
+    if (!body.some((l) => /expect\(/.test(l))) assertionlessTests.push(blk.title);
+    // hollow step: a `// step` whose region (until the NEXT step-comment / block end)
+    // contains no executable code. The region — not just the next line — is checked,
+    // so block-style steps (`// Assert all … { … expect … }`) are correctly counted.
+    const stepIdx: number[] = [];
+    for (let k = 1; k < body.length; k++) if (body[k].trim().startsWith('//')) stepIdx.push(k);
+    for (let s = 0; s < stepIdx.length; s++) {
+      const start = stepIdx[s] + 1;
+      const end = s + 1 < stepIdx.length ? stepIdx[s + 1] : body.length;
+      const hasCode = body.slice(start, end).some((l) => CODE_LINE.test(l));
+      if (!hasCode) hollowSteps.push({ test: blk.title, step: body[stepIdx[s]].trim().slice(0, 70) });
+    }
+  }
+  return { assertionlessTests, hollowSteps };
+}
+
+function extractTestTitles(specSrc: string): string[] {
+  // Count real test cases only: test(...), test.only/.skip/.fixme(...).
+  // Exclude test.describe / test.beforeAll / hooks (not test cases).
+  const titles: string[] = [];
+  const re = /\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(specSrc))) titles.push(m[2].trim());
+  return titles;
+}
+
+function normalize(src: string): string {
+  return src
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function findSpec(dir: string, name: string, flowMode: boolean): string | null {
+  // Screens compile to  <dir>/<name>/<feature>.spec.ts
+  // Flows   compile to  <dir>/flows/<name>/<feature>.spec.ts
+  // Scope the search to THIS target's own subdir — otherwise the first spec of
+  // ANY other screen/flow is returned, which (for an uncompiled flow) falsely
+  // reports the wrong screen's tests as drift.
+  const hits: string[] = [];
+  const walk = (d: string) => {
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.spec.ts')) hits.push(p);
+    }
+  };
+  const scoped = flowMode ? path.join(dir, 'flows', name) : path.join(dir, name);
+  if (!fs.existsSync(scoped)) return null; // no spec for this target (e.g. not compiled yet)
+  walk(scoped);
+  return hits[0] ?? null;
+}
+
+export async function runScriptCheck(screenDir: string, screenName: string, flowMode: boolean): Promise<ScriptCheckResult> {
+  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
+  const scenarios = loadScenarios(featurePath);
+  const automated = scenarios.filter((s) => !s.manual);
+  const manual = scenarios.filter((s) => s.manual);
+
+  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, flowMode);
+
+  const findings: string[] = [];
+  let specTitles: string[] = [];
+  let specSrc = '';
+  if (committedSpec) {
+    specSrc = fs.readFileSync(committedSpec, 'utf-8');
+    specTitles = extractTestTitles(specSrc);
+  } else {
+    findings.push('No generated spec found under specs/generated/ — run `sungen generate` / `/sungen:run-test` first.');
+  }
+
+  // A. Structural 1:1
+  const specTitleSet = new Set(specTitles);
+  const scenTitleSet = new Set(automated.map((s) => s.name));
+  const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);
+  const extraInSpec = specTitles.filter((t) => !scenTitleSet.has(t));
+  const countMatch = committedSpec ? automated.length === specTitles.length : false;
+  if (committedSpec && !countMatch) {
+    findings.push(`Count mismatch: ${automated.length} automated scenarios vs ${specTitles.length} test() blocks.`);
+  }
+  for (const t of missingInSpec) findings.push(`MISSING in spec: scenario "${t}" has no test() block (stale spec — regenerate).`);
+  for (const t of extraInSpec) findings.push(`EXTRA in spec: test "${t}" has no matching scenario (hand-edited spec).`);
+
+  // B. Drift — regenerate to temp and diff
+  let drift: ScriptCheckResult['drift'] = committedSpec ? 'in-sync' : 'no-spec';
+  const driftHunks: string[] = [];
+  if (committedSpec) {
+    try {
+      const { CodeGenerator } = require('../generators/test-generator/code-generator');
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-scriptcheck-'));
+      const qaSourceDir = path.join(process.cwd(), 'qa', flowMode ? 'flows' : 'screens');
+      const gen = new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode });
+      await gen.generateAllTests(qaSourceDir, tmp, [featurePath]);
+      const fresh = findSpec(tmp, screenName, flowMode);
+      if (fresh) {
+        const a = normalize(specSrc);
+        const b = normalize(fs.readFileSync(fresh, 'utf-8'));
+        if (a !== b) {
+          drift = 'drift';
+          // collect a few differing lines
+          const al = a.split('\n'), bl = b.split('\n');
+          const max = Math.max(al.length, bl.length);
+          for (let i = 0, shown = 0; i < max && shown < 6; i++) {
+            if (al[i] !== bl[i]) {
+              driftHunks.push(`  L${i + 1}\n    committed: ${(al[i] ?? '∅').trim().slice(0, 100)}\n    expected : ${(bl[i] ?? '∅').trim().slice(0, 100)}`);
+              shown++;
+            }
+          }
+          findings.push('DRIFT: committed spec differs from a fresh regenerate → spec was hand-edited or the .feature changed without `sungen generate`. The test code no longer reflects the Gherkin.');
+        }
+      }
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch (e) {
+      findings.push(`Drift check skipped (regenerate failed): ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  // C. Anti-bypass / faithfulness
+  const { assertionlessTests, hollowSteps } = committedSpec
+    ? analyzeFaithfulness(specSrc, scenTitleSet)
+    : { assertionlessTests: [], hollowSteps: [] };
+  for (const t of assertionlessTests) {
+    findings.push(`BYPASS: test "${t}" has 0 assertions (action-only — proves nothing). The testcase is not really automated.`);
+  }
+  for (const h of hollowSteps) {
+    findings.push(`BYPASS: in "${h.test}", step "${h.step}" emitted no code (hollow — the testcase step is not executed).`);
+  }
+  const bypass = assertionlessTests.length > 0 || hollowSteps.length > 0;
+
+  const ok = !!committedSpec && countMatch && missingInSpec.length === 0 && extraInSpec.length === 0 && drift === 'in-sync' && !bypass;
+
+  return {
+    screen: screenName,
+    specPath: committedSpec,
+    automatedScenarios: automated.length,
+    manualScenarios: manual.length,
+    specTestBlocks: specTitles.length,
+    countMatch,
+    missingInSpec,
+    extraInSpec,
+    drift,
+    driftHunks,
+    assertionlessTests,
+    hollowSteps,
+    bypass,
+    status: ok ? 'OK' : 'FAIL',
+    findings,
+  };
+}

package/src/harness/secret-scan.ts

@@ -0,0 +1,51 @@
+/**
+ * Secret scanner (security S0) — warn (never block) when test-data appears to
+ * contain a REAL secret rather than a safe placeholder/test value.
+ *
+ * test-data/*.yaml is committed by design, so a real API key / prod token there is
+ * a leak waiting to happen. We flag high-confidence signals only, to avoid nagging
+ * about ordinary test passwords ("Test@123") or `{{vars}}`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SecretHit { file: string; line: number; reason: string }
+
+// High-confidence vendor token prefixes (very low false-positive rate).
+const VENDOR_PREFIXES = /\b(figd_[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{12,}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})/;
+// A secret-named key assigned a long, non-placeholder value.
+const SECRET_KEY = /\b(password|passwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret)\b\s*:\s*(.+)$/i;
+const PLACEHOLDERish = /\{\{|<.*>|changeme|example|dummy|test\b|placeholder|xxxx|\*\*\*/i;
+
+function scanText(text: string, file: string): SecretHit[] {
+  const hits: SecretHit[] = [];
+  text.split('\n').forEach((raw, i) => {
+    const line = i + 1;
+    if (VENDOR_PREFIXES.test(raw)) {
+      hits.push({ file, line, reason: 'looks like a real vendor API token/key' });
+      return;
+    }
+    const m = raw.match(SECRET_KEY);
+    if (m) {
+      const val = m[2].trim().replace(/^["']|["']$/g, '');
+      // Long, high-entropy-ish, not an obvious placeholder/test value.
+      if (val.length >= 20 && !PLACEHOLDERish.test(raw) && /[A-Za-z]/.test(val) && /[0-9]/.test(val)) {
+        hits.push({ file, line, reason: `secret-named key "${m[1]}" with a long literal value` });
+      }
+    }
+  });
+  return hits;
+}
+
+/** Scan a screen/flow dir's test-data/*.yaml for likely real secrets. */
+export function scanTestDataSecrets(baseDir: string): SecretHit[] {
+  const tdDir = path.join(baseDir, 'test-data');
+  if (!fs.existsSync(tdDir)) return [];
+  const hits: SecretHit[] = [];
+  for (const f of fs.readdirSync(tdDir)) {
+    if (!/\.ya?ml$/i.test(f)) continue;
+    const p = path.join(tdDir, f);
+    try { hits.push(...scanText(fs.readFileSync(p, 'utf-8'), path.join('test-data', f))); } catch { /* ignore */ }
+  }
+  return hits;
+}

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.',
+  };
+}