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

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

@@ -0,0 +1,40 @@
+"""The base every model in this package inherits, and the three settings that
+make validation mean something.
+
+    extra="forbid"   an unknown key is an ERROR, not ignored silently.
+    strict=True      no coercion: "60000" is not 60000, and 1 is not True.
+    frozen=True      a validated value cannot drift afterwards.
+
+`extra="forbid"` is the one that earns its place. The shell tree read the
+registry with `yq -r '.rows[].engine.script'`; a row that misspelled the key got
+an empty string, and an empty string was a gate that ran nothing and reported
+clean. A typo has to be an error at the boundary, because there is no later
+point at which it becomes visible.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class StrictModel(BaseModel):
+    """Immutable, no coercion, no unknown keys."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+        frozen=True,
+        validate_default=True,
+    )
+
+
+class OpenModel(BaseModel):
+    """Strict about the fields it declares, tolerant of the ones it does not.
+
+    For documents this package reads but does not own — `package.json` is the
+    example: its `license` field is subject matter here and its other forty keys
+    are none of this package's business. Forbidding them would make a check fail
+    on a perfectly good manifest.
+    """
+
+    model_config = ConfigDict(extra="ignore", strict=True, frozen=True)

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

@@ -0,0 +1,63 @@
+"""C1 — the grading receipt, and the guard that carries its name.
+
+    the compliance run emits a grading receipt per gate, and a gate whose
+    scope resolved to zero units must be could-not-run, never PASS
+
+`runner.run` already refuses to return a CLEAN verdict for an exhaustive dead
+scope — `test_a_scope_matching_nothing_on_a_whole_tree_is_could_not_run`
+proves it, and the widened whole-scope path proves the same thing a second
+way. This module is the other half: the durable per-gate artifact a run
+leaves behind, and a second, independent check of the same invariant at the
+point the artifact is built — so a future caller that reaches this function
+with a hand-built `Verdict` (a refactor, a new batch path, a test double)
+cannot mint a false PASS receipt just because it skipped `runner.run`.
+
+Deliberately thin: a receipt reports what `decide()` already decided. It does
+not re-grade, re-score, or carry an opinion `Verdict` does not already hold.
+"""
+
+from __future__ import annotations
+
+from .models import StrictModel
+from .verdict import Outcome, Verdict
+
+
+class Receipt(StrictModel):
+    """One row's grading outcome, as evidence rather than as a log line.
+
+    `status` is `verdict.status` verbatim (PASS/FAIL/ERROR) — no second
+    vocabulary for the same three outcomes. `units` is the file count the row
+    actually graded; see `Verdict.units` for why it lives there and not here.
+    """
+
+    gate: str
+    address: str
+    status: str
+    units: int
+    message: str
+
+
+def from_verdict(verdict: Verdict, *, exhaustive: bool) -> Receipt:
+    """Build one gate's receipt.
+
+    `exhaustive` is the same fact `runner.applicable_files` used to decide
+    whether an empty scope was dead or merely irrelevant to this diff — a
+    receipt built from a narrowed (hook-scoped) run must not punish a zero-unit
+    PASS that means "nothing in this changeset touched this gate"; one built
+    from an exhaustive run must never see a zero-unit PASS at all, because
+    `runner.run` cannot produce one (it raises `CouldNotRun` first). This
+    function checks that second claim rather than assuming it.
+    """
+    if exhaustive and verdict.units == 0 and verdict.outcome is Outcome.CLEAN:
+        raise ValueError(
+            f"{verdict.row.id}: refusing to record a PASS receipt for a gate "
+            "whose exhaustive scope resolved to zero units — a dead scope is "
+            "could-not-run, never a clean pass (C1)"
+        )
+    return Receipt(
+        gate=verdict.row.id,
+        address=verdict.row.address,
+        status=verdict.status,
+        units=verdict.units,
+        message=verdict.message,
+    )

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

