valid_audit.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tools/valid_audit.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/test_valid_audit.py"
"""
V-A-L-I-D — Verified Against Live Implementation Details.
 
Purpose
-------
The committed, CI-gated claim-vs-code audit for the registry spec
([OP-6], REGISTRY_SOURCE_AND_STORAGE_SPEC_V0_24.md §0.3 as amended by
[OP-8] + erratum). It keeps every present-tense, code-facing current-state
claim in the governed docs honest by construction: each tagged claim binds
to a committed receipt whose per-site code fingerprints must re-locate in
the live tree and whose claim text must still be verbatim-present at its tag.
 
Responsibilities
----------------
- Parse the committed receipts JSON (the system-of-record) through a
  pydantic-strict schema and check it agrees with the rendered markdown view.
- Enforce the tag<->receipt bijection (both-ways orphan check).
- Re-locate every `resolved_code_sites` fingerprint (hint range, then a
  sliding same-line-count window): 0 = drift (fail), 1 = mechanical
  relocation (reported, non-fatal in check mode), >=2 = ambiguous (fail).
- Assert each receipt's `claim_text` is verbatim-present at its tag; report a
  stale `spec_line` as a non-fatal mechanical provenance update.
- Scan the governed docs for untagged current-state trigger lines
  (fence/comment-aware) against `tools/valid_audit_lexicon.txt`, honouring
  token-scoped inline `@claim-exempt` waivers.
- Fail closed on any `DISPUTED` receipt unless `--allow-disputed` (a
  pre-flip-only relaxation that touches ONLY the `DISPUTED` gate).
- refresh mode rewrites mechanical relocations / stale `spec_line`s (and
  regenerates the markdown view) after a human re-verifies real drift.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- check mode is read-only and MUST NOT mutate the receipts file.
- Exit 0 clean (a reported pending relocation / stale spec_line is NOT a
  violation), 1 audit violations, 2 usage/config error.
- No `oc_chat` imports (never import the package under development from a
  tools/-launched script); stdlib + pydantic + oc_diagnostics only.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- pydantic (strict receipt schema at the audit boundary)
- argparse (the --check, --refresh and --refresh-relocations modes and their options)
- hashlib (SHA-256 code and claim fingerprints)
- json (reads the receipts file and writes its canonical JSON and the --json report)
- re (the claim tag and waiver patterns and the lexicon trigger patterns)
- pathlib (Path - the audit root and the governed doc, receipt and code site paths)
"""
from __future__ import annotations
 
import argparse
import hashlib
import json
import re
import sys
from pathlib import Path
from typing import Literal
 
from oc_diagnostics import _dbg
from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
_dbg("OC_CHAT.MAIN", "module", "valid_audit loaded", 4)
 
# --------------------------------------------------------------------------
# Configuration — paths are repo-root-relative so a fixture tree under
# `--root` is audited identically to the live tree.
# --------------------------------------------------------------------------
GOVERNED_DOCS = (
    # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
    "oc_chat/docs/architecture/orchestration/REGISTRY_SOURCE_AND_STORAGE_SPEC_V0_24.md",
    # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
    "oc_chat/docs/architecture/orchestration/REGISTRY_DATA_MODEL.md",
)
RECEIPTS_JSON = "oc_chat/docs/architecture/orchestration/audits/registry_v0_24_valid_claims.json"
RECEIPTS_MD = "oc_chat/docs/architecture/orchestration/audits/registry_v0_24_valid_claims.md"
LEXICON_FILE = "tools/valid_audit_lexicon.txt"
 
# Fingerprint preimage schema/version tag (a `hash_preimage`-style prefix so a
# preimage-structure change is detectable). Bump only if the preimage changes.
FP_SCHEMA = "vald1"
 
RECEIPTS_SCHEMA_VERSION = 1
 
# Inline markers (HTML comments) in the governed docs.
_TAG_RE = re.compile(r"<!--\s*@claim:\s*(VC-\d{4})\s*-->")
# A waiver may name one or more comma-separated trigger tokens before the
# ` — <reason>` separator, e.g. `<!-- @claim-exempt: landed,code-verified — meta -->`.
# OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
_EXEMPT_RE = re.compile(r"<!--\s*@claim-exempt:\s*([A-Za-z0-9_,-]+?)\s*(?:—|--)\s*.+?-->")
 
 
# --------------------------------------------------------------------------
# Receipt schema (pydantic-strict; the audit boundary, per spec §3.2 ethos)
# --------------------------------------------------------------------------
class CodeSite(BaseModel):
    """One resolved code location backing a claim, with its own fingerprint."""
 
    model_config = ConfigDict(extra="forbid", strict=True)
 
    path: str
    start: int = Field(ge=1)
    end: int = Field(ge=1)
    symbol: str | None = None
    role: Literal["primary", "secondary", "test", "ddl"] = "primary"
    code_fingerprint: str
 
 
