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

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

@@ -0,0 +1,578 @@
+"""DOC-007 — published-documentation semantics.
+
+Ported from `compliance_new/checks/docs/semantics/check.sh`, `RULE_ID=DOC-007`.
+
+Two independent lanes, both graded from the GIVEN SET rather than a walk:
+
+  pages           every `.md`/`.mdx` file under a governed top-level
+                   collection (`docs/architecture`, `docs/research`,
+                   `docs/compliance`, `docs/operations`) — frontmatter and body
+                   read directly, no ast-grep and no synthetic extraction pass.
+  yaml registers   `docs/compliance/gaps/gap-register.yaml` and
+                   `docs/compliance/controls/control-matrix.yaml`, each a list
+                   of records graded for required fields and a resolvable
+                   `remediation_link`.
+
+**The gap register reuses `checks/docs/register.py`'s `GapRegister`/
+`GapRecord`, exactly as instructed** — it is the shared model an earlier wave
+built for this document, and forking a second reader here would let the two
+disagree the moment either grew a field. That reuse trades away one piece of
+shell fidelity on purpose: `check.sh`'s `check_yaml_records` reports each
+missing field as its own finding (`gap record N missing owner`); `GapRegister`
+is `StrictModel` (`extra="forbid"`, every field mandatory), so a record missing
+a required field — or carrying one of the five forbidden delivery fields —
+fails model validation as ONE `SchemaInvalid`, reported as one finding rather
+than several. No fixture exercises this path (neither corpus commits a
+`gap-register.yaml`), so the divergence is unverified by any test; it is
+recorded here rather than silently shipped. The one per-record check `GapRecord`
+COULD still express structurally — that `remediation_link` resolves relative to
+the register's directory — is kept, field-for-field, once parsing succeeds.
+
+**The control matrix has no shared model, and none is added here.** Its real
+document (`docs/compliance/controls/control-matrix.yaml`, 203 records) carries
+an envelope (`metadata`, `coverage`, `status_definitions`) the committed test
+fixtures omit entirely, and per-record fields (`statement`, `applicability`,
+`cross_framework_mappings`, `examination_period`, `type_ii_evidence_status`)
+this gate never reads. A `StrictModel` envelope would have to either invent
+requirements neither shape agrees on, or degrade to `OpenModel` tolerance that
+buys nothing over reading the parsed YAML directly — so this gate reads
+`yaml.safe_load` output and grades the `controls:` list by key presence, the
+same generic shape `check_yaml_records` used for both documents in the shell
+version. This keeps `control record N missing X` field-level, matching
+`test.sh` byte for byte, without introducing a schema this package would then
+own but never actually enforce.
+
+Dropped as genuinely dead in the shell source, verified by reading the whole
+file rather than one grep hit: `frontmatter()`, `field()`, `body()`,
+`real_utc()`, and `contains_word()` are defined but called nowhere else in
+`check.sh` — the two `awk` passes below (`_split`/`_scan_body` and
+`_grade_control_matrix`) are the entire live rule. Nothing here ports them.
+
+The "no gap records found" message is reused verbatim for the control-matrix
+branch too — `check.sh`'s own `check_yaml_records` hardcodes that exact string
+regardless of `$kind`, so `docs/compliance/controls/control-matrix.yaml`
+having zero records would report "no gap records found", not "no control
+records found". That is what the shell source says, not a typo introduced
+here.
+
+The "unknown published collection" branch is carried over even though it can
+never fire: `_grade_pages` only ever selects files under the four governed
+top-level directories (the same filter `check.sh`'s own page-selection `case`
+applies before its awk pass ever runs), so `collection` is always one of them
+by construction. Kept for a byte-for-byte structural port of `finish()`, not
+because it is reachable.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from typing import ClassVar
+
+import yaml
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun, SchemaInvalid
+from ....core.finding import Report
+from ..register import GapRegister
+
+
+class DocsSemantics(Check):
+    id: ClassVar[str] = "DOC-007"
+    rule: ClassVar[str] = "DOC-007"
+
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>"}
+    """FIXED 2026-09-15 (K-42 sweep, SILENT form): `CONTENT` used to be a
+    hardcoded `"docs"` literal used as a bare `startswith` filter in
+    `_grade_pages`. A repository declaring `docs = "documentation"` had every
+    real page's path fail a `path.startswith` test against `docs/architecture/`
+    (real paths read `documentation/architecture/...`) — the filter dropped every page
+    before grading, and the gate reported clean having graded nothing. No
+    error, no could-not-run: a green light meaning nothing, and it was ARMED
+    in exactly that state on enact-m5 and enact-repo-controls-m5 (both happen
+    to declare `docs = "docs"`, so the literal was accidentally correct there
+    — this fix should not move either repo's count). `COLLECTIONS` below
+    stays literal: architecture/research/compliance/operations are the
+    settled taxonomy, not a resolvable path (see its own comment)."""
+
+    DELIMITER: ClassVar[str] = "---"
+
+    COLLECTIONS: ClassVar[tuple[str, ...]] = ("architecture", "research", "compliance", "operations")
+    # There is deliberately NO governed list of second-level categories.
+    #
+    # There was one, hardcoded: architecture had to be product/frontend/backend/
+    # agent-runtime/team/cloud-platform/contracts-and-data/decisions. That is one
+    # repository's documentation taxonomy written inside the package, and it shared
+    # not a single category with the next repository it was pointed at -- fourteen
+    # findings that said "your architecture tree is wrong" and meant "your tree is
+    # not the tree this list was written against". The same shape as 7b8c057, which
+    # cut DOC-006 from eight OKF profiles to four because seven declared trees that
+    # did not exist.
+    #
+    # What is standard is the COLLECTION -- architecture, operations, decisions,
+    # compliance -- and that is already declared once, in docs-okf-profiles.yaml's
+    # `paths:`. How a repository subdivides inside one is its own business, and a
+    # register of permitted subdivisions would only move the hardcoding into YAML.
+
+    KEY_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):[ \t]*(.*)$")
+
+    TIMESTAMP: ClassVar[re.Pattern[str]] = re.compile(
+        r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+    )
+    ORDINAL: ClassVar[re.Pattern[str]] = re.compile(
+        r"(R[0-9]+(-[A-Z][0-9]+)?|S[0-9]+(-[A-Z][0-9]+)?|D[0-9]+(-[A-Z][0-9]+)?|"
+        r"W[0-9]+(-[A-Z][0-9]+)?|wave\s+[0-9]+)\s*·"
+    )
+    TARGET_STATUS: ClassVar[re.Pattern[str]] = re.compile(
+        r"not yet (implemented|delivered)|implementation (gap|status)|"
+        r"delivery (record|status|state)|execution status|implementation evidence|"
+        r"known implementation boundary|current measured shape|measured tables?|"
+        r"current (code|implementation|checkout)|still (missing|absent|blocked)|outstanding:"
+    )
+    RECOMMENDATION_HEADING: ClassVar[re.Pattern[str]] = re.compile(
+        r"^>\s*draft for review|^##\s+(current state|implementation( map| status)?|"
+        r"delivery( status| plan)?|open questions|open decisions|recommendation)\s*$"
+    )
+    RECOMMENDATION_WORD: ClassVar[re.Pattern[str]] = re.compile(r"(^|[^a-z0-9_])recommended([^a-z0-9_]|$)")
+    IMPLEMENTATION_STATUS: ClassVar[re.Pattern[str]] = re.compile(
+        r"not yet (implemented|built|wired|available|supported)|"
+        # `not implemented BY <means>` states how something is achieved, not
+        # that it is undone. All three corpus hits were that shape or a rule's
+        # own subject ("a config not wired TO the shared guard"); none was a
+        # delivery claim. A bare "is not implemented." still fires.
+        r"not (implemented|built|wired)(?! (by|into|to|with|using|via)\b)|"
+        r"unimplemented|unbuilt|live-wired|landed|shipped|future implementation|open work|"
+        r"(implementation|delivery) (status|state)|"
+        r"(now|already|currently) (implemented|built|wired|deployed|landed|shipped|available|operational)|"
+        # `built` is DELIBERATELY absent from this clause. It is a construction
+        # verb before it is a delivery verb, and measured across both
+        # repositories' docs and plans trees every one of the 11 occurrences of
+        # `(is|are|was|were|has been|have been) built` was constructional --
+        # "built for linux/amd64", "built from the channel's posts", "built and
+        # mounted", "built lazily", "was built first". Not one was a delivery
+        # claim. The delivery sense keeps its own clause above
+        # (`now|already|currently built`) plus `not yet built` / `unbuilt`, so
+        # nothing real is given up.
+        r"(is|are|was|were|has been|have been) (now )?"
+        r"(implemented|wired|deployed|landed|shipped|completed|proven live)|"
+        r"no longer theoretical|what (landed|remains)|"
+        r"remaining (product |implementation |delivery )?(question|work|gap)|"
+        r"remains? (the )?(next slice|unbuilt|unimplemented|open)|deferred"
+    )
+    RESEARCH_QUESTION: ClassVar[re.Pattern[str]] = re.compile(r"(question|scope|problem)")
+    RESEARCH_METHOD: ClassVar[re.Pattern[str]] = re.compile(r"(method|setup|reproduce|command)")
+    RESEARCH_EVIDENCE: ClassVar[re.Pattern[str]] = re.compile(r"(evidence|finding|result|measurement|observed)")
+    RESEARCH_LIMITS: ClassVar[re.Pattern[str]] = re.compile(r"(source|reference|limitation|limit|caveat|unknown)")
+    REVIEW_CADENCE: ClassVar[re.Pattern[str]] = re.compile(r"review\s+(frequency|cadence)|review cadence")
+    RETENTION: ClassVar[re.Pattern[str]] = re.compile(r"retention|retain")
+
+    # FIXED 2026-09-16 (K-42 sweep, SILENT form, approved): GAP_REGISTER /
+    # CONTROL_MATRIX / ASSETS_DIR / EVIDENCE_FILE were hardcoded `docs/...`
+    # literals, each tested for membership in (or a prefix of) the given set
+    # -- `path not in files: return` / a bare `startswith` -- the same SILENT
+    # shape `CONTENT` had. None of the four paths exists in any repository in
+    # this estate today, so all four sub-checks are already silent no-ops on
+    # every armed run; the defect is the same regardless of whether it
+    # currently bites. Resolved off the same `docs_root` input above, via the
+    # `_gap_register`/`_control_matrix`/`_assets_dir`/`_evidence_file` helpers
+    # below -- each suffix stays literal, the settled shape of that one
+    # document, not a resolvable path.
+    GAP_FORBIDDEN: ClassVar[tuple[str, ...]] = (
+        "duration", "objective", "exit_criteria", "staffing", "phases",
+    )
+
+    CONTROL_REQUIRED: ClassVar[tuple[str, ...]] = (
+        "owner", "risk", "review_frequency", "retention", "status", "evidence",
+        "gap", "remediation_link",
+    )
+
+    ASSET_NAME: ClassVar[re.Pattern[str]] = re.compile(r"^mobile-reference-[0-9]{2}\.png$")
+    EVIDENCE_CAPTION: ClassVar[re.Pattern[str]] = re.compile(r"Reference screenshot\s+[0-9]+")
+
+    FIXED_MESSAGES: ClassVar[Mapping[str, str]] = {
+        "operations pages must be flat under docs/operations/":
+            "move the page to be a direct child of docs/operations/",
+        "unknown published collection":
+            "move the page under docs/architecture, docs/research, docs/compliance, "
+            "or docs/operations",
+        "description must explain purpose, not repeat title":
+            "rewrite the frontmatter description to explain purpose, not repeat the title",
+        "description contains an ordinal or wave label":
+            "remove the ordinal or wave label (e.g. 'R12 ·', 'wave 3 ·') from the description",
+        "last_update must be an ISO-8601 UTC timestamp":
+            "set last_update to an ISO-8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)",
+        "last_update is not a real UTC calendar timestamp":
+            "correct last_update to a real calendar date and time",
+        "architecture target cannot carry delivery-status narration; record the gap in plans/":
+            "move the delivery-status narration into a plans/ feature; keep this page target-state only",
+        "stable architecture cannot contain unresolved recommendation language":
+            "resolve or remove the recommendation language before marking the page stable",
+        "stable architecture cannot carry delivery or implementation status":
+            "remove delivery/implementation status narration; record it in plans/ instead",
+        "research must state question": "add a section stating the research question",
+        "research must state method": "add a section stating the research method",
+        "research must state evidence": "add a section stating the research evidence",
+        "research must state limits": "add a section stating the research limits",
+        "compliance matrix must state review frequency":
+            "add a review-frequency statement to the compliance matrix page",
+        "compliance matrix must state evidence retention":
+            "add an evidence-retention statement to the compliance matrix page",
+    }
+    DEFAULT_FIX: ClassVar[str] = (
+        "review docs/architecture/AGENTS.md's semantics contract and correct the page accordingly"
+    )
+
+    # -------------------------------------------------------------- structural
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        if not ctx.path(docs_root).is_dir():
+            yield self.report(
+                docs_root, "docs content root is missing",
+                f"create the {docs_root}/ directory before running this gate",
+            )
+
+    # ------------------------------------------------------------------ graded
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        yield from self._grade_pages(ctx, files)
+        yield from self._grade_gap_register(ctx, files)
+        yield from self._grade_control_matrix(ctx, files)
+        yield from self._grade_assets(ctx, files)
+        yield from self._grade_evidence_captions(ctx, files)
+
+    # --------------------------------------------------------------- the pages
+
+    def _grade_pages(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        prefix = f"{ctx.relative(ctx.inputs['docs_root'])}/"
+        for path in sorted(files):
+            if not any(path.startswith(f"{prefix}{c}/") for c in self.COLLECTIONS):
+                continue
+            if not path.endswith((".md", ".mdx")):
+                continue
+            if not ctx.path(path).is_file():
+                continue
+            yield from self._grade_page(ctx, path)
+
+    def _grade_page(self, ctx: Context, path: str) -> Iterable[Report]:
+        body = self.text(ctx, path)
+        if body is None:
+            return
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        rel = path[len(docs_root) + 1:]
+        parts = rel.split("/")
+        name = parts[-1]
+        if name in ("AGENTS.md", "CLAUDE.md"):
+            return
+        collection = parts[0]
+        nested = len(parts) > 2
+        category = parts[1] if nested else ""
+
+        frontmatter, body_lines, closed = self._split(body)
+        title = frontmatter.get("title", "")
+        description = frontmatter.get("description", "")
+        last_update = frontmatter.get("last_update", "")
+        status = frontmatter.get("status", "")
+        profile_state = frontmatter.get("profile_state", "")
+
+        (
+            research_question, research_method, research_evidence, research_limits,
+            review, retention, target_status, recommendation, implementation_status,
+        ) = self._scan_body(body_lines, closed)
+
+        for message in self._finish(
+            collection=collection, category=category, name=name, nested=nested,
+            title=title, description=description, last_update=last_update,
+            status=status, profile_state=profile_state,
+            target_status=target_status, recommendation=recommendation,
+            implementation_status=implementation_status,
+            research_question=research_question, research_method=research_method,
+            research_evidence=research_evidence, research_limits=research_limits,
+            review=review, retention=retention,
+        ):
+            yield self.report(path, message, self._fix_for(message))
+
+    def _split(self, body: str) -> tuple[dict[str, str], list[str], bool]:
+        """Frontmatter fields, body lines, and whether the frontmatter closed.
+
+        Mirrors the awk state machine's `in_frontmatter`/`closed` pair: a file
+        not opening with a bare `---` never sets `closed`, so the narration
+        rules that require it (target/recommendation/implementation status)
+        never fire for it -- only the keyword-scan rules do, over every line
+        past the first (awk's `FNR == 1 { ...; next }` always skips line one).
+        """
+        lines = body.splitlines()
+        if not lines or lines[0].strip() != self.DELIMITER:
+            return {}, (lines[1:] if lines else []), False
+
+        frontmatter: dict[str, str] = {}
+        for index in range(1, len(lines)):
+            line = lines[index]
+            if line.strip() == self.DELIMITER:
+                return frontmatter, lines[index + 1:], True
+            found = self.KEY_LINE.match(line)
+            if found:
+                frontmatter[found.group(1)] = self._scalar(found.group(2))
+        # No closing delimiter: never closed, no body lines.
+        return frontmatter, [], False
+
+    @staticmethod
+    def _scalar(value: str) -> str:
+        value = value.strip()
+        value = re.sub(r'^["\']', "", value)
+        value = re.sub(r'["\']$', "", value)
+        return value
+
+    FENCE: ClassVar[re.Pattern[str]] = re.compile(r"^\s*(```|~~~)")
+    CODE_SPAN: ClassVar[re.Pattern[str]] = re.compile(r"`[^`]*`")
+
+    @classmethod
+    def _prose(cls, line: str) -> str:
+        """The line with inline code spans blanked out.
+
+        These rules are about what a page SAYS, and a code span is not the page
+        speaking — it is a path, an identifier or a command being quoted. Left in,
+        `IMPLEMENTATION_STATUS` matched the filename in
+        `backend/shipped-runtime-imports.test.ts` and the word "implemented" inside
+        `` `agent-loop/v1` ``, so a page was told to move delivery narration it did
+        not contain. Six of nine findings against enact-m5 were this.
+        """
+        return cls.CODE_SPAN.sub(lambda m: " " * len(m.group(0)), line)
+
+    def _scan_body(self, body_lines: list[str], closed: bool) -> tuple[bool, ...]:
+        research_question = research_method = research_evidence = research_limits = False
+        review = retention = False
+        target_status = recommendation = implementation_status = False
+        fenced = False
+        for line in body_lines:
+            # A fenced block is a transcript, not prose. `bun test backend/shipped-...`
+            # inside one is a command to run, not a claim about what shipped.
+            if self.FENCE.match(line):
+                fenced = not fenced
+                continue
+            if fenced:
+                continue
+            low = self._prose(line).lower()
+            if self.RESEARCH_QUESTION.search(low):
+                research_question = True
+            if self.RESEARCH_METHOD.search(low):
+                research_method = True
+            if self.RESEARCH_EVIDENCE.search(low):
+                research_evidence = True
+            if self.RESEARCH_LIMITS.search(low):
+                research_limits = True
+            if self.REVIEW_CADENCE.search(low):
+                review = True
+            if self.RETENTION.search(low):
+                retention = True
+            if closed:
+                if self.TARGET_STATUS.search(low):
+                    target_status = True
+                if self.RECOMMENDATION_HEADING.match(low) or self.RECOMMENDATION_WORD.search(low):
+                    recommendation = True
+                if self.IMPLEMENTATION_STATUS.search(low):
+                    implementation_status = True
+        return (
+            research_question, research_method, research_evidence, research_limits,
+            review, retention, target_status, recommendation, implementation_status,
+        )
+
+    def _finish(  # noqa: PLR0913 — one finding rule per shell `finish()` branch
+        self, *, collection: str, category: str, name: str, nested: bool, title: str,
+        description: str, last_update: str, status: str, profile_state: str,
+        target_status: bool, recommendation: bool, implementation_status: bool,
+        research_question: bool, research_method: bool, research_evidence: bool,
+        research_limits: bool, review: bool, retention: bool,
+    ) -> Iterable[str]:
+        if collection == "operations":
+            if nested and name != "index.md":
+                # `nested` is `n > 2` in the shell awk -- a path with a 3rd
+                # segment. operations must stay flat.
+                yield "operations pages must be flat under docs/operations/"
+        elif collection not in self.COLLECTIONS:
+            yield "unknown published collection"
+
+        if description.lower() == title.lower():
+            yield "description must explain purpose, not repeat title"
+        if self.ORDINAL.search(description):
+            yield "description contains an ordinal or wave label"
+
+        if not self.TIMESTAMP.match(last_update):
+            yield "last_update must be an ISO-8601 UTC timestamp"
+        elif not self._valid_calendar(last_update):
+            yield "last_update is not a real UTC calendar timestamp"
+
+        lower_status = status.lower()
+        shown = lower_status if status != "" else "<missing>"
+        if collection == "architecture" and lower_status not in ("draft", "stable"):
+            yield (
+                f"architecture status must be 'draft' or 'stable' (got '{shown}') -- "
+                "deprecated/superseded content is deleted or rewritten in place, never labeled"
+            )
+        if collection == "operations" and lower_status not in ("draft", "stable"):
+            yield f"operations status must be 'draft' or 'stable' (got '{shown}')"
+
+        if collection == "architecture" and name != "index.md":
+            if target_status:
+                yield "architecture target cannot carry delivery-status narration; record the gap in plans/"
+            if lower_status == "stable" and profile_state != "migrated":
+                if recommendation:
+                    yield "stable architecture cannot contain unresolved recommendation language"
+                if implementation_status:
+                    yield "stable architecture cannot carry delivery or implementation status"
+
+        if (
+            collection == "research" and category != "rust-best-practices"
+            and name != "index.md" and profile_state != "migrated"
+        ):
+            if not research_question:
+                yield "research must state question"
+            if not research_method:
+                yield "research must state method"
+            if not research_evidence:
+                yield "research must state evidence"
+            if not research_limits:
+                yield "research must state limits"
+
+        if name == "control-matrix.md":
+            if not review:
+                yield "compliance matrix must state review frequency"
+            if not retention:
+                yield "compliance matrix must state evidence retention"
+
+    @staticmethod
+    def _valid_calendar(timestamp: str) -> bool:
+        year = int(timestamp[0:4])
+        month = int(timestamp[5:7])
+        day = int(timestamp[8:10])
+        hour = int(timestamp[11:13])
+        minute = int(timestamp[14:16])
+        second = int(timestamp[17:19])
+        if not (1 <= month <= 12 and day >= 1 and hour <= 23 and minute <= 59 and second <= 59):
+            return False
+        if month == 2:
+            leap = year % 400 == 0 or (year % 4 == 0 and year % 100 != 0)
+            max_day = 28 + (1 if leap else 0)
+        elif month in (4, 6, 9, 11):
+            max_day = 30
+        else:
+            max_day = 31
+        return day <= max_day
+
+    def _fix_for(self, message: str) -> str:
+        if message.startswith("architecture status must be") or message.startswith(
+            "operations status must be"
+        ):
+            return "set status to 'draft' or 'stable' in the frontmatter"
+        return self.FIXED_MESSAGES.get(message, self.DEFAULT_FIX)
+
+    # ----------------------------------------------------------- the registers
+
+    def _gap_register(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['docs_root'])}/compliance/gaps/gap-register.yaml"
+
+    def _control_matrix(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['docs_root'])}/compliance/controls/control-matrix.yaml"
+
+    def _assets_dir(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['docs_root'])}/assets/research/mobile-reference"
+
+    def _evidence_file(self, ctx: Context) -> str:
+        return (
+            f"{ctx.relative(ctx.inputs['docs_root'])}/research/field-notes/"
+            "mobile-reference-evidence.md"
+        )
+
+    def _grade_gap_register(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        path = self._gap_register(ctx)
+        if path not in files or not ctx.path(path).is_file():
+            return
+        try:
+            register = self.parse_yaml(ctx, path, GapRegister)
+        except SchemaInvalid as exc:
+            yield self.report(
+                path, f"gap register does not match its schema: {exc.detail}",
+                "conform the gap register to the shared GapRegister model in "
+                "checks/docs/register.py",
+            )
+            return
+        directory = path.rsplit("/", 1)[0]
+        for index, record in enumerate(register.gaps, start=1):
+            link = record.remediation_link
+            if link and not (ctx.root / directory / link).exists():
+                yield self.report(
+                    path, f"gap record {index} has an unusable remediation_link",
+                    f"set remediation_link to a path that exists relative to {directory}/",
+                )
+
+    def _grade_control_matrix(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        path = self._control_matrix(ctx)
+        if path not in files or not ctx.path(path).is_file():
+            return
+        body = self.text(ctx, path)
+        if body is None:
+            return
+        try:
+            document = yaml.safe_load(body)
+        except yaml.YAMLError as exc:
+            raise CouldNotRun(f"{path} is not valid YAML: {exc}") from exc
+
+        raw_records = document.get("controls") if isinstance(document, dict) else None
+        directory = path.rsplit("/", 1)[0]
+        count = 0
+        for index, record in enumerate(raw_records or [], start=1):
+            if not isinstance(record, dict):
+                continue
+            count += 1
+            for field in self.CONTROL_REQUIRED:
+                if self._missing(record, field):
+                    yield self.report(
+                        path, f"control record {index} missing {field}",
+                        f"add the {field} field to control record {index}",
+                    )
+            link = record.get("remediation_link")
+            if link not in (None, "") and not (ctx.root / directory / str(link)).exists():
+                yield self.report(
+                    path, f"control record {index} has an unusable remediation_link",
+                    f"set remediation_link to a path that exists relative to {directory}/",
+                )
+        if count == 0:
+            # Hardcoded "gap" in check.sh's own check_yaml_records regardless of
+            # $kind -- see the module docstring.
+            yield self.report(
+                path, "no gap records found", "add at least one control record to this file",
+            )
+
+    @staticmethod
+    def _missing(record: Mapping[str, object], key: str) -> bool:
+        value = record.get(key)
+        return key not in record or value is None or value == ""
+
+    # -------------------------------------------------------- assets/captions
+
+    def _grade_assets(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        prefix = f"{self._assets_dir(ctx)}/"
+        for path in sorted(files):
+            if not path.startswith(prefix) or not path.endswith(".png"):
+                continue
+            name = path.rsplit("/", 1)[-1]
+            if self.ASSET_NAME.match(name):
+                yield self.report(
+                    path, "research asset name must describe observable evidence",
+                    "rename the asset to describe the observable evidence it shows, "
+                    "not a generic index",
+                )
+
+    def _grade_evidence_captions(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        path = self._evidence_file(ctx)
+        if path not in files:
+            return
+        body = self.text(ctx, path)
+        if body is None:
+            return
+        if self.EVIDENCE_CAPTION.search(body):
+            yield self.report(
+                path, "image captions must describe observable evidence",
+                "rewrite the image caption to describe the observable evidence shown",
+            )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-clean/docs/architecture/backend/crate-overview.md

@@ -0,0 +1,8 @@
+---
+title: "Crate overview"
+description: "How the crate boundary is drawn"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-clean/docs/architecture/team/team-overview.md

@@ -0,0 +1,8 @@
+---
+title: "Team overview"
+description: "How the team boundary is drawn"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-clean/docs/compliance/controls/control-matrix.md

@@ -0,0 +1,12 @@
+---
+title: "Control matrix"
+description: "How controls are reviewed and retained"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+Each control carries a review frequency of one year.
+
+Evidence retention is seven years.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-clean/docs/compliance/controls/control-matrix.yaml

@@ -0,0 +1,10 @@
+controls:
+  - id: EC-A.5.36
+    owner: platform
+    risk: low
+    review_frequency: annual
+    retention: 7y
+    status: met
+    evidence: control-matrix.md
+    gap: none
+    remediation_link: control-matrix.md

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-clean/docs/research/benchmarks/note.md

@@ -0,0 +1,24 @@
+---
+title: "Benchmarks note"
+description: "What the benchmark boundary measures"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+## Question
+
+Which scope is measured.
+
+## Method
+
+Run the command.
+
+## Evidence
+
+The observed result.
+
+## Limits
+
+The caveat and its source.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/architecture/backend/crate-overview.md

@@ -0,0 +1,8 @@
+---
+title: "Crate overview"
+description: "How the crate boundary is drawn"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/architecture/product/stable-delivery.md

@@ -0,0 +1,10 @@
+---
+title: "Stable delivery"
+description: "Why a stable page narrates delivery"
+document_type: architecture
+status: stable
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+The boundary has been shipped.