avorelo 0.1.0

package/scripts/lib/skill-hygiene.js

@@ -0,0 +1,805 @@
+"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,
+};