@sun-asterisk/sungen 3.0.0 → 3.1.0

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -63,7 +63,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -3,6 +3,9 @@ import { type Page, type BrowserContext } from '@playwright/test';
 {{#if runtimeData}}
 import { TestDataLoader } from '{{basePath}}/test-data';
 {{/if}}
+{{#if needsDb}}
+import { db } from '{{basePath}}/db';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/code-generator.ts

@@ -4,6 +4,7 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
+import { isDbStep } from './patterns/database-patterns';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -236,7 +237,11 @@ export class CodeGenerator {
     const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
     const needsCleanupImport = !isParallelFeature && hasCleanupTags;
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport });
+    // Data Driver: if any step verifies DB state, import the `db` helper + emit specs/db.ts
+    const needsDb = this.featureUsesDb(feature);
+    if (needsDb) this.ensureDbFile(outputDir);
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -292,8 +297,30 @@ export class CodeGenerator {
   /**
    * Ensure specs/base.ts exists in the output directory
    */
+  /** True when any step (background or scenario) in the feature is a DB-verification step. */
+  private featureUsesDb(feature: ParsedFeature): boolean {
+    const steps: ParsedStep[] = [];
+    if (feature.background?.steps) steps.push(...feature.background.steps);
+    for (const sc of feature.scenarios || []) if (sc.steps) steps.push(...sc.steps);
+    return steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text));
+  }
+
+  /** Copy the Data Driver runtime helper into specs/db.ts (idempotent). */
+  ensureDbFile(outputDir: string): void {
+    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
+    const dbPath = path.join(outputDir, 'db.ts');
+    if (!fs.existsSync(dbPath)) {
+      const templatePath = path.join(templatesRoot, 'specs-db.ts');
+      if (fs.existsSync(templatePath)) {
+        if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+        fs.copyFileSync(templatePath, dbPath);
+        console.log('✓ Created: specs/db.ts');
+      }
+    }
+  }
+
   ensureBaseFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', '..', 'orchestrator', 'templates');
+    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
 
     const basePath = path.join(outputDir, 'base.ts');
     if (!fs.existsSync(basePath)) {

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

@@ -0,0 +1,95 @@
+import { ParsedStep } from '../../gherkin-parser';
+import { StepPattern, PatternContext } from './types';
+import { MappedStep } from '../step-mapper';
+
+/**
+ * Database verification patterns (Data Driver v1) — declarative, no-SQL DB assertions
+ * that compile to calls on the runtime `db` helper (specs/db.ts). Read-only.
+ *
+ *   User see [users] row where [email] is {{reg_email}}
+ *   User see [users] row where [email] is {{reg_email}} has [status] = "active"
+ *   User see [users] no row where [email] is {{dup_email}}
+ *   User see [orders] where [buyer] is {{buyer}} count is {{expected_count}}
+ *
+ * Identifiers ([table]/[column]) are validated by the helper; values bind as parameters.
+ */
+
+const TABLE = String.raw`\[([A-Za-z_][A-Za-z0-9_]*)\]`;
+const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
+
+const reRow = new RegExp(`see\\s+${TABLE}\\s+row\\s+where\\b`, 'i');
+const reNoRow = new RegExp(`see\\s+${TABLE}\\s+no\\s+row\\s+where\\b`, 'i');
+const reCount = new RegExp(`see\\s+${TABLE}.*\\bcount\\s+is\\b`, 'i');
+
+/** True when a step is a DB-verification step (used to wire the `db` import). */
+export function isDbStep(text: string): boolean {
+  return reNoRow.test(text) || reRow.test(text) || reCount.test(text);
+}
+
+/** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
+function valueExpr(token: string): string {
+  const t = token.trim();
+  const v = t.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+  if (v) return `testData.get(${JSON.stringify(v[1])})`;
+  const q = t.match(/^["'](.*)["']$/);
+  if (q) return JSON.stringify(q[1]);
+  if (/^-?\d+(?:\.\d+)?$/.test(t)) return t;
+  return JSON.stringify(t);
+}
+
+/** Parse a `[col] is VALUE [and [col2] is VALUE2]` segment into a JS object literal. */
+function parseFilter(segment: string): string {
+  const re = new RegExp(`\\[([A-Za-z_][A-Za-z0-9_]*)\\]\\s+is\\s+(${VALUE})`, 'gi');
+  const parts: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(segment))) parts.push(`${JSON.stringify(m[1])}: ${valueExpr(m[2])}`);
+  return `{ ${parts.join(', ')} }`;
+}
+
+/** Parse a `has [col] = VALUE [and [col2] = VALUE2]` segment into a JS object literal. */
+function parseExpected(segment: string): string {
+  const re = new RegExp(`\\[([A-Za-z_][A-Za-z0-9_]*)\\]\\s*=\\s*(${VALUE})`, 'gi');
+  const parts: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(segment))) parts.push(`${JSON.stringify(m[1])}: ${valueExpr(m[2])}`);
+  return parts.length ? `{ ${parts.join(', ')} }` : '';
+}
+
+export const databasePatterns: StepPattern[] = [
+  {
+    name: 'db-no-row',
+    priority: 60, // above generic see-assertions
+    matcher: (step: ParsedStep) => reNoRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(new RegExp(`${TABLE}\\s+no\\s+row\\s+where\\s+(.+)$`, 'i'))!;
+      const table = m[1];
+      const filter = parseFilter(m[2]);
+      return { code: `await db.assertNoRow(${JSON.stringify(table)}, ${filter});`, comment: `DB: no row in ${table}` };
+    },
+  },
+  {
+    name: 'db-count',
+    priority: 60,
+    matcher: (step: ParsedStep) => reCount.test(step.text) && !reRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(new RegExp(`${TABLE}(?:\\s+where\\s+(.+?))?\\s+count\\s+is\\s+(${VALUE})`, 'i'))!;
+      const table = m[1];
+      const filter = m[2] ? parseFilter(m[2]) : '{}';
+      return { code: `await db.assertCount(${JSON.stringify(table)}, ${filter}, Number(${valueExpr(m[3])}));`, comment: `DB: count rows in ${table}` };
+    },
+  },
+  {
+    name: 'db-row',
+    priority: 60,
+    matcher: (step: ParsedStep) => reRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      // [table] row where <filter> [has <expected>]
+      const m = step.text.match(new RegExp(`${TABLE}\\s+row\\s+where\\s+(.+?)(?:\\s+has\\s+(.+))?$`, 'i'))!;
+      const table = m[1];
+      const filter = parseFilter(m[2]);
+      const expected = m[3] ? parseExpected(m[3]) : '';
+      const args = expected ? `${JSON.stringify(table)}, ${filter}, ${expected}` : `${JSON.stringify(table)}, ${filter}`;
+      return { code: `await db.assertRow(${args});`, comment: `DB: row in ${table}` };
+    },
+  },
+];

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

