@ngocsangairvds/vsaf 3.2.13 → 3.2.15

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

@@ -1,2102 +0,0 @@
-"""Shared row evaluator enums, config, and value objects (FR-92 extraction)."""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import re
-from dataclasses import dataclass, field
-from enum import StrEnum
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.engine.instruction_analyzer import InstructionPlan
-
-from vds_agent_core.profiles import resolve_agentic_tool_first_scalar
-
-from vds_audit_orchestrator.config_resolution import build_app_config_discovery_result, discover_config_sources
-from vds_audit_orchestrator.engine.requirement_analysis import requires_app_config_only as _requires_app_config_only
-from vds_audit_orchestrator.models.checklist import EvidenceAnchor, RowProvenance, RowStatus, ScoreBreakdown
-
-# ---------------------------------------------------------------------------
-# Typed RouteDecision model
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class RouteDecision:
-    """Typed route decision replacing raw dict for route metadata.
-
-    Frozen dataclass following the existing pattern in this module.
-    """
-
-    route_id: str
-    route_confidence: float
-    ambiguity_reason_codes: list[str] = field(default_factory=list)
-    route_reason: str = ""
-    required_steps: list[str] = field(default_factory=list)
-    required_tools: list[str] = field(default_factory=list)
-    docs_focused: bool = False
-    code_targets: list[str] = field(default_factory=list)
-    docs_target: bool = False
-    code_target: bool = False
-    route_mode: str = ""
-    override_source: str = "heuristic"
-    override_reason: str = ""
-
-    def to_dict(self) -> dict[str, Any]:
-        """Serialize to dict for backward-compatible context passing."""
-        return {
-            "route_id": self.route_id,
-            "route_confidence": self.route_confidence,
-            "ambiguity_reason_codes": list(self.ambiguity_reason_codes),
-            "route_reason": self.route_reason,
-            "required_steps": list(self.required_steps),
-            "required_tools": list(self.required_tools),
-            "docs_focused": self.docs_focused,
-            "code_targets": list(self.code_targets),
-            "docs_target": self.docs_target,
-            "code_target": self.code_target,
-            "route_mode": self.route_mode,
-            "override_source": self.override_source,
-            "override_reason": self.override_reason,
-        }
-
-    def explain(self) -> str:
-        """Compact human-readable route summary."""
-        markers = f"confidence={self.route_confidence:.2f}"
-        if self.ambiguity_reason_codes:
-            markers += f" ambiguity={self.ambiguity_reason_codes}"
-        return f"route={self.route_id} mode={self.route_mode} {markers}"
-
-
-# ---------------------------------------------------------------------------
-# Route override precedence
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class RouteOverride:
-    """Explicit route override with source tracking.
-
-    Precedence: CLI override > row override map > heuristic route.
-    """
-
-    route_id: str
-    override_source: str  # "cli" | "row_map" | "heuristic"
-    override_reason: str = ""
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "route_id": self.route_id,
-            "override_source": self.override_source,
-            "override_reason": self.override_reason,
-        }
-
-
-def apply_route_override(
-    heuristic: RouteDecision,
-    *,
-    cli_override: str | None = None,
-    row_overrides: dict[str, str] | None = None,
-    row_id: str = "",
-) -> tuple[RouteDecision, RouteOverride | None]:
-    """Apply route override precedence: CLI > row map > heuristic.
-
-    Args:
-        heuristic: The heuristic-derived RouteDecision.
-        cli_override: Global CLI-level route override (highest precedence).
-        row_overrides: Per-row override map {row_id: route_id}.
-        row_id: Current row identifier for row-level lookup.
-
-    Returns:
-        Tuple of (final RouteDecision, RouteOverride metadata or None if no override).
-    """
-    if cli_override:
-        overridden = RouteDecision(
-            route_id=cli_override,
-            route_confidence=1.0,
-            route_reason=f"CLI override: {cli_override}",
-            route_mode=cli_override,
-            ambiguity_reason_codes=heuristic.ambiguity_reason_codes,
-            required_steps=heuristic.required_steps,
-            required_tools=heuristic.required_tools,
-            docs_focused=heuristic.docs_focused,
-            code_targets=heuristic.code_targets,
-            docs_target=heuristic.docs_target,
-            code_target=heuristic.code_target,
-            override_source="cli",
-            override_reason=f"Global CLI override applied: {cli_override}",
-        )
-        override_meta = RouteOverride(
-            route_id=cli_override,
-            override_source="cli",
-            override_reason=f"Global CLI override applied: {cli_override}",
-        )
-        return overridden, override_meta
-
-    if row_overrides and row_id and row_id in row_overrides:
-        row_route = row_overrides[row_id]
-        overridden = RouteDecision(
-            route_id=row_route,
-            route_confidence=1.0,
-            route_reason=f"Row override map: {row_id} -> {row_route}",
-            route_mode=row_route,
-            ambiguity_reason_codes=heuristic.ambiguity_reason_codes,
-            required_steps=heuristic.required_steps,
-            required_tools=heuristic.required_tools,
-            docs_focused=heuristic.docs_focused,
-            code_targets=heuristic.code_targets,
-            docs_target=heuristic.docs_target,
-            code_target=heuristic.code_target,
-            override_source="row_map",
-            override_reason=f"Row-specific override: {row_id} -> {row_route}",
-        )
-        override_meta = RouteOverride(
-            route_id=row_route,
-            override_source="row_map",
-            override_reason=f"Row-specific override: {row_id} -> {row_route}",
-        )
-        return overridden, override_meta
-
-    return heuristic, None
-
-
-# Interpretation marker taxonomy — strict allowlists
-DOCS_MARKER_ALLOWLIST: tuple[str, ...] = (
-    "openapi",
-    "swagger",
-    "sequence diagram",
-    "confluence",
-    "runbook",
-    "architecture document",
-    "api specification",
-    "technical design document",
-)
-
-CODE_MARKER_KEYWORDS: tuple[str, ...] = (
-    "implementation",
-    "source code",
-    "dockerfile",
-    "docker-compose",
-    "kubernetes",
-    "k8s",
-    "helm",
-    "healthcheck",
-    "health endpoint",
-    "metrics endpoint",
-    "liveness",
-    "readiness",
-    "actuator",
-    "unit test",
-    "integration test",
-    "pipeline",
-    "sast",
-    "dast",
-    "security scan",
-)
-
-PROCESS_MARKER_KEYWORDS: tuple[str, ...] = (
-    "sla",
-    "support",
-    "incident",
-    "compliance",
-    "policy",
-    "governance",
-    "regulatory",
-    "approval",
-    "review",
-    "audit",
-    "certification",
-)
-
-DEPLOYMENT_DOCS_SENSITIVE_MARKERS: tuple[str, ...] = (
-    "air-gapped",
-    "air gapped",
-    "offline",
-    "package",
-    "packaging",
-    "install",
-    "internet",
-    "sandbox",
-    "đóng gói",
-    "dong goi",
-    "không cần internet",
-    "khong can internet",
-    "cài đặt",
-    "cai dat",
-)
-
-
-class CheckCategory(StrEnum):
-    """Classification of check types for evaluation strategy."""
-
-    DETERMINISTIC = "deterministic"
-    SEMANTIC = "semantic"
-    HYBRID = "hybrid"
-
-
-DETERMINISTIC_CHECK_TYPES: frozenset[str] = frozenset(
-    {
-        "git_file_exists",
-        "git_file_content",
-        "git_directory_exists",
-        "file_exists",
-        "directory_exists",
-        "bitbucket_branch_permission",
-        "bitbucket_merge_check",
-        "bitbucket_default_reviewers",
-        "bitbucket_repo_settings",
-        "confluence_page_exists",
-        "confluence_attachment_exists",
-        "confluence_link_exists",
-        "sonarqube_quality_gate",
-        "sonarqube_metric",
-        "sonarqube_metric_threshold",
-        "sonarqube_coverage",
-        "sonarqube_bugs",
-        "sonarqube_vulnerabilities",
-        "jira_issue_exists",
-        "jira_issue_linked",
-        "openapi_spec_exists",
-        "openapi_valid",
-        "api_documented",
-        "ci_pipeline_exists",
-        "ci_config_valid",
-        "dockerfile_exists",
-    }
-)
-
-SEMANTIC_CHECK_TYPES: frozenset[str] = frozenset(
-    {
-        "readme_quality",
-        "documentation_quality",
-        "api_docs_quality",
-        "security_docs_quality",
-        "code_documentation",
-        "architecture_alignment",
-        "requirement_coverage",
-        "test_coverage_quality",
-        "compliance_narrative",
-        "llm_content_evaluation",
-        "llm_gap_analysis",
-    }
-)
-
-
-def _classify_check_type(check_type: str) -> CheckCategory:
-    """Classify a check type into its evaluation category."""
-    normalized = check_type.lower().strip()
-
-    if normalized in DETERMINISTIC_CHECK_TYPES:
-        return CheckCategory.DETERMINISTIC
-    if normalized in SEMANTIC_CHECK_TYPES:
-        return CheckCategory.SEMANTIC
-
-    if any(kw in normalized for kw in ["quality", "narrative", "alignment", "coverage_quality"]):
-        return CheckCategory.SEMANTIC
-    if any(kw in normalized for kw in ["exists", "threshold", "metric", "permission", "check"]):
-        return CheckCategory.DETERMINISTIC
-
-    return CheckCategory.HYBRID
-
-
-def is_deterministic(check_type: str) -> bool:
-    """Return True if check can be evaluated without LLM."""
-    return _classify_check_type(check_type) == CheckCategory.DETERMINISTIC
-
-
-def needs_llm(check_type: str, evidence_clarity: float = 1.0) -> bool:
-    """Determine if LLM evaluation is needed."""
-    category = _classify_check_type(check_type)
-
-    if category == CheckCategory.DETERMINISTIC:
-        return evidence_clarity < 0.3
-    if category == CheckCategory.SEMANTIC:
-        return True
-    return evidence_clarity < 0.7
-
-
-class RowLLMMode(StrEnum):
-    """LLM invocation mode for row evaluation."""
-
-    OFF = "off"
-    SELECTIVE = "selective"
-    PER_ROW = "per-row"
-
-
-class ConsistencyRetryMode(StrEnum):
-    """Retry policy for evidence-consistency correction turn."""
-
-    OFF = "off"
-    AUTO = "auto"
-    ALWAYS = "always"
-
-
-class RowUnifiedMode(StrEnum):
-    """Guarded rollout mode for unified row execution path."""
-
-    OFF = "off"
-    ON = "on"
-
-
-@dataclass
-class RowEvaluatorConfig:
-    """Configuration for row-level evaluation."""
-
-    mode: RowLLMMode = RowLLMMode.SELECTIVE
-    protocol: str | None = None
-    model: str | None = None
-    cache_enabled: bool = True
-    confidence_threshold: float = 0.6
-    batch_related_rows: bool = True
-    max_evidence_chars: int = 12000
-    decompose_complex: bool = False
-    consistency_retry_enabled: bool = True
-    consistency_retry_mode: ConsistencyRetryMode = ConsistencyRetryMode.AUTO
-    row_unified_mode: RowUnifiedMode = RowUnifiedMode.ON
-    use_dspy: bool = False
-    dspy_score_tolerance: float = 10.0
-    dspy_confidence_tolerance: float = 0.15
-    dspy_quality_threshold: float = 0.6
-    tool_first_enabled: bool = False
-    tool_first_max_steps: int = field(
-        default_factory=lambda: int(os.getenv("VDS_AUDIT_AGENTIC_TOOL_FIRST_MAX_STEPS", "30"))
-    )
-    tool_first_timeout_seconds: float = field(
-        default_factory=lambda: float(os.getenv("VDS_AUDIT_AGENTIC_TOOL_FIRST_TIMEOUT_SECONDS", "30.0"))
-    )
-    tool_first_budget_units: int = field(
-        default_factory=lambda: int(os.getenv("VDS_AUDIT_AGENTIC_TOOL_FIRST_BUDGET_UNITS", "50"))
-    )
-    tool_calls_limit: int = field(
-        default_factory=lambda: int(resolve_agentic_tool_first_scalar("tool_calls_limit", default=30))
-    )
-    strict_budget: bool = False
-    instruction_mode: str = "minimal"
-    evidence_strategy: str = "tool_first"
-    instruction_language: str = "vi"
-    max_inline_evidence_chars: int = 2000
-    agent_runtime_mode: str | None = None
-    runtime_context: dict[str, Any] = field(default_factory=dict)
-    # P172-E: Per-run control-objective evidence threshold overrides (TSK-172.30)
-    evidence_overrides: dict[str, dict[str, int]] = field(default_factory=dict)
-
-
-def compute_cache_key(
-    template_hash: str,
-    evidence_hash: str,
-    row_id: str,
-    model: str | None = None,
-) -> str:
-    """Compute stable cache key for row evaluation."""
-    key_parts = [template_hash, evidence_hash, row_id]
-    if model:
-        key_parts.append(model)
-    return hashlib.sha256("|".join(key_parts).encode()).hexdigest()[:32]
-
-
-def estimate_evidence_clarity(
-    requirement_text: str,
-    evidence_context: str,
-    evidence_refs: list[str],
-) -> float:
-    """Estimate clarity/completeness of evidence for a requirement."""
-    if not evidence_context.strip():
-        return 0.0
-
-    score = 0.0
-    evidence_len = len(evidence_context)
-    if evidence_len > 2000:
-        score += 0.3
-    elif evidence_len > 500:
-        score += 0.2
-    elif evidence_len > 100:
-        score += 0.1
-
-    ref_count = len(evidence_refs)
-    if ref_count >= 3:
-        score += 0.3
-    elif ref_count >= 1:
-        score += 0.15
-
-    req_words = set(requirement_text.lower().split())
-    evidence_words = set(evidence_context.lower().split())
-    overlap = len(req_words & evidence_words)
-    overlap_ratio = overlap / max(len(req_words), 1)
-    score += min(0.4, overlap_ratio * 0.5)
-
-    return min(1.0, score)
-
-
-def extract_requirement_guidance(config: dict[str, Any]) -> str:
-    """Build normalized requirement guidance text from checklist config.
-
-    The legacy ``evidence_required`` field is no longer included in routing
-    guidance.  It must not influence route decisions.
-
-    Runtime guidance injection gateway securely maps widened schema fields
-    (Hướng dẫn chi tiết, Check = Manual) to enforcement context.
-    """
-    parts: list[str] = []
-    main = str(config.get("confluence_main") or "").strip()
-    if main:
-        parts.append(f"Nội dung chính: {main}")
-    rule = str(config.get("confluence_rule") or "").strip()
-    if rule:
-        parts.append(f"Quy tắc: {rule}")
-
-    guidance = str(config.get("detailed_guidance") or config.get("confluence_notes") or "").strip()
-    if guidance:
-        parts.append(f"Hướng dẫn chi tiết: {guidance}")
-
-    check_manual = str(config.get("check_manual") or "").strip()
-    if check_manual:
-        parts.append(f"Check = Manual: {check_manual}")
-
-    evidence_hint = str(config.get("confluence_evidence_hint") or "").strip()
-    if evidence_hint:
-        parts.append(f"Minh chứng kỳ vọng: {evidence_hint}")
-    # Legacy evidence_required fallback removed from routing path.
-    # The hint must no longer influence route decisions.
-    return "\n".join(parts)
-
-
-def extract_disambiguation_hint(config: dict[str, Any]) -> str:
-    """Extract optional domain clarification hint from checklist config."""
-    return str(config.get("disambiguation_hint") or config.get("confluence_disambiguation_hint") or "").strip()
-
-
-_CONFIG_ENV_ALIAS_ORDER: tuple[tuple[str, tuple[str, ...]], ...] = (
-    ("preprod", ("pre-production", "pre production", "preprod", "pre_prod", "preprodution")),
-    ("production", ("production", "prod")),
-    ("staging", ("staging", "stage")),
-    ("uat", ("uat",)),
-    ("sit", ("sit",)),
-    ("qa", ("qa",)),
-    ("alpha", ("alpha",)),
-    ("beta", ("beta",)),
-    ("development", ("development", "dev")),
-    ("test", ("test",)),
-    ("sandbox", ("sandbox",)),
-    ("local", ("local",)),
-)
-_CONFIG_ENV_TOKEN_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = tuple(
-    (
-        canonical,
-        re.compile(r"(?<![a-z0-9])(?:" + "|".join(re.escape(alias.lower()) for alias in aliases) + r")(?![a-z0-9])"),
-    )
-    for canonical, aliases in _CONFIG_ENV_ALIAS_ORDER
-)
-
-
-def requires_app_config_only(*texts: Any) -> bool:
-    """Return True when row guidance explicitly narrows work to app-config."""
-
-    combined = "\n".join(str(text or "").strip() for text in texts if str(text or "").strip())
-    return _requires_app_config_only(combined)
-
-
-def extract_required_config_environments(*texts: Any) -> list[str]:
-    """Extract normalized config-environment hints from guidance text.
-
-    The parser intentionally stays lightweight and only returns environments
-    when the guidance names them explicitly. This keeps routing deterministic
-    while still allowing downstream evidence selection to honor requirements
-    like "môi trường production".
-    """
-
-    combined = "\n".join(str(text or "").strip() for text in texts if str(text or "").strip())
-    if not combined:
-        return []
-
-    lowered = combined.lower()
-    ordered_envs: list[tuple[int, str]] = []
-    for canonical, pattern in _CONFIG_ENV_TOKEN_PATTERNS:
-        for match in pattern.finditer(lowered):
-            ordered_envs.append((match.start(), canonical))
-
-    ordered_envs.sort(key=lambda item: item[0])
-    unique_envs: list[str] = []
-    for _, canonical in ordered_envs:
-        if canonical not in unique_envs:
-            unique_envs.append(canonical)
-    return unique_envs
-
-
-def _is_doc_like_ref(ref: str) -> bool:
-    raw_value = ref.strip().lower()
-    value = _normalize_ref_for_type_detection(raw_value)
-    if not value:
-        return False
-    if raw_value.startswith("chunk:"):
-        return True
-    if "://" in raw_value:
-        return True
-    if value.startswith("docs/") or "/docs/" in value:
-        return True
-    return bool(re.search(r"\.(md|markdown|rst|adoc|txt)$", value))
-
-
-def _normalize_ref_for_type_detection(ref: str) -> str:
-    value = str(ref or "").strip().lower()
-    if not value:
-        return ""
-    for prefix in ("code:", "doc:"):
-        if value.startswith(prefix):
-            value = value[len(prefix) :]
-            break
-    value = value.split("?", 1)[0]
-    value = value.split("#", 1)[0]
-    value = re.sub(r":\d+(?::\d+)?$", "", value)
-    return value
-
-
-def _is_code_like_ref(ref: str) -> bool:
-    value = _normalize_ref_for_type_detection(ref)
-    if not value or _is_doc_like_ref(value):
-        return False
-    infra_file_names = {"dockerfile", "containerfile", "makefile", "jenkinsfile"}
-    normalized = value.strip("/").lower()
-    if normalized in infra_file_names:
-        return True
-    if any(normalized.endswith(f"/{name}") for name in infra_file_names):
-        return True
-    return bool(
-        re.search(
-            r"\.(py|java|kt|kts|js|ts|tsx|jsx|go|rs|cpp|cc|c|h|hpp|yaml|yml|json|toml|xml|sql|sh)$",
-            value,
-        )
-    )
-
-
-def _is_deployment_docs_sensitive_requirement(requirement_text: str, requirement_category: str) -> bool:
-    combined = f"{requirement_text or ''} {requirement_category or ''}".lower()
-    return any(marker in combined for marker in DEPLOYMENT_DOCS_SENSITIVE_MARKERS)
-
-
-_GUIDANCE_SKIP_CLASSIFIERS: tuple[tuple[str, str, tuple[str, ...]], ...] = (
-    ("manual_required", "guidance_phrase:con_nguoi_lam", ("con người làm",)),
-    (
-        "infra_provided",
-        "guidance_phrase:infra_handled",
-        ("đã được xử lý ở tầng infra riêng", "không cần đánh giá"),
-    ),
-    (
-        "infra_provided",
-        "guidance_phrase:internal_system_guarantee",
-        ("mặc định đã được đảm bảo bởi hệ thống nội bộ",),
-    ),
-    (
-        "infra_provided",
-        "guidance_phrase:ci_cd_guarantee",
-        ("tiêu chí này đã có từ đầu ci/cd", "không cần đánh giá"),
-    ),
-    (
-        "infra_provided",
-        "guidance_phrase:ktdv_infra_support",
-        ("tiêu chí này đã được hỗ trợ bởi hạ tầng", "đơn vị ktdv", "không cần kiểm tra"),
-    ),
-    (
-        "quality_control_managed",
-        "guidance_phrase:quality_control_flow",
-        ("mặc định fail", "kiểm soát chất lượng"),
-    ),
-)
-
-
-def _normalize_guidance_skip_text(value: str) -> str:
-    text = " ".join(str(value or "").strip().lower().split())
-    text = text.replace(" ,", ",")
-    return text
-
-
-def _classify_guidance_skip(*texts: str) -> tuple[bool, str | None, str, str]:
-    for raw_text in texts:
-        source_text = str(raw_text or "").strip()
-        if not source_text:
-            continue
-        normalized = _normalize_guidance_skip_text(source_text)
-        for decision, reason, markers in _GUIDANCE_SKIP_CLASSIFIERS:
-            if all(marker in normalized for marker in markers):
-                return True, decision, source_text, reason
-    return False, None, "", ""
-
-
-def _infer_code_targets_from_requirement(requirement_text: str, requirement_category: str) -> list[str]:
-    combined = f"{requirement_text or ''} {requirement_category or ''}".lower()
-    inferred: list[str] = []
-    migration_requirement = any(
-        marker in combined
-        for marker in (
-            "flyway",
-            "liquibase",
-            "migration",
-            "migrate",
-            "changelog",
-            "changeset",
-            "db/migration",
-        )
-    )
-    architecture_exclusion_markers = (
-        "hexagonal",
-        "clean architecture",
-        "domain logic",
-        "ports & adapters",
-        "ports and adapters",
-        "framework",
-        "org.springframework",
-        "javax.persistence",
-        "ui layer",
-        "infrastructure layer",
-    )
-    if any(marker in combined for marker in ("dockerfile", "multi-stage", "multi stage", "container image")):
-        inferred.append("Dockerfile")
-    if "containerfile" in combined:
-        inferred.append("Containerfile")
-    if any(marker in combined for marker in ("docker compose", "docker-compose", "compose.yml", "compose.yaml")):
-        inferred.extend(["docker-compose.yml", "docker-compose.yaml"])
-    if any(marker in combined for marker in ("k8s", "kubernetes", "deployment.yaml", "readiness", "liveness")):
-        inferred.append("k8s/deployment.yaml")
-    if "helm" in combined:
-        inferred.extend(["helm/Chart.yaml", "helm/values.yaml"])
-    gateway_requirement = any(
-        marker in combined for marker in ("api gateway", "gateway", "rate limiting", "rate limit")
-    )
-    if gateway_requirement:
-        inferred.extend(
-            [
-                "AuthenticationFilter.java",
-                "RestTemplateConfig.java",
-                "RateLimitFilter.java",
-                "GatewayFilter.java",
-                "GatewayConditionMultiApi.java",
-                "AuthorizationFilter.java",
-                "GatewayConfig.java",
-                "ApiGatewayConfig.java",
-            ]
-        )
-    explicit_public_interface_requirement = any(
-        marker in combined
-        for marker in (
-            "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",
-        )
-    )
-    if explicit_public_interface_requirement:
-        inferred.extend(
-            [
-                "Service.java",
-                "ApiClient.java",
-                "FeignClient.java",
-                "MessageContract.java",
-                "Contract.java",
-                "Client.java",
-            ]
-        )
-    if migration_requirement:
-        inferred.extend(
-            [
-                "src/main/resources/db/migration",
-                "src/main/resources/db/changelog",
-                "src/main/resources/application.properties",
-                "src/main/resources/application.yml",
-                "src/main/resources/application.yaml",
-                "src/main/resources/bootstrap.properties",
-                "src/main/resources/bootstrap.yml",
-                "src/main/resources/bootstrap.yaml",
-                "db/migration",
-                "db/changelog",
-                "migrations",
-                "migration",
-                "liquibase",
-                "flyway",
-                "pom.xml",
-                "build.gradle",
-                "build.gradle.kts",
-                "application.properties",
-                "application.yml",
-                "application.yaml",
-                "bootstrap.properties",
-                "bootstrap.yml",
-                "bootstrap.yaml",
-                "changelog.xml",
-                "changelog.yaml",
-                "changelog.yml",
-                "changelog.json",
-            ]
-        )
-    db_decoupling_requirement = any(
-        marker in combined
-        for marker in (
-            "schema",
-            "datasource",
-            "database",
-            "db instance",
-            "connection string",
-            "cross-schema",
-            "cross schema",
-            "native query",
-            "join",
-            "jdbctemplate",
-            "createnativequery",
-        )
-    )
-    if db_decoupling_requirement and not any(marker in combined for marker in architecture_exclusion_markers):
-        inferred.extend(
-            [
-                "application.properties",
-                "DatabaseConfig.java",
-                "DataSourceConfig.java",
-                "Repository.java",
-                "application.yml",
-                "application.yaml",
-                "bootstrap.properties",
-                "bootstrap.yml",
-                "bootstrap.yaml",
-            ]
-        )
-    config_separation_requirement = any(
-        marker in combined for marker in ("configuration", "config", "cấu hình", "cau hinh")
-    ) and any(
-        marker in combined for marker in ("business", "nghiệp vụ", "nghiep vu", "technical", "kỹ thuật", "ky thuat")
-    )
-    if config_separation_requirement:
-        inferred.extend(
-            [
-                "application.properties",
-                "application.yml",
-                "application.yaml",
-                "bootstrap.properties",
-                "bootstrap.yml",
-                "bootstrap.yaml",
-                "AppConfig.java",
-                "ApplicationConfig.java",
-                "Config.java",
-            ]
-        )
-    return list(dict.fromkeys(target for target in inferred if target))
-
-
-def _clamp_unit(value: float) -> float:
-    return max(0.0, min(1.0, float(value)))
-
-
-def _extract_trace_ref_values(retrieval_trace: dict[str, Any] | None) -> list[str]:
-    if not isinstance(retrieval_trace, dict):
-        return []
-
-    refs: list[str] = []
-
-    def _append_ref(candidate: Any) -> None:
-        if isinstance(candidate, str):
-            value = candidate.strip()
-            if value:
-                refs.append(value)
-            return
-        if not isinstance(candidate, dict):
-            return
-        for key in ("source_path", "source_url", "ref_value", "ref", "path"):
-            raw = candidate.get(key)
-            if not raw:
-                continue
-            value = str(raw).strip()
-            if value:
-                refs.append(value)
-            return
-
-    docs_trace = retrieval_trace.get("docs")
-    if isinstance(docs_trace, dict):
-        top_k = docs_trace.get("top_k")
-        if isinstance(top_k, list):
-            for item in top_k:
-                _append_ref(item)
-    elif isinstance(docs_trace, list):
-        for item in docs_trace:
-            _append_ref(item)
-
-    code_trace = retrieval_trace.get("code")
-    if isinstance(code_trace, dict):
-        top_k = code_trace.get("top_k")
-        if isinstance(top_k, list):
-            for item in top_k:
-                _append_ref(item)
-
-    tool_loop = retrieval_trace.get("tool_first_loop")
-    if isinstance(tool_loop, dict):
-        evidence_refs = tool_loop.get("evidence_refs")
-        if isinstance(evidence_refs, list):
-            for item in evidence_refs:
-                _append_ref(item)
-        trace_steps = tool_loop.get("trace_steps")
-        if isinstance(trace_steps, list):
-            for step in trace_steps:
-                if not isinstance(step, dict):
-                    continue
-                output = step.get("output")
-                if not isinstance(output, dict):
-                    continue
-                for key in (
-                    "read_ref",
-                    "ref_value",
-                    "ref",
-                    "doc_id",
-                    "source_path",
-                    "source_url",
-                    "file_path",
-                    "path",
-                ):
-                    _append_ref(output.get(key))
-                chunk_id = output.get("chunk_id")
-                chunk_value = str(chunk_id or "").strip()
-                if chunk_value:
-                    if chunk_value.startswith("chunk:"):
-                        refs.append(chunk_value)
-                    else:
-                        refs.append(f"chunk:{chunk_value}")
-                hits = output.get("hits")
-                if isinstance(hits, list):
-                    for hit in hits:
-                        _append_ref(hit)
-                        if isinstance(hit, dict):
-                            for key in (
-                                "read_ref",
-                                "ref_value",
-                                "ref",
-                                "doc_id",
-                                "source_path",
-                                "source_url",
-                                "file_path",
-                                "path",
-                            ):
-                                _append_ref(hit.get(key))
-                            hit_chunk = str(hit.get("chunk_id") or "").strip()
-                            if hit_chunk:
-                                if hit_chunk.startswith("chunk:"):
-                                    refs.append(hit_chunk)
-                                else:
-                                    refs.append(f"chunk:{hit_chunk}")
-
-    return list(dict.fromkeys(refs))
-
-
-def compute_requirement_coverage_metrics(
-    *,
-    score_breakdown: ScoreBreakdown,
-    evidence_anchors: list[EvidenceAnchor],
-    retrieval_trace: dict[str, Any] | None = None,
-) -> dict[str, float]:
-    """Compute additive coverage metrics for row finalize stage."""
-    anchor_refs = [str(anchor.ref_value).strip() for anchor in evidence_anchors if str(anchor.ref_value).strip()]
-    trace_refs = _extract_trace_ref_values(retrieval_trace)
-    all_refs = list(dict.fromkeys(anchor_refs + trace_refs))
-
-    doc_refs = [ref for ref in all_refs if _is_doc_like_ref(ref)]
-    code_refs = [ref for ref in all_refs if _is_code_like_ref(ref)]
-    total_refs = len(all_refs)
-
-    docs_ratio = (len(doc_refs) / total_refs) if total_refs else 0.0
-    code_ratio = (len(code_refs) / total_refs) if total_refs else 0.0
-    evidence_presence = 1.0 if total_refs > 0 else 0.0
-
-    base_coverage = _clamp_unit(getattr(score_breakdown, "coverage_factor", 0.0))
-    confidence = _clamp_unit(getattr(score_breakdown, "confidence_factor", 0.0))
-    coverage_requirements = _clamp_unit(base_coverage * evidence_presence)
-
-    return {
-        "coverage_requirements": round(coverage_requirements, 4),
-        "coverage_code": round(_clamp_unit(code_ratio), 4),
-        "coverage_docs": round(_clamp_unit(docs_ratio), 4),
-        "coverage_confidence": round(confidence, 4),
-    }
-
-
-_NON_REPO_IDENTITY_FILENAMES = frozenset(
-    {
-        "application.properties",
-        "application.yml",
-        "application.yaml",
-        "bootstrap.properties",
-        "bootstrap.yml",
-        "bootstrap.yaml",
-        "values.yml",
-        "values.yaml",
-        "configmap.yml",
-        "configmap.yaml",
-        "secret.yml",
-        "secret.yaml",
-    }
-)
-
-
-_NON_REPO_IDENTITY_SEGMENTS = frozenset(
-    {
-        "application",
-        "bootstrap",
-        "values",
-        "configmap",
-        "secret",
-        "resources",
-        "database",
-        "datasource",
-        "schema",
-        "shared",
-        "memory",
-        "service",
-        "module",
-    }
-)
-
-
-def _is_plausible_repo_identity(value: str | None) -> bool:
-    text = str(value or "").strip()
-    if not text:
-        return False
-    lowered = text.casefold()
-    if lowered in {"unknown-repo", "unknown", "uncategorized", "n/a", "none"}:
-        return False
-    if lowered in _NON_REPO_IDENTITY_FILENAMES or lowered in _NON_REPO_IDENTITY_SEGMENTS:
-        return False
-    if any(token in lowered for token in ("decoupling", "architecture", "documentation", "security")):
-        return False
-    if text.startswith(("#", "-")):
-        return False
-    if "/" in text or "\\" in text:
-        return False
-    if "." in text:
-        suffix = text.rsplit(".", 1)[-1].casefold()
-        if suffix in {
-            "java",
-            "kt",
-            "kts",
-            "groovy",
-            "xml",
-            "yml",
-            "yaml",
-            "properties",
-            "json",
-            "conf",
-            "cfg",
-            "ini",
-            "sh",
-            "md",
-            "txt",
-        }:
-            return False
-    if not re.fullmatch(r"[A-Za-z0-9._-]+", text):
-        return False
-    return any(char.isalpha() for char in text)
-
-
-_GENERIC_REPO_PATH_SEGMENTS = frozenset(
-    {
-        "src",
-        "source",
-        "main",
-        "test",
-        "tests",
-        "docs",
-        "doc",
-        "config",
-        "configs",
-        "resources",
-        "production",
-        "prod",
-        "uat",
-        "sit",
-        "stg",
-        "staging",
-        "dev",
-        "development",
-        "local",
-        "shared",
-    }
-)
-
-
-def _repo_identity_from_path_like(value: str | None) -> str | None:
-    text = str(value or "").strip()
-    if not text:
-        return None
-    normalized = text.replace("\\", "/")
-    parts = [part.strip() for part in normalized.split("/") if part.strip() and part.strip() not in {".", ".."}]
-    if not parts:
-        return None
-    for index, part in enumerate(parts[:-1]):
-        if part.casefold().endswith("-project"):
-            candidate = parts[index + 1].strip()
-            if _is_plausible_repo_identity(candidate):
-                return candidate
-    trimmed_parts = [part for part in parts if part.casefold() not in _GENERIC_REPO_PATH_SEGMENTS]
-    search_parts = trimmed_parts[:-1] if trimmed_parts and "." in trimmed_parts[-1] else trimmed_parts
-    for candidate in reversed(search_parts):
-        if _is_plausible_repo_identity(candidate):
-            return candidate
-    first = trimmed_parts[0] if trimmed_parts else ""
-    return first if _is_plausible_repo_identity(first) else None
-
-
-def _derive_target_repo_identity(
-    *,
-    requirement_text: str,
-    requirement_category: str | None,
-    check_config: dict[str, Any] | None,
-    evidence_refs: list[str] | None,
-    inferred_code_targets: list[str] | None,
-) -> str:
-    config = dict(check_config or {})
-    direct_candidates = [
-        config.get("repo_slug"),
-        config.get("repo_name"),
-        config.get("repo_key"),
-        config.get("repository"),
-        config.get("repository_name"),
-        config.get("service_name"),
-        config.get("service"),
-    ]
-    for candidate in direct_candidates:
-        text = str(candidate or "").strip()
-        if _is_plausible_repo_identity(text):
-            return text
-
-    path_like_candidates = [
-        config.get("repo_path"),
-        config.get("repo_root"),
-        config.get("repository_path"),
-        *list(evidence_refs or []),
-        *list(inferred_code_targets or []),
-    ]
-    for candidate in path_like_candidates:
-        derived = _repo_identity_from_path_like(str(candidate or "").strip())
-        if derived and _is_plausible_repo_identity(derived):
-            return derived
-
-    requirement = str(requirement_text or "").strip()
-    category = str(requirement_category or "").strip()
-    named_requirement_match = re.search(r"\b([A-Za-z][A-Za-z0-9_-]{2,})\b", requirement)
-    if named_requirement_match:
-        possible = str(named_requirement_match.group(1) or "").strip()
-        if _is_plausible_repo_identity(possible) and possible.casefold() != category.casefold():
-            return possible
-
-    return "unknown-repo"
-
-
-def build_requirement_interpretation(
-    *,
-    requirement_text: str,
-    requirement_category: str | None,
-    requirement_guidance: str | None,
-    evidence_refs: list[str] | None = None,
-    check_config: dict[str, Any] | None = None,
-    instruction_plan: InstructionPlan | None = None,
-) -> dict[str, Any]:
-    """Build a normalized row requirement interpretation artifact.
-
-    When *instruction_plan* is provided and carries valid directives or
-    scoring criteria, its structured fields supersede the heuristic routing
-    for ``evidence_targets``, ``skill_objectives``, ``skills_needed``, and
-    ``acceptance_signals`` (DD-122.16).
-    """
-    requirement = str(requirement_text or "").strip()
-    category = str(requirement_category or "").strip()
-    guidance = str(requirement_guidance or "").strip()
-    refs = [str(ref).strip() for ref in (evidence_refs or []) if str(ref).strip()]
-    config = dict(check_config or {})
-
-    guidance_skill_lines = [
-        line.strip()
-        for line in guidance.splitlines()
-        if line.strip() and not line.strip().lower().startswith("quy tắc:")
-    ]
-    app_config_only = requires_app_config_only(
-        requirement,
-        guidance,
-        config.get("detailed_guidance"),
-        config.get("confluence_notes"),
-    )
-    if app_config_only:
-        required_config_environments = extract_required_config_environments(
-            guidance,
-            config.get("detailed_guidance"),
-        )
-        if not required_config_environments:
-            required_config_environments = extract_required_config_environments(
-                config.get("confluence_notes"),
-                extract_disambiguation_hint(config),
-            )
-    else:
-        required_config_environments = extract_required_config_environments(
-            guidance,
-            config.get("detailed_guidance"),
-            config.get("confluence_notes"),
-            extract_disambiguation_hint(config),
-        )
-    lowered_requirement = f"{requirement} {' '.join(guidance_skill_lines)}".lower().strip()
-    lowered_category = category.lower()
-    lowered = f"{lowered_category} {requirement.lower()} {guidance.lower()}".strip()
-    risk_focus = (
-        "security"
-        if any(
-            kw in lowered
-            for kw in (
-                "security",
-                "auth",
-                "authentication",
-                "authorization",
-                "vulnerability",
-                "token",
-                "sast",
-                "dast",
-                "quét lỗ hổng",
-                "quet lo hong",
-                "kiểm thử bảo mật",
-                "kiem thu bao mat",
-            )
-        )
-        else "quality"
-    )
-
-    doc_refs = [ref for ref in refs if _is_doc_like_ref(ref)]
-    code_refs = [ref for ref in refs if _is_code_like_ref(ref)]
-    evidence_targets: list[str] = []
-
-    security_control_markers = (
-        "sast",
-        "dast",
-        "vulnerability",
-        "critical",
-        "high/critical",
-        "security scan",
-        "quét lỗ hổng",
-        "quet lo hong",
-        "kiem thu bao mat",
-        "kiểm thử bảo mật",
-    )
-    has_security_control_signal = any(marker in lowered_requirement for marker in security_control_markers)
-    implementation_code_markers = (
-        "/health",
-        "/metrics",
-        "prometheus",
-        "health endpoint",
-        "metrics endpoint",
-        "healthcheck",
-        "liveness",
-        "readiness",
-        "actuator",
-        "dashboard",
-        "bảng điều khiển",
-        "bang dieu khien",
-    )
-    has_implementation_code_signal = any(marker in lowered for marker in implementation_code_markers)
-    explicit_docs_requirement_markers = (
-        "tài liệu",
-        "documentation",
-        "runbook",
-        "guideline",
-        "guide",
-        "hướng dẫn",
-        "huong dan",
-        "grafana",
-        "openapi",
-        "swagger",
-        "policy",
-        "quy trình",
-        "quy trinh",
-    )
-    has_explicit_docs_requirement_signal = any(
-        marker in lowered_requirement for marker in explicit_docs_requirement_markers
-    )
-    migration_requirement = any(
-        marker in lowered_requirement or marker in lowered_category
-        for marker in (
-            "flyway",
-            "liquibase",
-            "migration",
-            "migrate",
-            "changelog",
-            "changeset",
-        )
-    )
-
-    # Documentation-only routing must be driven by explicit artifact intent.
-    # Broad domain terms (e.g., architecture/SLA/support) can still represent
-    # implementation checks and should not force docs-only evidence targets.
-    docs_domain_markers = (
-        "tài liệu",
-        "documentation",
-        "runbook",
-        "guideline",
-        "guide",
-        "hướng dẫn",
-        "huong dan",
-        "openapi",
-        "swagger",
-        "postman",
-        "sequence diagram",
-        "data flow",
-        "screenshot",
-        "troubleshooting",
-        "wiki",
-        "gitbook",
-        "confluence",
-        "mttr",
-    )
-    docs_domain_signal = any(kw in lowered for kw in docs_domain_markers)
-    has_code_marker_signal = any(marker in lowered for marker in CODE_MARKER_KEYWORDS)
-    has_docs_marker_signal = any(marker in lowered for marker in DOCS_MARKER_ALLOWLIST)
-    has_semantic_code_signal = has_security_control_signal or has_implementation_code_signal or has_code_marker_signal
-    is_docs_only_domain = docs_domain_signal and not has_security_control_signal and not has_implementation_code_signal
-    deployment_docs_sensitive = _is_deployment_docs_sensitive_requirement(requirement, category)
-    infra_or_deployment_signal = deployment_docs_sensitive or any(
-        marker in lowered
-        for marker in (
-            "dockerfile",
-            "containerfile",
-            "kubernetes",
-            "k8s",
-            "helm",
-            "terraform",
-            "deployment",
-            "triển khai",
-            "trien khai",
-        )
-    )
-    has_semantic_docs_signal = (
-        is_docs_only_domain
-        or deployment_docs_sensitive
-        or has_explicit_docs_requirement_signal
-        or has_docs_marker_signal
-    )
-    project_scope_required = (
-        any(
-            marker in lowered
-            for marker in (
-                "dependency graph",
-                "circular dependency",
-                "dependency cycle",
-                "cycle trong dependency graph",
-                "dependency/lib",
-                "dependency lib",
-                "modules/services",
-                "service/module",
-                "module/service",
-                "dùng chung",
-                "dung chung",
-                "lib tập trung",
-                "lib tap trung",
-                "dependency tập trung",
-                "dependency tap trung",
-            )
-        )
-        and not infra_or_deployment_signal
-    )
-
-    # Route targeting should primarily follow requirement semantics, while
-    # matcher seed refs are only tie-breakers for ambiguous rows.
-    if has_semantic_docs_signal or (doc_refs and not has_semantic_code_signal):
-        evidence_targets.append("docs")
-
-    if (
-        has_semantic_code_signal
-        or (code_refs and not has_semantic_docs_signal)
-        or (not evidence_targets and not doc_refs)
-    ):
-        evidence_targets.append("code")
-
-    if has_implementation_code_signal and not has_explicit_docs_requirement_signal and not deployment_docs_sensitive:
-        evidence_targets = [target for target in evidence_targets if target != "docs"]
-
-    if app_config_only or migration_requirement:
-        evidence_targets = ["code"]
-
-    evidence_targets = ["code", "docs"] if not evidence_targets else list(dict.fromkeys(evidence_targets))
-
-    skill_objective_keywords: dict[str, tuple[str, ...]] = {
-        # Advisory-only signal: can help, but should not force a strict skill path.
-        "analyze_operational_readiness": (
-            "sizing",
-            "capacity",
-            "performance",
-            "load test",
-            "stress test",
-            "benchmark",
-        ),
-        # Strong signal: documentation artifact checks benefit from domain playbooks/runbooks.
-        "analyze_documentation_artifacts": (
-            "sequence diagram",
-            "data flow",
-            "technical specs",
-            "swagger",
-            "openapi",
-            "postman",
-            "sandbox",
-            "troubleshooting",
-            "user manual",
-            "hướng dẫn sử dụng",
-            "huong dan su dung",
-            "mttr",
-        ),
-        # Strong signal: requirement is typically process/tooling heavy.
-        "analyze_support_sla_controls": (
-            "sla",
-            "support",
-            "incident",
-            "oncall",
-            "runbook",
-            "quy trình",
-            "quy trinh",
-        ),
-        "analyze_compliance_controls": (
-            "compliance",
-            "policy",
-            "regulatory",
-            "governance",
-            "kiểm soát",
-            "kiem soat",
-        ),
-        "analyze_security_scan_controls": (
-            "sast",
-            "dast",
-            "security scan",
-            "vulnerability scan",
-            "critical",
-            "high/critical",
-            "quét lỗ hổng",
-            "quet lo hong",
-        ),
-        "analyze_tooling_automation_guidance": (
-            "workflow",
-            "orchestrator",
-            "playbook",
-            "cli",
-            "command",
-            "tooling",
-            "lsp",
-            "mypy",
-            "pyright",
-            "ruff",
-            "uv",
-            "typer",
-            "confluence",
-            "bitbucket",
-            "grafana",
-            "bpmn",
-            "automation",
-            "script",
-            "sync",
-            "integration guide",
-            "documentation process",
-        ),
-        "analyze_migration_scripts": (
-            "migration",
-            "migration script",
-            "liquibase",
-            "flyway",
-            "db/migration",
-            "db/changelog",
-            "changelog",
-            "schema evolution",
-            "versioned sql",
-        ),
-        "analyze_dependency_cycles": (
-            "circular dependency",
-            "dependency cycle",
-            "dependency graph",
-            "dependency/lib",
-            "dependency lib",
-            "shared-library",
-            "shared library",
-            "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",
-            "chu trình phụ thuộc",
-            "chu trinh phu thuoc",
-            "phụ thuộc vòng tròn",
-            "phu thuoc vong tron",
-        ),
-        # Phase 133: shared-library usage analysis (CL-003-like rows)
-        "analyze_shared_library_usage": (
-            "shared library",
-            "shared-library",
-            "thư viện dùng chung",
-            "lib tập trung",
-            "dependency tập trung",
-            "centralized lib",
-            "common-lib",
-            "LIB project",
-            "88724032",
-            "dùng chung",
-            "shared infrastructure",
-        ),
-        "analyze_architecture_compliance": (
-            "hexagonal",
-            "clean architecture",
-            "ports & adapters",
-            "ports and adapters",
-            "domain logic",
-            "domain independence",
-            "framework-agnostic",
-            "framework agnostic",
-            "domain-driven",
-            "ddd",
-            "kiến trúc sạch",
-            "kien truc sach",
-        ),
-        "analyze_public_interface_boundaries": (
-            "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",
-        ),
-        "discover_app_config": (
-            "app-config",
-            "app config",
-            "application.yml",
-            "application.yaml",
-            "application.properties",
-            "configmap",
-            "helm",
-            "environment config",
-            "production config",
-        ),
-        "resolve_environment_specific_config": (
-            "prod",
-            "production",
-            "uat",
-            "sit",
-            "stg",
-            "staging",
-            "dev",
-            "profile-specific",
-            "môi trường",
-            "moi truong",
-        ),
-        "analyze_datasource_isolation": (
-            "datasource",
-            "schema",
-            "db instance",
-            "database instance",
-            "pool limit",
-            "maximum-pool-size",
-            "minimum-idle",
-            "max-lifetime",
-            "separate schema",
-            "separate database",
-        ),
-        "compare_cross_service_config_separation": (
-            "shared datasource",
-            "shared schema",
-            "shared database",
-            "shared memory",
-            "shared-memory",
-            "direct database",
-            "direct db",
-            "gọi trực tiếp vào database",
-            "goi truc tiep vao database",
-            "cross-service config",
-            "separate schema",
-            "separate db instance",
-        ),
-    }
-    # Keep documentation artifact signals advisory by default. In practice these
-    # rows are often grounded effectively via docs/code tools and forcing strict
-    # execution-class skill calls increases discovery churn without evidence gain.
-    strict_skill_objectives = frozenset(
-        {
-            "analyze_support_sla_controls",
-            "analyze_compliance_controls",
-            "analyze_security_scan_controls",
-            "analyze_tooling_automation_guidance",
-            "analyze_migration_scripts",
-            "analyze_architecture_compliance",
-            "analyze_public_interface_boundaries",
-            "analyze_shared_library_usage",
-            "discover_app_config",
-            "resolve_environment_specific_config",
-            "analyze_datasource_isolation",
-            "compare_cross_service_config_separation",
-        }
-    )
-    skill_objectives: list[str] = []
-    matched_signals: list[tuple[str, str, str]] = []
-    for objective, keywords in skill_objective_keywords.items():
-        matched_keyword = next((keyword for keyword in keywords if keyword in lowered_requirement), None)
-        matched_scope = "requirement"
-        if not matched_keyword:
-            matched_keyword = next((keyword for keyword in keywords if keyword in lowered_category), None)
-            matched_scope = "category"
-        if not matched_keyword:
-            continue
-        skill_objectives.append(objective)
-        matched_signals.append((objective, matched_keyword, matched_scope))
-
-    # Prefer architecture-compliance objective over generic dependency-cycle
-    # objective when row text clearly describes hexagonal / clean architecture.
-    if "analyze_architecture_compliance" in skill_objectives and "analyze_dependency_cycles" in skill_objectives:
-        skill_objectives = [objective for objective in skill_objectives if objective != "analyze_dependency_cycles"]
-        matched_signals = [signal for signal in matched_signals if signal[0] != "analyze_dependency_cycles"]
-
-    explicit_interface_requirement = any(
-        marker in lowered_requirement
-        for marker in (
-            "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",
-        )
-    )
-    if explicit_interface_requirement and "analyze_dependency_cycles" in skill_objectives:
-        skill_objectives = [objective for objective in skill_objectives if objective != "analyze_dependency_cycles"]
-        matched_signals = [signal for signal in matched_signals if signal[0] != "analyze_dependency_cycles"]
-    if explicit_interface_requirement and "analyze_architecture_compliance" in skill_objectives:
-        skill_objectives = [
-            objective for objective in skill_objectives if objective != "analyze_architecture_compliance"
-        ]
-        matched_signals = [signal for signal in matched_signals if signal[0] != "analyze_architecture_compliance"]
-    if explicit_interface_requirement and "analyze_public_interface_boundaries" not in skill_objectives:
-        skill_objectives.append("analyze_public_interface_boundaries")
-        matched_signals.append(("analyze_public_interface_boundaries", "explicit public interface", "requirement"))
-    if migration_requirement and "analyze_tooling_automation_guidance" in skill_objectives:
-        skill_objectives = [
-            objective for objective in skill_objectives if objective != "analyze_tooling_automation_guidance"
-        ]
-        matched_signals = [signal for signal in matched_signals if signal[0] != "analyze_tooling_automation_guidance"]
-    if migration_requirement and "analyze_migration_scripts" not in skill_objectives:
-        skill_objectives.append("analyze_migration_scripts")
-        matched_signals.append(("analyze_migration_scripts", "liquibase/flyway", "requirement"))
-
-    # Security scan rows under SLA sections should stay security-focused. Keep
-    # SLA/support objective only when explicitly requested by requirement text.
-    if has_security_control_signal and "analyze_security_scan_controls" in skill_objectives:
-        support_from_requirement = any(
-            objective == "analyze_support_sla_controls" and scope == "requirement"
-            for objective, _, scope in matched_signals
-        )
-        if not support_from_requirement:
-            skill_objectives = [
-                objective for objective in skill_objectives if objective != "analyze_support_sla_controls"
-            ]
-            matched_signals = [signal for signal in matched_signals if signal[0] != "analyze_support_sla_controls"]
-
-    strict_requirement_signals = [
-        signal for signal in matched_signals if signal[0] in strict_skill_objectives and signal[2] == "requirement"
-    ]
-    if "analyze_dependency_cycles" in skill_objectives and not strict_requirement_signals:
-        dependency_requirement_match = next(
-            (
-                signal
-                for signal in matched_signals
-                if signal[0] == "analyze_dependency_cycles" and signal[1] in lowered_requirement
-            ),
-            None,
-        )
-        if dependency_requirement_match is not None:
-            strict_requirement_signals.append(
-                ("analyze_dependency_cycles", dependency_requirement_match[1], "requirement")
-            )
-    strict_category_signals = [
-        signal for signal in matched_signals if signal[0] in strict_skill_objectives and signal[2] == "category"
-    ]
-    if strict_requirement_signals:
-        skills_needed = True
-        skill_signal_keyword = strict_requirement_signals[0][1]
-        skills_needed_reason = f"requirement_keyword:{skill_signal_keyword}"
-    elif strict_category_signals:
-        skills_needed = False
-        skill_signal_keyword = strict_category_signals[0][1]
-        skills_needed_reason = f"advisory_keyword:{skill_signal_keyword}"
-    elif matched_signals:
-        skills_needed = False
-        skill_signal_keyword = matched_signals[0][1]
-        skills_needed_reason = f"advisory_keyword:{skill_signal_keyword}"
-    else:
-        skills_needed = False
-        skills_needed_reason = "no_skill_keyword_signal"
-
-    acceptance_signals: list[str] = []
-    for line in guidance.splitlines():
-        normalized = " ".join(line.split())
-        if not normalized:
-            continue
-        if normalized.lower().startswith(("minh chứng kỳ vọng:", "cách kiểm tra:", "quy tắc:", "nội dung chính:")):
-            acceptance_signals.append(normalized)
-    if not acceptance_signals and category:
-        acceptance_signals.append(f"Ưu tiên bám sát nhóm kiểm tra: {category}")
-
-    # Marker taxonomy + conflict diagnostics
-    docs_markers: list[str] = [marker for marker in DOCS_MARKER_ALLOWLIST if marker in lowered]
-    code_markers: list[str] = [marker for marker in CODE_MARKER_KEYWORDS if marker in lowered]
-    process_markers: list[str] = [marker for marker in PROCESS_MARKER_KEYWORDS if marker in lowered]
-
-    # Populate marker_conflicts when both docs and code markers are active
-    marker_conflicts: list[str] = []
-    if docs_markers and code_markers:
-        for dm in docs_markers:
-            for cm in code_markers:
-                marker_conflicts.append(f"docs_marker '{dm}' conflicts with code_marker '{cm}'")
-
-    check_manual_raw = str(config.get("check_manual") or "").strip()
-    detailed_guidance = str(config.get("detailed_guidance") or "").strip()
-    evidence_hint = str(config.get("confluence_evidence_hint") or "").strip()
-    guidance_skip, guidance_skip_decision, guidance_skip_source_text, guidance_skip_reason = _classify_guidance_skip(
-        detailed_guidance,
-        evidence_hint,
-        requirement_guidance,
-    )
-    manual_hint_text = " ".join(part for part in (detailed_guidance, evidence_hint) if part).lower()
-    manual_hint_markers = (
-        "con người làm",
-        "manual verification",
-        "manual review",
-        "kiểm tra thủ công",
-        "xác minh thủ công",
-        "đánh giá thủ công",
-    )
-    check_manual = check_manual_raw.lower() in {"1", "true", "yes", "on", "manual"} or any(
-        marker in manual_hint_text for marker in manual_hint_markers
-    )
-
-    inferred_code_targets = list(dict.fromkeys(_infer_code_targets_from_requirement(requirement, category) + code_refs))
-
-    app_config_discovery = None
-    if app_config_only or any(
-        objective in skill_objectives
-        for objective in (
-            "discover_app_config",
-            "resolve_environment_specific_config",
-            "analyze_datasource_isolation",
-            "compare_cross_service_config_separation",
-        )
-    ):
-        app_config_discovery = build_app_config_discovery_result(
-            target_repo=_derive_target_repo_identity(
-                requirement_text=requirement,
-                requirement_category=category,
-                check_config=config,
-                evidence_refs=refs,
-                inferred_code_targets=inferred_code_targets,
-            ),
-            target_environment=(required_config_environments[0] if required_config_environments else None),
-            config_sources=discover_config_sources(inferred_code_targets[:10]),
-        )
-
-    # --- DD-122.16: InstructionPlan supersedes heuristic routing ---
-    plan_metadata: dict[str, Any] = {}
-    if instruction_plan is not None:
-        plan_metadata["instruction_plan"] = instruction_plan.to_dict()
-        plan_metadata["instruction_plan_id"] = getattr(instruction_plan, "plan_id", "")
-
-        # Override evidence_targets when plan provides structured directives
-        plan_evidence_targets = getattr(instruction_plan, "evidence_targets", None)
-        if plan_evidence_targets:
-            evidence_targets = list(dict.fromkeys(plan_evidence_targets))
-
-        # Preserve semantic audit-skill objectives from requirement heuristics,
-        # then augment with instruction-plan directives instead of overwriting them.
-        valid_directives = getattr(instruction_plan, "valid_directives", ())
-        if valid_directives:
-            plan_skill_objectives = [
-                d.directive_type for d in valid_directives if d.directive_type not in ("skip_infra", "skip_manual")
-            ]
-            if plan_skill_objectives:
-                merged_objectives = list(dict.fromkeys([*skill_objectives, *plan_skill_objectives]))
-                skill_objectives = merged_objectives[:4]
-                skills_needed = True
-                if not str(skills_needed_reason or "").startswith("requirement_keyword:"):
-                    skills_needed_reason = f"instruction_plan:{instruction_plan.plan_id}"
-
-        # Override acceptance_signals from scoring criteria
-        plan_pass_criteria = getattr(instruction_plan, "pass_criteria", ())
-        plan_fail_criteria = getattr(instruction_plan, "fail_criteria", ())
-        if plan_pass_criteria or plan_fail_criteria:
-            plan_acceptance = [c.criterion for c in plan_pass_criteria if c.is_valid()]
-            plan_acceptance += [f"FAIL if: {c.criterion}" for c in plan_fail_criteria if c.is_valid()]
-            if plan_acceptance:
-                acceptance_signals = plan_acceptance[:6]
-
-    return {
-        "intent": requirement[:240],
-        "control_objective": category or "uncategorized",
-        "evidence_targets": evidence_targets,
-        "code_targets": inferred_code_targets[:5],
-        "risk_focus": risk_focus,
-        "project_scope_required": project_scope_required,
-        "check_manual": check_manual,
-        "guidance_skip": guidance_skip,
-        "guidance_skip_decision": guidance_skip_decision,
-        "guidance_skip_source_text": guidance_skip_source_text,
-        "guidance_skip_reason": guidance_skip_reason,
-        "detailed_guidance": detailed_guidance,
-        "app_config_only": app_config_only,
-        "required_config_environments": required_config_environments,
-        "app_config_discovery": (
-            {
-                "target_repo": app_config_discovery.target_repo,
-                "target_environment": app_config_discovery.target_environment,
-                "environment_detected": app_config_discovery.environment_detected,
-                "discovery_status": app_config_discovery.discovery_status,
-                "config_sources": [
-                    {
-                        "source_type": item.source_type,
-                        "source_path": item.source_path,
-                        "source_ref": item.source_ref,
-                        "environment_relevance": item.environment_relevance,
-                        "discovery_rank": item.discovery_rank,
-                        "keys_detected": list(item.keys_detected),
-                        "decisive_candidate": item.decisive_candidate,
-                        "redaction_applied": item.redaction_applied,
-                    }
-                    for item in app_config_discovery.config_sources
-                ],
-                "precedence_chain": [
-                    {
-                        "step_rank": step.step_rank,
-                        "source_type": step.source_type,
-                        "source_ref": step.source_ref,
-                        "override_kind": step.override_kind,
-                        "applies_to_environment": step.applies_to_environment,
-                        "resolution_note": step.resolution_note,
-                    }
-                    for step in app_config_discovery.precedence_chain
-                ],
-                "findings": [
-                    {
-                        "finding_type": finding.finding_type,
-                        "finding_value_kind": finding.finding_value_kind,
-                        "evidence_strength": finding.evidence_strength,
-                        "compared_subjects": list(finding.compared_subjects),
-                        "supports_row_decision": finding.supports_row_decision,
-                        "evidence_refs": list(finding.evidence_refs),
-                        "notes": finding.notes,
-                    }
-                    for finding in app_config_discovery.findings
-                ],
-                "unresolved_gaps": [
-                    {
-                        "gap_type": gap.gap_type,
-                        "severity": gap.severity,
-                        "details": gap.details,
-                        "remaining_candidates": list(gap.remaining_candidates),
-                    }
-                    for gap in app_config_discovery.unresolved_gaps
-                ],
-                "confidence": app_config_discovery.confidence,
-                "decisive": app_config_discovery.decisive,
-            }
-            if app_config_discovery is not None
-            else None
-        ),
-        "project_scope_strategy": (
-            [
-                "Ưu tiên tìm bằng chứng wiring giữa module/service trong code trước (client, import, config, integration points).",
-                "Đối chiếu thêm tài liệu kiến trúc/thiết kế tổng thể hoặc ADR mô tả dependency rules giữa module/service.",
-                "Chỉ được kết luận PASS nếu có artifact project-level xác nhận dependency graph/cycle analysis.",
-                "Nếu chỉ có bằng chứng repo-local hoặc tài liệu kiến trúc mức cao, coi kết luận là sơ bộ; không được PASS tuyệt đối.",
-                "Không dùng testcase, KBKT, hoặc build metadata chung làm bằng chứng chính cho yêu cầu này trừ khi yêu cầu gọi đích danh chúng.",
-            ]
-            if project_scope_required
-            else []
-        ),
-        "authoritative_artifact_expectations": (
-            [
-                "dependency graph toàn project",
-                "dependency cycle report",
-                "mvn dependency:tree hoặc Gradle dependency tree có phạm vi module/service",
-                "ArchUnit / jdeps / depcruise / madge / nx dep-graph output",
-            ]
-            if project_scope_required
-            else []
-        ),
-        "skills_needed": skills_needed,
-        "skills_needed_reason": skills_needed_reason,
-        "skill_objectives": skill_objectives[:4],
-        "acceptance_signals": acceptance_signals[:6],
-        "docs_markers": docs_markers,
-        "code_markers": code_markers,
-        "process_markers": process_markers,
-        "marker_conflicts": marker_conflicts,
-        **plan_metadata,
-    }
-
-
-@dataclass
-class RowEvaluationResult:
-    """Result of evaluating a single row."""
-
-    row_id: str
-    check_id: str
-    status: RowStatus
-    score: float
-    score_breakdown: ScoreBreakdown
-    reason: str
-    finding: str
-    evidence_anchors: list[EvidenceAnchor]
-    provenance: RowProvenance
-    reasoning: str = ""  # LLM chain-of-thought (from RowEvaluationResponse.reasoning)
-    severity: str | None = None
-    priority: str = "P2"
-    effort: str = "M"
-    recommendation: str | None = None
-    fix_suggestions: list[str] = field(default_factory=list)
-    score_1_5: int | None = None
-    cache_hit: bool = False
-    error_message: str | None = None
-    retry_count: int = 0
-    retry_metadata: dict[str, Any] = field(default_factory=dict)
-    retrieval_trace: dict[str, Any] | None = None
-    coverage_requirements: float | None = None
-    coverage_code: float | None = None
-    coverage_docs: float | None = None
-    coverage_confidence: float | None = None
-    coverage_deterministic_downgrade_flag: bool = False
-    # FR-305: Structured metadata fields for evaluation quality analysis
-    evidence_strength: str | None = None
-    termination_reason: str | None = None
-    check_description: str | None = None
-    tool_calls_used: int | None = None
-
-    @property
-    def is_error(self) -> bool:
-        return self.status == RowStatus.ERROR
-
-
-class EvidenceStrength(StrEnum):
-    """Classification of evidence quality for structured metadata (FR-305)."""
-
-    STRONG = "STRONG"
-    MODERATE = "MODERATE"
-    WEAK = "WEAK"
-    NONE = "NONE"
-
-
-def classify_evidence_strength(
-    evidence_refs: list[str] | None,
-    retrieval_trace: dict[str, Any] | None = None,
-) -> str:
-    """Classify evidence strength using weighted quality factors.
-
-    Weighted factors:
-    - Source diversity bonus: evidence spanning docs + code receives 2x boost.
-    - Short-content penalty: trace entries with content <200 bytes receive 0.5x.
-    - Keyword relevance boost: if trace provides check keywords and refs match,
-      apply 1.5x boost.
-
-    Thresholds:
-    - STRONG: score >= 4.0
-    - MODERATE: score >= 2.0
-    - WEAK: score >= 0.5
-    - NONE: score < 0.5
-    """
-    refs = [str(r).strip() for r in (evidence_refs or []) if str(r).strip()]
-    trace_refs = _extract_trace_ref_values(retrieval_trace)
-    all_refs = list(dict.fromkeys(refs + trace_refs))
-
-    if not all_refs:
-        return EvidenceStrength.NONE.value
-
-    # Preserve existing hard override used by tool-first loop traces.
-    if isinstance(retrieval_trace, dict):
-        tool_first_loop = retrieval_trace.get("tool_first_loop")
-        if isinstance(tool_first_loop, dict):
-            evidence_refs_count = tool_first_loop.get("evidence_refs_count")
-            if isinstance(evidence_refs_count, int) and evidence_refs_count == 0:
-                return EvidenceStrength.NONE.value
-
-    short_refs = _extract_short_content_refs(retrieval_trace)
-    weighted_score = 0.0
-    for ref in all_refs:
-        contribution = 1.0
-        if ref in short_refs:
-            contribution *= 0.5
-        weighted_score += contribution
-
-    has_docs = any(_is_doc_like_ref(ref) for ref in all_refs)
-    has_code = any(_is_code_like_ref(ref) for ref in all_refs)
-    if has_docs and has_code:
-        weighted_score *= 2.0
-
-    keywords = _extract_relevance_keywords(retrieval_trace)
-    if keywords and _refs_match_keywords(all_refs, keywords):
-        weighted_score *= 1.5
-
-    if weighted_score >= 4.0:
-        return EvidenceStrength.STRONG.value
-    if weighted_score >= 2.0:
-        return EvidenceStrength.MODERATE.value
-    if weighted_score >= 0.5:
-        return EvidenceStrength.WEAK.value
-    return EvidenceStrength.NONE.value
-
-
-def _extract_short_content_refs(retrieval_trace: dict[str, Any] | None) -> set[str]:
-    if not isinstance(retrieval_trace, dict):
-        return set()
-
-    short_refs: set[str] = set()
-
-    def _candidate_ref(item: dict[str, Any]) -> str:
-        for key in ("source_path", "source_url", "ref_value", "ref", "path"):
-            raw = item.get(key)
-            if raw is None:
-                continue
-            value = str(raw).strip()
-            if value:
-                return value
-        return ""
-
-    def _candidate_length(item: dict[str, Any]) -> int | None:
-        for key in ("content_text", "text", "content", "snippet"):
-            raw = item.get(key)
-            if raw is None:
-                continue
-            value = str(raw)
-            if value:
-                return len(value.encode("utf-8"))
-        return None
-
-    def _iter_candidates(section: Any) -> list[dict[str, Any]]:
-        if isinstance(section, dict):
-            top_k = section.get("top_k")
-            if isinstance(top_k, list):
-                return [item for item in top_k if isinstance(item, dict)]
-            return []
-        if isinstance(section, list):
-            return [item for item in section if isinstance(item, dict)]
-        return []
-
-    for section_name in ("docs", "code"):
-        for item in _iter_candidates(retrieval_trace.get(section_name)):
-            ref = _candidate_ref(item)
-            if not ref:
-                continue
-            content_length = _candidate_length(item)
-            if content_length is not None and content_length < 200:
-                short_refs.add(ref)
-    return short_refs
-
-
-def _extract_relevance_keywords(retrieval_trace: dict[str, Any] | None) -> set[str]:
-    if not isinstance(retrieval_trace, dict):
-        return set()
-
-    keywords: set[str] = set()
-    candidate_keys = ("check_keywords", "keywords", "query_terms", "search_terms", "terms")
-
-    def _consume(value: Any) -> None:
-        if isinstance(value, str):
-            for token in re.findall(r"[a-z0-9][a-z0-9._-]*", value.lower()):
-                if len(token) >= 3:
-                    keywords.add(token)
-            return
-        if isinstance(value, (list, tuple, set)):
-            for item in value:
-                _consume(item)
-            return
-        if isinstance(value, dict):
-            for nested in value.values():
-                _consume(nested)
-
-    for key in candidate_keys:
-        _consume(retrieval_trace.get(key))
-    tool_loop = retrieval_trace.get("tool_first_loop")
-    if isinstance(tool_loop, dict):
-        for key in candidate_keys:
-            _consume(tool_loop.get(key))
-    return keywords
-
-
-def _refs_match_keywords(refs: list[str], keywords: set[str]) -> bool:
-    if not refs or not keywords:
-        return False
-    lowered_refs = [ref.lower() for ref in refs if ref]
-    return any(keyword in ref for keyword in keywords for ref in lowered_refs)
-
-
-def _severity_from_status(status: RowStatus, score: float) -> str | None:
-    """Map status/score to rough severity bucket."""
-    if status in {RowStatus.PASS, RowStatus.NA}:
-        return None
-    if status == RowStatus.ERROR:
-        return "HIGH"
-    if score < 20:
-        return "HIGH"
-    if score < 40:
-        return "MEDIUM"
-    if score < 90:
-        return "LOW"
-    return None
-
-
-def _score_to_1_5(score_percent: float) -> int:
-    """Convert percent score to checklist 1-5 scale."""
-    if score_percent >= 90:
-        return 5
-    if score_percent >= 70:
-        return 4
-    if score_percent >= 50:
-        return 3
-    if score_percent >= 30:
-        return 2
-    return 1
-
-
-__all__ = [
-    "CODE_MARKER_KEYWORDS",
-    "DETERMINISTIC_CHECK_TYPES",
-    "DOCS_MARKER_ALLOWLIST",
-    "PROCESS_MARKER_KEYWORDS",
-    "SEMANTIC_CHECK_TYPES",
-    "CheckCategory",
-    "ConsistencyRetryMode",
-    "EvidenceStrength",
-    "RouteDecision",
-    "RouteOverride",
-    "RowEvaluationResult",
-    "RowEvaluatorConfig",
-    "RowLLMMode",
-    "RowUnifiedMode",
-    "_classify_check_type",
-    "_score_to_1_5",
-    "_severity_from_status",
-    "apply_route_override",
-    "build_requirement_interpretation",
-    "classify_evidence_strength",
-    "compute_cache_key",
-    "compute_requirement_coverage_metrics",
-    "estimate_evidence_clarity",
-    "extract_disambiguation_hint",
-    "extract_required_config_environments",
-    "extract_requirement_guidance",
-    "is_deterministic",
-    "needs_llm",
-    "requires_app_config_only",
-]