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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/cli.py

@@ -0,0 +1,483 @@
+"""The argv surface, and the ONLY module that reads the environment or calls git.
+
+Everything below this file receives what it needs as an argument. That is the
+whole of what "fully abstract" means here: there is exactly one place where the
+outside world gets in, and it is this one. `grep -rn 'os.environ' src/` returns
+these lines and nothing else.
+
+The third term of the applicable-scope formula — *minus what git cannot see* —
+is the CONSUMER's, and the consumer is this file. `git ls-files --cached
+--others --exclude-standard` is called here so that gitignored paths never enter
+a set, which is why no row needs to exclude `node_modules/` or `.scratch/`, and
+why no check needs to know git exists (K-41).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tomllib
+from collections.abc import Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import TextIO
+
+import yaml
+from pydantic import ValidationError
+
+from . import runner
+from .core.constants import Constants
+from .core.receipt import from_verdict
+from .core.verdict import Outcome, Verdict
+from .policy.registry import (
+    Registry,
+    RegistryError,
+    Row,
+    effective_trees,
+    load,
+    policy_text,
+)
+from .providers import PROVIDERS
+
+
+def find_root(explicit: str | None) -> Path:
+    """The repository being graded. Resolved once, here, and passed down.
+
+    Three sources, in order, and the first that answers wins. The shell tree had
+    four mechanisms answering this and they disagreed; the point is not which
+    order is right but that the question is asked in one place.
+    """
+    if explicit:
+        return Path(explicit).resolve()
+    from_environment = os.environ.get("ANALYSIS_PROJECT_ROOT")
+    if from_environment:
+        return Path(from_environment).resolve()
+    for candidate in (Path.cwd(), *Path.cwd().parents):
+        if (candidate / ".git").exists():
+            return candidate
+    raise SystemExit("adl-compliance: not inside a git repository, and no --root given")
+
+
+def visible_files(root: Path) -> tuple[str, ...]:
+    """Everything git can see, repository-relative. The caller's set.
+
+    `-c core.quotePath=false`, not left to the caller's ambient config
+    (Tarun, 2026-09-27, decision 3): left on git's own default (unset,
+    which behaves as quoting ON), a non-ASCII filename comes back
+    octal-escaped and double-quoted -- a filename this function returns as
+    a member of the given set, not something downstream ever unquotes. That
+    corrupted path then fails every prefix/root check this package does
+    (root-file detection, tree membership, doc-path matching), silently:
+    the file is simply invisible to those checks under its real name. This
+    must not depend on the checkout's own `core.quotePath` being set
+    correctly -- the function is not fully abstract otherwise (see the
+    module docstring's "one place the outside world gets in").
+    """
+    completed = subprocess.run(
+        ["git", "-c", "core.quotePath=false", "ls-files", "--cached", "--others", "--exclude-standard"],
+        cwd=root, capture_output=True, text=True, check=False,
+    )
+    if completed.returncode != 0:
+        raise SystemExit(f"adl-compliance: git ls-files failed: {completed.stderr.strip()}")
+    return tuple(line for line in completed.stdout.splitlines() if line)
+
+
+def selected_rows(
+    registry: Registry, target: str | None, only: Sequence[str] | None = None
+) -> list[Row]:
+    """Rows to grade. `only` selects by gate id (`RST-001`), `domain.name` address
+    (`rust.acp-boundary`), or a whole `domain` (`layout`).
+
+    An entry matching no row is a hard error, never a silent narrowing: a selector
+    that selects nothing is indistinguishable from a clean run, so a typo'd or
+    renamed id would report success while grading absolutely nothing. That is the
+    same "selects nothing, passes quietly" failure K-13 and K-21 record for scope
+    globs and prefix filters, arriving here through the selection list instead.
+    """
+    if only:
+        matched: dict[str, list[Row]] = {entry: [] for entry in only}
+        for row in registry.rows:
+            for entry in only:
+                if row.id == entry or row.address == entry or row.domain == entry:
+                    matched[entry].append(row)
+        unmatched = sorted(entry for entry, rows in matched.items() if not rows)
+        if unmatched:
+            known = ", ".join(sorted({row.domain for row in registry.rows}))
+            raise RegistryError(
+                f"selection matches no gate: {', '.join(unmatched)} "
+                f"(expected a gate id, a domain.name address, or one of these domains: {known})"
+            )
+        chosen = {row.id for rows in matched.values() for row in rows}
+        return [row for row in registry.rows if row.id in chosen]
+    if target is None:
+        return list(registry.rows)
+    return [registry.resolve(target)]
+
+
+def read_trees_file(path: str) -> dict[str, str]:
+    """A per-repo `[trees]` override, the same shape as the packaged
+    `policy/config.toml` — read here because this is the one module allowed to
+    read a file outside the package."""
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RegistryError(f"{path} could not be read: {exc}") from exc
+    try:
+        document = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise RegistryError(f"{path} is not valid TOML: {exc}") from exc
+    trees = document.get("trees")
+    if not isinstance(trees, dict):
+        raise RegistryError(f"{path} has no [trees] table")
+    return trees
+
+
+def load_registry(
+    registry_file: str,
+    trees_file: str | None,
+    tree_overrides: Mapping[str, str] | None = None,
+) -> Registry:
+    """`policy.registry.load`'s cached, package-only path when there is no
+    override; otherwise the same parse, validated with the trees override as
+    `context`, so `EngineSpec`/`Row`'s `<tree>` resolution sees it (Task 4)."""
+    if trees_file is None and not tree_overrides:
+        return load(registry_file)
+    # A file and flags compose: the file is the base, flags win per key, which is
+    # the same precedence `[controls.compliance.trees]` has over the packaged default.
+    trees = read_trees_file(trees_file) if trees_file else {}
+    trees.update(tree_overrides or {})
+    try:
+        document = yaml.safe_load(policy_text(registry_file))
+    except yaml.YAMLError as exc:
+        raise RegistryError(f"{registry_file} is not valid YAML: {exc}") from exc
+    try:
+        return Registry.model_validate(document, context={"trees": trees})
+    except ValidationError as exc:
+        raise RegistryError(f"{registry_file} violates its schema:\n{exc}") from exc
+
+
+def report(verdict: Verdict, stream: TextIO | None = None, errors: TextIO | None = None) -> None:
+    """Findings to stdout, advisories to stderr.
+
+    The streams default to None and are resolved HERE, not in the signature.
+    `stream=sys.stdout` as a default binds the object that existed at import
+    time, so anything that replaces the stream afterwards — a test harness, a
+    redirect, a caller wrapping the run — is silently written past.
+    """
+    out = sys.stdout if stream is None else stream
+    err = sys.stderr if errors is None else errors
+    for advisory in verdict.advisories:
+        print(advisory.render(), file=err)
+    print(verdict.render(), file=out)
+
+
+def tally(verdicts: Sequence[Verdict]) -> str:
+    """The counts, so a log's first line says what the run actually covered."""
+    passed = sum(1 for v in verdicts if v.outcome is Outcome.CLEAN)
+    failed = sum(1 for v in verdicts if v.outcome is Outcome.FINDINGS)
+    errored = sum(1 for v in verdicts if v.outcome is Outcome.COULD_NOT_RUN)
+    return f"{len(verdicts)} row(s): {passed} pass, {failed} fail, {errored} error"
+
+
+def write_logs(directory: Path, verdicts: Sequence[Verdict]) -> tuple[Path, Path]:
+    """Two files, because they answer two questions.
+
+    `all.log` is the sweep: one line per row, pass and fail alike, so a row that
+    was never reached stays distinguishable from one that came back clean.
+
+    `failures.log` is the work list: the same line for every non-clean row,
+    followed by its findings indented beneath it.
+
+    Both open with a `#` tally line even when there is nothing to report. An
+    empty file cannot tell "nothing failed" from "the run never happened", and
+    that is the exact confusion this estate keeps paying for.
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+
+    header = f"# {tally(verdicts)}"
+    all_path = directory / Constants.ALL_LOG
+    all_path.write_text(
+        "\n".join([header, *(v.summary() for v in verdicts)]) + "\n", encoding="utf-8"
+    )
+
+    failing = [v for v in verdicts if v.outcome is not Outcome.CLEAN]
+    lines = [f"# {len(failing)} of {len(verdicts)} row(s) did not pass"]
+    for verdict in failing:
+        lines.append(verdict.summary())
+        lines.extend(f"    {f.render()}" for f in verdict.findings)
+    failures_path = directory / Constants.FAILURES_LOG
+    failures_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    return all_path, failures_path
+
+
+def write_receipts(directory: Path, verdicts: Sequence[Verdict], *, exhaustive: bool) -> Path:
+    """C1: one `core.receipt.Receipt` per row, JSONL, alongside the two logs.
+
+    `exhaustive` is the one fact `write_logs` never needed and this does: it is
+    what tells `from_verdict` a zero-unit PASS apart as dead-scope (impossible,
+    and a hard error) from narrowed-and-irrelevant (a legitimate receipt). The
+    same value `main` already threads through every `runner.run` call for
+    exactly this reason.
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+    receipts_path = directory / Constants.RECEIPTS_LOG
+    lines = [
+        from_verdict(verdict, exhaustive=exhaustive).model_dump_json() for verdict in verdicts
+    ]
+    receipts_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+    return receipts_path
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="adl-compliance")
+    parser.add_argument(
+        "target", nargs="?",
+        help="a gate id (RST-001) or address (rust.acp-boundary); omit to run every row",
+    )
+    parser.add_argument("--root", help="the repository to grade (default: the enclosing checkout)")
+    parser.add_argument(
+        "--files", metavar="LIST",
+        help="a file holding the caller's set, one repository-relative path per line. "
+             "Omit to grade everything git can see.",
+    )
+    parser.add_argument(
+        "--exhaustive", action="store_true",
+        help="declare that --files is the complete visible tree. Used for a staged "
+             "index snapshot that intentionally has no .git directory; an empty "
+             "row scope is therefore could-not-run, never an unrelated partial set.",
+    )
+    parser.add_argument(
+        "--summary", action="store_true",
+        help="one line per gate instead of every finding",
+    )
+    parser.add_argument(
+        "--log-dir", metavar="DIR",
+        help=f"write {Constants.ALL_LOG} (every row) and {Constants.FAILURES_LOG} "
+             "(non-clean rows and their findings) into DIR",
+    )
+    parser.add_argument(
+        "--only", action="append", metavar="IDS-OR-ADDRESSES",
+        help="a gate id or <domain>.<name> address, or a comma-separated list of "
+             "either; repeatable. When given, replaces target/every-row selection "
+             "with exactly the named rows.",
+    )
+    parser.add_argument(
+        "--registry-file", metavar="FILENAME", default="gate-registry.yaml",
+        help="the packaged registry document to load (default: gate-registry.yaml)",
+    )
+    parser.add_argument(
+        "--input", metavar="GATE:NAME=PATH", action="append", default=[],
+        help="override a check's named input, repository-relative (repeatable). "
+             "A check declares logical names -- `orchestrator`, `registry` -- and a "
+             "declared default is otherwise the only value, so a gate whose input "
+             "names one repository's file cannot run anywhere else.",
+    )
+    parser.add_argument(
+        "--jobs", type=int, default=0, metavar="N",
+        help="grade N rows concurrently (default: one per CPU). `--jobs 1` forces "
+             "sequential, which is what a failing run wants when a check's own "
+             "subprocess output needs reading. Output order is the registry's "
+             "either way, never completion order.",
+    )
+    parser.add_argument(
+        "--declare", metavar="NAME=VALUE", action="append", default=[],
+        help="a fact the repository states about itself, as `license=Proprietary` "
+             "(repeatable). Read from [controls.compliance] and passed through: the "
+             "package grades a repository against what it declares, it does not hold "
+             "the answer. `license` is the only name consumed today (REP-001).",
+    )
+    parser.add_argument(
+        "--tree", metavar="NAME=PATH", action="append", default=[],
+        help="override one logical tree, as `rust=backend` (repeatable). The flag "
+             "form of --trees-file, so a caller holding the mapping in its own config "
+             "need not write a temporary TOML file to pass it.",
+    )
+    parser.add_argument(
+        "--trees-file", metavar="PATH.TOML",
+        help="a [trees] table overriding the packaged policy/config.toml, per key "
+             "(a key absent from it still resolves through the packaged default)",
+    )
+    args = parser.parse_args(argv)
+    if args.exhaustive and not args.files:
+        parser.error("--exhaustive requires --files")
+
+    # NAME=PATH pairs, repository-relative. Resolved against `root` below, beside
+    # every other input, so an override and a default reach the check identically.
+    # GATE:NAME=PATH. An override belongs to one gate: a flat map reached every
+    # row and made one declaration break every other check (see
+    # `resolve_inputs`).
+    overrides: dict[str, dict[str, str]] = {}
+    global_inputs: dict[str, str] = {}
+    for pair in args.input:
+        addressed, sep, value = pair.partition("=")
+        # Two accepted forms:
+        #   GATE:NAME=PATH  -- per-gate override (rare; useful for tests)
+        #   NAME=PATH       -- global input; applies to every gate sharing the
+        #                       same BatchProvider. This is the common case
+        #                       (`[controls.compliance.inputs]` is global).
+        if ":" in addressed:
+            gate, gate_sep, name = addressed.partition(":")
+            if not sep or not gate_sep or not gate.strip() or not name.strip() or not value.strip():
+                parser.error(f"--input expects GATE:NAME=PATH or NAME=PATH, got {pair!r}")
+            overrides.setdefault(gate.strip(), {})[name.strip()] = value.strip()
+        else:
+            if not sep or not addressed.strip() or not value.strip():
+                parser.error(f"--input expects GATE:NAME=PATH or NAME=PATH, got {pair!r}")
+            global_inputs[addressed.strip()] = value.strip()
+
+    declarations: dict[str, str] = {}
+    for pair in args.declare:
+        name, sep, value = pair.partition("=")
+        if not sep or not name.strip() or not value.strip():
+            parser.error(f"--declare expects NAME=VALUE, got {pair!r}")
+        declarations[name.strip()] = value.strip()
+
+    tree_overrides: dict[str, str] = {}
+    for pair in args.tree:
+        name, sep, value = pair.partition("=")
+        # `--tree specs=` with an EMPTY path is legal and meaningful: the
+        # repository declaring it has no such tree. An undeclared tree is
+        # could-not-run, because silence could equally mean "we have one and
+        # forgot to say" -- this is the owner answering. A missing `=` or a
+        # blank NAME is still an error.
+        if not sep or not name.strip():
+            parser.error(f"--tree expects NAME=PATH, got {pair!r}")
+        tree_overrides[name.strip()] = value.strip()
+
+    only = (
+        tuple(item.strip() for group in args.only for item in group.split(",") if item.strip())
+        if args.only
+        else None
+    )
+
+    # The same precedence `load_registry` applies to scope patterns, through the
+    # same function, so both surfaces resolve a placeholder identically.
+    declared_trees = dict(read_trees_file(args.trees_file)) if args.trees_file else {}
+    declared_trees.update(tree_overrides)
+    resolved_trees = effective_trees(declared_trees)
+
+    root = find_root(args.root)
+    try:
+        registry = load_registry(args.registry_file, args.trees_file, tree_overrides)
+        rows = selected_rows(registry, args.target, only)
+    except RegistryError as exc:
+        print(f"adl-compliance: {exc}", file=sys.stderr)
+        return int(Outcome.COULD_NOT_RUN)
+
+    if args.files:
+        given = tuple(
+            line for line in Path(args.files).read_text(encoding="utf-8").splitlines() if line
+        )
+        exhaustive = args.exhaustive
+        universe = given if exhaustive else visible_files(root)
+    else:
+        given = visible_files(root)
+        exhaustive = True
+        universe = given
+
+    # Expand global inputs to every batch-check row. The runner sees a
+    # per-gate map; a global declaration from `[controls.compliance.inputs]`
+    # (or `--input NAME=PATH`) is a declaration that applies to every gate
+    # sharing a BatchProvider, so we materialize that here. Non-batch rows
+    # (each owning its own per-gate input surface) are NEVER seeded with
+    # global inputs — passing `ui_bases` to TS-017, for instance, fails it as
+    # an unknown input and rolls every doc/typescript/layout gate back to
+    # could-not-run. The contract is: a gate's `inputs` class attribute is
+    # the authority on what it consumes; global inputs route only to rows
+    # that consume them (i.e. BatchCheck rows whose class names them).
+    from .checks import lookup
+    from .core.check import BatchCheck
+    inputs_by_gate: dict[str, dict[str, str]] = {gate: dict(names) for gate, names in overrides.items()}
+    for row in rows:
+        try:
+            check_class = lookup(row.id)
+        except KeyError:
+            continue
+        if not issubclass(check_class, BatchCheck):
+            continue
+        gate_inputs = inputs_by_gate.setdefault(row.id, {})
+        for name, value in global_inputs.items():
+            gate_inputs.setdefault(name, value)
+    resolved_inputs_by_gate: dict[str, dict[str, Path]] | None = None
+    if inputs_by_gate:
+        resolved_inputs_by_gate = {
+            gate: {name: root / value for name, value in names.items()}
+            for gate, names in inputs_by_gate.items()
+        }
+
+    batch_results = runner.prepare_batches(
+        rows,
+        root,
+        given,
+        exhaustive=exhaustive,
+        universe=universe,
+        trees=resolved_trees,
+        declared_trees=declared_trees,
+        inputs=resolved_inputs_by_gate,
+        providers=PROVIDERS,
+    )
+
+    def grade(row: Row) -> Verdict:
+        return runner.run(
+            row, root, given, exhaustive=exhaustive, universe=universe,
+            inputs=resolved_inputs_by_gate,
+            declarations=declarations,
+            trees=resolved_trees,
+            # The UNDILUTED map -- what this repository actually declared, with
+            # no packaged defaults merged in. `trees` above is the merged one,
+            # used for scope; these two must never converge. A check's INPUT
+            # resolving against a packaged default is how TS-001 graded zero
+            # files in four repositories and reported PASS. Owner ruling: the
+            # gate runs, `adl-config.toml` decides.
+            declared_trees=declared_trees,
+            batch_results=batch_results,
+        )
+
+    # Threads, not processes. Nearly every check is I/O or a subprocess
+    # (`ast-grep`, `just`, `cargo`, reading files), and CPython releases the GIL
+    # for both — so threads get the parallelism without paying to pickle a Row
+    # and a FileSet to a worker, and without the import cost of a fresh
+    # interpreter per gate. A check that is genuinely CPU-bound in Python would
+    # not scale here; none is today.
+    #
+    # Results are collected in REGISTRY ORDER regardless of completion order:
+    # a gate report whose line order shifts run to run is unreadable and makes
+    # two runs impossible to diff.
+    jobs = args.jobs if args.jobs > 0 else (os.cpu_count() or 1)
+    if jobs == 1 or len(rows) < 2:
+        verdicts_by_row = [grade(row) for row in rows]
+    else:
+        with ThreadPoolExecutor(max_workers=jobs) as pool:
+            verdicts_by_row = list(pool.map(grade, rows))
+
+    verdicts: list[Verdict] = []
+    worst = Outcome.CLEAN
+    for verdict in verdicts_by_row:
+        verdicts.append(verdict)
+        if args.summary:
+            # Advisories still go to stderr: --summary narrows stdout, it does
+            # not suppress a warning nobody has seen yet.
+            for advisory in verdict.advisories:
+                print(advisory.render(), file=sys.stderr)
+            print(verdict.summary())
+        else:
+            report(verdict)
+        worst = max(worst, verdict.outcome)
+
+    if args.log_dir:
+        all_path, failures_path = write_logs(Path(args.log_dir), verdicts)
+        receipts_path = write_receipts(Path(args.log_dir), verdicts, exhaustive=exhaustive)
+        print(
+            f"adl-compliance: wrote {all_path}, {failures_path} and {receipts_path}",
+            file=sys.stderr,
+        )
+
+    return int(worst)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/__init__.py