@@ -0,0 +1,82 @@
+"""The applicable-scope formula, and the only implementation of it.
+
+    applicable scope = (row's engine.scope  ∩  the caller's set)  −  what git cannot see
+
+The third term is the caller's: paths git cannot see never enter the set, so
+nothing here subtracts them. The first two are computed HERE, once, outside
+every check — which is the rule the shell tree stated and then broke in three
+places, because each check could reach for the registry itself.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from functools import lru_cache
+
+
+@lru_cache(maxsize=1024)
+def _compile(pattern: str) -> re.Pattern[str]:
+    """Translate one registry glob to an anchored regex.
+
+    Written out rather than delegated to `fnmatch` or `PurePath.match`: neither
+    gives `**` its cross-directory meaning, and a `**` that silently degrades to
+    `*` is a positive glob matching nothing — which excludes everything and
+    reports clean (K-13, K-17).
+    """
+    out: list[str] = []
+    i, n = 0, len(pattern)
+    while i < n:
+        char = pattern[i]
+        if pattern.startswith("**/", i):
+            # Zero OR MORE leading components, so `**/x` matches `x` as well.
+            out.append(r"(?:[^/]+/)*")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(r".*")
+            i += 2
+        elif char == "*":
+            out.append(r"[^/]*")
+            i += 1
+        elif char == "?":
+            out.append(r"[^/]")
+            i += 1
+        elif char == "{":
+            close = pattern.find("}", i)
+            if close == -1:
+                out.append(re.escape(char))
+                i += 1
+                continue
+            alternatives = pattern[i + 1 : close].split(",")
+            out.append("(?:" + "|".join(re.escape(a) for a in alternatives) + ")")
+            i = close + 1
+        else:
+            out.append(re.escape(char))
+            i += 1
+    return re.compile("^" + "".join(out) + "$")
+
+
+def matches(pattern: str, path: str) -> bool:
+    return _compile(pattern).search(path) is not None
+
+
+def in_scope(patterns: Sequence[str], path: str) -> bool:
+    """Ordered globs, last match wins, `!` excludes.
+
+    A path matched by no pattern at all is OUT. That is what makes a positive
+    glob list a whitelist, and it is why an empty result is never quietly
+    treated as a clean pass by the caller.
+    """
+    verdict = False
+    for pattern in patterns:
+        if pattern.startswith("!"):
+            if matches(pattern[1:], path):
+                verdict = False
+        elif matches(pattern, path):
+            verdict = True
+    return verdict
+
+
+def intersect(patterns: Sequence[str], paths: Iterable[str]) -> tuple[str, ...]:
+    """The row's declared scope ∩ the set the caller resolved. Order preserved."""
+    return tuple(p for p in paths if in_scope(patterns, p))

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

