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

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

@@ -0,0 +1,52 @@
+"""Execution-scoped input and output for checks sharing one analyzer process.
+
+The provider is an optimization boundary, not a second rule engine. It receives
+the exact ``FileSet`` already selected for every participating row and returns
+the same ``Finding``/``Advisory`` records an ordinary ``Check`` would yield.
+The normal runner still owns grants, verdicts, rendering and exit status.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from .context import FileSet
+from .finding import Report
+
+
+@dataclass(frozen=True)
+class BatchRequest:
+    root: Path
+    files_by_gate: dict[str, FileSet]
+    ui_tree: str | None = None
+    inputs: dict[str, Path] = field(default_factory=dict)
+    """Named inputs from `[controls.compliance.inputs]`, already resolved to
+    absolute paths by the runner. Globs (e.g. `<ui>/...*-base.svelte`) are NOT
+    expanded here -- the analyzer expands them against `ui_tree`, so the gate
+    sees the live file set instead of a snapshot taken at scope-build time."""
+
+    @property
+    def files(self) -> tuple[str, ...]:
+        """The ordered union a parser may load once for all selected rules."""
+        return tuple(sorted({path for files in self.files_by_gate.values() for path in files}))
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    reports: tuple[Report, ...] = ()
+    error: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.error == "":
+            raise ValueError("a batch error must explain why the analyzer could not run")
+        if self.error is not None and self.reports:
+            raise ValueError("a batch result cannot contain reports and an execution error")
+
+
+class BatchProvider(Protocol):
+    def run(self, request: BatchRequest) -> dict[str, BatchResult]: ...
+
+
+__all__ = ["BatchProvider", "BatchRequest", "BatchResult"]

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

@@ -0,0 +1,303 @@
+"""The base class every check inherits, and the behaviour it actually provides.
+
+A check is a pure function over the set it is handed. `run` is a TEMPLATE
+METHOD: subclasses never override it, they fill in the two hooks it calls, and
+those two hooks are the distinction this estate keeps having to re-explain.
+
+    structural(ctx)          rules that probe NAMED PATHS.
+                             An absent file is in no file set, so a rule about a
+                             file's absence can only be answered this way.
+
+    graded(ctx, files)       rules that read the GIVEN SET.
+                             Which files those are is `engine.scope`'s question,
+                             answered by the runner before this class is called.
+
+Every service below exists because two or more of the ported checks needed it
+and each had written its own slightly different copy: reading a file that may
+not be there, scanning lines with a pattern, asserting a set of literal markers,
+parsing a document into a validated model. A base class that only declared
+`run` was an interface wearing a class's clothes.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from abc import ABC
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from enum import Enum, auto
+from pathlib import Path
+from typing import ClassVar
+
+import yaml
+from pydantic import ValidationError
+
+from .constants import Constants
+from .context import Context, FileSet
+from .errors import CouldNotRun, SchemaInvalid
+from .finding import Advisory, Finding, Report
+from .models import StrictModel
+
+__all__ = ["BatchCheck", "Check", "Constants", "CouldNotRun", "FileState", "SchemaInvalid"]
+
+
+class FileState(Enum):
+    """What a structural probe found. The predicate is shared; the wording is not."""
+
+    MISSING = auto()
+    EMPTY = auto()
+    PRESENT = auto()
+
+
+class Check(Constants, ABC):
+    """One registered gate's rule logic. Stateless; instantiated per run.
+
+    `Constants` is inherited, not imported: every literal in the package is
+    declared in `core/constants.py` and reaches a subclass as `self.NAME`. A
+    check that defines a module-level constant beside itself has put a value
+    somewhere only it can see, which is the habit this base class removes.
+    """
+
+    id: ClassVar[str]
+    """The row id this implements — `RST-001`, not the address."""
+
+    rule: ClassVar[str | None] = None
+    """Default rule id for `self.report`. Single-rule gates set it once here
+    instead of repeating the literal at every call site."""
+
+    inputs: ClassVar[Mapping[str, str]] = {}
+    """Logical name -> default repository-relative path.
+
+    Declared, never joined in the body. The runner resolves each into
+    `ctx.inputs[name]`, and a caller overrides one by constructing a Context.
+    This is what replaces the `<GATE>_<INPUT>` environment variables: the same
+    capability, addressed by name, visible at the call site, and impossible to
+    leave set for the next caller.
+    """
+
+    #: Names in `inputs` that only WIDEN an allowlist -- absence grades STRICTER.
+    #: Every other input is fatal when its tree is undeclared, because grading
+    #: content you never read is how a gate reports PASS over nothing. These are
+    #: the inverse: dropping one can only turn a pass into a failure, never the
+    #: reverse, so requiring the tree would just pressure an owner into declaring
+    #: a directory that does not exist -- the one lie the engine cannot detect.
+    widening_inputs: ClassVar[frozenset[str]] = frozenset()
+
+    resources: ClassVar[Mapping[str, str]] = {}
+    """Logical name -> a file in THIS GATE'S OWN FOLDER.
+
+    The other half of `inputs`, and the distinction is who owns the document:
+
+        inputs      the CONSUMER's, named by a `<tree>` path. Measured evidence
+                    that changes per repository — a coverage summary, a lockfile.
+        resources   the PACKAGE's, sitting beside this check. Policy that ships
+                    with the gate and means nothing without it — a profile
+                    register, a rule table.
+
+    A gate declaring one is a FOLDER, not a module: `checks/<domain>/<name>/`
+    holding `check.py` and the document it grades. That is the shell tree's
+    co-location rule, and it exists because the alternative was four files in
+    four trees tied together by a path literal in a registry row that nothing
+    verified — and each of them moved independently, silently.
+
+    Resolved by `importlib.resources`, so the package finds its own data by its
+    own shape and never by this file's position on disk (K-16, K-40).
+    """
+
+    structural_grant: ClassVar[bool] = False
+    """The row's `grants:` names a REGISTER this check grades, not a catalogue
+    of signed exceptions, and its allowance is therefore 0.
+
+    Two of the thirteen catalogue-path rows are like this — `LAY-004`'s
+    directory ratchet and `RST-020`'s verified-exception register — and the
+    distinction is arithmetic, not bookkeeping. A catalogue is subtracted AFTER
+    counting: `remaining = findings - granted`. A register is spent BEFORE
+    counting: every directory it holds is excluded while deciding what even
+    counts as a finding, so by the time there is a number the grant is gone.
+
+    Passing the register's size as the allowance instead is the trap the shell
+    version wrote a paragraph about: 17 findings against a "grant" of 218 held
+    directories returns 0, and a failing gate reports green.
+
+    Declaring it here rather than in the registry is deliberate (K-09) — it is a
+    property of how this check counts, and it lives where the counting does. The
+    runner never guesses: without this flag, a `grants:` document that is not an
+    `adl.exception-catalog/v1` is a hard could-not-run.
+    """
+
+    whole_scope: ClassVar[bool] = False
+    """A triggered check grades its complete declared scope.
+
+    The caller's narrowed set still decides whether the gate applies. Once it
+    does, the runner replaces that set with the intersection against the full
+    Git-visible universe. This is for global-state rules such as a WIP cap:
+    counting only the changed plans would turn eleven open plans into one.
+    """
+
+    requires: ClassVar[tuple[str, ...]] = ()
+    """External executables this check drives. Verified by the runner, which
+    removes the `command -v x || exit 2` prologue every shell check re-typed."""
+
+    # ---------------------------------------------------------------- template
+
+    def run(self, ctx: Context, files: FileSet) -> Iterator[Report]:
+        """Grade, and return what was found. Not overridden — fill in the hooks."""
+        yield from self.structural(ctx)
+        yield from self.graded(ctx, files)
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        """Rules answered by probing named paths. Override if the gate has any."""
+        return ()
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        """Rules answered by reading the given set. Override if the gate has any."""
+        return ()
+
+    # ---------------------------------------------------------------- reporting
+
+    def report(
+        self,
+        path: str,
+        message: str,
+        fix: str,
+        *,
+        rule: str | None = None,
+        line: int | None = None,
+    ) -> Finding:
+        resolved = rule or self.rule
+        if resolved is None:
+            raise CouldNotRun(
+                f"{type(self).__name__} reported without a rule id and declares no default"
+            )
+        return Finding(rule=resolved, path=path, message=message, fix=fix, line=line)
+
+    def advise(self, path: str, message: str) -> Advisory:
+        return Advisory(path=path, message=message)
+
+    # ------------------------------------------------------------------ reading
+
+    def text(self, ctx: Context, target: str | Path) -> str | None:
+        """File contents, or None when the path is not a readable file.
+
+        A `str` is repository-relative and resolved against the graded root; a
+        `Path` is a named input the runner already resolved. Both, so a check
+        never joins a path itself.
+
+        None means ABSENT, and absence is frequently the finding. It is never a
+        silent empty string, which is what `$(cat missing 2>/dev/null)` gave the
+        shell tree and what let a missing file grade as a conforming one.
+        """
+        resolved = ctx.path(target) if isinstance(target, str) else target
+        if not resolved.is_file():
+            return None
+        return resolved.read_text(encoding="utf-8", errors="replace")
+
+    def state(self, ctx: Context, target: str | Path) -> FileState:
+        """The shared half of every "exists and is non-empty" probe."""
+        body = self.text(ctx, target)
+        if body is None:
+            return FileState.MISSING
+        return FileState.PRESENT if body.strip() else FileState.EMPTY
+
+    # ------------------------------------------------------------------ scanning
+
+    def missing_markers(self, body: str, markers: Sequence[str]) -> list[str]:
+        """Which required literals are absent, in declaration order."""
+        return [marker for marker in markers if marker not in body]
+
+    def present_markers(self, body: str, markers: Sequence[str]) -> list[str]:
+        """Which forbidden literals are present, in declaration order.
+
+        The mirror of `missing_markers`, and both are needed: a licence file is
+        graded on what it MUST contain, a folder guide on what it must NOT.
+        """
+        return [marker for marker in markers if marker in body]
+
+    def scan(
+        self, ctx: Context, target: str | Path, pattern: re.Pattern[str]
+    ) -> Iterator[tuple[int, re.Match[str]]]:
+        """Every match in the file, with its 1-based line number."""
+        body = self.text(ctx, target)
+        if body is None:
+            return
+        for number, line in enumerate(body.splitlines(), start=1):
+            for found in pattern.finditer(line):
+                yield number, found
+
+    # ------------------------------------------------------------------ parsing
+
+    def parse[T: StrictModel](self, ctx: Context, target: str | Path, model: type[T]) -> T:
+        """Load a JSON document and validate it strictly.
+
+        Raises SchemaInvalid — which the caller turns into its own finding,
+        because a malformed document this gate grades is subject matter, not a
+        broken machine. The detail carries the offending field, which the
+        hand-rolled boolean schema tests it replaces could never report.
+        """
+        shown = target if isinstance(target, str) else ctx.relative(target)
+        body = self._document(ctx, target, shown)
+        try:
+            loaded = json.loads(body)
+        except json.JSONDecodeError as exc:
+            raise SchemaInvalid(f"{shown} is not valid JSON: {exc}") from exc
+        return self._validate(loaded, model, shown)
+
+    def parse_yaml[T: StrictModel](
+        self, ctx: Context, target: str | Path, model: type[T]
+    ) -> T:
+        """The same, for a YAML document.
+
+        Separate from `parse` because the two failure messages differ and a
+        reader needs to know which parser rejected the file; identical in every
+        other respect, including that a missing document raises rather than
+        arriving as an empty one.
+        """
+        shown = target if isinstance(target, str) else ctx.relative(target)
+        body = self._document(ctx, target, shown)
+        try:
+            loaded = yaml.safe_load(body)
+        except yaml.YAMLError as exc:
+            raise SchemaInvalid(f"{shown} is not valid YAML: {exc}") from exc
+        return self._validate(loaded, model, shown)
+
+    def _document(self, ctx: Context, target: str | Path, shown: str) -> str:
+        body = self.text(ctx, target)
+        if body is None:
+            raise SchemaInvalid(f"{shown} is missing")
+        return body
+
+    @staticmethod
+    def _validate[T: StrictModel](loaded: object, model: type[T], shown: str) -> T:
+        try:
+            return model.model_validate(loaded)
+        except ValidationError as exc:
+            raise SchemaInvalid(f"{shown} does not match {model.__name__}: {exc}") from exc
+
+
+class BatchCheck(Check):
+    """A normal check whose graded reports were produced by one shared process.
+
+    The CLI batches selected rows by ``batch_provider``. This class merely feeds
+    the row's partition back through ``Check.run`` so grants, advisories and
+    verdicts remain on the single ordinary path.
+    """
+
+    batch_provider: ClassVar[str]
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        if ctx.batch_error is not None:
+            raise CouldNotRun(ctx.batch_error)
+        if ctx.batch_reports is None:
+            raise CouldNotRun(
+                f"{self.id} declares batch provider {self.batch_provider!r}, "
+                "but the execution produced no batch result"
+            )
+
+        allowed = set(files.paths)
+        outside = sorted({report.path for report in ctx.batch_reports if report.path not in allowed})
+        if outside:
+            raise CouldNotRun(
+                f"batch provider {self.batch_provider!r} returned {self.id} report(s) "
+                f"outside engine.scope: {', '.join(outside)}"
+            )
+        return ctx.batch_reports

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