class Receipt(BaseModel):
    """A single claim receipt — the full amended spec §0.3 field set."""
 
    model_config = ConfigDict(extra="forbid", strict=True)
 
    claim_id: str = Field(pattern=r"^VC-\d{4}$")
    spec_file: str
    spec_line: int = Field(ge=1)
    claim_text: str = Field(min_length=1)
    claim_kind: Literal[
        "behavior", "schema", "cli", "error-code", "test-surface", "ci-surface"
    ]
    expected_status: Literal["VERIFIED_CURRENT", "TARGET", "DORMANT", "DISPUTED"]
    resolved_code_sites: list[CodeSite] = Field(min_length=1)
    claim_fingerprint: str
    evidence_command_or_test: str
    last_verified_commit: str
    owner: str
    reviewer: str | None = None
    updated_at: str
 
 
class ReceiptFile(BaseModel):
    """The committed receipts artifact (canonical JSON system-of-record)."""
 
    model_config = ConfigDict(extra="forbid", strict=True)
 
    schema_version: int
    claims: list[Receipt]
 
 
# --------------------------------------------------------------------------
# Fingerprinting
# --------------------------------------------------------------------------
def code_fingerprint(lines: list[str], start: int, end: int) -> str:
    """SHA-256 over the newline-normalised bytes of lines[start:end] (1-indexed, inclusive)."""
 
    segment = "\n".join(lines[start - 1 : end])
    digest = hashlib.sha256(segment.encode("utf-8")).hexdigest()
    return f"{FP_SCHEMA}:code:{digest}"
 
 
def claim_fingerprint(claim_text: str) -> str:
    """SHA-256 over the receipt's stored `claim_text` (newline-normalised)."""
 
    normalized = claim_text.replace("\r\n", "\n").replace("\r", "\n")
    digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
    return f"{FP_SCHEMA}:claim:{digest}"
 
 
def relocate_site(lines: list[str], site: CodeSite) -> tuple[str, list[tuple[int, int]]]:
    """Return (status, candidates) for a site fingerprint.
 
    status ∈ {"located", "relocated", "drift", "ambiguous"}. "located" means
    the hinted range still carries the fingerprint (the hint disambiguates even
    if the same bytes recur elsewhere). Otherwise a same-line-count window slides
    over the file: 0 = drift, exactly 1 = relocated, >=2 = ambiguous.
    """
 
    span = site.end - site.start + 1
    if 1 <= site.start <= len(lines) and site.end <= len(lines):
        if code_fingerprint(lines, site.start, site.end) == site.code_fingerprint:
            return ("located", [(site.start, site.end)])
    candidates: list[tuple[int, int]] = []
    for start in range(1, len(lines) - span + 2):
        end = start + span - 1
        if code_fingerprint(lines, start, end) == site.code_fingerprint:
            candidates.append((start, end))
    if not candidates:
        return ("drift", [])
    if len(candidates) == 1:
        return ("relocated", candidates)
    return ("ambiguous", candidates)
 
 
# --------------------------------------------------------------------------
# Governed-doc scanning (tags, waivers, fence/comment-aware trigger lexicon)
# --------------------------------------------------------------------------
class LexiconEntry(BaseModel):
    """One curated trigger token + its compiled-elsewhere pattern string."""
 
    model_config = ConfigDict(extra="forbid", strict=True)
 
    token: str
    pattern: str
 
 
def load_lexicon(root: Path) -> list[LexiconEntry]:
    """Parse `tools/valid_audit_lexicon.txt` (`token :: regex`; `#` comments)."""
 
    path = root / LEXICON_FILE
    entries: list[LexiconEntry] = []
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or "::" not in line:
            continue
        token, pattern = line.split("::", 1)
        entries.append(LexiconEntry(token=token.strip(), pattern=pattern.strip()))
    return entries
 
 