@@ -0,0 +1,161 @@
+"""The verdict, and the only path to one.
+
+    remaining = violations - grants
+
+    remaining == 0  ->  pass
+    remaining  > 0  ->  FAIL   fix the violations, or sign a grant
+    remaining  < 0  ->  FAIL   lower the grant to what is actually there
+
+Carried over one-to-one from GRANTS.md, including the third line — the one that
+matters, because a grant that has stopped shrinking is a grant nobody is paying
+attention to.
+
+This module does no I/O. `granted` arrives as a number; turning a row's
+catalogue path into that number is `policy.grants`' job.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+from ..policy.registry import Row
+from . import scope
+from .finding import Advisory, Finding
+from .models import StrictModel
+
+
+class Outcome(IntEnum):
+    """Process exit status. A tool failure is never a finding (F-05)."""
+
+    CLEAN = 0
+    FINDINGS = 1
+    COULD_NOT_RUN = 2
+
+
+class Verdict(StrictModel):
+    row: Row
+    findings: tuple[Finding, ...] = ()
+    outcome: Outcome = Outcome.CLEAN
+    message: str = ""
+    granted: int = 0
+    """What the row had signed for. Carried on the verdict rather than recovered
+    from `message`: a number that has to be parsed back out of prose is a number
+    that will eventually be parsed wrong."""
+
+    advisories: tuple[Advisory, ...] = ()
+    """Reported, never counted. An advisory cannot move the outcome."""
+
+    units: int = 0
+    """How many files this row actually graded — `len(narrowed.paths)` at the
+    point `runner.run` called the check. Attached after `decide()` returns
+    (`model_copy(update={...})`), because `decide` itself never sees the file
+    set, only the findings it produced. Zero here means exactly what it says:
+    the check ran, and no file matched its scope. It is C1's evidence field —
+    `core.receipt.from_verdict` reads it to tell an exhaustive dead scope from
+    a narrowed "nothing relevant changed", the same distinction the runner's
+    own `exhaustive` guard already enforces (see test_runner.py)."""
+
+    @property
+    def exit_code(self) -> int:
+        return int(self.outcome)
+
+    @property
+    def rules(self) -> list[str]:
+        return [f.rule for f in self.findings]
+
+    @property
+    def status(self) -> str:
+        """PASS / FAIL / ERROR. Three words, because there are three outcomes.
+
+        ERROR is not a louder FAIL: a gate that could not run has graded
+        nothing, and reporting it as a failure invites someone to "fix" it by
+        deleting whatever would not load.
+        """
+        match self.outcome:
+            case Outcome.CLEAN:
+                return "PASS"
+            case Outcome.FINDINGS:
+                return "FAIL"
+            case Outcome.COULD_NOT_RUN:
+                return "ERROR"
+
+    def summary(self) -> str:
+        """ONE LINE, the whole verdict. The other half of `render`'s job.
+
+        `render` is the detail — every finding, then the tally. This is the row
+        as a single row: readable in a 122-line sweep, greppable by status, and
+        carrying severity and the grant count so a failure line does not send
+        the reader back to the registry to find out what it cost.
+        """
+        if self.outcome is Outcome.COULD_NOT_RUN:
+            detail = self.message.removeprefix("could not run — ")
+        elif self.outcome is Outcome.CLEAN:
+            # Always "0 finding(s), 0 granted" — PASS already says this.
+            detail = ""
+        else:
+            detail = f"{len(self.findings)} finding(s), {self.granted} granted"
+        return (
+            f"{self.row.id:<8} {self.row.address:<40} "
+            f"{self.row.severity} {self.status:<5} {detail}".rstrip()
+        )
+
+    def render(self) -> str:
+        lines = [f.render() for f in self.findings]
+        lines.append(f"{self.row.address}: {self.message}")
+        return "\n".join(lines)
+
+
+def decide(
+    row: Row,
+    findings: tuple[Finding, ...],
+    granted: tuple[str, ...] | int = (),
+    advisories: tuple[Advisory, ...] = (),
+) -> Verdict:
+    """A grant forgives a PATH, not a quantity.
+
+    `granted` was an int and this did `len(findings) - granted`, so a catalogue
+    naming three files forgave any three findings — including three at paths
+    nobody signed for. The `source.exclude_glob` that makes a grant a signed
+    exception was never consulted here at all.
+
+    An int is still accepted so a caller passing `0` keeps working; it grants
+    nothing, which is what all 85 such rows mean.
+    """
+    patterns = () if isinstance(granted, int) else granted
+    forgiven = tuple(
+        f for f in findings
+        if any(scope.in_scope((pattern,), f.path) for pattern in patterns)
+    )
+    outstanding = tuple(f for f in findings if f not in forgiven)
+    granted_count = len(forgiven)
+    remaining = len(outstanding)
+    if remaining == 0:
+        if advisories:
+            note = "OK with warnings, see stderr"
+        else:
+            note = "OK" if not granted_count else f"OK ({granted_count} granted)"
+        return Verdict(
+            row=row, findings=findings, outcome=Outcome.CLEAN,
+            message=note, granted=granted_count, advisories=advisories,
+        )
+    if remaining > 0:
+        return Verdict(
+            row=row, findings=findings, outcome=Outcome.FINDINGS,
+            message=(
+                f"FAIL — {len(findings)} finding(s), {granted_count} granted, "
+                f"{remaining} remaining"
+            ),
+            granted=granted_count, advisories=advisories,
+        )
+    return Verdict(
+        row=row, findings=findings, outcome=Outcome.FINDINGS,
+        message=(
+            f"FAIL — {granted_count} granted but only {len(findings)} found; "
+            f"lower grants to {len(findings)}"
+        ),
+        granted=granted, advisories=advisories,
+    )
+
+
+def could_not_run(row: Row, reason: str) -> Verdict:
+    return Verdict(row=row, outcome=Outcome.COULD_NOT_RUN, message=f"could not run — {reason}")

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

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

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

@@ -0,0 +1,131 @@
+"""`<name>` in a scope pattern, and the one file that says what it means.
+
+A row declares what its rule is ABOUT — `<rust>/crates/**/src/*.rs` — and
+`trees.toml` says where that currently lives. The registry therefore contains no
+consumer path at all, which is K-42: a path outside this package, written inside
+it, is a dependency on this particular checkout's shape.
+
+Expansion happens once, at registry load, so everything downstream — the scope
+intersection, the runner, every check — sees ordinary repository-relative globs
+and none of them knows this mechanism exists.
+
+An unknown placeholder is a LOAD FAILURE. Passing it through unexpanded would
+leave a pattern that matches nothing, and a positive glob matching nothing
+excludes everything (K-13) — the row would go quiet instead of loud.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Mapping
+from functools import cache
+from importlib import resources
+from typing import Annotated
+
+from pydantic import Field, ValidationError, field_validator
+
+from ..core.constants import Constants
+from ..core.models import StrictModel
+
+CONFIG_FILE = "config.toml"
+
+PLACEHOLDER = re.compile(r"<([^<>]*)>")
+"""Deliberately permissive about what it captures: `<Rust>` and `<not a tree>`
+must reach the unknown-name error rather than being left in the pattern by a
+stricter regex that simply did not match them."""
+
+
+class TreeMapError(Exception):
+    """`trees.toml` is missing, malformed, or a row names a tree it lacks."""
+
+
+class TreeMap(StrictModel):
+    version: int
+    # No `min_length`: the PACKAGED table is empty on purpose, and an empty map
+    # is the honest answer when nothing has been declared. Requiring one entry
+    # would force this package to ship one consumer's directory name forever.
+    trees: dict[str, str]
+
+    @field_validator("trees", mode="after")
+    @classmethod
+    def _paths_are_repository_relative(cls, value: dict[str, str]) -> dict[str, str]:
+        for name, path in value.items():
+            if not re.match(Constants.SLUG_PATTERN, name):
+                raise ValueError(f"tree name {name!r} is not a lowercase-hyphenated slug")
+            if not path:
+                raise ValueError(f"tree {name!r} has an empty path")
+            if path.startswith("/"):
+                raise ValueError(f"tree {name!r} is absolute ({path!r}); paths are repo-relative")
+            if path.endswith("/"):
+                raise ValueError(f"tree {name!r} ends with a slash ({path!r}); write it bare")
+            if PLACEHOLDER.search(path):
+                raise ValueError(
+                    f"tree {name!r} contains a placeholder ({path!r}); a tree resolves to a "
+                    "path, never to another placeholder"
+                )
+        return value
+
+    # An empty value is legal and load-bearing: it is the repository saying "I
+    # have no such tree", which is a different answer from saying nothing. See
+    # `absent()`.
+
+
+@cache
+def load() -> TreeMap:
+    """Package data, found by the package's own shape (K-16)."""
+    try:
+        text = resources.files(__package__).joinpath(CONFIG_FILE).read_text(encoding="utf-8")
+    except (FileNotFoundError, ModuleNotFoundError) as exc:
+        raise TreeMapError(f"{CONFIG_FILE} is missing from the package") from exc
+    try:
+        return TreeMap.model_validate(tomllib.loads(text))
+    except tomllib.TOMLDecodeError as exc:
+        raise TreeMapError(f"{CONFIG_FILE} is not valid TOML: {exc}") from exc
+    except ValidationError as exc:
+        raise TreeMapError(f"{CONFIG_FILE} violates its schema:\n{exc}") from exc
+
+
+def absent(pattern: str, mapping: Mapping[str, str] | None = None) -> bool:
+    """Does `pattern` name a tree the repository has DECLARED it does not have?
+
+    Three states, and the middle one is the only new idea:
+
+    * not in the map -- nobody has answered. The caller reports could-not-run.
+    * `""` -- the owner states there is no such tree here. The caller drops the
+      pattern (or the input) and grades a smaller, honest scope.
+    * a path -- graded there.
+
+    Silence is deliberately NOT absence. Reading it as absence is the TS-001
+    bug: a repository that has the tree but forgot to declare it would have it
+    silently ungraded and still read PASS.
+    """
+    trees = load().trees if mapping is None else mapping
+    return any(match.group(1) in trees and not trees[match.group(1)]
+               for match in PLACEHOLDER.finditer(pattern))
+
+
+def expand(pattern: str, mapping: Mapping[str, str] | None = None) -> str:
+    """`backend/crates/**` -> `backend/crates/**`. Unknown name raises."""
+    trees = load().trees if mapping is None else mapping
+
+    def resolve(found: re.Match[str]) -> str:
+        name = found.group(1)
+        if name not in trees:
+            known = ", ".join(sorted(trees)) or "nothing"
+            raise TreeMapError(
+                f"scope pattern {pattern!r} names unknown tree <{name}>; "
+                f"declare [controls.compliance.trees].{name} in adl-config.toml "
+                f"(declare it as \"\" if this repository has no such tree). "
+                f"Currently declared: {known}"
+            )
+        if not trees[name]:
+            # `<specs>/**` -> `/**` would be rooted at the repository root and
+            # grade EVERYTHING. Callers must ask `absent()` first.
+            raise TreeMapError(
+                f"scope pattern {pattern!r} names tree <{name}>, declared absent; "
+                "ask absent() before expanding"
+            )
+        return trees[name]
+
+    return PLACEHOLDER.sub(resolve, pattern)

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/policy/config.toml

