avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/avorelo-skill-registry.js

@@ -0,0 +1,810 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { scanTextForSecurity } = require("./security-scan");
+const {
+  SOURCE_CATALOG,
+  getSource,
+  canReuseSource,
+  canVendorSource,
+  canLearnPatterns,
+  hasConfirmedReusableLicense,
+} = require("./source-catalog");
+const { CAPABILITIES, getCapability } = require("./plans");
+
+const GENERATED_SKILL_REGISTRY_REL_PATH = ".avorelo/skills/registry.json";
+const VENDOR_SKILLPACKS_DIR = "vendor/skillpacks";
+const CANONICAL_AVORELO_SKILLS_DIR = "skills/avorelo";
+const MAX_ROUTE_SUMMARY_CHARS = 240;
+const MAX_ROUTE_SUPPORTING_SKILLS = 2;
+const BIDI_CHARS = ["\u202A", "\u202B", "\u202D", "\u202E", "\u202C", "\u2066", "\u2067", "\u2068", "\u2069"];
+
+const SECTION_ALIASES = Object.freeze({
+  overview: ["Overview"],
+  whenToUse: ["When to use this", "When to Use", "When to use"],
+  whenNotToUse: ["When NOT to use", "When not to use"],
+  workflow: [
+    "How It Works",
+    "How it Works",
+    "How it works",
+    "Workflow",
+    "The Process",
+    "The Planning Process",
+    "The TDD Cycle",
+    "The Five-Axis Review",
+    "Skill Discovery",
+    "Lifecycle Sequence",
+  ],
+  lifecycleStage: ["Lifecycle Mapping", "Lifecycle Sequence", "Lifecycle Stage"],
+  requiredChecks: ["Required checks", "Verification", "Verify the Verification"],
+  requiredOutput: ["Required output", "Output", "Usage"],
+  antiPatterns: ["Anti-patterns", "Common Rationalizations", "Failure Modes to Avoid"],
+  stopConditions: ["Stop conditions", "Red Flags"],
+  definitionOfDone: ["Definition of done"],
+  examples: ["Examples", "Quick Reference", "Usage", "Plan Document Template"],
+  references: ["References", "Source hierarchy"],
+});
+
+const CAPABILITY_BINDING_RULES = Object.freeze([
+  {
+    match: /using-agent-skills|using-avorelo-skills/i,
+    capabilityIds: ["source_backed_skill_router_basic", "dynamic_skill_pack_selection"],
+  },
+  {
+    match: /planning-and-task-breakdown|spec-driven-development|reference-first-implementation|source-driven-development/i,
+    capabilityIds: ["skill_pattern_extraction_basic", "source_backed_skill_router_basic", "prompt_compiler_advanced"],
+  },
+  {
+    match: /code-review-and-quality|pr-quality-gate/i,
+    capabilityIds: ["skill_pattern_extraction_basic", "source_backed_skill_router_basic", "evidence_latest"],
+  },
+  {
+    match: /test-driven-development/i,
+    capabilityIds: ["skill_pattern_extraction_basic", "source_backed_skill_router_basic", "evidence_latest"],
+  },
+  {
+    match: /prompt-context-optimization/i,
+    capabilityIds: ["skill_pattern_extraction_basic", "source_backed_skill_router_basic", "context_cost_advanced"],
+  },
+  {
+    match: /workspace-map/i,
+    capabilityIds: ["workspace_map_basic", "source_backed_skill_router_basic"],
+  },
+  {
+    match: /product-dogfood/i,
+    capabilityIds: ["skill_pattern_extraction_basic", "evidence_latest"],
+  },
+]);
+
+const TASK_SIGNAL_RULES = Object.freeze([
+  { match: /\b(plan|planning|breakdown|spec|acceptance criteria|task list)\b/i, boosts: ["planning-and-task-breakdown", "spec-driven-development", "reference-first-implementation"] },
+  { match: /\b(review|pr review|code review|quality gate|merge)\b/i, boosts: ["code-review-and-quality", "pr-quality-gate"] },
+  { match: /\b(test|testing|tdd|verify|verification|regression)\b/i, boosts: ["test-driven-development", "pr-quality-gate"] },
+  { match: /\b(source|reference|upstream|docs|documentation|verified)\b/i, boosts: ["source-driven-development", "reference-first-implementation"] },
+  { match: /\b(skill|skills|route|routing|select)\b/i, boosts: ["using-agent-skills", "using-avorelo-skills"] },
+  { match: /\b(context|token|prompt|scope|compact)\b/i, boosts: ["prompt-context-optimization"] },
+  { match: /\b(workspace|repo navigation|map|reentry)\b/i, boosts: ["workspace-map"] },
+  { match: /\b(dogfood|product learning|telemetry)\b/i, boosts: ["product-dogfood"] },
+]);
+
+function normalize(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function compactText(value, maxChars = MAX_ROUTE_SUMMARY_CHARS) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+function tokenize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9/_-]+/g, " ")
+    .split(/\s+/)
+    .map((term) => term.trim())
+    .filter((term) => term.length >= 3);
+}
+
+function estimateTokens(textLength) {
+  return Math.max(1, Math.ceil(Number(textLength || 0) / 4));
+}
+
+function buildContextWeight(charCount) {
+  const estimatedTokens = estimateTokens(charCount);
+  if (estimatedTokens >= 3500) return { label: "high", estimatedTokens, lazyLoadRecommended: true };
+  if (estimatedTokens >= 1200) return { label: "medium", estimatedTokens, lazyLoadRecommended: true };
+  return { label: "low", estimatedTokens, lazyLoadRecommended: false };
+}
+
+function listSkillFiles(cwd) {
+  const results = [];
+  const vendorRoot = path.join(cwd, VENDOR_SKILLPACKS_DIR);
+  const canonicalRoot = path.join(cwd, CANONICAL_AVORELO_SKILLS_DIR);
+
+  if (fs.existsSync(canonicalRoot)) {
+    for (const entry of fs.readdirSync(canonicalRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(canonicalRoot, entry.name, "SKILL.md");
+      if (fs.existsSync(skillFile)) {
+        results.push(skillFile);
+      }
+    }
+  }
+
+  if (fs.existsSync(vendorRoot)) {
+    for (const pack of fs.readdirSync(vendorRoot, { withFileTypes: true })) {
+      if (!pack.isDirectory()) continue;
+      const skillsRoot = path.join(vendorRoot, pack.name, "skills");
+      if (!fs.existsSync(skillsRoot)) continue;
+      for (const skill of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!skill.isDirectory()) continue;
+        const skillFile = path.join(skillsRoot, skill.name, "SKILL.md");
+        if (fs.existsSync(skillFile)) {
+          results.push(skillFile);
+        }
+      }
+    }
+  }
+
+  return results.sort((left, right) => left.localeCompare(right));
+}
+
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) {
+    return { frontmatter: {}, body: raw, errors: ["Missing YAML frontmatter"] };
+  }
+
+  const frontmatter = {};
+  const errors = [];
+  const lines = match[1].split(/\r?\n/);
+  let currentListKey = null;
+
+  lines.forEach((line) => {
+    const listMatch = line.match(/^\s*-\s+(.*)$/);
+    if (listMatch && currentListKey) {
+      if (!Array.isArray(frontmatter[currentListKey])) frontmatter[currentListKey] = [];
+      frontmatter[currentListKey].push(listMatch[1].trim());
+      return;
+    }
+
+    const separator = line.indexOf(":");
+    if (separator === -1) return;
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (!key) return;
+    if (!value) {
+      currentListKey = key;
+      frontmatter[key] = [];
+      return;
+    }
+    currentListKey = null;
+    frontmatter[key] = value;
+  });
+
+  if (!frontmatter.name) errors.push("Frontmatter must include name");
+  if (!frontmatter.description) errors.push("Frontmatter must include description");
+  return {
+    frontmatter,
+    body: raw.slice(match[0].length),
+    errors,
+  };
+}
+
+function extractSection(body, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`(?:^|\\r?\\n)##\\s+${escaped}\\r?\\n([\\s\\S]*?)(?=\\r?\\n##\\s+|$)`, "i");
+  const match = body.match(regex);
+  return match ? match[1].trim() : "";
+}
+
+function findSection(body, aliases) {
+  for (const heading of aliases) {
+    const value = extractSection(body, heading);
+    if (value) return value;
+  }
+  return "";
+}
+
+function detectReferences(body) {
+  const inline = (body.match(/`([^`]+)`/g) || [])
+    .map((token) => token.slice(1, -1))
+    .filter((token) => token.includes("/") || token.endsWith(".js") || token.endsWith(".md") || token.startsWith("http"));
+  const urls = body.match(/https?:\/\/[^\s)]+/g) || [];
+  return Array.from(new Set([...inline, ...urls]));
+}
+
+function detectCrossSkillReferences(body) {
+  return Array.from(new Set((body.match(/skills\/[A-Za-z0-9/_-]+/g) || [])));
+}
+
+function detectScripts(body) {
+  return Array.from(new Set([
+    ...(body.match(/scripts\/[A-Za-z0-9/_-]+\.[A-Za-z0-9]+/g) || []),
+    ...(body.match(/[A-Za-z0-9/_-]+\.sh\b/g) || []),
+  ]));
+}
+
+function detectAssets(body) {
+  return Array.from(new Set((body.match(/assets\/[A-Za-z0-9/_-]+\.[A-Za-z0-9]+/g) || [])));
+}
+
+function detectSupportingFiles(body) {
+  const matches = new Set();
+  const patterns = [
+    /`((?:\.{1,2}\/)?(?:references|scripts|assets)\/[^`\n]+\.(?:md|json|js|ts|tsx|sh|txt|yaml|yml))`/g,
+    /`((?:\.{1,2}\/)?[A-Za-z0-9._/-]+\.(?:md|json|js|ts|tsx|sh|txt|yaml|yml))`/g,
+    /\b((?:\.{1,2}\/)?(?:references|scripts|assets)\/[A-Za-z0-9._/-]+\.(?:md|json|js|ts|tsx|sh|txt|yaml|yml))\b/g,
+  ];
+
+  patterns.forEach((pattern) => {
+    let match = null;
+    while ((match = pattern.exec(body)) !== null) {
+      matches.add(match[1]);
+    }
+  });
+
+  return Array.from(matches);
+}
+
+function skillIdForFile(cwd, absPath) {
+  const relPath = normalize(path.relative(cwd, absPath));
+  if (relPath.startsWith("skills/avorelo/")) {
+    return relPath.split("/").slice(2, 3)[0];
+  }
+  if (relPath.startsWith("vendor/skillpacks/")) {
+    const parts = relPath.split("/");
+    return `${parts[2]}:${parts[4]}`;
+  }
+  return relPath;
+}
+
+function packIdForFile(cwd, absPath) {
+  const relPath = normalize(path.relative(cwd, absPath));
+  if (relPath.startsWith("vendor/skillpacks/")) {
+    return relPath.split("/")[2];
+  }
+  return "avorelo";
+}
+
+function sourceMetadataForPack(cwd, packId) {
+  if (packId === "avorelo") {
+    return {
+      id: "avorelo",
+      name: "Avorelo canonical skills",
+      sourceUrl: null,
+      reviewStatus: "trusted",
+      trustLevel: "high",
+      riskLevel: "low",
+      license: "proprietary",
+      canReuse: true,
+      canVendor: true,
+      canLearnPatterns: true,
+      attributionText: null,
+      runtimePolicy: "local_first_owned",
+      copyPolicy: "internal_only",
+      sourceSnapshot: { type: "canonical" },
+    };
+  }
+
+  const source = getSource(packId);
+  const sourceJsonPath = path.join(cwd, VENDOR_SKILLPACKS_DIR, packId, "SOURCE.json");
+  let sourceJson = null;
+  if (fs.existsSync(sourceJsonPath)) {
+    try {
+      sourceJson = JSON.parse(fs.readFileSync(sourceJsonPath, "utf8"));
+    } catch {}
+  }
+
+  return {
+    id: packId,
+    name: source?.name || sourceJson?.name || packId,
+    sourceUrl: source?.sourceUrl || sourceJson?.sourceUrl || null,
+    reviewStatus: source?.sourceReviewStatus || "unreviewed",
+    trustLevel: source?.sourceTrustLevel || "unknown",
+    riskLevel: source?.riskLevel || "high",
+    license: source?.license || sourceJson?.license || "unknown",
+    canReuse: source ? canReuseSource(source) : false,
+    canVendor: source ? canVendorSource(source.id) : false,
+    canLearnPatterns: source ? canLearnPatterns(source) : false,
+    attributionText: source?.attributionText || null,
+    runtimePolicy: sourceJson?.runtimePolicy || "unknown",
+    copyPolicy: sourceJson?.copyPolicy || "unknown",
+    sourceSnapshot: source?.sourceSnapshot || sourceJson?.sourceSnapshot || null,
+  };
+}
+
+function resolvePathRelativeToSkill(absSkillPath, candidate) {
+  const candidateText = String(candidate || "").trim();
+  if (!candidateText || /^https?:\/\//i.test(candidateText)) return null;
+  if (/^[A-Za-z]:\//i.test(candidateText)) return candidateText;
+  if (/^(?:references|assets|skills)\//.test(candidateText) && normalize(absSkillPath).includes("/vendor/skillpacks/")) {
+    const packRoot = path.resolve(path.dirname(absSkillPath), "..", "..");
+    return path.resolve(packRoot, candidateText);
+  }
+  return path.resolve(path.dirname(absSkillPath), candidateText);
+}
+
+function detectRedFlags(raw, sections) {
+  const findings = [];
+  if (BIDI_CHARS.some((char) => raw.includes(char))) {
+    findings.push({ code: "hidden_unicode", severity: "high", message: "Hidden Unicode control characters detected." });
+  }
+
+  const combined = [sections.antiPatterns, sections.stopConditions, raw].filter(Boolean).join("\n");
+  [
+    { code: "policy_bypass_phrase", severity: "high", pattern: /\b(ignore|bypass|disable|remove)\s+(?:the\s+)?(?:policy|guardrails|audit|proof|verification|review)\b/i, message: "Bypass-policy red flag detected." },
+    { code: "unsafe_auto_execution_phrase", severity: "high", pattern: /\b(auto-?run|execute automatically|run immediately)\b/i, message: "Auto-execution language detected." },
+  ].forEach((rule) => {
+    if (rule.pattern.test(combined)) findings.push({ code: rule.code, severity: rule.severity, message: rule.message });
+  });
+  return findings;
+}
+
+function buildWarnings({ absPath, relPath, raw, parsed, packMetadata, references, scripts, assets, supportingFiles, sections }) {
+  const warnings = [];
+
+  parsed.errors.forEach((error) => warnings.push({ code: "frontmatter_error", severity: "medium", message: error }));
+
+  if (!hasConfirmedReusableLicense({
+    license: packMetadata.license,
+    productDecision: packMetadata.reviewStatus === "blocked" ? "blocked" : "defer",
+    allowedUseModes: [],
+  }) && packMetadata.id !== "avorelo") {
+    warnings.push({ code: "unknown_or_unconfirmed_license", severity: "high", message: "Source license is not confirmed for reuse." });
+  }
+  if (packMetadata.reviewStatus === "unreviewed") {
+    warnings.push({ code: "unreviewed_source", severity: "high", message: "Source remains unreviewed and should stay deferred." });
+  }
+  if (packMetadata.reviewStatus === "blocked") {
+    warnings.push({ code: "blocked_source", severity: "high", message: "Source is blocked and must not be routed." });
+  }
+  if (packMetadata.id !== "avorelo" && !packMetadata.attributionText) {
+    warnings.push({ code: "missing_attribution", severity: "medium", message: "Vendored or external source is missing attribution guidance." });
+  }
+  if (scripts.length > 0 && packMetadata.id !== "avorelo") {
+    warnings.push({ code: "external_script_metadata_only", severity: "medium", message: "Imported script references must remain data-only and never auto-run." });
+  }
+
+  supportingFiles.forEach((candidate) => {
+    if (!/^(?:\.{1,2}\/|references\/|scripts\/|assets\/)/.test(candidate)) return;
+    const resolved = resolvePathRelativeToSkill(absPath, candidate);
+    if (!resolved) return;
+    if (!fs.existsSync(resolved)) {
+      warnings.push({
+        code: "missing_supporting_file",
+        severity: "medium",
+        message: `Referenced supporting file is missing: ${candidate}`,
+      });
+    }
+  });
+
+  const weight = buildContextWeight(raw.length);
+  if (weight.label === "high") {
+    warnings.push({
+      code: "context_heavy_skill",
+      severity: "medium",
+      message: `Skill is context-heavy (${weight.estimatedTokens} estimated tokens) and should be lazy-loaded.`,
+    });
+  }
+
+  if (references.some((reference) => /AGENTS\.md|CLAUDE\.md|GEMINI\.md|copilot/i.test(reference)) && raw.length > 3000) {
+    warnings.push({
+      code: "adapter_leakage_risk",
+      severity: "medium",
+      message: "Skill references adapter surfaces and is too large for thin adapter copying.",
+    });
+  }
+
+  detectRedFlags(raw, sections).forEach((finding) => warnings.push(finding));
+  return warnings;
+}
+
+function summarizeWarnings(warnings) {
+  return warnings.map((warning) => ({
+    code: warning.code,
+    severity: warning.severity,
+    message: warning.message,
+  }));
+}
+
+function suggestCapabilityBindings(skill) {
+  const suggestions = new Set();
+  const haystack = [skill.id, skill.name, skill.description, skill.whenToUse, skill.workflow].join(" ");
+  CAPABILITY_BINDING_RULES.forEach((rule) => {
+    if (rule.match.test(haystack)) {
+      rule.capabilityIds.forEach((id) => suggestions.add(id));
+    }
+  });
+
+  if (skill.packId !== "avorelo") {
+    suggestions.add("reference_source_intake_basic");
+    suggestions.add("skill_md_parser_basic");
+    suggestions.add("skill_pattern_extraction_basic");
+    suggestions.add("skill_trust_scan_basic");
+    suggestions.add("capability_binding_basic");
+    suggestions.add("source_backed_skill_router_basic");
+  }
+
+  if (skill.packId === "avorelo") {
+    suggestions.add("skill_md_parser_basic");
+    suggestions.add("skill_pattern_extraction_basic");
+    suggestions.add("capability_binding_basic");
+    suggestions.add("source_backed_skill_router_basic");
+  }
+
+  if (skill.adapterSuitability.length > 0) {
+    suggestions.add("thin_adapter_guidance_sync_basic");
+  }
+
+  return Array.from(suggestions).filter((id) => getCapability(id)).sort();
+}
+
+function routeEligibility(skill) {
+  if (skill.packId === "avorelo") {
+    return { routeEligible: true, deferredReason: null };
+  }
+  if (skill.sourceReviewStatus === "blocked") {
+    return { routeEligible: false, deferredReason: "Source is blocked." };
+  }
+  if (!skill.sourceLicenseConfirmed) {
+    return { routeEligible: false, deferredReason: "Source license or provenance is not confirmed for reuse." };
+  }
+  if (!skill.sourceReusable) {
+    return { routeEligible: false, deferredReason: "Source is reference-only or deferred." };
+  }
+  if (skill.warnings.some((warning) => warning.severity === "high" && warning.code !== "frontmatter_error")) {
+    return { routeEligible: false, deferredReason: "Skill has unresolved high-severity trust or safety warnings." };
+  }
+  return { routeEligible: true, deferredReason: null };
+}
+
+function routeSummaryForSkill(skill, score, chosen = false) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: compactText(skill.description),
+    packId: skill.packId,
+    sourceId: skill.sourceId,
+    sourceReviewStatus: skill.sourceReviewStatus,
+    trustLevel: skill.sourceTrustLevel,
+    score,
+    chosen,
+    summary: compactText(skill.whenToUse || skill.description),
+    verification: compactText(skill.requiredChecks || skill.definitionOfDone || ""),
+    evidenceRequirements: compactText(skill.evidenceRequirements || skill.requiredOutput || ""),
+    contextWeight: skill.contextWeight,
+    capabilityIds: skill.capabilityBindingSuggestions,
+    sourcePath: skill.sourcePath,
+    warnings: summarizeWarnings(skill.warnings).slice(0, 5),
+  };
+}
+
+function parseSkillFile(cwd, absPath) {
+  const raw = fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, "");
+  const parsed = parseFrontmatter(raw);
+  const body = parsed.body || "";
+  const relPath = normalize(path.relative(cwd, absPath));
+  const packId = packIdForFile(cwd, absPath);
+  const packMetadata = sourceMetadataForPack(cwd, packId);
+
+  const sections = {
+    overview: findSection(body, SECTION_ALIASES.overview),
+    whenToUse: findSection(body, SECTION_ALIASES.whenToUse),
+    whenNotToUse: findSection(body, SECTION_ALIASES.whenNotToUse),
+    workflow: findSection(body, SECTION_ALIASES.workflow),
+    lifecycleStage: findSection(body, SECTION_ALIASES.lifecycleStage),
+    requiredChecks: findSection(body, SECTION_ALIASES.requiredChecks),
+    requiredOutput: findSection(body, SECTION_ALIASES.requiredOutput),
+    antiPatterns: findSection(body, SECTION_ALIASES.antiPatterns),
+    stopConditions: findSection(body, SECTION_ALIASES.stopConditions),
+    definitionOfDone: findSection(body, SECTION_ALIASES.definitionOfDone),
+    examples: findSection(body, SECTION_ALIASES.examples),
+    referencesSection: findSection(body, SECTION_ALIASES.references),
+  };
+  const references = detectReferences(body);
+  const scripts = detectScripts(body);
+  const assets = detectAssets(body);
+  const supportingFiles = Array.from(new Set([...detectSupportingFiles(body), ...references, ...scripts, ...assets]));
+  const securityReport = scanTextForSecurity({
+    text: raw,
+    pathHint: relPath,
+    allowlist: { reasonCodes: [], pathPatterns: [] },
+  });
+  const warnings = buildWarnings({
+    absPath,
+    relPath,
+    raw,
+    parsed,
+    packMetadata,
+    references,
+    scripts,
+    assets,
+    supportingFiles,
+    sections,
+  });
+  const contextWeight = buildContextWeight(raw.length);
+  const skill = {
+    id: skillIdForFile(cwd, absPath),
+    name: parsed.frontmatter.name || null,
+    description: parsed.frontmatter.description || null,
+    overview: sections.overview,
+    whenToUse: sections.whenToUse,
+    whenNotToUse: sections.whenNotToUse,
+    workflow: sections.workflow,
+    lifecycleStage: sections.lifecycleStage,
+    requiredChecks: sections.requiredChecks,
+    requiredOutput: sections.requiredOutput,
+    antiPatterns: sections.antiPatterns,
+    stopConditions: sections.stopConditions,
+    definitionOfDone: sections.definitionOfDone,
+    examples: sections.examples,
+    referencesSection: sections.referencesSection,
+    verification: sections.requiredChecks || sections.definitionOfDone,
+    evidenceRequirements: sections.requiredOutput,
+    redFlags: summarizeWarnings(warnings.filter((warning) => warning.severity === "high" || warning.code.includes("policy") || warning.code.includes("auto_execution"))),
+    references,
+    scripts,
+    assets,
+    supportingFiles,
+    crossSkillReferences: detectCrossSkillReferences(body),
+    sourcePath: relPath,
+    packId,
+    sourceId: packMetadata.id,
+    sourceName: packMetadata.name,
+    sourceUrl: packMetadata.sourceUrl,
+    sourceReviewStatus: packMetadata.reviewStatus,
+    sourceTrustLevel: packMetadata.trustLevel,
+    sourceRiskLevel: packMetadata.riskLevel,
+    sourceLicense: packMetadata.license,
+    sourceLicenseConfirmed: hasConfirmedReusableLicense({
+      license: packMetadata.license,
+    }) || packId === "avorelo",
+    sourceReusable: packId === "avorelo" ? true : packMetadata.canReuse,
+    sourceVendorAllowed: packId === "avorelo" ? false : packMetadata.canVendor,
+    sourceLearnPatternAllowed: packId === "avorelo" ? true : packMetadata.canLearnPatterns,
+    sourceAttributionText: packMetadata.attributionText,
+    runtimePolicy: packMetadata.runtimePolicy,
+    copyPolicy: packMetadata.copyPolicy,
+    sourceSnapshot: packMetadata.sourceSnapshot,
+    estimatedContextChars: raw.length,
+    contextWeight,
+    adapterSuitability: ["agents", "claude", "cursor", "gemini", "copilot"].filter((surface) => raw.length < 14000 || surface === "agents"),
+    errors: parsed.errors,
+    warnings,
+    securityScan: {
+      riskScore: securityReport.riskScore,
+      topReasons: securityReport.topReasons,
+    },
+  };
+  const eligibility = routeEligibility(skill);
+  skill.routeEligible = eligibility.routeEligible;
+  skill.deferredReason = eligibility.deferredReason;
+  skill.capabilityBindingSuggestions = suggestCapabilityBindings(skill);
+  return skill;
+}
+
+function buildSkillRegistry(cwd) {
+  const skillFiles = listSkillFiles(cwd);
+  const skills = skillFiles.map((absPath) => parseSkillFile(cwd, absPath));
+  const warnings = [];
+  const seenIds = new Set();
+
+  skills.forEach((skill) => {
+    if (seenIds.has(skill.id)) {
+      warnings.push(`Duplicate skill id: ${skill.id}`);
+    }
+    seenIds.add(skill.id);
+    skill.errors.forEach((error) => warnings.push(`[${skill.id}] ${error}`));
+    skill.warnings.forEach((warning) => warnings.push(`[${skill.id}] ${warning.code}: ${warning.message}`));
+    skill.capabilityBindingSuggestions.forEach((capabilityId) => {
+      if (!getCapability(capabilityId)) {
+        warnings.push(`[${skill.id}] Unknown capability binding suggestion: ${capabilityId}`);
+      }
+    });
+  });
+
+  const reviewedSourceIds = Array.from(new Set(skills
+    .filter((skill) => skill.sourceReviewStatus === "reviewed" || skill.sourceReviewStatus === "trusted")
+    .map((skill) => skill.sourceId)))
+    .filter((id) => id !== "avorelo");
+  const deferredSourceIds = Array.from(new Set(skills
+    .filter((skill) => !skill.routeEligible && skill.packId !== "avorelo")
+    .map((skill) => skill.sourceId)));
+  const blockedSourceIds = Array.from(new Set(skills
+    .filter((skill) => skill.sourceReviewStatus === "blocked")
+    .map((skill) => skill.sourceId)));
+
+  return {
+    schemaVersion: 2,
+    generatedAt: new Date().toISOString(),
+    skills,
+    warnings,
+    summary: {
+      totalSkills: skills.length,
+      canonicalSkills: skills.filter((skill) => skill.packId === "avorelo").length,
+      reviewedExternalSkills: skills.filter((skill) => skill.packId !== "avorelo" && skill.routeEligible).length,
+      deferredExternalSkills: skills.filter((skill) => skill.packId !== "avorelo" && !skill.routeEligible).length,
+      skillsWithWarnings: skills.filter((skill) => skill.warnings.length > 0).length,
+      capabilityBoundSkills: skills.filter((skill) => skill.capabilityBindingSuggestions.length > 0).length,
+      reviewedSourceIds,
+      deferredSourceIds,
+      blockedSourceIds,
+    },
+  };
+}
+
+function writeSkillRegistry(cwd, registry) {
+  const absPath = path.join(cwd, GENERATED_SKILL_REGISTRY_REL_PATH);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(registry, null, 2), "utf8");
+  return GENERATED_SKILL_REGISTRY_REL_PATH;
+}
+
+function scoreSkill(skill, taskText) {
+  const terms = tokenize(taskText);
+  const sectionWeights = [
+    { text: skill.name, weight: 8 },
+    { text: skill.description, weight: 6 },
+    { text: skill.whenToUse, weight: 5 },
+    { text: skill.workflow, weight: 3 },
+    { text: skill.requiredChecks, weight: 3 },
+    { text: skill.antiPatterns, weight: 2 },
+    { text: skill.examples, weight: 1 },
+  ];
+
+  let score = 0;
+  let matchedTerms = 0;
+  const haystacks = sectionWeights.map((entry) => ({
+    text: String(entry.text || "").toLowerCase(),
+    weight: entry.weight,
+  }));
+  terms.forEach((term) => {
+    haystacks.forEach((entry) => {
+      if (entry.text.includes(term)) {
+        score += entry.weight;
+        matchedTerms += 1;
+      }
+    });
+  });
+
+  TASK_SIGNAL_RULES.forEach((rule) => {
+    if (rule.match.test(taskText) && rule.boosts.some((boost) => skill.id.includes(boost) || skill.name === boost)) {
+      score += 12;
+    }
+  });
+
+  if (skill.packId === "avorelo") score += 6;
+  else if (skill.routeEligible) score += 2;
+
+  if (skill.contextWeight.label === "high") score -= 3;
+  if (skill.contextWeight.label === "medium") score -= 1;
+
+  if (matchedTerms === 0 && score === 0) {
+    const taskLower = String(taskText || "").toLowerCase();
+    if (taskLower.includes("source-backed") && /using-agent-skills|reference-first-implementation|source-driven-development/i.test(skill.id)) {
+      score += 5;
+    }
+  }
+
+  return score;
+}
+
+function uniqueDeferredSources(skipped) {
+  const seen = new Map();
+  skipped
+    .filter((entry) => entry.reason === "deferred_source")
+    .forEach((entry) => {
+      const key = entry.sourceId || entry.packId;
+      if (!seen.has(key)) {
+        seen.set(key, {
+          sourceId: entry.sourceId,
+          sourceName: entry.sourceName,
+          reason: entry.deferredReason,
+        });
+      }
+    });
+  return Array.from(seen.values());
+}
+
+function routeSkillForTask(registry, task) {
+  const taskText = String(task || "").trim();
+  const candidates = [];
+  const skipped = [];
+
+  registry.skills.forEach((skill) => {
+    const score = scoreSkill(skill, taskText);
+    if (!skill.routeEligible) {
+      skipped.push({
+        id: skill.id,
+        name: skill.name,
+        packId: skill.packId,
+        sourceId: skill.sourceId,
+        sourceName: skill.sourceName,
+        reason: "deferred_source",
+        deferredReason: skill.deferredReason,
+      });
+      return;
+    }
+
+    if (score <= 0) {
+      skipped.push({
+        id: skill.id,
+        name: skill.name,
+        packId: skill.packId,
+        sourceId: skill.sourceId,
+        sourceName: skill.sourceName,
+        reason: "not_relevant",
+        deferredReason: null,
+      });
+      return;
+    }
+
+    candidates.push({ skill, score });
+  });
+
+  candidates.sort((left, right) => {
+    if (right.score !== left.score) return right.score - left.score;
+    if (left.skill.packId === "avorelo" && right.skill.packId !== "avorelo") return -1;
+    if (right.skill.packId === "avorelo" && left.skill.packId !== "avorelo") return 1;
+    return left.skill.id.localeCompare(right.skill.id);
+  });
+
+  const primary = candidates[0] || null;
+  const supporting = candidates.slice(1, 1 + MAX_ROUTE_SUPPORTING_SKILLS)
+    .filter((entry) => entry.score >= Math.max(2, (primary?.score || 0) - 6));
+
+  const selected = [primary, ...supporting].filter(Boolean);
+  const selectedCapabilities = Array.from(new Set(selected.flatMap((entry) => entry.skill.capabilityBindingSuggestions)))
+    .filter((capabilityId) => getCapability(capabilityId))
+    .sort();
+  const evidenceRequirements = selected
+    .map((entry) => compactText(entry.skill.evidenceRequirements || entry.skill.requiredOutput || entry.skill.definitionOfDone || ""))
+    .filter(Boolean);
+  const verificationRequirements = selected
+    .map((entry) => compactText(entry.skill.requiredChecks || entry.skill.definitionOfDone || ""))
+    .filter(Boolean);
+  const totalEstimatedTokens = selected.reduce((sum, entry) => sum + Number(entry.skill.contextWeight.estimatedTokens || 0), 0);
+  const skillContextWarnings = selected
+    .flatMap((entry) => (entry.skill.warnings || []).map((warning) => ({
+      code: warning.code,
+      severity: warning.severity,
+      skillId: entry.skill.id,
+      message: compactText(warning.message, 120),
+    })));
+
+  return {
+    task: taskText,
+    primarySkill: primary ? routeSummaryForSkill(primary.skill, primary.score, true) : null,
+    supportingSkills: supporting.map((entry) => routeSummaryForSkill(entry.skill, entry.score, false)),
+    selectedCapabilities,
+    skippedSkills: skipped.slice(0, 10),
+    deferredSources: uniqueDeferredSources(skipped),
+    evidenceRequirements,
+    verificationRequirements,
+    skillContextWarnings,
+    contextWeight: {
+      label: totalEstimatedTokens >= 3500 ? "high" : totalEstimatedTokens >= 1200 ? "medium" : "low",
+      estimatedTokens: totalEstimatedTokens,
+      lazyLoad: totalEstimatedTokens >= 1200,
+    },
+    nextAction: primary
+      ? `Load ${primary.skill.id} with compact supporting context, then verify against its required checks and evidence expectations.`
+      : "No reviewed skill matched strongly. Use canonical Avorelo skills or review deferred sources before routing external content.",
+    routeState: primary ? "selected" : "no_match",
+  };
+}
+
+module.exports = {
+  GENERATED_SKILL_REGISTRY_REL_PATH,
+  VENDOR_SKILLPACKS_DIR,
+  CANONICAL_AVORELO_SKILLS_DIR,
+  listSkillFiles,
+  parseFrontmatter,
+  parseSkillFile,
+  buildSkillRegistry,
+  writeSkillRegistry,
+  routeSkillForTask,
+};