@ngocsangairvds/vsaf 3.2.13 → 3.2.15

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

@@ -1,1725 +0,0 @@
-"""Requirement classification with fingerprinting and drift detection (Phase 114).
-
-This module provides:
-- Content and classification fingerprinting for drift detection (FR-114.2, FR-114.9)
-- Cross-run semantic drift computation (FR-114.9)
-- Drift severity classification (cosmetic, minor, major, breaking)
-- Classification cache for pre-computation (FR-114.10)
-
-Feature flags:
-- VDS_AUDIT_REQUIREMENT_DRIFT_ENABLED: Enable drift detection (default: false)
-- VDS_AUDIT_REQUIREMENT_DRIFT_EMBEDDING_SIMILARITY: Use BGE-M3 for semantic diff (default: true)
-"""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import unicodedata
-from collections.abc import Mapping
-from dataclasses import dataclass, field
-from datetime import UTC, datetime, timedelta
-from enum import StrEnum
-from typing import TYPE_CHECKING, Any, Literal
-
-import structlog
-from pydantic import BaseModel, Field, field_validator
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.engine.requirement_analysis import RequirementAnalysisResult
-
-logger = structlog.get_logger(__name__)
-
-
-def _default_modalities_for_analysis_mode(analysis_mode: str) -> list[str]:
-    normalized = str(analysis_mode or "").strip().lower()
-    if normalized == "code_first":
-        return ["code"]
-    if normalized == "docs_first":
-        return ["docs"]
-    if normalized in {"hybrid_balanced", "infra_negative"}:
-        return ["code", "docs"]
-    return ["code", "docs"]
-
-
-class DriftSeverity(StrEnum):
-    """Severity level for requirement content drift between runs."""
-
-    NONE = "none"
-    COSMETIC = "cosmetic"  # similarity > 0.95, trivial edits
-    MINOR = "minor"  # similarity 0.80-0.95, stable classification
-    MAJOR = "major"  # classification changed significantly
-    BREAKING = "breaking"  # project_scope_required changed
-
-
-class ClassificationSource(StrEnum):
-    """Source of the requirement classification result."""
-
-    HEURISTIC = "heuristic"  # Layer 1: deterministic marker-based
-    NLP_ENRICHMENT = "nlp_enrichment"  # Layer 2: BGE-M3 exemplar similarity
-    LLM_AGENT = "llm_agent"  # Layer 3: LLM agent classification
-    DSPY_CLASSIFIER = "dspy_classifier"  # Layer 3: DSPy compiled classifier
-    CACHED = "cached"  # Retrieved from cache (pre-computed)
-
-
-@dataclass(frozen=True, slots=True)
-class RequirementFingerprints:
-    """Content and classification fingerprints for drift detection (FR-114.2, DD-114.7).
-
-    Fingerprints use SHA-256 of NFC-normalized text for deterministic comparison.
-    Content fingerprint is computed from classification-driving fields.
-    Classification fingerprint is computed from output classification fields.
-    """
-
-    content_fingerprint: str = field(default="")
-    classification_fingerprint: str = field(default="")
-    nlp_embedding_fingerprint: str = field(default="")  # Optional BGE-M3 embedding hash
-
-    @classmethod
-    def compute_content_fingerprint(
-        cls,
-        requirement_text: str,
-        requirement_category: str,
-        *,
-        normalize_unicode: bool = True,
-    ) -> str:
-        """Compute content fingerprint from classification-driving fields.
-
-        Args:
-            requirement_text: The raw requirement description
-            requirement_category: The category/family of the requirement
-            normalize_unicode: Apply NFC normalization before hashing
-
-        Returns:
-            SHA-256 hex digest of normalized content
-        """
-        if normalize_unicode:
-            # NFC normalization ensures consistent fingerprints for diacritic variants
-            text = unicodedata.normalize("NFC", str(requirement_text))
-            category = unicodedata.normalize("NFC", str(requirement_category))
-        else:
-            text = str(requirement_text)
-            category = str(requirement_category)
-
-        # Combine fields with null separator for deterministic fingerprint
-        combined = f"{text}\x00{category}"
-        return hashlib.sha256(combined.encode("utf-8", errors="replace")).hexdigest()
-
-    @classmethod
-    def compute_classification_fingerprint(
-        cls,
-        analysis_mode: str,
-        evidence_targets: list[str] | tuple[str, ...],
-        project_scope_required: bool,
-        finalization_policy: str,
-    ) -> str:
-        """Compute classification fingerprint from output classification fields.
-
-        Args:
-            analysis_mode: The determined analysis mode
-            evidence_targets: Required evidence modalities
-            project_scope_required: Whether project scope is required
-            finalization_policy: The finalization policy
-
-        Returns:
-            SHA-256 hex digest of classification state
-        """
-        normalized_targets = sorted({str(t).lower() for t in evidence_targets})
-        combined = (
-            f"{analysis_mode}\x00"
-            f"{','.join(normalized_targets)}\x00"
-            f"{int(project_scope_required)}\x00"
-            f"{finalization_policy}"
-        )
-        return hashlib.sha256(combined.encode("utf-8")).hexdigest()
-
-    @classmethod
-    def compute_nlp_embedding_fingerprint(cls, embedding_vector: list[float] | tuple[float, ...]) -> str:
-        """Compute fingerprint from BGE-M3 embedding for semantic drift detection.
-
-        Args:
-            embedding_vector: The embedding vector (e.g., 1024-dim BGE-M3)
-
-        Returns:
-            SHA-256 hex digest of quantized embedding
-        """
-        # Quantize to 4 decimal places to avoid floating-point noise
-        quantized = tuple(round(float(x), 4) for x in embedding_vector)
-        combined = ",".join(str(v) for v in quantized)
-        return hashlib.sha256(combined.encode("utf-8")).hexdigest()
-
-
-class RequirementDriftReport(BaseModel):
-    """Drift report for a single requirement between prior and current run (FR-114.9)."""
-
-    # Identification
-    row_key: str = Field(description="Stable row identifier")
-    prior_content_fingerprint: str = Field(default="", description="Prior run content SHA-256")
-    current_content_fingerprint: str = Field(default="", description="Current run content SHA-256")
-    prior_classification_fingerprint: str = Field(default="", description="Prior classification SHA-256")
-    current_classification_fingerprint: str = Field(default="", description="Current classification SHA-256")
-
-    # Severity classification
-    severity: DriftSeverity = Field(default=DriftSeverity.NONE, description="Drift severity level")
-
-    # Semantic similarity (optional, computed when embedding_similarity_enabled=true)
-    cosine_similarity: float | None = Field(default=None, ge=-1.0, le=1.0, description="BGE-M3 cosine similarity")
-
-    # Classification deltas
-    prior_analysis_mode: str | None = Field(default=None, description="Prior analysis_mode")
-    current_analysis_mode: str | None = Field(default=None, description="Current analysis_mode")
-    prior_project_scope_required: bool | None = Field(default=None)
-    current_project_scope_required: bool | None = Field(default=None)
-
-    # Metadata
-    drift_detected: bool = Field(default=False, description="True if severity >= MINOR")
-    computed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-
-    @field_validator("drift_detected", mode="before")
-    @classmethod
-    def _compute_drift_detected(cls, v: bool | None, info: Any) -> bool:
-        """Automatically set drift_detected based on severity."""
-        if v is not None:
-            return v
-        severity = info.data.get("severity", DriftSeverity.NONE)
-        return severity in (DriftSeverity.MINOR, DriftSeverity.MAJOR, DriftSeverity.BREAKING)
-
-
-@dataclass(frozen=True, slots=True)
-class RequirementClassificationRecord:
-    """Persisted classification record for cross-run drift queries (FR-114.3, FR-114.9).
-
-    This is the persisted form stored in Postgres for drift detection.
-    """
-
-    row_key: str
-    content_fingerprint: str
-    classification_fingerprint: str
-
-    # Classification output
-    analysis_mode: str
-    evidence_targets: tuple[str, ...]
-    project_scope_required: bool
-    finalization_policy: str
-
-    # Metadata
-    classification_source: ClassificationSource
-    heuristic_confidence: float = 0.0
-    nlp_exemplar_similarity: float | None = None
-    run_id: str = ""
-    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for Postgres storage."""
-        return {
-            "row_key": self.row_key,
-            "content_fingerprint": self.content_fingerprint,
-            "classification_fingerprint": self.classification_fingerprint,
-            "analysis_mode": self.analysis_mode,
-            "evidence_targets": list(self.evidence_targets),
-            "project_scope_required": self.project_scope_required,
-            "finalization_policy": self.finalization_policy,
-            "classification_source": self.classification_source.value,
-            "heuristic_confidence": self.heuristic_confidence,
-            "nlp_exemplar_similarity": self.nlp_exemplar_similarity,
-            "run_id": self.run_id,
-            "created_at": self.created_at,
-        }
-
-    @classmethod
-    def from_mapping(cls, raw: Mapping[str, Any]) -> RequirementClassificationRecord | None:
-        """Create from Postgres query result."""
-        if not isinstance(raw, Mapping):
-            return None
-
-        row_key = raw.get("row_key")
-        if not row_key:
-            return None
-
-        source_raw = raw.get("classification_source", "heuristic")
-        try:
-            classification_source = ClassificationSource(str(source_raw))
-        except (ValueError, KeyError):
-            # Default to HEURISTIC for invalid/unknown sources
-            classification_source = ClassificationSource.HEURISTIC
-
-        # Extract evidence_targets - ensure it's a tuple
-        evidence_targets_raw = raw.get("evidence_targets", [])
-        if isinstance(evidence_targets_raw, str):
-            # Handle comma-separated string format
-            evidence_targets = tuple(t.strip() for t in evidence_targets_raw.split(",") if t.strip())
-        elif isinstance(evidence_targets_raw, list):
-            evidence_targets = tuple(str(t) for t in evidence_targets_raw)
-        else:
-            evidence_targets = ()
-
-        # Extract project_scope_required - handle various representations
-        pscr_raw = raw.get("project_scope_required", False)
-        if isinstance(pscr_raw, str):
-            project_scope_required = pscr_raw.lower() in ("true", "1", "yes")
-        else:
-            project_scope_required = bool(pscr_raw)
-
-        # Extract nlp_exemplar_similarity safely
-        nlp_sim_raw = raw.get("nlp_exemplar_similarity")
-        if nlp_sim_raw is not None:
-            try:
-                nlp_exemplar_similarity = float(nlp_sim_raw)
-            except (TypeError, ValueError):
-                nlp_exemplar_similarity = None
-        else:
-            nlp_exemplar_similarity = None
-
-        # Extract heuristic_confidence safely
-        try:
-            heuristic_confidence = float(raw.get("heuristic_confidence", 0.0))
-        except (TypeError, ValueError):
-            heuristic_confidence = 0.0
-
-        return cls(
-            row_key=str(row_key),
-            content_fingerprint=str(raw.get("content_fingerprint", "")),
-            classification_fingerprint=str(raw.get("classification_fingerprint", "")),
-            analysis_mode=str(raw.get("analysis_mode", "code_first")),
-            evidence_targets=evidence_targets,
-            project_scope_required=project_scope_required,
-            finalization_policy=str(raw.get("finalization_policy", "default")),
-            classification_source=classification_source,
-            heuristic_confidence=heuristic_confidence,
-            nlp_exemplar_similarity=nlp_exemplar_similarity,
-            run_id=str(raw.get("run_id", "")),
-        )
-
-
-class ChecklistDriftSummary(BaseModel):
-    """Aggregate drift summary for a checklist (FR-114.9, AC-114.9.2)."""
-
-    # Counts per severity level
-    rows_unchanged: int = Field(default=0, description="Content and classification unchanged")
-    rows_cosmetic_change: int = Field(default=0, description="Cosmetic drift (similarity > 0.95)")
-    rows_minor_change: int = Field(default=0, description="Minor drift (similarity 0.80-0.95)")
-    rows_major_change: int = Field(default=0, description="Major drift (classification changed)")
-    rows_breaking_change: int = Field(default=0, description="Breaking drift (project_scope changed)")
-    rows_added: int = Field(default=0, description="Rows added since prior run")
-    rows_removed: int = Field(default=0, description="Rows removed since prior run")
-    rows_total: int = Field(default=0, description="Total rows in current checklist")
-
-    # Page version comparison
-    prior_page_version: int | None = Field(default=None, description="Prior Confluence page version")
-    current_page_version: int | None = Field(default=None, description="Current Confluence page version")
-
-    # Drift detection status
-    drift_detection_enabled: bool = Field(default=False, description="Whether drift detection is enabled")
-    any_drift_detected: bool = Field(default=False, description="True if any row has severity >= MINOR")
-
-    # Prior run reference
-    prior_run_id: str = Field(default="", description="Prior run ID for drift comparison")
-
-    def add_row_drift(self, severity: DriftSeverity) -> None:
-        """Increment the appropriate counter based on severity."""
-        self.rows_total += 1
-        if severity == DriftSeverity.NONE:
-            self.rows_unchanged += 1
-        elif severity == DriftSeverity.COSMETIC:
-            self.rows_cosmetic_change += 1
-        elif severity == DriftSeverity.MINOR:
-            self.rows_minor_change += 1
-        elif severity == DriftSeverity.MAJOR:
-            self.rows_major_change += 1
-        elif severity == DriftSeverity.BREAKING:
-            self.rows_breaking_change += 1
-
-        if severity in (DriftSeverity.MINOR, DriftSeverity.MAJOR, DriftSeverity.BREAKING):
-            self.any_drift_detected = True
-
-
-def compute_row_drift(
-    *,
-    prior_record: RequirementClassificationRecord | None,
-    current_classification: RequirementClassificationRecord,
-    cosine_similarity: float | None = None,
-    similarity_thresholds: dict[str, float] | None = None,
-) -> RequirementDriftReport:
-    """Compute drift between prior and current requirement classification (FR-114.9, AC-114.9.1).
-
-    Fast path: if both content and classification fingerprints match exactly, no drift.
-    Otherwise, optionally compute BGE-M3 embedding similarity for semantic diff.
-    Classify drift severity based on content change, classification change, and similarity.
-
-    Args:
-        prior_record: Prior run classification record (None for new rows)
-        current_classification: Current run classification
-        cosine_similarity: Optional BGE-M3 cosine similarity (0-1, higher = more similar)
-        similarity_thresholds: Custom thresholds for severity classification
-
-    Returns:
-        RequirementDriftReport with severity and deltas
-    """
-    # Default similarity thresholds from DD-114.7
-    defaults = {
-        "cosmetic_min": 0.95,
-        "minor_min": 0.80,
-        "major_max": 0.80,
-    }
-    thresholds = similarity_thresholds or defaults
-
-    # Fast path: no prior record = new row
-    if prior_record is None:
-        return RequirementDriftReport(
-            row_key=current_classification.row_key,
-            current_content_fingerprint=current_classification.content_fingerprint,
-            current_classification_fingerprint=current_classification.classification_fingerprint,
-            current_analysis_mode=current_classification.analysis_mode,
-            current_project_scope_required=current_classification.project_scope_required,
-            severity=DriftSeverity.NONE,  # New rows are not "drift"
-            drift_detected=False,
-        )
-
-    # Check for breaking change FIRST: project_scope_required flipped
-    # This is checked even if content is the same, because a reclassification
-    # can change project scope even when the requirement text hasn't changed
-    if prior_record.project_scope_required != current_classification.project_scope_required:
-        return RequirementDriftReport(
-            row_key=current_classification.row_key,
-            prior_content_fingerprint=prior_record.content_fingerprint,
-            current_content_fingerprint=current_classification.content_fingerprint,
-            prior_classification_fingerprint=prior_record.classification_fingerprint,
-            current_classification_fingerprint=current_classification.classification_fingerprint,
-            prior_analysis_mode=prior_record.analysis_mode,
-            current_analysis_mode=current_classification.analysis_mode,
-            prior_project_scope_required=prior_record.project_scope_required,
-            current_project_scope_required=current_classification.project_scope_required,
-            severity=DriftSeverity.BREAKING,
-            drift_detected=True,
-        )
-
-    # Fast path: both content AND classification match = no drift
-    if (
-        prior_record.content_fingerprint == current_classification.content_fingerprint
-        and prior_record.classification_fingerprint == current_classification.classification_fingerprint
-    ):
-        return RequirementDriftReport(
-            row_key=current_classification.row_key,
-            prior_content_fingerprint=prior_record.content_fingerprint,
-            current_content_fingerprint=current_classification.content_fingerprint,
-            prior_classification_fingerprint=prior_record.classification_fingerprint,
-            current_classification_fingerprint=current_classification.classification_fingerprint,
-            prior_analysis_mode=prior_record.analysis_mode,
-            current_analysis_mode=current_classification.analysis_mode,
-            prior_project_scope_required=prior_record.project_scope_required,
-            current_project_scope_required=current_classification.project_scope_required,
-            severity=DriftSeverity.NONE,
-            drift_detected=False,
-        )
-
-    # Content or classification changed - classify severity
-    severity = DriftSeverity.MAJOR  # Default to major
-    drift_detected = True
-
-    # Check for major change: classification fingerprint differs
-    if prior_record.classification_fingerprint != current_classification.classification_fingerprint:
-        severity = DriftSeverity.MAJOR
-    # Use embedding similarity if available
-    elif cosine_similarity is not None:
-        if cosine_similarity >= thresholds["cosmetic_min"]:
-            severity = DriftSeverity.COSMETIC
-            drift_detected = False  # Cosmetic changes are not actionable drift
-        elif cosine_similarity >= thresholds["minor_min"]:
-            severity = DriftSeverity.MINOR
-        else:
-            severity = DriftSeverity.MAJOR
-    else:
-        # No similarity available, assume major when content changed
-        severity = DriftSeverity.MAJOR
-
-    return RequirementDriftReport(
-        row_key=current_classification.row_key,
-        prior_content_fingerprint=prior_record.content_fingerprint,
-        current_content_fingerprint=current_classification.content_fingerprint,
-        prior_classification_fingerprint=prior_record.classification_fingerprint,
-        current_classification_fingerprint=current_classification.classification_fingerprint,
-        prior_analysis_mode=prior_record.analysis_mode,
-        current_analysis_mode=current_classification.analysis_mode,
-        prior_project_scope_required=prior_record.project_scope_required,
-        current_project_scope_required=current_classification.project_scope_required,
-        cosine_similarity=cosine_similarity,
-        severity=severity,
-        drift_detected=drift_detected,
-    )
-
-
-def build_drift_advisory_note(
-    drift_report: RequirementDriftReport,
-    *,
-    include_classification_details: bool = True,
-) -> str:
-    """Build an advisory note for LLM prompt when drift is detected (FR-114.9, AC-114.9.3).
-
-    The note informs the agent about prior vs current classification to prevent
-    stale evaluation reasoning when requirement content has changed.
-
-    Args:
-        drift_report: The drift report for this row
-        include_classification_details: Whether to include full classification details
-
-    Returns:
-        Advisory note string for injection into LLM prompt
-    """
-    if not drift_report.drift_detected or drift_report.severity == DriftSeverity.NONE:
-        return ""
-
-    parts = [
-        f"[Requirement Change Advisory] This requirement content changed since the prior run (severity: {drift_report.severity.value})."
-    ]
-
-    if include_classification_details:
-        if drift_report.prior_analysis_mode and drift_report.current_analysis_mode and drift_report.prior_analysis_mode != drift_report.current_analysis_mode:
-                parts.append(f"  - Prior classification: {drift_report.prior_analysis_mode}")
-                parts.append(f"  - Current classification: {drift_report.current_analysis_mode}")
-
-        if drift_report.prior_project_scope_required != drift_report.current_project_scope_required:
-            prior_scope = "project-scope required" if drift_report.prior_project_scope_required else "repo-local"
-            current_scope = "project-scope required" if drift_report.current_project_scope_required else "repo-local"
-            parts.append(f"  - Prior scope: {prior_scope}")
-            parts.append(f"  - Current scope: {current_scope}")
-
-        if drift_report.cosine_similarity is not None:
-            parts.append(f"  - Semantic similarity: {drift_report.cosine_similarity:.3f}")
-
-    parts.append(
-        "Evaluate this requirement based on its CURRENT content, not stale assumptions from the prior version."
-    )
-
-    return "\n".join(parts)
-
-
-# Classification cache for pre-computation (FR-114.10)
-
-
-@dataclass(slots=True)
-class ClassificationCacheEntry:
-    """Single cache entry for requirement classification."""
-
-    content_fingerprint: str
-    classification_record: RequirementClassificationRecord
-    expires_at: datetime
-
-    def is_expired(self, now: datetime | None = None) -> bool:
-        """Check if this cache entry has expired."""
-        if now is None:
-            now = datetime.now(UTC)
-        return now > self.expires_at
-
-
-@dataclass(slots=True)
-class RequirementClassificationCache:
-    """In-memory classification cache for workflow execution (FR-114.10, AC-114.10.2).
-
-    Cache key: (row_key, content_fingerprint)
-    Cache invalidation: Automatic when content_fingerprint changes (AC-114.10.4)
-    Default TTL: 3600 seconds (AC-114.10.2)
-    """
-
-    ttl_seconds: int = 3600
-    _entries: dict[str, ClassificationCacheEntry] = field(default_factory=dict)
-    _hits: int = field(default=0)
-    _misses: int = field(default=0)
-
-    def _make_key(self, row_key: str, content_fingerprint: str) -> str:
-        """Create cache key from row_key and content_fingerprint."""
-        return f"{row_key}:{content_fingerprint}"
-
-    def get(
-        self,
-        row_key: str,
-        content_fingerprint: str,
-    ) -> RequirementClassificationRecord | None:
-        """Retrieve cached classification if available and not expired (AC-114.10.3)."""
-        key = self._make_key(row_key, content_fingerprint)
-        entry = self._entries.get(key)
-
-        if entry is None:
-            self._misses += 1
-            return None
-
-        if entry.is_expired():
-            # Lazy expiration - remove and return miss
-            del self._entries[key]
-            self._misses += 1
-            return None
-
-        self._hits += 1
-        return entry.classification_record
-
-    def put(
-        self,
-        row_key: str,
-        classification_record: RequirementClassificationRecord,
-    ) -> None:
-        """Store classification in cache (AC-114.10.1)."""
-        now = datetime.now(UTC)
-        expires_at = now.replace(microsecond=0)  # Truncate microseconds
-        # Add TTL seconds
-        expires_at = expires_at + timedelta(seconds=self.ttl_seconds)
-
-        key = self._make_key(row_key, classification_record.content_fingerprint)
-        self._entries[key] = ClassificationCacheEntry(
-            content_fingerprint=classification_record.content_fingerprint,
-            classification_record=classification_record,
-            expires_at=expires_at,
-        )
-
-    def invalidate(self, row_key: str, content_fingerprint: str) -> None:
-        """Invalidate cache entry when content fingerprint changes (AC-114.10.4)."""
-        key = self._make_key(row_key, content_fingerprint)
-        if key in self._entries:
-            del self._entries[key]
-
-    def clear(self) -> None:
-        """Clear all cache entries."""
-        self._entries.clear()
-        self._hits = 0
-        self._misses = 0
-
-    @property
-    def hit_rate(self) -> float:
-        """Calculate cache hit rate."""
-        total = self._hits + self._misses
-        return self._hits / total if total > 0 else 0.0
-
-    @property
-    def size(self) -> int:
-        """Return number of entries in cache."""
-        return len(self._entries)
-
-
-# ============================================================================
-# Phase 114 Package B: NLP Enrichment Layer (FR-114.4, FR-114.5, FR-114.6, FR-114.7)
-# ============================================================================
-
-import json
-import math
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-# Import embedding client for BGE-M3 exemplar similarity
-try:
-    from vds_audit_orchestrator.evidence.embedding_client import OllamaEmbeddingClient
-except ImportError:
-    OllamaEmbeddingClient = None  # type: ignore
-
-
-# Vietnamese-to-English concept map for cross-language signal injection (DD-114.6)
-# ~30 entries mapping Vietnamese technical terms to English marker families
-_VN_EN_CONCEPT_MAP: dict[str, list[str]] = {
-    # Database & data terms
-    "cơ sở dữ liệu": ["database", "data store"],
-    "co so du lieu": ["database", "data store"],
-    "csdl": ["database"],
-    # Authentication & authorization
-    "xác thực": ["authentication", "auth"],
-    "xac thuc": ["authentication", "auth"],
-    "xác thực người dùng": ["authentication", "user auth"],
-    "phân quyền": ["authorization", "access control"],
-    "phan quyen": ["authorization", "access control"],
-    "quyền truy cập": ["access control", "authorization"],
-    # Dependencies & coupling
-    "phụ thuộc": ["dependency", "coupling"],
-    "phu thuoc": ["dependency", "coupling"],
-    "phu thuộc vòng tròn": ["circular dependency"],
-    "dependency": ["dependency"],
-    # Architecture terms
-    "kiến trúc": ["architecture", "design"],
-    "kien truc": ["architecture", "design"],
-    "kiến trúc sạch": ["clean architecture"],
-    "kiến trúc hexagonal": ["hexagonal architecture"],
-    "hexagonal": ["hexagonal architecture"],
-    # Deployment & infrastructure
-    "triển khai": ["deployment", "deploy"],
-    "trien khai": ["deployment", "deploy"],
-    "docker": ["docker", "dockerfile", "container"],
-    "kubernetes": ["kubernetes", "k8s"],
-    "helm": ["helm", "helm chart"],
-    # Documentation terms
-    "tài liệu": ["documentation", "docs"],
-    "tai lieu": ["documentation", "docs"],
-    "tài liệu kỹ thuật": ["technical documentation"],
-    # Security terms
-    "bảo mật": ["security"],
-    "bao mat": ["security"],
-    "bảo mật thông tin": ["information security"],
-    "lỗ hổng bảo mật": ["security vulnerability"],
-    # API terms
-    "api": ["api", "rest api", "endpoint"],
-    "openapi": ["openapi", "swagger"],
-    "swagger": ["swagger", "openapi"],
-    # Testing terms
-    "kiểm thử": ["testing", "test"],
-    "kiem thu": ["testing", "test"],
-    "kiểm thử đơn vị": ["unit test"],
-    "kiểm thử tích hợp": ["integration test"],
-    # Code quality
-    "chất lượng mã": ["code quality"],
-    "chat luong ma": ["code quality"],
-    "tiêu chuẩn mã": ["code standard"],
-    # Error handling
-    "xử lý lỗi": ["error handling"],
-    "xu ly loi": ["error handling"],
-    "ghi log": ["logging", "log"],
-    # Performance & availability
-    "hiệu suất": ["performance"],
-    "hieu suat": ["performance"],
-    "khả dụng": ["availability", "high availability"],
-    "kha dung": ["availability", "high availability"],
-    # Configuration
-    "cấu hình": ["configuration", "config"],
-    "cau hinh": ["configuration", "config"],
-    # Modular design
-    "module": ["module"],
-    "dịch vụ": ["service"],
-    "dich vu": ["service"],
-    # Domain & design patterns
-    "domain": ["domain"],
-    "adapter": ["adapter"],
-    "port": ["port"],
-}
-
-
-def normalize_vietnamese_for_matching(text: str) -> str:
-    """Unicode NFC normalize for Vietnamese text before marker matching (DD-114.11).
-
-    Args:
-        text: Input text that may contain Vietnamese diacritics
-
-    Returns:
-        NFC-normalized text for consistent matching
-    """
-    return unicodedata.normalize("NFC", str(text))
-
-
-def strip_vietnamese_diacritics(text: str) -> str:
-    """NFD decompose + remove combining marks for diacritic-insensitive matching (DD-114.8).
-
-    Args:
-        text: Input text with Vietnamese diacritics
-
-    Returns:
-        Text with diacritics removed (e.g., "tài liệu" → "tai lieu")
-    """
-    nfd = unicodedata.normalize("NFD", str(text))
-    # Remove combining marks (category "Mn" = Mark, Nonspacing)
-    return "".join(c for c in nfd if unicodedata.category(c) != "Mn")
-
-
-def extract_cross_language_signals(text: str) -> list[str]:
-    """Extract English concept signals from Vietnamese text via concept map (FR-114.7).
-
-    Args:
-        text: Vietnamese or mixed Vietnamese/English requirement text
-
-    Returns:
-        List of English concept signals found in the text (deduplicated)
-    """
-    normalized = normalize_vietnamese_for_matching(text).lower()
-    signals: list[str] = []
-
-    for vn_term, en_concepts in _VN_EN_CONCEPT_MAP.items():
-        # Check both with and without diacritics for robustness
-        if vn_term.lower() in normalized:
-            signals.extend(en_concepts)
-        # Also check diacritic-stripped version
-        if strip_vietnamese_diacritics(vn_term.lower()) in strip_vietnamese_diacritics(normalized):
-            signals.extend(en_concepts)
-
-    # Deduplicate while preserving order
-    return list(dict.fromkeys(signals))
-
-
-def is_vietnamese_text(text: str) -> bool:
-    """Detect if text contains significant Vietnamese content.
-
-    Args:
-        text: Input text to analyze
-
-    Returns:
-        True if text contains Vietnamese diacritics or common VN markers
-    """
-    # Check for Vietnamese-specific diacritic ranges
-    for char in str(text):
-        code = ord(char)
-        # Vietnamese characters in Unicode Extended-A and other ranges
-        if (0x1EA0 <= code <= 0x1EF9) or (0x00C0 <= code <= 0x00AF):
-            return True
-    # Check for common Vietnamese words
-    lower = text.lower()
-    vn_markers = [
-        "tài liệu",
-        "tai lieu",
-        "kiểm tra",
-        "kiem tra",
-        "xác thực",
-        "xac thuc",
-        "triển khai",
-        "trien khai",
-        "cấu hình",
-        "cau hinh",
-    ]
-    return any(marker in lower for marker in vn_markers)
-
-
-# Exemplar-based classification (FR-114.4, FR-114.5, DD-114.2, DD-114.3)
-
-
-@dataclass(frozen=True, slots=True)
-class ExemplarClassificationResult:
-    """Result of exemplar-based classification via BGE-M3 similarity (FR-114.5)."""
-
-    # Classification outputs
-    analysis_mode: str | None = None
-    project_scope_required: bool | None = None
-    risk_focus: str | None = None
-
-    # Confidence metadata
-    confidence: float = 0.0  # Combined confidence: vote_share × top_similarity
-    top_similarity: float = 0.0  # Highest cosine similarity among top-k
-    vote_share: float = 0.0  # Proportion of top-k votes for winner
-
-    # Top matches for diagnostics
-    top_matches: list[tuple[str, float]] = field(default_factory=list)  # (exemplar_id, similarity)
-
-    # Classification status
-    has_confident_match: bool = False  # True if confidence >= 0.7
-
-
-@dataclass(slots=True)
-class ExemplarEmbeddingCache:
-    """Cache for pre-computed BGE-M3 exemplar embeddings (FR-114.4, DD-114.3).
-
-    Exemplars are loaded once per process from data/requirement_exemplars.json
-    and embeddings are computed on first use.
-    """
-
-    _exemplars: list[dict[str, Any]] = field(default_factory=list)
-    _embeddings: dict[str, list[float]] = field(default_factory=dict)  # exemplar_id -> vector
-    _loaded: bool = False
-    _embedding_client: OllamaEmbeddingClient | None = field(default=None)
-
-    @property
-    def is_loaded(self) -> bool:
-        """Check if exemplars have been loaded from JSON file."""
-        return self._loaded
-
-    @property
-    def size(self) -> int:
-        """Return number of loaded exemplars."""
-        return len(self._exemplars)
-
-    def load_exemplars(self, path: str | Path | None = None) -> None:
-        """Load exemplars from JSON file (FR-114.4, DD-114.12).
-
-        Args:
-            path: Path to exemplars JSON file. If None, uses default path.
-        """
-        if self._loaded:
-            return
-
-        if path is None:
-            # Default path: audit_orchestrator/data/requirement_exemplars.json at repo root.
-            # requirement_classification.py lives under src/vds_audit_orchestrator/engine/,
-            # so parent[3] is the package root directory that owns data/.
-            package_root = Path(__file__).resolve().parents[3]
-            path = package_root / "data" / "requirement_exemplars.json"
-
-        try:
-            with open(path, encoding="utf-8") as f:
-                data = json.load(f)
-            self._exemplars = data.get("exemplars", [])
-            self._loaded = True
-        except (FileNotFoundError, json.JSONDecodeError):
-            # Fail gracefully - exemplar classification becomes unavailable
-            self._exemplars = []
-            self._loaded = True
-
-    def get_embedding_client(self) -> OllamaEmbeddingClient | None:
-        """Get or create the embedding client for BGE-M3."""
-        if self._embedding_client is None and OllamaEmbeddingClient is not None:
-            # Check if NLP is enabled via env var (FR-114.5)
-            if os.getenv("VDS_AUDIT_REQUIREMENT_NLP_ENABLED", "false").lower() == "true":
-                self._embedding_client = OllamaEmbeddingClient(model="bge-m3")
-        return self._embedding_client
-
-    def ensure_embeddings(self) -> None:
-        """Ensure all exemplar embeddings are computed and cached."""
-        if not self._loaded:
-            self.load_exemplars()
-
-        client = self.get_embedding_client()
-        if client is None:
-            return  # NLP not available
-
-        # Collect exemplar IDs that need embedding
-        missing_ids = [
-            ex.get("id") or ex.get("exemplar_id", "")
-            for ex in self._exemplars
-            if (ex.get("id") or ex.get("exemplar_id")) not in self._embeddings
-        ]
-
-        if not missing_ids:
-            return  # All embeddings already cached
-
-        # Compute embeddings for missing exemplars
-        texts_to_embed = []
-        ids_to_embed = []
-        for ex in self._exemplars:
-            ex_id = ex.get("id") or ex.get("exemplar_id", "")
-            if ex_id in missing_ids:
-                # Use both VN and EN text for bilingual support
-                vn_text = ex.get("requirement_text", "")
-                en_text = ex.get("requirement_en", "")
-                # Combine both for cross-lingual matching
-                combined = f"{vn_text} {en_text}".strip()
-                texts_to_embed.append(combined)
-                ids_to_embed.append(ex_id)
-
-        if not texts_to_embed:
-            return
-
-        try:
-            result = client.embed_texts(texts_to_embed)
-            for ex_id, vector in zip(ids_to_embed, result.vectors, strict=False):
-                self._embeddings[ex_id] = vector
-        except Exception:
-            # Fail gracefully - individual exemplar embedding failures don't block
-            pass
-
-    def get_exemplar_embedding(self, exemplar_id: str) -> list[float] | None:
-        """Get cached embedding for a specific exemplar."""
-        if exemplar_id in self._embeddings:
-            return self._embeddings[exemplar_id]
-        return None
-
-    def find_similar_exemplars(
-        self,
-        query_text: str,
-        *,
-        top_k: int = 5,
-        min_similarity: float = 0.0,
-    ) -> list[tuple[str, float]]:
-        """Find top-k most similar exemplars via cosine similarity (FR-114.5, DD-114.3).
-
-        Args:
-            query_text: Requirement text to classify
-            top_k: Number of top matches to return (default: 5)
-            min_similarity: Minimum similarity threshold (default: 0.0)
-
-        Returns:
-            List of (exemplar_id, similarity) tuples, sorted by similarity descending
-        """
-        self.ensure_embeddings()
-
-        client = self.get_embedding_client()
-        if client is None or not self._exemplars:
-            return []  # NLP not available or no exemplars
-
-        # Embed query
-        try:
-            result = client.embed_texts([query_text])
-            query_vector = result.vectors[0] if result.vectors else []
-            if not query_vector:
-                return []
-        except Exception:
-            return []
-
-        # Compute cosine similarity with all exemplars
-        similarities: list[tuple[str, float]] = []
-        for ex in self._exemplars:
-            ex_id = ex.get("id") or ex.get("exemplar_id", "")
-            ex_vector = self._embeddings.get(ex_id)
-            if ex_vector is None:
-                continue
-
-            # Cosine similarity: dot(a,b) / (|a| * |b|)
-            dot_product = sum(a * b for a, b in zip(query_vector, ex_vector, strict=False))
-            norm_a = math.sqrt(sum(a * a for a in query_vector))
-            norm_b = math.sqrt(sum(b * b for b in ex_vector))
-            similarity = dot_product / (norm_a * norm_b) if norm_a > 0 and norm_b > 0 else 0.0
-
-            if similarity >= min_similarity:
-                similarities.append((ex_id, similarity))
-
-        # Sort by similarity descending and return top-k
-        similarities.sort(key=lambda x: x[1], reverse=True)
-        return similarities[:top_k]
-
-    def classify_by_exemplar_similarity(
-        self,
-        query_text: str,
-        *,
-        top_k: int = 5,
-        min_confidence: float = 0.0,
-    ) -> ExemplarClassificationResult:
-        """Classify requirement via top-k weighted voting (FR-114.5, DD-114.3).
-
-        Classification algorithm:
-        1. Embed query via BGE-M3
-        2. Find top-k most similar exemplars by cosine similarity
-        3. Weight each vote by similarity² (amplifies strong matches)
-        4. Winner = argmax(vote totals)
-        5. Confidence = vote_share × top_similarity
-
-        Args:
-            query_text: Requirement text to classify
-            top_k: Number of exemplars to consider for voting (default: 5)
-            min_confidence: Minimum confidence for has_confident_match flag
-
-        Returns:
-            ExemplarClassificationResult with classification and confidence
-        """
-        # NFR-114.6: Emit classification started telemetry (NFR-114.6, DD-114.4)
-        logger.info(
-            "nlp_classification_started",
-            query_length=len(query_text),
-            top_k=top_k,
-            min_confidence=min_confidence,
-        )
-
-        # Find top-k similar exemplars
-        top_matches = self.find_similar_exemplars(query_text, top_k=top_k)
-
-        if not top_matches:
-            return ExemplarClassificationResult(
-                confidence=0.0,
-                top_similarity=0.0,
-                vote_share=0.0,
-                top_matches=[],
-                has_confident_match=False,
-            )
-
-        # Weighted voting: similarity² weighting (DD-114.3)
-        votes: dict[str, float] = {}
-        total_weight = 0.0
-
-        for exemplar_id, similarity in top_matches:
-            ex = next(
-                (e for e in self._exemplars if (e.get("id") or e.get("exemplar_id", "")) == exemplar_id),
-                None,
-            )
-            if not ex:
-                continue
-
-            gt = ex.get("ground_truth", {})
-            analysis_mode = gt.get("analysis_mode", "")
-            project_scope = gt.get("project_scope_required", False)
-            risk_focus = gt.get("risk_focus", "")
-
-            # Weight by similarity squared to amplify strong matches
-            weight = similarity * similarity
-
-            votes[f"mode:{analysis_mode}"] = votes.get(f"mode:{analysis_mode}", 0.0) + weight
-            votes[f"scope:{project_scope}"] = votes.get(f"scope:{project_scope}", 0.0) + weight
-            votes[f"risk:{risk_focus}"] = votes.get(f"risk:{risk_focus}", 0.0) + weight
-            total_weight += weight
-
-        if total_weight == 0:
-            return ExemplarClassificationResult(
-                confidence=0.0,
-                top_similarity=top_matches[0][1] if top_matches else 0.0,
-                vote_share=0.0,
-                top_matches=top_matches,
-                has_confident_match=False,
-            )
-
-        # Determine winners
-        best_mode = max(
-            ((k, v) for k, v in votes.items() if k.startswith("mode:")),
-            key=lambda item: item[1],
-        )
-        best_scope = max(
-            ((k, v) for k, v in votes.items() if k.startswith("scope:")),
-            key=lambda item: item[1],
-        )
-        best_risk = max(
-            ((k, v) for k, v in votes.items() if k.startswith("risk:")),
-            key=lambda item: item[1],
-        )
-
-        # Extract values
-        analysis_mode = best_mode[0].split(":", 1)[1] if best_mode[1] > 0 else None
-        project_scope_str = best_scope[0].split(":", 1)[1] if best_scope[1] > 0 else None
-        project_scope = project_scope_str == "True" if project_scope_str else None
-        risk_focus = best_risk[0].split(":", 1)[1] if best_risk[1] > 0 else None
-
-        # Compute confidence metrics
-        top_similarity = top_matches[0][1] if top_matches else 0.0
-        vote_share = best_mode[1] / total_weight if total_weight > 0 else 0.0
-        confidence = vote_share * top_similarity
-
-        # Build result before telemetry
-        result = ExemplarClassificationResult(
-            analysis_mode=analysis_mode,
-            project_scope_required=project_scope,
-            risk_focus=risk_focus,
-            confidence=confidence,
-            top_similarity=top_similarity,
-            vote_share=vote_share,
-            top_matches=top_matches,
-            has_confident_match=confidence >= min_confidence,
-        )
-
-        # NFR-114.6: Emit classification completed telemetry (NFR-114.6, DD-114.4)
-        logger.info(
-            "nlp_classification_completed",
-            similarity_score=result.top_similarity,
-            top_mode=result.analysis_mode,
-            vote_count=len(top_matches),
-            cache_hit=False,  # Always false: classification computed fresh each time
-            has_confident_match=result.has_confident_match,
-        )
-
-        return result
-
-
-# Global exemplar cache singleton (initialized on first use)
-_global_exemplar_cache: ExemplarEmbeddingCache | None = None
-
-
-def get_global_exemplar_cache() -> ExemplarEmbeddingCache:
-    """Get the global exemplar embedding cache singleton."""
-    global _global_exemplar_cache
-    if _global_exemplar_cache is None:
-        _global_exemplar_cache = ExemplarEmbeddingCache()
-    return _global_exemplar_cache
-
-
-# Heuristic-NLP arbitration logic (FR-114.6, DD-114.1)
-
-
-@dataclass(frozen=True, slots=True)
-class ArbitrationResult:
-    """Result of heuristic-NLP arbitration (FR-114.6)."""
-
-    # Final classification (may be heuristic or NLP)
-    analysis_mode: str
-    project_scope_required: bool
-    classification_source: ClassificationSource
-
-    # Confidence after arbitration
-    final_confidence: float
-
-    # Arbitration metadata
-    heuristic_confidence: float
-    nlp_confidence: float | None
-    nlp_agreed: bool
-    arbitration_outcome: Literal[
-        "heuristic_kept",
-        "nlp_agreement_boost",
-        "nlp_high_similarity_adopted",
-        "escalated_to_layer3",
-        "nlp_unavailable",
-    ]
-
-    # NLP details (if available)
-    nlp_top_similarity: float = 0.0
-    nlp_vote_share: float = 0.0
-
-
-def arbitrate_heuristic_nlp(
-    *,
-    _heuristic_result: RequirementAnalysisResult,
-    heuristic_confidence: float,
-    nlp_result: ExemplarClassificationResult | None,
-    analysis_mode: str,
-    project_scope_required: bool,
-    _finalization_policy: str,
-) -> ArbitrationResult:
-    """Arbitrate between heuristic and NLP classification (FR-114.6, DD-114.1).
-
-    Arbitration rules:
-    1. If NLP unavailable → use heuristic
-    2. If heuristic confidence >= 0.8 → use heuristic (Layer 1 sufficient)
-    3. If NLP agrees with heuristic → boost to 0.85, source = nlp_enrichment
-    4. If NLP disagrees + high similarity (> 0.85) → adopt NLP
-    5. If NLP disagrees + low similarity → escalate to Layer 3
-
-    Args:
-        heuristic_result: Result from heuristic classification
-        heuristic_confidence: Confidence score from heuristic (0-1)
-        nlp_result: Result from NLP exemplar classification (None if unavailable)
-        analysis_mode: Current analysis mode from heuristic
-        project_scope_required: Current project scope from heuristic
-        finalization_policy: Current finalization policy
-
-    Returns:
-        ArbitrationResult with final classification and arbitration metadata
-    """
-    # NFR-114.6: Emit arbitration started telemetry (NFR-114.6, DD-114.4)
-    logger.info(
-        "nlp_arbitration_started",
-        heuristic_confidence=heuristic_confidence,
-        heuristic_mode=analysis_mode,
-        heuristic_scope=project_scope_required,
-        nlp_available=nlp_result is not None,
-    )
-
-    # Check if NLP is enabled and available
-    nlp_enabled = os.getenv("VDS_AUDIT_REQUIREMENT_NLP_ENABLED", "false").lower() == "true"
-    if not nlp_enabled or nlp_result is None:
-        outcome = "nlp_unavailable"
-        logger.info("nlp_arbitration_completed", arbitration_outcome=outcome)
-        return ArbitrationResult(
-            analysis_mode=analysis_mode,
-            project_scope_required=project_scope_required,
-            classification_source=ClassificationSource.HEURISTIC,
-            final_confidence=heuristic_confidence,
-            heuristic_confidence=heuristic_confidence,
-            nlp_confidence=None,
-            nlp_agreed=False,
-            arbitration_outcome=outcome,
-        )
-
-    # Layer 1 fast path: high heuristic confidence
-    if heuristic_confidence >= 0.8:
-        outcome = "heuristic_kept"
-        logger.info("nlp_arbitration_completed", arbitration_outcome=outcome)
-        return ArbitrationResult(
-            analysis_mode=analysis_mode,
-            project_scope_required=project_scope_required,
-            classification_source=ClassificationSource.HEURISTIC,
-            final_confidence=heuristic_confidence,
-            heuristic_confidence=heuristic_confidence,
-            nlp_confidence=nlp_result.confidence,
-            nlp_agreed=False,  # NLP not consulted
-            arbitration_outcome=outcome,
-        )
-
-    # Check for NLP-heuristic agreement
-    nlp_mode = nlp_result.analysis_mode
-    nlp_scope = nlp_result.project_scope_required
-
-    mode_agrees = nlp_mode == analysis_mode if nlp_mode else True
-    scope_agrees = nlp_scope == project_scope_required if nlp_scope is not None else True
-    nlp_agrees = mode_agrees and scope_agrees
-
-    if nlp_agrees:
-        # Boost confidence when NLP confirms heuristic
-        outcome = "nlp_agreement_boost"
-        logger.info(
-            "nlp_arbitration_completed",
-            arbitration_outcome=outcome,
-            nlp_agreed=True,
-            nlp_similarity=nlp_result.top_similarity,
-        )
-        return ArbitrationResult(
-            analysis_mode=analysis_mode,
-            project_scope_required=project_scope_required,
-            classification_source=ClassificationSource.NLP_ENRICHMENT,
-            final_confidence=max(heuristic_confidence, 0.85),
-            heuristic_confidence=heuristic_confidence,
-            nlp_confidence=nlp_result.confidence,
-            nlp_agreed=True,
-            arbitration_outcome=outcome,
-            nlp_top_similarity=nlp_result.top_similarity,
-            nlp_vote_share=nlp_result.vote_share,
-        )
-
-    # NLP disagrees - check similarity strength
-    if nlp_result.top_similarity > 0.85:
-        # High similarity - adopt NLP classification
-        final_mode = nlp_mode or analysis_mode
-        final_scope = nlp_scope if nlp_scope is not None else project_scope_required
-        outcome = "nlp_high_similarity_adopted"
-        logger.info(
-            "nlp_arbitration_completed",
-            arbitration_outcome=outcome,
-            nlp_agreed=False,
-            nlp_similarity=nlp_result.top_similarity,
-            nlp_adopted=True,
-        )
-        return ArbitrationResult(
-            analysis_mode=final_mode,
-            project_scope_required=final_scope,
-            classification_source=ClassificationSource.NLP_ENRICHMENT,
-            final_confidence=nlp_result.confidence,
-            heuristic_confidence=heuristic_confidence,
-            nlp_confidence=nlp_result.confidence,
-            nlp_agreed=False,
-            arbitration_outcome=outcome,
-            nlp_top_similarity=nlp_result.top_similarity,
-            nlp_vote_share=nlp_result.vote_share,
-        )
-
-    # Low similarity - escalate to Layer 3
-    outcome = "escalated_to_layer3"
-    logger.info(
-        "nlp_arbitration_completed",
-        arbitration_outcome=outcome,
-        nlp_agreed=False,
-        nlp_similarity=nlp_result.top_similarity,
-    )
-    return ArbitrationResult(
-        analysis_mode=analysis_mode,
-        project_scope_required=project_scope_required,
-        classification_source=ClassificationSource.HEURISTIC,  # Tentative
-        final_confidence=heuristic_confidence,  # Low confidence signals need for Layer 3
-        heuristic_confidence=heuristic_confidence,
-        nlp_confidence=nlp_result.confidence,
-        nlp_agreed=False,
-        arbitration_outcome=outcome,
-        nlp_top_similarity=nlp_result.top_similarity,
-        nlp_vote_share=nlp_result.vote_share,
-    )
-
-
-def enrich_requirement_with_vietnamese_signals(
-    requirement_text: str,
-    _requirement_category: str,
-) -> tuple[str, list[str]]:
-    """Enrich requirement with cross-language Vietnamese signals (FR-114.7, DD-114.6).
-
-    Applies Unicode NFC normalization, extracts English concept signals
-    from Vietnamese text, and returns both normalized text and signals.
-
-    Args:
-        requirement_text: Raw requirement text (may contain Vietnamese)
-        requirement_category: Requirement category/family
-
-    Returns:
-        Tuple of (normalized_text, english_signals)
-    """
-    # Normalize Vietnamese text
-    normalized_text = normalize_vietnamese_for_matching(requirement_text)
-
-    # Extract cross-language signals
-    english_signals = extract_cross_language_signals(normalized_text)
-
-    return normalized_text, english_signals
-
-
-# Enhanced requirement analysis with NLP integration
-
-
-def classify_requirement_with_nlp_enrichment(
-    *,
-    requirement_text: str,
-    requirement_category: str = "",
-    heuristic_result: RequirementAnalysisResult | None = None,
-    heuristic_confidence: float = 0.5,
-) -> tuple[RequirementAnalysisResult, ArbitrationResult]:
-    """Classify requirement with NLP enrichment layer (FR-114.4, FR-114.5, FR-114.6, FR-114.7).
-
-    This integrates all P114-B components:
-    1. Vietnamese cross-language signal enrichment (FR-114.7)
-    2. Exemplar-based classification (FR-114.4, FR-114.5)
-    3. Heuristic-NLP arbitration (FR-114.6)
-
-    Args:
-        requirement_text: The requirement description
-        requirement_category: Optional category/family
-        heuristic_result: Result from heuristic (Layer 1) classification
-        heuristic_confidence: Confidence from heuristic (0-1)
-
-    Returns:
-        Tuple of (final_analysis_result, arbitration_result)
-    """
-    # Import for use in construction
-    from vds_audit_orchestrator.engine.requirement_analysis import (
-        RequirementAnalysisResult as _RequirementAnalysisResult,
-    )
-    from vds_audit_orchestrator.engine.requirement_analysis import (
-        analyze_requirement_intent,
-    )
-
-    # Apply Vietnamese enrichment (FR-114.7)
-    normalized_text, vn_signals = enrich_requirement_with_vietnamese_signals(
-        requirement_text,
-        requirement_category,
-    )
-
-    # Build enriched text (original + injected signals)
-    enriched_text = normalized_text
-    if vn_signals:
-        # Append English signals for better matching
-        signal_text = " ".join(vn_signals)
-        enriched_text = f"{normalized_text} {signal_text}"
-
-    # Default heuristic result if not provided
-    if heuristic_result is None:
-        heuristic_result = analyze_requirement_intent(
-            requirement_text=enriched_text,
-            requirement_category=requirement_category,
-        )
-
-    # Get NLP exemplar classification (FR-114.4, FR-114.5)
-    cache = get_global_exemplar_cache()
-    nlp_result = cache.classify_by_exemplar_similarity(
-        enriched_text,
-        top_k=5,
-        min_confidence=0.0,
-    )
-
-    # Arbitrate between heuristic and NLP (FR-114.6)
-    arbitration = arbitrate_heuristic_nlp(
-        heuristic_result=heuristic_result,
-        heuristic_confidence=heuristic_confidence,
-        nlp_result=nlp_result,
-        analysis_mode=heuristic_result.analysis_mode,
-        project_scope_required=heuristic_result.project_scope_required,
-        finalization_policy=heuristic_result.finalization_policy,
-    )
-
-    app_config_only_contract = (
-        heuristic_result.finalization_policy == "app_config_evidence_only"
-        or "app_config_only_requirement" in heuristic_result.analysis_reason_codes
-    )
-
-    # Build final result based on arbitration
-    if arbitration.arbitration_outcome in ("nlp_high_similarity_adopted",) and not app_config_only_contract:
-        # Adopt NLP classification
-        final_mode = arbitration.analysis_mode
-        final_scope = arbitration.project_scope_required
-        final_source = arbitration.classification_source
-        final_modalities = _default_modalities_for_analysis_mode(final_mode)
-    else:
-        # Keep heuristic (possibly boosted)
-        final_mode = heuristic_result.analysis_mode
-        final_scope = heuristic_result.project_scope_required
-        final_source = arbitration.classification_source
-        final_modalities = list(heuristic_result.required_anchor_modalities)
-
-    # Create enhanced result with NLP-enriched reason codes
-    enhanced_reason_codes = list(heuristic_result.analysis_reason_codes)
-    if vn_signals:
-        enhanced_reason_codes.append("vietnamese_cross_language_enrichment")
-    if final_source == ClassificationSource.NLP_ENRICHMENT:
-        enhanced_reason_codes.append("nlp_exemplar_classification")
-
-    classification_fingerprint = RequirementFingerprints.compute_classification_fingerprint(
-        analysis_mode=final_mode,
-        evidence_targets=final_modalities,
-        project_scope_required=final_scope,
-        finalization_policy=heuristic_result.finalization_policy,
-    )
-
-    # Construct final result using locally imported class
-    final_result = _RequirementAnalysisResult(
-        analysis_mode=final_mode,
-        analysis_reason_codes=enhanced_reason_codes,
-        required_anchor_modalities=final_modalities,
-        project_scope_required=final_scope,
-        execution_scope_class=heuristic_result.execution_scope_class,
-        generic_anchor_exemption=heuristic_result.generic_anchor_exemption,
-        minimum_substantive_code_anchors=heuristic_result.minimum_substantive_code_anchors,
-        finalization_policy=heuristic_result.finalization_policy,
-        heuristic_confidence=arbitration.final_confidence,
-        classification_source=final_source.value,
-        content_fingerprint=heuristic_result.content_fingerprint,
-        classification_fingerprint=classification_fingerprint,
-        nlp_exemplar_similarity=float(arbitration.nlp_top_similarity or nlp_result.top_similarity or 0.0),
-    )
-
-    return final_result, arbitration
-
-
-# Updated __all__ exports
-
-# ---------------------------------------------------------------------------
-# Phase 122 — Requirement Scope Classification (FR-122.1, TSK-122.1)
-# ---------------------------------------------------------------------------
-
-RequirementScope = Literal["repo-scoped", "infra-scoped", "manual-only"]
-ScopeClassificationSource = Literal["heuristic", "embedding", "llm", "fixture", "default"]
-
-# Layer 1 heuristic markers for scope classification.
-# Keys are lowercase marker strings; values are confidence weights (0.0–1.0).
-# A match on any marker in a dictionary assigns the corresponding scope.
-
-INFRA_SCOPE_MARKERS: dict[str, float] = {
-    # Container / orchestration
-    "dockerfile": 0.95,
-    "containerfile": 0.95,
-    "docker-compose": 0.90,
-    "docker compose": 0.90,
-    "kubernetes": 0.90,
-    "k8s": 0.90,
-    "helm chart": 0.90,
-    "helm": 0.80,
-    "terraform": 0.95,
-    "ansible": 0.90,
-    "jenkins pipeline": 0.90,
-    "jenkinsfile": 0.90,
-    # CI/CD
-    "ci/cd pipeline": 0.85,
-    "ci/cd": 0.80,
-    "gitlab-ci": 0.85,
-    "github actions": 0.85,
-    ".github/workflows": 0.90,
-    # Infrastructure
-    "load balancer": 0.85,
-    "cân bằng tải": 0.85,
-    "firewall": 0.85,
-    "tường lửa": 0.85,
-    "dns configuration": 0.85,
-    "cấu hình dns": 0.85,
-    "ssl certificate": 0.85,
-    "chứng chỉ ssl": 0.85,
-    "network policy": 0.85,
-    "chính sách mạng": 0.85,
-    "ingress controller": 0.85,
-    "service mesh": 0.85,
-    "istio": 0.85,
-    # Server / OS level
-    "server configuration": 0.80,
-    "cấu hình server": 0.80,
-    "cấu hình máy chủ": 0.80,
-    "os hardening": 0.85,
-    "system monitoring": 0.80,
-    "giám sát hệ thống": 0.80,
-    "infrastructure as code": 0.90,
-    "hạ tầng": 0.75,
-    # Deployment-only (not discoverable from app source)
-    "deployment topology": 0.85,
-    "triển khai hạ tầng": 0.85,
-    "blue-green deployment": 0.80,
-    "canary deployment": 0.80,
-    "rolling update": 0.75,
-}
-
-REPO_SCOPE_MARKERS: dict[str, float] = {
-    # Architecture / boundary checks that are directly discoverable from source code
-    "hexagonal / clean architecture": 0.98,
-    "hexagonal architecture": 0.97,
-    "clean architecture": 0.97,
-    "hexagonal": 0.94,
-    "domain logic": 0.94,
-    "ports & adapters": 0.98,
-    "ports and adapters": 0.98,
-    "dependency inversion": 0.92,
-    "kiến trúc sạch": 0.94,
-    "kiến trúc hexagonal": 0.94,
-    "không phụ thuộc vào framework": 0.96,
-    "khong phu thuoc vao framework": 0.96,
-}
-
-MANUAL_ONLY_MARKERS: dict[str, float] = {
-    # Explicit manual verification
-    "manual verification": 0.90,
-    "kiểm tra thủ công": 0.90,
-    "xác minh thủ công": 0.90,
-    "manual review": 0.85,
-    "đánh giá thủ công": 0.85,
-    "manual testing": 0.85,
-    "kiểm thử thủ công": 0.85,
-    # Physical / human process
-    "physical access": 0.90,
-    "truy cập vật lý": 0.90,
-    "on-site inspection": 0.90,
-    "kiểm tra tại chỗ": 0.90,
-    "interview": 0.80,
-    "phỏng vấn": 0.80,
-    # Organizational / policy
-    "organizational policy": 0.80,
-    "chính sách tổ chức": 0.80,
-    "training record": 0.85,
-    "hồ sơ đào tạo": 0.85,
-    "approval process": 0.75,
-    "quy trình phê duyệt": 0.75,
-    "sign-off": 0.80,
-    "ký duyệt": 0.80,
-    # Compliance / audit trail
-    "audit trail review": 0.80,
-    "xem xét nhật ký kiểm toán": 0.80,
-    "compliance documentation": 0.75,
-    "tài liệu tuân thủ": 0.75,
-    "penetration test report": 0.85,
-    "báo cáo kiểm thử xâm nhập": 0.85,
-}
-
-# Confidence threshold for Layer 1 heuristic scope classification.
-_SCOPE_HEURISTIC_CONFIDENCE_THRESHOLD = 0.70
-
-
-def _layer1_scope_heuristic(
-    requirement_text: str,
-    requirement_category: str,
-) -> tuple[RequirementScope, float, list[str]] | None:
-    """Layer 1: Deterministic marker-based scope classification.
-
-    Returns (scope, confidence, matched_markers) or None if no match above threshold.
-    """
-    text_lower = (requirement_text or "").lower()
-    category_lower = (requirement_category or "").lower()
-    combined = f"{text_lower} {category_lower}"
-
-    # Check infra markers
-    infra_matches: list[tuple[str, float]] = []
-    for marker, weight in INFRA_SCOPE_MARKERS.items():
-        if marker in combined:
-            infra_matches.append((marker, weight))
-
-    # Check repo-scoped markers
-    repo_matches: list[tuple[str, float]] = []
-    for marker, weight in REPO_SCOPE_MARKERS.items():
-        if marker in combined:
-            repo_matches.append((marker, weight))
-
-    # Check manual markers
-    manual_matches: list[tuple[str, float]] = []
-    for marker, weight in MANUAL_ONLY_MARKERS.items():
-        if marker in combined:
-            manual_matches.append((marker, weight))
-
-    # Pick the scope with the highest max confidence
-    best_infra = max((w for _, w in infra_matches), default=0.0)
-    best_repo = max((w for _, w in repo_matches), default=0.0)
-    best_manual = max((w for _, w in manual_matches), default=0.0)
-
-    if best_repo >= _SCOPE_HEURISTIC_CONFIDENCE_THRESHOLD and best_repo > best_infra and best_repo >= best_manual:
-        matched = [m for m, _ in repo_matches]
-        return "repo-scoped", best_repo, matched
-
-    if best_infra >= _SCOPE_HEURISTIC_CONFIDENCE_THRESHOLD and best_infra >= best_manual:
-        matched = [m for m, _ in infra_matches]
-        return "infra-scoped", best_infra, matched
-
-    if best_manual >= _SCOPE_HEURISTIC_CONFIDENCE_THRESHOLD:
-        matched = [m for m, _ in manual_matches]
-        return "manual-only", best_manual, matched
-
-    return None
-
-
-def _layer2_scope_embedding(
-    requirement_text: str,
-    requirement_category: str,
-) -> tuple[RequirementScope, float, str] | None:
-    """Layer 2: Embedding similarity against scope-labeled exemplars.
-
-    Returns (scope, confidence, exemplar_id) or None if no confident match.
-    """
-    try:
-        cache = get_global_exemplar_cache()
-        result = cache.classify_by_exemplar_similarity(
-            f"{requirement_text} {requirement_category}",
-            top_k=3,
-            min_confidence=0.0,
-        )
-        if result and result.top_similarity >= 0.75:
-            # Check if the matched exemplar has a scope label
-            exemplar_id = result.exemplar_id or ""
-            scope_label = getattr(result, "scope_label", None)
-            if scope_label and scope_label in {"repo-scoped", "infra-scoped", "manual-only"}:
-                return scope_label, result.top_similarity, exemplar_id
-    except Exception:
-        logger.debug("scope_embedding_layer_unavailable")
-    return None
-
-
-def _layer3_scope_llm(
-    _requirement_text: str,
-    _requirement_category: str,
-) -> tuple[RequirementScope, float] | None:
-    """Layer 3: LLM fallback for scope classification.
-
-    Returns (scope, confidence) or None if LLM is unavailable or inconclusive.
-    This is a placeholder for future LLM integration — currently returns None
-    to fall through to the default repo-scoped classification.
-    """
-    # LLM scope classification is deferred to Phase 122 stabilization.
-    # The three-layer contract is satisfied: Layer 3 returns None → default to repo-scoped.
-    return None
-
-
-def classify_requirement_scope(
-    requirement_text: str,
-    requirement_category: str,
-    *,
-    fixtures: dict[str, Any] | None = None,
-) -> tuple[RequirementScope, float, ScopeClassificationSource]:
-    """Three-layer requirement scope classification (FR-122.1, AC-122.1.5).
-
-    Classification flow:
-    1. Check deterministic fixtures (if provided)
-    2. Layer 1: Heuristic marker matching
-    3. Layer 2: Embedding similarity against scope-labeled exemplars
-    4. Layer 3: LLM fallback
-    5. Default: repo-scoped with 1.0 confidence
-
-    Returns:
-        (requirement_scope, scope_confidence, scope_classification_source)
-    """
-    # Fixture override for deterministic testing
-    if fixtures:
-        text_key = (requirement_text or "").strip()
-        if text_key in fixtures:
-            entry = fixtures[text_key]
-            return (
-                entry.get("requirement_scope", "repo-scoped"),
-                float(entry.get("scope_confidence", 1.0)),
-                "fixture",
-            )
-
-    # Layer 1: Heuristic markers
-    layer1 = _layer1_scope_heuristic(requirement_text, requirement_category)
-    if layer1 is not None:
-        scope, confidence, matched = layer1
-        logger.debug(
-            "scope_classification_heuristic",
-            scope=scope,
-            confidence=confidence,
-            matched_markers=matched[:3],
-        )
-        return scope, confidence, "heuristic"
-
-    # Layer 2: Embedding similarity
-    layer2 = _layer2_scope_embedding(requirement_text, requirement_category)
-    if layer2 is not None:
-        scope, confidence, exemplar_id = layer2
-        logger.debug(
-            "scope_classification_embedding",
-            scope=scope,
-            confidence=confidence,
-            exemplar_id=exemplar_id,
-        )
-        return scope, confidence, "embedding"
-
-    # Layer 3: LLM fallback
-    layer3 = _layer3_scope_llm(requirement_text, requirement_category)
-    if layer3 is not None:
-        scope, confidence = layer3
-        logger.debug("scope_classification_llm", scope=scope, confidence=confidence)
-        return scope, confidence, "llm"
-
-    # Default: repo-scoped (actionable from application source)
-    return "repo-scoped", 1.0, "default"
-
-
-__all__ = [
-    "INFRA_SCOPE_MARKERS",
-    "MANUAL_ONLY_MARKERS",
-    "ArbitrationResult",
-    "ChecklistDriftSummary",
-    "ClassificationCacheEntry",
-    "ClassificationSource",
-    "DriftSeverity",
-    "ExemplarClassificationResult",
-    "ExemplarEmbeddingCache",
-    "RequirementClassificationCache",
-    "RequirementClassificationRecord",
-    "RequirementDriftReport",
-    "RequirementFingerprints",
-    # Phase 122 exports (FR-122.1)
-    "RequirementScope",
-    "ScopeClassificationSource",
-    "arbitrate_heuristic_nlp",
-    "build_drift_advisory_note",
-    "classify_requirement_scope",
-    "classify_requirement_with_nlp_enrichment",
-    "compute_row_drift",
-    "enrich_requirement_with_vietnamese_signals",
-    "extract_cross_language_signals",
-    "get_global_exemplar_cache",
-    "is_vietnamese_text",
-    # P114-B exports
-    "normalize_vietnamese_for_matching",
-    "strip_vietnamese_diacritics",
-]