@pigcloud/skills 1.0.11 → 1.1.2

package/bin/rules-loader.js

@@ -1,484 +1,271 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-
-const PACKAGE_ROOT = path.join(__dirname, '..');
-const RULES_ROOT = path.join(PACKAGE_ROOT, 'rules');
-const REGISTRY_PATH = path.join(RULES_ROOT, 'bundles.json');
-const SKILL_PROFILE_MAP_PATH = path.join(RULES_ROOT, 'skill-profile-map.json');
-const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
-const CORE_BUNDLE_NAME = 'core';
-const CORE_PROFILE_NAME = 'core';
-const REVIEW_BUNDLE_NAME = 'review';
-
-function readRegistry() {
-  return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));
-}
-
-function readSkillProfileMap() {
-  return JSON.parse(fs.readFileSync(SKILL_PROFILE_MAP_PATH, 'utf8'));
-}
-
-function readSkillRuleProfile(skillName) {
-  const skillFile = path.join(SKILLS_ROOT, skillName, 'SKILL.md');
-  if (!fs.existsSync(skillFile)) {
-    return null;
-  }
-
-  const content = fs.readFileSync(skillFile, 'utf8');
-  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!frontmatterMatch) {
-    return null;
-  }
-
-  const profileMatch = frontmatterMatch[1].match(/^rule_profile:\s*(.+)$/m);
-  return profileMatch ? profileMatch[1].trim() : null;
-}
-
-function readSkillRuleBundle(skillName) {
-  const skillProfileMap = readSkillProfileMap();
-  const mapped = skillProfileMap[skillName];
-  if (mapped && mapped.bundle) {
-    return mapped.bundle;
-  }
-
-  const profile = readSkillRuleProfile(skillName);
-  if (!profile || profile === CORE_PROFILE_NAME) {
-    return CORE_BUNDLE_NAME;
-  }
-
-  return findBundleByProfile(readRegistry(), profile);
-}
-
-function combineLayers(layers, meta = {}) {
-  const flattenedFiles = [];
-  const seen = new Set();
-
-  for (const layer of layers) {
-    for (const file of layer.files || []) {
-      if (seen.has(file)) continue;
-      seen.add(file);
-      flattenedFiles.push(file);
-    }
-  }
-
-  const primary = meta.baseLayer || layers[layers.length - 1] || layers[0] || null;
-  return {
-    bundle: meta.bundle || (primary ? primary.bundle : CORE_BUNDLE_NAME),
-    profile: meta.profile || (primary ? primary.profile : null),
-    skill: meta.skill || null,
-    source: meta.source || 'workspace detection',
-    entry: meta.entry || (primary ? primary.entry : 'core/index.md'),
-    files: flattenedFiles,
-    description: primary ? primary.description : 'Baseline rules',
-    layers
-  };
-}
-
-function getLayer(registry, bundleName, profileName = '') {
-  const bundle = registry[bundleName];
-  if (!bundle) return null;
-
-  const profile = profileName && bundle.profiles && bundle.profiles[profileName]
-    ? profileName
-    : (bundle.profiles && bundle.profiles[CORE_PROFILE_NAME] ? CORE_PROFILE_NAME : '');
-  const selected = profile ? bundle.profiles[profile] : bundle;
-
-  if (!selected) return null;
-
-  return {
-    bundle: bundleName,
-    profile: profile || null,
-    entry: selected.entry,
-    files: selected.files,
-    description: selected.description || bundle.description
-  };
-}
-
-function listSkillDirectories() {
-  if (!fs.existsSync(SKILLS_ROOT)) {
-    return [];
-  }
-
-  return fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && entry.name !== 'references')
-    .map((entry) => entry.name)
-    .sort();
-}
-
-function shouldValidateSkillProfiles() {
-  const skip = String(process.env.PIG_SKILLS_SKIP_RULE_PROFILE_VALIDATION || '').trim().toLowerCase();
-  if (['1', 'true', 'yes'].includes(skip)) {
-    return false;
-  }
-
-  const explicit = String(process.env.PIG_SKILLS_VALIDATE_RULE_PROFILES || '').trim().toLowerCase();
-  if (['1', 'true', 'yes'].includes(explicit)) {
-    return true;
-  }
-
-  return process.env.NODE_ENV !== 'production';
-}
-
-function validateSkillProfileConsistency() {
-  const registry = readRegistry();
-  const skillProfileMap = readSkillProfileMap();
-  const skillDirs = listSkillDirectories();
-  const issues = [];
-
-  const mappedSkills = Object.keys(skillProfileMap).sort();
-  for (const skillName of skillDirs) {
-    if (!skillProfileMap[skillName]) {
-      issues.push(`Missing mapping for skill: ${skillName}`);
-      continue;
-    }
-
-    const declaredProfile = readSkillRuleProfile(skillName);
-    if (!declaredProfile) {
-      issues.push(`Missing rule_profile declaration for skill: ${skillName}`);
-      continue;
-    }
-
-    const mappedProfile = skillProfileMap[skillName].profile || CORE_PROFILE_NAME;
-    if (declaredProfile !== mappedProfile) {
-      issues.push(`Profile mismatch for ${skillName}: skill=${declaredProfile}, map=${mappedProfile}`);
-    }
-
-    const mappedBundle = skillProfileMap[skillName].bundle || CORE_BUNDLE_NAME;
-    const bundle = registry[mappedBundle];
-    if (!bundle) {
-      issues.push(`Unknown bundle mapped for ${skillName}: ${mappedBundle}`);
-      continue;
-    }
-
-    if (!bundle.profiles || !bundle.profiles[mappedProfile]) {
-      issues.push(`Unknown profile mapped for ${skillName}: ${mappedBundle}/${mappedProfile}`);
-    }
-  }
-
-  for (const mappedSkill of mappedSkills) {
-    if (!skillDirs.includes(mappedSkill)) {
-      issues.push(`Mapping exists for missing skill directory: ${mappedSkill}`);
-    }
-  }
-
-  if (issues.length > 0) {
-    const error = new Error(`Rule profile consistency check failed:\n- ${issues.join('\n- ')}`);
-    error.issues = issues;
-    throw error;
-  }
-
-  return {
-    skillCount: skillDirs.length,
-    mappedSkillCount: mappedSkills.length
-  };
-}
-
-function findBundleByProfile(registry, profileName) {
-  if (!profileName || profileName === CORE_PROFILE_NAME) {
-    return registry[CORE_BUNDLE_NAME] ? CORE_BUNDLE_NAME : Object.keys(registry)[0] || CORE_BUNDLE_NAME;
-  }
-
-  for (const [bundleName, bundleConfig] of Object.entries(registry)) {
-    if (bundleConfig && bundleConfig.profiles && bundleConfig.profiles[profileName]) {
-      return bundleName;
-    }
-  }
-
-  return null;
-}
-
-function existsInRoot(cwd, relativePath) {
-  return fs.existsSync(path.join(cwd, relativePath));
-}
-
-function normalizeChangedFiles(changedFilesInput) {
-  if (!changedFilesInput) {
-    return [];
-  }
-
-  const items = Array.isArray(changedFilesInput)
-    ? changedFilesInput
-    : String(changedFilesInput)
-        .split(/[\r\n,]+/)
-        .map((item) => item.trim());
-
-  return [...new Set(items.filter(Boolean))];
-}
-
-function hasChangedFile(changedFiles, matcher) {
-  return changedFiles.some((filePath) => matcher(filePath.replace(/\\/g, '/')));
-}
-
-function hasCodingSignals(cwd) {
-  const packageJsonPath = path.join(cwd, 'package.json');
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-      if (pkg && typeof pkg === 'object') {
-        const hasScripts = pkg.scripts && typeof pkg.scripts === 'object' && Object.keys(pkg.scripts).length > 0;
-        const hasDeps = (pkg.dependencies && Object.keys(pkg.dependencies).length > 0)
-          || (pkg.devDependencies && Object.keys(pkg.devDependencies).length > 0);
-        if (hasScripts || hasDeps) {
-          return true;
-        }
-      }
-    } catch {
-      // Ignore malformed package.json and fall back to file heuristics.
-    }
-  }
-
-  return [
-    'pom.xml',
-    'build.gradle',
-    'build.gradle.kts',
-    'mvnw',
-    'gradlew',
-    'src',
-    'src/main/java',
-    'src/main/resources',
-    'README.md',
-    'README.en.md'
-  ].some((hint) => existsInRoot(cwd, hint));
-}
-
-function hasJavaSignals(cwd) {
-  return [
-    'pom.xml',
-    'build.gradle',
-    'build.gradle.kts',
-    'mvnw',
-    'gradlew',
-    'src/main/java',
-    'src/main/resources',
-    'src/test/java'
-  ].some((hint) => existsInRoot(cwd, hint));
-}
-
-function hasVueSignals(cwd) {
-  return [
-    'frontend',
-    'frontend/src',
-    'src/App.vue',
-    'src/main.ts',
-    'src/main.js',
-    'src/components',
-    'src/views',
-    'vite.config.ts',
-    'vite.config.js',
-    'vue.config.js'
-  ].some((hint) => existsInRoot(cwd, hint));
-}
-
-function hasTypeScriptSignals(cwd) {
-  return [
-    'tsconfig.json',
-    'tsconfig.app.json',
-    'tsconfig.node.json',
-    'src',
-    'frontend/src',
-    'src/main.ts',
-    'src/env.d.ts',
-    'frontend/tsconfig.json'
-  ].some((hint) => existsInRoot(cwd, hint));
-}
-
-function detectReviewAutoOverlayProfiles(cwd, registry, changedFilesInput = []) {
-  const profiles = [];
-  const reviewBundle = registry[REVIEW_BUNDLE_NAME] || {};
-  const reviewProfiles = reviewBundle.profiles || {};
-  const changedFiles = normalizeChangedFiles(changedFilesInput);
-
-  if (changedFiles.length > 0) {
-    if (reviewProfiles['code-java'] && (
-      hasChangedFile(changedFiles, (filePath) => /\.(java|kt|xml)$/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(pom\.xml|build\.gradle(\.kts)?|mvnw|gradlew)$/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(src\/main\/java|src\/test\/java)(\/|$)/i.test(filePath))
-    )) {
-      profiles.push('code-java');
-    }
-
-    if (reviewProfiles['code-vue'] && (
-      hasChangedFile(changedFiles, (filePath) => /\.vue$/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(src\/main\.(ts|js)|src\/App\.vue|src\/components|src\/views|frontend\/)/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(vite\.config\.(ts|js)|vue\.config\.js)$/i.test(filePath))
-    )) {
-      profiles.push('code-vue');
-    }
-
-    if (reviewProfiles['code-ts'] && (
-      hasChangedFile(changedFiles, (filePath) => /\.(ts|tsx|d\.ts)$/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(tsconfig(\.[^.]+)?\.json|vite\.config\.ts|eslint\.config\.ts|src\/env\.d\.ts)$/i.test(filePath))
-      || hasChangedFile(changedFiles, (filePath) => /(^|\/)(src\/store|src\/stores|src\/state|frontend\/src\/store|frontend\/src\/stores|frontend\/src\/state)(\/|$)/i.test(filePath))
-    )) {
-      profiles.push('code-ts');
-    }
-
-    return profiles;
-  }
-
-  if (hasJavaSignals(cwd) && reviewProfiles['code-java']) {
-    profiles.push('code-java');
-  }
-
-  if (hasVueSignals(cwd) && reviewProfiles['code-vue']) {
-    profiles.push('code-vue');
-  }
-
-  if (hasTypeScriptSignals(cwd) && reviewProfiles['code-ts']) {
-    profiles.push('code-ts');
-  }
-
-  return profiles;
-}
-
-function parseBundleOverride(override) {
-  if (!override) {
-    return { bundle: '', profile: '' };
-  }
-
-  if (override.includes(':')) {
-    const [bundle, profile] = override.split(':', 2);
-    return { bundle, profile };
-  }
-
-  if (override.includes('/')) {
-    const [bundle, profile] = override.split('/', 2);
-    return { bundle, profile };
-  }
-
-  return { bundle: override, profile: '' };
-}
-
-function detectRulesBundle(cwd = process.cwd(), changedFilesInput = []) {
-  const registry = readRegistry();
-  const skillProfileMap = readSkillProfileMap();
-  const override = String(process.env.PIG_SKILLS_RULE_BUNDLE || process.env.PIG_SKILLS_RULES_BUNDLE || '').trim();
-  const profileOverride = String(process.env.PIG_SKILLS_RULE_PROFILE || '').trim();
-  const skillOverride = String(process.env.PIG_SKILLS_RULE_SKILL || '').trim();
-  const overlayOverride = String(process.env.PIG_SKILLS_RULE_OVERLAY || '').trim();
-  const changedFiles = normalizeChangedFiles(
-    changedFilesInput.length > 0
-      ? changedFilesInput
-      : process.env.PIG_SKILLS_CHANGED_FILES || ''
-  );
-
-  if (shouldValidateSkillProfiles()) {
-    validateSkillProfileConsistency();
-  }
-
-  function resolveBundleSelection(bundleName, profileName = '') {
-    const layers = [];
-    let baseLayer = null;
-    const seenLayers = new Set();
-
-    function addLayer(bundle, profile, markAsBase = false) {
-      const layer = getLayer(registry, bundle, profile);
-      if (!layer) return null;
-      const key = `${layer.bundle}:${layer.profile || ''}`;
-      if (seenLayers.has(key)) {
-        if (markAsBase) baseLayer = layer;
-        return layer;
-      }
-      seenLayers.add(key);
-      layers.push(layer);
-      if (markAsBase) baseLayer = layer;
-      return layer;
-    }
-
-    if (bundleName === CORE_BUNDLE_NAME) {
-      addLayer(CORE_BUNDLE_NAME, CORE_PROFILE_NAME, true);
-    } else {
-      addLayer(CORE_BUNDLE_NAME, CORE_PROFILE_NAME);
-      addLayer(bundleName, profileName, true);
-    }
-
-    if (bundleName === REVIEW_BUNDLE_NAME) {
-      for (const autoProfile of detectReviewAutoOverlayProfiles(cwd, registry, changedFiles)) {
-        addLayer(REVIEW_BUNDLE_NAME, autoProfile);
-      }
-    }
-
-    if (overlayOverride && registry[overlayOverride]) {
-      const overlayProfile = profileOverride && registry[overlayOverride].profiles && registry[overlayOverride].profiles[profileOverride]
-        ? profileOverride
-        : (registry[overlayOverride].profiles && registry[overlayOverride].profiles[CORE_PROFILE_NAME] ? CORE_PROFILE_NAME : '');
-      addLayer(overlayOverride, overlayProfile);
-    }
-
-    if (layers.length === 0) return null;
-    return combineLayers(layers, {
-      bundle: bundleName,
-      profile: profileName || null,
-      baseLayer,
-      source: 'environment override'
-    });
-  }
-
-  if (override) {
-    const parsed = parseBundleOverride(override);
-    if (registry[parsed.bundle]) {
-      const resolved = resolveBundleSelection(parsed.bundle, profileOverride || parsed.profile || '');
-      if (resolved) return resolved;
-    }
-  }
-
-  if (skillOverride) {
-    const mapped = skillProfileMap[skillOverride] || {};
-    const declaredProfile = readSkillRuleProfile(skillOverride);
-    const selectedProfile = profileOverride || mapped.profile || declaredProfile || '';
-    const selectedBundle = mapped.bundle || readSkillRuleBundle(skillOverride) || findBundleByProfile(registry, selectedProfile);
-    const resolved = selectedBundle ? resolveBundleSelection(selectedBundle, selectedProfile) : null;
-    if (resolved) {
-      return {
-        ...resolved,
-        skill: skillOverride,
-        source: declaredProfile ? 'skill declaration' : 'skill mapping'
-      };
-    }
-  }
-
-  const bundle = hasCodingSignals(cwd) ? 'coding' : CORE_BUNDLE_NAME;
-  const bundleConfig = registry[bundle];
-  const profileName = bundle === CORE_BUNDLE_NAME
-    ? CORE_PROFILE_NAME
-    : (profileOverride && bundleConfig && bundleConfig.profiles && bundleConfig.profiles[profileOverride]
-      ? profileOverride
-      : (bundleConfig && bundleConfig.profiles && bundleConfig.profiles.analysis ? 'analysis' : 'core'));
-  const selection = resolveBundleSelection(bundle, profileName || '');
-
-  if (!selection) {
-    return combineLayers(
-      [getLayer(registry, CORE_BUNDLE_NAME, CORE_PROFILE_NAME)].filter(Boolean),
-      {
-        bundle: CORE_BUNDLE_NAME,
-        profile: CORE_PROFILE_NAME,
-        skill: skillOverride || null,
-        source: 'workspace detection'
-      }
-    );
-  }
-
-  return {
-    ...selection,
-    skill: skillOverride || null,
-    source: 'workspace detection'
-  };
-}
-
-if (require.main === module) {
-  const cwd = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
-  process.stdout.write(`${JSON.stringify(detectRulesBundle(cwd), null, 2)}\n`);
-}
-
-module.exports = {
-  detectRulesBundle,
-  readRegistry,
-  readSkillProfileMap,
-  readSkillRuleProfile,
-  readSkillRuleBundle,
-  validateSkillProfileConsistency,
-  shouldValidateSkillProfiles,
-  findBundleByProfile
-};
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const RULES_ROOT = path.join(PACKAGE_ROOT, 'rules');
+const STAGE_REGISTRY_PATH = path.join(RULES_ROOT, 'stages.json');
+const SKILL_STAGE_MAP_PATH = path.join(RULES_ROOT, 'skill-stage-map.json');
+const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
+const CORE_STAGE_NAME = 'core';
+const OVERLAY_STAGE_NAME = 'overlays';
+
+function readRegistry() {
+  return JSON.parse(fs.readFileSync(STAGE_REGISTRY_PATH, 'utf8'));
+}
+
+function readSkillStageMap() {
+  return JSON.parse(fs.readFileSync(SKILL_STAGE_MAP_PATH, 'utf8'));
+}
+
+function readSkillStage(skillName) {
+  return readSkillStageMap()[skillName]?.stage || null;
+}
+
+function listSkillDirectories() {
+  if (!fs.existsSync(SKILLS_ROOT)) {
+    return [];
+  }
+
+  const results = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'references') {
+        continue;
+      }
+
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const skillFile = path.join(fullPath, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          results.push(path.relative(SKILLS_ROOT, fullPath).replace(/\\/g, '/'));
+        }
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(SKILLS_ROOT);
+  return results.sort();
+}
+
+function readSkillName(skillDir) {
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    return '';
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const match = content.match(/^name:\s*(.+)$/m);
+  return match ? match[1].trim() : '';
+}
+
+function validateSkillStageConsistency() {
+  const registry = readRegistry();
+  const stageMap = readSkillStageMap();
+  const skillDirs = listSkillDirectories();
+  const issues = [];
+
+  const mappedSkills = Object.keys(stageMap).sort();
+  const discoveredSkillNames = [];
+
+  for (const skillPath of skillDirs) {
+    const skillName = readSkillName(path.join(SKILLS_ROOT, skillPath));
+    if (!skillName) {
+      issues.push(`Missing skill name in: ${skillPath}`);
+      continue;
+    }
+
+    discoveredSkillNames.push(skillName);
+    const mapping = stageMap[skillName];
+    if (!mapping) {
+      issues.push(`Missing stage mapping for skill: ${skillPath}`);
+      continue;
+    }
+
+    const stageName = mapping.stage;
+    const stage = registry[stageName];
+    if (!stage) {
+      issues.push(`Unknown stage mapped for ${skillPath}: ${stageName}`);
+      continue;
+    }
+
+    const files = new Set(stage.files || []);
+    if (stage.entry) {
+      files.add(stage.entry);
+    }
+    for (const relativePath of files) {
+      const filePath = path.join(RULES_ROOT, relativePath);
+      if (!fs.existsSync(filePath)) {
+        issues.push(`Missing stage file for ${skillPath}: ${relativePath}`);
+      }
+    }
+  }
+
+  for (const mappedSkill of mappedSkills) {
+    if (!discoveredSkillNames.includes(mappedSkill)) {
+      issues.push(`Mapping exists for missing skill directory: ${mappedSkill}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    const error = new Error(`Rule stage consistency check failed:\n- ${issues.join('\n- ')}`);
+    error.issues = issues;
+    throw error;
+  }
+
+  return {
+    skillCount: skillDirs.length,
+    mappedSkillCount: mappedSkills.length
+  };
+}
+
+function normalizeStageName(stageName) {
+  return String(stageName || '').trim();
+}
+
+function getLayer(registry, stageName, variantName = '') {
+  const stage = registry[stageName];
+  if (!stage) return null;
+
+  if (variantName) {
+    const variant = stage.variants && stage.variants[variantName];
+    if (!variant) return null;
+    return {
+      stage: stageName,
+      variant: variantName,
+      entry: variant.entry,
+      files: variant.files,
+      description: variant.description || stage.description
+    };
+  }
+
+  return {
+    stage: stageName,
+    variant: null,
+    entry: stage.entry,
+    files: stage.files,
+    description: stage.description
+  };
+}
+
+function combineLayers(layers, meta = {}) {
+  const flattenedFiles = [];
+  const seen = new Set();
+
+  for (const layer of layers) {
+    for (const file of layer.files || []) {
+      if (seen.has(file)) continue;
+      seen.add(file);
+      flattenedFiles.push(file);
+    }
+  }
+
+  const primary = meta.baseLayer || layers[layers.length - 1] || layers[0] || null;
+  return {
+    stage: meta.stage || (primary ? primary.stage : CORE_STAGE_NAME),
+    overlay: meta.overlay || null,
+    skill: meta.skill || null,
+    source: meta.source || 'stage map',
+    entry: meta.entry || (primary ? primary.entry : 'core/index.md'),
+    files: flattenedFiles,
+    description: primary ? primary.description : 'Baseline rules',
+    layers
+  };
+}
+
+function resolveStageSelection(registry, stageName, overlayName = '', meta = {}) {
+  const layers = [];
+  let baseLayer = null;
+  const seenLayers = new Set();
+
+  function addLayer(selectedStage, variant = '', markAsBase = false) {
+    const layer = getLayer(registry, selectedStage, variant);
+    if (!layer) return null;
+    const key = `${layer.stage}:${layer.variant || ''}`;
+    if (seenLayers.has(key)) {
+      if (markAsBase) baseLayer = layer;
+      return layer;
+    }
+    seenLayers.add(key);
+    layers.push(layer);
+    if (markAsBase) baseLayer = layer;
+    return layer;
+  }
+
+  addLayer(CORE_STAGE_NAME, '', stageName === CORE_STAGE_NAME);
+
+  if (stageName !== CORE_STAGE_NAME) {
+    addLayer(stageName, '', true);
+  }
+
+  if (overlayName) {
+    const overlayExists = registry[OVERLAY_STAGE_NAME]
+      && registry[OVERLAY_STAGE_NAME].variants
+      && registry[OVERLAY_STAGE_NAME].variants[overlayName];
+    if (!overlayExists) {
+      throw new Error(`Unknown overlay: ${overlayName}`);
+    }
+    addLayer(OVERLAY_STAGE_NAME, overlayName, false);
+  }
+
+  if (layers.length === 0) return null;
+  return combineLayers(layers, {
+    stage: stageName,
+    overlay: overlayName || null,
+    baseLayer,
+    source: meta.source || 'explicit selection'
+  });
+}
+
+function readEnvironmentStage() {
+  return normalizeStageName(process.env.PIG_SKILLS_RULE_STAGE || process.env.PIG_SKILLS_RULES_STAGE);
+}
+
+function readEnvironmentOverlay() {
+  return normalizeStageName(process.env.PIG_SKILLS_RULE_OVERLAY);
+}
+
+function detectRulesStage(cwd = process.cwd()) { // eslint-disable-line no-unused-vars
+  const registry = readRegistry();
+  const stageMap = readSkillStageMap();
+  const stageOverride = readEnvironmentStage();
+  const skillOverride = normalizeStageName(process.env.PIG_SKILLS_RULE_SKILL);
+  const overlayOverride = readEnvironmentOverlay();
+
+  if (stageOverride) {
+    if (!registry[stageOverride]) {
+      throw new Error(`Unknown stage: ${stageOverride}`);
+    }
+    return resolveStageSelection(registry, stageOverride, overlayOverride, { source: 'stage override' });
+  }
+
+  if (skillOverride) {
+    const mapped = stageMap[skillOverride];
+    if (!mapped) {
+      throw new Error(`Unknown skill mapping: ${skillOverride}`);
+    }
+    return resolveStageSelection(registry, mapped.stage, overlayOverride, {
+      skill: skillOverride,
+      source: 'skill mapping'
+    });
+  }
+
+  return resolveStageSelection(registry, CORE_STAGE_NAME, overlayOverride, { source: 'default' });
+}
+
+if (require.main === module) {
+  const cwd = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
+  process.stdout.write(`${JSON.stringify(detectRulesStage(cwd), null, 2)}\n`);
+}
+
+module.exports = {
+  detectRulesStage,
+  readRegistry,
+  readSkillStageMap,
+  readSkillStage,
+  validateSkillStageConsistency,
+  resolveStageSelection
+};