avorelo 0.1.0 → 0.3.0

package/scripts/lib/skill-hygiene.js

@@ -1,805 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const { parseSkillFile } = require("./avorelo-skill-registry");
-
-const HYGIENE_CONTRACT = "avorelo.skillHygiene.v1";
-const HYGIENE_SCHEMA_VERSION = 1;
-const MAX_ACCEPTED_CONTRIBUTIONS = 3;
-const MAX_CONTRIBUTION_TOKENS = 30;
-const DESCRIPTION_OVERLAP_THRESHOLD = 0.45;
-
-const ALLOWED_CONTRIBUTION_TYPES = new Set([
-  "verification_check",
-  "edge_case",
-  "required_output_field",
-  "security_caveat",
-  "compact_example",
-]);
-
-const BLOCKED_CONTRIBUTION_TYPES = new Set([
-  "duplicate_workflow",
-  "new_main_workflow_authority",
-  "new_risky_tool_mcp_authority",
-  "policy_conflicting_instruction",
-  "broad_execution_instruction",
-  "long_context_dump",
-  "workflow_step",
-]);
-
-const RISKY_CONTRIBUTION_REASON_CODES = new Set([
-  "conflicting_invocation_policy",
-  "conflicting_tool_policy",
-  "conflicting_verification_policy",
-  "conflicting_context_policy",
-  "conflicting_source_priority",
-  "policy_bypass_phrase",
-  "unsafe_auto_execution_phrase",
-  "mcp_server_reference",
-  "browser_control_reference",
-  "broad_file_write_language",
-  "secret_access_language",
-  "shell_execution_language",
-  "network_or_remote_fetch",
-]);
-
-const GENERIC_CAPABILITY_IDS = new Set([
-  "capability_binding_basic",
-  "skill_md_parser_basic",
-  "skill_pattern_extraction_basic",
-  "skill_trust_scan_basic",
-  "source_backed_skill_router_basic",
-  "reference_source_intake_basic",
-  "thin_adapter_guidance_sync_basic",
-]);
-
-function tokenize(text) {
-  return String(text || "")
-    .toLowerCase()
-    .replace(/[^a-z0-9/_-]+/g, " ")
-    .split(/\s+/)
-    .map((t) => t.trim())
-    .filter((t) => t.length >= 3);
-}
-
-function jaccardSimilarity(setA, setB) {
-  if (setA.size === 0 && setB.size === 0) return 0;
-  const intersection = new Set([...setA].filter((x) => setB.has(x)));
-  const union = new Set([...setA, ...setB]);
-  return intersection.size / union.size;
-}
-
-function descriptionOverlap(a, b) {
-  const tokA = new Set(tokenize(a));
-  const tokB = new Set(tokenize(b));
-  return jaccardSimilarity(tokA, tokB);
-}
-
-function hasCapabilityOverlap(a, b) {
-  const capsA = new Set((a.capabilityBindingSuggestions || []).filter((c) => !GENERIC_CAPABILITY_IDS.has(c)));
-  const capsB = new Set((b.capabilityBindingSuggestions || []).filter((c) => !GENERIC_CAPABILITY_IDS.has(c)));
-  const intersection = [...capsA].filter((x) => capsB.has(x));
-  return intersection.length > 0 ? intersection : null;
-}
-
-function hasTaskSignalOverlap(a, b) {
-  const sigA = new Set(tokenize((a.whenToUse || "") + " " + (a.description || "")));
-  const sigB = new Set(tokenize((b.whenToUse || "") + " " + (b.description || "")));
-  return jaccardSimilarity(sigA, sigB);
-}
-
-function detectDuplicateReasonCodes(skillA, skillB) {
-  const codes = [];
-
-  if (skillA.name && skillB.name && skillA.name === skillB.name) {
-    codes.push("duplicate_name");
-  }
-
-  const overlap = descriptionOverlap(skillA.description, skillB.description);
-  if (overlap >= DESCRIPTION_OVERLAP_THRESHOLD) {
-    codes.push("high_description_overlap");
-  }
-
-  const capOverlap = hasCapabilityOverlap(skillA, skillB);
-  if (capOverlap && capOverlap.length >= 1) {
-    codes.push("same_capability_binding");
-  }
-
-  const taskSig = hasTaskSignalOverlap(skillA, skillB);
-  if (taskSig >= 0.4) {
-    codes.push("same_task_signal");
-  }
-
-  const refsA = new Set(skillA.references || []);
-  const refsB = new Set(skillB.references || []);
-  const refOverlap = [...refsA].filter((r) => refsB.has(r));
-  if (refOverlap.length >= 2) {
-    codes.push("same_supporting_reference");
-  }
-
-  const reqA = tokenize(skillA.requiredOutput || skillA.requiredChecks || "");
-  const reqB = tokenize(skillB.requiredOutput || skillB.requiredChecks || "");
-  const reqOverlap = jaccardSimilarity(new Set(reqA), new Set(reqB));
-  if (reqOverlap >= 0.5 && reqA.length > 2 && reqB.length > 2) {
-    codes.push("same_required_output");
-  }
-
-  return codes;
-}
-
-function detectConflictReasonCodes(skillA, skillB) {
-  const codes = [];
-  const rawA = [skillA.workflow, skillA.antiPatterns, skillA.stopConditions, skillA.whenToUse, skillA.requiredChecks].join(" ");
-  const rawB = [skillB.workflow, skillB.antiPatterns, skillB.stopConditions, skillB.whenToUse, skillB.requiredChecks].join(" ");
-
-  const bypassPattern = /\b(ignore|bypass|disable|remove)\s+(?:the\s+)?(?:policy|guardrails|audit|proof|verification|review)\b/i;
-  if (bypassPattern.test(rawA) || bypassPattern.test(rawB)) {
-    codes.push("policy_bypass_phrase");
-  }
-
-  const autoExecPattern = /\b(auto-?run|execute automatically|run immediately|always execute)\b/i;
-  if (autoExecPattern.test(rawA) || autoExecPattern.test(rawB)) {
-    codes.push("unsafe_auto_execution_phrase");
-  }
-
-  const hasNeverA = /\bnever\s+(run|execute|call|invoke)\b/i.test(rawA);
-  const hasAlwaysB = /\balways\s+(run|execute|call|invoke)\b/i.test(rawB);
-  const hasNeverB = /\bnever\s+(run|execute|call|invoke)\b/i.test(rawB);
-  const hasAlwaysA = /\balways\s+(run|execute|call|invoke)\b/i.test(rawA);
-  if ((hasNeverA && hasAlwaysB) || (hasNeverB && hasAlwaysA)) {
-    codes.push("conflicting_invocation_policy");
-  }
-
-  return codes;
-}
-
-function detectContextHeavyReasonCodes(skill) {
-  const codes = [];
-  if (skill.contextWeight?.label === "high") {
-    codes.push("context_heavy_skill");
-  }
-  if ((skill.examples || "").length > 2000) {
-    codes.push("long_inline_examples");
-  }
-  if (skill.contextWeight?.lazyLoadRecommended) {
-    codes.push("lazy_load_recommended");
-  }
-  return codes;
-}
-
-function detectSecurityHygieneReasonCodes(skill) {
-  const codes = [];
-  const warningCodes = new Set((skill.warnings || []).map((w) => w.code));
-  if (warningCodes.has("hidden_unicode")) codes.push("hidden_unicode");
-  if (warningCodes.has("external_script_metadata_only")) codes.push("external_script_metadata_only");
-  if (warningCodes.has("unreviewed_source") || warningCodes.has("blocked_source")) {
-    codes.push("blocked_or_unreviewed_source");
-  }
-
-  const rawText = [skill.workflow, skill.whenToUse, skill.description, skill.antiPatterns, skill.stopConditions].join(" ");
-
-  const bypassPat = /\b(ignore|bypass|disable|remove)\s+(?:the\s+)?(?:policy|guardrails|audit|proof|verification|review)\b/i;
-  if (warningCodes.has("policy_bypass_phrase") || bypassPat.test(rawText)) codes.push("policy_bypass_phrase");
-
-  const autoExecPat = /\b(auto-?run|execute automatically|run immediately|always execute)\b/i;
-  if (warningCodes.has("unsafe_auto_execution_phrase") || autoExecPat.test(rawText)) codes.push("unsafe_auto_execution_phrase");
-
-  if (/\b(curl|wget|fetch)\b.*\b(http|https):\/\//i.test(rawText)) codes.push("network_or_remote_fetch");
-  if (/\b(bash|sh|shell|exec|spawn|child_process)\b/i.test(rawText)) codes.push("shell_execution_language");
-  if (/\bmcp[_\s]server\b/i.test(rawText)) codes.push("mcp_server_reference");
-  if (/\b(browser[_\s]control|headless[_\s]browser|pw[_\s]browser|selenium[_\s]driver)\b/i.test(rawText)) codes.push("browser_control_reference");
-  if (/\b(write[_\s]file|fs\.write|writeFileSync|create[_\s]file)\b/i.test(rawText)) codes.push("broad_file_write_language");
-  if (/\b(secret|api[_\s]key|password|credential|token)\b/i.test(rawText)) codes.push("secret_access_language");
-
-  return [...new Set(codes)];
-}
-
-function detectStalenessReasonCodes(skill) {
-  const codes = [];
-  if (skill.warnings?.some((w) => w.code === "missing_supporting_file")) {
-    codes.push("missing_supporting_file");
-  }
-  if (skill.sourceReviewStatus === "deferred" || skill.deferredReason?.includes("deferred")) {
-    codes.push("deferred_or_blocked_source");
-  }
-  return codes;
-}
-
-function isSkillUnsafe(skill) {
-  const secCodes = detectSecurityHygieneReasonCodes(skill);
-  const criticalCodes = new Set([
-    "hidden_unicode",
-    "policy_bypass_phrase",
-    "unsafe_auto_execution_phrase",
-    "blocked_or_unreviewed_source",
-  ]);
-  return secCodes.some((c) => criticalCodes.has(c));
-}
-
-function selectPrimaryFromGroup(skills) {
-  const sorted = [...skills].sort((a, b) => {
-    const aScore = primaryScore(a);
-    const bScore = primaryScore(b);
-    if (bScore !== aScore) return bScore - aScore;
-    return a.id.localeCompare(b.id);
-  });
-  return sorted[0];
-}
-
-function primaryScore(skill) {
-  let score = 0;
-  if (skill.packId === "avorelo") score += 10;
-  else if (skill.sourceReviewStatus === "trusted") score += 8;
-  else if (skill.sourceReviewStatus === "reviewed") score += 6;
-  if (skill.routeEligible) score += 4;
-  const secCodes = detectSecurityHygieneReasonCodes(skill);
-  score -= secCodes.length * 2;
-  if (skill.contextWeight?.label === "low") score += 2;
-  else if (skill.contextWeight?.label === "medium") score += 1;
-  else if (skill.contextWeight?.label === "high") score -= 1;
-  return score;
-}
-
-function extractBoundedContributions(primarySkill, shadowSkill) {
-  const contributions = [];
-
-  const primaryChecks = tokenize(primarySkill.requiredChecks || primarySkill.definitionOfDone || "");
-  const shadowChecks = tokenize(shadowSkill.requiredChecks || shadowSkill.definitionOfDone || "");
-  if (shadowChecks.length > 0) {
-    const overlap = jaccardSimilarity(new Set(primaryChecks), new Set(shadowChecks));
-    if (overlap < 0.6 && shadowChecks.length <= 20) {
-      const uniqueTokens = shadowChecks.filter((t) => !primaryChecks.includes(t));
-      if (uniqueTokens.length >= 2) {
-        const secCodes = detectSecurityHygieneReasonCodes(shadowSkill);
-        const hasRisky = secCodes.some((c) => RISKY_CONTRIBUTION_REASON_CODES.has(c));
-        if (!hasRisky) {
-          contributions.push({
-            fromSkill: shadowSkill.id,
-            type: "verification_check",
-            text: `Verify: ${uniqueTokens.slice(0, 8).join(", ")}`,
-            reasonCodes: ["unique_verification_check", "non_conflicting"],
-            contextTokensEstimated: Math.min(uniqueTokens.length * 2, MAX_CONTRIBUTION_TOKENS),
-          });
-        }
-      }
-    }
-  }
-
-  const primaryWhenNot = tokenize(primarySkill.whenNotToUse || "");
-  const shadowWhenNot = tokenize(shadowSkill.whenNotToUse || "");
-  if (shadowWhenNot.length > 2) {
-    const overlap = jaccardSimilarity(new Set(primaryWhenNot), new Set(shadowWhenNot));
-    if (overlap < 0.5 && shadowWhenNot.length <= 15) {
-      const uniqueTokens = shadowWhenNot.filter((t) => !primaryWhenNot.includes(t));
-      if (uniqueTokens.length >= 2) {
-        contributions.push({
-          fromSkill: shadowSkill.id,
-          type: "edge_case",
-          text: `Edge: ${uniqueTokens.slice(0, 6).join(", ")}`,
-          reasonCodes: ["unique_edge_case", "non_conflicting"],
-          contextTokensEstimated: Math.min(uniqueTokens.length * 2, MAX_CONTRIBUTION_TOKENS),
-        });
-      }
-    }
-  }
-
-  return contributions.slice(0, MAX_ACCEPTED_CONTRIBUTIONS);
-}
-
-function classifyContribution(contribution, primarySkill, shadowSkill) {
-  if (!ALLOWED_CONTRIBUTION_TYPES.has(contribution.type)) {
-    return {
-      ...contribution,
-      accepted: false,
-      reasonCodes: [...(contribution.reasonCodes || []), "disallowed_contribution_type"],
-    };
-  }
-
-  if (BLOCKED_CONTRIBUTION_TYPES.has(contribution.type)) {
-    return {
-      ...contribution,
-      accepted: false,
-      reasonCodes: [...(contribution.reasonCodes || []), "blocked_type"],
-    };
-  }
-
-  const secCodes = detectSecurityHygieneReasonCodes(shadowSkill);
-  const hasRisky = secCodes.some((c) => RISKY_CONTRIBUTION_REASON_CODES.has(c));
-  if (hasRisky) {
-    return {
-      ...contribution,
-      accepted: false,
-      reasonCodes: [...(contribution.reasonCodes || []), ...secCodes.filter((c) => RISKY_CONTRIBUTION_REASON_CODES.has(c))],
-    };
-  }
-
-  return { ...contribution, accepted: true };
-}
-
-function detectDuplicateGroups(skills) {
-  const groups = [];
-  const grouped = new Set();
-
-  for (let i = 0; i < skills.length; i++) {
-    if (grouped.has(skills[i].id)) continue;
-    const group = [skills[i]];
-    const groupReasons = {};
-
-    for (let j = i + 1; j < skills.length; j++) {
-      if (grouped.has(skills[j].id)) continue;
-      const codes = detectDuplicateReasonCodes(skills[i], skills[j]);
-      if (codes.length > 0) {
-        group.push(skills[j]);
-        groupReasons[skills[j].id] = codes;
-        grouped.add(skills[j].id);
-      }
-    }
-
-    if (group.length > 1) {
-      grouped.add(skills[i].id);
-      groups.push({
-        skillIds: group.map((s) => s.id),
-        reasonCodes: groupReasons,
-      });
-    }
-  }
-
-  return groups;
-}
-
-function detectConflictGroups(skills) {
-  const groups = [];
-  const seen = new Set();
-
-  for (let i = 0; i < skills.length; i++) {
-    for (let j = i + 1; j < skills.length; j++) {
-      const key = `${skills[i].id}::${skills[j].id}`;
-      if (seen.has(key)) continue;
-      const codes = detectConflictReasonCodes(skills[i], skills[j]);
-      if (codes.length > 0) {
-        seen.add(key);
-        groups.push({
-          skillIds: [skills[i].id, skills[j].id],
-          reasonCodes: codes,
-        });
-      }
-    }
-  }
-
-  return groups;
-}
-
-function buildSkillHygiene(registry, options = {}) {
-  const skills = (registry.skills || []).filter((s) => s.routeEligible);
-  const allSkills = registry.skills || [];
-
-  const duplicateGroups = detectDuplicateGroups(skills);
-  const conflictGroups = detectConflictGroups(skills);
-
-  const contextHeavySkills = allSkills
-    .filter((s) => s.contextWeight?.label === "high")
-    .map((s) => ({ skillId: s.id, reasonCodes: detectContextHeavyReasonCodes(s) }));
-
-  const unsafeSkills = allSkills
-    .filter((s) => isSkillUnsafe(s))
-    .map((s) => ({ skillId: s.id, reasonCodes: detectSecurityHygieneReasonCodes(s) }));
-
-  const shadowCandidates = [];
-  const routingGuards = [];
-
-  duplicateGroups.forEach((group) => {
-    const groupSkills = group.skillIds
-      .map((id) => skills.find((s) => s.id === id))
-      .filter(Boolean);
-    const primary = selectPrimaryFromGroup(groupSkills);
-    const shadows = groupSkills.filter((s) => s.id !== primary.id);
-
-    shadows.forEach((shadow) => {
-      const rawContribs = extractBoundedContributions(primary, shadow);
-      const classified = rawContribs.map((c) => classifyContribution(c, primary, shadow));
-      const accepted = classified.filter((c) => c.accepted);
-      const rejected = classified.filter((c) => !c.accepted);
-
-      shadowCandidates.push({
-        skillId: shadow.id,
-        primarySkillId: primary.id,
-        duplicateReasonCodes: group.reasonCodes[shadow.id] || [],
-        acceptedContributions: accepted,
-        rejectedContributions: rejected,
-      });
-    });
-
-    const conflictsForGroup = conflictGroups.filter((cg) =>
-      cg.skillIds.some((id) => group.skillIds.includes(id))
-    );
-
-    const acceptedFromShadows = shadowCandidates
-      .filter((sc) => sc.primarySkillId === primary.id)
-      .flatMap((sc) => sc.acceptedContributions);
-
-    const hygieneDecision = conflictsForGroup.length > 0
-      ? "selected_primary_only"
-      : acceptedFromShadows.length > 0
-      ? "primary_plus_bounded_contributions"
-      : "deduped";
-
-    routingGuards.push({
-      taskCapabilityScope: primary.capabilityBindingSuggestions?.slice(0, 3) || [],
-      primarySkillId: primary.id,
-      suppressedSkillIds: shadows.map((s) => s.id),
-      hygieneDecision,
-      reasonCodes: group.reasonCodes,
-      conflictAvoided: conflictsForGroup.flatMap((cg) => cg.reasonCodes),
-    });
-  });
-
-  const allReasonCodes = [
-    ...duplicateGroups.flatMap((g) => Object.values(g.reasonCodes).flat()),
-    ...conflictGroups.flatMap((g) => g.reasonCodes),
-    ...contextHeavySkills.flatMap((s) => s.reasonCodes),
-  ];
-
-  const reasonCodeCounts = {};
-  allReasonCodes.forEach((code) => {
-    reasonCodeCounts[code] = (reasonCodeCounts[code] || 0) + 1;
-  });
-  const topReasonCodes = Object.entries(reasonCodeCounts)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 8)
-    .map(([code]) => code);
-
-  const totalAccepted = shadowCandidates.reduce((sum, sc) => sum + sc.acceptedContributions.length, 0);
-  const totalRejected = shadowCandidates.reduce((sum, sc) => sum + sc.rejectedContributions.length, 0);
-  const routeEligibleAfterHygiene = skills.length - shadowCandidates.length;
-
-  const hygieneStatus =
-    unsafeSkills.length > 0 || conflictGroups.length > 0 ? "action_needed"
-    : duplicateGroups.length > 0 || contextHeavySkills.length > 0 ? "watch"
-    : "clean";
-
-  const nextAction =
-    hygieneStatus === "action_needed"
-      ? "Review unsafe or conflicting skills. Run `avorelo skills hygiene --json` for details."
-      : hygieneStatus === "watch"
-      ? "Duplicate groups detected. Check shadow candidates for context savings."
-      : "Skills hygiene is clean. No duplicate full activation detected.";
-
-  return {
-    schemaVersion: HYGIENE_SCHEMA_VERSION,
-    contract: HYGIENE_CONTRACT,
-    generatedAt: new Date().toISOString(),
-    summary: {
-      totalSkills: allSkills.length,
-      routeEligibleSkills: skills.length,
-      duplicateGroups: duplicateGroups.length,
-      conflictGroups: conflictGroups.length,
-      shadowCandidates: shadowCandidates.length,
-      acceptedContributions: totalAccepted,
-      rejectedContributions: totalRejected,
-      contextHeavySkills: contextHeavySkills.length,
-      unsafeSkills: unsafeSkills.length,
-      routeEligibleAfterHygiene,
-    },
-    duplicateGroups,
-    conflictGroups,
-    shadowCandidates,
-    routingGuards,
-    contextHeavySkills,
-    unsafeSkills,
-    topReasonCodes,
-    hygieneStatus,
-    nextAction,
-    redacted: true,
-  };
-}
-
-function selectPrimarySkillForTask(skills, task, options = {}) {
-  const taskText = String(task || "").trim();
-  const eligible = skills.filter((s) => s.routeEligible && !isSkillUnsafe(s));
-  if (eligible.length === 0) return null;
-
-  const scored = eligible.map((s) => ({ skill: s, score: primaryScore(s) }));
-  scored.sort((a, b) => {
-    if (b.score !== a.score) return b.score - a.score;
-    return a.skill.id.localeCompare(b.skill.id);
-  });
-
-  return scored[0]?.skill || null;
-}
-
-function buildBoundedContributions(primarySkill, shadowSkills, options = {}) {
-  const allContributions = [];
-
-  for (const shadow of shadowSkills) {
-    const raw = extractBoundedContributions(primarySkill, shadow);
-    const classified = raw.map((c) => classifyContribution(c, primarySkill, shadow));
-    allContributions.push(...classified);
-    if (allContributions.filter((c) => c.accepted).length >= MAX_ACCEPTED_CONTRIBUTIONS) break;
-  }
-
-  return {
-    accepted: allContributions.filter((c) => c.accepted).slice(0, MAX_ACCEPTED_CONTRIBUTIONS),
-    rejected: allContributions.filter((c) => !c.accepted),
-  };
-}
-
-function buildRouteHygiene(registry, routeResult, options = {}) {
-  const hygiene = buildSkillHygiene(registry, options);
-  const primaryId = routeResult.primarySkill?.id || null;
-  if (!primaryId) {
-    return {
-      hygieneDecision: "clean",
-      primarySkill: null,
-      suppressedDuplicateSkills: [],
-      shadowSkills: [],
-      acceptedContributions: [],
-      rejectedContributions: [],
-      conflictAvoided: [],
-      contextBudgetApplied: false,
-      reasonCodes: [],
-      hygieneWarnings: [],
-    };
-  }
-
-  const isUnsafe = hygiene.unsafeSkills.some((u) => u.skillId === primaryId);
-  if (isUnsafe) {
-    return {
-      hygieneDecision: "blocked_from_auto_route",
-      primarySkill: primaryId,
-      suppressedDuplicateSkills: [],
-      shadowSkills: [],
-      acceptedContributions: [],
-      rejectedContributions: [],
-      conflictAvoided: [],
-      contextBudgetApplied: false,
-      reasonCodes: hygiene.unsafeSkills.find((u) => u.skillId === primaryId)?.reasonCodes || [],
-      hygieneWarnings: ["primary_skill_flagged_unsafe"],
-    };
-  }
-
-  const guardForPrimary = hygiene.routingGuards.find((g) => g.primarySkillId === primaryId);
-  if (guardForPrimary) {
-    const shadowCandidatesForPrimary = hygiene.shadowCandidates.filter((sc) => sc.primarySkillId === primaryId);
-    return {
-      hygieneDecision: guardForPrimary.hygieneDecision,
-      primarySkill: primaryId,
-      suppressedDuplicateSkills: guardForPrimary.suppressedSkillIds,
-      shadowSkills: shadowCandidatesForPrimary.map((sc) => sc.skillId),
-      acceptedContributions: shadowCandidatesForPrimary.flatMap((sc) => sc.acceptedContributions),
-      rejectedContributions: shadowCandidatesForPrimary.flatMap((sc) => sc.rejectedContributions),
-      conflictAvoided: guardForPrimary.conflictAvoided,
-      contextBudgetApplied: guardForPrimary.suppressedSkillIds.length > 0,
-      reasonCodes: Object.values(guardForPrimary.reasonCodes || {}).flat(),
-      hygieneWarnings: [],
-    };
-  }
-
-  const shadowEntry = hygiene.shadowCandidates.find((sc) => sc.skillId === primaryId);
-  if (shadowEntry) {
-    const hygienePrimary = shadowEntry.primarySkillId;
-    const guardForHygienePrimary = hygiene.routingGuards.find((g) => g.primarySkillId === hygienePrimary);
-    return {
-      hygieneDecision: "deduped",
-      primarySkill: primaryId,
-      suppressedDuplicateSkills: [],
-      shadowSkills: [],
-      acceptedContributions: shadowEntry.acceptedContributions || [],
-      rejectedContributions: shadowEntry.rejectedContributions || [],
-      conflictAvoided: guardForHygienePrimary?.conflictAvoided || [],
-      contextBudgetApplied: false,
-      reasonCodes: shadowEntry.duplicateReasonCodes || [],
-      hygieneWarnings: [`route_primary_is_shadow_under_${hygienePrimary}`],
-    };
-  }
-
-  const isContextHeavy = hygiene.contextHeavySkills.some((c) => c.skillId === primaryId);
-  return {
-    hygieneDecision: "clean",
-    primarySkill: primaryId,
-    suppressedDuplicateSkills: [],
-    shadowSkills: [],
-    acceptedContributions: [],
-    rejectedContributions: [],
-    conflictAvoided: [],
-    contextBudgetApplied: false,
-    reasonCodes: [],
-    hygieneWarnings: isContextHeavy ? ["primary_skill_context_heavy_lazy_load_recommended"] : [],
-  };
-}
-
-function buildSkillIntakeCheck(cwd, candidateSkillPath, options = {}) {
-  const registry = options.registry || null;
-
-  let candidateSkill;
-  try {
-    const absPath = path.resolve(cwd, candidateSkillPath);
-    candidateSkill = parseSkillFile(cwd, absPath);
-  } catch (err) {
-    return {
-      schemaVersion: HYGIENE_SCHEMA_VERSION,
-      contract: "avorelo.skillIntakeCheck.v1",
-      generatedAt: new Date().toISOString(),
-      candidatePath: candidateSkillPath,
-      decision: "block",
-      reasonCodes: ["parse_error"],
-      message: `Could not parse candidate skill: ${err.message}`,
-      duplicateMatches: [],
-      conflictMatches: [],
-      securityFlags: [],
-      redacted: true,
-    };
-  }
-
-  const secCodes = detectSecurityHygieneReasonCodes(candidateSkill);
-  const criticalSec = ["hidden_unicode", "policy_bypass_phrase", "unsafe_auto_execution_phrase", "blocked_or_unreviewed_source"];
-  if (secCodes.some((c) => criticalCodes.has(c))) {
-    return {
-      schemaVersion: HYGIENE_SCHEMA_VERSION,
-      contract: "avorelo.skillIntakeCheck.v1",
-      generatedAt: new Date().toISOString(),
-      candidatePath: candidateSkillPath,
-      decision: "block",
-      reasonCodes: secCodes,
-      message: "Candidate skill has critical security flags and cannot be admitted.",
-      duplicateMatches: [],
-      conflictMatches: [],
-      securityFlags: secCodes,
-      redacted: true,
-    };
-  }
-
-  const existingSkills = registry ? (registry.skills || []) : [];
-  const duplicateMatches = [];
-  const conflictMatches = [];
-
-  existingSkills.forEach((existing) => {
-    const dupCodes = detectDuplicateReasonCodes(candidateSkill, existing);
-    if (dupCodes.length > 0) {
-      duplicateMatches.push({ skillId: existing.id, reasonCodes: dupCodes });
-    }
-    const conflictCodes = detectConflictReasonCodes(candidateSkill, existing);
-    if (conflictCodes.length > 0) {
-      conflictMatches.push({ skillId: existing.id, reasonCodes: conflictCodes });
-    }
-  });
-
-  let decision = "allow";
-  if (conflictMatches.length > 0) {
-    decision = "block";
-  } else if (duplicateMatches.length > 0 && duplicateMatches.some((m) => m.reasonCodes.includes("same_capability_binding") || m.reasonCodes.includes("high_description_overlap"))) {
-    decision = "merge_recommended";
-  } else if (duplicateMatches.length > 0) {
-    decision = "warn";
-  }
-
-  const reasonCodes = [
-    ...(duplicateMatches.flatMap((m) => m.reasonCodes)),
-    ...(conflictMatches.flatMap((m) => m.reasonCodes)),
-    ...secCodes,
-  ];
-
-  return {
-    schemaVersion: HYGIENE_SCHEMA_VERSION,
-    contract: "avorelo.skillIntakeCheck.v1",
-    generatedAt: new Date().toISOString(),
-    candidatePath: candidateSkillPath,
-    candidateSkillId: candidateSkill.id,
-    candidateSkillName: candidateSkill.name,
-    decision,
-    reasonCodes: [...new Set(reasonCodes)],
-    message: intakeDecisionMessage(decision, duplicateMatches, conflictMatches),
-    duplicateMatches,
-    conflictMatches,
-    securityFlags: secCodes,
-    redacted: true,
-  };
-}
-
-function intakeDecisionMessage(decision, duplicateMatches, conflictMatches) {
-  if (decision === "block") return `Candidate skill conflicts with ${conflictMatches.length} existing skill(s). Review conflicts before admission.`;
-  if (decision === "merge_recommended") return `Candidate skill overlaps significantly with ${duplicateMatches.length} existing skill(s). Consider merging or extracting unique contributions.`;
-  if (decision === "warn") return `Candidate skill has minor overlap with ${duplicateMatches.length} existing skill(s). Review before adding.`;
-  return "Candidate skill passes hygiene checks.";
-}
-
-function summarizeSkillHygiene(hygiene) {
-  const s = hygiene.summary || {};
-  return {
-    hygieneStatus: hygiene.hygieneStatus,
-    totalSkills: s.totalSkills,
-    duplicateGroups: s.duplicateGroups,
-    conflictGroups: s.conflictGroups,
-    shadowCandidates: s.shadowCandidates,
-    acceptedContributions: s.acceptedContributions,
-    contextHeavySkills: s.contextHeavySkills,
-    unsafeSkills: s.unsafeSkills,
-    routeEligibleAfterHygiene: s.routeEligibleAfterHygiene,
-    topReasonCodes: hygiene.topReasonCodes || [],
-    nextAction: hygiene.nextAction,
-  };
-}
-
-function formatSkillHygieneText(hygiene) {
-  const s = hygiene.summary || {};
-  const lines = [
-    `Skills Hygiene: ${(hygiene.hygieneStatus || "clean").toUpperCase()} · deduped=${s.duplicateGroups || 0} · shadow=${s.shadowCandidates || 0} · contributions=${s.acceptedContributions || 0} · conflicts=${s.conflictGroups || 0}`,
-    `  total=${s.totalSkills || 0} · context_heavy=${s.contextHeavySkills || 0} · unsafe=${s.unsafeSkills || 0} · eligible_after_hygiene=${s.routeEligibleAfterHygiene || 0}`,
-  ];
-
-  if (hygiene.topReasonCodes?.length) {
-    lines.push(`  top_reason_codes: ${hygiene.topReasonCodes.slice(0, 5).join(", ")}`);
-  }
-
-  if (hygiene.duplicateGroups?.length) {
-    lines.push("");
-    lines.push("Duplicate Groups:");
-    hygiene.duplicateGroups.forEach((g) => {
-      lines.push(`  [${g.skillIds.join(" vs ")}] — ${Object.values(g.reasonCodes).flat().join(", ")}`);
-    });
-  }
-
-  if (hygiene.shadowCandidates?.length) {
-    lines.push("");
-    lines.push("Shadow Candidates:");
-    hygiene.shadowCandidates.forEach((sc) => {
-      const contrib = sc.acceptedContributions?.length || 0;
-      lines.push(`  ${sc.skillId} → shadow under ${sc.primarySkillId} (contributions=${contrib})`);
-    });
-  }
-
-  if (hygiene.conflictGroups?.length) {
-    lines.push("");
-    lines.push("Conflict Groups:");
-    hygiene.conflictGroups.forEach((g) => {
-      lines.push(`  [${g.skillIds.join(" vs ")}] — ${g.reasonCodes.join(", ")}`);
-    });
-  }
-
-  lines.push("");
-  lines.push(hygiene.nextAction || "");
-  return lines.join("\n");
-}
-
-function formatSkillIntakeCheckText(check) {
-  const lines = [
-    `Skill Intake Check: ${(check.decision || "allow").toUpperCase()} — ${check.candidateSkillId || check.candidatePath}`,
-    `  ${check.message}`,
-  ];
-
-  if (check.duplicateMatches?.length) {
-    lines.push(`  duplicate_matches: ${check.duplicateMatches.map((m) => m.skillId).join(", ")}`);
-  }
-  if (check.conflictMatches?.length) {
-    lines.push(`  conflict_matches: ${check.conflictMatches.map((m) => m.skillId).join(", ")}`);
-  }
-  if (check.securityFlags?.length) {
-    lines.push(`  security_flags: ${check.securityFlags.join(", ")}`);
-  }
-  return lines.join("\n");
-}
-
-const criticalCodes = new Set([
-  "hidden_unicode",
-  "policy_bypass_phrase",
-  "unsafe_auto_execution_phrase",
-  "blocked_or_unreviewed_source",
-]);
-
-module.exports = {
-  HYGIENE_CONTRACT,
-  HYGIENE_SCHEMA_VERSION,
-  buildSkillHygiene,
-  buildSkillIntakeCheck,
-  selectPrimarySkillForTask,
-  buildBoundedContributions,
-  buildRouteHygiene,
-  summarizeSkillHygiene,
-  formatSkillHygieneText,
-  formatSkillIntakeCheckText,
-  detectDuplicateReasonCodes,
-  detectConflictReasonCodes,
-  detectContextHeavyReasonCodes,
-  detectSecurityHygieneReasonCodes,
-  isSkillUnsafe,
-};