@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/compliance/declared.txt

@@ -0,0 +1 @@
+declared

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/decisions/declared.txt

@@ -0,0 +1 @@
+declared

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/index.md

@@ -0,0 +1 @@
+# index

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/operations/declared.txt

@@ -0,0 +1 @@
+declared

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/research/declared.txt

@@ -0,0 +1 @@
+declared

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/stray-root-file.md

@@ -0,0 +1 @@
+stray file

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/totally-made-up/nonsense.md

@@ -0,0 +1 @@
+invented folder

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/test_check.py

@@ -0,0 +1,106 @@
+"""DOC-010 — `docs/` is a closed set.
+
+Ported in the same shape `layout/root_closed_set/test_check.py` uses: ONE
+corpus, and the clean case is the same tree with the two violating entries
+left out of the given set — exactly what a commit touching nothing undeclared
+looks like in production.
+
+This check is not yet wired into `checks/__init__.py` at file-creation time in
+a concurrent close-out session (several other gates are landing in the same
+wave), so — same reasoning as `root_closed_set/test_check.py` — every test
+below calls `DocsClosedSet` directly rather than through `runner.run`/
+`decide`, bypassing row-scope narrowing and registry lookup entirely.
+"""
+
+from __future__ import annotations
+
+from helpers import corpus, corpus_files
+
+from adl_compliance.checks.docs.closed_set import DocsClosedSet
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.finding import Finding
+from adl_compliance.policy.registry import load
+
+CORPUS = corpus("docs", "closed-set")
+ROW = load().by_id("DOC-010")
+
+INVENTED_FOLDER = "docs/totally-made-up/nonsense.md"
+STRAY_FILE = "docs/stray-root-file.md"
+
+
+def clean_set() -> tuple[str, ...]:
+    return tuple(
+        p for p in corpus_files(CORPUS)
+        if p != INVENTED_FOLDER and p != STRAY_FILE
+    )
+
+
+def findings_for(given: tuple[str, ...]) -> tuple[Finding, ...]:
+    ctx = Context(root=CORPUS, row=ROW, inputs={"docs_root": CORPUS / "docs"})
+    return tuple(DocsClosedSet().run(ctx, FileSet(paths=given)))
+
+
+def test_the_premise_holds() -> None:
+    """Asserted, not assumed: a mistyped path would leave both sets identical
+    and every case below would agree for nothing."""
+    all_files = corpus_files(CORPUS)
+    assert INVENTED_FOLDER in all_files
+    assert STRAY_FILE in all_files
+    assert len(clean_set()) == len(all_files) - 2
+
+
+def test_the_closed_set_is_silent() -> None:
+    findings = findings_for(clean_set())
+    assert findings == (), tuple(f.render() for f in findings)
+
+
+def test_an_invented_subfolder_is_reported() -> None:
+    """The gap this gate exists to close: DOC-007 filters to a fixed
+    collection list and skips everything else in silence (verified there by
+    creating `docs/totally-made-up/nonsense.md` and running the full armed
+    set: zero findings). This gate must name the path instead."""
+    findings = findings_for(corpus_files(CORPUS))
+    messages = tuple(f.render() for f in findings)
+    assert any(
+        "docs/totally-made-up" in m and "undeclared docs/ subfolder" in m
+        for m in messages
+    ), messages
+
+
+def test_a_stray_root_file_is_reported() -> None:
+    findings = findings_for(corpus_files(CORPUS))
+    messages = tuple(f.render() for f in findings)
+    assert any(
+        "docs/stray-root-file.md" in m and "undeclared top-level docs/ file" in m
+        for m in messages
+    ), messages
+
+
+def test_every_finding_is_tagged_doc_010() -> None:
+    findings = findings_for(corpus_files(CORPUS))
+    assert findings
+    assert all(f.rule == "DOC-010" for f in findings), tuple(f.render() for f in findings)
+
+
+def test_declared_dirs_and_files_stay_silent() -> None:
+    """Without this, the invented-folder case above also passes against a
+    gate that calls every docs/ entry undeclared."""
+    text = "\n".join(f.render() for f in findings_for(corpus_files(CORPUS)))
+    for entry in ("architecture", "research", "compliance", "operations", "decisions"):
+        assert f"docs/{entry}: undeclared" not in text
+    for entry in ("AGENTS.md", "CLAUDE.md", "index.md"):
+        assert f"docs/{entry}: undeclared" not in text
+
+
+def test_an_empty_set_grades_nothing() -> None:
+    """Every undeclared entry is still on disk. A check that grades only what
+    it is handed must report none of them against an empty given set."""
+    findings = findings_for(())
+    assert findings == ()
+
+
+def test_a_path_outside_docs_is_ignored() -> None:
+    """This gate grades `docs/`'s own shape, not the whole repository root —
+    that is LAY-012's job."""
+    findings = findings_for(("plans/totally-made-up/nonsense.md",))
+    assert findings == ()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/__init__.py

