@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/engine/skill_recommendation.py

@@ -1,1183 +0,0 @@
-"""Deterministic skill recommendation logic for Phase 125 (TSK-125.2).
-
-Provides structured, inspectable skill recommendations based on:
-- Requirement analysis and classification
-- Runtime skill availability
-- Discovery evidence (docs/code findings)
-- Policy eligibility
-
-All recommendations include inspectable rationale for telemetry.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
-
-from structlog import get_logger
-
-# TSK-125.7: Import compliance types from telemetry module
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.engine.telemetry import (
-        ComplianceEvidence,
-    )
-
-logger = get_logger(__name__)
-
-
-@dataclass
-class SkillRecommendation:
-    """A single skill recommendation with rationale."""
-
-    skill_name: str
-    priority: int  # Lower is higher priority
-    rationale: str
-    objective_fit: str  # "primary", "secondary", "fallback"
-    prerequisites_met: bool = True
-    blocked_reason: str | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        """Serialize to telemetry-friendly dict."""
-        return {
-            "skill_name": self.skill_name,
-            "priority": self.priority,
-            "rationale": self.rationale,
-            "objective_fit": self.objective_fit,
-            "prerequisites_met": self.prerequisites_met,
-            "blocked_reason": self.blocked_reason,
-        }
-
-
-@dataclass
-class SkillRecommendationResult:
-    """Complete skill recommendation result with inspectable rationale."""
-
-    recommended_skills: list[SkillRecommendation] = field(default_factory=list)
-    primary_skill: str | None = None
-    fallback_skills: list[str] = field(default_factory=list)
-    recommendation_mode: str = "standard"  # "disabled", "minimal", "standard", "permissive"
-    discovery_evidence: dict[str, Any] = field(default_factory=dict)
-    requirement_analysis: dict[str, Any] = field(default_factory=dict)
-    skill_readiness: dict[str, Any] = field(default_factory=dict)
-    decision_rationale: str = ""
-    # TSK-125.7: Compliance evidence for hexagonal-compliance-skill (imported from telemetry)
-    compliance_evidence: ComplianceEvidence | None = None
-
-    def to_telemetry_payload(self) -> dict[str, Any]:
-        """Serialize to telemetry payload (AC-125.2.5, TSK-125.7)."""
-        payload = {
-            "recommended_skills": [rec.to_dict() for rec in self.recommended_skills],
-            "primary_skill": self.primary_skill,
-            "fallback_skills": list(self.fallback_skills),
-            "recommendation_mode": self.recommendation_mode,
-            "discovery_evidence": dict(self.discovery_evidence),
-            "requirement_analysis": dict(self.requirement_analysis),
-            "skill_readiness": dict(self.skill_readiness),
-            "decision_rationale": self.decision_rationale,
-        }
-        # TSK-125.7: Include compliance evidence if available
-        if self.compliance_evidence:
-            payload["compliance_evidence"] = self.compliance_evidence.to_dict()
-        return payload
-
-
-# Skill priority mappings by objective (AC-125.2.2, TSK-125.7)
-SKILL_OBJECTIVE_PRIORITY: dict[str, tuple[str, ...]] = {
-    "analyze_documentation_artifacts": (
-        "audit-orchestrator-skill",
-        "research-skill",
-        "vds-scripts-skill",
-    ),
-    "analyze_support_sla_controls": (
-        "research-skill",
-        "audit-orchestrator-skill",
-        "vds-scripts-skill",
-    ),
-    "analyze_compliance_controls": (
-        "research-skill",
-        "audit-orchestrator-skill",
-        "vds-ai-memory-skill",
-    ),
-    "analyze_security_scan_controls": (
-        "research-skill",
-        "audit-orchestrator-skill",
-        "llm-analysis-skill",
-    ),
-    "analyze_tooling_automation_guidance": (
-        "vds-scripts-skill",
-        "cli-development-skill",
-        "audit-orchestrator-skill",
-        "lsp-skill",
-    ),
-    "analyze_migration_scripts": ("migration-script-detection-skill",),
-    "analyze_operational_readiness": (
-        "research-skill",
-        "llm-analysis-skill",
-        "audit-orchestrator-skill",
-    ),
-    # TSK-125.7: Architecture compliance objective (CL-006-like rows)
-    "analyze_architecture_compliance": (
-        "hexagonal-compliance-skill",
-        "research-skill",
-        "code-review-graph-skill",
-        "audit-orchestrator-skill",
-    ),
-    "analyze_public_interface_boundaries": ("public-interface-boundary-skill",),
-    "discover_app_config": (
-        "app-config-discovery-skill",
-        "research-skill",
-        "audit-orchestrator-skill",
-    ),
-    "resolve_environment_specific_config": (
-        "app-config-discovery-skill",
-        "research-skill",
-        "audit-orchestrator-skill",
-    ),
-    "analyze_datasource_isolation": (
-        "app-config-discovery-skill",
-        "research-skill",
-        "audit-orchestrator-skill",
-    ),
-    "compare_cross_service_config_separation": (
-        "app-config-discovery-skill",
-        "research-skill",
-        "code-review-graph-skill",
-    ),
-    # Phase 133: shared-library usage analysis (CL-003-like rows)
-    "analyze_shared_library_usage": ("shared-infrastructure-lib-usage-skill",),
-}
-
-# Default fallback priority
-SKILL_FALLBACK_PRIORITY: tuple[str, ...] = (
-    "research-skill",
-    "audit-orchestrator-skill",
-    "vds-scripts-skill",
-    "grepai-skill",
-)
-
-# Marker patterns for skill inference
-SKILL_MARKER_PATTERNS: dict[str, tuple[str, ...]] = {
-    "research-skill": (
-        "sla",
-        "support",
-        "incident",
-        "runbook",
-        "monitoring",
-        "grafana",
-        "compliance",
-        "security",
-        "policy",
-        "governance",
-    ),
-    "vds-scripts-skill": (
-        "orchestrator",
-        "cli",
-        "automation",
-        "workflow",
-        "script",
-        "command",
-    ),
-    "cli-development-skill": (
-        "cli",
-        "typer",
-        "command-line",
-        "automation",
-        "workflow",
-    ),
-    "spec-creation-skill": (
-        "spec",
-        "requirement",
-        "design",
-        "task",
-        "phase",
-        "migration",
-    ),
-    "vds-ai-memory-skill": (
-        "memory",
-        "decision",
-        "knowledge",
-        "note",
-        "context",
-    ),
-    "grepai-skill": (
-        "search",
-        "semantic",
-        "discovery",
-        "explore",
-        "codebase",
-    ),
-    "public-interface-boundary-skill": (
-        "explicit public interface",
-        "interface/contract",
-        "interface contract",
-        "api client",
-        "message contract",
-        "import class implementation",
-        "concrete implementation",
-        "concrete class",
-        "public interface",
-        "public contract",
-    ),
-    "migration-script-detection-skill": (
-        "migration script",
-        "liquibase",
-        "flyway",
-        "db/migration",
-        "db/changelog",
-        "changelog",
-        "schema migration",
-        "versioned sql",
-    ),
-    "llm-analysis-skill": (
-        "analyze",
-        "evaluate",
-        "score",
-        "llm",
-        "quality",
-    ),
-    "repomix-skill": (
-        "pack",
-        "context",
-        "repository",
-        "bundle",
-        "consolidate",
-    ),
-    "code-review-graph-skill": (
-        "structure",
-        "dependency",
-        "call-graph",
-        "blast-radius",
-        "architecture",
-    ),
-    "circular-dependency-skill": (
-        "circular dependency",
-        "dependency cycle",
-        "cycle detection",
-        "dependency/lib",
-        "dependency lib",
-        "shared-library",
-        "shared library",
-        "dependency graph",
-        "service/module",
-        "module/service",
-        "module service",
-        "dùng chung",
-        "dung chung",
-        "lib tập trung",
-        "lib tap trung",
-        "dependency tập trung",
-        "dependency tap trung",
-    ),
-    # Phase 133: shared-library usage analysis (CL-003-like rows)
-    "shared-infrastructure-lib-usage-skill": (
-        "thư viện dùng chung",
-        "lib tập trung",
-        "shared library",
-        "shared-library",
-        "centralized lib",
-        "common-lib",
-        "LIB project",
-        "88724032",
-        "shared infrastructure",
-    ),
-    # TSK-125.7: Hexagonal compliance markers for CL-006-like rows
-    "hexagonal-compliance-skill": (
-        "hexagonal",
-        "clean architecture",
-        "ports",
-        "adapters",
-        "domain-driven",
-        "ddd",
-        "architecture compliance",
-        "layer violation",
-        "domain independence",
-        "framework-agnostic",
-        "architecture pattern",
-    ),
-}
-
-
-def normalize_skill_name(name: str) -> str:
-    """Normalize skill name for matching."""
-    normalized = str(name or "").strip().lower()
-    if not normalized:
-        return ""
-    normalized = re.sub(r"[\s_]+", "-", normalized)
-    return normalized
-
-
-def build_skill_aliases(name: str) -> set[str]:
-    """Build skill name aliases for flexible matching."""
-    text = str(name or "").strip()
-    if not text:
-        return set()
-    normalized = normalize_skill_name(text)
-    aliases: set[str] = {text, normalized}
-    if normalized.endswith("-skill"):
-        aliases.add(normalized[: -len("-skill")])
-    else:
-        aliases.add(f"{normalized}-skill")
-    return {alias for alias in aliases if alias}
-
-
-def resolve_available_skill_match(
-    candidate: str,
-    available_skill_names: list[str],
-) -> str | None:
-    """Resolve candidate skill name against available skills."""
-    candidate_aliases = build_skill_aliases(candidate)
-    if not candidate_aliases:
-        return None
-    for available in available_skill_names:
-        if candidate_aliases.intersection(build_skill_aliases(available)):
-            return available
-    return None
-
-
-def infer_skills_from_markers(
-    requirement_text: str,
-    requirement_category: str,
-) -> list[str]:
-    """Infer relevant skills from requirement text markers."""
-    lowered = f"{requirement_text} {requirement_category}".lower()
-    inferred: list[str] = []
-
-    for skill_name, markers in SKILL_MARKER_PATTERNS.items():
-        if any(marker in lowered for marker in markers) and skill_name not in inferred:
-            inferred.append(skill_name)
-
-    return inferred
-
-
-def is_source_backed_research_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement needs source-backed research (AC-125.2.2).
-
-    Source-backed research is needed when:
-    - Requirement mentions external sources, standards, or best practices
-    - Interpretation indicates docs-first or hybrid route
-    - Requirement category is compliance, security, or operational
-    """
-    lowered = f"{requirement_text} {requirement_category}".lower()
-
-    source_markers = (
-        "standard",
-        "best practice",
-        "guideline",
-        "policy",
-        "compliance",
-        "security",
-        "framework",
-        "specification",
-        "documentation",
-        "reference",
-        "official",
-        "source",
-        "external",
-        "internet",
-    )
-
-    if any(marker in lowered for marker in source_markers):
-        return True
-
-    if interpretation:
-        route_hints = str(interpretation.get("route_hint", "") or "").lower()
-        if any(hint in route_hints for hint in ("docs", "hybrid", "documentation")):
-            return True
-
-        objectives = interpretation.get("skill_objectives") or []
-        objective_names = [str(obj) for obj in objectives]
-        if any(
-            obj in objective_names
-            for obj in (
-                "analyze_compliance_controls",
-                "analyze_security_scan_controls",
-                "analyze_support_sla_controls",
-            )
-        ):
-            return True
-
-    return False
-
-
-def has_discovery_evidence(
-    discovery_evidence: dict[str, Any],
-) -> bool:
-    """Check if discovery found relevant repo/files (AC-125.2.3).
-
-    Discovery evidence includes:
-    - docs_search_count > 0
-    - code_search_count > 0
-    - docs_read_count > 0
-    - code_read_count > 0
-    """
-    docs_search = int(discovery_evidence.get("docs_search_count") or 0)
-    code_search = int(discovery_evidence.get("code_search_count") or 0)
-    docs_read = int(discovery_evidence.get("docs_read_count") or 0)
-    code_read = int(discovery_evidence.get("code_read_count") or 0)
-
-    return (docs_search + code_search + docs_read + code_read) > 0
-
-
-def is_code_centric_analysis(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement needs code-centric structural analysis (AC-125.2.4).
-
-    Code-centric analysis is needed when:
-    - Requirement mentions architecture, structure, dependencies
-    - Interpretation indicates code-first route
-    - Requirement is about implementation details
-    """
-    lowered = f"{requirement_text} {requirement_category}".lower()
-
-    code_centric_markers = (
-        "architecture",
-        "structure",
-        "dependency",
-        "module",
-        "service",
-        "implementation",
-        "code",
-        "source",
-        "pattern",
-        "hexagonal",
-        "clean architecture",
-        "domain",
-        "ports",
-        "adapters",
-    )
-
-    if any(marker in lowered for marker in code_centric_markers):
-        return True
-
-    if interpretation:
-        route_hints = str(interpretation.get("route_hint", "") or "").lower()
-        if "code" in route_hints:
-            return True
-
-        analysis_mode = str(interpretation.get("analysis_mode", "") or "").lower()
-        if "code" in analysis_mode:
-            return True
-
-    return False
-
-
-def has_code_navigation_breadth_weakness(
-    requirement_text: str,
-    interpretation: dict[str, Any] | None,
-    discovery_evidence: dict[str, Any] | None,
-) -> bool:
-    """Determine if primary weakness is code-navigation breadth (TSK-125.6).
-
-    Code-navigation breadth weakness is present when:
-    - Requirement needs broad code understanding across multiple files/modules
-    - Discovery evidence shows limited code navigation so far
-    - Interpretation indicates cross-cutting concern or dependency analysis
-
-    This is distinct from:
-    - Deep single-file analysis (not breadth weakness)
-    - Config/docs-heavy requirements (not code-centric)
-    """
-    # Check interpretation for breadth indicators
-    if interpretation:
-        analysis_mode = str(interpretation.get("analysis_mode", "") or "").lower()
-
-        # Breadth indicators
-        breadth_markers = [
-            "dependency",
-            "cross-cutting",
-            "multi-module",
-            "service-mesh",
-            "api-contract",
-            "caller-graph",
-            "callee-graph",
-            "import-chain",
-            "inheritance-tree",
-        ]
-
-        if any(marker in analysis_mode for marker in breadth_markers):
-            return True
-
-        # Check if objective requires breadth
-        objectives = interpretation.get("skill_objectives") or []
-        objective_str = " ".join(str(obj) for obj in objectives).lower()
-        if any(marker in objective_str for marker in breadth_markers):
-            return True
-
-    # Check discovery evidence for limited code navigation
-    if discovery_evidence:
-        code_findings = discovery_evidence.get("code_findings") or []
-        code_read_count = discovery_evidence.get("code_read_count") or 0
-
-        # If we've read very few code files but requirement is code-centric,
-        # it suggests breadth weakness
-        if len(code_findings) <= 2 and code_read_count <= 3:
-            # Double-check with requirement text
-            lowered = requirement_text.lower()
-            if any(marker in lowered for marker in ["multiple", "across", "between", "throughout"]):
-                return True
-
-    return False
-
-
-def check_graph_build_readiness(
-    skill_readiness: dict[str, Any] | None,
-    _repo_path: str | None = None,
-) -> tuple[bool, str | None]:
-    """Check if local graph-build readiness is available (TSK-125.6).
-
-    Graph-build readiness requires:
-    1. Skill is available in skill_readiness
-    2. Skill is policy-eligible
-    3. Skill is runtime-loadable
-    4. Local repo is present (repo_path exists)
-    5. Graph data is available or can be built
-
-    Returns:
-        tuple: (is_ready, blocked_reason)
-    """
-    if not skill_readiness:
-        return False, "skill_readiness_not_provided"
-
-    # Check graph skills readiness list
-    graph_readiness_list = skill_readiness.get("graph_skills_readiness") or []
-
-    for graph_info in graph_readiness_list:
-        if graph_info.get("skill_name") == "code-review-graph-skill":
-            available = graph_info.get("available", False)
-            policy_eligible = graph_info.get("policy_eligible", False)
-            runtime_loadable = graph_info.get("runtime_loadable", False)
-            has_local_repo = graph_info.get("has_local_repo", False)
-            has_graph_data = graph_info.get("has_graph_data", False)
-            prerequisites_met = graph_info.get("prerequisites_met", False)
-
-            # Check each prerequisite and return specific blocked reason
-            if not available:
-                return False, "skill_not_available"
-            if not policy_eligible:
-                return False, "policy_not_eligible"
-            if not runtime_loadable:
-                return False, "runtime_not_loadable"
-            if not has_local_repo:
-                return False, "local_repo_not_found"
-            if not has_graph_data:
-                return False, "graph_data_not_available"
-
-            # All prerequisites met
-            return prerequisites_met, None if prerequisites_met else "prerequisites_not_met"
-
-    # code-review-graph-skill not found in readiness list
-    return False, "skill_not_in_readiness_diagnostics"
-
-
-def is_shared_library_usage_requirement(
-    requirement_text: str,
-    guidance_text: str,
-    _check_id: str | None = None,
-    requirement_type_tag: str | None = None,
-) -> bool:
-    """Determine if requirement needs shared-library usage analysis (Phase 133, CL-003-like rows)."""
-    lowered = f"{requirement_text} {guidance_text}".lower()
-    markers = (
-        "thư viện dùng chung",
-        "lib tập trung",
-        "shared library",
-        "centralized lib",
-        "88724032",
-        "shared infrastructure",
-    )
-    return any(m in lowered for m in markers) or requirement_type_tag == "shared_library"
-
-
-def is_dependency_cycle_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement needs dependency/cycle/shared-library analysis."""
-    lowered = f"{requirement_text} {requirement_category}".lower()
-    row_key = ""
-    check_id = ""
-    if interpretation:
-        row_key = str(
-            interpretation.get("row_key") or interpretation.get("row_id") or interpretation.get("check_id") or ""
-        ).strip()
-        check_id = row_key.split(":", 1)[0].strip().upper() if row_key else ""
-
-    dependency_markers = (
-        "circular dependency",
-        "dependency cycle",
-        "cycle detection",
-        "dependency graph",
-        "dependency/lib",
-        "dependency lib",
-        "service/module",
-        "module/service",
-        "module service",
-        "dùng chung",
-        "dung chung",
-        "lib tập trung",
-        "lib tap trung",
-        "dependency tập trung",
-        "dependency tap trung",
-        "return-path",
-        "return path",
-        "cl-004",
-    )
-    if any(marker in lowered for marker in dependency_markers):
-        return True
-
-    if interpretation:
-        if check_id == "CL-004":
-            return True
-        objectives = interpretation.get("skill_objectives") or []
-        objective_names = [str(obj) for obj in objectives]
-        if "analyze_dependency_cycles" in objective_names:
-            return True
-
-        req_type_tag = str(interpretation.get("requirement_type_tag", "") or "").lower()
-        if req_type_tag in ("dependency", "dependency_cycle"):
-            return True
-
-        analysis_mode = str(interpretation.get("analysis_mode", "") or "").lower()
-        if any(marker in analysis_mode for marker in ("dependency", "cycle", "graph", "decoupling")):
-            return True
-
-        skills_needed_reason = str(interpretation.get("skills_needed_reason", "") or "").lower()
-        if any(marker in skills_needed_reason for marker in ("dependency", "cycle", "decoupling")):
-            return True
-
-    return False
-
-
-def is_architecture_compliance_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement needs architecture compliance analysis (TSK-125.7).
-
-    Architecture compliance analysis is needed when:
-    - Requirement mentions hexagonal architecture, clean architecture, or DDD
-    - Requirement is about layer separation, ports/adapters, or domain independence
-    - Interpretation indicates architecture compliance objective
-    - Requirement is explicitly about architecture pattern compliance
-    """
-    lowered = f"{requirement_text} {requirement_category}".lower()
-
-    # Architecture compliance markers
-    arch_compliance_markers = (
-        "hexagonal",
-        "clean architecture",
-        "ports and adapters",
-        "ports & adapters",
-        "domain-driven",
-        "ddd",
-        "layer separation",
-        "layer violation",
-        "domain independence",
-        "framework-agnostic",
-        "architecture compliance",
-        "architecture pattern",
-        "architecture review",
-    )
-
-    if any(marker in lowered for marker in arch_compliance_markers):
-        return True
-
-    # Check interpretation for architecture compliance objective
-    if interpretation:
-        objectives = interpretation.get("skill_objectives") or []
-        objective_names = [str(obj) for obj in objectives]
-        if "analyze_architecture_compliance" in objective_names:
-            return True
-
-        # Check requirement type tag
-        req_type_tag = str(interpretation.get("requirement_type_tag", "") or "").lower()
-        if req_type_tag in ("architecture", "architecture_pattern", "hexagonal"):
-            return True
-
-        # Check analysis mode
-        analysis_mode = str(interpretation.get("analysis_mode", "") or "").lower()
-        if "architecture" in analysis_mode:
-            return True
-
-    return False
-
-
-def is_public_interface_boundary_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement needs explicit public-interface boundary analysis."""
-    lowered = f"{requirement_text} {requirement_category}".lower()
-
-    public_interface_markers = (
-        "explicit public interface",
-        "interface/contract",
-        "interface contract",
-        "api client",
-        "message contract",
-        "import class implementation",
-        "không import class implementation",
-        "khong import class implementation",
-        "concrete implementation",
-        "concrete class",
-        "public interface",
-        "public contract",
-        "cl-002",
-    )
-
-    if any(marker in lowered for marker in public_interface_markers):
-        return True
-
-    if interpretation:
-        objectives = interpretation.get("skill_objectives") or []
-        objective_names = [str(obj) for obj in objectives]
-        if "analyze_public_interface_boundaries" in objective_names:
-            return True
-
-        req_type_tag = str(interpretation.get("requirement_type_tag", "") or "").lower()
-        if req_type_tag in ("api_contract", "public_interface_boundary"):
-            return True
-
-    return False
-
-
-def is_migration_script_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement should resolve strictly to migration script detection."""
-    lowered = f"{requirement_text} {requirement_category}".lower()
-    migration_markers = (
-        "migration script",
-        "liquibase",
-        "flyway",
-        "db/migration",
-        "db/changelog",
-        "changelog",
-        "schema migration",
-        "versioned sql",
-        "cl-007",
-    )
-    if any(marker in lowered for marker in migration_markers):
-        return True
-    if interpretation:
-        objectives = [str(obj) for obj in (interpretation.get("skill_objectives") or [])]
-        if "analyze_migration_scripts" in objectives:
-            return True
-        req_type_tag = str(interpretation.get("requirement_type_tag", "") or "").lower()
-        if req_type_tag == "migration":
-            return True
-    return False
-
-
-def is_app_config_requirement(
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-) -> bool:
-    """Determine if requirement should resolve strictly to app-config discovery."""
-    lowered = f"{requirement_text} {requirement_category}".lower()
-    app_config_markers = (
-        "app-config",
-        "app config",
-        "repo app-config",
-        "repo app config",
-        "datasource",
-        "datasource.url",
-        "maximum-pool-size",
-        "minimum-idle",
-        "max-lifetime",
-        "separate schema",
-        "separate db instance",
-        "separate database instance",
-        "shared datasource",
-        "shared schema",
-        "shared database",
-        "direct database",
-        "direct db",
-        "gọi trực tiếp vào database",
-        "goi truc tiep vao database",
-        "shared memory",
-        "shared-memory",
-        "application.properties",
-        "application.yml",
-        "application.yaml",
-        "connection pooling",
-        "cl-005",
-        "cl-006",
-        "cl-015",
-    )
-    if any(marker in lowered for marker in app_config_markers):
-        return True
-    if interpretation:
-        if bool(interpretation.get("app_config_only")):
-            return True
-        objectives = [str(obj) for obj in (interpretation.get("skill_objectives") or [])]
-        if any(
-            objective
-            in {
-                "discover_app_config",
-                "resolve_environment_specific_config",
-                "analyze_datasource_isolation",
-                "compare_cross_service_config_separation",
-            }
-            for objective in objectives
-        ):
-            return True
-    return False
-
-
-def recommend_skills_deterministic(
-    *,
-    requirement_text: str,
-    requirement_category: str,
-    interpretation: dict[str, Any] | None,
-    available_skill_names: list[str],
-    skill_readiness: dict[str, Any] | None = None,
-    discovery_evidence: dict[str, Any] | None = None,
-    recommendation_mode: str = "standard",
-    skills_needed: bool = True,
-    limit: int = 3,
-) -> SkillRecommendationResult:
-    """Deterministic skill recommendation logic (TSK-125.2).
-
-    This is the main entry point for skill recommendations, fulfilling all
-    acceptance criteria for TSK-125.2:
-    - AC-125.2.1: Use runtime SkillManager/planner mappings
-    - AC-125.2.2: Prefer research-skill for source-backed research
-    - AC-125.2.3: Admit repomix-skill only after discovery
-    - AC-125.2.4: Admit code-review-graph-skill for code-centric analysis
-    - AC-125.2.5: Recommendation rationale inspectable in telemetry
-    """
-    # Early exit if skills disabled
-    if not skills_needed or recommendation_mode == "disabled":
-        return SkillRecommendationResult(
-            recommendation_mode=recommendation_mode,
-            decision_rationale="Skills disabled by policy or skills_needed=False",
-        )
-
-    if not available_skill_names:
-        return SkillRecommendationResult(
-            recommendation_mode=recommendation_mode,
-            decision_rationale="No available skills configured",
-        )
-
-    # Extract interpretation details
-    interp = dict(interpretation or {})
-    objectives = [str(item).strip() for item in (interp.get("skill_objectives") or []) if str(item).strip()]
-
-    # Build candidate list from objectives
-    candidates: list[str] = []
-    for objective in objectives:
-        candidates.extend(SKILL_OBJECTIVE_PRIORITY.get(objective, ()))
-
-    # AC-125.2.2: Prefer research-skill for source-backed research
-    if (
-        is_source_backed_research_requirement(
-            requirement_text,
-            requirement_category,
-            interp,
-        )
-        and "research-skill" not in candidates
-    ):
-        candidates.insert(0, "research-skill")
-
-    # Infer from markers
-    inferred = infer_skills_from_markers(requirement_text, requirement_category)
-    for skill in inferred:
-        if skill not in candidates:
-            candidates.append(skill)
-
-    # AC-125.2.3: Admit repomix-skill only after discovery
-    discovery = discovery_evidence or {}
-    if has_discovery_evidence(discovery):
-        if "repomix-skill" not in candidates:
-            candidates.append("repomix-skill")
-    else:
-        # Remove repomix if present (no discovery yet)
-        candidates = [c for c in candidates if c != "repomix-skill"]
-
-    # AC-125.2.4: Admit code-review-graph-skill for code-centric analysis
-    # TSK-125.6: Enhanced admission logic with all prerequisites
-    if is_code_centric_analysis(requirement_text, requirement_category, interp):
-        # TSK-125.6: Check all admission criteria
-        # 1. Question is code-centric (already checked above)
-        # 2. Primary weakness is code-navigation breadth
-        # 3. Local graph-build readiness is available
-        # 4. Repo is known (checked via graph readiness)
-
-        has_breadth_weakness = has_code_navigation_breadth_weakness(
-            requirement_text,
-            interp,
-            discovery,
-        )
-
-        graph_ready, graph_blocked_reason = check_graph_build_readiness(
-            skill_readiness,
-            repo_path=None,  # Will be checked in graph readiness diagnostics
-        )
-
-        if has_breadth_weakness and graph_ready:
-            if "code-review-graph-skill" not in candidates:
-                candidates.append("code-review-graph-skill")
-        elif has_breadth_weakness and not graph_ready:
-            # Log why it's not being recommended despite breadth weakness
-            # This will be captured in telemetry
-            logger.debug(
-                "code_review_graph_skill_blocked",
-                blocked_reason=graph_blocked_reason,
-                requirement_category=requirement_category,
-            )
-
-    # TSK-125.7: Admit hexagonal-compliance-skill for architecture compliance requirements
-    if is_architecture_compliance_requirement(requirement_text, requirement_category, interp):
-        # Hexagonal-compliance-skill is authoritative evidence for architecture rows
-        # Insert at beginning to prioritize over other skills
-        if "hexagonal-compliance-skill" not in candidates:
-            candidates.insert(0, "hexagonal-compliance-skill")
-
-    public_interface_requirement = is_public_interface_boundary_requirement(
-        requirement_text, requirement_category, interp
-    )
-    if public_interface_requirement:
-        candidates = ["public-interface-boundary-skill"]
-
-    migration_requirement = is_migration_script_requirement(requirement_text, requirement_category, interp)
-    if migration_requirement:
-        candidates = ["migration-script-detection-skill"]
-
-    app_config_requirement = is_app_config_requirement(requirement_text, requirement_category, interp)
-    if app_config_requirement and not migration_requirement:
-        candidates = ["app-config-discovery-skill"]
-
-    # Phase 133: shared-library usage strict path (CL-003-like rows)
-    shared_library_requirement = is_shared_library_usage_requirement(
-        requirement_text,
-        requirement_category,
-        requirement_type_tag=str(interp.get("requirement_type_tag", "") or "").strip().lower() or None,
-    )
-    if shared_library_requirement and not app_config_requirement and not public_interface_requirement:
-        candidates = ["shared-infrastructure-lib-usage-skill"]
-
-    # Add fallback skills
-    if (
-        not app_config_requirement
-        and not public_interface_requirement
-        and not migration_requirement
-        and not shared_library_requirement
-    ):
-        candidates.extend(SKILL_FALLBACK_PRIORITY)
-
-    # Resolve against available skills
-    recommendations: list[SkillRecommendation] = []
-    seen_skills: set[str] = set()
-
-    for idx, candidate in enumerate(candidates):
-        if len(recommendations) >= limit:
-            break
-
-        resolved = resolve_available_skill_match(candidate, available_skill_names)
-        if not resolved or resolved in seen_skills:
-            continue
-
-        seen_skills.add(resolved)
-
-        # Determine objective fit
-        if idx == 0:
-            objective_fit = "primary"
-        elif idx < len(objectives) + 2:
-            objective_fit = "secondary"
-        else:
-            objective_fit = "fallback"
-
-        # Check prerequisites
-        prerequisites_met = True
-        blocked_reason = None
-
-        # Check skill readiness if available
-        if skill_readiness:
-            effective_skills = skill_readiness.get("effective_available_skills", [])
-            if resolved not in effective_skills:
-                prerequisites_met = False
-                blocked_reason = "not_effective_available"
-
-            graph_readiness_list = skill_readiness.get("graph_skills_readiness", [])
-            for graph_info in graph_readiness_list:
-                if graph_info.get("skill_name") == resolved:
-                    if not graph_info.get("prerequisites_met", False):
-                        prerequisites_met = False
-                        blocked_reason = graph_info.get("blocked_reason", "prerequisites_not_met")
-                    break
-
-        # Build rationale
-        rationale_parts: list[str] = []
-        if objective_fit == "primary":
-            rationale_parts.append("Primary recommendation based on objective")
-        elif objective_fit == "secondary":
-            rationale_parts.append("Secondary recommendation from marker inference")
-        else:
-            rationale_parts.append("Fallback recommendation")
-
-        if resolved == "research-skill" and is_source_backed_research_requirement(
-            requirement_text,
-            requirement_category,
-            interp,
-        ):
-            rationale_parts.append("source-backed research requirement")
-
-        if resolved == "repomix-skill":
-            if has_discovery_evidence(discovery):
-                rationale_parts.append("discovery evidence present")
-            else:
-                rationale_parts.append("WARNING: no discovery evidence")
-
-        if resolved == "code-review-graph-skill":
-            if is_code_centric_analysis(requirement_text, requirement_category, interp):
-                rationale_parts.append("code-centric structural analysis")
-            if has_code_navigation_breadth_weakness(requirement_text, interp, discovery):
-                rationale_parts.append("code-navigation breadth weakness detected")
-            graph_ready, graph_blocked = check_graph_build_readiness(skill_readiness)
-            if graph_ready:
-                rationale_parts.append("graph-build prerequisites met")
-            else:
-                rationale_parts.append(f"WARNING: graph-build not ready: {graph_blocked}")
-            # Explicit note: companion context only, not authoritative evidence
-            rationale_parts.append("COMPANION CONTEXT ONLY - not docs/config grounding proof")
-
-        # TSK-125.7: Rationale for hexagonal-compliance-skill
-        if resolved == "hexagonal-compliance-skill" and is_architecture_compliance_requirement(requirement_text, requirement_category, interp):
-                rationale_parts.append("architecture compliance requirement (authoritative evidence)")
-                # Note about caching for multi-repo analysis
-                rationale_parts.append("supports caching for multi-repo analysis")
-
-        if not prerequisites_met:
-            rationale_parts.append(f"BLOCKED: {blocked_reason}")
-
-        rationale = "; ".join(rationale_parts)
-
-        recommendations.append(
-            SkillRecommendation(
-                skill_name=resolved,
-                priority=idx,
-                rationale=rationale,
-                objective_fit=objective_fit,
-                prerequisites_met=prerequisites_met,
-                blocked_reason=blocked_reason,
-            )
-        )
-
-    # Determine primary and fallbacks
-    primary_skill = None
-    fallback_skills: list[str] = []
-
-    for rec in recommendations:
-        if rec.prerequisites_met:
-            if primary_skill is None:
-                primary_skill = rec.skill_name
-            else:
-                fallback_skills.append(rec.skill_name)
-
-    # Build decision rationale
-    rationale_parts: list[str] = []
-    rationale_parts.append(f"Recommendation mode: {recommendation_mode}")
-    rationale_parts.append(f"Available skills: {len(available_skill_names)}")
-    rationale_parts.append(
-        f"Effective skills: {len(skill_readiness.get('effective_available_skills', [])) if skill_readiness else 'N/A'}"
-    )
-    rationale_parts.append(f"Objectives: {', '.join(objectives) or 'none'}")
-    rationale_parts.append(
-        f"Source-backed: {is_source_backed_research_requirement(requirement_text, requirement_category, interp)}"
-    )
-    rationale_parts.append(f"Discovery evidence: {has_discovery_evidence(discovery)}")
-    rationale_parts.append(f"Code-centric: {is_code_centric_analysis(requirement_text, requirement_category, interp)}")
-    # TSK-125.7: Add architecture compliance to decision rationale
-    rationale_parts.append(
-        f"Architecture compliance: {is_architecture_compliance_requirement(requirement_text, requirement_category, interp)}"
-    )
-    rationale_parts.append(
-        "Public interface boundary: "
-        f"{is_public_interface_boundary_requirement(requirement_text, requirement_category, interp)}"
-    )
-    rationale_parts.append(
-        f"Shared library usage: {is_shared_library_usage_requirement(requirement_text, requirement_category)}"
-    )
-    rationale_parts.append(f"Primary skill: {primary_skill or 'none'}")
-    rationale_parts.append(f"Fallback skills: {', '.join(fallback_skills) or 'none'}")
-
-    decision_rationale = " | ".join(rationale_parts)
-
-    return SkillRecommendationResult(
-        recommended_skills=recommendations,
-        primary_skill=primary_skill,
-        fallback_skills=fallback_skills,
-        recommendation_mode=recommendation_mode,
-        discovery_evidence=dict(discovery),
-        requirement_analysis={
-            "objectives": objectives,
-            "source_backed": is_source_backed_research_requirement(
-                requirement_text,
-                requirement_category,
-                interp,
-            ),
-            "code_centric": is_code_centric_analysis(
-                requirement_text,
-                requirement_category,
-                interp,
-            ),
-            "architecture_compliance": is_architecture_compliance_requirement(
-                requirement_text,
-                requirement_category,
-                interp,
-            ),
-            "public_interface_boundary": is_public_interface_boundary_requirement(
-                requirement_text,
-                requirement_category,
-                interp,
-            ),
-            "migration_script": is_migration_script_requirement(
-                requirement_text,
-                requirement_category,
-                interp,
-            ),
-            "shared_library_usage": is_shared_library_usage_requirement(
-                requirement_text,
-                requirement_category,
-            ),
-            "has_discovery": has_discovery_evidence(discovery),
-        },
-        skill_readiness=dict(skill_readiness or {}),
-        decision_rationale=decision_rationale,
-    )
-
-
-__all__ = [
-    "SKILL_FALLBACK_PRIORITY",
-    "SKILL_MARKER_PATTERNS",
-    "SKILL_OBJECTIVE_PRIORITY",
-    "SkillRecommendation",
-    "SkillRecommendationResult",
-    "build_skill_aliases",
-    "has_discovery_evidence",
-    "infer_skills_from_markers",
-    "is_code_centric_analysis",
-    "is_migration_script_requirement",
-    "is_public_interface_boundary_requirement",
-    "is_shared_library_usage_requirement",
-    "is_source_backed_research_requirement",
-    "normalize_skill_name",
-    "recommend_skills_deterministic",
-    "resolve_available_skill_match",
-]