psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/check_v3_7_3_three_layer_citation.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""v3.7.3 Three-Layer Citation lint.
+
+External motivation: Zhao et al. arXiv:2605.07723 (2026-05) — corpus-scale
+audit of LLM hallucinations finds the L3 claim-faithfulness gap unaddressed
+by existing safeguards. v3.7.3 extends Two-Layer Citation Emission with a
+structured anchor marker. Spec:
+  docs/design/2026-05-12-ars-v3.7.3-claim-faithfulness-and-contaminated-source-spec.md
+  §3.1
+
+The lint checks a draft markdown file (e.g., output of synthesis_agent,
+draft_writer_agent, report_compiler_agent) for:
+
+  1. Every `<!--ref:slug-->` is followed by `<!--anchor:<kind>:<value>-->`
+     where <kind> ∈ {quote, page, section, paragraph, none}.
+  2. When <kind> = quote, the URL-decoded value is <=25 words by whitespace
+     split (per shared/references/word_count_conventions.md).
+  3. No `<!--anchor:...-->` marker stands alone without a preceding
+     `<!--ref:slug-->`.
+
+Exit codes:
+  0 - all citations conform
+  1 - one or more violations
+  2 - invocation error
+
+This is a static lint over markdown text. It does NOT verify that the
+anchor value is faithful to the cited source (that is v3.8 L3 audit scope).
+It only verifies the anchor channel exists and is well-formed.
+
+Usage:
+  python scripts/check_v3_7_3_three_layer_citation.py <path-to-draft.md> [...]
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote
+
+REF_PATTERN = re.compile(r"<!--ref:([A-Za-z][A-Za-z0-9_:-]*)\s*([^-]*?)-->")
+ANCHOR_PATTERN = re.compile(
+    r"<!--anchor:(quote|page|section|paragraph|none):([^>]*?)-->"
+)
+ANY_ANCHOR_PATTERN = re.compile(r"<!--anchor:")
+VALID_KINDS = {"quote", "page", "section", "paragraph", "none"}
+QUOTE_WORD_CAP = 25
+
+
+def _strip_fenced_code_blocks(text: str) -> str:
+    """Replace content inside ``` fenced code blocks with blank lines so
+    line numbers in violation messages stay accurate. v3.7.3 F7 closure
+    (gemini review): example ref/anchor markers in spec docs and
+    documentation belong inside code fences and must not be linted as
+    contract violations.
+
+    Handles ``` and ~~~ fences. Indented (4-space) code blocks are not
+    handled — they are rare for Markdown contributors and unlikely to
+    contain HTML comment markers in practice."""
+    out_lines = []
+    in_fence = False
+    fence_char = None
+    for line in text.split("\n"):
+        stripped = line.lstrip()
+        if not in_fence:
+            if stripped.startswith("```") or stripped.startswith("~~~"):
+                in_fence = True
+                fence_char = stripped[:3]
+                out_lines.append(line)  # keep fence opener
+                continue
+            out_lines.append(line)
+        else:
+            if stripped.startswith(fence_char):
+                in_fence = False
+                fence_char = None
+                out_lines.append(line)  # keep fence closer
+                continue
+            # Blank out content inside fence
+            out_lines.append("")
+    return "\n".join(out_lines)
+
+
+def _check_quote_premature_terminator(text: str, path: Path) -> list[str]:
+    """v3.7.3 F10 closure (codex round-3): an unencoded `-->` inside a
+    `quote` anchor value prematurely terminates the HTML comment at the
+    FIRST `-->`, leaving the rest of the intended quote as visible
+    trailing prose. The main ref-anchor regex stops at that first `-->`,
+    so the `"--" in value` check (F1) never sees the dangerous bytes.
+
+    This sentinel scan walks each `<!--anchor:quote:` opening, finds the
+    first `-->`, and checks the bytes between that close and the next
+    `<!--` opening (or end-of-text). If those bytes contain another
+    `-->` token, the original quote was malformed — at least two
+    HTML-comment terminators were emitted into what should have been one
+    URL-encoded payload.
+
+    Walks raw text (NOT stripped text) because the bug is about HTML
+    comment parsing, not about block context."""
+    violations: list[str] = []
+    pos = 0
+    open_marker = "<!--anchor:quote:"
+    while True:
+        start = text.find(open_marker, pos)
+        if start == -1:
+            break
+        # First `-->` after the opening marker — this is where the HTML
+        # parser thinks the comment ends.
+        first_close = text.find("-->", start + len(open_marker))
+        if first_close == -1:
+            # Unterminated comment — separate violation outside this
+            # check's scope. Skip.
+            pos = start + len(open_marker)
+            continue
+        after_close = first_close + 3
+        # Find the next `<!--` opener (or end of text) — that's the
+        # right edge of the trailing-text region to inspect.
+        next_open = text.find("<!--", after_close)
+        if next_open == -1:
+            next_open = len(text)
+        trailing = text[after_close:next_open]
+        # The dangerous signal is finding another `-->` in the trailing
+        # text — that proves the quote value itself contained at least
+        # two HTML-comment terminators, so the user clearly emitted a
+        # raw `-->` inside what should have been a percent-encoded
+        # payload. Legitimate trailing prose between two citations
+        # (whitespace + words + punctuation) does NOT contain `-->`
+        # tokens and must not false-positive.
+        if "-->" in trailing:
+            line_no = text.count("\n", 0, start) + 1
+            violations.append(
+                f"{path}:{line_no}: quote anchor contains unencoded "
+                f"`-->` (HTML comment terminator) inside its value, "
+                f"causing premature comment close at byte {first_close}; "
+                f"v3.7.3 F10 — percent-encode `-` as `%2D` per F1 rule"
+            )
+        pos = after_close
+    return violations
+
+
+def lint_file(path: Path) -> list[str]:
+    """Return a list of violation strings; empty list = PASS."""
+    if not path.exists():
+        return [f"{path}: file does not exist"]
+    raw_text = path.read_text(encoding="utf-8")
+    text = _strip_fenced_code_blocks(raw_text)
+    violations: list[str] = []
+
+    # v3.7.3 F10: sentinel scan for premature HTML comment terminators
+    # inside quote anchor values. Runs BEFORE the main regex match so
+    # malformed quote payloads cannot slip through.
+    violations.extend(_check_quote_premature_terminator(text, path))
+
+    # Find every ref marker; the very next non-whitespace token MUST be an
+    # anchor marker. Allow optional whitespace/newline between ref and
+    # anchor (F2). The ref marker can carry 0-2 status suffix tokens:
+    #   `<!--ref:slug-->`                                  (0 — pre-finalizer)
+    #   `<!--ref:slug ok-->` / `<!--ref:slug LOW-WARN-->`  (1 — post-finalizer v3.7.1)
+    #   `<!--ref:slug ok CONTAMINATED-PREPRINT-->`         (2 — v3.7.3 contamination annotation)
+    # v3.7.3 F8 closure (codex round-2): regex previously allowed only 0-1
+    # tokens, causing finditer to skip 2-token contamination markers
+    # entirely — violations on those refs went undetected.
+    ref_anchor_pattern = re.compile(
+        r"<!--ref:[A-Za-z][A-Za-z0-9_:-]*"
+        r"(?:\s+[\w-]+(?:\+[\w-]+)*){0,2}"
+        r"\s*-->"
+        r"(\s*<!--anchor:([^:>]*):([^>]*?)-->)?"
+    )
+    for m in ref_anchor_pattern.finditer(text):
+        line_no = text.count("\n", 0, m.start()) + 1
+        anchor_match = m.group(1)
+        if anchor_match is None:
+            violations.append(
+                f"{path}:{line_no}: ref marker without trailing anchor "
+                f"(v3.7.3 R-L3-1-A): {m.group(0)!r}"
+            )
+            continue
+        kind = m.group(2)
+        value = m.group(3)
+        if kind not in VALID_KINDS:
+            violations.append(
+                f"{path}:{line_no}: invalid anchor kind {kind!r}; "
+                f"must be one of {sorted(VALID_KINDS)}"
+            )
+            continue
+        # v3.7.3 F9 closure (codex round-2) + F19 closure (codex round-8):
+        # empty value on a non-`none` anchor kind bypasses the NO-LOCATOR
+        # gate while pretending to satisfy the locator contract. Only
+        # `none` may have an empty value; every other kind MUST have a
+        # non-empty locator payload. F19 additionally URL-decodes the
+        # value before the emptiness check, so encoded-whitespace
+        # payloads like `<!--anchor:page:%20%20-->` (which look
+        # non-empty as raw bytes) are correctly identified as empty
+        # after decoding.
+        if kind != "none" and unquote(value).strip() == "":
+            violations.append(
+                f"{path}:{line_no}: empty anchor value for kind "
+                f"{kind!r} (decoded; v3.7.3 F9+F19); only `none` may "
+                f"have an empty value, every other kind requires a "
+                f"non-empty locator payload"
+            )
+            continue
+        if kind == "quote":
+            decoded = unquote(value)
+            word_count = len(decoded.split())
+            if word_count > QUOTE_WORD_CAP:
+                violations.append(
+                    f"{path}:{line_no}: quote anchor exceeds {QUOTE_WORD_CAP} "
+                    f"words by whitespace split (got {word_count}); "
+                    f"v3.7.3 R-L3-1-B — replace with page or section locator"
+                )
+            # Raw `--` in the URL-encoded `quote:` value will prematurely
+            # close the HTML comment in many parsers (gemini review F1).
+            # Standard RFC 3986 percent-encoding does NOT encode `-`; the
+            # v3.7.3 contract additionally requires `-` -> `%2D`. So the
+            # ENCODED value (before unquote) must not contain consecutive
+            # hyphens. Check the raw `value` not `decoded`.
+            if "--" in value:
+                violations.append(
+                    f"{path}:{line_no}: quote anchor contains raw `--` "
+                    f"in URL-encoded value; v3.7.3 F1 requires `-` to be "
+                    f"percent-encoded as `%2D` to prevent premature HTML "
+                    f"comment termination"
+                )
+
+    # Malformed ref markers (any `<!--ref:...-->` that the strict
+    # ref_anchor_pattern did not match) must be reported. v3.7.3 F14
+    # closure (codex round-5): a ref with 3+ status suffix tokens like
+    # `<!--ref:slug ok CONTAMINATED-PREPRINT EXTRA-->` exceeds the
+    # {0,2} cap on the strict pattern and is silently skipped. If it
+    # also has no trailing anchor, the orphan scan has nothing to
+    # report, and the lint declares success on a contract violation.
+    # Fix: broad-scan EVERY `<!--ref:...-->` opening, then check whether
+    # it overlaps with any strict ref_anchor_pattern match. Any ref
+    # opening NOT covered by a strict match is malformed.
+    strict_ref_ranges: list[tuple[int, int]] = []
+    for m in ref_anchor_pattern.finditer(text):
+        # Record the bytes covered by the strict ref portion (up to
+        # the first `-->` of the ref marker). The anchor portion is
+        # optional; we only need the ref range to detect malformed
+        # refs that fall outside it.
+        ref_open = m.start()
+        ref_close = text.find("-->", ref_open) + 3
+        strict_ref_ranges.append((ref_open, ref_close))
+    broad_ref_pattern = re.compile(r"<!--ref:([^>]*?)-->")
+    for m in broad_ref_pattern.finditer(text):
+        start = m.start()
+        covered = any(s <= start < e for (s, e) in strict_ref_ranges)
+        if not covered:
+            line_no = text.count("\n", 0, start) + 1
+            violations.append(
+                f"{path}:{line_no}: malformed ref marker — does not "
+                f"match the v3.7.3 ref shape "
+                f"(slug + 0-2 status tokens): {m.group(0)!r}; "
+                f"v3.7.3 F14 — fix the ref or remove it"
+            )
+
+    # Orphan anchor markers (anchor without a preceding REF marker) are a
+    # violation. v3.7.3 F12 closure (codex round-4): the earlier
+    # implementation used a `(?<!-->)` lookbehind to skip anchors that
+    # immediately followed any HTML comment close, on the assumption
+    # that such anchors were paired with their ref. But `-->` ends ANY
+    # HTML comment, not just refs — so `<!--note--><!--anchor:page:1-->`
+    # or a malformed ref like `<!--ref:slug ok CONTAMINATED-PREPRINT EXTRA-->`
+    # (3 tokens, exceeding the {0,2} cap on the main regex) followed by
+    # an anchor would silently slip through the orphan scan. The fix:
+    # remove the lookbehind, scan EVERY anchor in the file, and inside
+    # the loop verify that the preceding text ends with a well-formed
+    # ref marker per the same regex used by the main ref_anchor_pattern.
+    orphan_pattern = re.compile(
+        r"<!--anchor:([^:>]*):([^>]*?)-->"
+    )
+    for m in orphan_pattern.finditer(text):
+        preceding = text[: m.start()]
+        if not re.search(
+            r"<!--ref:[A-Za-z][A-Za-z0-9_:-]*(?:\s+[\w-]+(?:\+[\w-]+)*){0,2}\s*-->\s*$",
+            preceding,
+        ):
+            line_no = text.count("\n", 0, m.start()) + 1
+            violations.append(
+                f"{path}:{line_no}: orphan anchor marker without preceding "
+                f"ref marker: {m.group(0)!r}"
+            )
+
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        type=Path,
+        help="markdown files to lint",
+    )
+    args = parser.parse_args()
+
+    total_violations: list[str] = []
+    for p in args.paths:
+        total_violations.extend(lint_file(p))
+
+    if total_violations:
+        print("\n".join(total_violations), file=sys.stderr)
+        print(
+            f"\n[v3.7.3 three-layer-citation lint] FAILED "
+            f"({len(total_violations)} violation(s))",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"[v3.7.3 three-layer-citation lint] PASSED "
+        f"({len(args.paths)} file(s) scanned)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/ars/scripts/check_v3_8_annotation_literal_sync.py

@@ -0,0 +1,228 @@
+"""ARS v3.8 §3.6 + §5 — annotation literal sync lint.
+
+The 8-row finalizer matrix in `scripts/claim_audit_finalizer.py` emits five
+HIGH-WARN annotation classes that the formatter's terminal hard gate
+(`academic-paper/agents/formatter_agent.md`) MUST refuse on. The annotation
+literals appear in two places:
+
+1. `scripts/claim_audit_finalizer.py` as `ANNOTATION_HIGH_WARN_*` constants
+   (the finalizer write side — `apply_finalizer` returns these on
+   gate_refuse=True rows).
+2. `academic-paper/agents/formatter_agent.md` REFUSE rules 6-10 (the
+   formatter read side — terminal hard gate scans the draft for these
+   literals before emitting LaTeX/DOCX/PDF).
+
+A literal drift between the two sides silently breaks the gate: if the
+finalizer is renamed from `[HIGH-WARN-CLAIM-NOT-SUPPORTED]` to
+`[HIGH-WARN-CLAIM-UNSUPPORTED]` and the formatter rule 6 is not updated,
+the formatter will pass output that the orchestrator marked HIGH-WARN.
+
+This lint extracts the five `ANNOTATION_HIGH_WARN_*` constant values from
+the finalizer module and asserts each one's bracket prefix appears in the
+formatter agent prompt's REFUSE list. The check uses bracket-prefix
+matching (NOT byte-equivalence on the full annotation) because the
+NEGATIVE-CONSTRAINT-VIOLATION + CONSTRAINT-VIOLATION-UNCITED literals
+carry a runtime `({violated_constraint_id})` interpolation that the
+formatter prose cannot duplicate verbatim — the prefix up to but not
+including the interpolation hole is the contract.
+
+Spec: docs/design/2026-05-15-issue-103-claim-alignment-audit-spec.md §5.
+
+Lint exit codes:
+  0 = pass (all five HIGH-WARN annotation prefixes present in formatter).
+  1 = at least one annotation prefix missing from formatter REFUSE list.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+FINALIZER_MODULE = REPO_ROOT / "scripts" / "claim_audit_finalizer.py"
+FORMATTER_AGENT = REPO_ROOT / "academic-paper" / "agents" / "formatter_agent.md"
+
+_HEADING_AFTER_REFUSE = re.compile(r"(?m)^#{1,2}[ \t]+")
+
+
+def _extract_refuse_block(formatter_text: str) -> str | None:
+    """Return the REFUSE-rules block text, or None if the marker is absent.
+
+    The block opens at the literal marker
+    `**REFUSE to emit final output**` (line bold in `formatter_agent.md`)
+    and ends at the next H2 or H1 heading. Numbered rules 1-10 live inside
+    this block — restricting the lint search here prevents the false PASS
+    where a HIGH-WARN literal appears in background prose / cross-reference
+    but is removed from the gate rules.
+    """
+    marker = "**REFUSE to emit final output**"
+    start = formatter_text.find(marker)
+    if start == -1:
+        return None
+    nm = _HEADING_AFTER_REFUSE.search(formatter_text, start + len(marker))
+    end = nm.start() if nm else len(formatter_text)
+    return formatter_text[start:end]
+
+
+def _annotation_match_token(annotation_literal: str) -> str:
+    """Return the search token the formatter REFUSE block must contain.
+
+    Annotation literals follow three shapes:
+      - Closed plain:        `[HIGH-WARN-CLAIM-NOT-SUPPORTED]`
+      - Interpolated suffix: `[HIGH-WARN-NEGATIVE-CONSTRAINT-VIOLATION ({violated_constraint_id})]`
+      - Em-dash suffix:      `[HIGH-WARN-CLAIM-AUDIT-ANCHORLESS — v3.7.3 R-L3-1-A VIOLATION REACHED AUDIT]`
+
+    Closed plain literals MUST match byte-equivalently including the
+    closing bracket. Step 8 codex R2 P2-1 closure: cutting at `]` left
+    just the prefix without the bracket, so a renamed formatter rule
+    such as `[HIGH-WARN-FABRICATED-REFERENCE-RENAMED]` would still
+    contain `[HIGH-WARN-FABRICATED-REFERENCE` and false-pass the lint
+    while the terminal gate actually scans for the wrong literal.
+
+    Interpolated and em-dash literals match the formatter prose's
+    prefix form (which abbreviates the variable suffix). The search
+    token cuts at the first ` (`, ` —`, or `{` — whichever appears
+    first — and the formatter prose must contain that prefix exactly.
+
+    Decision: closed literals exact, interpolated/em-dash prefix.
+    """
+    # Detect interpolated/em-dash shapes first — these need prefix match.
+    # Use the earliest-occurring terminator (min idx across the three
+    # candidate cuts), not the list-order first hit — `{` and ` (` can
+    # both appear in the same literal and the earlier of the two is
+    # the semantic prefix boundary.
+    earliest = len(annotation_literal)
+    for terminator in ("{", " (", " —"):
+        idx = annotation_literal.find(terminator)
+        if idx != -1 and idx < earliest:
+            earliest = idx
+    if earliest < len(annotation_literal):
+        return annotation_literal[:earliest].rstrip()
+    # Closed plain literal — return the whole thing so the search hit
+    # requires byte-equivalent presence including the `]`.
+    return annotation_literal
+
+
+# Backwards-compat alias for tests written against the prior name.
+_annotation_prefix = _annotation_match_token
+
+
+def _extract_finalizer_high_warn_constants(source: str) -> dict[str, str]:
+    """Parse the finalizer module source for `ANNOTATION_HIGH_WARN_*` constants.
+
+    Imports `scripts.claim_audit_finalizer` and reads each
+    `ANNOTATION_HIGH_WARN_*` attribute via `dir()` + `getattr()`. Reading the
+    runtime module (instead of AST-walking the source) ensures the lint
+    sees the exact string Python sees at import time, including any future
+    derived/templated values.
+
+    Filters to `ANNOTATION_HIGH_WARN_*` names only. The five canonical
+    HIGH-WARN classes are:
+      - ANNOTATION_HIGH_WARN_CLAIM_NOT_SUPPORTED
+      - ANNOTATION_HIGH_WARN_NEGATIVE_CONSTRAINT_VIOLATION
+      - ANNOTATION_HIGH_WARN_FABRICATED_REFERENCE
+      - ANNOTATION_HIGH_WARN_ANCHORLESS
+      - ANNOTATION_HIGH_WARN_CONSTRAINT_VIOLATION_UNCITED
+    """
+    ns: dict[str, object] = {}
+    # The module's import of `INV14_FAULT_CLASS_TAGS` from
+    # `_claim_audit_constants` is part of module init. Use the module
+    # import path so the load succeeds end-to-end.
+    sys.path.insert(0, str(REPO_ROOT))
+    try:
+        from scripts import claim_audit_finalizer  # noqa: F401  (import for side effect: load constants)
+
+        for name in dir(claim_audit_finalizer):
+            if name.startswith("ANNOTATION_HIGH_WARN_"):
+                ns[name] = getattr(claim_audit_finalizer, name)
+    finally:
+        sys.path.remove(str(REPO_ROOT))
+    return {name: value for name, value in ns.items() if isinstance(value, str)}
+
+
+def main() -> int:
+    if not FINALIZER_MODULE.exists():
+        print(f"[v3.8 annotation-sync] FAIL: missing {FINALIZER_MODULE}")
+        return 1
+    if not FORMATTER_AGENT.exists():
+        print(f"[v3.8 annotation-sync] FAIL: missing {FORMATTER_AGENT}")
+        return 1
+
+    constants = _extract_finalizer_high_warn_constants(FINALIZER_MODULE.read_text())
+    if len(constants) != 5:
+        print(
+            f"[v3.8 annotation-sync] FAIL: expected exactly 5 ANNOTATION_HIGH_WARN_* "
+            f"constants in claim_audit_finalizer.py; found {len(constants)}: "
+            f"{sorted(constants)}"
+        )
+        return 1
+
+    formatter_text = FORMATTER_AGENT.read_text()
+    # Restrict the search to the REFUSE-list block so the lint actually
+    # proves the formatter's terminal hard gate refuses on each annotation
+    # — a literal that appears only in background prose or a cross-reference
+    # would not be enforced by the gate. Step 8 codex R1 P3 closure.
+    #
+    # The REFUSE block opens at `**REFUSE to emit final output**` and ends
+    # at the next H2 (`## `) or H1 (`# `) heading; numbered rules 1-10 live
+    # inside that block. If the marker is missing the lint fails closed.
+    refuse_block = _extract_refuse_block(formatter_text)
+    if refuse_block is None:
+        print(
+            f"[v3.8 annotation-sync] FAIL: REFUSE-list marker "
+            f"'**REFUSE to emit final output**' not found in {FORMATTER_AGENT.name}; "
+            f"cannot scope the sync check to the gate rules."
+        )
+        return 1
+
+    missing: list[tuple[str, str]] = []
+    for name, literal in sorted(constants.items()):
+        token = _annotation_match_token(literal)
+        # Closed literals end in `]` and require exact byte-equivalent
+        # substring match (Step 8 codex R2 P2-1 closure).
+        # Interpolated/em-dash tokens (e.g. `[HIGH-WARN-NEGATIVE-
+        # CONSTRAINT-VIOLATION`) require a BOUNDARY character following
+        # the token in the formatter prose — otherwise a rename that
+        # appends text (`[HIGH-WARN-NEGATIVE-CONSTRAINT-VIOLATION-RENAMED`)
+        # would still substring-match the original prefix and false-pass
+        # the lint. Step 8 codex R3 P2 closure: require the token to be
+        # followed by ` ` (space-paren contract per canonical form) or
+        # `]` (no-variable closing bracket) — both are valid boundaries
+        # in the formatter REFUSE prose.
+        if token.endswith("]"):
+            present = token in refuse_block
+        else:
+            # Boundary characters that legitimately follow the token in
+            # formatter prose: ` ` (the canonical ` ({var})]` continuation),
+            # `]` (no-variable closing bracket), `` ` `` (markdown inline
+            # code close — rules 7/9/10 wrap the token in backticks). Any
+            # OTHER following character (a letter, digit, or hyphen)
+            # indicates a rename attack — e.g. `…VIOLATION-RENAMED]`
+            # should NOT satisfy `…VIOLATION` because the boundary is a
+            # hyphen-letter run that extends the identifier.
+            present = any(
+                f"{token}{boundary}" in refuse_block
+                for boundary in (" ", "]", "`")
+            )
+        if not present:
+            missing.append((name, token))
+
+    if missing:
+        print(
+            f"[v3.8 annotation-sync] FAIL: {len(missing)} HIGH-WARN annotation "
+            f"literal(s) missing from formatter REFUSE list (spec §5 + §1 "
+            f"deliverable 5):"
+        )
+        for name, prefix in missing:
+            print(f"  - {name}: prefix {prefix!r} not found in {FORMATTER_AGENT.name}")
+        return 1
+
+    print(
+        f"[v3.8 annotation-sync] PASS: all {len(constants)} HIGH-WARN annotation "
+        f"prefixes present in formatter_agent.md REFUSE list"
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())