def _strip_code_and_comments(line: str, in_html_comment: bool) -> tuple[str, bool]:
    """Remove inline-code spans and HTML-comment interiors (comment state carries across lines)."""
 
    out: list[str] = []
    i = 0
    n = len(line)
    while i < n:
        if in_html_comment:
            idx = line.find("-->", i)
            if idx == -1:
                return ("".join(out), True)
            i = idx + 3
            in_html_comment = False
            continue
        if line.startswith("<!--", i):
            idx = line.find("-->", i + 4)
            if idx == -1:
                return ("".join(out), True)
            i = idx + 3
            continue
        ch = line[i]
        if ch == "`":
            idx = line.find("`", i + 1)
            if idx == -1:
                out.append(ch)
                i += 1
                continue
            i = idx + 1
            continue
        out.append(ch)
        i += 1
    return ("".join(out), in_html_comment)
 
 
def find_tags(lines: list[str]) -> dict[str, int]:
    """Map each `@claim: <ID>` to its 1-indexed line (last wins on a dup — flagged elsewhere)."""
 
    tags: dict[str, int] = {}
    for idx, line in enumerate(lines, start=1):
        for match in _TAG_RE.finditer(line):
            tags.setdefault(match.group(1), idx)
    return tags
 
 
def find_all_tag_ids(lines: list[str]) -> list[str]:
    """Every `@claim: <ID>` occurrence in order (to detect duplicate tags)."""
 
    ids: list[str] = []
    for line in lines:
        for match in _TAG_RE.finditer(line):
            ids.append(match.group(1))
    return ids
 
 
def _line_is_tagged(lines: list[str], idx: int) -> bool:
    """A trigger line is tagged if it (or the immediately-preceding line) carries a @claim tag."""
 
    if _TAG_RE.search(lines[idx - 1]):
        return True
    return idx >= 2 and bool(_TAG_RE.search(lines[idx - 2]))
 
 
def _waived_tokens(lines: list[str], idx: int) -> set[str]:
    """Trigger tokens waived on the trigger line or the immediately-preceding line."""
 
    tokens: set[str] = set()
    for line_idx in (idx - 1, idx - 2):
        if line_idx < 0:
            continue
        for match in _EXEMPT_RE.finditer(lines[line_idx]):
            tokens.update(tok.strip() for tok in match.group(1).split(",") if tok.strip())
    return tokens
 
 
def scan_untagged_triggers(
    lines: list[str], lexicon: list[LexiconEntry], rel: str
) -> list[dict[str, object]]:
    """Fence/comment-aware scan for current-state trigger lines lacking a tag or waiver."""
 
    compiled = [(entry, re.compile(entry.pattern)) for entry in lexicon]
    violations: list[dict[str, object]] = []
    in_fence = False
    in_html_comment = False
    for idx, raw in enumerate(lines, start=1):
        stripped = raw.strip()
        if stripped.startswith("```") or stripped.startswith("~~~"):
            in_fence = not in_fence
            continue
        if in_fence:
            continue
        scannable, in_html_comment = _strip_code_and_comments(raw, in_html_comment)
        for entry, pattern in compiled:
            if not pattern.search(scannable):
                continue
            if _line_is_tagged(lines, idx):
                continue
            if entry.token in _waived_tokens(lines, idx):
                continue
            violations.append(
                {
                    "kind": "untagged_trigger",
                    "file": rel,
                    "line": idx,
                    "token": entry.token,
                    "text": raw.strip(),
                }
            )
    return violations
 
 