@@ -11,6 +11,7 @@ import { scrollPatterns } from './scroll-patterns';
 import { scopePatterns } from './scope-patterns';
 import { tablePatterns } from './table-patterns';
 import { capturePatterns } from './capture-patterns';
+import { databasePatterns } from './database-patterns';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -36,6 +37,7 @@ export class PatternRegistry {
     this.patterns.push(...scopePatterns);
     this.patterns.push(...tablePatterns);
     this.patterns.push(...capturePatterns);
+    this.patterns.push(...databasePatterns);
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));
@@ -165,4 +167,5 @@ export { keyboardPatterns } from './keyboard-patterns';
 export { scrollPatterns } from './scroll-patterns';
 export { scopePatterns } from './scope-patterns';
 export { tablePatterns } from './table-patterns';
+export { databasePatterns, isDbStep } from './database-patterns';
 export * from './types';

package/src/generators/test-generator/template-engine.ts

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb });
   }
 
   renderTestFile(data: {

package/src/harness/audit.ts

@@ -4,9 +4,10 @@
  *
  * The score is INTENTIONALLY weighted toward business-critical coverage/depth
  * (not breadth), so it surfaces the gaps a count-based view hides. See
- * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
+ * docs/orchestration-spec.md §5 and docs/spec/sungen_refactor_spec.md.
  */
 import * as path from 'path';
+import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
@@ -14,6 +15,10 @@ import {
 } from './sensors';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
+import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
+import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
+  negativeSideEffect, sourceBacked, crossArtifactOwnership } from './quality-gates';
+import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-ledger';
 
 export interface AuditReport {
   screen: string;
@@ -25,6 +30,15 @@ export interface AuditReport {
   balance: BalanceResult;
   duplicates: DuplicateResult;
   trace: TraceResult;
+  taxonomyMismatch: boolean;    // scenarios use IDs not in the project's test-viewpoint.md
+  downstream: DownstreamResult; // downstream screens referenced but under-covered
+  manualOracle: ManualOracleResult; // @manual scenarios lacking setup/action/oracle
+  ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
+  calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
+    axes: Record<string, number>;
+    weakest: { axis: string; value: number };
+    inflated: boolean;
+  };
   score: {
     overall: number;            // 0..10, business-weighted
     coverage: number;           // 0..1
@@ -37,15 +51,20 @@ export interface AuditReport {
   findings: string[];           // human-actionable, what the Repair loop would target
   intent: IntentProfile;        // P3 — the intent profile that drove the thresholds
   provenance: Provenance;       // D1 — sungen version + catalog hash (diagnose cross-user score gaps)
+  spec: SpecCoverageResult;     // G2 — spec-clause coverage (FR + validation-trigger matrix)
 }
 
 export function runAudit(screenDir: string, screenName: string): AuditReport {
   const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
   const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
 
+  const specPath = path.join(screenDir, 'requirements', 'spec.md');
+  const featureText = fs.existsSync(featurePath) ? fs.readFileSync(featurePath, 'utf-8') : '';
+
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
   const catalog = loadCatalog();
+  const spec = specCoverage(specPath, scenarios, featureText);
 
   const gate = viewpointGate(scenarios, viewpoints, catalog);
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
@@ -56,6 +75,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const balance = coverageBalance(scenarios);
   const duplicates = duplicateClusters(scenarios);
   const trace = traceability(scenarios, viewpoints);
+  // #1 taxonomy-match: when the project defines a viewpoint taxonomy, scenarios must use it.
+  const taxonomyMismatch = viewpoints.length > 0 && trace.withVpCode > 0 && trace.mappedRatio < 0.6;
+  // #2 downstream-scope + #4 manual-oracle
+  const downstream = downstreamScope(readText(specPath), scenarios);
+  const manualOracleResult = manualOracle(featureText);
+  const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
+  const negSideEffect = negativeSideEffect(scenarios);
+  const ownership = crossArtifactOwnership(screenDir, scenarios);
+  const unsourced = sourceBacked(scenarios, parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
 
   // Sub-scores
   const coverage = gate.coverageRatio;
@@ -100,16 +128,65 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (gate.universalGaps.length) {
     findings.push(`UNIVERSAL: missing theme(s): ${gate.universalGaps.join(', ')} (low priority reminder).`);
   }
+  for (const g of spec.triggerGaps) {
+    findings.push(`TRIGGER-UNCOVERED: spec validates "${g.constraint}"${g.code ? ` (${g.code})` : ''} on [${g.required.join(', ')}] but scenarios only exercise it on [${g.found.join(', ') || 'none'}] → add a ${g.missing.join(', ')}-trigger scenario for this constraint (don't collapse the trigger × input matrix).`);
+  }
+  for (const u of spec.uncoveredMust) {
+    findings.push(`SPEC-UNCOVERED: ${u.id} (MUST) has no covering scenario — "${u.text}" → add a scenario or tag one @spec:${u.id}.`);
+  }
+  if (taxonomyMismatch) {
+    findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
+  }
+  for (const d of downstream.underCovered) {
+    findings.push(`DOWNSTREAM-SCOPE-MISSING: "${d.route}" is a navigation target but is covered only by a page-nav assertion — cover its content/guards, or scaffold it (\`sungen add --screen ${d.slug}\`).`);
+  }
+  for (const m of manualOracleResult.insufficient.slice(0, 8)) {
+    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — a @manual scenario needs setup · action · observable expected · oracle/tool (not just a one-line note).`);
+  }
+  if (ledger.hasViewpoint && ledger.missing.length) {
+    const sample = ledger.missing.slice(0, 6).map((m) => m.id || `"${m.text}"`).join(', ');
+    findings.push(`VIEWPOINT-ITEM-MISSING: ${ledger.missing.length}/${ledger.total} atomic viewpoint items have no covering scenario (${(ledger.ratio * 100).toFixed(0)}% covered) — e.g. ${sample}. Cover each item or mark it deferred/spec-gap.`);
+  }
+  for (const n of negSideEffect.slice(0, 6)) {
+    findings.push(`NEGATIVE-SIDE-EFFECT-UNPROVEN: "${n}" — the title claims something must NOT happen but the steps don't prove the absence (assert a count / negative state, or make it @manual with an oracle).`);
+  }
+  for (const d of ownership.duplicates.slice(0, 6)) {
+    findings.push(`DUPLICATE-FLOW-OWNERSHIP: "${d.scenario}" has the same shape as a scenario in flow "${d.flow}" — keep one owner (screen-local vs flow); the other should only reference/set up.`);
+  }
+  for (const u of unsourced.slice(0, 6)) {
+    findings.push(`UNSOURCEABLE-SCENARIO: "${u}" doesn't trace to any FR / viewpoint item — link it to a source, or tag it @exploration (not part of the official suite).`);
+  }
+
+  // #8 — multi-axis calibration: a high overall must not hide a weak axis.
+  const manualCompleteness = manualOracleResult.manualTotal
+    ? 1 - manualOracleResult.insufficient.length / manualOracleResult.manualTotal : 1;
+  const axes: Record<string, number> = {
+    coverage: Math.round(coverage * 100) / 100,
+    businessDepth: Math.round(businessDepth * 100) / 100,
+    claimProof: Math.round(claim.ratio * 100) / 100,
+    specFR: spec.frTotal ? Math.round((spec.frCovered / spec.frTotal) * 100) / 100 : 1,
+    atomicLedger: Math.round(ledger.ratio * 100) / 100,
+    manualOracle: Math.round(manualCompleteness * 100) / 100,
+    taxonomy: taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100,
+  };
+  const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
+  const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };
+  const inflated = overall >= 8 && weakest.value < 0.6;
+  if (inflated) {
+    findings.push(`SCORE-INFLATED-BY-BREADTH: overall ${Math.round(overall * 10) / 10}/10 but the weakest axis "${weakest.axis}" is ${(weakest.value * 100).toFixed(0)}% — breadth is hiding a weak dimension. Raise "${weakest.axis}" before trusting the headline.`);
+  }
+  const calibration = { axes, weakest, inflated };
 
-  // Gate now spans coverage (viewpoint themes) AND depth (data-correctness).
-  // A depth 'fail' (below the intent threshold) fails the gate; 'warn' does not.
+  // Gate spans coverage (viewpoint themes), depth, claim-proof, spec-clause coverage,
+  // AND taxonomy-match (scenarios must use the project's viewpoint IDs when defined).
   const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' ? 'PASS' : 'FAIL';
+    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch ? 'PASS' : 'FAIL';
 
   return {
     screen: screenName,
     scenarioCount: scenarios.length,
-    gate, depth, claim, taxonomy, balance, duplicates, trace,
+    gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
+    taxonomyMismatch, downstream, manualOracle: manualOracleResult, ledger, calibration,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability-plan.ts

@@ -4,7 +4,7 @@
  * Classifies each scenario's execution mode + each @manual case by reason code
  * (M1–M9), maps capability-reasons to drivers, and emits the manual-reason KPI.
  * Never installs anything (that's `sungen capability add`). See
- * reports/sungen_phase2b_spec.md.
+ * docs/spec/sungen_phase2b_spec.md.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -43,6 +43,17 @@ const INFER: { code: string; re: RegExp }[] = [
   { code: 'M9', re: /\b(judgment|human|subjective|manual review)\b/i },
 ];
 
+/**
+ * Classify free text (e.g. a legacy testcase's precondition+steps+expected) into a
+ * manual-reason code, or '' when nothing matches (→ UI-automatable). Reuses the same
+ * INFER patterns as the scenario planner so legacy-ingest and the Gherkin planner agree.
+ */
+export function classifyReason(text: string): string {
+  const t = (text || '').toLowerCase();
+  for (const { code, re } of INFER) if (re.test(t)) return code;
+  return '';
+}
+
 interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason: string }
 
 /** Parse scenarios with their tags + the reason comment line above (for @manual). */

package/src/harness/catalog/drivers.yaml

@@ -1,6 +1,6 @@
 # Driver Catalog (metadata only — NO driver code is bundled here).
 # Lets Sungen RECOMMEND/RESOLVE a driver that may not be installed yet, and tells
-# `sungen capability add` which package to install. See reports/sungen_phase2a_spec.md.
+# `sungen capability add` which package to install. See docs/spec/sungen_phase2a_spec.md.
 #
 # kind: platform → the runtime/codegen adapter for a target (pick ONE per project)
 # kind: capability → an extra ability added on top of a platform (Phase 3)

package/src/harness/catalog/universal-viewpoints.yaml

@@ -5,7 +5,7 @@
 #
 # Each page-type lists must-cover themes. A theme is "covered" when the project's
 # viewpoint-overview (or generated scenarios) contains one of its keywords.
-# See docs/orchestration-spec.md §5.2 and reports/sungen_refactor_spec.md §9.
+# See docs/orchestration-spec.md §5.2 and docs/spec/sungen_refactor_spec.md §9.
 #
 # `depth:` (optional, harness-roadmap P1) marks a theme as DATA-correctness:
 #   requires: data-assertion  → scenarios on this theme must assert DATA (not just

package/src/harness/eval/skill-lint.ts

@@ -0,0 +1,87 @@
+/**
+ * Static skill-lint (Eval Harness L1) — deterministic quality checks on Sungen's OWN
+ * AI-instruction templates, so a broken / unregistered / oversized skill fails before it
+ * ships. Learned (generically) from the "static validations" tier of an agent-kit evals
+ * layer. No project data — this lints the sungen package's own templates.
+ *
+ * Design note: the checks are MAPPING-DRIVEN. `AI_RULES_FILE_MAPPING` is the source of
+ * truth for what each template installs as, so the lint uses the install target (does it
+ * end in `/SKILL.md`?) to tell a top-level skill from a sub-content fragment — instead of
+ * guessing from filenames. We deliberately do NOT enforce claude↔github body parity: the
+ * two variants are hand-tuned per platform and intentionally diverge in wording and even
+ * structure, so byte/heading equality would be pure false positives.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AI_RULES_FILE_MAPPING } from '../../orchestrator/ai-rules-updater';
+
+export interface SkillLintFinding { level: 'error' | 'warn'; file: string; rule: string; detail: string }
+export interface SkillLintResult { checked: number; findings: SkillLintFinding[]; errors: number }
+
+const LINE_BUDGET = 700; // a skill much larger than this is a context-cost smell (warn)
+const SKILL_RE = /^(claude|github)-skill-/;
+
+function stripFrontmatter(text: string): { fm: string | null; body: string } {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!m) return { fm: null, body: text };
+  return { fm: m[1], body: text.slice(m[0].length) };
+}
+
+/** Lint the AI-instruction templates in `dir` (default: the sungen source templates). */
+export function lintSkills(dir: string): SkillLintResult {
+  const findings: SkillLintFinding[] = [];
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+  const skillFiles = files.filter((f) => SKILL_RE.test(f));
+
+  // mapping: template file -> install target (source of truth for "is this a top-level skill")
+  const target = new Map<string, string>(AI_RULES_FILE_MAPPING.map(([tpl, dst]) => [tpl, dst]));
+  const isTopLevelSkill = (f: string) => (target.get(f) || '').endsWith('/SKILL.md');
+
+  // 1) registration integrity (bidirectional) — the highest-value check:
+  //    a skill file missing from the mapping never installs; a mapping to a missing file
+  //    ships a broken/empty skill.
+  for (const f of skillFiles) {
+    if (!target.has(f)) findings.push({ level: 'error', file: f, rule: 'unregistered', detail: 'skill template not in AI_RULES_FILE_MAPPING (it would never be installed)' });
+  }
+  for (const [tpl] of AI_RULES_FILE_MAPPING) {
+    if (!fs.existsSync(path.join(dir, tpl))) findings.push({ level: 'error', file: tpl, rule: 'mapped-missing', detail: 'AI_RULES_FILE_MAPPING points to a template that does not exist' });
+  }
+
+  // 2) frontmatter (name + description) — ONLY for top-level skills (SKILL.md targets).
+  //    Sub-content fragments (mode-*.md, group-*.md) are loaded by their parent router
+  //    and legitimately carry no frontmatter.
+  for (const f of skillFiles) {
+    if (!isTopLevelSkill(f)) continue;
+    const text = fs.readFileSync(path.join(dir, f), 'utf8');
+    const { fm } = stripFrontmatter(text);
+    if (!fm) { findings.push({ level: 'error', file: f, rule: 'frontmatter', detail: 'top-level skill (SKILL.md) is missing --- frontmatter --- (Claude/Copilot will not load it)' }); continue; }
+    if (!/\bname\s*:/.test(fm)) findings.push({ level: 'error', file: f, rule: 'frontmatter-name', detail: 'no `name:` in frontmatter' });
+    if (!/\bdescription\s*:/.test(fm)) findings.push({ level: 'error', file: f, rule: 'frontmatter-description', detail: 'no `description:` in frontmatter' });
+  }
+
+  // 3) line budget — context-cost smell (advisory).
+  for (const f of skillFiles) {
+    const lines = fs.readFileSync(path.join(dir, f), 'utf8').split('\n').length;
+    if (lines > LINE_BUDGET) findings.push({ level: 'warn', file: f, rule: 'line-budget', detail: `${lines} lines > ${LINE_BUDGET} (context-cost smell)` });
+  }
+
+  // 4) variant PRESENCE (not body equality) — every top-level skill should ship for both
+  //    platforms. Catches "added a Claude skill but forgot the Copilot variant". Advisory.
+  const skillName = (dst: string) => { const m = dst.match(/\/(sungen-[^/]+)\/SKILL\.md$/); return m ? m[1] : null; };
+  const claudeSkills = new Set<string>(), githubSkills = new Set<string>();
+  for (const f of skillFiles) {
+    if (!isTopLevelSkill(f)) continue;
+    const name = skillName(target.get(f)!); if (!name) continue;
+    (f.startsWith('claude-') ? claudeSkills : githubSkills).add(name);
+  }
+  for (const n of claudeSkills) if (!githubSkills.has(n)) findings.push({ level: 'warn', file: `claude .../${n}/SKILL.md`, rule: 'variant-missing', detail: `Claude skill "${n}" has no GitHub (Copilot) variant` });
+  for (const n of githubSkills) if (!claudeSkills.has(n)) findings.push({ level: 'warn', file: `github .../${n}/SKILL.md`, rule: 'variant-missing', detail: `GitHub skill "${n}" has no Claude variant` });
+
+  return { checked: skillFiles.length, findings, errors: findings.filter((f) => f.level === 'error').length };
+}
+
+/** Default templates dir, resolved relative to this module (works from src via tsx and dist). */
+export function defaultSkillDir(): string {
+  // src/harness/eval → src/orchestrator/...  |  dist/harness/eval → dist/orchestrator/...
+  return path.resolve(__dirname, '..', '..', 'orchestrator', 'templates', 'ai-instructions');
+}

package/src/harness/flow-plan.ts

@@ -5,7 +5,7 @@
  * leg's SELECTOR READINESS + capability, folds in the manual-reason taxonomy
  * (capability-plan) and the run-test contract (flow-check), and emits a run-test
  * PLAN. Automates the manual diagnosis done while healing cart-and-filter.
- * See reports/sungen_phase2c_spec.md.
+ * See docs/spec/sungen_phase2c_spec.md.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/src/harness/parse.ts

@@ -29,6 +29,18 @@ export interface ScenarioInfo {
   stepSkeleton: string;       // normalized steps for duplicate clustering
   haystack: string;           // lowercase name + steps text (for keyword coverage)
   stepsText: string;          // lowercase steps ONLY (name excluded) — for claim-proof
+  vpId?: string;              // raw leading ID token of the title (project's scheme: VP0-001, MS-HP-001, VP-LIST-001)
+}
+
+/** Format-tolerant: is this token an ID (project's scheme), not a prose word?
+ * Accepts VP0, VP0-001, MS-HP-001, TV-01, VP-LIST-001 — requires a digit + uppercase start. */
+export function isIdLike(s: string): boolean {
+  return /^[A-Z][A-Za-z0-9.-]*$/.test(s) && /\d/.test(s) && s.length >= 3;
+}
+
+/** The ID minus its trailing -NNN sequence number (VP0-001 → VP0, MS-HP-001 → MS-HP). */
+export function idPrefix(id: string): string {
+  return id.replace(/[-.]\d{1,4}$/, '');
 }
 
 // ---------- test-viewpoint.md ----------
@@ -50,7 +62,7 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
       const cells = line.split('|').map((c) => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1);
       if (cells.length >= 3) {
         const id = cells[0];
-        if (/^VP[-A-Z0-9]/i.test(id) && !/^vp$/i.test(id) && !/^-+$/.test(cells[1])) {
+        if (isIdLike(id) && !/^-+$/.test(cells[1])) {
           const pr = /high/i.test(cells[1]) ? 'High' : /medium/i.test(cells[1]) ? 'Medium' : /low/i.test(cells[1]) ? 'Low' : 'Unknown';
           entries.set(id.toUpperCase(), { id: id.toUpperCase(), priority: pr as any, reason: cells[2] });
         }
@@ -66,8 +78,8 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
     if (g) { group = (g[1][0].toUpperCase() + g[1].slice(1).toLowerCase()) as any; continue; }
     if (/^##\s/.test(line)) { group = undefined; }
     if (group) {
-      const m = line.match(/^-\s+(VP[-A-Z0-9]+)/i);
-      if (m) {
+      const m = line.match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
+      if (m && isIdLike(m[1])) {
         const id = m[1].toUpperCase();
         const existing = entries.get(id);
         if (existing) existing.group = group;
@@ -92,6 +104,9 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const codeMatch = sc.name.match(/\bVP-([A-Z]+)-\d+/i);
   const vpCode = codeMatch ? codeMatch[0].toUpperCase() : undefined;
   const category = codeMatch ? codeMatch[1].toUpperCase() : undefined;
+  // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
+  const leadMatch = sc.name.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/);
+  const vpId = leadMatch && isIdLike(leadMatch[1]) ? leadMatch[1].toUpperCase() : undefined;
 
   // Then-phase detection (And/But inherit previous primary keyword)
   let last = 'Given';
@@ -136,6 +151,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     stepSkeleton: skeletonParts.join(' | '),
     haystack: textParts.join(' ').toLowerCase(),
     stepsText: stepTextParts.join(' ').toLowerCase(),
+    vpId,
   };
 }