@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/llm/prompts/instruction_templates.py

@@ -1,634 +0,0 @@
-"""Instruction templates for agentic evaluation (TSK-610.7).
-
-Provides minimal, tool-aware prompt templates that instruct the agent to
-discover evidence through tools and skills rather than receiving everything
-inline.  This shifts from "fat prompts with all details" to "lean prompts
-with tool instructions," reducing token cost and improving grounding.
-
-Design principles:
-- Prompts tell the agent WHAT tools exist and WHEN to use them.
-- Prompts NEVER embed full evidence inline when tools can retrieve it.
-- Prompts MUST NOT override runtime tool permissions or grounding gates.
-- Skill instructions MUST NOT let the agent invent skill/resource/script
-  identifiers — only declared names are valid.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass, field
-from enum import StrEnum
-from typing import Any
-
-from structlog import get_logger
-from vds_agent_core.config import AgentRuntimeMode
-
-logger = get_logger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Enums
-# ---------------------------------------------------------------------------
-
-
-class InstructionMode(StrEnum):
-    """How much tool guidance to inject into the system prompt."""
-
-    NONE = "none"
-    """No tool instructions — classic inline-evidence prompt."""
-
-    MINIMAL = "minimal"
-    """Lean instruction block listing available tools/skills."""
-
-    FULL = "full"
-    """Detailed per-tool usage guidance with examples."""
-
-
-class EvidenceStrategy(StrEnum):
-    """How evidence is surfaced to the evaluator."""
-
-    INLINE = "inline"
-    """All evidence embedded in the user prompt (legacy)."""
-
-    TOOL_FIRST = "tool_first"
-    """Agent discovers evidence via tools; inline is fallback."""
-
-    TOOL_ONLY = "tool_only"
-    """Agent MUST use tools; no inline evidence provided."""
-
-
-# ---------------------------------------------------------------------------
-# Tool / Skill descriptors (kept intentionally small)
-# ---------------------------------------------------------------------------
-
-_TOOL_CATALOG: dict[str, str] = {
-    "search_docs": "Search Confluence/documentation corpus by semantic query. Returns ranked hits with snippets.",
-    "search_code": "Search repository code by pattern or keyword. Returns file paths and matching lines.",
-    "read_doc_chunk": "Retrieve full content of a specific document chunk by ID.",
-    "read_code_file": "Read a specific file from the repository.",
-    "get_row_context": "Get contextual metadata for the current checklist row.",
-    "record_evidence_refs": (
-        "Record discovered evidence references for traceability. "
-        "Confluence citations MUST include ref_type='confluence_page', page_id, "
-        "and canonical source_uri (source_url alias accepted)."
-    ),
-}
-
-_TOOL_USAGE_HINTS: dict[str, str] = {
-    "search_docs": 'Use when the requirement references documentation, architecture, or process artifacts. Example: search_docs(query="API versioning policy", limit=3)',
-    "search_code": 'Use when the requirement references code, configuration, or implementation. Example: search_code(query="health check endpoint", limit=5)',
-    "read_doc_chunk": "Use after search_docs returns a relevant hit — read the full chunk for detailed evidence.",
-    "read_code_file": "Use after search_code returns a relevant hit — read the full file for detailed evidence.",
-    "get_row_context": "Use at the start to understand the evaluation context, seed evidence refs, and runtime identifiers.",
-    "record_evidence_refs": (
-        "Use to persist discovered evidence references for downstream traceability. "
-        "For Confluence refs: ref_type='confluence_page', include page_id + canonical source_uri "
-        "(source_url alias accepted)."
-    ),
-}
-
-# ---------------------------------------------------------------------------
-# Category-to-tool-bias mapping (FR-201, TSK-890.28)
-# ---------------------------------------------------------------------------
-
-CATEGORY_TOOL_BIAS: dict[str, str] = {
-    # docs_primary: categories where documentation evidence is the primary signal
-    "documentation_quality": "docs_primary",
-    "api_docs_quality": "docs_primary",
-    "readme_quality": "docs_primary",
-    "security_docs_quality": "docs_primary",
-    "compliance_narrative": "docs_primary",
-    "architecture_alignment": "docs_primary",
-    "requirement_coverage": "docs_primary",
-    # code_primary: categories where code/config evidence is the primary signal
-    "code_documentation": "code_primary",
-    "test_coverage_quality": "code_primary",
-    "ci_pipeline_exists": "code_primary",
-    "dockerfile_exists": "code_primary",
-    "ci_config_valid": "code_primary",
-    "openapi_valid": "code_primary",
-}
-
-
-def _tool_bias_for_category(category: str) -> str:
-    """Return tool bias for a category: docs_primary, code_primary, or balanced."""
-    normalized = str(category or "").strip().lower()
-    return CATEGORY_TOOL_BIAS.get(normalized, "balanced")
-
-
-@dataclass(frozen=True, slots=True)
-class SkillDescriptor:
-    """Minimal metadata for a skill injected into agent instructions."""
-
-    name: str
-    description: str
-    trust_tier: str = "internal"
-
-
-# ---------------------------------------------------------------------------
-# Template builder
-# ---------------------------------------------------------------------------
-
-
-@dataclass(slots=True)
-class InstructionTemplateConfig:
-    """Controls what gets injected into the agent prompt."""
-
-    mode: InstructionMode = InstructionMode.MINIMAL
-    evidence_strategy: EvidenceStrategy = EvidenceStrategy.TOOL_FIRST
-    available_tools: list[str] = field(default_factory=list)
-    available_skills: list[SkillDescriptor] = field(default_factory=list)
-    max_inline_evidence_chars: int = 2000
-    language: str = "vi"
-    runtime_mode: AgentRuntimeMode = AgentRuntimeMode.PYDANTICAI
-    skills_toolset_enabled: bool = False
-
-
-def build_tool_instructions(config: InstructionTemplateConfig) -> str:
-    """Build the tool/skill instruction block for system prompts.
-
-    Returns an empty string when ``config.mode`` is ``NONE``.
-    """
-    if config.mode == InstructionMode.NONE:
-        return ""
-
-    parts: list[str] = []
-
-    # --- Evidence strategy preamble ---
-    tools = config.available_tools or list(_TOOL_CATALOG)
-    parts.append(_evidence_strategy_preamble(config.evidence_strategy, tools))
-
-    # --- Tool catalog ---
-    tool_lines = _build_tool_section(tools, detailed=config.mode == InstructionMode.FULL)
-    if tool_lines:
-        parts.append(tool_lines)
-
-    # --- Skill catalog ---
-    if config.available_skills:
-        parts.append(_build_skill_section(config.available_skills))
-
-    # --- Runtime-specific directives ---
-    runtime_directives = _runtime_directives(
-        config.runtime_mode,
-        config.language,
-        skills_toolset_enabled=config.skills_toolset_enabled,
-    )
-    if runtime_directives:
-        parts.append(runtime_directives)
-
-    # --- Grounding rules ---
-    parts.append(_grounding_rules(config.language))
-
-    return "\n\n".join(parts)
-
-
-def build_agentic_system_prompt(
-    *,
-    base_system: str,
-    config: InstructionTemplateConfig,
-) -> str:
-    """Compose a full system prompt by appending tool instructions to base.
-
-    Args:
-        base_system: The core evaluation system prompt (e.g.
-            ``ROW_EVALUATION_SYSTEM``).
-        config: Instruction template configuration.
-
-    Returns:
-        Combined system prompt.  When ``config.mode`` is ``NONE`` the
-        base prompt is returned unchanged.
-    """
-    instructions = build_tool_instructions(config)
-    if not instructions:
-        return base_system
-    return f"{base_system}\n\n{instructions}\n\n{_confluence_citation_contract(config.language)}"
-
-
-def _build_cross_repo_scope_block(cross_repo_context: dict[str, Any] | None) -> str:
-    """Phase 123: Build cross-repo scope instruction block for the agent.
-
-    When shared_library_routing_activated or config_repo_companion_applied is True,
-    or scope_hint is 'all'/'lib'/'config', inject explicit instructions telling the
-    agent about the ``scope`` parameter on ``search_code`` so it searches beyond the
-    main repository.
-    """
-    if not cross_repo_context:
-        return ""
-
-    scope_hint = str(cross_repo_context.get("scope_hint") or "").strip().lower()
-    requirement_type_tag = str(cross_repo_context.get("requirement_type_tag") or "").strip().lower()
-    shared_lib_active = bool(cross_repo_context.get("shared_library_routing_activated"))
-    config_companion_active = bool(cross_repo_context.get("config_repo_companion_applied"))
-    has_lib_pack = bool(cross_repo_context.get("lib_pack"))
-    app_config_only = bool(cross_repo_context.get("app_config_only"))
-
-    is_cross_repo = (
-        scope_hint in {"all", "lib", "config"}
-        or requirement_type_tag in {"shared_library", "config_pattern"}
-        or shared_lib_active
-        or config_companion_active
-        or has_lib_pack
-        or app_config_only
-    )
-
-    if not is_cross_repo:
-        return ""
-
-    if app_config_only:
-        lines = [
-            "QUAN TRỌNG: Hướng dẫn chi tiết yêu cầu chỉ kiểm tra repo app-config.",
-            "Chỉ đọc các ref cấu hình app-config đã được phát hiện sẵn; nếu thật sự cần tìm thêm thì chỉ dùng search_code(query=..., scope='config', config_root_filter='app-config').",
-            "Khi mở file cấu hình, dùng read_code_file(path=..., scope='config', config_root_filter='app-config').",
-            "ƯU TIÊN đọc trực tiếp các file application.properties/application.yml/bootstrap.* đúng môi trường được nêu trong hướng dẫn.",
-            "KHÔNG dùng search_docs/read_doc_chunk.",
-            "KHÔNG dùng scope='all' hoặc scope='lib'.",
-            "KHÔNG mở rộng tìm kiếm sang repo ứng dụng hoặc repo config khác nếu chưa có bằng chứng app-config.",
-        ]
-        if scope_hint:
-            lines.append(f"scope_hint gợi ý: '{scope_hint}'")
-        if requirement_type_tag:
-            lines.append(f"loại yêu cầu: '{requirement_type_tag}'")
-        return "\n".join(lines)
-
-    lines = [
-        "QUAN TRỌNG: Yêu cầu này liên quan đến thư viện dùng chung và/hoặc phụ thuộc cross-repo.",
-        "Bạn CÓ THỂ tìm kiếm bằng chứng từ nhiều nguồn repo khác nhau bằng tham số scope của search_code:",
-        "- search_code(query=..., scope='lib') — tìm trong các repo thư viện dùng chung (shared library)",
-        "- search_code(query=..., scope='config') — tìm trong các repo cấu hình (config) và app-config",
-        "- search_code(query=..., scope='all') — tìm trong TẤT CẢ các repo khả dụng (main + lib + config)",
-        "HÃY sử dụng scope='all' hoặc scope='lib' để tìm bằng chứng từ thư viện dùng chung.",
-        "KHÔNG chỉ tìm trong repo chính — bằng chứng có thể nằm ở repo lib/config.",
-    ]
-
-    if scope_hint:
-        lines.append(f"scope_hint gợi ý: '{scope_hint}'")
-    if requirement_type_tag:
-        lines.append(f"loại yêu cầu: '{requirement_type_tag}'")
-
-    return "\n".join(lines)
-
-
-def build_agentic_user_prompt(
-    *,
-    row_id: str,
-    category: str,
-    requirement_text: str,
-    requirement_guidance: str | None = None,
-    requirement_interpretation: str | None = None,
-    instruction_rubric: str | None = None,
-    evidence_context: str | None = None,
-    evidence_refs: list[str] | None = None,
-    config: InstructionTemplateConfig,
-    cross_repo_context: dict[str, Any] | None = None,
-) -> str:
-    """Build user prompt adapted to the evidence strategy.
-
-    When ``evidence_strategy`` is ``TOOL_ONLY``, no inline evidence is
-    included — the agent is expected to discover it via tools.
-    When ``TOOL_FIRST``, a truncated summary is included as seed context.
-    When ``INLINE``, the full evidence is embedded (legacy behavior).
-    """
-    tool_bias = _tool_bias_for_category(category)
-    bias_hint = ""
-    if tool_bias == "docs_primary":
-        bias_hint = "ƯU TIÊN: Tìm kiếm bằng chứng từ tài liệu (search_docs/read_doc_chunk) trước khi tìm trong code."
-    elif tool_bias == "code_primary":
-        bias_hint = (
-            "ƯU TIÊN: Tìm kiếm bằng chứng từ mã nguồn (search_code/read_code_file) trước khi tìm trong tài liệu."
-        )
-
-    # Phase 123: Inject cross-repo scope instructions when shared_library/config routing is active.
-    cross_repo_scope_block = _build_cross_repo_scope_block(cross_repo_context)
-
-    lines: list[str] = [
-        "Đánh giá yêu cầu sau theo checklist:",
-        "",
-        f"row_id: {row_id}",
-        f"nhóm/loại: {category}",
-    ]
-    if bias_hint:
-        lines.append(f"tool_bias: {tool_bias}")
-        lines.append(bias_hint)
-    if cross_repo_scope_block:
-        lines.append("")
-        lines.append(cross_repo_scope_block)
-    lines += [
-        "",
-        "YÊU CẦU (requirement_text):",
-        requirement_text,
-        "",
-        "HƯỚNG DẪN ĐÁNH GIÁ (nếu có):",
-        requirement_guidance or "Không có hướng dẫn bổ sung.",
-    ]
-    if str(instruction_rubric or "").strip():
-        lines += [
-            "",
-            str(instruction_rubric).strip(),
-        ]
-    lines += [
-        "",
-        "DIỄN GIẢI YÊU CẦU CHUẨN HÓA:",
-        requirement_interpretation or "{}",
-        "",
-        "ĐẦU RA BẮT BUỘC (output schema):",
-        "- Với mỗi evidence_anchor loại code/doc: excerpt phải là trích dẫn nguyên văn 1-2 dòng từ nội dung đã đọc (evidence_context hoặc tool-read content).",
-        "- Nếu excerpt rỗng thì BẮT BUỘC có excerpt_unavailable_reason.",
-        '- Ví dụ hợp lệ: excerpt: "spring.datasource.url=jdbc:postgresql://...", excerpt_unavailable_reason: ""',
-        '- Ví dụ không hợp lệ: excerpt: "" (thiếu excerpt_unavailable_reason).',
-    ]
-
-    refs = evidence_refs or []
-
-    if config.evidence_strategy == EvidenceStrategy.TOOL_ONLY:
-        lines.extend(
-            [
-                "",
-                "BẰNG CHỨNG:",
-                "Sử dụng các công cụ (tools) để tìm kiếm và đọc bằng chứng.",
-                f"Số lượng tham chiếu gợi ý: {len(refs)}",
-            ]
-        )
-        if refs:
-            lines.append("Tham chiếu gợi ý (dùng để bắt đầu tìm kiếm):")
-            for ref in refs[:10]:
-                lines.append(f"- {ref}")
-
-    elif config.evidence_strategy == EvidenceStrategy.TOOL_FIRST:
-        seed = _truncate(evidence_context, config.max_inline_evidence_chars)
-        lines.extend(
-            [
-                "",
-                "BẰNG CHỨNG SƠ BỘ (seed — dùng tools để tìm thêm nếu cần):",
-                seed or "(không có bằng chứng sơ bộ — dùng tools để tìm)",
-                "",
-                f"DANH SÁCH THAM CHIẾU (evidence_refs): {len(refs)}",
-            ]
-        )
-        for ref in refs[:20]:
-            lines.append(f"- {ref}")
-
-    else:
-        # INLINE — legacy full embedding
-        lines.extend(
-            [
-                "",
-                "BẰNG CHỨNG (evidence_context, có thể bị cắt ngắn):",
-                evidence_context or "(không có bằng chứng)",
-                "",
-                f"DANH SÁCH THAM CHIẾU (evidence_refs): {len(refs)}",
-            ]
-        )
-        for ref in refs[:50]:
-            lines.append(f"- {ref}")
-
-    return "\n".join(lines)
-
-
-# ---------------------------------------------------------------------------
-# Skill metadata injection
-# ---------------------------------------------------------------------------
-
-
-def inject_skills_into_config(
-    config: InstructionTemplateConfig,
-    skills_metadata: list[Any],
-) -> InstructionTemplateConfig:
-    """Populate ``available_skills`` from runtime skill metadata.
-
-    Accepts ``SkillInfo`` instances from ``skills_toolset`` and converts
-    them to ``SkillDescriptor`` entries for prompt injection.
-
-    Returns a **new** config (the original is not mutated).
-    """
-    descriptors: list[SkillDescriptor] = []
-    for item in skills_metadata:
-        name = getattr(item, "name", None)
-        if not name:
-            continue
-        descriptors.append(
-            SkillDescriptor(
-                name=str(name),
-                description=str(getattr(item, "description", "") or ""),
-                trust_tier=str(getattr(item, "trust_tier", "external-unverified")),
-            )
-        )
-    return InstructionTemplateConfig(
-        mode=config.mode,
-        evidence_strategy=config.evidence_strategy,
-        available_tools=list(config.available_tools),
-        available_skills=descriptors,
-        max_inline_evidence_chars=config.max_inline_evidence_chars,
-        language=config.language,
-        runtime_mode=config.runtime_mode,
-        skills_toolset_enabled=config.skills_toolset_enabled,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-
-def _evidence_strategy_preamble(strategy: EvidenceStrategy, tools: list[str]) -> str:
-    tool_set = set(tools)
-
-    if strategy == EvidenceStrategy.TOOL_ONLY:
-        search_tools = [t for t in ("search_docs", "search_code") if t in tool_set]
-        read_tools = [t for t in ("read_doc_chunk", "read_code_file") if t in tool_set]
-        search_label = "/".join(search_tools) if search_tools else "search tools"
-        read_label = "/".join(read_tools) if read_tools else "read tools"
-        flow = f"get_row_context → {search_label} → {read_label} → đánh giá"
-        return (
-            "## Chiến lược bằng chứng: TOOL-ONLY\n"
-            "Bạn PHẢI sử dụng các công cụ (tools) để tìm kiếm và đọc bằng chứng.\n"
-            "KHÔNG có bằng chứng được cung cấp trực tiếp trong prompt.\n"
-            f"Quy trình: {flow}."
-        )
-    if strategy == EvidenceStrategy.TOOL_FIRST:
-        search_tools = [t for t in ("search_docs", "search_code") if t in tool_set]
-        search_label = "/".join(search_tools) if search_tools else "search tools"
-        return (
-            "## Chiến lược bằng chứng: TOOL-FIRST\n"
-            "Bằng chứng sơ bộ có thể được cung cấp; ưu tiên đánh giá trực tiếp từ seed + evidence_refs.\n"
-            f"Chỉ dùng {search_label} khi còn thiếu/mơ hồ và KHÔNG lặp lại cùng tool+query.\n"
-            "Mỗi vòng chỉ gọi tối đa một search theo docs và một search theo code, "
-            "sau đó chuyển sang đọc/ghi tham chiếu."
-        )
-    return (
-        "## Chiến lược bằng chứng: INLINE\n"
-        "Toàn bộ bằng chứng đã được cung cấp trong prompt. Đánh giá dựa trên nội dung đã cho."
-    )
-
-
-def _build_tool_section(tools: list[str], *, detailed: bool) -> str:
-    lines = ["## Công cụ khả dụng (Available Tools)"]
-    for tool_name in tools:
-        desc = _TOOL_CATALOG.get(tool_name, "")
-        if not desc:
-            continue
-        if detailed:
-            hint = _TOOL_USAGE_HINTS.get(tool_name, "")
-            lines.append(f"- **{tool_name}**: {desc}")
-            if hint:
-                lines.append(f"  → {hint}")
-        else:
-            lines.append(f"- **{tool_name}**: {desc}")
-    return "\n".join(lines)
-
-
-def _build_skill_section(skills: list[SkillDescriptor]) -> str:
-    lines = [
-        "## Kỹ năng khả dụng (Available Skills)",
-        "Chỉ được sử dụng các skill được liệt kê dưới đây.",
-        "KHÔNG được bịa tên skill, resource, hoặc script.",
-    ]
-    for skill in skills:
-        tier_label = {"internal": "✅", "external-verified": "☑️", "external-unverified": "⚠️"}.get(skill.trust_tier, "⚠️")
-        lines.append(f"- {tier_label} **{skill.name}**: {skill.description}")
-    return "\n".join(lines)
-
-
-def _grounding_rules(language: str) -> str:
-    if language == "vi":
-        return (
-            "## Quy tắc grounding\n"
-            "- Chỉ trích dẫn bằng chứng thực tế từ tools hoặc context đã cung cấp.\n"
-            "- KHÔNG suy đoán nội dung từ tên file.\n"
-            "- KHÔNG bịa đường dẫn, URL, hoặc nội dung không tồn tại.\n"
-            "- Nếu không tìm thấy bằng chứng qua tools, ghi rõ 'không tìm thấy' và cho điểm thấp.\n"
-            "- Tránh gọi lặp lại cùng tool với cùng tham số; nếu không có tín hiệu mới sau 2 lượt, dừng tìm thêm.\n"
-            "- Với trích dẫn Confluence, bắt buộc dùng ref_type='confluence_page' và phải có page_id + source_uri chuẩn tắc (chấp nhận alias source_url).\n"
-            "- Ghi lại tất cả tham chiếu đã tìm được bằng record_evidence_refs."
-        )
-    return (
-        "## Grounding Rules\n"
-        "- Only cite evidence actually retrieved from tools or provided context.\n"
-        "- Do NOT speculate about content based on file names.\n"
-        "- Do NOT fabricate paths, URLs, or content.\n"
-        "- If no evidence is found via tools, state 'not found' and score low.\n"
-        "- Avoid repeating the same tool call with the same arguments; if no new signal after two attempts, stop searching.\n"
-        "- For Confluence citations, use ref_type='confluence_page' and include page_id plus canonical source_uri (source_url alias accepted).\n"
-        "- Record all discovered references using record_evidence_refs."
-    )
-
-
-def _confluence_citation_contract(language: str) -> str:
-    if language == "vi":
-        return (
-            "## Ràng buộc trích dẫn Confluence\n"
-            "- Khi ghi nhận tham chiếu Confluence, bắt buộc dùng ref_type='confluence_page'.\n"
-            "- Mỗi tham chiếu phải có page_id và source_uri chuẩn tắc (source_url là alias hợp lệ).\n"
-        )
-    return (
-        "## Confluence Citation Contract\n"
-        "- For Confluence references, ref_type MUST be 'confluence_page'.\n"
-        "- Each reference MUST include page_id and canonical source_uri (source_url alias is accepted).\n"
-    )
-
-
-def _runtime_directives(
-    runtime_mode: AgentRuntimeMode,
-    language: str,
-    *,
-    skills_toolset_enabled: bool,
-) -> str:
-    _ = runtime_mode
-    if not skills_toolset_enabled:
-        return ""
-
-    if language == "en":
-        return (
-            "## Skill Operation Directives\n"
-            "- Use row policy `skills_needed` as the row-level gate for skill strictness.\n"
-            "- If `Available Skills` is empty, do not call `list_skills`, `load_skill`, `read_skill_resource`, or `run_skill_script`; continue with docs/code tools only.\n"
-            "- If `skills_needed=true`, execute one bounded skill sequence: `load_skill` then `read_skill_resource` or `run_skill_script`.\n"
-            "- For `skills_needed=true`, avoid finalizing without at least one execution-class skill call unless no applicable skill/resource exists.\n"
-            "- If `skills_needed=false`, skill calls remain optional; avoid discovery-only churn.\n"
-            "- Use ONLY exact skill identifiers listed in `Available Skills`; do not invent skill names.\n"
-            "- Call `list_skills` at most once per row.\n"
-            "- Call `load_skill` at most once per selected skill unless changing to a different skill.\n"
-            "- After `load_skill`, immediately perform `read_skill_resource` or `run_skill_script`; avoid repeated load-only loops.\n"
-            "- When using skills, only call these operations:\n"
-            "  - list_skills\n"
-            "  - load_skill\n"
-            "  - read_skill_resource\n"
-            "  - run_skill_script\n"
-            "- Prefer resource reads and scripts that directly produce row-level evidence.\n"
-            "- Avoid repetitive skill calls without new evidence; stop after two non-progress skill calls."
-        )
-
-    return (
-        "## Chỉ thị thao tác Skill\n"
-        "- Dùng `skills_needed` như điều kiện điều phối độ chặt cho row hiện tại.\n"
-        "- Nếu `Available Skills` đang rỗng, không gọi `list_skills`, `load_skill`, `read_skill_resource`, hoặc `run_skill_script`; chỉ dùng docs/code tools.\n"
-        "- Nếu `skills_needed=true`, thực thi 1 chuỗi skill ngắn: `load_skill` rồi `read_skill_resource` hoặc `run_skill_script`.\n"
-        "- Với `skills_needed=true`, không kết thúc khi chưa có ít nhất 1 lượt skill thuộc nhóm thực thi, trừ khi không có skill/resource phù hợp.\n"
-        "- Nếu `skills_needed=false`, skill vẫn là tùy chọn; tránh discovery-only churn.\n"
-        "- Chỉ dùng đúng tên skill trong mục `Available Skills`; không tự tạo tên skill mới.\n"
-        "- Chỉ gọi `list_skills` tối đa 1 lần cho mỗi row.\n"
-        "- Với mỗi skill đã chọn, chỉ gọi `load_skill` tối đa 1 lần (trừ khi đổi sang skill khác).\n"
-        "- Sau `load_skill`, phải chuyển ngay sang `read_skill_resource` hoặc `run_skill_script`; tránh vòng lặp load-only.\n"
-        "- Khi dùng skill, chỉ gọi các thao tác sau:\n"
-        "  - list_skills\n"
-        "  - load_skill\n"
-        "  - read_skill_resource\n"
-        "  - run_skill_script\n"
-        "- Ưu tiên đọc resource/chạy script tạo bằng chứng trực tiếp cho row hiện tại.\n"
-        "- Tránh lặp lại gọi skill khi không tạo thêm bằng chứng mới; dừng sau 2 lượt không tiến triển."
-    )
-
-
-def _truncate(text: str | None, max_chars: int) -> str | None:
-    if not text:
-        return None
-    if len(text) <= max_chars:
-        return text
-    return text[:max_chars] + "\n\n… (truncated — use tools to read full content)"
-
-
-def _prompt_hash_material() -> str:
-    """Build canonical hash input for instruction template prompt metadata."""
-    sample_config = InstructionTemplateConfig(
-        mode=InstructionMode.FULL,
-        evidence_strategy=EvidenceStrategy.TOOL_FIRST,
-        available_tools=sorted(_TOOL_CATALOG.keys()),
-        language="vi",
-        runtime_mode=AgentRuntimeMode.PYDANTICAI,
-        skills_toolset_enabled=True,
-    )
-    sample_user_prompt = build_agentic_user_prompt(
-        row_id="ROW-001",
-        category="security",
-        requirement_text="Phải có xác thực API.",
-        requirement_guidance="Đánh giá dựa trên tài liệu và code liên quan.",
-        evidence_context="api/auth.py chứa middleware validate token.",
-        evidence_refs=["src/api/auth.py", "docs/security.md"],
-        config=sample_config,
-    )
-    material = {
-        "tool_catalog": _TOOL_CATALOG,
-        "tool_usage_hints": _TOOL_USAGE_HINTS,
-        "evidence_preambles": {
-            strategy.value: _evidence_strategy_preamble(strategy, sorted(_TOOL_CATALOG.keys()))
-            for strategy in EvidenceStrategy
-        },
-        "grounding_rules": {
-            "vi": _grounding_rules("vi"),
-            "en": _grounding_rules("en"),
-        },
-        "runtime_directives": {
-            "vi": _runtime_directives(AgentRuntimeMode.PYDANTICAI, "vi", skills_toolset_enabled=True),
-            "en": _runtime_directives(AgentRuntimeMode.PYDANTICAI, "en", skills_toolset_enabled=True),
-        },
-        "sample_user_prompt": sample_user_prompt,
-    }
-    return json.dumps(material, ensure_ascii=False, sort_keys=True)
-
-
-PROMPT_VERSION = "1.1.0"
-PROMPT_CHANGELOG = (
-    "1.0.0: Added prompt metadata constants for provenance/version tracking (FR-86).",
-    "1.1.0: Added Confluence citation contract guidance for record_evidence_refs and grounding rules (FR-233).",
-)
-PROMPT_HASH = hashlib.sha256(f"{PROMPT_VERSION}\n{_prompt_hash_material()}".encode()).hexdigest()

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/llm/prompts/readme_evaluation.py

@@ -1,25 +0,0 @@
-"""Prompt templates for README evaluation."""
-
-from __future__ import annotations
-
-import hashlib
-
-README_EVALUATION_SYSTEM = """You are a documentation quality expert.
-Evaluate the README file for clarity, completeness, and usability.
-"""
-
-README_EVALUATION_USER = """README Content:
-{content}
-
-Evaluate based on:
-1. Project Description (Clear?)
-2. Installation Instructions (Complete?)
-3. Usage Examples (Present?)
-4. Configuration (Documented?)
-"""
-
-PROMPT_VERSION = "1.0.0"
-PROMPT_CHANGELOG = ("1.0.0: Added prompt metadata constants for provenance/version tracking (FR-86).",)
-PROMPT_HASH = hashlib.sha256(
-    f"{PROMPT_VERSION}\n{README_EVALUATION_SYSTEM}\n{README_EVALUATION_USER}".encode()
-).hexdigest()