# --------------------------------------------------------------------------
# Markdown view rendering (deterministic; refresh regenerates, check compares)
# --------------------------------------------------------------------------
def render_markdown(receipt_file: ReceiptFile) -> str:
    """Render the committed markdown view from the JSON system-of-record (deterministic)."""
 
    out: list[str] = []
    out.append("# V-A-L-I-D receipts — registry V0.24 claim-vs-code audit")
    out.append("")
    out.append(
        # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
        "GENERATED from `registry_v0_24_valid_claims.json` by "
        "`python tools/valid_audit.py --refresh-relocations` / `--refresh <id>`; "
        "do not hand-edit. The JSON is the system-of-record."
    )
    out.append("")
    out.append(f"- schema_version: {receipt_file.schema_version}")
    out.append(f"- claim count: {len(receipt_file.claims)}")
    out.append("")
    out.append(
        # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
        "V-A-L-I-D verifies structure + code-site existence + fingerprint drift "
        "(with mechanical relocation), NOT prose semantics — the claim<->code "
        "correspondence is human-verified when a receipt is authored and re-checked "
        "on real drift (spec §0.3 / Design boundaries)."
    )
    out.append("")
    for receipt in sorted(receipt_file.claims, key=lambda r: r.claim_id):
        out.append(f"## {receipt.claim_id} — {receipt.expected_status}")
        out.append("")
        out.append(f"- **claim_kind:** {receipt.claim_kind}")
        out.append(f"- **spec:** `{receipt.spec_file}`:{receipt.spec_line}")
        out.append(f"- **claim_text:** {receipt.claim_text}")
        out.append(f"- **claim_fingerprint:** `{receipt.claim_fingerprint}`")
        out.append("- **resolved_code_sites:**")
        for site in receipt.resolved_code_sites:
            symbol = f" `{site.symbol}`" if site.symbol else ""
            out.append(
                f"  - [{site.role}]{symbol} `{site.path}`:{site.start}-{site.end} "
                f"— `{site.code_fingerprint}`"
            )
        out.append(f"- **evidence:** {receipt.evidence_command_or_test}")
        out.append(f"- **last_verified_commit:** `{receipt.last_verified_commit}`")
        reviewer = receipt.reviewer if receipt.reviewer is not None else "(none — T1)"
        out.append(f"- **owner / reviewer:** {receipt.owner} / {reviewer}")
        out.append(f"- **updated_at:** {receipt.updated_at}")
        out.append("")
    return "\n".join(out).rstrip("\n") + "\n"
 
 
def canonical_json(receipt_file: ReceiptFile) -> str:
    """Canonical JSON (sorted keys, LF, 2-space indent, trailing newline)."""
 
    payload = receipt_file.model_dump(mode="json", exclude_none=False)
    return json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
 
 
# --------------------------------------------------------------------------
# Loading
# --------------------------------------------------------------------------
class ConfigError(Exception):
    """Usage / configuration error → exit 2."""
 
 
def load_receipts(root: Path) -> ReceiptFile:
    """Load + strict-validate the receipts JSON (raises ConfigError on absence/parse/schema)."""
 
    path = root / RECEIPTS_JSON
    if not path.is_file():
        raise ConfigError(f"receipts JSON not found: {RECEIPTS_JSON}")
    try:
        raw = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as exc:
        raise ConfigError(f"receipts JSON is not valid JSON: {exc}") from exc
    try:
        return ReceiptFile.model_validate(raw)
    except ValidationError as exc:
        raise ConfigError(f"receipts JSON fails the strict schema:\n{exc}") from exc
 
 
def _read_lines(root: Path, rel: str) -> list[str]:
    path = root / rel
    if not path.is_file():
        raise ConfigError(f"governed doc not found: {rel}")
    return path.read_text(encoding="utf-8").splitlines()
 
 
# --------------------------------------------------------------------------
# The audit
# --------------------------------------------------------------------------
class AuditResult(BaseModel):
    """Structured audit outcome (also the `--json` payload shape)."""
 
    model_config = ConfigDict(extra="forbid")
 
    ok: bool
    violations: list[dict[str, object]]
    pending_relocations: list[dict[str, object]]
    stale_spec_lines: list[dict[str, object]]
    disputed: list[dict[str, object]]
    allow_disputed: bool
 
 
