@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,427 @@
+"""DOC-009 — the Markdown plan-event ledger.
+
+Five committed corpora (`ledger-clean`, `ledger-violation`, `ledger-bad-date`,
+`ledger-long-event`, `ledger-empty-table`) cover the shapes an author actually
+commits. Everything else is built in `tmp_path` from `table(...)`, because a
+one-row defect does not earn a directory on disk.
+
+`test.sh`'s third scenario -- no `ADL_CHANGED_FILES` set, exit 2 -- has no
+Python analogue: `Check.run(ctx, files)` always receives a `FileSet` (K-18), so
+there is no "unset" state to construct. `test_no_set_is_could_not_run` below is
+the same substitution `DOC-006`'s test already makes for the identical shell
+contract: the caller declares its set exhaustive, and the row's own
+`engine.scope` matches nothing in an empty set.
+
+`test.sh`'s closing `dispatch_contract DOC-009 pr_validation` proves only that
+the row is well-formed and wired to a profile -- registry-shape and
+profile-wiring assertions belong to `tests/core/test_registry.py`, not to a
+single gate's test module.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import shutil
+from datetime import date, timedelta
+
+import pytest
+import yaml
+
+from adl_compliance import runner
+from adl_compliance.core.verdict import Outcome, Verdict
+from adl_compliance.policy.registry import Registry, effective_trees, load, policy_text
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+ROW = load().by_id("DOC-009")
+
+LEDGER = "plans/LEDGER.md"
+LEGACY = "plans/LEDGER.yaml"
+
+HEADER = "| Date | Id | Area | Event | Refs |\n| --- | --- | --- | --- | --- |\n"
+
+
+def table(*rows: str) -> str:
+    """A ledger document whose table holds exactly `rows`."""
+    return "# Ledger\n\n" + HEADER + "".join(f"{row}\n" for row in rows)
+
+
+def run(case: str) -> Verdict:
+    return runner.run(ROW, FIXTURES / case, (LEDGER,))
+
+
+def run_body(tmp_path: pathlib.Path, body: str, *, legacy: str | None = None) -> Verdict:
+    root = tmp_path / "repo"
+    (root / "plans").mkdir(parents=True)
+    (root / "plans" / "LEDGER.md").write_text(body, encoding="utf-8")
+    given = [LEDGER]
+    if legacy is not None:
+        (root / "plans" / "LEDGER.yaml").write_text(legacy, encoding="utf-8")
+        given.append(LEGACY)
+    return runner.run(ROW, root, tuple(given))
+
+
+def messages(verdict: Verdict) -> list[str]:
+    return [finding.message for finding in verdict.findings]
+
+
+def reported(verdict: Verdict, message: str, *, path: str = LEDGER) -> bool:
+    return any(
+        finding.rule == "KNW-002" and finding.path == path and finding.message == message
+        for finding in verdict.findings
+    )
+
+
+# ------------------------------------------------------------ committed corpora
+
+
+def test_a_well_formed_table_passes() -> None:
+    verdict = run("ledger-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_non_kebab_case_id_is_reported() -> None:
+    verdict = run("ledger-violation")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].id: must be lower-kebab-case"), verdict.render()
+
+
+def test_a_date_that_is_not_a_real_day_is_reported() -> None:
+    """Well-formed `YYYY-MM-DD`, but February never has a thirtieth: the
+    calendar half of `_valid_date`, not just its regex."""
+    verdict = run("ledger-bad-date")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].date: must be YYYY-MM-DD"), verdict.render()
+
+
+def test_an_over_long_event_is_reported() -> None:
+    verdict = run("ledger-long-event")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].event: must be at most 99 characters"), verdict.render()
+
+
+def test_a_table_with_no_rows_is_reported() -> None:
+    verdict = run("ledger-empty-table")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict,
+        "the ledger must hold a '| Date | Id | Area | Event | Refs |' table "
+        "with at least one entry",
+    ), verdict.render()
+
+
+# ------------------------------------------------------------- document present
+
+
+def test_a_missing_ledger_is_reported(tmp_path: pathlib.Path) -> None:
+    root = tmp_path / "repo"
+    (root / "plans").mkdir(parents=True)
+    (root / "plans" / "OTHER.md").write_text("# not the ledger\n", encoding="utf-8")
+    verdict = runner.run(ROW, root, ("plans/OTHER.md",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "required ledger is missing"), verdict.render()
+
+
+def test_a_document_without_the_header_is_not_a_ledger(tmp_path: pathlib.Path) -> None:
+    """The Markdown carrier of the old `schema_version: 1`: a table whose
+    columns are not this gate's columns is not recognised as a ledger."""
+    verdict = run_body(
+        tmp_path,
+        "# Ledger\n\n| When | Slug | Note |\n| --- | --- | --- |\n"
+        "| 2026-01-01 | an-entry | something happened |\n",
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict,
+        "the ledger must hold a '| Date | Id | Area | Event | Refs |' table "
+        "with at least one entry",
+    ), verdict.render()
+
+
+def test_a_header_without_its_delimiter_is_not_a_ledger(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        "# Ledger\n\n| Date | Id | Area | Event | Refs |\n"
+        "| 2026-01-01 | an-entry | docs | something happened | — |\n",
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict,
+        "the ledger must hold a '| Date | Id | Area | Event | Refs |' table "
+        "with at least one entry",
+    ), verdict.render()
+
+
+def test_a_row_with_the_wrong_cell_count_is_could_not_run(tmp_path: pathlib.Path) -> None:
+    """The Markdown analogue of a YAML entry that is not a mapping: a broken
+    document shape, not a graded finding about its content."""
+    verdict = run_body(tmp_path, table("| 2026-01-01 | an-entry | docs |"))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "row has 3 cells" in verdict.render()
+
+
+# --------------------------------------------------------------- per-row fields
+
+
+def test_a_duplicate_id_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table(
+            "| 2026-01-02 | same-entry | docs | the first use of this id | — |",
+            "| 2026-01-01 | same-entry | docs | the second use of this id | — |",
+        ),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[2].id: duplicate ID same-entry"), verdict.render()
+
+
+def test_a_future_date_is_reported(tmp_path: pathlib.Path) -> None:
+    tomorrow = (date.today() + timedelta(days=1)).isoformat()
+    verdict = run_body(
+        tmp_path, table(f"| {tomorrow} | tomorrows-entry | docs | not yet happened | — |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].date: cannot be in the future"), verdict.render()
+
+
+def test_rows_out_of_order_are_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table(
+            "| 2026-01-01 | older-entry | docs | the older event | — |",
+            "| 2026-01-02 | newer-entry | docs | the newer event, filed below it | — |",
+        ),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[2]: rows must be newest-first"), verdict.render()
+
+
+def test_an_empty_area_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path, table("| 2026-01-01 | an-entry |  | something happened | — |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].area: must be a non-empty string"), verdict.render()
+
+
+def test_an_empty_event_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(tmp_path, table("| 2026-01-01 | an-entry | docs |  | — |"))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(verdict, "row[1].event: must be a non-empty string"), verdict.render()
+
+
+def test_an_event_at_the_limit_passes(tmp_path: pathlib.Path) -> None:
+    """The boundary, so the limit cannot drift to 98 or 100 unnoticed."""
+    event = "e" * 99
+    verdict = run_body(tmp_path, table(f"| 2026-01-01 | an-entry | docs | {event} | — |"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ------------------------------------------------------------------------- refs
+
+
+def test_a_ref_that_is_not_inline_code_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | plans/LEDGER.md |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "row[1].refs: each reference must be inline code: plans/LEDGER.md",
+    ), verdict.render()
+
+
+def test_an_empty_ref_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | `plans/LEDGER.md`, `` |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "row[1].refs: references must be non-empty strings",
+    ), verdict.render()
+
+
+def test_an_absolute_ref_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | `/etc/hosts` |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "row[1].refs: reference must be repository-relative: /etc/hosts",
+    ), verdict.render()
+
+
+def test_a_uri_ref_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | `https://example.test/x` |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict,
+        "row[1].refs: reference must be repository-relative: https://example.test/x",
+    ), verdict.render()
+
+
+def test_a_ref_naming_no_real_path_is_reported(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | `plans/NOPE.md#anchor` |"),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "row[1].refs: missing or case-mismatched path: plans/NOPE.md#anchor",
+    ), verdict.render()
+
+
+def test_a_ref_with_an_anchor_onto_a_real_path_passes(tmp_path: pathlib.Path) -> None:
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | `plans/LEDGER.md#ledger` |"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# -------------------------------------------------------------- the inverted half
+
+
+def test_a_leftover_yaml_ledger_is_reported(tmp_path: pathlib.Path) -> None:
+    """INVERTED 2026-09-17. This gate used to REQUIRE `plans/LEDGER.yaml` and
+    report `plans/LEDGER.md` as "hard-cut Markdown ledger must be removed",
+    while LAY-006 listed `*/LEDGER.md` as an allowed markdown root. Markdown
+    won; YAML is now the form that has to go."""
+    verdict = run_body(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | — |"),
+        legacy="schema_version: 1\nentries: []\n",
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "superseded YAML ledger must be removed", path=LEGACY,
+    ), verdict.render()
+
+
+def test_a_markdown_ledger_alone_draws_no_legacy_finding() -> None:
+    """The half that reversed: `plans/LEDGER.md` is the ledger now, so its mere
+    presence must not produce a finding of any kind."""
+    verdict = run("ledger-clean")
+    assert not messages(verdict), verdict.render()
+
+
+# ------------------------------------------------------------------- wiring
+
+
+def test_a_redeclared_plans_tree_is_still_graded(tmp_path: pathlib.Path) -> None:
+    """The LOUD false-finding this check shipped with.
+
+    The ledger paths were hardcoded `plans/...` literals, opened as named
+    paths. A repository whose plans root is not the packaged default had its
+    real ledger fail that open, and `structural` reported "required ledger is
+    missing" -- a wrong, visible finding about a document that is right there,
+    just under a different root. Same corpus content as `ledger-violation`,
+    committed again under `roadmap/` instead of `plans/`: the same
+    non-kebab-case entry, wrongly invisible before the fix, caught after."""
+    root = tmp_path / "repo"
+    shutil.copytree(FIXTURES / "ledger-violation" / "plans", root / "roadmap")
+
+    trees = {"plans": "roadmap"}
+    document = yaml.safe_load(policy_text("gate-registry.yaml"))
+    registry = Registry.model_validate(document, context={"trees": trees})
+    row = registry.by_id("DOC-009")
+
+    verdict = runner.run(
+        row, root, ("roadmap/LEDGER.md",), trees=effective_trees(trees),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict, "row[1].id: must be lower-kebab-case", path="roadmap/LEDGER.md",
+    ), (
+        f"a real ledger under a redeclared plans root was reported missing "
+        f"instead of graded: {verdict.render()}"
+    )
+
+
+def test_no_set_is_could_not_run() -> None:
+    verdict = runner.run(ROW, FIXTURES / "ledger-clean", (), exhaustive=True)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+
+
+# --------------------------------------------------------------- freshness
+
+
+def _freshness_repo(tmp_path: pathlib.Path, ledger_body: str, plan_rel: str) -> pathlib.Path:
+    """A repo with a well-formed ledger and one other plan document, so the
+    freshness rule has a real plan to trigger on and a real ledger to check
+    for in the given set."""
+    root = tmp_path / "repo"
+    (root / "plans").mkdir(parents=True)
+    (root / "plans" / "LEDGER.md").write_text(ledger_body, encoding="utf-8")
+    plan_path = root / plan_rel
+    plan_path.parent.mkdir(parents=True, exist_ok=True)
+    plan_path.write_text("# a plan\n", encoding="utf-8")
+    return root
+
+
+def test_a_plan_changed_without_a_ledger_entry_is_reported(tmp_path: pathlib.Path) -> None:
+    """DOC-009 grades the ledger's shape but never its freshness (gap,
+    `plans/GAPS-AND-FINDINGS.md`): a plan changing with no ledger entry in
+    the same change used to pass every run."""
+    root = _freshness_repo(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | — |"),
+        "plans/features/az1-foo/spec.md",
+    )
+    verdict = runner.run(ROW, root, ("plans/features/az1-foo/spec.md",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert reported(
+        verdict,
+        f"plan changed without a {LEDGER} entry",
+        path="plans/features/az1-foo/spec.md",
+    ), verdict.render()
+
+
+def test_a_plan_changed_with_the_ledger_in_the_same_set_passes(tmp_path: pathlib.Path) -> None:
+    """Same violation on disk, but the ledger is also in the given set --
+    read as "the entry landed in this same change", the same proof
+    `docs.index-updated` (DOC-004) accepts for a catalog moving with its
+    pages."""
+    root = _freshness_repo(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | — |"),
+        "plans/features/az1-foo/spec.md",
+    )
+    verdict = runner.run(
+        ROW, root, ("plans/features/az1-foo/spec.md", "plans/LEDGER.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_plan_already_declared_by_being_the_only_change_is_not_reported(
+    tmp_path: pathlib.Path,
+) -> None:
+    """The ledger changing alone -- no other plan in the given set -- is not
+    a freshness violation; there is nothing it needed to catch up with."""
+    root = _freshness_repo(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | — |"),
+        "plans/features/az1-foo/spec.md",
+    )
+    verdict = runner.run(ROW, root, ("plans/LEDGER.md",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_whole_tree_run_with_no_change_set_is_could_not_run_not_a_false_pass(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A real plan sits on disk without a ledger entry -- exactly the
+    freshness violation above -- but no change set was given at all. This
+    must stay could-not-run, never read the empty set as "nothing changed,
+    so nothing to flag"."""
+    root = _freshness_repo(
+        tmp_path,
+        table("| 2026-01-01 | an-entry | docs | something happened | — |"),
+        "plans/features/az1-foo/spec.md",
+    )
+    verdict = runner.run(ROW, root, (), exhaustive=True)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()

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

@@ -0,0 +1,11 @@
+"""The `docs.markdown-ast` gate.
+
+A folder rather than a module because this gate grades Markdown documents in
+the given set, and its fixture corpora belong beside the check that reads them.
+"""
+
+from __future__ import annotations
+
+from .check import MarkdownAst
+
+__all__ = ["MarkdownAst"]

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

@@ -0,0 +1,84 @@
+"""DOC-005 — a Markdown page must not end inside an unterminated YAML front
+matter block or an unterminated fenced code block.
+
+Ported from `compliance_new/checks/docs/markdown-ast/check.sh`. That script
+scans each `.md`/`.mdx` file in the given set with a small line-by-line state
+machine, reproduced here exactly:
+
+    front matter   opens only when LINE 1 is exactly `---`; closes on a line
+                   that is exactly `---` or `...`. While open, fence lines are
+                   not inspected at all (the shell script's front-matter branch
+                   always `continue`s before reaching the fence checks).
+    fenced block   a line starting with three backticks toggles a backtick
+                   fence open/closed; a line starting with three tildes does
+                   the same for a tilde fence. A backtick line while a tilde
+                   fence is open (or vice versa) does not toggle anything —
+                   the two fence kinds do not close each other.
+
+Whichever state is still open at end of file is the finding. A file can carry
+at most one: front matter that never closed pre-empts fence scanning entirely
+for the rest of that file, so a fence opened after unterminated front matter
+is never reached, exactly as check.sh's `awk` script never reaches it either.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+
+
+class MarkdownAst(Check):
+    id: ClassVar[str] = "DOC-005"
+    rule: ClassVar[str] = "DOC-005"
+
+    FRONTMATTER_REASON: ClassVar[str] = "unterminated YAML front matter"
+    FRONTMATTER_FIX: ClassVar[str] = (
+        "add a closing --- (or ...) to terminate the YAML frontmatter block"
+    )
+    FENCE_REASON: ClassVar[str] = "unterminated fenced code block"
+    FENCE_FIX: ClassVar[str] = (
+        "add a closing fence (matching ``` or ~~~) to terminate the code block"
+    )
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        for path in sorted(files.with_suffix(".md", ".mdx")):
+            body = self.text(ctx, path)
+            if body is None:
+                continue
+            finding = self._scan(path, body)
+            if finding is not None:
+                yield finding
+
+    def _scan(self, path: str, body: str) -> Report | None:
+        front_matter = False
+        fence = ""
+        for line_no, line in enumerate(body.splitlines(), start=1):
+            if line_no == 1 and line == "---":
+                front_matter = True
+                continue
+            if front_matter:
+                if line == "---" or line == "...":
+                    front_matter = False
+                continue
+            if line.startswith("```"):
+                if fence == "":
+                    fence = "`"
+                elif fence == "`":
+                    fence = ""
+                continue
+            if line.startswith("~~~"):
+                if fence == "":
+                    fence = "~"
+                elif fence == "~":
+                    fence = ""
+                continue
+
+        if front_matter:
+            return self.report(path, self.FRONTMATTER_REASON, self.FRONTMATTER_FIX)
+        if fence:
+            return self.report(path, self.FENCE_REASON, self.FENCE_FIX)
+        return None

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/markdown_ast/fixtures/markdown-structure-bad-fence/docs/bad-fence.md

@@ -0,0 +1,2 @@
+```rust
+fn main() {}

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/markdown_ast/fixtures/markdown-structure-bad-fence/docs/valid.md

@@ -0,0 +1,5 @@
+---
+title: valid
+---
+
+Prose only.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/markdown_ast/fixtures/markdown-structure-bad-frontmatter/docs/bad-front-matter.md

@@ -0,0 +1,2 @@
+---
+title: invalid

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/markdown_ast/fixtures/markdown-structure-bad-frontmatter/docs/valid.md

@@ -0,0 +1,5 @@
+---
+title: valid
+---
+
+Prose only.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/markdown_ast/fixtures/markdown-structure-clean/docs/valid.md

@@ -0,0 +1,7 @@
+---
+title: valid
+---
+
+```rust
+fn main() {}
+```

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

@@ -0,0 +1,126 @@
+"""DOC-005 — ported from `compliance_new/checks/docs/markdown-ast/test.sh`.
+
+Same three fixtures, copied verbatim from the shell tree's committed corpus
+(`fixtures/markdown-structure-clean`, `fixtures/markdown-structure-bad-frontmatter`,
+`fixtures/markdown-structure-bad-fence`): the shell test asserted exit 0 with no
+finding on the clean corpus, exactly one `DOC-005` finding naming the offending
+page (and none for `docs/valid.md` beside it) on each violation corpus, and
+that reported paths never reach outside the corpus. Proven here the same way.
+
+This check is intentionally NOT wired into `checks/__init__.py` yet (a
+separate step wires this whole wave's checks into the registry in one shot, to
+avoid concurrent edits to that shared file), so these tests call
+`MarkdownAst.graded` directly against a hand-built `Context`/`FileSet` rather
+than going through `runner.run`/`checks.lookup` — the same bypass
+`typescript/no_eval/test_check.py`'s `graded_directly` uses to exercise a rule
+without depending on registry wiring. This remains valid once the wiring
+lands: it is the check's own rule logic being exercised, not the dispatch path.
+
+The shell test's fifth case — no `ADL_CHANGED_FILES` set, asserting exit 2 —
+has no analog here: `graded` always receives an explicit `FileSet`, so "handed
+nothing to grade" is an empty/non-matching set, which is a clean no-op (see the
+last scenario test below), not a could-not-run. That is a property of this
+framework's dispatch contract (there is no unset-environment-variable state),
+not something this check re-invents.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance.checks.docs.markdown_ast import MarkdownAst
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.verdict import Outcome, decide
+from adl_compliance.policy.registry import load
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+CLEAN = FIXTURES / "markdown-structure-clean"
+BAD_FRONTMATTER = FIXTURES / "markdown-structure-bad-frontmatter"
+BAD_FENCE = FIXTURES / "markdown-structure-bad-fence"
+ROW = load().by_id("DOC-005")
+
+
+def graded(root: pathlib.Path, paths: tuple[str, ...]):
+    ctx = Context(root=root, row=ROW)
+    findings = tuple(MarkdownAst().graded(ctx, FileSet(paths=paths)))
+    return decide(ROW, findings, 0, ())
+
+
+def test_the_row_declares_the_gate_this_check_ports() -> None:
+    assert ROW.domain == "docs"
+    assert ROW.name == "markdown-ast"
+
+
+def test_a_page_whose_frontmatter_and_fence_both_close_is_silent() -> None:
+    verdict = graded(CLEAN, ("docs/valid.md",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+def test_unterminated_front_matter_is_reported() -> None:
+    verdict = graded(BAD_FRONTMATTER, ("docs/bad-front-matter.md", "docs/valid.md"))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert len(verdict.findings) == 1
+    finding = verdict.findings[0]
+    assert finding.rule == "DOC-005"
+    assert finding.path == "docs/bad-front-matter.md"
+    assert finding.message == "unterminated YAML front matter"
+
+
+def test_only_the_offending_page_is_reported_not_the_well_formed_one_beside_it() -> None:
+    """The bad-frontmatter corpus carries a well-formed `docs/valid.md` beside
+    the broken page, proving the gate reports the offender, not everything it
+    read."""
+    verdict = graded(BAD_FRONTMATTER, ("docs/bad-front-matter.md", "docs/valid.md"))
+    assert all(f.path != "docs/valid.md" for f in verdict.findings)
+
+
+def test_unterminated_fenced_code_block_is_reported() -> None:
+    verdict = graded(BAD_FENCE, ("docs/bad-fence.md", "docs/valid.md"))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert len(verdict.findings) == 1
+    finding = verdict.findings[0]
+    assert finding.rule == "DOC-005"
+    assert finding.path == "docs/bad-fence.md"
+    assert finding.message == "unterminated fenced code block"
+
+
+def test_only_the_offending_fence_page_is_reported_not_the_well_formed_one_beside_it() -> None:
+    verdict = graded(BAD_FENCE, ("docs/bad-fence.md", "docs/valid.md"))
+    assert all(f.path != "docs/valid.md" for f in verdict.findings)
+
+
+def test_every_reported_path_is_actually_in_the_corpus() -> None:
+    """Isolation proof mirrored from test.sh: a gate that resolved a
+    repository root instead of grading the directory it was pointed at would
+    name paths outside the corpus here."""
+    verdict = graded(BAD_FENCE, ("docs/bad-fence.md", "docs/valid.md"))
+    for finding in verdict.findings:
+        assert (BAD_FENCE / finding.path).is_file()
+
+
+def test_a_file_outside_the_given_set_is_not_graded() -> None:
+    """The bad-fence corpus is unchanged on disk and still broken, but only
+    the well-formed page is in the given set, so there is nothing to grade."""
+    verdict = graded(BAD_FENCE, ("docs/valid.md",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_no_markdown_files_in_the_given_set_is_a_clean_no_op_not_could_not_run() -> None:
+    """See the module docstring: this framework represents "handed nothing to
+    grade" as an empty/non-matching file set, which is clean here rather than
+    the shell gate's exit-2 could-not-run for an unset `ADL_CHANGED_FILES`."""
+    verdict = graded(BAD_FENCE, ())
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_non_markdown_file_in_the_given_set_is_not_this_gates_subject_matter() -> None:
+    """`with_suffix(".md", ".mdx")` narrows to Markdown; anything else in the
+    set is not this check's concern even if present."""
+    findings = tuple(
+        MarkdownAst().graded(
+            Context(root=BAD_FENCE, row=ROW),
+            FileSet(paths=("docs/bad-fence.md", "docs/not-markdown.txt")),
+        )
+    )
+    assert all(f.path != "docs/not-markdown.txt" for f in findings)