@@ -0,0 +1,7 @@
+"""DOC-002 — `docs.english-only`."""
+
+from __future__ import annotations
+
+from .check import DocsEnglishOnly
+
+__all__ = ["DocsEnglishOnly"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/check.py

@@ -0,0 +1,291 @@
+"""DOC-002 — reject non-English (Han) content and filenames.
+
+Ported from `compliance_new/checks/docs/english-only/check.sh`. That script's
+own header explains its shape: it takes NO arguments, reads exactly the given
+set (`ADL_CHANGED_FILES`, already narrowed by the runner to the row's
+`engine.scope`), performs no walk and no `git` call, and never echoes the
+offending Han text into a report — only where it is, never what it is.
+
+Five finding kinds, unchanged from the shell version:
+
+    "Han filename"           a path component contains a Han character.
+    "raw Han text"           a line contains a raw Han character.
+    "Han Unicode escape"     a line contains a \\u/\\U escape that DECODES to
+                             a Han codepoint (an escape for a non-Han
+                             codepoint, e.g. \\u0041, is not a finding).
+    "Han archive filename"   an OOXML (.docx/.xlsx/.pptx) member name is Han.
+    "unreadable Office archive" / "unreadable archive text"
+                             the zip, or one member's text stream, could not
+                             be read at all — a tool failure reported as a
+                             finding, never silently skipped.
+
+What check.sh needed and this class does not: `rg`/`unzip`/`iconv`/`od`
+subprocess plumbing, its own ZIP central-directory parser (`read_archive_members`,
+`read_le16/32`), and the fork-avoidance batching (`bulk_filename_scan`,
+`classify_matches_awk`) that existed only because bash's own scanning is slow.
+Python's `re` module scans full Unicode codepoints directly (no UTF-16
+surrogate-pair handling needed, unlike the bash/rg version's `\\x{...}`
+escapes for the supplementary-plane ranges), and `zipfile` is the stdlib
+reader for the OOXML archives check.sh hand-parsed a ZIP central directory to
+reach — so the same five findings are produced with much less machinery.
+
+One finding per (path, line, kind), not per matched character or codepoint —
+`graded` de-duplicates on that key exactly as check.sh's own
+`sort | awk '!seen[key]++'` pass did, because the message text never repeats
+the matched value (a two-character Han word on one line is one finding, not
+two).
+
+The row's `engine.scope` (`policy/gate-registry.yaml`, `DOC-002`) excludes
+four specific frontend fixture files — SCOPE, decided by the row, not by this
+check. `scan_excluded`'s three rules below are a different thing: SUBJECT-MATTER
+exclusions this gate owns, because they say what kind of content Han text is
+allowed to be (hidden paths, the one named i18n directory, any locale-named
+data directory), not where in the tree it lives.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from re import Pattern
+from typing import ClassVar
+
+import re as _re
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Finding
+
+
+class DocsEnglishOnly(Check):
+    id: ClassVar[str] = "DOC-002"
+    rule: ClassVar[str] = "DOC-002"
+
+    OFFICE_SUFFIXES: ClassVar[frozenset[str]] = frozenset({".docx", ".pptx", ".xlsx"})
+    ARCHIVE_TEXT_SUFFIXES: ClassVar[frozenset[str]] = frozenset(
+        {".json", ".rels", ".txt", ".xml"}
+    )
+    # A suffix missing from this set is not a small gap: the file's raw bytes get
+    # decoded as UTF-8 and every byte that happens to land in a CJK range becomes
+    # a finding. One absent `.ogg` produced 536 of them, none about documentation.
+    BINARY_SUFFIXES: ClassVar[frozenset[str]] = frozenset(
+        {
+            ".7z", ".avi", ".bin", ".bmp", ".bz2", ".class", ".dmg", ".doc", ".eot",
+            ".exe", ".gif", ".gz", ".heic", ".ico", ".icns", ".jar", ".jpeg", ".jpg",
+            ".lockb", ".mov", ".mp3", ".mp4", ".mpeg", ".oga", ".ogg", ".ogv",
+            ".opus", ".otf", ".pdf", ".png", ".so", ".tar", ".tgz", ".tif", ".tiff",
+            ".ttf", ".wasm", ".wav", ".webm", ".webp", ".woff", ".woff2", ".xls",
+            ".zip",
+        }
+    )
+    ARCHIVE_THEME_PREFIXES: ClassVar[tuple[str, ...]] = (
+        "xl/theme/", "word/theme/", "ppt/theme/",
+    )
+
+    # Han/CJK-ideograph codepoint ranges: CJK Unified (+ Extension A), CJK
+    # Compatibility Ideographs, and Extensions B-G in the supplementary planes
+    # — the same set check.sh's HAN_CLASS/is_han_codepoint covered.
+    HAN_RANGES: ClassVar[tuple[tuple[int, int], ...]] = (
+        (0x3400, 0x4DBF),
+        (0x4E00, 0x9FFF),
+        (0xF900, 0xFAFF),
+        (0x20000, 0x2A6DF),
+        (0x2A700, 0x2B73F),
+        (0x2B740, 0x2B81F),
+        (0x2B820, 0x2CEAF),
+        (0x2CEB0, 0x2EBEF),
+        (0x30000, 0x3134F),
+    )
+
+    HAN_PATTERN: ClassVar[Pattern[str]] = _re.compile(
+        "[" + "".join(f"{chr(lo)}-{chr(hi)}" for lo, hi in HAN_RANGES) + "]"
+    )
+    """Built from actual embedded Unicode characters, not `\\uXXXX` escapes in
+    the pattern text — `re` parsing `\\u`/`\\U` escapes itself would work too,
+    but this way the codepoints are literal Python string content and there is
+    nothing left for the regex engine to interpret."""
+
+    ESCAPE_PATTERN: ClassVar[Pattern[str]] = _re.compile(
+        r"\\(u[0-9A-Fa-f]{4}|u\{[0-9A-Fa-f]{1,6}\}|U[0-9A-Fa-f]{8})"
+    )
+    """Textual `\\u`/`\\U` escapes that could encode a Han codepoint without
+    containing the raw character. Matches are validated numerically afterwards
+    — the pattern also matches escapes for non-Han codepoints (e.g. `\\u0041`)."""
+
+    CONTENT_PATTERN: ClassVar[Pattern[str]] = _re.compile(
+        HAN_PATTERN.pattern + "|" + ESCAPE_PATTERN.pattern
+    )
+
+    LOCALE_DIR: ClassVar[Pattern[str]] = _re.compile(
+        r"(^|/)i18n/(locales/)?[a-z]{2}(-[A-Za-z]{2,4})?/"
+    )
+    """Locale DATA directories anywhere in the tree — `.../i18n/<locale>/...`
+    and `.../i18n/locales/<locale>/...` — where non-English text is the point,
+    not a defect. Mirrors check.sh's `scan_excluded` rule 3."""
+
+    inputs: ClassVar[dict[str, str]] = {"frontend_src": "<frontend>"}
+    """FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): `I18N_OWNER` was a
+    hardcoded `frontend/mobile/src/i18n` literal, matched against the given
+    set with `==`/`startswith` inside `_excluded` -- a rule 2 EXEMPTION, not a
+    filter over what gets scanned. A repository whose frontend root is not the
+    packaged default had its real i18n directory fail this match, so its
+    genuinely-translated strings were no longer exempt -- every one of them
+    became a false "raw Han text" finding. LOUD, not silent: the wrong path
+    does not go quiet, it makes real translated content look like a defect.
+    `mobile/src/i18n` stays literal below the resolved root: the settled
+    platform path, not a resolvable one, the same call TS-001's `MOBILE_SRC`
+    fix already made."""
+
+    FIX_BY_KIND: ClassVar[dict[str, str]] = {
+        "Han Unicode escape": "replace the \\u/\\U escape with the equivalent English text",
+        "raw Han text": "translate this Han-script text into English",
+        "Han filename": "rename this path component using ASCII/English characters",
+        "Han archive filename": (
+            "rename this archive member using ASCII/English characters and re-save the document"
+        ),
+        "unreadable Office archive": (
+            "repair or re-export the Office file so it is a valid, readable ZIP archive"
+        ),
+        "unreadable archive text": (
+            "repair the archive member or re-export the document so its text stream can be read"
+        ),
+    }
+    """One genuine, specific remediation per finding kind — check.sh's
+    `english_only_fix`. No catch-all default: every kind this class emits has
+    an entry here, and a kind added without one is a programming error, not a
+    generic message papering over it."""
+
+    # ------------------------------------------------------------- entrypoint
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Finding]:
+        seen: set[tuple[str, int | None, str]] = set()
+        for finding in self._raw_findings(ctx, files):
+            key = (finding.path, finding.line, finding.message)
+            if key in seen:
+                continue
+            seen.add(key)
+            yield finding
+
+    def _raw_findings(self, ctx: Context, files: FileSet) -> Iterator[Finding]:
+        # Filename scan runs over every path in the given set, whether or not
+        # it still exists on disk — check.sh's ALL_RELPATHS is filled before
+        # its own `[ -f "$rel" ]` guard, because a Han PATH is the finding
+        # there, distinct from Han CONTENT, which a deleted file no longer has.
+        i18n_owner = self._i18n_owner(ctx)
+        for relative in files:
+            if self._excluded(relative, i18n_owner):
+                continue
+            if self.HAN_PATTERN.search(relative):
+                yield self._finding(relative, "Han filename")
+
+        for relative in files.existing(ctx.root):
+            if self._excluded(relative, i18n_owner):
+                continue
+            suffix = self._path_suffix(relative).lower()
+            if suffix in self.OFFICE_SUFFIXES:
+                yield from self._archive_findings(ctx, relative)
+            elif suffix not in self.BINARY_SUFFIXES:
+                yield from self._scan_plain_file(ctx, relative)
+
+    # ------------------------------------------------------ subject-matter scope
+
+    def _i18n_owner(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['frontend_src'])}/mobile/src/i18n"
+
+    def _excluded(self, relative: str, i18n_owner: str) -> bool:
+        # 1. Hidden paths, by decision. Every component is tested.
+        if any(part.startswith(".") for part in relative.split("/")):
+            return True
+        # 2. The one named i18n owner exemption.
+        if relative == i18n_owner or relative.startswith(i18n_owner + "/"):
+            return True
+        # 3. Any locale-named data directory, anywhere.
+        if self.LOCALE_DIR.search(relative):
+            return True
+        return False
+
+    # -------------------------------------------------------------- plain files
+
+    def _scan_plain_file(self, ctx: Context, relative: str) -> Iterator[Finding]:
+        body = self.text(ctx, relative)
+        if body is None:
+            return
+        for line_no, kind in self._scan_text(body):
+            yield self._finding(relative, kind, line=line_no)
+
+    def _scan_text(self, body: str) -> Iterator[tuple[int, str]]:
+        for line_no, line in enumerate(body.splitlines(), start=1):
+            for match in self.CONTENT_PATTERN.finditer(line):
+                value = match.group(0)
+                if value.startswith("\\"):
+                    codepoint = self._escape_codepoint(value)
+                    if codepoint is not None and self._is_han(codepoint):
+                        yield line_no, "Han Unicode escape"
+                else:
+                    yield line_no, "raw Han text"
+
+    @staticmethod
+    def _escape_codepoint(value: str) -> int | None:
+        stripped = value.lstrip("\\")
+        hex_text = stripped[2:-1] if stripped.startswith("u{") else stripped[1:]
+        try:
+            return int(hex_text, 16)
+        except ValueError:
+            return None
+
+    def _is_han(self, codepoint: int) -> bool:
+        return any(lo <= codepoint <= hi for lo, hi in self.HAN_RANGES)
+
+    # ---------------------------------------------------------------- archives
+
+    def _archive_findings(self, ctx: Context, relative: str) -> Iterator[Finding]:
+        abs_path: Path = ctx.path(relative)
+        try:
+            archive = zipfile.ZipFile(abs_path)
+        except (zipfile.BadZipFile, OSError):
+            yield self._finding(relative, "unreadable Office archive")
+            return
+        try:
+            for info in sorted(archive.infolist(), key=lambda entry: entry.filename):
+                member = info.filename
+                if member.endswith("/"):
+                    continue
+                yield from self._archive_member_findings(ctx, archive, relative, member)
+        finally:
+            archive.close()
+
+    def _archive_member_findings(
+        self, ctx: Context, archive: zipfile.ZipFile, relative: str, member: str
+    ) -> Iterator[Finding]:
+        shown = f"{relative}!/{member}"
+        if self.HAN_PATTERN.search(member):
+            yield self._finding(shown, "Han archive filename")
+
+        suffix = self._path_suffix(member).lower()
+        if suffix not in self.ARCHIVE_TEXT_SUFFIXES:
+            return
+        if member.startswith(self.ARCHIVE_THEME_PREFIXES):
+            return
+        try:
+            data = archive.read(member)
+        except (KeyError, RuntimeError, zipfile.BadZipFile):
+            yield self._finding(shown, "unreadable archive text")
+            return
+        body = data.decode("utf-8", errors="replace")
+        for line_no, kind in self._scan_text(body):
+            yield self._finding(shown, kind, line=line_no)
+
+    # ------------------------------------------------------------------ shared
+
+    @staticmethod
+    def _path_suffix(relative: str) -> str:
+        base = relative.rsplit("/", 1)[-1]
+        if base.startswith(".") and base.count(".") <= 1:
+            return ""
+        if "." in base:
+            return "." + base.rsplit(".", 1)[-1]
+        return ""
+
+    def _finding(self, path: str, kind: str, *, line: int | None = 1) -> Finding:
+        return self.report(path, f"{kind} on this line", self.FIX_BY_KIND[kind], line=line)

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/fixtures/clean/backend/clean.rs