def run_audit(root: Path, allow_disputed: bool) -> AuditResult:
    """Run the full read-only audit and return a structured result."""
 
    violations: list[dict[str, object]] = []
    pending: list[dict[str, object]] = []
    stale_lines: list[dict[str, object]] = []
    disputed: list[dict[str, object]] = []
 
    receipt_file = load_receipts(root)
    receipts = {r.claim_id: r for r in receipt_file.claims}
 
    # Schema-level: duplicate ids in the JSON itself.
    seen: set[str] = set()
    for receipt in receipt_file.claims:
        if receipt.claim_id in seen:
            violations.append({"kind": "duplicate_receipt_id", "claim_id": receipt.claim_id})
        seen.add(receipt.claim_id)
 
    # JSON <-> markdown agreement.
    md_path = root / RECEIPTS_MD
    if not md_path.is_file():
        raise ConfigError(f"receipts markdown view not found: {RECEIPTS_MD}")
    if md_path.read_text(encoding="utf-8") != render_markdown(receipt_file):
        violations.append({"kind": "json_md_disagreement", "detail": RECEIPTS_MD})
 
    # claim_fingerprint self-consistency.
    for receipt in receipt_file.claims:
        if receipt.claim_fingerprint != claim_fingerprint(receipt.claim_text):
            violations.append(
                {"kind": "claim_fingerprint_mismatch", "claim_id": receipt.claim_id}
            )
 
    # Tag <-> receipt bijection + claim-text presence + spec_line provenance.
    doc_lines: dict[str, list[str]] = {rel: _read_lines(root, rel) for rel in GOVERNED_DOCS}
    all_tag_ids: list[str] = []
    tag_line: dict[tuple[str, str], int] = {}
    for rel, lines in doc_lines.items():
        ids_in_doc = find_all_tag_ids(lines)
        all_tag_ids.extend(ids_in_doc)
        for cid, ln in find_tags(lines).items():
            tag_line[(rel, cid)] = ln
 
    tag_id_set = set(all_tag_ids)
    if len(all_tag_ids) != len(tag_id_set):
        dupes = sorted({cid for cid in all_tag_ids if all_tag_ids.count(cid) > 1})
        violations.append({"kind": "duplicate_tag", "claim_ids": dupes})
 
    for cid in tag_id_set:
        if cid not in receipts:
            violations.append({"kind": "tag_without_receipt", "claim_id": cid})
    for cid in receipts:
        if cid not in tag_id_set:
            violations.append({"kind": "receipt_without_tag", "claim_id": cid})
 
    # Per-receipt checks.
    for receipt in sorted(receipt_file.claims, key=lambda r: r.claim_id):
        cid = receipt.claim_id
        if receipt.expected_status == "DISPUTED":
            disputed.append({"claim_id": cid, "claim_text": receipt.claim_text})
            if not allow_disputed:
                violations.append({"kind": "disputed_receipt", "claim_id": cid})
 
        # claim-text presence + spec_line provenance (against its tag).
        key = (receipt.spec_file, cid)
        if key in tag_line:
            true_line = tag_line[key]
            lines = doc_lines[receipt.spec_file]
            on_line = receipt.claim_text in lines[true_line - 1]
            on_prev = true_line >= 2 and receipt.claim_text in lines[true_line - 2]
            if not (on_line or on_prev):
                violations.append({"kind": "claim_text_drift", "claim_id": cid})
            if receipt.spec_line != true_line:
                stale_lines.append(
                    {"claim_id": cid, "stored": receipt.spec_line, "actual": true_line}
                )
        # (a receipt whose spec_file isn't governed, or whose tag is missing, is
        # already caught by the bijection check above.)
 
        # Code-site relocation.
        for site in receipt.resolved_code_sites:
            code_path = root / site.path
            if not code_path.is_file():
                violations.append(
                    {"kind": "code_site_missing_file", "claim_id": cid, "path": site.path}
                )
                continue
            code_lines = code_path.read_text(encoding="utf-8").splitlines()
            status, candidates = relocate_site(code_lines, site)
            if status == "drift":
                violations.append(
                    {"kind": "code_drift", "claim_id": cid, "path": site.path,
                     "hint": [site.start, site.end]}
                )
            elif status == "ambiguous":
                violations.append(
                    {"kind": "ambiguous_relocation", "claim_id": cid, "path": site.path,
                     "candidates": [list(c) for c in candidates]}
                )
            elif status == "relocated":
                new_start, new_end = candidates[0]
                pending.append(
                    {"claim_id": cid, "path": site.path,
                     "stored": [site.start, site.end], "actual": [new_start, new_end]}
                )
 
    ok = not violations
    return AuditResult(
        ok=ok,
        violations=violations,
        pending_relocations=pending,
        stale_spec_lines=stale_lines,
        disputed=disputed,
        allow_disputed=allow_disputed,
    )
 
 
# --------------------------------------------------------------------------
# Refresh mode (never run in CI)
# --------------------------------------------------------------------------
def refresh(root: Path, only_relocations: bool, claim_id: str | None) -> int:
    """Rewrite mechanical relocations / stale spec_lines + regenerate the markdown view."""
 
    func = "refresh"
    receipt_file = load_receipts(root)
    doc_lines: dict[str, list[str]] = {rel: _read_lines(root, rel) for rel in GOVERNED_DOCS}
    tag_line: dict[tuple[str, str], int] = {}
    for rel, lines in doc_lines.items():
        for cid, ln in find_tags(lines).items():
            tag_line[(rel, cid)] = ln
 
    changed = 0
    for receipt in receipt_file.claims:
        if claim_id is not None and receipt.claim_id != claim_id:
            continue
        key = (receipt.spec_file, receipt.claim_id)
        if key in tag_line and receipt.spec_line != tag_line[key]:
            receipt.spec_line = tag_line[key]
            changed += 1
        for site in receipt.resolved_code_sites:
            code_path = root / site.path
            if not code_path.is_file():
                continue
            code_lines = code_path.read_text(encoding="utf-8").splitlines()
            status, candidates = relocate_site(code_lines, site)
            if status == "relocated":
                site.start, site.end = candidates[0]
                changed += 1
 
    (root / RECEIPTS_JSON).write_text(canonical_json(receipt_file), encoding="utf-8", newline="\n")
    (root / RECEIPTS_MD).write_text(render_markdown(receipt_file), encoding="utf-8", newline="\n")
    _dbg("OC_CHAT.MAIN", func, f"{changed} field(s) rewritten", 2)
    print(f"refresh: {changed} mechanical field(s) rewritten; markdown view regenerated")
    return 0
 
 