@@ -0,0 +1,30 @@
+# The consumer's layout, declared once.
+#
+# A registry row names a LOGICAL tree and never a physical path, so
+# `<rust>/crates/**/src/*.rs` is a rule about Rust crates and this file is the
+# only place that says Rust lives in `backend/`. Move the tree, edit one line,
+# and all 82 backend-rooted scope entries follow.
+#
+# This closes K-42 for the registry. A path outside this package written inside
+# it is a dependency on THIS checkout's shape; the rule is that the consumer's
+# layout arrives rather than being spelled. `compliance` is in the table for
+# exactly that reason -- the port from the shell tree to this package is one
+# line here, not 79 edits across the rows.
+#
+# SYNTAX IS `<name>`, NOT `{name}`. Braces are already glob alternation and 11
+# rows use it -- `{docs,.plans,.specs}/**`, `{schema,compliance}/**`. A `{rust}`
+# placeholder would be indistinguishable from a one-element alternation, and
+# resolving that by "a placeholder has no comma" is the silent-ambiguity trap
+# K-13 records. Angle brackets appear in no scope entry and in no path.
+#
+# An unknown `<name>` is a registry LOAD failure, never a pattern passed through
+# unexpanded: an unexpanded placeholder matches nothing, and a positive glob
+# matching nothing excludes everything (K-13).
+
+version = 1
+
+[trees]
+# Deliberately empty. A tree is a CONSUMER path, and a consumer path written
+# inside this package is a dependency on one checkout's shape (K-42). Every
+# repository declares its own in `[controls.compliance.trees]`; an undeclared
+# tree is could-not-run naming what to add, never a silent wrong answer.

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

