aepkit 0.6.0__py3-none-any.whl

aepkit/lint.py

@@ -0,0 +1,549 @@
+"""Cross-check the document set for the failure modes this protocol names by hand:
+task IDs that exist in one document but not the other, gates with no stated negative
+control, DONE reports with no pasted verify output, work started in a later phase before
+earlier phases are APPROVED, unfilled opportunity/shaping/non-goal fields or open deferred
+items in plan-of-record.md, near-duplicate paragraphs from append-only logging, and an
+annex count that signals an under-verified plan rather than a healthy one.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+REPORT_ID_RE = re.compile(r"\*\*Report:\*\*\s*`?([A-Za-z0-9_.\-]+)`?")
+GUIDE_HEADER_RE = re.compile(r"^###\s+([A-Za-z0-9_.\-]+)\s+[\u2014\u2013\-]\s*(.*)$", re.MULTILINE)
+LOG_HEADER_RE = re.compile(
+    r"^###\s+([A-Za-z0-9_.\-]+)\s+[\u2014\u2013\-]\s+([A-Za-z_]+)\s*$", re.MULTILINE
+)
+GATE_ID_RE = re.compile(r"-G\d+$|^G\d+$", re.IGNORECASE)
+VERIFY_FIELD_RE = re.compile(r"^\*\*Verify output:\*\*", re.MULTILINE)
+NEXT_FIELD_RE = re.compile(r"^\*\*[^*\n]+:\*\*", re.MULTILINE)
+SECTION_END_RE = re.compile(r"^#{1,6}\s|^---\s*$", re.MULTILINE)
+PLACEHOLDER_RE = re.compile(r"<[^>\n]*>")
+# A mention that negates or defers the control ("negative control: n/a", "no negative
+# control needed", "negative control: TBD", "the negative control step was not done")
+# does not count as stating one. This is a wording heuristic, not proof the control ran.
+_DEFERRAL = (
+    r"n/?a|n\.\s?a\.?|none(?:\s+yet)?|tbd|todo|later|pending|skip(?:ped)?|deferred|missing"
+    r"|not\s+(?:yet|needed|required|applicable|done|run|performed|written)"
+    r"|to\s+be\s+(?:written|done|added|decided|determined|defined|confirmed|run)"
+)
+NEGATED_CONTROL_RE = re.compile(
+    r"\b(?:no|without|skip(?:ped)?|omit(?:ted)?)\s+(?:the\s+)?negative\s+control"
+    rf"|negative\s+controls?[^A-Za-z0-9\n]{{0,10}}(?:{_DEFERRAL})\b"
+    rf"|negative\s+controls?\b[^.\n]{{0,40}}\b(?:was|is|were|are)\s+(?:{_DEFERRAL})\b",
+    re.IGNORECASE,
+)
+# Text that only defers ("n/a", "TBD", "none yet") or is only punctuation ("-", "...") is
+# not a stated control or pasted output.
+DEFERRAL_ONLY_RE = re.compile(rf"^[^A-Za-z0-9]*(?:(?:{_DEFERRAL})[^A-Za-z0-9]*)?$", re.IGNORECASE)
+CONTROL_MENTION_RE = re.compile(r"negative\s+controls?", re.IGNORECASE)
+# A stated control says what is broken and what fails: at least a short sentence, with no
+# deferral in it ("will add later", "TBA") and not a bare cross-reference ("see above").
+MIN_CONTROL_WORDS = 4
+DEFERRAL_PHRASE_RE = re.compile(
+    rf"\b(?:{_DEFERRAL}|tba|tbc|tbd|will\s+(?:be\s+)?(?:add|writ|do|defin|document|creat|implement|provid|decid)\w*"
+    r"|see\s+(?:above|below)|to\s+follow|coming\s+soon|planned\s+(?:for|in)|in\s+a\s+later|once\s+\w+\s+(?:is|are|lands?)"
+    r"|next\s+(?:sprint|release|phase|iteration)"
+    r"|no\s+(?:negative\s+)?controls?|omit\w*|could\s*n[o']?t\s+\w+|can\s*n[o']?t\s+be\s+(?:broken|shown|tested)"
+    r"|nothing\s+to\s+(?:show|break|test)|not\s+possible|impossible|unnecessary|unneeded"
+    r"|waiv\w*|out\s+of\s+scope|hypothetical\w*|postpon\w*|would|might|anyway|eventually"
+    r"|could|should|may|maybe|perhaps|probably|presumably|supposedly|hopefully|in\s+theory"
+    r"|(?:remov|disabl|break|chang|delet|revert|bypass|mutat)\w*\s+nothing"
+    r"|do\s+not\s+know|don'?t\s+know)\b",
+    re.IGNORECASE,
+)
+WORD_RE = re.compile(r"[A-Za-z0-9_]+")
+# A stated control names an action that removes the protection or feeds the input it must
+# stop, and a failure it causes. Both are required, so a refusal or a waiver in new words
+# ("waived by the lead", "out of scope") does not read as a control.
+CONTROL_ACTION_RE = re.compile(
+    r"\b(?:remov|revert|delet|disabl|comment\w*\s+out|drop|bypass|flip|mutat|replac|strip|undo"
+    r"|roll\s*back|swap|corrupt|tamper|chang|patch|turn\s+off|unset|send|feed|submit|pass|call"
+    r"|request|post|inject|use|set|break|weaken|loosen|invert|negat|stub|mock"
+    r"|add|insert|introduc|stash)\w*",
+    re.IGNORECASE,
+)
+CONTROL_FAILURE_RE = re.compile(
+    r"\b(?:fail\w*|error\w*|reject\w*|red|non-?zero|exit(?:s|ed)?\s+(?:code\s+)?[1-9]\d*|rais\w*|throw\w*"
+    r"|crash\w*|den(?:y|ies|ied)|block\w*|refus\w*|[45]\d\d|assert\w*|catch\w*|caught|flag\w*|trip\w*)\b",
+    re.IGNORECASE,
+)
+# "nothing fails", "would not fail", "no error": the failure is negated.
+NEGATED_FAILURE_RE = re.compile(
+    r"\b(?:not|never|no|nothing|without|n't)\s+(?:\w+\s+){0,2}(?:fail|error|reject|rais|throw|crash|block)\w*",
+    re.IGNORECASE,
+)
+# "did not remove", "never disabled": the action itself is negated, so it was not done.
+NEGATED_ACTION_RE = re.compile(
+    r"\b(?:not|never|no|without|n't|did\s+not|didn'?t)\s+(?:\w+\s+){0,3}"
+    r"(?:remov|revert|delet|disabl|drop|bypass|flip|mutat|replac|strip|undo"
+    r"|swap|corrupt|tamper|chang|patch|unset|send|feed|submit|pass|call"
+    r"|request|post|inject|break|weaken|loosen|invert|negat|stub|mock"
+    r"|add|insert|introduc|stash)\w*",
+    re.IGNORECASE,
+)
+# Where a stated control ends: the next bold field, heading, or blank line.
+CONTROL_END_RE = re.compile(r"\n\s*(?:[-*]\s+)?(?:\*\*|__)[^*_\n]+:|\n#|\n\s*\n")
+# A task or gate ID contains a digit (P0-T1, T3, G2); headings like "### Notes — x" are not tasks.
+TASK_ID_RE = re.compile(r"\d")
+FENCE_LINE_RE = re.compile(r"^\s*(```|~~~)[\w-]*\s*$", re.MULTILINE)
+# Pasted output is a fenced block with something in it; prose about the output is a claim.
+FENCED_BLOCK_RE = re.compile(r"^\s*(```|~~~)[\w-]*\s*\n(.*?)^\s*\1\s*$", re.MULTILINE | re.DOTALL)
+PHASE_RE = re.compile(r"^P(\d+)-", re.IGNORECASE)
+DEFERRED_PHASE_RE = re.compile(r"\b(?:P|Phase\s*)(\d+)\b", re.IGNORECASE)
+VERDICTS = {"APPROVED", "CONDITIONAL", "REJECTED"}
+DETERMINISTIC_BYPASS_RE = re.compile(
+    r"\b(?:n/?a|not\s+applicable)\b[^\n]{0,60}\b"
+    r"(?:deterministic|bug\s*fix|fix|compliance|security|patch|migration)\b",
+    re.IGNORECASE,
+)
+PLAN_DEFERRAL_RE = re.compile(
+    r"^\s*(?:n/?a|n\.\s?a\.?|none(?:\s+yet)?|tbd|todo|tba|tbc|later|pending|skip(?:ped)?|deferred)\s*$"
+    r"|\b(?:tbd|todo|tba|tbc|to\s+be\s+(?:written|done|added|decided|determined|defined|confirmed))\b",
+    re.IGNORECASE,
+)
+PLAN_ALWAYS_REQUIRED: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("Target outcome", re.compile(r"\*\*Target outcome:\*\*", re.IGNORECASE)),
+    ("Problem / friction", re.compile(r"\*\*Problem\s*/\s*friction:\*\*", re.IGNORECASE)),
+    ("Cost of doing nothing", re.compile(r"\*\*Cost of doing nothing:\*\*", re.IGNORECASE)),
+    ("Explicit non-goals", re.compile(r"\*\*Explicit non-goals:\*\*", re.IGNORECASE)),
+)
+PLAN_SHAPING_OPTIONS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("Option A", re.compile(r"\*\*Option A(?:\s*\([^*\n]*\))?:\*\*", re.IGNORECASE)),
+    ("Option B", re.compile(r"\*\*Option B(?:\s*\([^*\n]*\))?:\*\*", re.IGNORECASE)),
+    ("Option C", re.compile(r"\*\*Option C(?:\s*\([^*\n]*\))?:\*\*", re.IGNORECASE)),
+)
+PLAN_SELECTED_OPTION_RE = re.compile(
+    r"\*\*Selected option\s*(?:&|and)\s*rationale:\*\*", re.IGNORECASE
+)
+PLAN_RISKIEST_ASSUMPTION_RE = re.compile(
+    r"\*\*Riskiest assumption(?:\s*(?:&|and)\s*first-phase validation)?:\*\*", re.IGNORECASE
+)
+
+MIN_DUP_LEN = 120
+DEFAULT_ANNEX_THRESHOLD = 6
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def _guide_sections(text: str) -> list[tuple[str, str, str]]:
+    """Return (id, title, body) for every '### ID — title' section."""
+    matches = list(GUIDE_HEADER_RE.finditer(text))
+    sections = []
+    for i, m in enumerate(matches):
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        sections.append((m.group(1), m.group(2).strip(), text[start:end]))
+    return sections
+
+
+def _states_negative_control(body: str) -> bool:
+    """True when a mention of the negative control is followed by what it is: a sentence that
+    names the action that removes the protection (or feeds the input it must stop) and the
+    failure it causes, with no deferral or negation. This is a wording heuristic; the Auditor
+    still re-runs the control."""
+    if NEGATED_CONTROL_RE.search(body):
+        return False
+    for mention in CONTROL_MENTION_RE.finditer(body):
+        rest = body[mention.end() :]
+        end = CONTROL_END_RE.search(rest)
+        text = PLACEHOLDER_RE.sub("", rest[: end.start()] if end else rest).strip()
+        if (
+            len(WORD_RE.findall(text)) >= MIN_CONTROL_WORDS
+            and not DEFERRAL_PHRASE_RE.search(text)
+            and CONTROL_ACTION_RE.search(text)
+            and CONTROL_FAILURE_RE.search(text)
+            and not NEGATED_FAILURE_RE.search(text)
+            and not NEGATED_ACTION_RE.search(text)
+        ):
+            return True
+    return False
+
+
+def _is_gate(task_id: str, title: str) -> bool:
+    return bool(GATE_ID_RE.search(task_id)) or "gate" in title.lower()
+
+
+def _done_without_evidence(log_text: str) -> list[str]:
+    """IDs reported DONE whose **Verify output:** field is missing, empty, or only defers.
+
+    The protocol records such a report as FAILED: evidence is pasted command output,
+    not a claim that the command passed. Output counts only inside a fenced code block,
+    so prose such as "all tests pass" or "looks correct" is not evidence; template
+    placeholders, empty fences, and a lone deferral such as "n/a" or "TBD" are not either.
+    """
+    missing = []
+    for m in LOG_HEADER_RE.finditer(log_text):
+        if m.group(2).upper() != "DONE":
+            continue
+        rest = log_text[m.end() :]
+        end = SECTION_END_RE.search(rest)
+        body = rest[: end.start()] if end else rest
+        field = VERIFY_FIELD_RE.search(body)
+        if not field:
+            missing.append(m.group(1))
+            continue
+        after = body[field.end() :]
+        nxt = NEXT_FIELD_RE.search(after)
+        evidence = after[: nxt.start()] if nxt else after
+        blocks = [
+            PLACEHOLDER_RE.sub("", b.group(2)).strip() for b in FENCED_BLOCK_RE.finditer(evidence)
+        ]
+        if not any(b and not DEFERRAL_ONLY_RE.match(b) for b in blocks):
+            missing.append(m.group(1))
+    return missing
+
+
+def _phase_order_violations(guide_text: str, log_text: str) -> list[str]:
+    """IDs reported DONE in a phase that started before every earlier phase was APPROVED."""
+    from .status import _board_verdicts
+
+    ids = [task_id for task_id, _, _ in _guide_sections(guide_text) if TASK_ID_RE.search(task_id)]
+    verdicts = {k: v for k, v in _board_verdicts(log_text).items() if v in VERDICTS}
+    reports: dict[str, str] = {}
+    for m in LOG_HEADER_RE.finditer(log_text):
+        task_id, value = m.group(1), m.group(2).upper()
+        ids.append(task_id)
+        if value in VERDICTS:
+            verdicts.setdefault(task_id, value)
+        else:
+            reports[task_id] = value
+    phases: defaultdict[int, set[str]] = defaultdict(set)
+    for task_id in ids:
+        found = PHASE_RE.match(task_id)
+        if found:
+            phases[int(found.group(1))].add(task_id)
+    violations = []
+    for phase, members in sorted(phases.items()):
+        earlier = {i for p, m in phases.items() if p < phase for i in m}
+        if any(verdicts.get(i) != "APPROVED" for i in earlier):
+            violations += sorted(i for i in members if reports.get(i) == "DONE" or i in verdicts)
+    return violations
+
+
+HEADER_LINE_RE = re.compile(r"^###\s+.*$", re.MULTILINE)
+
+
+def _duplicate_paragraphs(text: str) -> list[tuple[str, int]]:
+    paragraphs = re.split(r"\n\s*\n", text)
+    stripped = [HEADER_LINE_RE.sub("", p) for p in paragraphs]
+    normalized = [re.sub(r"\s+", " ", p).strip() for p in stripped]
+    normalized = [p for p in normalized if len(p) >= MIN_DUP_LEN]
+    counts = Counter(normalized)
+    return [(p, n) for p, n in counts.items() if n > 1]
+
+
+def _extract_plan_field(plan_text: str, pattern: re.Pattern[str]) -> str | None:
+    match = pattern.search(plan_text)
+    if not match:
+        return None
+    rest = plan_text[match.end() :]
+    end = CONTROL_END_RE.search(rest)
+    raw = rest[: end.start()] if end else rest
+    return PLACEHOLDER_RE.sub("", raw).strip()
+
+
+def _is_filled_plan_value(value: str | None) -> bool:
+    if not value:
+        return False
+    if PLAN_DEFERRAL_RE.search(value) or DEFERRAL_ONLY_RE.match(value):
+        return False
+    return len(WORD_RE.findall(value)) >= 2
+
+
+def _plan_gaps(plan_text: str) -> list[str]:
+    """Return missing or unfilled opportunity/shaping/non-goal fields in plan-of-record.md."""
+    gaps: list[str] = []
+    for label, pattern in PLAN_ALWAYS_REQUIRED:
+        val = _extract_plan_field(plan_text, pattern)
+        if not _is_filled_plan_value(val):
+            gaps.append(label)
+
+    selected = _extract_plan_field(plan_text, PLAN_SELECTED_OPTION_RE)
+    is_bypass = bool(selected and DETERMINISTIC_BYPASS_RE.search(selected))
+    if not is_bypass and not _is_filled_plan_value(selected):
+        gaps.append("Selected option & rationale (or state 'N/A (Deterministic Fix/Compliance)')")
+
+    riskiest = _extract_plan_field(plan_text, PLAN_RISKIEST_ASSUMPTION_RE)
+    if not (
+        (riskiest and DETERMINISTIC_BYPASS_RE.search(riskiest)) or _is_filled_plan_value(riskiest)
+    ):
+        gaps.append(
+            "Riskiest assumption & first-phase validation "
+            "(or state 'N/A (Deterministic Fix/Compliance)')"
+        )
+
+    if not is_bypass:
+        for opt_label, opt_pattern in PLAN_SHAPING_OPTIONS:
+            opt_val = _extract_plan_field(plan_text, opt_pattern)
+            if not _is_filled_plan_value(opt_val):
+                gaps.append(opt_label)
+
+    return gaps
+
+
+def _open_deferred_items(plan_text: str, known_ids: set[str], log_text: str) -> list[str]:
+    """Flag deferred-ledger rows whose closing task ID does not exist or remains empty when
+    its target phase is being closed."""
+    from .status import _board_verdicts, _cells
+
+    verdicts = {k: v for k, v in _board_verdicts(log_text).items() if v in VERDICTS}
+    reports: dict[str, str] = {}
+    for m in LOG_HEADER_RE.finditer(log_text):
+        tid, val = m.group(1), m.group(2).upper()
+        if val in VERDICTS:
+            verdicts.setdefault(tid, val)
+        else:
+            reports[tid] = val
+
+    closing_phases: set[int] = set()
+    phase_members: defaultdict[int, set[str]] = defaultdict(set)
+    for tid in known_ids | set(verdicts) | set(reports):
+        pm = PHASE_RE.match(tid)
+        if not pm:
+            continue
+        pnum = int(pm.group(1))
+        phase_members[pnum].add(tid)
+        if GATE_ID_RE.search(tid) and (
+            reports.get(tid) == "DONE" or verdicts.get(tid) == "APPROVED"
+        ):
+            closing_phases.add(pnum)
+    for pnum, members in phase_members.items():
+        if members and all(
+            reports.get(i) == "DONE" or verdicts.get(i) == "APPROVED" for i in members
+        ):
+            closing_phases.add(pnum)
+
+    issues: list[str] = []
+    lines = plan_text.splitlines()
+    for i, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        header = [c.lower() for c in _cells(line)]
+        if "id" not in header or "deferred to" not in header or "closed by" not in header:
+            continue
+        id_col = header.index("id")
+        def_col = header.index("deferred to")
+        closed_col = header.index("closed by")
+        for row in lines[i + 1 :]:
+            if not row.lstrip().startswith("|"):
+                break
+            cells = _cells(row)
+            if len(cells) <= max(id_col, def_col, closed_col):
+                continue
+            item_id = PLACEHOLDER_RE.sub("", cells[id_col]).strip()
+            if not item_id or set(item_id) <= set("-: "):
+                continue
+            deferred_to = PLACEHOLDER_RE.sub("", cells[def_col]).strip()
+            closed_by = PLACEHOLDER_RE.sub("", cells[closed_col]).strip()
+            closing_ids = (
+                []
+                if PLAN_DEFERRAL_RE.search(closed_by)
+                else [
+                    tok
+                    for tok in re.findall(r"[A-Za-z0-9_.\-]+", closed_by)
+                    if TASK_ID_RE.search(tok)
+                ]
+            )
+            unknown = [cid for cid in closing_ids if cid not in known_ids]
+            if unknown:
+                issues.append(
+                    f"{item_id} (Closed by {', '.join(unknown)}, which is not in execution-guide.md)"
+                )
+                continue
+            if not closing_ids:
+                pm = DEFERRED_PHASE_RE.search(deferred_to)
+                if pm and int(pm.group(1)) in closing_phases:
+                    issues.append(
+                        f"{item_id} (deferred to Phase {pm.group(1)}, still open in Closed by)"
+                    )
+        break
+    return issues
+
+
+def run(target_dir: str, annex_threshold: int = DEFAULT_ANNEX_THRESHOLD) -> int:
+    target = Path(target_dir)
+    # A missing document is an error, not a clean result: linting nothing proves nothing.
+    missing_docs = [
+        name
+        for name in ("execution-guide.md", "compliance-log.md")
+        if not (target / name).is_file()
+    ]
+    if missing_docs:
+        print(
+            f"error: {target} is missing {', '.join(missing_docs)} (run `aepkit init {target}`).",
+            file=sys.stderr,
+        )
+        return 2
+    guide_text = _read(target / "execution-guide.md")
+    log_text = _read(target / "compliance-log.md")
+
+    problems = 0
+
+    # 1. Every **Report:** ID in the guide should have an entry in the log.
+    guide_ids = REPORT_ID_RE.findall(guide_text)
+    log_ids = {m.group(1) for m in LOG_HEADER_RE.finditer(log_text)}
+
+    missing = [i for i in guide_ids if i not in log_ids]
+    if missing:
+        problems += len(missing)
+        print(
+            f"[missing report] {len(missing)} task(s) in execution-guide.md have no entry in compliance-log.md:"
+        )
+        for i in missing:
+            print(f"  - {i}")
+
+    # 1a. The guide must define tasks, and every task or gate must name its Report ID;
+    #     otherwise the missing-report check above has nothing to compare.
+    task_sections = [
+        (task_id, body)
+        for task_id, _, body in _guide_sections(guide_text)
+        if TASK_ID_RE.search(task_id)
+    ]
+    if not task_sections:
+        problems += 1
+        print("[empty guide] execution-guide.md defines no tasks or gates (### <ID> — <title>).")
+    no_report_line = [task_id for task_id, body in task_sections if not REPORT_ID_RE.search(body)]
+    if no_report_line:
+        problems += len(no_report_line)
+        print(
+            f"[missing report line] {len(no_report_line)} task(s) in execution-guide.md have no **Report:** line:"
+        )
+        for i in no_report_line:
+            print(f"  - {i}")
+
+    # 1b. Every log entry should belong to a task or gate in the guide.
+    known_ids = set(guide_ids) | {task_id for task_id, _, _ in _guide_sections(guide_text)}
+    orphans = sorted(i for i in log_ids if i not in known_ids)
+    if orphans:
+        problems += len(orphans)
+        print(
+            f"[orphan report] {len(orphans)} entry(ies) in compliance-log.md have no task or gate in execution-guide.md:"
+        )
+        for i in orphans:
+            print(f"  - {i}")
+
+    # 2. Gates with no stated negative control. A gate still exactly as scaffolded (its title
+    #    is a template placeholder) and not yet reported DONE is an unwritten gate, not a gap.
+    log_status = {m.group(1): m.group(2).upper() for m in LOG_HEADER_RE.finditer(log_text)}
+    gate_gaps = []
+    for task_id, title, body in _guide_sections(guide_text):
+        unwritten = PLACEHOLDER_RE.fullmatch(title.split(":", 1)[-1].strip()) is not None
+        if unwritten and log_status.get(task_id) != "DONE":
+            continue
+        if _is_gate(task_id, title) and not _states_negative_control(body):
+            gate_gaps.append(task_id)
+    if gate_gaps:
+        problems += len(gate_gaps)
+        print(
+            f"[gate w/o negative control] {len(gate_gaps)} gate(s) don't mention a negative control:"
+        )
+        for i in gate_gaps:
+            print(f"  - {i}")
+
+    # 3. DONE reports with no pasted verify output.
+    unevidenced = _done_without_evidence(log_text)
+    if unevidenced:
+        problems += len(unevidenced)
+        print(
+            f"[done without evidence] {len(unevidenced)} report(s) marked DONE in "
+            "compliance-log.md have no pasted Verify output (the protocol records these as FAILED):"
+        )
+        for i in unevidenced:
+            print(f"  - {i}")
+        print(
+            "  Paste the literal command output under **Verify output:** inside a ``` code "
+            "block; a sentence about the result is not output."
+        )
+
+    # 3a. Work reported in a phase whose predecessors are not all APPROVED.
+    out_of_order = _phase_order_violations(guide_text, log_text)
+    if out_of_order:
+        problems += len(out_of_order)
+        print(
+            f"[phase order] {len(out_of_order)} report(s) in a phase started before every "
+            "earlier phase was APPROVED:"
+        )
+        for i in out_of_order:
+            print(f"  - {i}")
+
+    # 3b. Plan of record: opportunity/shaping/non-goals (once work starts) and deferred items.
+    plan_path = target / "plan-of-record.md"
+    if plan_path.is_file():
+        from .status import _board_verdicts
+
+        plan_text = _read(plan_path)
+        board = _board_verdicts(log_text)
+        work_started = any(
+            v == "DONE" or v in VERDICTS for v in (*log_status.values(), *board.values())
+        )
+        if work_started:
+            plan_gaps = _plan_gaps(plan_text)
+            if plan_gaps:
+                problems += len(plan_gaps)
+                print(
+                    f"[unfilled plan] {len(plan_gaps)} required field(s) in plan-of-record.md "
+                    "are missing, empty, or still placeholders while work is reported DONE/audited:"
+                )
+                for g in plan_gaps:
+                    print(f"  - {g}")
+        deferred_issues = _open_deferred_items(plan_text, known_ids, log_text)
+        if deferred_issues:
+            problems += len(deferred_issues)
+            print(
+                f"[open deferred item] {len(deferred_issues)} row(s) in the deferred items "
+                "ledger of plan-of-record.md are open or reference an unknown task:"
+            )
+            for d in deferred_issues:
+                print(f"  - {d}")
+
+    # 4. Near-duplicate paragraphs in the log (append-only rot).
+    dups = _duplicate_paragraphs(log_text)
+    if dups:
+        problems += len(dups)
+        print(
+            f"[duplicate content] {len(dups)} paragraph(s) repeated verbatim in compliance-log.md:"
+        )
+        for p, n in dups:
+            preview = p[:100] + ("…" if len(p) > 100 else "")
+            print(f"  - x{n}: {preview}")
+
+    # 5. Annex count as a plan-health signal.
+    annex_dir = target / "annexes"
+    if annex_dir.exists():
+        annex_files = [f for f in annex_dir.iterdir() if f.is_file() and f.name != ".gitkeep"]
+        phase_pattern = re.compile(r"^(?:P(\d+)|phase[-_]?(\d+))", re.IGNORECASE)
+        phase_counts: defaultdict[str, int] = defaultdict(int)
+        for f in annex_files:
+            m = phase_pattern.search(f.stem)
+            if m:
+                phase_num = m.group(1) or m.group(2)
+                phase_counts[f"Phase {phase_num}"] += 1
+            else:
+                phase_counts["General"] += 1
+
+        phase_exceeded = {p: c for p, c in phase_counts.items() if c > annex_threshold}
+        if len(annex_files) > annex_threshold or phase_exceeded:
+            problems += 1
+            print(
+                f"[annex count] {len(annex_files)} annexes exceeds the threshold of "
+                f"{annex_threshold}. This usually means a phase's plan was under-verified "
+                f"before work started, not that it hit unusual surprises. Worth naming as a "
+                f"planning finding, not only fixing task by task."
+            )
+            if len(phase_counts) > 1 or (len(phase_counts) == 1 and "General" not in phase_counts):
+                for p_name, count in sorted(phase_counts.items()):
+                    print(f"  - {p_name}: {count} annex(es)")
+
+    if problems == 0:
+        print("clean — no cross-document gaps found.")
+        return 0
+
+    print(f"\n{problems} issue(s) found.")
+    return 1