validate_change_record.py

#!/usr/bin/env python3
"""Fail-closed structural validator for an AI Change Record Markdown artifact."""

from __future__ import annotations

import re
import sys
from pathlib import Path

REQUIRED_HEADINGS = (
    "## 1. Record identity",
    "## 2. Change statement",
    "## 3. Change surface",
    "## 4. Purpose and expected effect",
    "## 5. Boundary and accountable decision",
    "## 6. Evidence and re-check",
    "## 7. Monitoring and pause condition",
    "## 8. Rollback or containment",
    "## 9. Review outcome and open questions",
    "## 10. Retention and correction",
)

REQUIRED_LABELS = (
    "Accountable owner (person or role):",
    "Decision right:",
    "What this record does not authorize:",
    "Re-check to perform:",
    "Pause condition requiring human review:",
    "Rollback path, if reversible:",
    "Correction route:",
)

PROHIBITED = (
    r"\bthis (?:record|template) (?:approves|authorizes|certifies)\b",
    r"\bguarantee(?:s|d)? (?:safety|compliance|security)\b",
    r"\brisk[- ]free\b",
)


def main() -> int:
    if len(sys.argv) != 2:
        print("Usage: validate_change_record.py <record.md>", file=sys.stderr)
        return 2

    record_path = Path(sys.argv[1])
    if not record_path.is_file():
        print(f"FAIL: record not found: {record_path}", file=sys.stderr)
        return 2

    content = record_path.read_text(encoding="utf-8")
    failures: list[str] = []

    for heading in REQUIRED_HEADINGS:
        if heading not in content:
            failures.append(f"missing required heading: {heading}")
    for label in REQUIRED_LABELS:
        if label not in content:
            failures.append(f"missing required field label: {label}")
    for expression in PROHIBITED:
        if re.search(expression, content, flags=re.IGNORECASE):
            failures.append(f"contains prohibited assurance language: /{expression}/")

    if failures:
        print("FAIL: AI Change Record is incomplete or contains prohibited language.")
        for failure in failures:
            print(f"- {failure}")
        return 1

    print("PASS: record contains all required sections, accountability fields, review paths, and no prohibited assurance language.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())