@@ -0,0 +1 @@
+"""core."""

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/core/ast_grep.py

@@ -0,0 +1,199 @@
+"""Shared base for `engine.rule` gates: dispatch to the real `ast-grep` CLI.
+
+Ten of the twenty-two rule-engine rows in `policy/gate-registry.yaml` have no
+`check.sh` at all in the shell tree (`compliance_new/`) — their rule logic
+lives entirely in an ast-grep `RuleConfig` YAML, dispatched through
+`compliance_new/checks/framework/_rule-check.sh`'s `rule_check()`/`rule_hits()`
+helpers. `RST-001` (`AcpBoundary`) already proved the shape a Python port of
+that dispatch takes: shell to a packaged `sgconfig.yml`, parse the
+`--json=stream` output, turn each match into a `Finding`. This module is that
+shape, extracted so a single-rule gate declares data, not a subprocess call.
+
+A concrete check declares three things and nothing else:
+
+    rule_ids     the ast-grep rule id(s) in the packaged config this gate
+                 grades. More than one only when a single gate is genuinely
+                 graded by several rule documents together (e.g. a `.ts`
+                 document and its `.tsx` sibling) — `--filter` is built as one
+                 anchored alternation, so that stays one subprocess call.
+    extensions   which of the GIVEN file set are this rule's subject matter.
+                 This is not scope (AGENTS.md "Applicable scope"): the runner
+                 already narrowed the set through the row's `engine.scope`
+                 before this class ever sees it. `extensions` answers "which
+                 of these files does this rule's parser apply to" — the same
+                 question `language:` answers on the YAML side, and the two
+                 must agree, since `.ts` is not `.tsx` (AGENTS.md "language:
+                 is per parser").
+    rule         (inherited from `Check`) the id reported on the Finding.
+
+and may override `message_for`/`fix_for` to phrase a finding better than the
+rule document's own generic `message:`/`note:` fields, without touching the
+query itself. **The query is never reimplemented** — every subclass runs the
+one packaged `sgconfig.yml` this class resolves via `importlib.resources`
+(K-16, K-40): a rule YAML is read from where it already lives as package data,
+copied in verbatim, never hand-transcribed as a Python pattern.
+
+ast-grep is handed a FILE LIST, never a directory, and no `--globs` — the two
+must never be mixed (AGENTS.md "Handing a set to ast-grep": `ast-grep` skips
+glob filtering entirely for a path named on the command line). The narrowing
+is already complete by the time `graded` runs; this only picks out the subject
+matter.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from collections.abc import Iterable, Iterator, Sequence
+from contextlib import ExitStack
+from importlib import resources
+from typing import ClassVar
+
+from .check import Check
+from .context import Context, FileSet
+from .errors import CouldNotRun
+from .finding import Report
+from .models import OpenModel
+
+# A `// biome-ignore <rule>: <reason>` marker. `<reason>` is optional in the
+# GRAMMAR (a bare marker parses) but not in what gets HONOURED — owner ruling:
+# "if it's legitimate, own it", so group(2) is inspected for emptiness by the
+# caller rather than being made mandatory here and rejecting the bare form
+# outright, which would turn "not owned" into "not even a suppression".
+_BIOME_IGNORE = re.compile(r"^\s*//\s*biome-ignore\s+(\S+)(?::\s*(.*))?\s*$")
+_COMMENT_LINE = re.compile(r"^\s*//")
+
+
+class AstGrepRange(OpenModel):
+    """Open, like every model over ast-grep's own output: it emits `column`
+    and `byteOffset` here too, and forbidding fields this package ignores
+    would break the gate on ast-grep's next release rather than on a real
+    defect."""
+
+    line: int = 0
+
+
+class AstGrepSpan(OpenModel):
+    start: AstGrepRange = AstGrepRange()
+
+
+class AstGrepMatch(OpenModel):
+    """One `--json=stream` record. Open for the same reason as `AstGrepSpan`."""
+
+    file: str
+    ruleId: str = ""  # noqa: N815 — the wire name
+    message: str = ""
+    note: str | None = None
+    range: AstGrepSpan = AstGrepSpan()
+
+
+class AstGrepCheck(Check):
+    """One or more ast-grep rule ids, graded against the given file set."""
+
+    requires: ClassVar[tuple[str, ...]] = ("ast-grep",)
+
+    rule_ids: ClassVar[tuple[str, ...]] = ()
+    """The rule id(s) in the packaged config this gate grades. Declared, never
+    the empty default a real subclass would run with — `_scan` refuses to
+    build a filter that matches everything when this is unset (K-13: a
+    positive glob matching nothing excludes everything, and the same failure
+    mode applies to an unfiltered `--filter` matching everything)."""
+
+    extensions: ClassVar[tuple[str, ...]] = ()
+    """Which of the GIVEN files are this rule's subject matter. Not scope —
+    the row's `engine.scope` already narrowed the set; this narrows it again
+    by file KIND, the same distinction `language:` draws on the YAML side."""
+
+    SGCONFIG_PACKAGE: ClassVar[str] = "adl_compliance.rules"
+    SGCONFIG_NAME: ClassVar[str] = "sgconfig.yml"
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        corpus = sorted(
+            path for path in files.existing(ctx.root) if path.endswith(self.extensions)
+        )
+        if not corpus:
+            return
+        for match in self._scan(ctx, corpus):
+            if self._is_owned_suppression(ctx, match):
+                continue
+            yield self.report(
+                match.file,
+                self.message_for(match),
+                self.fix_for(match),
+                rule=self.rule_for(match),
+                line=match.range.start.line + 1,
+            )
+
+    def _is_owned_suppression(self, ctx: Context, match: AstGrepMatch) -> bool:
+        """Owner ruling on TS-013's two `enact-m5` findings: "if it's
+        legitimate, own it" / "no exception". Synthesised into one mechanism
+        for every `engine.rule` row, not one gate's patch: a match is skipped
+        only when the row DECLARES an equivalent biome rule (`engine.
+        suppression`) and the match is immediately preceded — allowing a
+        multi-line comment continuation — by a `// biome-ignore <rule>:
+        <reason>` comment naming that same rule with a non-empty reason. A
+        bare marker, a different rule, a non-adjacent comment, or no declared
+        equivalence at all honours nothing.
+        """
+        equivalent = ctx.row.engine.suppression
+        if not equivalent:
+            return False
+        body = self.text(ctx, match.file)
+        if body is None:
+            return False
+        lines = body.splitlines()
+        index = match.range.start.line - 1  # the line immediately above the match
+        while index >= 0 and _COMMENT_LINE.match(lines[index]):
+            found = _BIOME_IGNORE.match(lines[index])
+            if found:
+                rule, reason = found.group(1), found.group(2)
+                return rule == equivalent and bool(reason and reason.strip())
+            index -= 1
+        return False
+
+    def rule_for(self, match: AstGrepMatch) -> str:
+        """The id reported on the Finding. Defaults to this gate's own
+        `self.rule`; override for a per-ast-grep-rule-id mapping the way
+        `AcpBoundary.ACP_CODE` does when one gate spans several rule ids."""
+        return self.rule or match.ruleId
+
+    def message_for(self, match: AstGrepMatch) -> str:
+        """The rule document's own `message:`. Override to phrase a finding
+        specific to this gate rather than the query's generic wording."""
+        return match.message
+
+    def fix_for(self, match: AstGrepMatch) -> str:
+        """The rule document's own `note:`, or a generic fallback. Override
+        for remediation text specific to this gate."""
+        return match.note or f"fix the flagged construct per {match.ruleId}"
+
+    def _scan(self, ctx: Context, corpus: Sequence[str]) -> Iterator[AstGrepMatch]:
+        if not self.rule_ids:
+            raise CouldNotRun(f"{type(self).__name__} declares no rule_ids")
+        rule_filter = "^(" + "|".join(self.rule_ids) + ")$"
+        with ExitStack() as stack:
+            config = stack.enter_context(
+                resources.as_file(resources.files(self.SGCONFIG_PACKAGE) / self.SGCONFIG_NAME)
+            )
+            completed = subprocess.run(
+                [
+                    "ast-grep", "scan", "--config", str(config),
+                    "--filter", rule_filter, "--json=stream", *corpus,
+                ],
+                cwd=ctx.root, capture_output=True, text=True, check=False,
+            )
+        # ast-grep's own exit status carries no verdict of its own: 0 whether
+        # or not an info/warning rule matched, and NONZERO whenever an
+        # error-severity rule matched (AGENTS.md, K-22) — so only >1 means the
+        # tool itself broke rather than a real match. A tool failure is never
+        # a finding (F-05).
+        if completed.returncode > 1:
+            raise CouldNotRun(
+                f"ast-grep exited {completed.returncode} scanning {len(corpus)} file(s): "
+                f"{completed.stderr.strip()}"
+            )
+        for line in completed.stdout.splitlines():
+            if not line.strip():
+                continue
+            yield AstGrepMatch.model_validate(json.loads(line))