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

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

@@ -23,11 +23,14 @@ export interface TestFileData {
   featureFileName?: string; // Feature file name for TestDataLoader.load()
   isParallel?: boolean; // @parallel tag: fresh page per test (opt-out from serial default)
   flowMode?: boolean;   // flow: cross-screen → longer per-test timeout (bug #243)
+  platform?: string;    // mobile @platform:* value (mobile|android|ios) → `// sungen:platform=` marker for wdio per-OS routing
   cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
   backgroundSteps?: Array<{ comment?: string; code: string }>; // Raw background steps for serial beforeAll
   scenarios: string[];
   authGroups?: AuthGroup[]; // Grouped by auth role for nested describes
   singleAuthRole?: string;  // Auth role when all scenarios share the same role
+  appPackage?: string;      // Mobile (appium): Android package from the feature `Path:` → drives the per-scenario relaunch reset (beforeEach terminate+activate)
+  iosBundleId?: string;     // Mobile (appium): iOS bundle id from a dual-id `Path: <pkg>/<activity> | <bundleId>`
 }
 
 export interface ScenarioData {

package/src/generators/test-generator/adapters/appium/templates/steps/actions/scroll-action.hbs

@@ -1,10 +1,13 @@
 if (driver.isIOS) {
-  // iOS (XCUITest) has no UiScrollable. Swipe the screen up in bounded steps until the target is on
-  // screen (a below-fold element isn't in the XCUITest tree until scrolled, so getElementRect/tap on
-  // it would otherwise fail). Bounded so a missing target can't loop forever.
+  // iOS (XCUITest) has no UiScrollable. Swipe up in bounded steps until the target is on screen (a
+  // below-fold element isn't in the XCUITest tree until scrolled). A settle `pause` between swipes
+  // paces the loop so it doesn't flood `execute/sync` (rapid back-to-back swipes are a common source
+  // of flakiness; issue #394). Bounded (cap 10) so a missing target can't loop forever. NOTE: this
+  // does NOT fix an app that crashes mid-scroll on its own — that's an app-stability issue, not codegen.
   const __t = $({{> appium-selector-expr}});
-  for (let __i = 0; __i < 12 && !(await __t.isDisplayed().catch(() => false)); __i++) {
+  for (let __i = 0; __i < 10 && !(await __t.isDisplayed().catch(() => false)); __i++) {
     await driver.execute('mobile: swipe', { direction: 'up' });
+    await driver.pause(400); // settle: let the app render between swipes (don't flood execute/sync)
   }
 } else {
 {{#if (eq strategy 'accessibility-id')}}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/toggle-action.hbs

@@ -1,3 +1,20 @@
-{{!-- A switch/toggle flips state on tap (mirrors the web toggle pattern: unconditional click).
-      Use `check`/`uncheck` instead when you need to drive it to a specific on/off state idempotently. --}}
-await {{> locator}}.click();
+{{!-- A switch/toggle flips state on tap. On Flutter (and many native layouts) the row's a11y node
+      spans the FULL width and merges the label with the switch, so a centre .click() lands on the
+      LABEL and does NOT flip the control — only the trailing visual switch toggles. So tap the
+      RIGHT portion (vertical centre) via getElementRect (W3C-standard → Android + iOS). Falls back to
+      a plain centre click when the rect is unavailable. Use `check`/`uncheck` to drive a specific
+      on/off state idempotently instead. --}}
+await (async () => {
+  const e = await {{> locator}};
+  const r = await driver.getElementRect(e.elementId);
+  if (r && r.width) {
+    // Trailing switch: ~right edge, vertical centre. The inset clears the label/track padding while
+    // staying on the switch even on a full-width composite row.
+    const x = Math.round(r.x + r.width - Math.max(48, r.width * 0.08));
+    const y = Math.round(r.y + r.height / 2);
+    if (driver.isIOS) { await driver.execute('mobile: tap', { x, y }); }
+    else { await driver.execute('mobile: clickGesture', { x, y }); }
+  } else {
+    await e.click();
+  }
+})();

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/checked-assertion.hbs

@@ -1 +1,4 @@
-await expect({{> locator}}).toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/not-checked-assertion.hbs

@@ -1 +1,4 @@
-await expect({{> locator}}).not.toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).not.toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -152,6 +152,9 @@ describe('{{featureName}}', () => {
     const __APP_PKG__ = __resolveAppId();
     try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
     await driver.activateApp(__APP_PKG__);
+    // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
+    // app relaunch above resets in-app state, but device orientation is OS-level and persists.
+    try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
     // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
     // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
     // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd

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

@@ -74,7 +74,7 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
  * Any tag not recognized by sungen as functional → pass through.
  */
 const FUNCTIONAL_TAG_PREFIXES = [
-  '@parallel', '@cleanup:', '@auth:', '@manual', '@no-auth',
+  '@parallel', '@serial', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
   '@flow', '@cases:', '@deferred:', '@owned-by:',
 ];
@@ -173,8 +173,10 @@ function getEffectiveAuthRole(
  * @manual at scenario level → skip that scenario
  */
 function isManual(tags: string[]): boolean {
-  // @deferred:flow is owned by a flow → not automated on this screen, so it skips like @manual (H6).
-  return tags.some(tag => tag === '@manual' || tag === '@deferred:flow');
+  // Recognize bare `@manual` AND the reason-coded `@manual:Mx` convention (what create-test emits) —
+  // must match harness/parse.ts + capability-plan.ts, else an `@manual:Mx` scenario is wrongly
+  // GENERATED (and run) instead of skipped. @deferred:flow is owned by a flow → also skips here (H6).
+  return tags.some(tag => /^@manual\b/i.test(tag) || tag === '@deferred:flow');
 }
 
 /**
@@ -271,10 +273,13 @@ export class CodeGenerator {
     const depth = outputSubdir ? outputSubdir.split('/').length : 0;
     const basePath = depth > 0 ? Array(depth).fill('..').join('/') : '..';
 
-    // Serial + @cleanup tags → need cleanupPage import from base
-    const isParallelFeature = (feature.tags || []).includes('@parallel');
+    // Isolation model: per-scenario fresh page is the DEFAULT (no cascade — one failure can't skip
+    // the rest). `@serial` opts INTO the shared-page serial suite (a genuinely stateful, ordered
+    // sequence). `@parallel` is a back-compat alias of the default (isolated). See #414.
+    const isSerialFeature = (feature.tags || []).includes('@serial');
+    const isParallelFeature = !isSerialFeature;          // isolated unless explicitly @serial
     const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
-    const needsCleanupImport = !isParallelFeature && hasCleanupTags;
+    const needsCleanupImport = isSerialFeature && hasCleanupTags;  // afterEach cleanup only on the shared-page path
 
     // Active capabilities for this feature (registry-driven): the default UI + any whose annotation
     // tags appear (@query) or whose detectsStep matches (declarative DB steps). Each active
@@ -480,14 +485,23 @@ export class CodeGenerator {
       }
     }
 
-    // Detect @parallel opt-out (default is serial)
-    const isParallel = (feature.tags || []).includes('@parallel');
+    // Per-scenario ISOLATION is the default (test.describe + a fresh page each scenario → a failure
+    // never skip-cascades). `@serial` opts into the shared-page serial suite for a stateful sequence.
+    const isParallel = !(feature.tags || []).includes('@serial');
 
     // Generate background if exists
     let background: string | undefined;
     let backgroundSteps: Array<{ comment?: string; code: string }> | undefined;
     if (feature.background) {
-      if (isParallel) {
+      // Mobile (appium) ALWAYS inlines Background via `backgroundSteps`: the test-file template emits a
+      // relaunch-per-scenario beforeEach and renders Background INSIDE it (it has no separate `background`
+      // beforeEach slot), and that per-scenario relaunch already gives @parallel its reset semantics.
+      // Routing a @parallel *mobile* feature to generateBeforeEach() computes the nav steps into
+      // `background`, which the mobile template then ignores → the Background nav (e.g. `tap [Settings]
+      // tab`) is silently dropped and every scenario runs on the launcher. So branch on isParallel only
+      // for web; for appium always use generateBackgroundSteps().
+      const isMobile = this.adapter.frameworkName === 'appium';
+      if (isParallel && !isMobile) {
         background = await this.generateBeforeEach(feature.background);
       } else {
         backgroundSteps = await this.generateBackgroundSteps(feature.background);
@@ -597,6 +611,29 @@ export class CodeGenerator {
     const cleanup = extractCleanupFlags(feature.tags || []);
     const screenshotOnFailure = hasScreenshotOnFailure(feature.tags || []);
 
+    // Mobile: the @platform:* value (mobile|android|ios). Emitted as a `// sungen:platform=` marker
+    // so wdio.conf routes the spec per OS — android/ios = that OS only, mobile (default) = both.
+    // Only the appium adapter consumes it; web features have no @platform tag → undefined → no marker.
+    const platform = this.adapter.frameworkName === 'appium'
+      ? (feature.tags || []).find(t => t.startsWith('@platform:'))?.split(':')[1]
+      : undefined;
+
+    // Mobile: parse the feature `Path:` (the app entry) into the app id(s) the per-scenario relaunch
+    // reset needs. Dual-id form: `<androidPkg>[/<activity>] | <iosBundleId>` — appPackage is the Android
+    // package (activity stripped, it isn't needed for terminateApp/activateApp); iosBundleId is the part
+    // after `|` when present. Without these the test-file template's `{{#if appPackage}}` stays false and
+    // the beforeEach (terminate+activate) reset is never emitted → nav scenarios cascade-fail.
+    let appPackage: string | undefined;
+    let iosBundleId: string | undefined;
+    if (this.adapter.frameworkName === 'appium' && feature.path) {
+      const [androidPart, iosPart] = feature.path.split('|').map(s => s.trim());
+      // Guard against a web-style URL Path (`/login`): only treat as a package when it isn't a route.
+      if (androidPart && !androidPart.startsWith('/')) {
+        appPackage = androidPart.split('/')[0].trim() || undefined;
+      }
+      if (iosPart) iosBundleId = iosPart;
+    }
+
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
       imports: '', // Not used in template as it's rendered separately
@@ -613,11 +650,14 @@ export class CodeGenerator {
       featureFileName: featureName,
       isParallel,
       flowMode: isFlowFeature,
+      platform,
       cleanup,
       backgroundSteps,
       scenarios: needsGrouping ? [] : scenarios,
       authGroups: needsGrouping ? authGroups : undefined,
       singleAuthRole,
+      appPackage,
+      iosBundleId,
     });
   }
 

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

@@ -21,9 +21,19 @@ export class TemplateEngine {
       return text.split('\n').map(line => indentation + line).join('\n');
     });
 
+    // Escape a raw string for embedding inside a single-quoted JS string literal. Every caller wraps
+    // the result in '…' (selector values, attribute values, scope), so a value containing a newline,
+    // backslash, or quote must be escaped or the generated spec is a syntax error (e.g. a Flutter
+    // composite content-desc like "Quick Convert\nSelect File\n…" used as an accessibility-id).
+    // Order matters: backslash first, then the rest.
     Handlebars.registerHelper('escapeQuotes', function(text: string) {
       if (text == null) return '';
-      return String(text).replace(/'/g, "\\'");
+      return String(text)
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
     });
 
     Handlebars.registerHelper('escapeRegex', function(text: string) {
@@ -259,11 +269,14 @@ export class TemplateEngine {
     screenName?: string;
     featureFileName?: string;
     isParallel?: boolean;
+    platform?: string;
     cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
     backgroundSteps?: Array<{ comment?: string; code: string }>;
     scenarios: string[];
     authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
     singleAuthRole?: string;
+    appPackage?: string;
+    iosBundleId?: string;
   }): string {
     return this.render('test-file', data);
   }

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -20,6 +20,12 @@ interface SelectorEntry {
   scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
   match?: 'exact' | 'partial';  // For getByText matching (default: partial)
 
+  // === Mobile per-platform variant (issue #392) ===
+  // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
+  // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
+  android?: SelectorEntry;
+  ios?: SelectorEntry;
+
   // === v2: Complex Elements ===
   variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
   trigger?: string;       // Visible button that triggers hidden file input
@@ -52,8 +58,17 @@ interface LegacySelectorFile {
 }
 
 export interface ResolvedSelector {
-  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator';
+  // Web (Playwright) strategies + mobile (Appium) strategies. Mobile types pass through from
+  // selectors.yaml so the appium adapter's `appium-selector` switch can emit the right WDIO selector
+  // (`~` / raw xpath / `android=` / `-ios predicate string:` / `id=`). See issue #392.
+  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
+    | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
+  // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
+  // right native selector per OS. Each side carries its own strategy+value (issue #392).
+  androidSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
+  iosSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
   role?: string;        // For role-based selectors (e.g., 'button', 'link')
   name?: string;        // For accessible name in role selectors
   locator?: string;     // CSS locator for fallback
@@ -472,6 +487,25 @@ export class SelectorResolver {
       return { ...resolved, ...v2Fields };
     };
 
+    // Mobile per-platform variant (issue #392): `{ android: {...}, ios: {...} }`. Resolve each side
+    // and emit androidSelector/iosSelector so the appium codegen renders `driver.isIOS ? ios : android`.
+    // The base strategy/value falls back to whichever side is present (a missing side falls back to it).
+    // `nth`/`scope` are shared (top-level) — they cannot diverge per-OS (the codegen ternary swaps only
+    // strategy+value); a case needing per-OS nth/scope is a sub-feature, not a variant.
+    if (entry.android || entry.ios) {
+      const av = entry.android ? this.resolveFromEntry(entry.android, originalLabel) : undefined;
+      const iv = entry.ios ? this.resolveFromEntry(entry.ios, originalLabel) : undefined;
+      const base = (av || iv) as ResolvedSelector;
+      return withExtras({
+        strategy: base.strategy,
+        value: base.value,
+        name: base.name,
+        nth,
+        ...(av ? { androidSelector: { strategy: av.strategy, value: av.value, name: av.name } } : {}),
+        ...(iv ? { iosSelector: { strategy: iv.strategy, value: iv.value, name: iv.name } } : {}),
+      });
+    }
+
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
@@ -536,6 +570,22 @@ export class SelectorResolver {
           exact,
         });
 
+      // Mobile (Appium) native strategies — pass through unchanged; the appium adapter's
+      // `appium-selector` switch renders the right WDIO selector (`~` / raw xpath / `android=` /
+      // `-ios predicate string:` / `id=`). On web these types never appear. See issue #392.
+      case 'accessibility-id':
+      case 'xpath':
+      case 'android-uiautomator':
+      case 'ios-predicate':
+      case 'id':
+        return withExtras({
+          strategy: type,
+          value,
+          name,
+          nth,
+          exact,
+        });
+
       default:
         // Fallback to placeholder
         return withExtras({

package/src/harness/audit.ts

@@ -22,7 +22,7 @@ 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, isolationRisk } from './quality-gates';
+  negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
 import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-ledger';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
@@ -146,7 +146,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const capGate = scoringCap?.gateProvider as
     ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
   const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile');
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
@@ -244,6 +244,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (isoRisk) {
     findings.push('ISOLATION-RISK: this @parallel flow mutates the cart but has no per-scenario isolation → cart/count/quantity asserts can go flaky when scenarios share state. Add `@cleanup:cart` (or `@isolate`, or a `Given User has an empty cart` background) so each scenario starts clean.');
   }
+  // #414 — serial-cascade masking: an @serial suite of independent (re-navigating) scenarios hides
+  // failures, because Playwright's describe.serial SKIPS everything after the first red. Isolation is
+  // the default, so this only fires when @serial was added to a suite that didn't need it.
+  const cascadeN = serialCascadeRisk(featureText, scenarios.length);
+  if (cascadeN) {
+    findings.push(`SERIAL-CASCADE-RISK: this \`@serial\` suite has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
+  }
   if (flowDepth.stateful && flowDepth.missing.length) {
     const how: Record<string, string> = {
       'count-proof': 'assert the cart ROW COUNT / item QUANTITY (e.g. `... table with {{two_rows}}`, `Quantity column with {{qty}}`), not just the row presence',

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

@@ -91,6 +91,21 @@ page_types:
           keywords: ["success message", "saved", "created", "confirmation"]
           template: "User see [Success] message with {{success_text}}"
 
+  # Mobile launcher / home screen (Appium). Display + navigation only — no web form/validation.
+  # A `mobile-*` candidate (considered ONLY for mobile targets; never for web). Keywords are
+  # launcher-DISTINCTIVE (a tab-bar landing screen) and deliberately exclude generic tokens like
+  # "tab"/"navigation"/"home" that a mobile commerce/list screen also carries — so such a screen
+  # still selects ecommerce-list, not mobile-home. Both themes are presence/navigation (no `depth:`)
+  # — seeing the content and leaving Home (a destination marker OR the Home-only anchor going
+  # `is hidden`) IS the assertion; no data-assertion is forced.
+  mobile-home:
+    detect_keywords: ["bottom navigation", launcher, greeting, "home screen", "launcher screen"]
+    must_cover:
+      - theme: content-visibility
+        keywords: [displayed, render, loads, exposes, shown, visible]
+      - theme: navigation-correctness
+        keywords: [tap, navigate, "leaves home", "is hidden", opens, navigation]
+
   auth:
     detect_keywords: [login, logout, password, signin, "sign in", credential]
     must_cover:

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

@@ -1,87 +1,98 @@
 /**
  * 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.
+ * single-source AI templates (`templates/ai-src/`), so a broken skill fails before it ships.
  *
- * 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.
+ * Source of truth is now `ai-src/` (one file per skill/command, cap-fenced for per-assistant
+ * deltas) — NOT the retired per-assistant `ai-instructions/` duplicates. Checks:
+ *   - skills:   `ai-src/skills/<dir>/SKILL.md` has `name:` + `description:` frontmatter
+ *   - commands: `ai-src/commands/<name>.md` has `description:` frontmatter
+ *   - cap-fence validity: every {{#cap}}/{{^cap}} uses a known tag and is closed
+ *   - line budget: context-cost smell (advisory)
+ * Aux fragments (viewpoint group-*.md, capture mode files) load via a parent and need no
+ * frontmatter, so only `SKILL.md` is frontmatter-checked.
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AI_RULES_FILE_MAPPING } from '../../orchestrator/ai-rules-updater';
+import { stripCaps, VALID_CAPS } from '../../orchestrator/ai-skills/cap-stripper';
 
 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-/;
+const LINE_BUDGET = 700;
 
-function stripFrontmatter(text: string): { fm: string | null; body: string } {
+function frontmatter(text: string): string | null {
   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) };
+  return m ? m[1] : null;
 }
 
-/** Lint the AI-instruction templates in `dir` (default: the sungen source templates). */
-export function lintSkills(dir: string): SkillLintResult {
+/** Lint the single-source templates under `srcRoot` (the `ai-src` dir). */
+export function lintSkills(srcRoot: 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));
+  let checked = 0;
 
-  // 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');
+  const checkCaps = (rel: string, text: string) => {
+    try { for (const cap of VALID_CAPS) stripCaps(text, [cap], rel); stripCaps(text, [], rel); }
+    catch (e) { findings.push({ level: 'error', file: rel, rule: 'cap-fence', detail: String((e as Error).message) }); }
+  };
+  const lineBudget = (rel: string, text: string) => {
+    const n = text.split('\n').length;
+    if (n > LINE_BUDGET) findings.push({ level: 'warn', file: rel, rule: 'line-budget', detail: `${n} lines > ${LINE_BUDGET} (context-cost smell)` });
+  };
 
-  // 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' });
+  // Skills
+  const skillsDir = path.join(srcRoot, 'skills');
+  for (const dir of fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir) : []) {
+    const dp = path.join(skillsDir, dir);
+    if (!fs.statSync(dp).isDirectory()) continue;
+    for (const file of fs.readdirSync(dp)) {
+      if (!file.endsWith('.md')) continue;
+      const rel = `skills/${dir}/${file}`;
+      const text = fs.readFileSync(path.join(dp, file), 'utf8');
+      checkCaps(rel, text);
+      lineBudget(rel, text);
+      if (file === 'SKILL.md') {
+        checked++;
+        const fm = frontmatter(text);
+        if (!fm) { findings.push({ level: 'error', file: rel, rule: 'frontmatter', detail: 'SKILL.md missing --- frontmatter ---' }); continue; }
+        if (!/\bname\s*:/.test(fm)) findings.push({ level: 'error', file: rel, rule: 'frontmatter-name', detail: 'no `name:` in frontmatter' });
+        if (!/\bdescription\s*:/.test(fm)) findings.push({ level: 'error', file: rel, 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)` });
+  // Agents (Claude-only sub-agents)
+  const agentsDir = path.join(srcRoot, 'agents');
+  for (const file of fs.existsSync(agentsDir) ? fs.readdirSync(agentsDir) : []) {
+    if (!file.endsWith('.md')) continue;
+    const rel = `agents/${file}`;
+    const text = fs.readFileSync(path.join(agentsDir, file), 'utf8');
+    checked++;
+    checkCaps(rel, text);
+    lineBudget(rel, text);
+    const fm = frontmatter(text);
+    if (!fm) { findings.push({ level: 'error', file: rel, rule: 'frontmatter', detail: 'agent missing --- frontmatter ---' }); continue; }
+    if (!/\bname\s*:/.test(fm)) findings.push({ level: 'error', file: rel, rule: 'frontmatter-name', detail: 'no `name:` in frontmatter' });
+    if (!/\bdescription\s*:/.test(fm)) findings.push({ level: 'error', file: rel, rule: 'frontmatter-description', detail: 'no `description:` in frontmatter' });
   }
 
-  // 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);
+  // Commands
+  const cmdsDir = path.join(srcRoot, 'commands');
+  for (const file of fs.existsSync(cmdsDir) ? fs.readdirSync(cmdsDir) : []) {
+    if (!file.endsWith('.md')) continue;
+    const rel = `commands/${file}`;
+    const text = fs.readFileSync(path.join(cmdsDir, file), 'utf8');
+    checked++;
+    checkCaps(rel, text);
+    lineBudget(rel, text);
+    const fm = frontmatter(text);
+    if (!fm) { findings.push({ level: 'error', file: rel, rule: 'frontmatter', detail: 'command missing --- frontmatter ---' }); continue; }
+    if (!/\bdescription\s*:/.test(fm)) findings.push({ level: 'error', file: rel, rule: 'frontmatter-description', detail: 'no `description:` in frontmatter' });
   }
-  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 };
+  return { checked, findings, errors: findings.filter((f) => f.level === 'error').length };
 }
 
-/** Default templates dir, resolved relative to this module (works from src via tsx and dist). */
+/** Default source 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');
+  return path.resolve(__dirname, '..', '..', 'orchestrator', 'templates', 'ai-src');
 }