@@ -0,0 +1,106 @@
+"""The values more than one module needs.
+
+`Check` inherits this class, so every check reaches these as `self.NAME` without
+importing anything, and the two modules that are not checks — `cli` and `policy`
+— reference `Constants.NAME` directly.
+
+The line this file draws:
+
+    used by more than one module   ->  here
+    used by exactly one gate       ->  a ClassVar on that gate's check class
+
+Both halves matter. Hoisting a gate's private regex up here would put it in
+everyone's namespace to no purpose, and leaving a shared value at module scope
+is how `SCHEMA` came to be defined twice, in two files, with two different
+values — each correct for its own reader and invisible to the other.
+
+What is NOT here, deliberately:
+
+- Anything computed. A value derived from another value at import time is code,
+  and code that hides in a constants file is code nobody reads.
+- Dispatch tables holding CLASSES. They would import a check into `core`, and
+  the dependency only points one way: `checks` -> `core` -> `policy`.
+- A row's scope, severity, or grant count. Those live in the registry YAML,
+  which is policy, not code — a copy here would make two mechanisms answer one
+  question (C-09).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Final
+
+
+class Constants:
+    """Read-only class attributes. Never instantiated; only ever inherited."""
+
+    # ------------------------------------------------------------------- logs
+    # Written by `cli.write_logs`, asserted by `tests/core/test_cli.py`. The
+    # name of a file one module writes and another reads is shared by
+    # definition.
+
+    # ---------------------------------------------------------- tool-owned
+    # `.workflows/` belongs to adl-repo-controls. Owner ruling 2026-09-16:
+    # ".workflows is what u declare and deploy as the owner of git hooks", and
+    # "workflows/ is the <workflow> that you are seeking" -- the consumer's tree,
+    # reached as `<workflows>`.
+    #
+    # Two directories, similar names, different owners, and conflating them is a
+    # real bug rather than a tidiness question: the K-42 sweep converted
+    # `.workflows/AGENTS.md` into `<workflows>/AGENTS.md`, which repoints a path
+    # this tool fixes everywhere at a tree the repository declares. enact-m5 has
+    # BOTH and an AGENTS.md in each, so that conversion silently swapped which
+    # file two gates were reading.
+    #
+    # A check that means OUR directory names it from here. One that means THEIR
+    # tree resolves the placeholder.
+
+    TOOL_DIR: ClassVar[str] = ".workflows"
+    """This package's deployment surface in a consumer: the hook stubs and lock."""
+
+    TOOL_AGENTS_MD: ClassVar[str] = ".workflows/AGENTS.md"
+    """Our own guide inside it -- fixed, never resolved through a declaration."""
+
+    ALL_LOG: ClassVar[str] = "all.log"
+    """One line per row, pass and fail alike."""
+
+    FAILURES_LOG: ClassVar[str] = "failures.log"
+    """The same line for non-clean rows, with their findings indented beneath."""
+
+    RECEIPTS_LOG: ClassVar[str] = "receipts.jsonl"
+    """C1: one JSON `core.receipt.Receipt` per row, one per line, every run —
+    the durable evidence `all.log`/`failures.log` do not carry: a machine-
+    readable outcome per gate, independent of the human-facing summary text."""
+
+    # --------------------------------------------------------- policy schemas
+    # Two documents, two schemas, read by two modules. Kept adjacent because
+    # the failure they replace was `SCHEMA` meaning one thing in `registry.py`
+    # and another in `grants.py`, with nothing in either file to reveal it.
+
+    REGISTRY_SCHEMA: ClassVar[str] = "adl.gate-profile/v1"
+    GRANTS_SCHEMA: ClassVar[str] = "adl.exception-catalog/v1"
+
+    # ------------------------------------------------------ registry grammar
+    # Transcribed from `policy/gate-registry.schema.yaml`, which is the source
+    # of truth. `ID_PATTERN` and `SLUG_PATTERN` each have several consumers in
+    # `registry.py` alone — the id pattern validates `Row.id` and again decides
+    # whether a CLI argument is an id or an address.
+
+    ID_PATTERN: ClassVar[str] = r"^[A-Z][A-Z0-9]*-[0-9]{3}$"
+    SLUG_PATTERN: ClassVar[str] = r"^[a-z0-9]+(-[a-z0-9]+)*$"
+    TITLE_LIMIT: ClassVar[int] = 80
+
+    # ----------------------------------------------------- coverage vocabulary
+    # The four names every coverage gate reports against, and the contract the
+    # two summary readers in `checks/coverage/baseline.py` both have to meet:
+    # the Istanbul reader iterates this tuple, and the coverage.py reader maps
+    # its own differently-named fields onto these same four keys. Three more
+    # coverage rows in the registry are still shell and will read it too.
+
+    COVERAGE_METRICS: ClassVar[tuple[str, ...]] = (
+        "lines", "statements", "functions", "branches",
+    )
+
+
+CONSTANTS: Final = Constants
+"""Alias for the callers that reach these without inheriting: `cli` and
+`policy`. Both are the wrong shape for a check, and neither should grow one."""

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

