@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/models/checklist.py

@@ -1,921 +0,0 @@
-"""Audit checklist row evaluation models (TSK-180/181).
-
-Phase 18: Template-row-locked checklist artifacts with evidence-anchored scoring.
-
-This module provides the canonical data models for audit checklist generation,
-ensuring strict 1:1 mapping between template rows and evaluation results.
-
-Research Foundation:
-- RULERS (arXiv:2601.08654): Locked rubrics + evidence-anchored scoring
-- Evaluative Fingerprints (arXiv:2601.05114): Provenance tracking for reproducibility
-- TICK (arXiv:2410.03608): Checklist decomposition for complex requirements
-
-Reference: design.md Section "Phase 18-19 Implementation Reference"
-"""
-
-from __future__ import annotations
-
-import hashlib
-from datetime import datetime
-from enum import StrEnum
-from typing import Any, ClassVar
-
-from pydantic import BaseModel, ConfigDict, Field, computed_field
-
-VERIFICATION_REASON_EXCERPT_VERIFIED_IN_CONTEXT = "excerpt_verified_in_context"
-VERIFICATION_REASON_EXCERPT_SEMANTIC_MATCH = "excerpt_semantic_match"
-VERIFICATION_REASON_EXCERPT_MISMATCH_OR_UNVERIFIED = "excerpt_mismatch_or_unverified"
-VERIFICATION_REASON_NO_EXCERPT_TO_VERIFY = "no_excerpt_to_verify"
-VERIFICATION_REASON_EXCERPT_VERIFICATION_DISABLED = "excerpt_verification_disabled"
-VERIFICATION_REASON_LLM_ANCHOR_PROVIDED = "llm_anchor_provided"
-VERIFICATION_REASON_FALLBACK_REF_INHERITED = "fallback_ref_inherited"
-VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE = "extracted_from_finding_evidence"
-VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF = "extracted_from_finding_evidence_ref"
-VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_DATA = "extracted_from_finding_evidence_data"
-VERIFICATION_REASON_VERIFIED_WITHOUT_REASON = "verified_without_explicit_reason"
-
-_VERIFICATION_REASON_TAXONOMY: frozenset[str] = frozenset(
-    {
-        VERIFICATION_REASON_EXCERPT_VERIFIED_IN_CONTEXT,
-        VERIFICATION_REASON_EXCERPT_SEMANTIC_MATCH,
-        VERIFICATION_REASON_EXCERPT_MISMATCH_OR_UNVERIFIED,
-        VERIFICATION_REASON_NO_EXCERPT_TO_VERIFY,
-        VERIFICATION_REASON_EXCERPT_VERIFICATION_DISABLED,
-        VERIFICATION_REASON_LLM_ANCHOR_PROVIDED,
-        VERIFICATION_REASON_FALLBACK_REF_INHERITED,
-        VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE,
-        VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF,
-        VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_DATA,
-        VERIFICATION_REASON_VERIFIED_WITHOUT_REASON,
-    }
-)
-
-_VERIFICATION_REASON_ALIASES: dict[str, str] = {
-    "verified": VERIFICATION_REASON_EXCERPT_VERIFIED_IN_CONTEXT,
-    "verified_true": VERIFICATION_REASON_EXCERPT_VERIFIED_IN_CONTEXT,
-    "unverified": VERIFICATION_REASON_EXCERPT_MISMATCH_OR_UNVERIFIED,
-    "extracted_from_finding_evidence_reference": VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF,
-    "extracted-from-finding-evidence-ref": VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF,
-    "extracted-from-finding-evidence-data": VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_DATA,
-}
-
-
-def normalize_verification_reason(
-    reason: str | None,
-    *,
-    verified: bool,
-    excerpt: str | None = None,
-) -> str:
-    """Normalize evidence verification reason into Phase 86 taxonomy."""
-    normalized = str(reason or "").strip().lower().replace("-", "_").replace(" ", "_")
-    normalized = _VERIFICATION_REASON_ALIASES.get(normalized, normalized)
-    if normalized in _VERIFICATION_REASON_TAXONOMY:
-        return normalized
-    if verified:
-        return VERIFICATION_REASON_VERIFIED_WITHOUT_REASON
-    has_excerpt = bool(str(excerpt or "").strip())
-    if has_excerpt:
-        return VERIFICATION_REASON_EXCERPT_MISMATCH_OR_UNVERIFIED
-    return VERIFICATION_REASON_NO_EXCERPT_TO_VERIFY
-
-
-class RowStatus(StrEnum):
-    """Row evaluation status with strict, stable mapping.
-
-    Vietnamese output mapping:
-    - PASS → ĐẠT
-    - PARTIAL → MỘT PHẦN
-    - FAIL → KHÔNG ĐẠT
-    - NA → KHÔNG ÁP DỤNG
-    - ERROR → LỖI
-    """
-
-    PASS = "PASS"  # final_score >= 90, no critical gating failures
-    PARTIAL = "PARTIAL"  # 40 <= final_score < 90
-    FAIL = "FAIL"  # final_score < 40 OR critical gating failure
-    NA = "N/A"  # Not applicable to profile/repo
-    ERROR = "ERROR"  # Evaluation failed (tooling error)
-
-    @classmethod
-    def from_score(cls, score: float, *, gating_failure: bool = False) -> RowStatus:
-        """Map score to status using documented thresholds.
-
-        Args:
-            score: Final score as percentage (0-100).
-            gating_failure: Whether a critical gating condition failed.
-
-        Returns:
-            Appropriate RowStatus based on thresholds.
-        """
-        if gating_failure:
-            return cls.FAIL
-        if score >= 90:
-            return cls.PASS
-        if score >= 40:
-            return cls.PARTIAL
-        return cls.FAIL
-
-    @property
-    def vietnamese(self) -> str:
-        """Get Vietnamese translation for stakeholder output."""
-        mapping = {
-            RowStatus.PASS: "ĐẠT",
-            RowStatus.PARTIAL: "MỘT PHẦN",
-            RowStatus.FAIL: "KHÔNG ĐẠT",
-            RowStatus.NA: "KHÔNG ÁP DỤNG",
-            RowStatus.ERROR: "LỖI",
-        }
-        return mapping[self]
-
-    @property
-    def emoji(self) -> str:
-        """Get emoji representation for markdown output."""
-        mapping = {
-            RowStatus.PASS: "✅",
-            RowStatus.PARTIAL: "⚠️",
-            RowStatus.FAIL: "❌",
-            RowStatus.NA: "➖",
-            RowStatus.ERROR: "🔴",
-        }
-        return mapping[self]
-
-
-class EvidenceAnchor(BaseModel):
-    """Evidence reference with verification metadata.
-
-    Design note: Evidence anchors are extractive (verbatim excerpts from source)
-    rather than abstractive to ensure auditability per RULERS research.
-    """
-
-    model_config = ConfigDict(extra="ignore")
-
-    ref_type: str = Field(
-        description="Type of evidence reference: code_path | confluence_url | bitbucket_ref | doc_path | jira_key"
-    )
-    ref_value: str = Field(description="The actual reference (path, URL, key, etc.)")
-    ref_hash: str | None = Field(
-        default=None,
-        description="SHA256 hash of content for verification",
-    )
-    excerpt: str | None = Field(
-        default=None,
-        description="Verbatim excerpt from source (extractive, not paraphrased)",
-    )
-    excerpt_unavailable_reason: str | None = Field(
-        default=None,
-        description="Explicit reason when excerpt is unavailable (required when excerpt is empty).",
-    )
-    verified: bool = Field(
-        default=False,
-        description="Whether excerpt was verified against source content",
-    )
-    verification_reason: str | None = Field(
-        default=None,
-        description="Verification decision reason (for example excerpt_verified_in_context, no_excerpt_to_verify)",
-    )
-    line_range: tuple[int, int] | None = Field(
-        default=None,
-        description="Line range for code evidence (start, end)",
-    )
-    page_id: str | None = Field(
-        default=None,
-        description="Canonical Confluence page id for docs evidence when available.",
-    )
-    page_title: str | None = Field(
-        default=None,
-        description="Human-readable Confluence page title for docs evidence when available.",
-    )
-    source_url: str | None = Field(
-        default=None,
-        description="Canonical source URL for docs evidence when available.",
-    )
-    chunk_id: str | None = Field(
-        default=None,
-        description="Internal chunk identity preserved for grounding and traceability.",
-    )
-
-    @computed_field
-    @property
-    def anchor_id(self) -> str:
-        """Stable identifier for deduplication."""
-        key = f"{self.ref_type}|{self.ref_value}|{self.ref_hash or ''}"
-        return hashlib.sha256(key.encode()).hexdigest()[:16]
-
-    @computed_field
-    @property
-    def file_path(self) -> str | None:
-        """Expose code-backed refs under an explicit file_path field for downstream consumers."""
-        normalized_type = str(self.ref_type or "").strip().lower()
-        if normalized_type not in {"code_path", "code_file", "file_path"}:
-            return None
-        return self.ref_value or None
-
-    def format_for_output(self, max_excerpt_length: int = 200) -> str:
-        """Format anchor for human-readable output."""
-        parts = [f"{self.ref_type}: {self.ref_value}"]
-        if self.line_range:
-            parts[0] += f" (L{self.line_range[0]}-{self.line_range[1]})"
-        if self.excerpt:
-            excerpt = self.excerpt[:max_excerpt_length]
-            if len(self.excerpt) > max_excerpt_length:
-                excerpt += "..."
-            parts.append(f'  "{excerpt}"')
-        return "\n".join(parts)
-
-
-class ScoreBreakdown(BaseModel):
-    """Detailed score calculation breakdown for auditability.
-
-    Formula: final_score = min(raw_score, score_cap_applied?) * coverage_factor * confidence_factor
-    """
-
-    model_config = ConfigDict(extra="ignore")
-
-    raw_score: float = Field(
-        ge=0.0,
-        le=100.0,
-        description="Initial score before adjustments (0-100)",
-    )
-    raw_score_0_10: float | None = Field(
-        default=None,
-        ge=0.0,
-        le=10.0,
-        description="0-10 scale version for legacy compatibility",
-    )
-    score_cap_applied: float | None = Field(
-        default=None,
-        description="Score cap if gating conditions failed",
-    )
-    coverage_factor: float = Field(
-        default=1.0,
-        ge=0.0,
-        le=1.0,
-        description="Evidence coverage ratio (how much of requirement was verified)",
-    )
-    confidence_factor: float = Field(
-        default=1.0,
-        ge=0.0,
-        le=1.0,
-        description="Judgment confidence (deterministic=high, LLM=variable)",
-    )
-    final_score: float = Field(
-        ge=0.0,
-        le=100.0,
-        description="Final adjusted score after all factors applied",
-    )
-
-    @computed_field
-    @property
-    def calculation_formula(self) -> str:
-        """Human-readable formula showing how final_score was derived."""
-        parts = [f"raw={self.raw_score:.1f}"]
-        if self.score_cap_applied is not None:
-            parts.append(f"cap={self.score_cap_applied:.1f}")
-        if self.coverage_factor < 1.0:
-            parts.append(f"cov={self.coverage_factor:.2f}")
-        if self.confidence_factor < 1.0:
-            parts.append(f"conf={self.confidence_factor:.2f}")
-        return " × ".join(parts) + f" = {self.final_score:.1f}"
-
-    @classmethod
-    def compute(
-        cls,
-        raw_score: float,
-        *,
-        score_cap: float | None = None,
-        coverage: float = 1.0,
-        confidence: float = 1.0,
-    ) -> ScoreBreakdown:
-        """Compute score breakdown from inputs.
-
-        Args:
-            raw_score: Initial score (0-100).
-            score_cap: Optional cap to apply.
-            coverage: Evidence coverage factor (0-1).
-            confidence: Judgment confidence factor (0-1).
-
-        Returns:
-            Computed ScoreBreakdown with final_score.
-        """
-        effective_score = raw_score
-        if score_cap is not None:
-            effective_score = min(raw_score, score_cap)
-        final = effective_score * coverage * confidence
-
-        return cls(
-            raw_score=raw_score,
-            raw_score_0_10=raw_score / 10.0,
-            score_cap_applied=score_cap,
-            coverage_factor=coverage,
-            confidence_factor=confidence,
-            final_score=final,
-        )
-
-
-class RowProvenance(BaseModel):
-    """Provenance metadata for reproducibility and audit trail.
-
-    Per Evaluative Fingerprints research, recording provenance enables:
-    - Variance detection across repeat runs
-    - Model-specific calibration
-    - Debugging evaluation discrepancies
-    """
-
-    model_config = ConfigDict(extra="ignore")
-
-    row_llm_mode: str = Field(
-        description="Evaluation mode: off | selective | per-row",
-    )
-    protocol: str | None = Field(
-        default=None,
-        description="LLM protocol if used (anthropic, openai, gemini, etc.)",
-    )
-    model: str | None = Field(
-        default=None,
-        description="Model name if LLM used (e.g., claude-sonnet-4-20250514)",
-    )
-    prompt_version: str | None = Field(
-        default=None,
-        description="Prompt template version used by evaluator when applicable",
-    )
-    prompt_hash: str | None = Field(
-        default=None,
-        description="Prompt template hash used by evaluator when applicable",
-    )
-    instruction_profile: str | None = Field(
-        default=None,
-        description="Resolved instruction profile identifier for this row evaluation",
-    )
-    instruction_inputs: dict[str, Any] | None = Field(
-        default=None,
-        description="Resolved instruction inputs used to derive instruction profile/hash",
-    )
-    instruction_hash: str | None = Field(
-        default=None,
-        description="Stable hash derived from instruction inputs for reproducibility",
-    )
-    template_hash: str = Field(
-        description="SHA256 hash of template content (first 16 chars)",
-    )
-    rubric_version: str | None = Field(
-        default=None,
-        description="Template version string if available",
-    )
-    evidence_hash: str = Field(
-        description="SHA256 hash of evidence bundle used (first 16 chars)",
-    )
-    evaluated_at: datetime = Field(
-        default_factory=datetime.utcnow,
-        description="Timestamp of evaluation",
-    )
-    evaluation_duration_ms: int | None = Field(
-        default=None,
-        description="Evaluation duration in milliseconds",
-    )
-    cache_hit: bool = Field(
-        default=False,
-        description="Whether result was retrieved from cache",
-    )
-    source_run_id: str | None = Field(
-        default=None,
-        description="Run ID from which this row result was sourced after targeted or cross-run merge.",
-    )
-    original_provider: str | None = Field(
-        default=None,
-        description="Provider/profile originally selected for the row or containing run.",
-    )
-    final_provider: str | None = Field(
-        default=None,
-        description="Provider/profile that produced the final row result.",
-    )
-    failover_count: int = Field(
-        default=0,
-        ge=0,
-        description="Number of provider failover hops applied before final row result.",
-    )
-    failover_chain: list[str] = Field(
-        default_factory=list,
-        description="Ordered provider/profile chain observed for the row result.",
-    )
-    failover_reason: str | None = Field(
-        default=None,
-        description="Structured reason for provider failover when one occurred.",
-    )
-
-    @computed_field
-    @property
-    def evaluation_source(self) -> str:
-        """Human-readable evaluation source description."""
-        if self.row_llm_mode == "off":
-            return "deterministic"
-        if self.cache_hit:
-            return f"cached:{self.protocol or 'rule'}:{self.model or 'deterministic'}"
-        if self.protocol and self.model:
-            return f"{self.protocol}:{self.model}"
-        return "rule:deterministic"
-
-
-class RowEvaluation(BaseModel):
-    """Complete evaluation result for a single template row (TSK-180/181).
-
-    This is the atomic unit of the audit checklist. Each row corresponds
-    to exactly one row in the input template (strict 1:1 mapping).
-
-    Design Pattern: Follows existing CheckFinding patterns from models/findings.py
-    but adds evidence anchoring per RULERS research.
-    """
-
-    model_config = ConfigDict(extra="ignore", populate_by_name=True)
-
-    # Row identification (strict template match)
-    row_id: str = Field(
-        description="Stable row identifier from template (e.g., 'SEC-001:row_5')",
-    )
-    row_index: int = Field(
-        ge=0,
-        description="0-based index in original template",
-    )
-    check_id: str | None = Field(
-        default=None,
-        description="Check ID if structured template",
-    )
-    section_id: str | None = Field(
-        default=None,
-        description="Section ID if structured template",
-    )
-
-    # Original requirement (preserved from template)
-    requirement_text: str = Field(
-        description="Original requirement text from template row (Tiêu chí con kỹ thuật)",
-    )
-    requirement_category: str | None = Field(
-        default=None,
-        description="Rule/Group/Category from template (Quy tắc / Tiêu chí chính)",
-    )
-
-    # Weights (original and adjusted)
-    weight_raw: float = Field(
-        description="Original weight from template (Trọng số)",
-    )
-    weight_adjusted: float = Field(
-        description="Profile-adjusted weight",
-    )
-    weight_adjustment_reason: str | None = Field(
-        default=None,
-        description="Why weight was adjusted (if applicable)",
-    )
-
-    # Evaluation results
-    status: RowStatus = Field(
-        description="Final row status (PASS/PARTIAL/FAIL/NA/ERROR)",
-    )
-    score_breakdown: ScoreBreakdown = Field(
-        description="Detailed score calculation for auditability",
-    )
-    gating_applied: bool = Field(
-        default=False,
-        description="Whether score gating rules were applied to this row",
-    )
-    gating_reason: str | None = Field(
-        default=None,
-        description="Trigger reason when score gating was applied",
-    )
-
-    # Evidence (anchored, extractive)
-    evidence_refs: list[EvidenceAnchor] = Field(
-        default_factory=list,
-        description="Evidence anchors supporting this evaluation",
-    )
-    retrieval_trace: dict[str, Any] | None = Field(
-        default=None,
-        description="Optional retrieval/tool trace metadata propagated from row evaluation runtime",
-    )
-    evidence_gap_diagnostics: dict[str, Any] | None = Field(
-        default=None,
-        description="Optional evidence-gap classification projected from retrieval trace for checklist export",
-    )
-
-    # Reason + Finding (requirement-scoped, mandatory)
-    reason: str = Field(
-        description="Why evidence meets/does not meet requirement (Lý do, 1-3 sentences)",
-    )
-    reasoning: str = Field(
-        default="",
-        description="LLM chain-of-thought reasoning (from RowEvaluationResponse.reasoning)",
-    )
-    finding: str = Field(
-        description="Actionable finding scoped to this requirement (Phát hiện)",
-    )
-
-    # Remediation metadata
-    severity: str | None = Field(
-        default=None,
-        description="Issue severity: CRITICAL | HIGH | MEDIUM | LOW | INFO",
-    )
-    priority: str | None = Field(
-        default=None,
-        description="Remediation priority: P0 | P1 | P2 | P3",
-    )
-    effort: str | None = Field(
-        default=None,
-        description="Remediation effort: S | M | L | XL",
-    )
-    recommendation: str | None = Field(
-        default=None,
-        description="Remediation suggestion",
-    )
-
-    # Provenance
-    provenance: RowProvenance = Field(
-        description="Evaluation provenance for reproducibility",
-    )
-
-    # Multi-probe decomposition (optional, for complex rows per TICK research)
-    probe_results: list[dict[str, Any]] | None = Field(
-        default=None,
-        description="Sub-question results if row was decomposed into boolean probes",
-    )
-
-    # Score in original scale (1-5) for Vietnamese checklist
-    score_1_5: int | None = Field(
-        default=None,
-        ge=1,
-        le=5,
-        description="Score in 1-5 scale for Điểm (1-5) column",
-    )
-    retry_count: int = Field(
-        default=0,
-        ge=0,
-        description="Number of retry attempts before final row result.",
-    )
-    retry_metadata: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Structured retry/validation diagnostics for troubleshooting.",
-    )
-    retry_outcome: str | None = Field(
-        default=None,
-        description="Normalized retry/finalization outcome projected for top-level checklist row export.",
-    )
-    repo_key: str | None = Field(
-        default=None,
-        description="Repository storage key associated with this row result when available.",
-    )
-    repo_path: str | None = Field(
-        default=None,
-        description="Repository path associated with this row result when available.",
-    )
-    recommended_skills: list[str] | None = Field(
-        default=None,
-        description="Recommended strict-skill set projected for this row when available.",
-    )
-    observed_skill_effective_calls: int | None = Field(
-        default=None,
-        description="Effective skill execution count projected for this row when available.",
-    )
-    coverage_requirements: float | None = Field(
-        default=None,
-        description="Requirement-level coverage score derived from retrieval/evidence metrics.",
-    )
-    coverage_code: float | None = Field(
-        default=None,
-        description="Code evidence coverage ratio for this row.",
-    )
-    coverage_docs: float | None = Field(
-        default=None,
-        description="Documentation evidence coverage ratio for this row.",
-    )
-    coverage_confidence: float | None = Field(
-        default=None,
-        description="Confidence-adjusted coverage factor for this row.",
-    )
-    coverage_deterministic_downgrade_flag: bool = Field(
-        default=False,
-        description="True when very-low-coverage deterministic downgrade hook was applied.",
-    )
-
-    # Phase 122: Requirement guidance for instruction analysis
-    requirement_guidance: str | None = Field(
-        default=None,
-        description="Normalized guidance text for this requirement (Hướng dẫn chi tiết), used by Phase 122 instruction analyzer",
-    )
-
-    @computed_field
-    @property
-    def score_percent(self) -> float:
-        """Convenience accessor for final score as percentage."""
-        return self.score_breakdown.final_score
-
-    @computed_field
-    @property
-    def status_vietnamese(self) -> str:
-        """Vietnamese status for stakeholder output (Trạng thái)."""
-        return self.status.vietnamese
-
-    @computed_field
-    @property
-    def points_awarded(self) -> float:
-        """Points awarded based on weight and score."""
-        return (self.score_percent / 100.0) * self.weight_adjusted
-
-    @computed_field
-    @property
-    def evidence_refs_str(self) -> str:
-        """Format evidence refs as newline-separated string for Excel."""
-
-        def _display_ref(ref: EvidenceAnchor) -> str:
-            if ref.page_title and ref.source_url:
-                return f"{ref.page_title}: {ref.source_url}"
-            if ref.page_title:
-                return ref.page_title
-            if ref.source_url:
-                return ref.source_url
-            return f"{ref.ref_type}: {ref.ref_value}"
-
-        return "\n".join(_display_ref(ref) for ref in self.evidence_refs[:5])
-
-    def compute_score_1_5(self) -> int:
-        """Compute 1-5 score from percentage for Vietnamese checklist."""
-        pct = self.score_percent
-        if pct >= 90:
-            return 5
-        if pct >= 70:
-            return 4
-        if pct >= 50:
-            return 3
-        if pct >= 30:
-            return 2
-        return 1
-
-
-class ChecklistExportConfig(BaseModel):
-    """Configuration for checklist export formats."""
-
-    model_config = ConfigDict(extra="ignore")
-
-    include_score_breakdown: bool = Field(
-        default=True,
-        description="Include detailed score breakdown columns",
-    )
-    include_evidence_excerpts: bool = Field(
-        default=True,
-        description="Include evidence excerpts in output",
-    )
-    include_provenance: bool = Field(
-        default=True,
-        description="Include provenance columns",
-    )
-    include_probe_results: bool = Field(
-        default=False,
-        description="Include multi-probe decomposition results",
-    )
-    max_evidence_refs: int = Field(
-        default=5,
-        ge=1,
-        le=20,
-        description="Maximum evidence references per row",
-    )
-    max_excerpt_length: int = Field(
-        default=500,
-        ge=50,
-        le=2000,
-        description="Maximum excerpt length in characters",
-    )
-    max_reason_length: int = Field(
-        default=500,
-        ge=100,
-        le=2000,
-        description="Maximum reason/finding length in characters",
-    )
-
-
-class AuditChecklist(BaseModel):
-    """Complete audit checklist artifact (TSK-180).
-
-    This is the canonical machine-readable format. The Excel output
-    is derived from this JSON structure.
-
-    Contract: Row count MUST equal input template row count (strict 1:1 mapping).
-    """
-
-    model_config = ConfigDict(extra="ignore", populate_by_name=True)
-
-    # Metadata
-    checklist_version: str = Field(
-        default="1.0.0",
-        description="Schema version for forward compatibility",
-    )
-    generated_at: datetime = Field(
-        default_factory=datetime.utcnow,
-        description="Generation timestamp",
-    )
-
-    # Template identification
-    template_name: str = Field(
-        description="Template name/title",
-    )
-    template_version: str = Field(
-        description="Template version string",
-    )
-    template_hash: str = Field(
-        description="SHA256 hash of template content (first 16 chars)",
-    )
-    template_row_count: int = Field(
-        ge=0,
-        description="Total rows in input template (for validation)",
-    )
-
-    # Repository identification
-    repository: str = Field(
-        description="Repository name/path being audited",
-    )
-    repository_ref: str | None = Field(
-        default=None,
-        description="Git ref (commit SHA, branch, tag)",
-    )
-
-    # Evaluation configuration
-    row_llm_mode: str = Field(
-        description="Row evaluation mode: off | selective | per-row",
-    )
-    evidence_hash: str = Field(
-        description="SHA256 hash of evidence bundle (first 16 chars)",
-    )
-
-    # Row evaluations (strict 1:1 with template)
-    rows: list[RowEvaluation] = Field(
-        default_factory=list,
-        description="One entry per template row, in original order",
-    )
-
-    # Stability flags (for variance detection per Evaluative Fingerprints)
-    stability_flags: list[str] = Field(
-        default_factory=list,
-        description="Variance warnings from repeat-run checks",
-    )
-
-    # Result columns defined in spec
-    _result_columns: ClassVar[list[tuple[str, str]]] = [
-        ("Trạng thái", "status_vietnamese"),
-        ("Điểm (%)", "score_percent"),
-        ("Điểm (1-5)", "score_1_5"),
-        ("Lý do", "reason"),
-        ("Phát hiện", "finding"),
-        ("Minh chứng", "evidence_refs_str"),
-    ]
-
-    _optional_columns: ClassVar[list[tuple[str, str]]] = [
-        ("Points Awarded", "points_awarded"),
-        ("Max Points", "weight_adjusted"),
-        ("Severity", "severity"),
-        ("Priority", "priority"),
-        ("Effort", "effort"),
-        ("Recommendation", "recommendation"),
-        ("Raw Score", "score_breakdown.raw_score"),
-        ("Coverage", "score_breakdown.coverage_factor"),
-        ("Confidence", "score_breakdown.confidence_factor"),
-        ("Score Cap", "score_breakdown.score_cap_applied"),
-        ("Provenance", "provenance.evaluation_source"),
-    ]
-
-    @computed_field
-    @property
-    def total_rows(self) -> int:
-        """Total number of evaluated rows."""
-        return len(self.rows)
-
-    @computed_field
-    @property
-    def pass_count(self) -> int:
-        """Count of rows with PASS status."""
-        return sum(1 for r in self.rows if r.status == RowStatus.PASS)
-
-    @computed_field
-    @property
-    def partial_count(self) -> int:
-        """Count of rows with PARTIAL status."""
-        return sum(1 for r in self.rows if r.status == RowStatus.PARTIAL)
-
-    @computed_field
-    @property
-    def fail_count(self) -> int:
-        """Count of rows with FAIL status."""
-        return sum(1 for r in self.rows if r.status == RowStatus.FAIL)
-
-    @computed_field
-    @property
-    def na_count(self) -> int:
-        """Count of rows with N/A status."""
-        return sum(1 for r in self.rows if r.status == RowStatus.NA)
-
-    @computed_field
-    @property
-    def error_count(self) -> int:
-        """Count of rows with ERROR status."""
-        return sum(1 for r in self.rows if r.status == RowStatus.ERROR)
-
-    @computed_field
-    @property
-    def overall_score(self) -> float:
-        """Weighted average score of applicable rows."""
-        applicable = [r for r in self.rows if r.status not in (RowStatus.NA, RowStatus.ERROR)]
-        if not applicable:
-            return 0.0
-        total_weight = sum(r.weight_adjusted for r in applicable)
-        if total_weight <= 0:
-            return 0.0
-        weighted_sum = sum(r.score_percent * r.weight_adjusted for r in applicable)
-        return weighted_sum / total_weight
-
-    @computed_field
-    @property
-    def overall_score_1_5(self) -> float:
-        """Overall score on 1-5 scale."""
-        pct = self.overall_score
-        return 1 + (pct / 100.0) * 4  # Maps 0-100 to 1-5
-
-    def validate_row_count(self) -> bool:
-        """Validate that evaluated rows match template row count."""
-        return len(self.rows) == self.template_row_count
-
-    def get_rows_by_status(self, status: RowStatus) -> list[RowEvaluation]:
-        """Get all rows with a specific status."""
-        return [r for r in self.rows if r.status == status]
-
-    def get_failed_rows(self) -> list[RowEvaluation]:
-        """Get all rows that need attention (FAIL or PARTIAL)."""
-        return [r for r in self.rows if r.status in (RowStatus.FAIL, RowStatus.PARTIAL)]
-
-    def get_top_findings(
-        self,
-        limit: int = 10,
-        *,
-        include_partial: bool = True,
-    ) -> list[RowEvaluation]:
-        """Get top findings sorted by severity and score.
-
-        Args:
-            limit: Maximum number of findings to return.
-            include_partial: Whether to include PARTIAL status rows.
-
-        Returns:
-            List of RowEvaluation sorted by severity (FAIL first, then lowest score).
-        """
-        statuses = {RowStatus.FAIL}
-        if include_partial:
-            statuses.add(RowStatus.PARTIAL)
-
-        filtered = [r for r in self.rows if r.status in statuses]
-
-        # Sort by status (FAIL before PARTIAL), then by score ascending
-        sorted_rows = sorted(
-            filtered,
-            key=lambda r: (0 if r.status == RowStatus.FAIL else 1, r.score_percent),
-        )
-
-        return sorted_rows[:limit]
-
-    def get_section_summary(self) -> dict[str, dict[str, Any]]:
-        """Get summary statistics grouped by section.
-
-        Returns:
-            Dict mapping section_id to summary statistics.
-        """
-        sections: dict[str, dict[str, Any]] = {}
-
-        for row in self.rows:
-            sid = row.section_id or "default"
-            if sid not in sections:
-                sections[sid] = {
-                    "section_id": sid,
-                    "total_rows": 0,
-                    "pass_count": 0,
-                    "partial_count": 0,
-                    "fail_count": 0,
-                    "na_count": 0,
-                    "error_count": 0,
-                    "total_weight": 0.0,
-                    "weighted_score": 0.0,
-                }
-
-            sections[sid]["total_rows"] += 1
-            status_key = f"{row.status.value.lower().replace('/', '_')}_count"
-            if status_key in sections[sid]:
-                sections[sid][status_key] += 1
-
-            if row.status not in (RowStatus.NA, RowStatus.ERROR):
-                sections[sid]["total_weight"] += row.weight_adjusted
-                sections[sid]["weighted_score"] += row.score_percent * row.weight_adjusted
-
-        # Compute section scores
-        for _sid, data in sections.items():
-            if data["total_weight"] > 0:
-                data["score_percentage"] = data["weighted_score"] / data["total_weight"]
-            else:
-                data["score_percentage"] = 0.0
-
-        return sections
-
-
-# Convenience type aliases
-ChecklistRow = RowEvaluation
-ChecklistArtifact = AuditChecklist