@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,1433 +0,0 @@
-"""Deterministic requirement-intent analysis for tool-first planning (Phase 111).
-
-Phase 113: Execution-scope classification (FR-113.1, TSK-113.1).
-Phase 114: NLP and semantic requirement classification with confidence-gated escalation
-    (FR-114.1, FR-114.2, TSK-114.1, TSK-114.2).
-"""
-
-from __future__ import annotations
-
-import hashlib
-import re
-import unicodedata
-from collections.abc import Mapping
-from dataclasses import asdict, dataclass, field
-from functools import lru_cache
-from pathlib import Path
-from typing import Any, Literal, cast
-
-AnalysisMode = Literal["code_first", "docs_first", "hybrid_balanced", "infra_negative"]
-ClassificationSource = Literal["heuristic", "nlp_enrichment", "llm_agent", "dspy_classifier"]
-ExecutionScopeClass = Literal["repo_local", "project_doc_authoritative", "cross_repo_code_required"]
-
-# Phase 115
-CodeSearchStrategy = Literal[
-    "targeted_file",
-    "structural_pattern",
-    "semantic_grep",
-    "vector_semantic",
-    "multi_pass",
-]
-
-
-@dataclass(frozen=True, slots=True)
-class CodeSearchStrategyHint:
-    """Advisory search strategy consumed by the planner within a single row lifecycle."""
-
-    strategy: CodeSearchStrategy
-    preferred_tools: tuple[str, ...] = ()
-    scope_hint: str | None = None
-    query_variant: str | None = None
-    file_pattern_hints: tuple[str, ...] = ()
-    escalation_scope: str | None = None
-    vector_priority: bool = False
-    requirement_type_tag: str | None = None
-    app_config_only: bool = False
-
-    @property
-    def primary_strategy(self) -> CodeSearchStrategy:
-        return self.strategy
-
-    @property
-    def fallback_strategy(self) -> CodeSearchStrategy | None:
-        if self.strategy in {"structural_pattern", "vector_semantic"}:
-            return "semantic_grep"
-        if self.strategy in {"targeted_file", "multi_pass"} and self.escalation_scope:
-            return "semantic_grep"
-        return None
-
-    @property
-    def bounded_scope_required(self) -> bool:
-        return bool(self.escalation_scope)
-
-    @property
-    def diversity_sampling_enabled(self) -> bool:
-        return self.strategy == "multi_pass" and self.requirement_type_tag == "cross_cutting"
-
-    @property
-    def complementary_reads_required(self) -> bool:
-        return self.requirement_type_tag in {"migration", "security", "architecture"}
-
-
-_GENERIC_METADATA_REQUIREMENT_MARKERS = (
-    "pom.xml",
-    "dependency graph",
-    "dependencies",
-    "dependency lock",
-    "build.gradle",
-    "package.json",
-)
-_DOCS_FOCUSED_MARKERS = (
-    "openapi",
-    "swagger",
-    "api specification",
-    "api docs",
-    "documentation",
-    "tài liệu",
-    "tai lieu",
-)
-_CODE_FOCUSED_MARKERS = (
-    "implementation",
-    "source code",
-    "code path",
-    "line",
-    "class",
-    "method",
-    "domain",
-    "hexagonal",
-    "decoupling",
-    "cycle",
-)
-_ARCHITECTURE_STRONG_CODE_MARKERS = (
-    "decoupling",
-    "circular dependency",
-    "dependency cycle",
-    "clean architecture",
-    "hexagonal architecture",
-    "ports",
-    "adapters",
-    "domain",
-)
-_INFRA_MARKERS = (
-    "dockerfile",
-    "containerfile",
-    "docker-compose",
-    "compose.yml",
-    "compose.yaml",
-    "kubernetes",
-    "k8s",
-    "helm",
-    "terraform",
-    "deployment",
-)
-_SOURCE_EXTENSIONS = (".java", ".kt", ".kts", ".py", ".go", ".ts", ".tsx", ".js", ".jsx", ".rb", ".scala")
-_GENERIC_BUILD_METADATA_FILENAMES = frozenset(
-    {
-        "pom.xml",
-        "readme",
-        "readme.md",
-        "readme.rst",
-        "readme.txt",
-        "package.json",
-        "build.gradle",
-        "build.gradle.kts",
-        "settings.gradle",
-        "settings.gradle.kts",
-        "additional-spring-configuration-metadata.json",
-    }
-)
-_REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS: tuple[str, ...] = (
-    "analysis_mode",
-    "analysis_reason_codes",
-    "required_anchor_modalities",
-    "project_scope_required",
-    "execution_scope_class",
-    "generic_anchor_exemption",
-    "minimum_substantive_code_anchors",
-    "finalization_policy",
-    # Phase 114 fields (FR-114.1, TSK-114.1)
-    "heuristic_confidence",
-    "classification_source",
-    "content_fingerprint",
-    "classification_fingerprint",
-    "nlp_exemplar_similarity",
-    # Phase 122 fields (FR-122.1, TSK-122.7)
-    "requirement_scope",
-    "scope_confidence",
-    "scope_classification_source",
-)
-_ROUTE_REASON_TOKEN_PATTERN = re.compile(r"(?:^|;)\s*([a-z_]+)\s*=\s*([^;]+)")
-_ROUTE_MODE_TO_ANALYSIS_MODE: dict[str, AnalysisMode] = {
-    "docs_only": "docs_first",
-    "code_only": "code_first",
-    "hybrid_docs_first": "hybrid_balanced",
-    "hybrid_code_first": "hybrid_balanced",
-}
-_ANALYSIS_DEFAULT_MODALITIES: dict[AnalysisMode, list[str]] = {
-    "code_first": ["code"],
-    "docs_first": ["docs"],
-    "hybrid_balanced": ["code", "docs"],
-    "infra_negative": ["docs", "code"],
-}
-_ANALYSIS_DEFAULT_FINALIZATION_POLICY: dict[AnalysisMode, str] = {
-    "code_first": "code_substantive_required",
-    "docs_first": "docs_primary",
-    "hybrid_balanced": "mixed_modalities_preserve_strong_code",
-    "infra_negative": "infra_negative_allow_generic",
-}
-_APP_CONFIG_ONLY_FINALIZATION_POLICY = "app_config_evidence_only"
-
-
-@dataclass(frozen=True, slots=True)
-class RequirementAnalysisResult:
-    """Deterministic row-intent policy contract for route and evidence curation.
-
-    Phase 113: Added execution_scope_class field (FR-113.1, TSK-113.1).
-    Phase 114: Added heuristic_confidence, classification_source, content_fingerprint,
-               classification_fingerprint, nlp_exemplar_similarity (FR-114.1, FR-114.2).
-    """
-
-    analysis_mode: AnalysisMode
-    analysis_reason_codes: list[str] = field(default_factory=list)
-    required_anchor_modalities: list[str] = field(default_factory=list)
-    project_scope_required: bool = False
-    execution_scope_class: ExecutionScopeClass = "repo_local"
-    generic_anchor_exemption: bool = False
-    minimum_substantive_code_anchors: int = 0
-    finalization_policy: str = "default"
-    # Phase 114 fields (FR-114.1, FR-114.2)
-    heuristic_confidence: float = 0.5
-    classification_source: ClassificationSource = "heuristic"
-    content_fingerprint: str = ""
-    classification_fingerprint: str = ""
-    nlp_exemplar_similarity: float = 0.0
-    # Phase 122 fields (FR-122.1, TSK-122.3)
-    requirement_scope: str = "repo-scoped"
-    scope_confidence: float = 0.0
-    scope_classification_source: str = "default"
-
-    def to_dict(self) -> dict[str, Any]:
-        return asdict(self)
-
-    @classmethod
-    def from_mapping(cls, raw: Mapping[str, Any] | None) -> RequirementAnalysisResult | None:
-        if not isinstance(raw, Mapping):
-            return None
-        mode = str(raw.get("analysis_mode") or "").strip().lower()
-        if mode not in {"code_first", "docs_first", "hybrid_balanced", "infra_negative"}:
-            return None
-        validated_mode = cast("AnalysisMode", mode)
-        reason_codes_raw = raw.get("analysis_reason_codes")
-        modalities_raw = raw.get("required_anchor_modalities")
-        reason_codes = (
-            [str(code).strip() for code in reason_codes_raw if str(code).strip()]
-            if isinstance(reason_codes_raw, list)
-            else []
-        )
-        modalities = (
-            [str(modality).strip().lower() for modality in modalities_raw if str(modality).strip()]
-            if isinstance(modalities_raw, list)
-            else []
-        )
-        normalized_modalities = [modality for modality in modalities if modality in {"code", "docs"}]
-        try:
-            min_anchors = int(raw.get("minimum_substantive_code_anchors") or 0)
-        except (TypeError, ValueError):
-            min_anchors = 0
-
-        # Parse execution_scope_class with fallback (Phase 113, FR-113.1)
-        scope_class_raw = str(raw.get("execution_scope_class") or "").strip().lower()
-        valid_scope_classes = {"repo_local", "project_doc_authoritative", "cross_repo_code_required"}
-        scope_class: ExecutionScopeClass = (
-            cast("ExecutionScopeClass", scope_class_raw) if scope_class_raw in valid_scope_classes else "repo_local"
-        )
-
-        # Parse Phase 114 fields (FR-114.1, TSK-114.1)
-        # heuristic_confidence: float between 0.0 and 1.0
-        heuristic_confidence_raw = raw.get("heuristic_confidence")
-        if isinstance(heuristic_confidence_raw, (int, float)):
-            heuristic_confidence = max(0.0, min(1.0, float(heuristic_confidence_raw)))
-        else:
-            heuristic_confidence = 0.5  # Default fallback
-
-        # classification_source: must be valid enum value
-        source_raw = str(raw.get("classification_source") or "").strip().lower()
-        valid_sources = {"heuristic", "nlp_enrichment", "llm_agent", "dspy_classifier"}
-        classification_source: ClassificationSource = (
-            cast("ClassificationSource", source_raw) if source_raw in valid_sources else "heuristic"
-        )
-
-        # content_fingerprint: SHA-256 hex string
-        content_fingerprint = str(raw.get("content_fingerprint") or "").strip()
-
-        # classification_fingerprint: SHA-256 hex string
-        classification_fingerprint = str(raw.get("classification_fingerprint") or "").strip()
-
-        # nlp_exemplar_similarity: float between 0.0 and 1.0
-        nlp_similarity_raw = raw.get("nlp_exemplar_similarity")
-        if isinstance(nlp_similarity_raw, (int, float)):
-            nlp_exemplar_similarity = max(0.0, min(1.0, float(nlp_similarity_raw)))
-        else:
-            nlp_exemplar_similarity = 0.0  # Default when not provided
-
-        # Phase 122 fields (FR-122.1, TSK-122.3)
-        valid_scopes = {"repo-scoped", "infra-scoped", "manual-only"}
-        scope_raw = str(raw.get("requirement_scope") or "").strip()
-        requirement_scope = scope_raw if scope_raw in valid_scopes else "repo-scoped"
-
-        scope_conf_raw = raw.get("scope_confidence")
-        if isinstance(scope_conf_raw, (int, float)):
-            scope_confidence = max(0.0, min(1.0, float(scope_conf_raw)))
-        else:
-            scope_confidence = 0.0
-
-        valid_scope_sources = {"heuristic", "embedding", "llm", "fixture", "default"}
-        scope_source_raw = str(raw.get("scope_classification_source") or "").strip()
-        scope_classification_source = scope_source_raw if scope_source_raw in valid_scope_sources else "default"
-
-        return cls(
-            analysis_mode=validated_mode,
-            analysis_reason_codes=list(dict.fromkeys(reason_codes)),
-            required_anchor_modalities=list(dict.fromkeys(normalized_modalities)),
-            project_scope_required=bool(raw.get("project_scope_required")),
-            execution_scope_class=scope_class,
-            generic_anchor_exemption=bool(raw.get("generic_anchor_exemption")),
-            minimum_substantive_code_anchors=max(0, min_anchors),
-            finalization_policy=str(raw.get("finalization_policy") or "default").strip() or "default",
-            # Phase 114 fields (FR-114.1, TSK-114.1)
-            heuristic_confidence=heuristic_confidence,
-            classification_source=classification_source,
-            content_fingerprint=content_fingerprint,
-            classification_fingerprint=classification_fingerprint,
-            nlp_exemplar_similarity=nlp_exemplar_similarity,
-            # Phase 122 fields (FR-122.1, TSK-122.3)
-            requirement_scope=requirement_scope,
-            scope_confidence=scope_confidence,
-            scope_classification_source=scope_classification_source,
-        )
-
-
-def _normalize_analysis_mode(value: Any) -> AnalysisMode | None:
-    mode = str(value or "").strip().lower()
-    if mode not in {"code_first", "docs_first", "hybrid_balanced", "infra_negative"}:
-        return None
-    return cast("AnalysisMode", mode)
-
-
-def _normalize_route_mode(*, route_mode: Any, route_id: Any) -> str:
-    normalized_mode = str(route_mode or "").strip().lower()
-    if normalized_mode:
-        return normalized_mode
-    normalized_route_id = str(route_id or "").strip().lower()
-    if normalized_route_id.startswith("docs_"):
-        return "docs_only"
-    if normalized_route_id.startswith("code_"):
-        return "code_only"
-    if normalized_route_id.startswith("hybrid_docs_first"):
-        return "hybrid_docs_first"
-    if normalized_route_id.startswith("hybrid_code_first"):
-        return "hybrid_code_first"
-    return ""
-
-
-def _coerce_nonnegative_int(value: Any, default: int = 0) -> int:
-    try:
-        return max(0, int(value))
-    except (TypeError, ValueError):
-        return default
-
-
-def _parse_route_reason_tokens(route_reason: str) -> dict[str, str]:
-    normalized_reason = str(route_reason or "").strip().lower()
-    if not normalized_reason:
-        return {}
-    parsed: dict[str, str] = {}
-    for match in _ROUTE_REASON_TOKEN_PATTERN.finditer(normalized_reason):
-        key = str(match.group(1) or "").strip().lower()
-        value = str(match.group(2) or "").strip().lower()
-        if key and value and key not in parsed:
-            parsed[key] = value
-    return parsed
-
-
-def _inferred_route_reason(
-    trace: Mapping[str, Any], loop_trace: Mapping[str, Any], route_decision: Mapping[str, Any]
-) -> str:
-    for raw in (
-        trace.get("route_reason"),
-        loop_trace.get("route_reason"),
-        route_decision.get("route_reason"),
-    ):
-        reason = str(raw or "").strip()
-        if reason:
-            return reason
-    trace_steps_raw = loop_trace.get("trace_steps")
-    trace_steps = trace_steps_raw if isinstance(trace_steps_raw, list) else []
-    for step in trace_steps:
-        if not isinstance(step, Mapping):
-            continue
-        reason = str(step.get("route_reason") or "").strip()
-        if reason:
-            return reason
-    return ""
-
-
-def _analysis_mode_from_signals(
-    *,
-    route_mode: str,
-    docs_target: bool,
-    code_target: bool,
-    selection_blocked_reason: str,
-) -> AnalysisMode | None:
-    blocked = selection_blocked_reason.lower()
-    if blocked.startswith("missing_infra_artifact"):
-        return "infra_negative"
-    if docs_target and code_target:
-        return "hybrid_balanced"
-    if code_target:
-        return "code_first"
-    if docs_target:
-        return "docs_first"
-    return _ROUTE_MODE_TO_ANALYSIS_MODE.get(route_mode)
-
-
-def _has_code_path_signal(
-    *,
-    trace: Mapping[str, Any],
-    loop_trace: Mapping[str, Any],
-    route_mode: str,
-    code_target: bool,
-    interpretation: Mapping[str, Any],
-) -> bool:
-    if code_target:
-        return True
-    evidence_targets_raw = interpretation.get("evidence_targets")
-    evidence_targets = evidence_targets_raw if isinstance(evidence_targets_raw, list) else []
-    if any(str(target).strip().lower() == "code" for target in evidence_targets):
-        return True
-    code_targets_raw = interpretation.get("code_targets")
-    code_targets = code_targets_raw if isinstance(code_targets_raw, list) else []
-    if any(str(target).strip() for target in code_targets):
-        return True
-    if route_mode in {"code_only", "hybrid_code_first", "hybrid_docs_first"}:
-        return True
-    timeout_snapshot_raw = trace.get("timeout_progress_snapshot")
-    timeout_snapshot = timeout_snapshot_raw if isinstance(timeout_snapshot_raw, Mapping) else {}
-    for key in ("code_search_count", "code_read_count"):
-        if _coerce_nonnegative_int(loop_trace.get(key), 0) > 0:
-            return True
-        if _coerce_nonnegative_int(trace.get(key), 0) > 0:
-            return True
-        if _coerce_nonnegative_int(timeout_snapshot.get(key), 0) > 0:
-            return True
-    return False
-
-
-def _collect_requirement_analysis_candidate_paths(
-    trace: Mapping[str, Any],
-    *,
-    loop_trace: Mapping[str, Any],
-    interpretation: Mapping[str, Any],
-) -> list[str]:
-    """Prefer real explored/cited repo paths over static interpretation targets."""
-
-    candidates: list[str] = []
-
-    def _append_path(raw: Any) -> None:
-        path = str(raw or "").strip()
-        if path and path not in candidates:
-            candidates.append(path)
-
-    evidence_sets_raw = trace.get("evidence_ref_sets")
-    evidence_sets = evidence_sets_raw if isinstance(evidence_sets_raw, Mapping) else {}
-    for key in ("final_cited_refs", "exploratory_refs"):
-        raw_list = evidence_sets.get(key)
-        if isinstance(raw_list, list):
-            for entry in raw_list:
-                if isinstance(entry, Mapping):
-                    _append_path(
-                        entry.get("file_path")
-                        or entry.get("doc_path")
-                        or entry.get("ref_value")
-                        or entry.get("source_path")
-                    )
-                else:
-                    _append_path(entry)
-
-    loop_evidence_raw = loop_trace.get("evidence_refs")
-    if isinstance(loop_evidence_raw, list):
-        for entry in loop_evidence_raw:
-            if isinstance(entry, Mapping):
-                _append_path(
-                    entry.get("file_path")
-                    or entry.get("doc_path")
-                    or entry.get("ref_value")
-                    or entry.get("source_path")
-                )
-            else:
-                _append_path(entry)
-
-    if candidates:
-        return candidates
-
-    code_candidate_paths_raw = interpretation.get("code_targets")
-    if isinstance(code_candidate_paths_raw, list):
-        for path in code_candidate_paths_raw:
-            _append_path(path)
-    return candidates
-
-
-def _infer_requirement_analysis_candidate(
-    trace: Mapping[str, Any],
-    *,
-    loop_trace: Mapping[str, Any],
-    route_decision: Mapping[str, Any],
-) -> RequirementAnalysisResult | None:
-    interpretation_raw = trace.get("requirement_interpretation")
-    interpretation = interpretation_raw if isinstance(interpretation_raw, Mapping) else {}
-
-    docs_intent_raw = loop_trace.get("docs_intent_utilization")
-    docs_intent = docs_intent_raw if isinstance(docs_intent_raw, Mapping) else {}
-    route_id = str(trace.get("route_id") or loop_trace.get("route_id") or route_decision.get("route_id") or "").strip()
-    route_mode = _normalize_route_mode(
-        route_mode=(trace.get("route_mode") or loop_trace.get("route_mode") or route_decision.get("route_mode")),
-        route_id=route_id,
-    )
-    docs_target = bool(route_decision.get("docs_target")) or bool(docs_intent.get("docs_target"))
-    code_target = bool(route_decision.get("code_target")) or bool(docs_intent.get("code_target"))
-    selection_blocked_reason = str(
-        trace.get("selection_blocked_reason") or loop_trace.get("selection_blocked_reason") or ""
-    ).strip()
-
-    route_reason = _inferred_route_reason(trace, loop_trace, route_decision)
-    route_tokens = _parse_route_reason_tokens(route_reason)
-    hinted_mode = _normalize_analysis_mode(route_tokens.get("analysis_mode"))
-    hinted_policy = str(route_tokens.get("finalization_policy") or "").strip().lower()
-
-    inferred_mode = hinted_mode or _analysis_mode_from_signals(
-        route_mode=route_mode,
-        docs_target=docs_target,
-        code_target=code_target,
-        selection_blocked_reason=selection_blocked_reason,
-    )
-    hinted_mode_overridden = False
-
-    guidance_text = str(
-        interpretation.get("detailed_guidance")
-        or trace.get("requirement_guidance")
-        or loop_trace.get("requirement_guidance")
-        or ""
-    ).strip()
-
-    base: RequirementAnalysisResult | None = None
-    if interpretation:
-        code_candidate_paths = _collect_requirement_analysis_candidate_paths(
-            trace,
-            loop_trace=loop_trace,
-            interpretation=interpretation,
-        )
-        base = analyze_requirement_intent(
-            requirement_text=str(interpretation.get("intent") or ""),
-            requirement_category=str(interpretation.get("control_objective") or ""),
-            interpretation=dict(interpretation),
-            code_candidate_paths=code_candidate_paths,
-            guidance_text=guidance_text,
-        )
-        if base.analysis_mode == "infra_negative" and inferred_mode in {"code_first", "hybrid_balanced"}:
-            inferred_mode = base.analysis_mode
-            hinted_mode_overridden = True
-            hinted_policy = ""
-        elif inferred_mode is None:
-            inferred_mode = base.analysis_mode
-
-    if inferred_mode is None:
-        return None
-
-    base_finalization_policy = (
-        str(base.finalization_policy).strip().lower()
-        if base is not None and base.analysis_mode == inferred_mode
-        else ""
-    )
-    finalization_policy = (
-        hinted_policy or base_finalization_policy or _ANALYSIS_DEFAULT_FINALIZATION_POLICY[inferred_mode]
-    )
-    minimum_substantive_code_anchors = base.minimum_substantive_code_anchors if base is not None else 0
-    if inferred_mode in {"code_first", "hybrid_balanced"} and minimum_substantive_code_anchors <= 0:
-        if _has_code_path_signal(
-            trace=trace,
-            loop_trace=loop_trace,
-            route_mode=route_mode,
-            code_target=code_target,
-            interpretation=interpretation,
-        ):
-            minimum_substantive_code_anchors = 1
-
-    reason_codes = list(base.analysis_reason_codes if base is not None else [])
-    if not reason_codes:
-        reason_codes.append("requirement_interpretation_fallback" if interpretation else "route_metadata_fallback")
-    if hinted_mode is not None:
-        reason_codes.append("route_reason_analysis_mode_hint")
-    if hinted_mode_overridden:
-        reason_codes.append("route_reason_analysis_mode_hint_overridden")
-    elif route_mode:
-        reason_codes.append("route_mode_inference")
-    if hinted_policy:
-        reason_codes.append("route_reason_finalization_policy_hint")
-    if selection_blocked_reason.startswith("missing_infra_artifact"):
-        reason_codes.append("infra_artifact_candidate_missing")
-    normalized_reasons = list(dict.fromkeys(code for code in reason_codes if str(code).strip()))
-
-    # Preserve execution_scope_class from base analysis (Phase 113, FR-113.1)
-    execution_scope_class: ExecutionScopeClass = base.execution_scope_class if base is not None else "repo_local"
-
-    # Preserve Phase 114 fields from base analysis when available (FR-114.1, TSK-114.1)
-    # Otherwise use default values for inferred results
-    heuristic_confidence = base.heuristic_confidence if base is not None else 0.5
-    classification_source = base.classification_source if base is not None else "heuristic"
-    content_fingerprint = base.content_fingerprint if base is not None else ""
-    classification_fingerprint = base.classification_fingerprint if base is not None else ""
-    nlp_exemplar_similarity = base.nlp_exemplar_similarity if base is not None else 0.0
-
-    result = RequirementAnalysisResult(
-        analysis_mode=inferred_mode,
-        analysis_reason_codes=normalized_reasons,
-        required_anchor_modalities=list(_ANALYSIS_DEFAULT_MODALITIES[inferred_mode]),
-        project_scope_required=bool(base.project_scope_required) if base is not None else False,
-        execution_scope_class=execution_scope_class,
-        generic_anchor_exemption=bool(base.generic_anchor_exemption) if base is not None else False,
-        minimum_substantive_code_anchors=max(0, int(minimum_substantive_code_anchors)),
-        finalization_policy=finalization_policy,
-        # Phase 114 fields (FR-114.1, FR-114.2, TSK-114.1, TSK-114.2)
-        heuristic_confidence=heuristic_confidence,
-        classification_source=classification_source,
-        content_fingerprint=content_fingerprint,
-        classification_fingerprint=classification_fingerprint,
-        nlp_exemplar_similarity=nlp_exemplar_similarity,
-    )
-    return _apply_app_config_only_contract(result, guidance_text=guidance_text)
-
-
-def resolve_requirement_analysis_from_trace(trace: Mapping[str, Any] | None) -> RequirementAnalysisResult | None:
-    """Resolve requirement-analysis diagnostics from trace payload with fallback inference.
-
-    The resolver prefers explicit requirement-analysis payloads, then inline diagnostics.
-    If those are unavailable, it infers a conservative payload from route metadata and
-    requirement interpretation signals so sidecar exports can stay machine-verifiable.
-    """
-
-    if not isinstance(trace, Mapping):
-        return None
-    loop_trace_raw = trace.get("tool_first_loop")
-    loop_trace = loop_trace_raw if isinstance(loop_trace_raw, Mapping) else {}
-    route_decision_raw = trace.get("tool_first_route_decision")
-    route_decision = route_decision_raw if isinstance(route_decision_raw, Mapping) else {}
-    code_ranking_raw = loop_trace.get("code_ranking_diagnostics")
-    code_ranking = code_ranking_raw if isinstance(code_ranking_raw, Mapping) else {}
-
-    inline_trace = {key: trace.get(key) for key in _REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS if key in trace}
-    inline_loop = {key: loop_trace.get(key) for key in _REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS if key in loop_trace}
-    inline_route = {
-        key: route_decision.get(key) for key in _REQUIREMENT_ANALYSIS_DIAGNOSTIC_KEYS if key in route_decision
-    }
-
-    inferred = _infer_requirement_analysis_candidate(trace, loop_trace=loop_trace, route_decision=route_decision)
-    candidate_payloads: tuple[tuple[str, Any], ...] = (
-        ("trace", trace.get("requirement_analysis")),
-        ("tool_first_loop", loop_trace.get("requirement_analysis")),
-        ("route_decision", route_decision.get("requirement_analysis")),
-        ("code_ranking", code_ranking.get("requirement_analysis")),
-        ("trace_inline", inline_trace if inline_trace else None),
-        ("tool_first_loop_inline", inline_loop if inline_loop else None),
-        ("route_decision_inline", inline_route if inline_route else None),
-    )
-    source_priority = {
-        "trace": 0,
-        "trace_inline": 0,
-        "tool_first_loop": 1,
-        "tool_first_loop_inline": 1,
-        "route_decision": 1,
-        "route_decision_inline": 1,
-        "code_ranking": 2,
-    }
-    best_parsed: RequirementAnalysisResult | None = None
-    best_score: tuple[int, int, int, int, int] | None = None
-    best_complete = False
-    for source, candidate in candidate_payloads:
-        parsed = RequirementAnalysisResult.from_mapping(candidate if isinstance(candidate, Mapping) else None)
-        if parsed is None:
-            continue
-        finalization_policy = str(parsed.finalization_policy or "").strip().lower()
-        parsed_complete = (
-            bool(parsed.analysis_reason_codes)
-            and bool(parsed.required_anchor_modalities)
-            and bool(finalization_policy and finalization_policy != "default")
-        )
-        if parsed_complete and parsed.analysis_mode in {"code_first", "hybrid_balanced"}:
-            parsed_complete = parsed.minimum_substantive_code_anchors > 0
-        parsed_score = (
-            len(parsed.required_anchor_modalities),
-            len(parsed.analysis_reason_codes),
-            max(0, int(parsed.minimum_substantive_code_anchors)),
-            1 if finalization_policy not in {"", "default"} else 0,
-            int(source_priority.get(source, 0)),
-        )
-        if best_complete and not parsed_complete:
-            continue
-        if (not best_complete and parsed_complete) or best_score is None or parsed_score > best_score:
-            best_score = parsed_score
-            best_parsed = parsed
-            best_complete = parsed_complete
-    if best_complete and best_parsed is not None:
-        return best_parsed
-    if inferred is None:
-        return best_parsed
-    inferred_score = (
-        len(inferred.required_anchor_modalities),
-        len(inferred.analysis_reason_codes),
-        max(0, int(inferred.minimum_substantive_code_anchors)),
-        1 if str(inferred.finalization_policy or "").strip().lower() not in {"", "default"} else 0,
-        -1,
-    )
-    if best_score is None or inferred_score > best_score:
-        return inferred
-    return best_parsed
-
-
-def _norm_targets(raw_targets: Any) -> set[str]:
-    if not isinstance(raw_targets, list):
-        return set()
-    return {str(target).strip().lower() for target in raw_targets if str(target).strip()}
-
-
-def _list_from_interpretation(interpretation: dict[str, Any], key: str) -> list[str]:
-    raw = interpretation.get(key)
-    if not isinstance(raw, list):
-        return []
-    return [str(item).strip().lower() for item in raw if str(item).strip()]
-
-
-def _looks_like_source(candidate: str) -> bool:
-    path = Path(candidate)
-    name = path.name.lower()
-    return path.suffix.lower() in _SOURCE_EXTENSIONS and name not in _GENERIC_BUILD_METADATA_FILENAMES
-
-
-def _count_substantive_source_candidates(candidates: list[str]) -> int:
-    normalized: list[str] = []
-    for candidate in candidates:
-        path = str(candidate or "").strip()
-        if not path or not _looks_like_source(path):
-            continue
-        if path not in normalized:
-            normalized.append(path)
-    return len(normalized)
-
-
-def _derive_execution_scope_class(
-    *,
-    project_scope_required: bool,
-    lowered_requirement: str,
-    decoupling_architecture_signal: bool,
-    infra_signal: bool,
-) -> ExecutionScopeClass:
-    """Derive execution scope class from requirement analysis (Phase 113, FR-113.1, TSK-113.1).
-
-    Rules:
-    - project_scope_required=False → repo_local
-    - project_scope_required=True + docs-only signals → project_doc_authoritative
-    - project_scope_required=True + code-signals (dependency graph, circular dependency,
-      modules/services) → cross_repo_code_required
-
-    Infra/deployment rows with dependency graph mentions must NOT be promoted to
-    cross-repo code scope (AC-113.1.3).
-    """
-    if not project_scope_required:
-        return "repo_local"
-
-    # Infra/deployment rows stay at project_doc_authoritative even with dependency keywords
-    if infra_signal:
-        return "project_doc_authoritative"
-
-    # Check for code-focused cross-repo signals (AC-113.1.3)
-    cross_repo_code_markers = (
-        "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",
-        "decoupling",
-        "hexagonal architecture",
-        "clean architecture",
-        "ports and adapters",
-    )
-
-    has_cross_repo_code_signal = any(marker in lowered_requirement for marker in cross_repo_code_markers)
-
-    if has_cross_repo_code_signal and decoupling_architecture_signal:
-        return "cross_repo_code_required"
-
-    # Default to project doc authoritative for project scope without cross-repo code signals
-    return "project_doc_authoritative"
-
-
-def _normalize_for_fingerprint(text: str) -> str:
-    """Normalize text for fingerprint computation using NFC Unicode normalization.
-
-    Phase 114: Ensures equivalent Unicode sequences (e.g., 'café' vs 'cafe\\u0301')
-    produce identical fingerprints (FR-114.2, DD-114.7).
-    """
-    return unicodedata.normalize("NFC", str(text).strip())
-
-
-def compute_requirement_content_fingerprint(
-    *,
-    requirement_text: str,
-    requirement_category: str = "",
-) -> str:
-    """Compute SHA-256 fingerprint of requirement content for drift detection (FR-114.2, TSK-114.2).
-
-    The fingerprint combines normalized requirement text and category to detect
-    content changes between runs. NFC normalization ensures Unicode equivalent
-    sequences produce identical fingerprints.
-
-    Returns:
-        64-character hexadecimal SHA-256 digest.
-    """
-    normalized_text = _normalize_for_fingerprint(requirement_text)
-    normalized_category = _normalize_for_fingerprint(requirement_category)
-    combined = f"{normalized_text}|{normalized_category}"
-    return hashlib.sha256(combined.encode("utf-8")).hexdigest()
-
-
-def compute_classification_fingerprint(
-    *,
-    analysis_mode: AnalysisMode,
-    required_anchor_modalities: list[str] | tuple[str, ...],
-    project_scope_required: bool,
-    finalization_policy: str,
-) -> str:
-    """Compute SHA-256 fingerprint of classification output for drift detection (FR-114.2, TSK-114.2).
-
-    The fingerprint combines routing-relevant classification fields to detect
-    when classification behavior changes between runs. Evidence targets are
-    sorted to ensure order-independent fingerprinting.
-
-    Returns:
-        64-character hexadecimal SHA-256 digest.
-    """
-    # Sort modalities for deterministic fingerprint
-    sorted_modalities = sorted(str(m).lower().strip() for m in required_anchor_modalities if str(m).strip())
-    modalities_str = ",".join(sorted_modalities)
-
-    combined = (
-        f"{analysis_mode}|{modalities_str}|{int(project_scope_required)}|{str(finalization_policy).strip().lower()}"
-    )
-    return hashlib.sha256(combined.encode("utf-8")).hexdigest()
-
-
-def analyze_requirement_intent(
-    *,
-    requirement_text: str,
-    requirement_category: str = "",
-    interpretation: dict[str, Any] | None = None,
-    code_candidate_paths: list[str] | None = None,
-    guidance_text: str = "",
-) -> RequirementAnalysisResult:
-    """Classify requirement intent without invoking an LLM.
-
-    Phase 123: *guidance_text* is now included in project_scope_required detection
-    to catch Vietnamese markers that appear in guidance but not in the short
-    requirement text (e.g. CL-003, CL-006).
-    """
-
-    interp = interpretation if isinstance(interpretation, dict) else {}
-    guidance_text = str(guidance_text or interp.get("detailed_guidance") or "").strip()
-    lowered = f"{requirement_text or ''} {requirement_category or ''}".lower()
-
-    evidence_targets = _norm_targets(interp.get("evidence_targets"))
-    docs_markers = _list_from_interpretation(interp, "docs_markers")
-    code_markers = _list_from_interpretation(interp, "code_markers")
-    process_markers = _list_from_interpretation(interp, "process_markers")
-
-    reason_codes: list[str] = []
-    required_anchor_modalities: list[str] = []
-
-    doc_signal = (
-        "docs" in evidence_targets or bool(docs_markers) or any(marker in lowered for marker in _DOCS_FOCUSED_MARKERS)
-    )
-    code_signal = (
-        "code" in evidence_targets or bool(code_markers) or any(marker in lowered for marker in _CODE_FOCUSED_MARKERS)
-    )
-    infra_signal = any(marker in lowered for marker in _INFRA_MARKERS)
-    mixed_signal = doc_signal and code_signal
-
-    candidates = list(dict.fromkeys(code_candidate_paths or []))
-    substantive_source_candidate_count = _count_substantive_source_candidates(candidates)
-    has_substantive_source_candidate = substantive_source_candidate_count > 0
-    has_infra_candidate = any(
-        marker in candidate.lower()
-        for candidate in candidates
-        for marker in (
-            "dockerfile",
-            "containerfile",
-            "compose.yml",
-            "compose.yaml",
-            "helm",
-            "k8s",
-            "kubernetes",
-            "terraform",
-        )
-    )
-    decoupling_architecture_signal = any(marker in lowered for marker in _ARCHITECTURE_STRONG_CODE_MARKERS)
-    decoupling_control_signal = "decoupling" in str(requirement_category or "").lower()
-    decoupling_code_authoritative = decoupling_architecture_signal or decoupling_control_signal
-    # Phase 123: Include guidance text in project_scope_required detection and add
-    # Vietnamese markers (DD-123.9).  Guidance text often carries the strongest
-    # cross-project signals for rows whose short requirement text is generic.
-    lowered_with_guidance = f"{lowered} {guidance_text.lower()}"
-    project_scope_required = (
-        any(
-            marker in lowered_with_guidance
-            for marker in (
-                "dependency graph",
-                "circular dependency",
-                "dependency cycle",
-                "cycle trong dependency graph",
-                "dependency/lib",
-                "dependency lib",
-                "modules/services",
-                "service/module",
-                "module/service",
-                # Phase 123: Vietnamese markers for cross-project scope
-                "tập trung trên 1 project",
-                "repo dùng chung",
-                "thư viện dùng chung",
-                "sdk nền tảng",
-                "quản lý tập trung",
-                "dependency/lib tập trung",
-                "lib tập trung",
-                "lib tap trung",
-                "dependency tập trung",
-                "dependency tap trung",
-                "dùng chung",
-                "dung chung",
-                "dùng chung giữa các",
-                "dùng chung cho các",
-            )
-        )
-        and not infra_signal
-    )
-    generic_anchor_exemption = any(marker in lowered for marker in _GENERIC_METADATA_REQUIREMENT_MARKERS)
-    if decoupling_architecture_signal and has_substantive_source_candidate:
-        generic_anchor_exemption = False
-
-    if "docs" in evidence_targets:
-        reason_codes.append("evidence_target_docs")
-    if "code" in evidence_targets:
-        reason_codes.append("evidence_target_code")
-    if docs_markers:
-        reason_codes.append("docs_marker_signal")
-    if code_markers:
-        reason_codes.append("code_marker_signal")
-    if process_markers:
-        reason_codes.append("process_marker_signal")
-    if infra_signal:
-        reason_codes.append("infra_marker_signal")
-    if project_scope_required:
-        reason_codes.append("project_scope_required")
-    if project_scope_required and decoupling_architecture_signal:
-        reason_codes.append("project_scope_source_structure_required")
-        reason_codes.append("authoritative_project_artifact_expected")
-    if has_substantive_source_candidate:
-        reason_codes.append("substantive_source_candidate_present")
-    if generic_anchor_exemption:
-        reason_codes.append("generic_metadata_requirement")
-    elif decoupling_architecture_signal and has_substantive_source_candidate:
-        reason_codes.append("generic_metadata_exemption_blocked_by_substantive_code")
-
-    mode: AnalysisMode
-    finalization_policy: str
-    minimum_substantive_code_anchors = 0
-
-    if infra_signal and (not has_infra_candidate):
-        mode = "infra_negative"
-        required_anchor_modalities = ["docs", "code"]
-        finalization_policy = "infra_negative_allow_generic"
-        reason_codes.append("infra_artifact_candidate_missing")
-    elif decoupling_code_authoritative:
-        mode = "code_first"
-        required_anchor_modalities = ["code"]
-        finalization_policy = "code_substantive_required"
-        minimum_substantive_code_anchors = 1 if has_substantive_source_candidate else 0
-        if substantive_source_candidate_count >= 2:
-            minimum_substantive_code_anchors = 2
-            reason_codes.append("corroborating_code_anchors_required")
-        if mixed_signal:
-            reason_codes.append("decoupling_code_authoritative_override")
-        reason_codes.append("code_first_requirement")
-    elif mixed_signal:
-        mode = "hybrid_balanced"
-        required_anchor_modalities = ["code", "docs"]
-        finalization_policy = "mixed_modalities_preserve_strong_code"
-        minimum_substantive_code_anchors = 1 if has_substantive_source_candidate else 0
-        if decoupling_architecture_signal and substantive_source_candidate_count >= 2:
-            minimum_substantive_code_anchors = 2
-            reason_codes.append("corroborating_code_anchors_required")
-        reason_codes.append("mixed_modalities_required")
-    elif code_signal:
-        mode = "code_first"
-        required_anchor_modalities = ["code"]
-        finalization_policy = "code_substantive_required"
-        minimum_substantive_code_anchors = 1 if has_substantive_source_candidate else 0
-        if substantive_source_candidate_count >= 2:
-            minimum_substantive_code_anchors = 2
-            reason_codes.append("corroborating_code_anchors_required")
-        reason_codes.append("code_first_requirement")
-    else:
-        mode = "docs_first"
-        required_anchor_modalities = ["docs"]
-        finalization_policy = "docs_primary"
-        reason_codes.append("docs_first_requirement")
-
-    # Keep deterministic order and deduplicate.
-    normalized_reasons = list(dict.fromkeys(code for code in reason_codes if code))
-
-    # Derive execution scope class (Phase 113, FR-113.1, TSK-113.1)
-    execution_scope_class = _derive_execution_scope_class(
-        project_scope_required=project_scope_required,
-        lowered_requirement=lowered,
-        decoupling_architecture_signal=decoupling_architecture_signal,
-        infra_signal=infra_signal,
-    )
-
-    # Compute heuristic confidence from marker presence (Phase 114, FR-114.1, TSK-114.1)
-    # Higher confidence when multiple corroborating markers are present
-    marker_count = sum(
-        [
-            doc_signal,
-            code_signal,
-            infra_signal,
-            decoupling_architecture_signal,
-            project_scope_required,
-            has_substantive_source_candidate,
-        ]
-    )
-    # Base confidence from 0.4 to 0.9 based on marker count
-    heuristic_confidence = min(0.9, 0.4 + (marker_count * 0.08))
-
-    # Compute content and classification fingerprints (Phase 114, FR-114.2, TSK-114.2)
-    content_fingerprint = compute_requirement_content_fingerprint(
-        requirement_text=requirement_text,
-        requirement_category=requirement_category,
-    )
-    classification_fingerprint = compute_classification_fingerprint(
-        analysis_mode=mode,
-        required_anchor_modalities=required_anchor_modalities,
-        project_scope_required=project_scope_required,
-        finalization_policy=finalization_policy,
-    )
-
-    result = RequirementAnalysisResult(
-        analysis_mode=mode,
-        analysis_reason_codes=normalized_reasons,
-        required_anchor_modalities=required_anchor_modalities,
-        project_scope_required=project_scope_required,
-        execution_scope_class=execution_scope_class,
-        generic_anchor_exemption=generic_anchor_exemption,
-        minimum_substantive_code_anchors=minimum_substantive_code_anchors,
-        finalization_policy=finalization_policy,
-        # Phase 114 fields (FR-114.1, FR-114.2, TSK-114.1, TSK-114.2)
-        heuristic_confidence=heuristic_confidence,
-        classification_source="heuristic",  # Layer 1: deterministic marker-based
-        content_fingerprint=content_fingerprint,
-        classification_fingerprint=classification_fingerprint,
-        nlp_exemplar_similarity=0.0,  # NLP layer not yet applied
-    )
-    return _apply_app_config_only_contract(result, guidance_text=guidance_text)
-
-
-def _normalize_strategy_text(value: str) -> str:
-    return str(value or "").strip().lower()
-
-
-_SHARED_LIBRARY_MARKERS = (
-    "shared library",
-    "shared-library",
-    "common lib",
-    "common-lib",
-    "common repo",
-    "common-repo",
-    "dependency lib",
-    "dependency-lib",
-    "sdk nền tảng",
-    "sdk nen tang",
-    "repo dùng chung",
-    "repo dung chung",
-    "thư viện dùng chung",
-    "thu vien dung chung",
-    "thư viện chung",
-    "thu vien chung",
-    "lib tập trung",
-    "lib tap trung",
-    "88724032",
-)
-_APP_CONFIG_ONLY_MARKERS = (
-    "app-config",
-    "app config",
-    "repo app-config",
-    "repo app config",
-)
-_APP_CONFIG_FIRST_DB_ISOLATION_MARKERS = (
-    "schema/db instance riêng",
-    "schema / db instance riêng",
-    "schema riêng",
-    "db instance riêng",
-    "database instance riêng",
-    "separate schema",
-    "separate db instance",
-    "separate database instance",
-    "gọi trực tiếp vào database",
-    "goi truc tiep vao database",
-    "shared memory",
-    "shared-memory",
-    "shared schema",
-    "shared database",
-    "shared datasource",
-)
-
-
-def requires_app_config_only(guidance_text: str = "") -> bool:
-    """Return True when requirement/guidance should stay app-config-first."""
-    guidance_lower = str(guidance_text or "").strip().lower()
-    if not guidance_lower:
-        return False
-    if any(marker in guidance_lower for marker in _APP_CONFIG_ONLY_MARKERS):
-        return True
-    return any(marker in guidance_lower for marker in _APP_CONFIG_FIRST_DB_ISOLATION_MARKERS)
-
-
-def _apply_app_config_only_contract(
-    result: RequirementAnalysisResult,
-    *,
-    guidance_text: str = "",
-) -> RequirementAnalysisResult:
-    """Keep app-config-only rows on config-file evidence without code-anchor hard gates."""
-    if not requires_app_config_only(guidance_text):
-        return result
-
-    required_anchor_modalities = ["code"]
-    finalization_policy = _APP_CONFIG_ONLY_FINALIZATION_POLICY
-    reason_codes = list(dict.fromkeys([*result.analysis_reason_codes, "app_config_only_requirement"]))
-    classification_fingerprint = compute_classification_fingerprint(
-        analysis_mode="code_first",
-        required_anchor_modalities=required_anchor_modalities,
-        project_scope_required=result.project_scope_required,
-        finalization_policy=finalization_policy,
-    )
-    return RequirementAnalysisResult(
-        analysis_mode="code_first",
-        analysis_reason_codes=reason_codes,
-        required_anchor_modalities=required_anchor_modalities,
-        project_scope_required=result.project_scope_required,
-        execution_scope_class=result.execution_scope_class,
-        generic_anchor_exemption=result.generic_anchor_exemption,
-        minimum_substantive_code_anchors=0,
-        finalization_policy=finalization_policy,
-        heuristic_confidence=result.heuristic_confidence,
-        classification_source=result.classification_source,
-        content_fingerprint=result.content_fingerprint,
-        classification_fingerprint=classification_fingerprint,
-        nlp_exemplar_similarity=result.nlp_exemplar_similarity,
-        requirement_scope=result.requirement_scope,
-        scope_confidence=result.scope_confidence,
-        scope_classification_source=result.scope_classification_source,
-    )
-
-
-@lru_cache(maxsize=512)
-def _derive_code_search_strategy_cached(
-    analysis_mode: AnalysisMode,
-    execution_scope_class: ExecutionScopeClass,
-    project_scope_required: bool,
-    analysis_reason_codes_key: tuple[str, ...],
-    minimum_substantive_code_anchors: int,
-    requirement_text: str,
-    category: str,
-    guidance_text: str = "",
-) -> CodeSearchStrategyHint | None:
-    combined = f"{requirement_text} {category} {guidance_text}".strip().lower()
-    reason_codes = {
-        _normalize_strategy_text(code) for code in analysis_reason_codes_key if _normalize_strategy_text(code)
-    }
-
-    if requires_app_config_only(guidance_text):
-        return CodeSearchStrategyHint(
-            strategy="targeted_file",
-            preferred_tools=("read_code_file",),
-            scope_hint="config",
-            query_variant="app_config_only",
-            file_pattern_hints=(
-                "**/application.properties",
-                "**/application.yml",
-                "**/application.yaml",
-                "**/bootstrap.properties",
-                "**/bootstrap.yml",
-                "**/bootstrap.yaml",
-            ),
-            escalation_scope=None,
-            vector_priority=False,
-            requirement_type_tag="config_pattern",
-            app_config_only=True,
-        )
-
-    # Phase 123 fix: Do not short-circuit docs_first rows when guidance contains
-    # dependency-inspection markers (pom.xml, build.gradle) or shared-library markers.
-    # CL-003-like rows have generic requirement text but guidance that explicitly
-    # requires code inspection of build files and shared-lib verification.
-    _has_dependency_inspection_marker = any(
-        marker in combined
-        for marker in (
-            "pom.xml",
-            "build.gradle",
-            "settings.gradle",
-            "package.json",
-            "requirements.txt",
-            "dependency",
-        )
-    )
-    _has_shared_lib_marker = any(marker in combined for marker in _SHARED_LIBRARY_MARKERS)
-    _has_explicit_public_interface_marker = 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 (
-        analysis_mode == "docs_first"
-        and not any(
-            marker in combined for marker in ("code", "source", "implementation", "repository", "class", "method")
-        )
-        and not _has_dependency_inspection_marker
-        and not _has_shared_lib_marker
-    ):
-        return None
-
-    # Phase 123 (FR-123.2, DD-123.9): Shared-library / common-lib promotion.
-    # Guidance text often carries the strongest shared-library signals for rows
-    # whose short requirement text is generic (e.g. CL-003).
-    if _has_explicit_public_interface_marker:
-        return CodeSearchStrategyHint(
-            strategy="multi_pass",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="primary",
-            file_pattern_hints=("**/*.java", "**/*.kt", "**/*.ts", "**/*.js"),
-            escalation_scope="code",
-            vector_priority=False,
-            requirement_type_tag="api_contract",
-        )
-
-    if any(marker in combined for marker in _SHARED_LIBRARY_MARKERS):
-        return CodeSearchStrategyHint(
-            strategy="multi_pass",
-            preferred_tools=("search_code", "read_code_file", "search_docs"),
-            scope_hint="lib",
-            query_variant="primary",
-            file_pattern_hints=(
-                "**/pom.xml",
-                "**/build.gradle",
-                "**/build.gradle.kts",
-                "**/*.java",
-                "**/*.kt",
-                "**/*.py",
-                "**/*.ts",
-            ),
-            escalation_scope="all",
-            vector_priority=False,
-            requirement_type_tag="shared_library",
-        )
-
-    if any(
-        marker in combined
-        for marker in (
-            "flyway",
-            "liquibase",
-            "alembic",
-            "migration",
-            "migrate",
-            "changeset",
-            "changelog",
-            "db/migration",
-        )
-    ):
-        return CodeSearchStrategyHint(
-            strategy="targeted_file",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="migration",
-            file_pattern_hints=(
-                "**/db/migration/**",
-                "**/migrations/**",
-                "**/V*__.sql",
-                "**/changelog*.xml",
-                "**/changelog*.yaml",
-            ),
-            escalation_scope="all",
-            vector_priority=False,
-            requirement_type_tag="migration",
-        )
-
-    if any(
-        marker in combined
-        for marker in (
-            "hexagonal",
-            "clean architecture",
-            "ports",
-            "adapters",
-            "circular dependency",
-            "dependency cycle",
-            "domain layer",
-        )
-    ):
-        return CodeSearchStrategyHint(
-            strategy="structural_pattern",
-            preferred_tools=("search_code_vector", "search_code", "read_code_file"),
-            scope_hint="all"
-            if project_scope_required or execution_scope_class == "cross_repo_code_required"
-            else "code",
-            query_variant="primary",
-            file_pattern_hints=("**/*.java", "**/*.kt", "**/*.py", "**/*.ts"),
-            escalation_scope=None,
-            vector_priority=True,
-            requirement_type_tag="architecture",
-        )
-
-    if any(
-        marker in combined
-        for marker in (
-            "sast",
-            "dast",
-            "vulnerability",
-            "security scan",
-            "secret",
-            "jwt",
-            "authentication",
-            "authorization",
-        )
-    ):
-        return CodeSearchStrategyHint(
-            strategy="multi_pass",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="primary",
-            file_pattern_hints=("**/*.java", "**/*.kt", "**/*.py", "**/*.yml", "**/*.yaml"),
-            escalation_scope="all" if execution_scope_class != "project_doc_authoritative" else None,
-            vector_priority=False,
-            requirement_type_tag="security",
-        )
-
-    if any(
-        marker in combined
-        for marker in ("consistent", "standardized", "across", "all services", "every module", "nhất quán", "đồng nhất")
-    ):
-        return CodeSearchStrategyHint(
-            strategy="multi_pass",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="primary",
-            file_pattern_hints=("**/*.java", "**/*.kt", "**/*.py", "**/*.ts"),
-            escalation_scope="all" if project_scope_required else None,
-            vector_priority=False,
-            requirement_type_tag="cross_cutting",
-        )
-
-    if analysis_mode == "infra_negative":
-        return CodeSearchStrategyHint(
-            strategy="targeted_file",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="all",
-            query_variant="primary",
-            file_pattern_hints=("**/Dockerfile*", "**/*.yaml", "**/*.yml", "**/*.tf"),
-            escalation_scope=None,
-            vector_priority=False,
-            requirement_type_tag="infrastructure",
-        )
-
-    if analysis_mode == "hybrid_balanced" or minimum_substantive_code_anchors > 1:
-        return CodeSearchStrategyHint(
-            strategy="vector_semantic",
-            preferred_tools=("search_code_vector", "search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="primary",
-            file_pattern_hints=(),
-            escalation_scope=None,
-            vector_priority=True,
-            requirement_type_tag="general_code",
-        )
-
-    if analysis_mode == "code_first" or "code_first_requirement" in reason_codes:
-        return CodeSearchStrategyHint(
-            strategy="semantic_grep",
-            preferred_tools=("search_code", "read_code_file"),
-            scope_hint="code",
-            query_variant="primary",
-            file_pattern_hints=(),
-            escalation_scope="all"
-            if project_scope_required or execution_scope_class == "cross_repo_code_required"
-            else None,
-            vector_priority=False,
-            requirement_type_tag="general_code",
-        )
-
-    return CodeSearchStrategyHint(
-        strategy="semantic_grep",
-        preferred_tools=("search_code", "read_code_file"),
-        scope_hint="code",
-        query_variant="primary",
-        file_pattern_hints=(),
-        escalation_scope=None,
-        vector_priority=False,
-        requirement_type_tag="general_code",
-    )
-
-
-def derive_code_search_strategy(
-    analysis_result: RequirementAnalysisResult,
-    requirement_text: str = "",
-    category: str = "",
-    guidance_text: str = "",
-) -> CodeSearchStrategyHint | None:
-    """Derive advisory search strategy from canonical classification without side effects.
-
-    Phase 123 (DD-123.9): *guidance_text* carries detailed instructions / guidance
-    that may contain shared-library markers invisible in the short requirement text.
-    """
-    return _derive_code_search_strategy_cached(
-        analysis_result.analysis_mode,
-        analysis_result.execution_scope_class,
-        bool(analysis_result.project_scope_required),
-        tuple(analysis_result.analysis_reason_codes),
-        int(analysis_result.minimum_substantive_code_anchors),
-        str(requirement_text or ""),
-        str(category or ""),
-        str(guidance_text or ""),
-    )