@@ -0,0 +1,99 @@
+"""The two values every check is handed, and the only two it may read.
+
+This module is the answer to "no variables here and there". A check receives a
+`Context` and a `FileSet` as arguments. It reads no environment, resolves no
+root, opens no path it built itself, and holds no module-level state. Everything
+it is allowed to know is reachable from these two objects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from pydantic import Field
+
+from ..policy.registry import Row
+from .finding import Report
+from .models import StrictModel
+
+
+class FileSet(StrictModel):
+    """The applicable scope: already intersected, repository-relative, ordered.
+
+    It is a VALUE, passed as an argument. The shell tree carried it in
+    `ADL_CHANGED_FILES`, which the runner both read (the caller's set) and
+    wrote (the narrowed list) — one name holding two facts, each free to be
+    read as the other.
+    """
+
+    paths: tuple[str, ...] = ()
+
+    def __iter__(self) -> Iterator[str]:  # type: ignore[override]
+        return iter(self.paths)
+
+    def __len__(self) -> int:
+        return len(self.paths)
+
+    def __bool__(self) -> bool:
+        return bool(self.paths)
+
+    def with_suffix(self, *suffixes: str) -> FileSet:
+        """Subject matter, not scope: `.md` because this rule grades prose."""
+        return FileSet(paths=tuple(p for p in self.paths if p.endswith(suffixes)))
+
+    def existing(self, root: Path) -> FileSet:
+        """Drop paths that are no longer on disk.
+
+        A liveness check on paths already given, never a search for paths: a set
+        can legitimately name a file this commit deleted.
+        """
+        return FileSet(paths=tuple(p for p in self.paths if (root / p).is_file()))
+
+
+class Context(StrictModel):
+    """Everything a check may know about the world outside its arguments."""
+
+    root: Path
+    """The repository being graded. Resolved once, at the CLI boundary."""
+
+    row: Row
+    """The registry row that selected this check."""
+
+    declarations: dict[str, str] = Field(default_factory=dict)
+    """What the repository declares about itself, from `[controls.compliance]`.
+
+    Facts a repository OWNS and the package cannot derive: which licence it
+    ships under, and nothing else so far. A check reads the declaration and
+    grades the repository against it — it never holds an answer of its own.
+    `REP-001` required the Apache License 2.0 text outright until 2026-09-15,
+    which is a gate deciding a company's licensing rather than enforcing it.
+    """
+
+    inputs: dict[str, Path] = Field(default_factory=dict)
+    """Named inputs, already resolved to absolute paths by the runner.
+
+    A check declares the logical names it needs and reads `ctx.inputs["x"]`. It
+    never joins a path, and a test overrides an input by building a Context —
+    not by exporting `COVERAGE_BASELINE_CONFIG` into the process.
+    """
+
+    batch_reports: tuple[Report, ...] | None = None
+    """Reports produced once for this row by its declared batch provider."""
+
+    batch_error: str | None = None
+    """Why the shared provider could not produce this row; never a finding."""
+
+    def path(self, relative: str) -> Path:
+        """A repository-relative path, resolved against the graded root.
+
+        For the named structural probes a rule genuinely owns — `LICENSE`,
+        `docs/architecture/decisions` — which are subject matter, not scope.
+        """
+        return self.root / relative
+
+    def relative(self, absolute: Path) -> str:
+        """The inverse, for reporting a named input by the name it was given."""
+        try:
+            return str(absolute.relative_to(self.root))
+        except ValueError:
+            return str(absolute)

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

@@ -0,0 +1,32 @@
+"""The two failures, kept apart on purpose.
+
+Their own module so that `policy` can raise one without importing `check` — a
+grants catalogue that cannot be read is a could-not-run, and saying so should
+not make the policy layer depend on the check layer.
+"""
+
+from __future__ import annotations
+
+
+class CouldNotRun(Exception):
+    """The check could not reach a verdict. Exit 2, never a finding.
+
+    A missing tool, an unreadable register, a scanner that crashed. The one
+    distinction the shell tree kept collapsing: `rg` exits 1 for no match and 2
+    for a failure, and a check that treats both as "found nothing" reports clean
+    when the tool broke.
+    """
+
+
+class SchemaInvalid(Exception):
+    """A document this check GRADES does not match its schema.
+
+    Distinct from CouldNotRun on purpose. That a register is malformed is
+    usually a FINDING — it is the subject matter — so the check catches this and
+    words its own rule id. Raising CouldNotRun instead would make a broken
+    register indistinguishable from a broken machine.
+    """
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(detail)
+        self.detail = detail

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

@@ -0,0 +1,65 @@
+"""The finding record, and the one place its text shape is defined.
+
+Every producer returns these; nothing prints its own. `lib/findings.sh` was
+already the single renderer in the shell tree and this keeps that property, but
+as a validated type rather than a convention a check has to remember to honour.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import Field
+
+from .models import StrictModel
+
+
+class Severity(StrEnum):
+    """The three levels `policy/severity-policy.yaml` defines. Frozen 2026-08-22."""
+
+    HIGH = "H"
+    MEDIUM = "M"
+    LOW = "L"
+
+
+class Finding(StrictModel):
+    """One violation.
+
+    `path` is repository-relative, always. The shell tree spent three helpers
+    building absolute paths and stripping the root back off before reporting;
+    there is nothing to strip if nothing is ever prefixed.
+    """
+
+    rule: Annotated[str, Field(min_length=1)]
+    path: Annotated[str, Field(min_length=1)]
+    message: Annotated[str, Field(min_length=1)]
+    fix: Annotated[str, Field(min_length=1)]
+    line: Annotated[int, Field(ge=1)] | None = None
+
+    def render(self) -> str:
+        """Render the violation and the concrete repair guidance together."""
+        location = self.path if self.line is None else f"{self.path}:{self.line}"
+        return f"{self.rule} {location}: {self.message}; fix: {self.fix}"
+
+
+class Advisory(StrictModel):
+    """A warning: reported, never counted.
+
+    A distinct type rather than a Finding with a flag, because the difference is
+    the whole point — an advisory must not move the verdict, and anything that
+    can be mistaken for a Finding eventually will be.
+    """
+
+    path: Annotated[str, Field(min_length=1)]
+    message: Annotated[str, Field(min_length=1)]
+
+    def render(self) -> str:
+        return f"WARN {self.path}: {self.message}"
+
+
+type Report = Finding | Advisory
+
+
+def render(findings: list[Finding]) -> str:
+    return "\n".join(f.render() for f in findings)