@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,882 +0,0 @@
-"""Instruction-aware evaluation pipeline (Phase 122, FR-122.5).
-
-Two-layer instruction decomposition:
-- Layer 1: Vietnamese heuristic directive parser (_layer1_heuristic_parse)
-- Layer 2: LLM decomposition agent with knowledge-store caching (_layer2_llm_decompose)
-
-Produces InstructionPlan that drives evidence gathering and scoring rubric.
-
-Default-on control surface: ``features.instruction_analysis_enabled``.
-Legacy top-level env alias ``VDS_AUDIT_INSTRUCTION_ANALYSIS_ENABLED`` remains
-accepted as a compatibility override for older automation.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import re
-import uuid
-from dataclasses import asdict, dataclass
-from typing import Any
-
-import structlog
-
-from vds_audit_orchestrator.config import get_config
-from vds_audit_orchestrator.engine.project_knowledge_store import ProjectKnowledgeStore
-
-logger = structlog.get_logger(__name__)
-
-# ---------------------------------------------------------------------------
-# Type aliases (TSK-122.19, AC-122.5.2)
-# ---------------------------------------------------------------------------
-DirectiveType = str  # "search_file" | "search_config" | "search_code_pattern" |
-#                      "verify_absence" | "skip_infra" | "skip_manual" | "check_api"
-TargetScope = str  # "current_repo" | "config_repo" | "project_wide"
-
-VALID_DIRECTIVE_TYPES: frozenset[str] = frozenset(
-    {
-        "search_file",
-        "search_config",
-        "search_code_pattern",
-        "verify_absence",
-        "skip_infra",
-        "skip_manual",
-        "check_api",
-    }
-)
-
-VALID_TARGET_SCOPES: frozenset[str] = frozenset(
-    {
-        "current_repo",
-        "config_repo",
-        "project_wide",
-    }
-)
-
-VALID_VERDICTS: frozenset[str] = frozenset(
-    {
-        "PASS",
-        "FAIL",
-        "evidence_for_pass",
-        "evidence_for_fail",
-    }
-)
-
-# ---------------------------------------------------------------------------
-# Data models (TSK-122.19, DD-122.11)
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class InstructionDirective:
-    """A single directive extracted from instruction text (AC-122.5.2)."""
-
-    directive_type: str
-    target: str
-    target_scope: str = "current_repo"
-    rationale: str = ""
-
-    def is_valid(self) -> bool:
-        return (
-            self.directive_type in VALID_DIRECTIVE_TYPES
-            and self.target_scope in VALID_TARGET_SCOPES
-            and bool(self.target.strip())
-        )
-
-
-@dataclass(frozen=True, slots=True)
-class ScoringCriterion:
-    """A pass/fail criterion derived from instruction text (AC-122.5.3)."""
-
-    criterion: str
-    verdict_if_met: str = "PASS"
-    weight: float = 1.0
-    source_instruction: str = ""
-
-    def is_valid(self) -> bool:
-        return self.verdict_if_met in VALID_VERDICTS and 0.0 <= self.weight <= 1.0 and bool(self.criterion.strip())
-
-
-@dataclass(frozen=True, slots=True)
-class InstructionPlan:
-    """Structured execution contract between analysis and planner (DD-122.11)."""
-
-    plan_id: str = ""
-    requirement_key: str = ""
-    directives: tuple[InstructionDirective, ...] = ()
-    pass_criteria: tuple[ScoringCriterion, ...] = ()
-    fail_criteria: tuple[ScoringCriterion, ...] = ()
-    skip_decision: str | None = None
-    skip_reason: str | None = None
-    confidence: float = 0.0
-    analysis_source: str = "heuristic"
-    raw_instruction: str = ""
-
-    @property
-    def has_directives(self) -> bool:
-        return len(self.directives) > 0
-
-    @property
-    def has_scoring_criteria(self) -> bool:
-        return len(self.pass_criteria) > 0 or len(self.fail_criteria) > 0
-
-    @property
-    def should_skip(self) -> bool:
-        return self.skip_decision is not None
-
-    @property
-    def valid_directives(self) -> tuple[InstructionDirective, ...]:
-        return tuple(d for d in self.directives if d.is_valid())
-
-    @property
-    def evidence_targets(self) -> list[str]:
-        """Derive evidence targets from directives for planner integration."""
-        targets: list[str] = []
-        for d in self.valid_directives:
-            if d.directive_type not in ("skip_infra", "skip_manual"):
-                targets.append(d.target)
-        return targets
-
-    def to_dict(self) -> dict[str, Any]:
-        return asdict(self)
-
-
-@dataclass(frozen=True, slots=True)
-class ComplianceResult:
-    """Post-evaluation compliance check result (AC-122.5.8, DD-122.13)."""
-
-    compliant: bool = True
-    violations: tuple[str, ...] = ()
-    coverage_ratio: float = 1.0
-    rubric_alignment: float = 1.0
-    confidence_adjustment: float = 1.0
-
-    def to_dict(self) -> dict[str, Any]:
-        return asdict(self)
-
-
-# ---------------------------------------------------------------------------
-# Layer 1: Vietnamese heuristic directive parser (TSK-122.20, DD-122.10)
-# ---------------------------------------------------------------------------
-
-# Search-file patterns: Vietnamese instructions referencing specific files
-SEARCH_FILE_PATTERNS: dict[str, tuple[str, float]] = {
-    # (pattern, confidence)
-    r"(?i)kiểm tra\s+(?:file|tệp|tập tin)\s+(.+?)(?:\s+có|\s+để|\s*$)": ("search_file", 0.90),
-    r"(?i)tìm\s+(?:file|tệp)\s+(.+?)(?:\s+trong|\s+ở|\s*$)": ("search_file", 0.85),
-    r"(?i)xem\s+(?:file|tệp)\s+(.+?)(?:\s+có|\s*$)": ("search_file", 0.85),
-    r"(?i)(?:application|app)[\w\-]*\.(?:yml|yaml|properties|conf)": ("search_config", 0.90),
-    r"(?i)(?:docker-compose|dockerfile|\.dockerignore)": ("search_file", 0.90),
-    r"(?i)(?:pom\.xml|build\.gradle|package\.json|pyproject\.toml)": ("search_file", 0.90),
-    r"(?i)(?:\.env|\.env\.\w+)": ("search_config", 0.85),
-    r"(?i)cấu hình\s+(.+?)(?:\s+có|\s+để|\s*$)": ("search_config", 0.85),
-    r"(?i)(?:config|cấu hình)\s+(?:file|tệp)\s+(.+)": ("search_config", 0.85),
-    r"(?i)kiểm tra\s+cấu hình\s+(.+)": ("search_config", 0.85),
-}
-
-# Skip-infra patterns: instructions about infrastructure that can't be checked in code
-# Includes both instruction-style (imperative verbs) and requirement-style (declarative) patterns
-SKIP_INFRA_PATTERNS: dict[str, float] = {
-    # Instruction-style patterns (original)
-    r"(?i)kiểm tra\s+(?:trên\s+)?(?:server|máy chủ)\s+(?:production|staging|dev)": 0.90,
-    r"(?i)(?:anthropic|azure|gcp|cloud)\s+(?:console|portal|dashboard)": 0.90,
-    r"(?i)kiểm tra\s+(?:trực tiếp\s+)?(?:trên\s+)?(?:hệ thống|hạ tầng)\s+(?:thực tế|production)": 0.90,
-    r"(?i)(?:monitoring|grafana|prometheus|datadog)\s+(?:dashboard|alert)": 0.85,
-    r"(?i)kiểm tra\s+(?:log|nhật ký)\s+(?:trên\s+)?(?:server|hệ thống)": 0.85,
-    r"(?i)(?:ssh|remote)\s+(?:vào|đến|tới)\s+(?:server|máy chủ)": 0.90,
-    r"(?i)kiểm tra\s+(?:network|mạng|firewall|tường lửa)": 0.85,
-    r"(?i)(?:load balancer|cdn|dns)\s+(?:configuration|cấu hình)": 0.85,
-    # Requirement-style patterns (Vietnamese declarative)
-    r"(?i)(?:có\s+)?api\s+gateway\s+(?:để\s+)?(?:quản lý|manage)": 0.90,
-    r"(?i)(?:có\s+)?(?:dashboard|grafana|prometheus)\s+(?:mẫu|theo dõi|hiển thị|monitoring)": 0.90,
-    r"(?i)(?:cấu hình|có)\s+(?:readiness|liveness)\s+probe": 0.90,
-    r"(?i)(?:cấu hình|có)\s+(?:ha|high.?availability)\s+(?:trong\s+)?(?:k8s|kubernetes)": 0.90,
-    r"(?i)(?:xác định|có|cấu hình)\s+(?:rõ\s+)?(?:ngưỡng\s+)?(?:cpu[/\s]*ram|cpu|ram)\s+(?:tối thiểu|request|limit)": 0.90,
-    r"(?i)(?:đóng gói|có)\s+(?:trọn bộ\s+)?(?:image[/\s]*lib|image|lib)\s+(?:để\s+)?(?:cài đặt|offline|không cần\s+internet)": 0.90,
-    r"(?i)script\s+load\s+docker\s+image\s+(?:từ|from)\s+(?:file\s+)?\.tar": 0.90,
-    r"(?i)(?:cấu hình|có)\s+(?:sẵn\s+)?(?:các\s+)?(?:quy tắc\s+)?(?:cảnh báo|alerting)\s*(?:rules?)?": 0.90,
-    r"(?i)(?:đã\s+)?(?:được\s+)?hỗ trợ\s+(?:bởi\s+)?hạ tầng.*không cần\s+kiểm tra": 0.90,
-    r"(?i)(?:quản lý|có|thu thập)\s+logs?\s+(?:tập trung|centralized)": 0.90,
-    r"(?i)(?:hệ thống|có)\s+(?:tập trung\s+)?(?:logs?|elk|graylog)": 0.90,
-    r"(?i)(?:đã\s+)?(?:được\s+)?quét\s+(?:lỗ hổng\s+)?(?:bảo mật|sast|dast)": 0.90,
-    r"(?i)stateless\s+service": 0.90,
-    r"(?i)(?:có\s+)?dockerfile\s+(?:chuẩn|multi.?stage)": 0.85,
-    r"(?i)(?:có\s+)?(?:docker.?compose|helm\s+charts?)": 0.85,
-    r"(?i)(?:triển khai|deploy)\s+(?:trên|via)\s+(?:k8s|kubernetes|helm)": 0.85,
-    # Note: /health and /metrics endpoints are CODE-verifiable, not infra - do NOT add patterns for them
-    # Only skip infra-level health check CONFIGURATION (like k8s probes, monitoring setup)
-    r"(?i)(?:cấu hình|setup|configure)\s+(?:health\s*check|monitoring)\s+(?:trong|in)\s+(?:k8s|kubernetes)": 0.85,
-    r"(?i)(?:resource\s+)?(?:consumption|usage)\s+(?:dashboard|monitoring)": 0.85,
-    # English keyword patterns for common infrastructure terms
-    r"(?i)\b(?:grafana|prometheus|datadog|newrelic|splunk)\b": 0.80,
-    r"(?i)\b(?:kubernetes|k8s|helm|docker.?compose)\b": 0.80,
-    r"(?i)\b(?:sast|dast|sonarqube|checkmarx)\b": 0.80,
-    r"(?i)\b(?:air.?gap|offline)\s+(?:install|deployment|bundle)\b": 0.85,
-}
-
-# Skip-manual patterns: instructions requiring human judgment/interview
-# Includes both instruction-style (imperative verbs) and requirement-style (declarative) patterns
-SKIP_MANUAL_PATTERNS: dict[str, float] = {
-    # Instruction-style patterns (original)
-    r"(?i)phỏng vấn\s+(?:đội|nhóm|team)": 0.90,
-    r"(?i)(?:hỏi|trao đổi với)\s+(?:đội|nhóm|team|dev|developer)": 0.85,
-    r"(?i)kiểm tra\s+(?:thủ công|bằng tay)": 0.90,
-    r"(?i)xác minh\s+(?:thủ công|bằng tay)": 0.90,
-    r"(?i)(?:đánh giá|review)\s+(?:thủ công|bằng tay)": 0.85,
-    r"(?i)(?:quan sát|theo dõi)\s+(?:quy trình|process)": 0.80,
-    r"(?i)(?:báo cáo|report)\s+(?:kiểm thử xâm nhập|penetration test)": 0.85,
-    r"(?i)(?:chứng chỉ|certificate|giấy phép|license)\s+(?:còn hạn|hết hạn|validity)": 0.80,
-    # Requirement-style patterns (Vietnamese declarative - documentation artifacts)
-    r"(?i)(?:có\s+)?sequence\s+diagram": 0.90,
-    r"(?i)(?:có\s+)?sơ đồ\s+(?:kiến trúc|luồng dữ liệu|hạ tầng|architecture)": 0.90,
-    r"(?i)(?:có\s+)?danh mục\s+(?:đầy đủ\s+)?(?:error\s*codes?|mã lỗi)": 0.90,
-    r"(?i)(?:có\s+)?tài liệu\s+(?:sizing|test tải|performance)": 0.90,
-    r"(?i)doc\s*versioning": 0.90,
-    r"(?i)(?:có\s+)?(?:bộ\s+)?postman\s+collection": 0.90,
-    r"(?i)(?:có\s+)?hướng dẫn\s+(?:sandbox|simulation|môi trường thử nghiệm)": 0.90,
-    r"(?i)(?:tài liệu|có)\s+(?:hdsd|hướng dẫn sử dụng)\s+(?:có\s+)?(?:ảnh chụp|screenshot)": 0.90,
-    r"(?i)(?:có\s+)?(?:hướng dẫn|troubleshooting)\s+(?:xử lý|guide)\s+(?:các\s+)?(?:lỗi|sự cố)": 0.90,
-    r"(?i)(?:tài liệu|có)\s+(?:quản lý\s+)?phiên bản\s+(?:wiki|gitbook|confluence)": 0.90,
-    r"(?i)(?:có\s+)?tài liệu\s+cam kết\s+(?:thời gian|mttr|sla)": 0.90,
-    r"(?i)(?:có\s+)?(?:quy trình\s+)?đóng gói\s+(?:log|data\s*dump)": 0.90,
-    # English keyword patterns for documentation artifacts
-    r"(?i)\b(?:sequence|architecture|data.?flow)\s+diagram\b": 0.90,
-    r"(?i)\b(?:error.?code|mã lỗi)\s*(?:catalog|list|danh mục)\b": 0.90,
-    r"(?i)\b(?:postman|swagger|openapi)\s*(?:collection|spec)\b": 0.85,
-    r"(?i)\b(?:sandbox|simulation)\s*(?:guide|hướng dẫn)\b": 0.90,
-    r"(?i)\b(?:troubleshooting|user\s*manual|hướng dẫn)\s*(?:guide|doc)\b": 0.85,
-    r"(?i)\bmttr\b.*(?:commitment|cam kết|sla)": 0.90,
-}
-
-# Pass-criteria patterns: Vietnamese instructions describing what constitutes a pass
-PASS_CRITERIA_PATTERNS: dict[str, float] = {
-    r"(?i)(?:đạt|pass)\s+(?:nếu|khi|when)\s+(.+)": 0.85,
-    r"(?i)(?:yêu cầu|requirement)\s*:\s*(.+)": 0.80,
-    r"(?i)(?:phải|must|cần)\s+(?:có|tồn tại|exist)\s+(.+)": 0.85,
-    r"(?i)(?:phải|must|cần)\s+(?:sử dụng|dùng|use)\s+(.+)": 0.85,
-    r"(?i)(?:phải|must|cần)\s+(?:tuân thủ|comply|follow)\s+(.+)": 0.85,
-    r"(?i)(?:không được|must not|không)\s+(?:có|chứa|contain)\s+(.+)": 0.85,
-}
-
-# Fail-criteria patterns: Vietnamese instructions describing what constitutes a fail
-FAIL_CRITERIA_PATTERNS: dict[str, float] = {
-    r"(?i)(?:không đạt|fail)\s+(?:nếu|khi|when)\s+(.+)": 0.85,
-    r"(?i)(?:vi phạm|violation)\s+(?:nếu|khi|when)\s+(.+)": 0.85,
-    r"(?i)(?:cảnh báo|warning)\s+(?:nếu|khi|when)\s+(.+)": 0.80,
-    r"(?i)(?:không được phép|forbidden|cấm)\s+(.+)": 0.85,
-    r"(?i)(?:thiếu|missing|không có)\s+(.+?)\s+(?:là|sẽ)\s+(?:lỗi|fail)": 0.85,
-}
-
-# Code pattern search markers
-CODE_PATTERN_MARKERS: dict[str, tuple[str, float]] = {
-    r"(?i)tìm\s+(?:pattern|mẫu)\s+(.+?)(?:\s+trong|\s*$)": ("search_code_pattern", 0.85),
-    r"(?i)(?:grep|search|tìm kiếm)\s+(.+?)\s+(?:trong|in)\s+(?:code|mã nguồn)": ("search_code_pattern", 0.85),
-    r"(?i)kiểm tra\s+(?:xem\s+)?(?:có\s+)?(?:sử dụng|dùng|import)\s+(.+)": ("search_code_pattern", 0.80),
-    r"(?i)(?:annotation|decorator|@\w+)": ("search_code_pattern", 0.80),
-}
-
-# Verify-absence markers
-VERIFY_ABSENCE_MARKERS: dict[str, tuple[str, float]] = {
-    r"(?i)(?:không được|must not|không)\s+(?:có|chứa|contain|sử dụng|dùng)\s+(.+)": ("verify_absence", 0.85),
-    r"(?i)(?:đảm bảo|ensure)\s+(?:không|no)\s+(.+)": ("verify_absence", 0.85),
-    r"(?i)(?:xác nhận|verify)\s+(?:không còn|no longer|đã xóa|removed)\s+(.+)": ("verify_absence", 0.85),
-}
-
-# API check markers
-API_CHECK_MARKERS: dict[str, tuple[str, float]] = {
-    r"(?i)kiểm tra\s+(?:api|endpoint)\s+(.+?)(?:\s+có|\s*$)": ("check_api", 0.85),
-    r"(?i)(?:api|endpoint)\s+(.+?)\s+(?:phải|must|cần)\s+(.+)": ("check_api", 0.80),
-    r"(?i)(?:rest|graphql|grpc)\s+(?:api|endpoint|service)": ("check_api", 0.80),
-}
-
-_HEURISTIC_CONFIDENCE_THRESHOLD = 0.70
-
-
-def _extract_file_target(text: str) -> str:
-    """Extract a file/config target from instruction text."""
-    # Look for quoted strings first
-    quoted = re.findall(r'["\']([^"\']+)["\']', text)
-    if quoted:
-        return quoted[0]
-    # Look for file-like patterns
-    file_patterns = re.findall(
-        r"(?:[\w\-]+\.(?:yml|yaml|xml|json|toml|properties|conf|env|java|py|ts|js|go|rs|dockerfile))",
-        text,
-        re.IGNORECASE,
-    )
-    if file_patterns:
-        return file_patterns[0]
-    # Look for path-like patterns
-    path_patterns = re.findall(r"(?:[\w\-/]+/[\w\-]+(?:\.\w+)?)", text)
-    if path_patterns:
-        return path_patterns[0]
-    # Fallback: extract the most relevant noun phrase
-    return text.strip()[:100]
-
-
-def _layer1_heuristic_parse(
-    instruction_text: str,
-    requirement_key: str = "",
-) -> InstructionPlan | None:
-    """Layer 1: Deterministic Vietnamese pattern matching (DD-122.10).
-
-    Returns InstructionPlan if patterns match with sufficient confidence,
-    None if the instruction is ambiguous and needs Layer 2.
-    """
-    if not instruction_text or not instruction_text.strip():
-        return None
-
-    text = instruction_text.strip()
-    directives: list[InstructionDirective] = []
-    pass_criteria: list[ScoringCriterion] = []
-    fail_criteria: list[ScoringCriterion] = []
-    max_confidence = 0.0
-    skip_decision: str | None = None
-    skip_reason: str | None = None
-
-    # --- Check skip-infra patterns ---
-    for pattern, confidence in SKIP_INFRA_PATTERNS.items():
-        if re.search(pattern, text):
-            skip_decision = "infra_provided"
-            skip_reason = f"Instruction requires infrastructure-level verification: {text[:200]}"
-            directives.append(
-                InstructionDirective(
-                    directive_type="skip_infra",
-                    target=text[:200],
-                    target_scope="current_repo",
-                    rationale="Infrastructure verification detected by heuristic",
-                )
-            )
-            max_confidence = max(max_confidence, confidence)
-            logger.debug(
-                "instruction_heuristic_skip_infra",
-                pattern=pattern,
-                confidence=confidence,
-            )
-            break
-
-    # --- Check skip-manual patterns ---
-    if not skip_decision:
-        for pattern, confidence in SKIP_MANUAL_PATTERNS.items():
-            if re.search(pattern, text):
-                skip_decision = "manual_required"
-                skip_reason = f"Instruction requires manual verification: {text[:200]}"
-                directives.append(
-                    InstructionDirective(
-                        directive_type="skip_manual",
-                        target=text[:200],
-                        target_scope="current_repo",
-                        rationale="Manual verification detected by heuristic",
-                    )
-                )
-                max_confidence = max(max_confidence, confidence)
-                logger.debug(
-                    "instruction_heuristic_skip_manual",
-                    pattern=pattern,
-                    confidence=confidence,
-                )
-                break
-
-    # --- Extract search-file/config directives ---
-    if not skip_decision:
-        for pattern, (dtype, confidence) in SEARCH_FILE_PATTERNS.items():
-            match = re.search(pattern, text)
-            if match:
-                target = match.group(1) if match.lastindex and match.lastindex >= 1 else _extract_file_target(text)
-                scope = "config_repo" if dtype == "search_config" else "current_repo"
-                directives.append(
-                    InstructionDirective(
-                        directive_type=dtype,
-                        target=target.strip(),
-                        target_scope=scope,
-                        rationale=f"File/config target extracted from: {text[:100]}",
-                    )
-                )
-                max_confidence = max(max_confidence, confidence)
-
-        # --- Extract code-pattern directives ---
-        for pattern, (dtype, confidence) in CODE_PATTERN_MARKERS.items():
-            match = re.search(pattern, text)
-            if match:
-                target = match.group(1) if match.lastindex and match.lastindex >= 1 else text[:100]
-                directives.append(
-                    InstructionDirective(
-                        directive_type=dtype,
-                        target=target.strip(),
-                        target_scope="current_repo",
-                        rationale=f"Code pattern extracted from: {text[:100]}",
-                    )
-                )
-                max_confidence = max(max_confidence, confidence)
-
-        # --- Extract verify-absence directives ---
-        for pattern, (dtype, confidence) in VERIFY_ABSENCE_MARKERS.items():
-            match = re.search(pattern, text)
-            if match:
-                target = match.group(1) if match.lastindex and match.lastindex >= 1 else text[:100]
-                directives.append(
-                    InstructionDirective(
-                        directive_type=dtype,
-                        target=target.strip(),
-                        target_scope="current_repo",
-                        rationale=f"Absence verification extracted from: {text[:100]}",
-                    )
-                )
-                max_confidence = max(max_confidence, confidence)
-
-        # --- Extract API check directives ---
-        for pattern, (dtype, confidence) in API_CHECK_MARKERS.items():
-            match = re.search(pattern, text)
-            if match:
-                target = match.group(1) if match.lastindex and match.lastindex >= 1 else text[:100]
-                directives.append(
-                    InstructionDirective(
-                        directive_type=dtype,
-                        target=target.strip(),
-                        target_scope="current_repo",
-                        rationale=f"API check extracted from: {text[:100]}",
-                    )
-                )
-                max_confidence = max(max_confidence, confidence)
-
-    # --- Extract pass criteria ---
-    for pattern, confidence in PASS_CRITERIA_PATTERNS.items():
-        match = re.search(pattern, text)
-        if match:
-            criterion_text = match.group(1) if match.lastindex and match.lastindex >= 1 else text[:100]
-            pass_criteria.append(
-                ScoringCriterion(
-                    criterion=criterion_text.strip(),
-                    verdict_if_met="PASS",
-                    weight=1.0,
-                    source_instruction=text[:200],
-                )
-            )
-            max_confidence = max(max_confidence, confidence)
-
-    # --- Extract fail criteria ---
-    for pattern, confidence in FAIL_CRITERIA_PATTERNS.items():
-        match = re.search(pattern, text)
-        if match:
-            criterion_text = match.group(1) if match.lastindex and match.lastindex >= 1 else text[:100]
-            fail_criteria.append(
-                ScoringCriterion(
-                    criterion=criterion_text.strip(),
-                    verdict_if_met="FAIL",
-                    weight=1.0,
-                    source_instruction=text[:200],
-                )
-            )
-            max_confidence = max(max_confidence, confidence)
-
-    # --- Decide if we have enough signal ---
-    if max_confidence < _HEURISTIC_CONFIDENCE_THRESHOLD:
-        return None  # Not enough signal, escalate to Layer 2
-
-    if not directives and not pass_criteria and not fail_criteria:
-        return None  # No actionable content extracted
-
-    plan_id = f"heur-{uuid.uuid4().hex[:12]}"
-
-    plan = InstructionPlan(
-        plan_id=plan_id,
-        requirement_key=requirement_key,
-        directives=tuple(directives),
-        pass_criteria=tuple(pass_criteria),
-        fail_criteria=tuple(fail_criteria),
-        skip_decision=skip_decision,
-        skip_reason=skip_reason,
-        confidence=max_confidence,
-        analysis_source="heuristic",
-        raw_instruction=text,
-    )
-
-    logger.debug(
-        "instruction_heuristic_plan",
-        plan_id=plan_id,
-        requirement_key=requirement_key,
-        directive_count=len(directives),
-        pass_criteria_count=len(pass_criteria),
-        fail_criteria_count=len(fail_criteria),
-        skip_decision=skip_decision,
-        confidence=max_confidence,
-    )
-
-    return plan
-
-
-# ---------------------------------------------------------------------------
-# Layer 2: LLM decomposition agent (TSK-122.22, DD-122.14)
-# ---------------------------------------------------------------------------
-
-
-def _instruction_text_hash(text: str) -> str:
-    """Compute stable hash for instruction text caching."""
-    normalized = text.strip().lower()
-    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
-
-
-def _layer2_llm_decompose(
-    instruction_text: str,
-    requirement_key: str = "",
-    repo_type: str = "",
-    tech_stack_summary: str = "",
-) -> InstructionPlan | None:
-    """Layer 2: bounded fallback decomposition with knowledge-store caching.
-
-    Current rollout-safe behavior:
-    - read/write cache from Phase 118 knowledge store when runtime config is available,
-    - synthesize a conservative plan from deterministic file/pattern cues,
-    - return None when no additional actionable structure can be derived.
-    """
-    instruction_hash = _instruction_text_hash(instruction_text)
-    runtime_project_key = str(os.environ.get("VDS_AUDIT_PROJECT_KEY") or "").strip()
-    runtime_state_dsn = str(os.environ.get("VDS_AUDIT_STATE_DSN") or "").strip()
-    runtime_run_id = str(os.environ.get("VDS_AUDIT_RUN_ID") or "phase122").strip() or "phase122"
-
-    store: ProjectKnowledgeStore | None = None
-    cached_payload: dict[str, Any] | None = None
-    if runtime_project_key and runtime_state_dsn:
-        try:
-            store = ProjectKnowledgeStore(dsn=runtime_state_dsn)
-            cached_payload = store.get_instruction_plan(
-                project_key=runtime_project_key,
-                requirement_key=requirement_key,
-                instruction_text_hash=instruction_hash,
-            )
-        except Exception:
-            logger.debug("instruction_llm_cache_unavailable", requirement_key=requirement_key)
-            store = None
-
-    if cached_payload:
-        try:
-            content = json.loads(str(cached_payload.get("content") or "{}"))
-            plan = InstructionPlan(
-                plan_id=str(content.get("plan_id") or f"cache-{instruction_hash[:12]}"),
-                requirement_key=requirement_key,
-                directives=tuple(InstructionDirective(**item) for item in (content.get("directives") or [])),
-                pass_criteria=tuple(ScoringCriterion(**item) for item in (content.get("pass_criteria") or [])),
-                fail_criteria=tuple(ScoringCriterion(**item) for item in (content.get("fail_criteria") or [])),
-                skip_decision=content.get("skip_decision"),
-                skip_reason=content.get("skip_reason"),
-                confidence=float(content.get("confidence") or cached_payload.get("confidence") or 0.0),
-                analysis_source=str(content.get("analysis_source") or "llm_cache"),
-                raw_instruction=str(content.get("raw_instruction") or instruction_text),
-            )
-            return plan
-        except Exception:
-            logger.warning("instruction_llm_cache_decode_failed", requirement_key=requirement_key)
-
-    text_lower = instruction_text.lower()
-    directives: list[InstructionDirective] = []
-    pass_criteria: list[ScoringCriterion] = []
-    fail_criteria: list[ScoringCriterion] = []
-
-    file_candidates = re.findall(
-        r"(?:[\w./*-]+\.(?:yml|yaml|properties|json|xml|toml|env|conf|ini|java|kt|py|ts|js|go|sql)|dockerfile|docker-compose(?:\.ya?ml)?)",
-        instruction_text,
-        re.IGNORECASE,
-    )
-    for candidate in file_candidates[:3]:
-        target_scope = (
-            "config_repo"
-            if any(ext in candidate.lower() for ext in (".yml", ".yaml", ".properties", ".env", ".conf", ".ini"))
-            else "current_repo"
-        )
-        directives.append(
-            InstructionDirective(
-                directive_type="search_config" if target_scope == "config_repo" else "search_file",
-                target=str(candidate).strip(),
-                target_scope=target_scope,
-                rationale=f"layer2_fallback(repo_type={repo_type or 'unknown'}, tech_stack={tech_stack_summary[:60]})",
-            )
-        )
-
-    if "không" in text_lower or "must not" in text_lower or "forbidden" in text_lower:
-        negative_target = instruction_text.strip()[:120]
-        directives.append(
-            InstructionDirective(
-                directive_type="verify_absence",
-                target=negative_target,
-                target_scope="current_repo",
-                rationale="layer2 absence inference",
-            )
-        )
-        fail_criteria.append(
-            ScoringCriterion(
-                criterion=negative_target,
-                verdict_if_met="FAIL",
-                weight=0.8,
-                source_instruction=instruction_text[:200],
-            )
-        )
-    else:
-        summary_target = instruction_text.strip()[:120]
-        if summary_target:
-            pass_criteria.append(
-                ScoringCriterion(
-                    criterion=summary_target,
-                    verdict_if_met="PASS",
-                    weight=0.7,
-                    source_instruction=instruction_text[:200],
-                )
-            )
-
-    if not directives and not pass_criteria and not fail_criteria:
-        return None
-
-    plan = InstructionPlan(
-        plan_id=f"llm-{instruction_hash[:12]}",
-        requirement_key=requirement_key,
-        directives=tuple(directives),
-        pass_criteria=tuple(pass_criteria),
-        fail_criteria=tuple(fail_criteria),
-        confidence=0.6,
-        analysis_source="llm_fallback",
-        raw_instruction=instruction_text.strip(),
-    )
-
-    if store is not None and runtime_project_key:
-        try:
-            store.put_instruction_plan(
-                project_key=runtime_project_key,
-                requirement_key=requirement_key,
-                instruction_text_hash=instruction_hash,
-                content=json.dumps(plan.to_dict(), ensure_ascii=False),
-                confidence=plan.confidence,
-                source_run_id=runtime_run_id,
-            )
-        except Exception:
-            logger.debug("instruction_llm_cache_store_failed", requirement_key=requirement_key)
-
-    return plan
-
-
-# ---------------------------------------------------------------------------
-# Orchestrator: analyze_instruction() (TSK-122.23, AC-122.5.1)
-# ---------------------------------------------------------------------------
-
-_INSTRUCTION_ANALYSIS_ENV = "VDS_AUDIT_INSTRUCTION_ANALYSIS_ENABLED"
-
-
-def _is_instruction_analysis_enabled() -> bool:
-    """Check if instruction analysis is enabled (AC-122.5.10).
-
-    ``features.instruction_analysis_enabled`` is the authoritative default-on
-    control. The legacy top-level env var remains accepted as a compatibility
-    override for older automation.
-    """
-    raw = os.environ.get(_INSTRUCTION_ANALYSIS_ENV)
-    if raw is not None:
-        return raw.strip().lower() in {"1", "true", "yes", "on"}
-
-    try:
-        return bool(get_config().features.instruction_analysis_enabled)
-    except Exception:
-        return True
-
-
-def _validate_plan(plan: InstructionPlan) -> InstructionPlan:
-    """Validate and sanitize an InstructionPlan (AC-122.5.6).
-
-    Drops invalid directives with warning, retains valid ones.
-    Returns sanitized plan or empty plan if nothing valid remains.
-    """
-    valid_directives: list[InstructionDirective] = []
-    dropped = 0
-
-    for d in plan.directives:
-        if d.is_valid():
-            valid_directives.append(d)
-        else:
-            dropped += 1
-            logger.warning(
-                "instruction_directive_dropped",
-                directive_type=d.directive_type,
-                target=d.target,
-                target_scope=d.target_scope,
-                reason="invalid_directive",
-            )
-
-    valid_pass = tuple(c for c in plan.pass_criteria if c.is_valid())
-    valid_fail = tuple(c for c in plan.fail_criteria if c.is_valid())
-
-    dropped_criteria = len(plan.pass_criteria) - len(valid_pass) + len(plan.fail_criteria) - len(valid_fail)
-    if dropped_criteria > 0:
-        logger.warning(
-            "instruction_criteria_dropped",
-            dropped_count=dropped_criteria,
-        )
-
-    if dropped > 0:
-        logger.info(
-            "instruction_plan_sanitized",
-            original_directives=len(plan.directives),
-            valid_directives=len(valid_directives),
-            dropped=dropped,
-        )
-
-    return InstructionPlan(
-        plan_id=plan.plan_id,
-        requirement_key=plan.requirement_key,
-        directives=tuple(valid_directives),
-        pass_criteria=valid_pass,
-        fail_criteria=valid_fail,
-        skip_decision=plan.skip_decision,
-        skip_reason=plan.skip_reason,
-        confidence=plan.confidence,
-        analysis_source=plan.analysis_source,
-        raw_instruction=plan.raw_instruction,
-    )
-
-
-def analyze_instruction(
-    instruction_text: str,
-    requirement_key: str = "",
-    repo_type: str = "",
-    tech_stack_summary: str = "",
-) -> InstructionPlan | None:
-    """Two-layer instruction analysis orchestrator (AC-122.5.1).
-
-    Layer 1: Vietnamese heuristic pattern matching (fast, deterministic)
-    Layer 2: LLM decomposition (slow, for ambiguous instructions)
-
-    Returns InstructionPlan or None if analysis is disabled or produces no result.
-    """
-    if not _is_instruction_analysis_enabled():
-        logger.debug("instruction_analysis_disabled")
-        return None
-
-    if not instruction_text or not instruction_text.strip():
-        return None
-
-    # Layer 1: Heuristic
-    plan = _layer1_heuristic_parse(instruction_text, requirement_key)
-    if plan is not None:
-        validated = _validate_plan(plan)
-        if validated.has_directives or validated.has_scoring_criteria or validated.should_skip:
-            logger.info(
-                "instruction_analysis_layer1_success",
-                requirement_key=requirement_key,
-                directive_count=len(validated.directives),
-                confidence=validated.confidence,
-                skip_decision=validated.skip_decision,
-            )
-            return validated
-
-    # Layer 2: LLM decomposition (AC-122.5.11)
-    plan = _layer2_llm_decompose(
-        instruction_text,
-        requirement_key=requirement_key,
-        repo_type=repo_type,
-        tech_stack_summary=tech_stack_summary,
-    )
-    if plan is not None:
-        validated = _validate_plan(plan)
-        if validated.has_directives or validated.has_scoring_criteria or validated.should_skip:
-            # Check confidence threshold (AC-122.5.11)
-            if validated.confidence < 0.6:
-                logger.warning(
-                    "instruction_analysis_layer2_low_confidence",
-                    requirement_key=requirement_key,
-                    confidence=validated.confidence,
-                )
-                return None  # Fallback to heuristic behavior
-            logger.info(
-                "instruction_analysis_layer2_success",
-                requirement_key=requirement_key,
-                directive_count=len(validated.directives),
-                confidence=validated.confidence,
-            )
-            return validated
-
-    logger.debug(
-        "instruction_analysis_no_result",
-        requirement_key=requirement_key,
-    )
-    return None
-
-
-# ---------------------------------------------------------------------------
-# P167-D: Shared instruction text builder (TSK-167.10)
-# ---------------------------------------------------------------------------
-
-
-def _build_instruction_analysis_text(row: dict[str, Any]) -> str:
-    """Build canonical instruction text for analysis from a normalized checklist row.
-
-    This is the single source of truth for instruction text assembly, shared between:
-    - Pre-dispatch filtering in ``workflow_cmds._resolve_repo_row_keys_for_sharding``
-      (P167-D parent context)
-    - Per-row evaluation in ``row_evaluator`` (Phase 122 child context)
-
-    Both must produce identical text from the same inputs to guarantee that
-    rows excluded by pre-dispatch analysis are exactly those the evaluator would
-    classify as skip_infra or skip_manual.
-
-    The logic mirrors ``extract_requirement_guidance`` (row_evaluator_types) plus
-    description concatenation, inlined here to avoid a circular import between
-    ``instruction_analyzer`` and ``row_evaluator_types``.
-
-    Args:
-        row: Normalized row dict with ``check_config`` (dict) and ``description``
-             (str) keys. Both fields are optional — missing or None values are
-             treated as empty.
-    """
-    check_config = dict(row.get("check_config") or {})
-
-    parts: list[str] = []
-    main = str(check_config.get("confluence_main") or "").strip()
-    if main:
-        parts.append(f"Nội dung chính: {main}")
-    rule = str(check_config.get("confluence_rule") or "").strip()
-    if rule:
-        parts.append(f"Quy tắc: {rule}")
-    guidance = str(check_config.get("detailed_guidance") or check_config.get("confluence_notes") or "").strip()
-    if guidance:
-        parts.append(f"Hướng dẫn chi tiết: {guidance}")
-    check_manual = str(check_config.get("check_manual") or "").strip()
-    if check_manual:
-        parts.append(f"Check = Manual: {check_manual}")
-    evidence_hint = str(check_config.get("confluence_evidence_hint") or "").strip()
-    if evidence_hint:
-        parts.append(f"Minh chứng kỳ vọng: {evidence_hint}")
-
-    guidance_text = "\n".join(parts)
-    description = str(row.get("description") or "").strip()
-
-    if guidance_text and description:
-        return f"{guidance_text}\n{description}"
-    return guidance_text or description
-
-
-# ---------------------------------------------------------------------------
-# Exports
-# ---------------------------------------------------------------------------
-
-__all__ = [
-    "API_CHECK_MARKERS",
-    "CODE_PATTERN_MARKERS",
-    "FAIL_CRITERIA_PATTERNS",
-    "PASS_CRITERIA_PATTERNS",
-    "SEARCH_FILE_PATTERNS",
-    "SKIP_INFRA_PATTERNS",
-    "SKIP_MANUAL_PATTERNS",
-    "VALID_DIRECTIVE_TYPES",
-    "VALID_TARGET_SCOPES",
-    "VALID_VERDICTS",
-    "VERIFY_ABSENCE_MARKERS",
-    "ComplianceResult",
-    "InstructionDirective",
-    "InstructionPlan",
-    "ScoringCriterion",
-    "_build_instruction_analysis_text",
-    "_instruction_text_hash",
-    "_is_instruction_analysis_enabled",
-    "_layer1_heuristic_parse",
-    "_layer2_llm_decompose",
-    "_validate_plan",
-    "analyze_instruction",
-]