@@ -0,0 +1 @@
+English only.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/fixtures/excluded/frontend/mobile/src/i18n/locales/zh-CN/strings.ts

@@ -0,0 +1 @@
+export const strings = { greeting: "你好" };

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/fixtures/violation/backend/escaped.rs

@@ -0,0 +1,2 @@
+// literal escape sequence below, not a rendered character
+let s = "\u{4E00}";

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/fixtures/violation/backend/raw.rs

@@ -0,0 +1 @@
+一

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/fixtures/violation/backend//346/226/207/344/273/266.rs

@@ -0,0 +1 @@
+English only content; the filename itself is the finding.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/english_only/test_check.py

@@ -0,0 +1,193 @@
+"""DOC-002 — ported from `compliance_new/checks/docs/english-only/test.sh`.
+
+Same three committed corpora, same relative paths and contents as the shell
+test's fixtures (`fixtures/violation/backend/{raw.rs,escaped.rs,文件.rs}`,
+`fixtures/clean/backend/clean.rs`,
+`fixtures/excluded/frontend/mobile/src/i18n/locales/zh-CN/strings.ts`), and the
+same four assertions: a violating tree reports all three finding kinds and
+never echoes the offending Han text; a clean tree is silent; translated locale
+data is excluded by subject matter, not by scope; and the row still declares
+the script this class ports.
+
+Not ported: test.sh's "no set: could not run" case. That is a property of the
+shell CLI (`ADL_CHANGED_FILES` unset), not of this gate's rule logic — a
+`Check.graded` is always called with a `FileSet` argument here, so there is no
+"unset" state to assert, exactly as no other ported check's test re-asserts it.
+
+`DocsEnglishOnly().graded(...)` is called directly, through `decide`, rather
+than through `runner.run`: DOC-002 is not yet listed in `checks/__init__.py`
+(a later step wires this whole wave in one shot — see this gate's own
+AGENTS.md), and `runner.run` would report `COULD_NOT_RUN` for an unwired row.
+This mirrors `typescript/no_eval/test_check.py`'s `graded_directly` helper,
+which exercises the same direct path alongside its (already-wired) `runner.run`
+assertions.
+
+The archive-scanning behaviour (`.docx`/`.xlsx`/`.pptx` member text and member
+filenames) IS ported in `check.py`, using stdlib `zipfile` rather than
+check.sh's hand-rolled ZIP central-directory parser — a genuine simplification,
+not a gap, since Python already has a real ZIP reader. It is exercised below
+with small in-memory archives built at test time, which is not something
+test.sh did (its own header records the shell version's archive path as
+untested); this is additional coverage, not a substitute for anything test.sh
+asserts.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import zipfile
+
+from helpers import corpus
+
+from adl_compliance.checks.docs.english_only import DocsEnglishOnly
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.verdict import Outcome, decide
+from adl_compliance.policy.registry import load
+
+CORPORA = corpus("docs", "english-only")
+VIOLATION = CORPORA / "violation"
+CLEAN = CORPORA / "clean"
+EXCLUDED = CORPORA / "excluded"
+ROW = load().by_id("DOC-002")
+
+
+def graded_directly(root: pathlib.Path, paths: tuple[str, ...]):
+    # `frontend_src` is a RESOLVED INPUT now, not a class constant -- `frontend`
+    # bare, the packaged default `<frontend>` actually resolves to, which is
+    # also every committed corpus's real shape.
+    ctx = Context(root=root, row=ROW, inputs={"frontend_src": root / "frontend"})
+    findings = tuple(DocsEnglishOnly().graded(ctx, FileSet(paths=paths)))
+    return decide(ROW, findings, 0, ())
+
+
+def test_the_row_identifies_this_check() -> None:
+    """The wiring proof the shell test's `dispatch_contract` covered: the row
+    genuinely addresses this check, not a renamed one."""
+    assert ROW.domain == "docs"
+    assert ROW.name == "english-only"
+
+
+def test_the_violating_fixture_reports_all_three_kinds() -> None:
+    verdict = graded_directly(
+        VIOLATION, ("backend/raw.rs", "backend/escaped.rs", "backend/文件.rs")
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert len(verdict.findings) == 3
+
+    rendered = verdict.render()
+    assert "DOC-002 backend/raw.rs:1: raw Han text on this line" in rendered
+    assert "DOC-002 backend/escaped.rs:2: Han Unicode escape on this line" in rendered
+    assert "DOC-002 backend/文件.rs:1: Han filename on this line" in rendered
+    assert all(f.rule == "DOC-002" for f in verdict.findings)
+
+
+def test_the_offending_han_text_is_never_echoed() -> None:
+    """check.sh's own rule: a report names WHERE, never WHAT. The Han-named
+    fixture still shows Han in its own path (the path IS the finding there);
+    this checks only that the raw content character (一, from raw.rs/escaped.rs)
+    never leaks into a message."""
+    verdict = graded_directly(
+        VIOLATION, ("backend/raw.rs", "backend/escaped.rs", "backend/文件.rs")
+    )
+    for finding in verdict.findings:
+        assert "一" not in finding.message
+
+
+def test_the_clean_fixture_is_silent() -> None:
+    verdict = graded_directly(CLEAN, ("backend/clean.rs",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_locale_data_is_excluded_by_subject_matter_not_scope() -> None:
+    """`frontend/mobile/src/i18n/locales/zh-CN/` is Han BY DESIGN — translated
+    UI strings, not prose to flag. Proves `_excluded`'s subject-matter
+    exemption: the row's own scope is `**` (minus four unrelated files) and
+    would otherwise select this path."""
+    path = "frontend/mobile/src/i18n/locales/zh-CN/strings.ts"
+    verdict = graded_directly(EXCLUDED, (path,))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert not any(f.rule == "DOC-002" for f in verdict.findings)
+
+
+def test_a_redeclared_frontend_tree_still_exempts_the_i18n_owner(tmp_path: pathlib.Path) -> None:
+    """The LOUD false-positive this check shipped with.
+
+    `I18N_OWNER = "frontend/mobile/src/i18n"` was matched against the given
+    set directly. A repository whose frontend root is not the packaged
+    default had its real, genuinely-translated i18n tree fail that match --
+    every translated string in it became a false "raw Han text" finding.
+    Unlike a SILENT filter this does not go quiet; it makes real, exempt
+    content look like a defect, which is what makes it LOUD."""
+    path = "web/mobile/src/i18n/locales/zh-CN/strings.ts"
+    root = tmp_path / "repo"
+    target = root / path
+    target.parent.mkdir(parents=True)
+    target.write_text("export const greeting = '一';\n", encoding="utf-8")
+    ctx = Context(root=root, row=ROW, inputs={"frontend_src": root / "web"})
+    findings = tuple(DocsEnglishOnly().graded(ctx, FileSet(paths=(path,))))
+    verdict = decide(ROW, findings, 0, ())
+    assert verdict.outcome is Outcome.CLEAN, (
+        f"genuinely-translated i18n content under a redeclared frontend root "
+        f"was falsely flagged: {verdict.render()}"
+    )
+
+
+def test_a_deleted_paths_han_filename_still_reports_but_not_its_content(
+    tmp_path: pathlib.Path,
+) -> None:
+    """check.sh fills `ALL_RELPATHS` (filename scan) unconditionally, before
+    its own `[ -f "$rel" ]` guard on `ALL_FILE_ABS` (content scan) — a Han path
+    component is the finding even for a path the given set names but that no
+    longer exists on disk; there is simply nothing left to read for content."""
+    verdict = graded_directly(tmp_path, ("backend/文件.rs",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert len(verdict.findings) == 1
+    assert verdict.findings[0].message == "Han filename on this line"
+
+
+# ---------------------------------------------------------------- archives
+
+
+def _write_docx(path: pathlib.Path, *, member_name: str, member_text: str) -> None:
+    with zipfile.ZipFile(path, "w") as archive:
+        archive.writestr("[Content_Types].xml", "<Types/>")
+        archive.writestr(member_name, member_text)
+
+
+def test_an_office_archive_with_han_member_name_and_text_is_reported(
+    tmp_path: pathlib.Path,
+) -> None:
+    _write_docx(tmp_path / "report.docx", member_name="word/文档.xml", member_text="一")
+    verdict = graded_directly(tmp_path, ("report.docx",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    kinds = {f.message for f in verdict.findings}
+    assert "Han archive filename on this line" in kinds
+    assert "raw Han text on this line" in kinds
+    assert all(f.path.startswith("report.docx!/") for f in verdict.findings)
+
+
+def test_an_office_archive_with_english_only_members_is_silent(
+    tmp_path: pathlib.Path,
+) -> None:
+    _write_docx(tmp_path / "report.docx", member_name="word/document.xml", member_text="hello")
+    verdict = graded_directly(tmp_path, ("report.docx",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_theme_member_is_excluded_from_archive_text_scanning(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Mirrors check.sh's `xl/theme/* | word/theme/* | ppt/theme/*` skip."""
+    _write_docx(tmp_path / "report.docx", member_name="word/theme/theme1.xml", member_text="一")
+    verdict = graded_directly(tmp_path, ("report.docx",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_unreadable_office_archive_is_reported_not_silently_skipped(
+    tmp_path: pathlib.Path,
+) -> None:
+    broken = tmp_path / "broken.docx"
+    broken.write_bytes(b"not a zip file")
+    verdict = graded_directly(tmp_path, ("broken.docx",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.findings[0].message == "unreadable Office archive on this line"

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/index_updated/__init__.py

@@ -0,0 +1,12 @@
+"""The `docs.index-updated` gate.
+
+A folder rather than a module because this gate GRADES A DOCUMENT (each
+collection's `index.md` catalog) and the document belongs beside the check
+that reads it.
+"""
+
+from __future__ import annotations
+
+from .check import IndexUpdated
+
+__all__ = ["IndexUpdated"]