@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/risk-compliance/compliance-audit/scripts/validate_tracker.py

@@ -0,0 +1,829 @@
+#!/usr/bin/env python3
+"""Validate a compliance audit tracker against its checklist and evidence.
+
+Usage:
+    python3 validate_tracker.py <tracker.md> --checklist <checklist.md> [--evidence DIR] [--json] [--strict]
+
+Checks (Step 9A — structural):
+  1. row_coverage      Every Control ID in checklist scope has exactly one tracker row.
+  2. item_coverage     Every numbered item from the checklist row appears as an "Control N:"
+                       bullet in the row's Observations cell.
+  3. rating_value      Control Effectiveness Rating is one of the four canonical
+                       outcomes: Satisfactory / Improvement Recommended /
+                       Unsatisfactory / N/A.
+  4. rubric_consistency  Effectiveness rating obeys the VARS rubric:
+                       - any mandatory item "Partial" or "Not addressed" => Unsatisfactory
+                       - all mandatory met but a recommended item is missing/partial
+                         (or a mandatory item can be strengthened) => Improvement Recommended
+                       - all items Covered => Satisfactory
+                       - rows rated N/A are exempt (scoping decision, not derivable).
+  5. gap_xref          Each gap referenced in Issue Description by "(Control N)"
+                       or "[Control N: ...]" must correspond to an item marked
+                       "Not addressed" or "Partial" in the same row's Observations
+                       cell. (Recommendations may also reference a "Covered"
+                       mandatory item flagged for strengthening.)
+
+Checks (Step 9B — citation grounding, requires --evidence):
+  6. citation_grounding  For every "Covered in <doc> section <clause>" (or similar)
+                       citation in Observations, the cited clause string must
+                       appear in the corresponding evidence markdown file.
+
+Exit codes:
+  0 = no errors (warnings allowed unless --strict).
+  1 = errors found.
+
+Errors vs warnings:
+  - row_coverage missing rows           -> ERROR
+  - item_coverage missing bullets       -> ERROR
+  - rating_value not in canonical set   -> ERROR
+  - rubric_consistency violations       -> ERROR
+  - gap_xref dangling reference         -> WARNING
+  - citation_grounding missing clause   -> WARNING
+  - citation_grounding missing doc      -> WARNING
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Item-ID normalization
+# ---------------------------------------------------------------------------
+
+_ITEM_ID_PUNCT = re.compile(r"[()\s]+")
+
+
+def normalize_item_id(raw: str) -> str:
+    """Canonicalise an item identifier.
+
+    Examples
+    --------
+    "(2.a)" -> "2.a"
+    "Control 2a" -> "2a"
+    "1.b" -> "1.b"
+    """
+    s = raw.strip().lower()
+    s = re.sub(r"^control\s+", "", s)
+    s = _ITEM_ID_PUNCT.sub("", s)
+    # collapse "2.a" and "2a" to the same canonical form by stripping
+    # the dot when it sits between digit(s) and letter(s)
+    s = re.sub(r"^(\d+)\.([a-z])", r"\1\2", s)
+    s = re.sub(r"^(\d+)\.([ivx]+)$", r"\1.\2", s)  # keep 3.i, 3.ii intact
+    return s
+
+
+def ancestor_canons(raw_id: str) -> set[str]:
+    """Canonical ids of an item plus all its dotted ancestors.
+
+    "6.a.i" -> {"6", "6a", "6a.i"}. Used so a parent bullet (e.g. the tracker
+    listing "Control 6.a") satisfies coverage of its descendant checklist
+    items (6.a.i … 6.a.x), which auditors routinely roll up rather than
+    enumerate leaf-by-leaf.
+    """
+    parts = raw_id.split(".")
+    return {normalize_item_id(".".join(parts[:k])) for k in range(1, len(parts) + 1)}
+
+
+# ---------------------------------------------------------------------------
+# Checklist parsing
+# ---------------------------------------------------------------------------
+
+CONTROL_HEAD_RE = re.compile(r"^###\s+([A-Z][A-Z0-9]*\.C\d+(?:\.\d+)?):\s+(.+?)\s*$")
+SEVERITY_RE = re.compile(r"^-\s+\*\*Severity:\*\*\s*(\w+)", re.IGNORECASE)
+ITEM_LINE_RE = re.compile(
+    r"^\s*-\s+\[\s\]\s+\*\*\(([^)]+)\)\*\*\s*(\(Recommended\)\s*)?(.*)$",
+    re.IGNORECASE,
+)
+SUB_ITEM_LINE_RE = re.compile(
+    r"^\s+-\s+\[\s\]\s+\*\*\(([^)]+)\)\*\*\s*(\(Recommended\)\s*)?(.*)$",
+    re.IGNORECASE,
+)
+
+
+class ChecklistItem:
+    __slots__ = ("id", "canonical", "mandatory", "text")
+
+    def __init__(self, raw_id: str, mandatory: bool, text: str):
+        self.id = raw_id
+        self.canonical = normalize_item_id(raw_id)
+        self.mandatory = mandatory
+        self.text = text
+
+
+class ChecklistControl:
+    __slots__ = ("id", "title", "severity", "items")
+
+    def __init__(self, ctrl_id: str, title: str, severity: str):
+        self.id = ctrl_id
+        self.title = title
+        self.severity = severity.lower()  # "mandatory" or "recommended"
+        self.items: list[ChecklistItem] = []
+
+
+def parse_checklist(path: Path) -> dict[str, ChecklistControl]:
+    controls: dict[str, ChecklistControl] = {}
+    current: Optional[ChecklistControl] = None
+    in_verification = False
+
+    for line in path.read_text(encoding="utf-8").splitlines():
+        m = CONTROL_HEAD_RE.match(line)
+        if m:
+            current = ChecklistControl(m.group(1), m.group(2).strip(), "mandatory")
+            controls[current.id] = current
+            in_verification = False
+            continue
+
+        if current is None:
+            continue
+
+        sev = SEVERITY_RE.match(line)
+        if sev:
+            current.severity = sev.group(1).lower()
+            continue
+
+        if line.strip().startswith("- **Verification:**"):
+            in_verification = True
+            continue
+        if line.strip().startswith("- **Evidence:**") or line.strip().startswith("- **Source:**"):
+            in_verification = False
+            continue
+
+        if not in_verification:
+            continue
+
+        m = ITEM_LINE_RE.match(line) or SUB_ITEM_LINE_RE.match(line)
+        if not m:
+            continue
+        raw_id, recommended_marker, text = m.group(1), m.group(2), m.group(3)
+        # An item is recommended if the control is recommended-severity, the line
+        # carries the (Recommended) marker, or the id is R-prefixed (R1, R1.a, …)
+        # — the last covers sub-items of a recommended parent, which inherit the
+        # prefix but not the inline marker.
+        is_rec_id = normalize_item_id(raw_id).startswith("r")
+        mandatory = current.severity == "mandatory" and not recommended_marker and not is_rec_id
+        current.items.append(ChecklistItem(raw_id, mandatory, text.strip()))
+
+    return controls
+
+
+# ---------------------------------------------------------------------------
+# Tracker parsing
+# ---------------------------------------------------------------------------
+
+TABLE_HEADER_RE = re.compile(r"^\|\s*Control ID\s*\|", re.IGNORECASE)
+SEPARATOR_RE = re.compile(r"^\|[\s\-:|]+\|\s*$")
+PHASES_RE = re.compile(r"\*\*Audit Phases Completed:\*\*\s*(.+?)\s*$", re.IGNORECASE)
+ARCHETYPES_RE = re.compile(r"\*\*Archetypes In Scope:\*\*\s*(.+?)\s*$", re.IGNORECASE)
+SCOPE_RE = re.compile(r"\*\*Scope:\*\*\s*(.+?)\s*$", re.IGNORECASE)
+
+
+class TrackerRow:
+    __slots__ = ("control_id", "title", "archetype", "observations", "issue", "rating", "remediation", "complete_by", "status", "raw")
+
+    def __init__(self, cells: list[str]):
+        # Expected column order: Control ID | Control Title | Archetype | Observations
+        # | Issue Description | Control Effectiveness Rating | Proposed Remediation
+        # | Complete By | Remediation Status
+        # Pad cells defensively in case of trailing-empty stripping.
+        cells = cells + [""] * (9 - len(cells))
+        self.control_id = cells[0].strip()
+        self.title = cells[1].strip()
+        self.archetype = cells[2].strip()
+        self.observations = cells[3]
+        self.issue = cells[4]
+        self.rating = cells[5].strip()
+        self.remediation = cells[6]
+        self.complete_by = cells[7].strip()
+        self.status = cells[8]
+        self.raw = cells
+
+
+def split_table_row(line: str) -> list[str]:
+    """Split a markdown table row on unescaped pipes; ``\\|`` stays inside its cell."""
+    body = line.strip()
+    if body.startswith("|"):
+        body = body[1:]
+    if body.endswith("|") and not body.endswith("\\|"):
+        body = body[:-1]
+    return [c.strip() for c in re.split(r"(?<!\\)\|", body)]
+
+
+def parse_tracker(path: Path) -> tuple[list[str], list[str], Optional[str], list[TrackerRow]]:
+    """Return (phases, archetypes_in_scope, scope_string, rows)."""
+    text = path.read_text(encoding="utf-8")
+    phases: list[str] = []
+    archetypes: list[str] = []
+    scope: Optional[str] = None
+    rows: list[TrackerRow] = []
+
+    in_table = False
+    for line in text.splitlines():
+        m = PHASES_RE.search(line)
+        if m:
+            phase_str = m.group(1).strip().strip("[]")
+            phases = [p.strip() for p in re.split(r"[,;]", phase_str) if p.strip()]
+            continue
+
+        m = ARCHETYPES_RE.search(line)
+        if m:
+            arch_str = m.group(1).strip().strip("[]")
+            # Each token may be annotated, e.g. "AACQ (22 controls)". Keep only the
+            # leading archetype code so it matches a control's "AACQ.Cx.y" prefix;
+            # otherwise the scope set comes out empty and every row is flagged
+            # "outside declared scope" (and the missing-row check is disabled).
+            archetypes = [
+                am.group(1).upper()
+                for a in re.split(r"[,;]", arch_str)
+                if (am := re.match(r"\s*([A-Za-z]+)", a))
+            ]
+            continue
+
+        m = SCOPE_RE.search(line)
+        if m:
+            scope = m.group(1).strip()
+            continue
+
+        if not in_table:
+            if TABLE_HEADER_RE.match(line):
+                in_table = True
+            continue
+
+        if SEPARATOR_RE.match(line):
+            continue
+        if not line.strip().startswith("|"):
+            in_table = False
+            continue
+
+        cells = split_table_row(line)
+        if not cells or not cells[0]:
+            continue
+        rows.append(TrackerRow(cells))
+
+    return phases, archetypes, scope, rows
+
+
+# ---------------------------------------------------------------------------
+# Observation cell parsing
+# ---------------------------------------------------------------------------
+
+BULLET_SPLIT_RE = re.compile(r"\s*<br\s*/?>\s*|\n+", re.IGNORECASE)
+BULLET_PREFIX_RE = re.compile(r"^[\s•\-\*]+")
+OBS_BULLET_RE = re.compile(
+    r"^Control\s+([^:]+?):\s*(.*)$",
+    re.IGNORECASE,
+)
+
+
+class Observation:
+    __slots__ = ("item_id", "canonical", "status", "text")
+
+    def __init__(self, item_id: str, status: str, text: str):
+        self.item_id = item_id
+        self.canonical = normalize_item_id(item_id)
+        self.status = status  # "covered" | "partial" | "not_addressed" | "unknown"
+        self.text = text
+
+
+def classify_status(text: str) -> str:
+    low = text.lower().strip()
+    if "not addressed" in low:
+        return "not_addressed"
+    if low.startswith("partial") or "partial —" in low or "partial -" in low:
+        return "partial"
+    if "covered in" in low or low.startswith("covered"):
+        return "covered"
+    return "unknown"
+
+
+def parse_observations(cell: str) -> list[Observation]:
+    out: list[Observation] = []
+    for chunk in BULLET_SPLIT_RE.split(cell):
+        chunk = BULLET_PREFIX_RE.sub("", chunk).strip()
+        if not chunk:
+            continue
+        m = OBS_BULLET_RE.match(chunk)
+        if not m:
+            continue
+        item_id = m.group(1).strip()
+        text = m.group(2).strip()
+        out.append(Observation(item_id, classify_status(text), text))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Issue Description gap parsing
+# ---------------------------------------------------------------------------
+
+# Matches both the legacy parenthetical form "(Control 1c)" and the enumerated
+# bracket form "[Control 1.a: Partial]" / "[Control R1.a]". The item id is
+# captured up to the first ":" , ")" or "]".
+GAP_REF_RE = re.compile(r"[\[(]\s*Control\s+([^\]:)]+?)\s*[\]:)]", re.IGNORECASE)
+
+# Split point between the two Issue Description groups.
+REC_LABEL_RE = re.compile(r"\*{0,2}\s*recommendations\s*\*{0,2}\s*:", re.IGNORECASE)
+
+
+def extract_gap_refs(cell: str) -> list[str]:
+    return [normalize_item_id(m) for m in GAP_REF_RE.findall(cell)]
+
+
+def split_issue_sections(cell: str) -> tuple[str, str]:
+    """Split an Issue Description cell into (actions_required, recommendations).
+
+    Everything before the "Recommendations:" label is Actions Required; the
+    label and everything after is Recommendations. Works for both the legacy
+    inline format and the enumerated format.
+    """
+    m = REC_LABEL_RE.search(cell)
+    if m:
+        return cell[: m.start()], cell[m.start():]
+    return cell, ""
+
+
+# ---------------------------------------------------------------------------
+# Citation grounding
+# ---------------------------------------------------------------------------
+
+CITATION_RE = re.compile(
+    r"covered in\s+(?P<rest>[^•<]+?)(?=(?:\s+and\s+covered\s+in\s|<br|$|•))",
+    re.IGNORECASE,
+)
+# Clause marker is the word "section" (prescribed). Legacy "§" is still accepted
+# so trackers written under the old convention keep grounding. The "section"
+# form requires a following digit so document names containing the word
+# "section" aren't mistaken for a clause marker.
+CLAUSE_RE = re.compile(r"(?:§\s*|\b[Ss]ection\s+(?=\d))([^\s,;]+)")
+CLAUSE_SPLIT_RE = re.compile(r"§|\b[Ss]ection\s+(?=\d)")
+# Sentence-break markers that end a citation phrase. After the citation
+# "Covered in X section 3.2(a)", any prose introduced by " — ", "; ", " -- ", or
+# ". " (period + space) is descriptive, not part of the citation, and its
+# clause references should NOT be treated as citations to ground.
+CITATION_END_RE = re.compile(r"\s+(?:—|--|;|\.\s)")
+
+
+def list_evidence_files(evidence_dir: Path) -> list[Path]:
+    return sorted([p for p in evidence_dir.rglob("*.md") if p.is_file()])
+
+
+# Trackers cite the client's original filename (``merchant-agreement-v2.4.pdf``);
+# doc-to-md keeps the stem, so the parsed copy is ``merchant-agreement-v2.4.md``.
+ORIGINAL_EXT_RE = re.compile(
+    r"\.(?:pdf|docx?|pptx?|xlsx?|xlsm|csv|txt|rtf|md|html?|png|jpe?g|gif|tiff?|bmp|webp)$",
+    re.IGNORECASE,
+)
+
+
+def normalize_doc_token(s: str) -> str:
+    # \W keeps non-ASCII letters, so a CJK filename still has a token to match.
+    return re.sub(r"[\W_]+", "", s.casefold())
+
+
+class AmbiguousEvidence(Exception):
+    """More than one parsed file shares the cited original filename's stem."""
+
+    def __init__(self, matches: list[Path]):
+        super().__init__(", ".join(str(m) for m in matches))
+        self.matches = matches
+
+
+def find_evidence_file(citation: str, evidence_files: list[Path]) -> Optional[Path]:
+    """Match a doc reference to an evidence file.
+
+    An original filename (with extension) resolves only to the parsed markdown
+    with the same stem: no fuzzy fallback, so ``policy-v2.pdf`` never grounds
+    against ``policy-v2.4.md``. When several files share the stem, the one in a
+    folder named after the extension (``pdf/policy.md``) wins; otherwise
+    ``AmbiguousEvidence`` is raised. A reference without an extension falls
+    back to best-effort fuzzy matching.
+    """
+    cited = citation.strip()
+    ext = ORIGINAL_EXT_RE.search(cited)
+    cite_norm = normalize_doc_token(ORIGINAL_EXT_RE.sub("", cited))
+    if not cite_norm:
+        return None
+    exact = [p for p in evidence_files if normalize_doc_token(p.stem) == cite_norm]
+    if ext:
+        if len(exact) > 1:
+            suffix = ext.group(0)[1:].lower()
+            by_folder = [p for p in exact if p.parent.name.lower() == suffix]
+            if len(by_folder) == 1:
+                return by_folder[0]
+            raise AmbiguousEvidence(exact)
+        return exact[0] if exact else None
+    if exact:
+        return exact[0]
+    best = None
+    best_overlap = 0
+    for path in evidence_files:
+        stem = normalize_doc_token(path.stem)
+        if not stem:
+            continue
+        # use longest common contiguous run as a cheap similarity score
+        overlap = 0
+        for length in range(min(len(stem), len(cite_norm)), 3, -1):
+            for i in range(len(cite_norm) - length + 1):
+                if cite_norm[i : i + length] in stem:
+                    overlap = length
+                    break
+            if overlap:
+                break
+        if overlap > best_overlap:
+            best, best_overlap = path, overlap
+    return best
+
+
+def is_clause_grounded(clause: str, body: str) -> bool:
+    """Return True if the clause string is anchored in the evidence body.
+
+    Tolerates nested clause references — a cited ``section 3.2(a)(i)`` still grounds
+    when the evidence has ``3.2(a)`` as a heading and ``(i)`` listed as a
+    sub-item underneath. This matches how regulatory and contractual prose
+    is actually structured: parent headings carry the section number, child
+    bullets carry only the inner marker.
+    """
+    needle = clause.strip().rstrip(".,;")
+    # "(section 2.1)" captures "2.1)": drop a closing paren with no opener.
+    while needle.endswith(")") and needle.count(")") > needle.count("("):
+        needle = needle[:-1]
+    if not needle:
+        return True
+    if _in_body(needle, body):
+        return True
+    # Walk up by stripping the trailing parenthetical group. If the parent
+    # appears in the body and the leaf (e.g. "(i)") is also somewhere in the
+    # body, accept the citation as grounded.
+    parent_match = re.search(r"\(([^()]*)\)$", needle)
+    if not parent_match:
+        return False
+    parent = needle[: parent_match.start()].rstrip(".")
+    leaf = needle[parent_match.start():]
+    if not parent:
+        return False
+    if _in_body(parent, body) and leaf in body:
+        return True
+    return False
+
+
+def _in_body(clause: str, body: str) -> bool:
+    """Clause appears in the body as a whole number: ``1`` does not match ``2.1`` or ``10``."""
+    lead = r"(?<![\d.])" if clause[:1].isdigit() else ""
+    tail = r"(?![\d])" if clause[-1:].isdigit() else ""
+    return re.search(lead + re.escape(clause) + tail, body) is not None
+
+
+def check_citation(text: str, evidence_files: list[Path]) -> list[tuple[str, str]]:
+    """Return list of (level, message) for citation issues in one bullet text."""
+    issues: list[tuple[str, str]] = []
+    for cite in CITATION_RE.finditer(text):
+        rest = cite.group("rest").strip().rstrip(".,;")
+        # Trim descriptive prose after the citation phrase. Without this, a
+        # bullet like "Covered in MA section 3.2(a) — also see section 99.99 for context"
+        # would falsely flag section 99.99 as a missing citation.
+        end = CITATION_END_RE.search(rest)
+        if end:
+            rest = rest[: end.start()].strip()
+        clauses = CLAUSE_RE.findall(rest)
+        # doc-name fragment is the part before the first clause marker
+        doc_part = CLAUSE_SPLIT_RE.split(rest, maxsplit=1)[0].strip().rstrip("(),. ")
+        try:
+            evidence = find_evidence_file(doc_part, evidence_files)
+        except AmbiguousEvidence as amb:
+            names = ", ".join(f"{p.parent.name}/{p.name}" for p in amb.matches)
+            issues.append(("warning", f"ambiguous document '{doc_part}' matches {names}; put each in a folder named after its extension"))
+            continue
+        if evidence is None:
+            issues.append(("warning", f"no evidence file matches '{doc_part}'"))
+            continue
+        if doc_part and not ORIGINAL_EXT_RE.search(doc_part):
+            issues.append(("warning", f"cites '{doc_part}' without a file extension; cite the original filename"))
+        body = evidence.read_text(encoding="utf-8", errors="replace")
+        for clause in clauses:
+            if not is_clause_grounded(clause, body):
+                # Use the clause as cited, only stripping trailing punctuation
+                # (not closing parens, which are part of identifiers like (i)).
+                shown = clause.strip().rstrip(".,;")
+                issues.append(
+                    (
+                        "warning",
+                        f"clause 'section {shown}' not found in {doc_part or evidence.name}",
+                    )
+                )
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+# Canonical VARS effectiveness outcomes (strict set). N/A covers controls that
+# are not applicable to the entity's scope.
+CANONICAL_RATINGS = {"satisfactory", "improvement recommended", "unsatisfactory", "na"}
+NA_VALUES = {"na", "n/a", "n.a.", "not applicable"}
+
+
+def normalize_rating(raw: str) -> str:
+    """Lower-case + collapse the N/A variants to a single 'na' token."""
+    r = raw.strip().lower()
+    return "na" if r in NA_VALUES else r
+
+
+def derive_expected_rating(observations: list[Observation], items: list[ChecklistItem]) -> Optional[str]:
+    """Apply the VARS effectiveness rubric to predict the rating.
+
+    Rubric (rated prior to remediation):
+      - Unsatisfactory          — any MANDATORY item is not fulfilled, i.e.
+                                   "Partial" or "Not addressed" (these become
+                                   Actions Required).
+      - Improvement Recommended — all mandatory items fulfilled, but at least
+                                   one RECOMMENDED item is missing or partial
+                                   (these become Recommendations).
+      - Satisfactory            — every item (mandatory and recommended) Covered.
+
+    Returns one of "Unsatisfactory", "Improvement Recommended", "Satisfactory",
+    or None if the input is incomplete (missing observations). N/A is never
+    derived — it is a human scoping decision applied to the row directly.
+    """
+    if not items:
+        return None
+
+    observed_by_canon: dict[str, Observation] = {obs.canonical: obs for obs in observations}
+
+    def effective_status(item: ChecklistItem) -> str:
+        """Status of an item, inheriting from the nearest bulleted ancestor.
+
+        Mirrors item_coverage: if a leaf (e.g. 3.b.i) has no direct bullet but
+        its parent (3.b) is bulleted, the leaf takes the parent's status. Returns
+        'missing' when neither the item nor any ancestor is observed.
+        """
+        parts = item.id.split(".")
+        for k in range(len(parts), 0, -1):           # self -> root, most specific first
+            canon = normalize_item_id(".".join(parts[:k]))
+            if canon in observed_by_canon:
+                return observed_by_canon[canon].status
+        return "missing"
+
+    UNMET = ("missing", "not_addressed", "partial")
+
+    # any mandatory item not fully covered (Partial or Not addressed) -> Unsatisfactory
+    if any(item.mandatory and effective_status(item) in UNMET for item in items):
+        return "Unsatisfactory"
+
+    # all mandatory covered; any recommended item missing or partial -> Improvement Recommended
+    if any((not item.mandatory) and effective_status(item) in UNMET for item in items):
+        return "Improvement Recommended"
+
+    return "Satisfactory"
+
+
+def derive_scope(
+    controls: dict[str, ChecklistControl],
+    archetypes: list[str],
+    scope_str: Optional[str],
+    explicit_scope: list[str],
+) -> set[str]:
+    """Determine which Control IDs are in scope for this audit.
+
+    Precedence: --scope CLI flag > tracker "Scope: targeted: ..." > tracker
+    "Archetypes In Scope" > all controls.
+    """
+    if explicit_scope:
+        return {cid for cid in explicit_scope if cid in controls}
+
+    if scope_str and scope_str.lower().startswith("targeted"):
+        # form: "targeted: AACQ.C2.1, AACQ.C14.1"
+        rest = scope_str.split(":", 1)[1] if ":" in scope_str else ""
+        ids = [s.strip() for s in re.split(r"[,;]", rest) if s.strip()]
+        return {cid for cid in ids if cid in controls}
+
+    if archetypes:
+        return {cid for cid in controls if cid.split(".")[0].upper() in archetypes}
+
+    return set(controls.keys())
+
+
+def validate(
+    tracker_path: Path,
+    checklist_path: Path,
+    evidence_dir: Optional[Path],
+    explicit_scope: Optional[list[str]] = None,
+) -> list[dict]:
+    findings: list[dict] = []
+    controls = parse_checklist(checklist_path)
+    phases, archetypes, scope_str, rows = parse_tracker(tracker_path)
+
+    if not rows:
+        findings.append(
+            {
+                "check": "tracker_parse",
+                "level": "error",
+                "control_id": None,
+                "message": "no tracker rows parsed (table not found or empty)",
+            }
+        )
+        return findings
+
+    in_scope = derive_scope(controls, archetypes, scope_str, explicit_scope or [])
+    rows_by_id = {r.control_id: r for r in rows}
+    evidence_files: list[Path] = list_evidence_files(evidence_dir) if evidence_dir else []
+
+    # 1. row_coverage — only check controls in scope
+    for ctrl_id in in_scope:
+        if ctrl_id not in rows_by_id:
+            findings.append(
+                {
+                    "check": "row_coverage",
+                    "level": "error",
+                    "control_id": ctrl_id,
+                    "message": f"checklist control {ctrl_id} has no tracker row",
+                }
+            )
+    for ctrl_id in rows_by_id:
+        if ctrl_id not in controls:
+            findings.append(
+                {
+                    "check": "row_coverage",
+                    "level": "error",
+                    "control_id": ctrl_id,
+                    "message": f"tracker row {ctrl_id} not present in checklist",
+                }
+            )
+        elif ctrl_id not in in_scope:
+            findings.append(
+                {
+                    "check": "row_coverage",
+                    "level": "warning",
+                    "control_id": ctrl_id,
+                    "message": f"tracker row {ctrl_id} present but outside declared scope",
+                }
+            )
+
+    for row in rows:
+        control = controls.get(row.control_id)
+        if control is None:
+            continue
+
+        observations = parse_observations(row.observations)
+        observed = {obs.canonical for obs in observations}
+        item_canon = {item.canonical for item in control.items}
+
+        # 2. item_coverage — a checklist item is covered if it OR any dotted
+        #    ancestor is bulleted (parent bullets roll up their sub-items).
+        for item in control.items:
+            if not (ancestor_canons(item.id) & observed):
+                findings.append(
+                    {
+                        "check": "item_coverage",
+                        "level": "error",
+                        "control_id": row.control_id,
+                        "message": f"item ({item.id}) missing from Observations",
+                    }
+                )
+        for canon in observed - item_canon:
+            findings.append(
+                {
+                    "check": "item_coverage",
+                    "level": "warning",
+                    "control_id": row.control_id,
+                    "message": f"Observations bullet 'Control {canon}' has no matching checklist item",
+                }
+            )
+
+        # 3. rating_value — must be one of the four canonical outcomes
+        rating_norm = normalize_rating(row.rating) if row.rating else ""
+        if row.rating and rating_norm not in CANONICAL_RATINGS:
+            findings.append(
+                {
+                    "check": "rating_value",
+                    "level": "error",
+                    "control_id": row.control_id,
+                    "message": (
+                        f"rating '{row.rating}' is not a canonical outcome "
+                        "(Satisfactory / Improvement Recommended / Unsatisfactory / N/A)"
+                    ),
+                }
+            )
+
+        # clause_marker — the deliverable writes "section 3.2", never "§3.2".
+        for label, cell in (("Observations", row.observations), ("Issue Description", row.issue)):
+            if "§" in cell:
+                findings.append(
+                    {
+                        "check": "clause_marker",
+                        "level": "warning",
+                        "control_id": row.control_id,
+                        "message": f"{label} uses '§'; write 'section <clause>' instead",
+                    }
+                )
+
+        # 4. rubric_consistency — N/A rows are exempt (scoping decision)
+        expected = derive_expected_rating(observations, control.items)
+        if expected and row.rating and rating_norm != "na" and rating_norm != expected.lower():
+            findings.append(
+                {
+                    "check": "rubric_consistency",
+                    "level": "error",
+                    "control_id": row.control_id,
+                    "message": f"rating '{row.rating}' inconsistent with rubric (expected '{expected}')",
+                }
+            )
+
+        # 5. gap_xref — Actions Required gaps must not be "Covered"; Recommendations
+        #    may reference a Covered mandatory item flagged for strengthening.
+        actions_text, rec_text = split_issue_sections(row.issue)
+        for section, refs, enforce_not_covered in (
+            ("Actions Required", extract_gap_refs(actions_text), True),
+            ("Recommendations", extract_gap_refs(rec_text), False),
+        ):
+            for gap_canon in refs:
+                obs = next((o for o in observations if o.canonical == gap_canon), None)
+                if obs is None:
+                    findings.append(
+                        {
+                            "check": "gap_xref",
+                            "level": "warning",
+                            "control_id": row.control_id,
+                            "message": f"{section} references (Control {gap_canon}) which has no Observations bullet",
+                        }
+                    )
+                elif enforce_not_covered and obs.status == "covered":
+                    findings.append(
+                        {
+                            "check": "gap_xref",
+                            "level": "warning",
+                            "control_id": row.control_id,
+                            "message": f"{section} references (Control {gap_canon}) but Observation is 'Covered'",
+                        }
+                    )
+
+        # 6. citation_grounding
+        if evidence_files:
+            for obs in observations:
+                if obs.status not in ("covered", "partial"):
+                    continue
+                for level, msg in check_citation(obs.text, evidence_files):
+                    findings.append(
+                        {
+                            "check": "citation_grounding",
+                            "level": level,
+                            "control_id": row.control_id,
+                            "message": f"({obs.item_id}) {msg}",
+                        }
+                    )
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("tracker", type=Path)
+    ap.add_argument("--checklist", type=Path, required=True)
+    ap.add_argument("--evidence", type=Path, default=None, help="evidence markdown directory (enables citation grounding)")
+    ap.add_argument(
+        "--scope",
+        type=str,
+        default=None,
+        help="comma-separated Control IDs to validate (overrides tracker-declared scope)",
+    )
+    ap.add_argument("--json", action="store_true", help="emit findings as JSON")
+    ap.add_argument("--strict", action="store_true", help="exit non-zero on warnings as well")
+    args = ap.parse_args()
+
+    explicit_scope = (
+        [s.strip() for s in args.scope.split(",") if s.strip()] if args.scope else None
+    )
+    findings = validate(args.tracker, args.checklist, args.evidence, explicit_scope)
+
+    errors = [f for f in findings if f["level"] == "error"]
+    warnings = [f for f in findings if f["level"] == "warning"]
+
+    if args.json:
+        json.dump({"errors": errors, "warnings": warnings}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        for f in findings:
+            tag = "ERROR" if f["level"] == "error" else "WARN"
+            ctl = f["control_id"] or "-"
+            print(f"[{tag}] [{f['check']}] {ctl}: {f['message']}", file=sys.stderr)
+        print(
+            f"\n{len(errors)} error(s), {len(warnings)} warning(s)",
+            file=sys.stderr,
+        )
+
+    if errors or (args.strict and warnings):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())