# --------------------------------------------------------------------------
# Reporting + CLI
# --------------------------------------------------------------------------
def _format_report(result: AuditResult) -> str:
    lines: list[str] = []
    if result.violations:
        lines.append(f"V-A-L-I-D: {len(result.violations)} violation(s):")
        for v in result.violations:
            lines.append(f"  - {json.dumps(v, sort_keys=True)}")
    else:
        lines.append("V-A-L-I-D: clean (0 violations).")
    if result.disputed:
        state = "reported (relaxed by --allow-disputed)" if result.allow_disputed else "FATAL"
        lines.append(f"DISPUTED rows [{state}]: {len(result.disputed)}")
        for d in result.disputed:
            lines.append(f"  - {d['claim_id']}")
    if result.pending_relocations or result.stale_spec_lines:
        lines.append("Relocations pending (mechanical, non-fatal — run --refresh-relocations):")
        for p in result.pending_relocations:
            lines.append(
                f"  - {p['claim_id']} {p['path']} {p['stored']} -> {p['actual']}"
            )
        for s in result.stale_spec_lines:
            lines.append(
                f"  - {s['claim_id']} spec_line {s['stored']} -> {s['actual']}"
            )
    return "\n".join(lines)
 
 
def check(root: Path, allow_disputed: bool, as_json: bool) -> int:
    """check mode — read-only; the canonical CI/ACs/docs invocation."""
 
    lexicon = load_lexicon(root)
    result = run_audit(root, allow_disputed)
    for rel in GOVERNED_DOCS:
        lines = _read_lines(root, rel)
        result.violations.extend(scan_untagged_triggers(lines, lexicon, rel))
    result.ok = not result.violations
    if as_json:
        print(json.dumps(result.model_dump(), indent=2, sort_keys=True))
    else:
        print(_format_report(result))
    return 0 if result.ok else 1
 
 
def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
        description="V-A-L-I-D claim-vs-code audit for the registry V0.24 spec.",
    )
    parser.add_argument("--check", action="store_true", help="Read-only audit (CI/ACs/docs invocation).")
    parser.add_argument(
        "--allow-disputed",
        action="store_true",
        # OCT-LINT: disable=no_hardcoded_secrets reason="Doc paths, HTML-comment regexes, and markdown-render/help strings are not secrets"
        help="Relax ONLY the DISPUTED gate (pre-flip-only; forbidden after the gate-blocking flip).",
    )
    parser.add_argument("--refresh", metavar="CLAIM_ID", help="Refresh one receipt (after re-verifying real drift).")
    parser.add_argument(
        "--refresh-relocations",
        action="store_true",
        help="Rewrite all mechanical relocations / stale spec_lines + regenerate the markdown view.",
    )
    parser.add_argument("--root", default=None, help="Repo root to audit (default: this tool's repo).")
    parser.add_argument("--json", action="store_true", help="Emit a JSON report (check mode).")
    args = parser.parse_args(argv)
 
    root = Path(args.root).resolve() if args.root else Path(__file__).resolve().parent.parent
 
    modes = [bool(args.check), bool(args.refresh), bool(args.refresh_relocations)]
    if sum(modes) != 1:
        print("usage: exactly one of --check / --refresh <id> / --refresh-relocations", file=sys.stderr)
        return 2
    try:
        if args.check:
            return check(root, args.allow_disputed, args.json)
        if args.refresh_relocations:
            return refresh(root, only_relocations=True, claim_id=None)
        return refresh(root, only_relocations=False, claim_id=args.refresh)
    except ConfigError as exc:
        print(f"config error: {exc}", file=sys.stderr)
        return 2
 
 
if __name__ == "__main__":
    sys.exit(main())