@@ -0,0 +1,65 @@
+"""What is allowed to sit directly under `docs/`, declared once.
+
+`docs.closed-set` (DOC-010) is modelled on `layout.root-closed-set` (LAY-012)
+and this package's own `root_shape.py`: a closed set says "nothing outside
+this", and the answer is declared once, here, so a second docs gate does not
+grow its own, independently drifting copy the way LAY-008/LAY-012 once did for
+the repository root (see `root_shape.py`'s module docstring).
+
+Nothing below is invented — every entry is read off an EXISTING docs gate:
+
+ALLOWED_DOCS_DIRS
+    architecture, research, compliance, operations
+        `docs.semantics` (DOC-007, `checks/docs/semantics/check.py`)
+        already names these four as `COLLECTIONS`, calling them "the settled
+        taxonomy". `docs.okf-profile`'s `docs-okf-profiles.yaml` grades the
+        same paths (`docs/architecture/**`, `docs/operations/**`) and
+        `docs-knowledge-indexes.yaml` discovers an `index.md` catalog for
+        each of the four (`docs/architecture/index.md`, `docs/research/
+        index.md`, `docs/compliance/index.md`, `docs/operations/index.md`).
+    decisions
+        `docs.adr-lifecycle`'s own default ADR directory is `<docs>/decisions`
+        (`checks/docs/adr_lifecycle/check.py`, `_decisions()`), and
+        `docs-okf-profiles.yaml`'s ADR profile grades both
+        `docs/architecture/decisions/**` (nested under `architecture`, already
+        covered above) and `docs/decisions/**` — a second, top-level ADR
+        location — as the same document type. `architecture/decisions` is
+        therefore NOT a second top-level entry here; it is a path one level
+        inside `architecture`, already permitted by that entry.
+
+ALLOWED_DOCS_FILES
+    AGENTS.md, CLAUDE.md
+        every `docs-knowledge-indexes.yaml` catalog entry carries
+        `exclude_names: [index.md, AGENTS.md, CLAUDE.md]` — the standing set
+        of non-content files a documentation tree is allowed to hold
+        alongside its pages, and `docs/AGENTS.md`/`docs/CLAUDE.md` are that
+        set's root-level instance.
+    index.md
+        the same `exclude_names` entry, and `docs-knowledge-indexes.yaml`'s
+        own `discovery` list, which is exactly this filename at each
+        collection root. Permitted at `docs/` itself for the same reason
+        `root_shape.py` permits an unused entry: PERMITTED, not required —
+        no repository in this estate ships a top-level `docs/index.md` today,
+        and declaring it costs nothing.
+
+These are PERMITTED, not required — the same distinction `root_shape.py`
+draws for the repository root. A repository using only two of the five
+directories is not missing three findings; it has simply not written those
+pages yet.
+"""
+
+from __future__ import annotations
+
+ALLOWED_DOCS_DIRS: frozenset[str] = frozenset({
+    "architecture",
+    "research",
+    "compliance",
+    "operations",
+    "decisions",
+})
+
+ALLOWED_DOCS_FILES: frozenset[str] = frozenset({
+    "AGENTS.md",
+    "CLAUDE.md",
+    "index.md",
+})