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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/__init__.py

@@ -0,0 +1,11 @@
+"""The `layout.references` gate.
+
+A folder rather than a module because this gate GRADES A DOCUMENT SET; the
+fixtures it is tested against belong beside the check that reads them.
+"""
+
+from __future__ import annotations
+
+from .check import References
+
+__all__ = ["References"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/check.py

@@ -0,0 +1,188 @@
+"""LAY-011 — every local link in a Markdown page under docs/.plans/.specs
+resolves, exactly (case included), and no page still points at a retired
+docs/strategy/ path.
+
+  graded  the given set, narrowed to `.md`/`.mdx` (the row's `engine.scope`
+          already excludes `.plans/c_done/**` as a SOURCE — a completed plan
+          names paths that were real when it was written and is not rewritten
+          when they move).
+
+This gate has no structural half: there is no named path whose mere absence is
+itself a finding, only pages to read and links inside them to resolve.
+
+BACKLINK TARGETS ARE RESOLVED, NOT GRADED, exactly as `docs.adr-lifecycle`
+resolves its own: a link target is read straight off disk through `ctx.path`,
+never filtered through the given set. `.plans/c_done/26-07-27-history.md` is
+excluded from the set as a SOURCE and still resolves as a TARGET, because
+whether a link resolves is a property of the page holding it, not of whether
+the destination itself was part of this run's scope.
+
+EXACT-CASE EXISTENCE, WITHOUT `.`. `Path.exists()` alone is not enough: on a
+case-insensitive filesystem (macOS's default), `Path.exists()` on a
+docs-tree link spelled `Readme.md` is true when only `README.md` is on disk,
+and a directory listing is what
+supplies the one true spelling — from the graded root, with no `git` involved,
+so a link into a committed fixture corpus resolves the same way it does in CI.
+Only the FINAL path component is checked this way; a case mismatch in an
+intermediate directory is invisible to this probe on a case-insensitive
+filesystem, exactly as it was to the shell gate this ports.
+
+A REAL BUG FOUND, NOT SILENTLY REPRODUCED: the shell check's guard against
+treating an absolute URI (`http:`, `mailto:`, ...) as a local path reads
+`"$raw" =~ ^[[:alpha:]][[:alpha:][:di:]+.-]*:` — `[:di:]` is not a POSIX class
+name (`digit` truncated), so bash rejects the regex as invalid at every
+evaluation, prints "invalid regular expression" to stderr, and the match always
+evaluates false. The scheme guard therefore never fires in the deployed shell
+gate: an ordinary `[label](https://example.com)` link is NOT skipped and is
+checked as if it were a repository-relative path, which fails and reports a
+false-positive `missing local reference` on any page containing an external
+link. Neither committed fixture (nor `test.sh`) contains such a link, so
+nothing pins the intended behaviour down in the test suite. This port implements
+the evidently INTENDED rule instead — an absolute-URI-scheme prefix is skipped —
+with a corrected pattern, on the reasoning that the rule being ported is "don't
+flag external links", not "crash the regex engine". See the class docstring's
+`URI_SCHEME` for the corrected pattern. Reported here rather than silently
+fixed or silently reproduced, per instructions.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+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 References(Check):
+    id: ClassVar[str] = "LAY-011"
+    # Was "LAY-010" — the neighbouring gate's id, so every broken-link finding printed
+    # under `layout.profile-data` and sent a reader chasing a Rust migration-filename
+    # rule. Third instance of the defect 58866d2 fixed for LAY-008, and its test pinned
+    # it the same way. (`layout/profile_data` carries the same shape DELIBERATELY: its
+    # docstring explains it is a faithful carry of a shell-source mismatch whose own
+    # test.sh asserts LAY-009. This one had no such justification anywhere in the file.)
+    rule: ClassVar[str] = "LAY-011"
+
+    # This gate's own values, and no other module's business. Shared values are
+    # inherited from `core.constants.Constants` via `Check`.
+    # Resolved, not hardcoded. Only root-relative links (`/architecture/...`)
+    # use it, so a redeclared `docs` produced a FALSE "missing local reference"
+    # -- loud and wrong rather than silent, but wrong either way.
+    # FIXED 2026-09-16 (K-42 sweep, SILENT form, approved): RETIRED_PATH was
+    # also a hardcoded `docs/strategy/` literal, scanned across raw line text
+    # -- a repository whose docs root is not the packaged default had a real
+    # stale mention (written with its own redeclared prefix) go unmatched, no
+    # error and no finding, indistinguishable from a page with no stale
+    # reference at all. `strategy` stays literal below the resolved root: the
+    # one retired collection name, not a resolvable path.
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>"}
+    FENCE: ClassVar[re.Pattern[str]] = re.compile(r"^\s*```")
+    GAP_BULLET: ClassVar[str] = "- GAP-"
+
+    # `!?\[text\](target)` — a Markdown (or image) link. The target is either a
+    # `<bracketed target with spaces>` or a run of non-space, non-`)` chars,
+    # optionally followed by a space and a title, e.g. `(./x.md "Title")`.
+    LINK: ClassVar[re.Pattern[str]] = re.compile(
+        r"!?\[[^\]]*\]\((<[^>]+>|[^\s)]+)(?:[ \t][^)]*)?\)"
+    )
+
+    # The corrected version of the shell check's broken scheme guard — see the
+    # module docstring's "A REAL BUG FOUND" note.
+    URI_SCHEME: ClassVar[re.Pattern[str]] = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*:")
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        for source in sorted(files.with_suffix(".md", ".mdx")):
+            yield from self._check_source(ctx, source)
+
+    def _retired_path(self, ctx: Context) -> re.Pattern[str]:
+        docs_root = re.escape(ctx.relative(ctx.inputs["docs_root"]))
+        return re.compile(rf"{docs_root}/strategy/\S+")
+
+    def _check_source(self, ctx: Context, source: str) -> Iterable[Report]:
+        body = self.text(ctx, source)
+        if body is None:
+            return
+        lines = body.splitlines()
+
+        # A separate scanner from the link parser below — it reads the raw
+        # line, not a Markdown link, so an inline-code mention still counts.
+        # One match per line, matching the shell gate's single `awk match()`.
+        retired_path = self._retired_path(ctx)
+        for number, line in enumerate(lines, start=1):
+            found = retired_path.search(line)
+            if found:
+                yield self.report(
+                    source,
+                    f"stale retired docs path {found.group(0)}",
+                    "update the link to point at the retired path's current "
+                    "location, or remove it",
+                    line=number,
+                )
+
+        fenced = False
+        for number, line in enumerate(lines, start=1):
+            if self.FENCE.match(line):
+                fenced = not fenced
+                continue
+            if fenced:
+                continue
+            if line.startswith(self.GAP_BULLET):
+                continue
+            for match in self.LINK.finditer(line):
+                yield from self._check_link(ctx, source, number, match.group(1))
+
+    def _check_link(
+        self, ctx: Context, source: str, line: int, captured: str
+    ) -> Iterable[Report]:
+        if captured.startswith("<"):
+            raw = captured[1:].split(">", 1)[0]
+        else:
+            raw = captured
+        if not raw:
+            return
+        if raw.startswith("#") or raw.startswith("//") or self.URI_SCHEME.match(raw):
+            return
+
+        target = raw.split("#", 1)[0].replace("%20", " ")
+        if not target:
+            return
+
+        if target.startswith("/"):
+            ok = self._target_exists(ctx, f"{ctx.relative(ctx.inputs['docs_root'])}/{target[1:]}") or self._target_exists(
+                ctx, target[1:]
+            )
+            fix = "fix the link target so it resolves under docs/ or the repo root, or remove it"
+        else:
+            directory = posixpath.dirname(source)
+            joined = target if directory in ("", ".") else f"{directory}/{target}"
+            ok = self._target_exists(ctx, joined)
+            fix = f"fix the link target so it resolves relative to {directory}/, or remove it"
+
+        if not ok:
+            yield self.report(source, f"missing local reference {raw}", fix, line=line)
+
+    def _target_exists(self, ctx: Context, candidate: str) -> bool:
+        target = candidate.rstrip("/")
+        basename = target.rsplit("/", 1)[-1]
+        if "." in basename:
+            return self._case_exists(ctx, target)
+        for suffix in ("", "/README.md", "/README.mdx", "/index.md", "/index.mdx", ".md", ".mdx"):
+            if self._case_exists(ctx, f"{target}{suffix}"):
+                return True
+        return False
+
+    def _case_exists(self, ctx: Context, candidate: str) -> bool:
+        """Exact-case existence, without `.` — see the module docstring."""
+        path = ctx.path(posixpath.normpath(candidate))
+        try:
+            if not path.exists():
+                return False
+            if path.is_dir():
+                return True
+            return any(entry.name == path.name for entry in path.parent.iterdir())
+        except OSError:
+            return False

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-broken/.plans/c_done/26-07-27-history.md

@@ -0,0 +1,3 @@
+---
+plan_state: completed
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-broken/docs/README.md

@@ -0,0 +1,8 @@
+---
+title: "Readme"
+description: "Case-exactness target"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-broken/docs/architecture/product/links.md

@@ -0,0 +1,20 @@
+---
+title: "Links"
+description: "Three links on this page do not resolve"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+[Sibling](./route-target.md)
+
+[Published route](/architecture/product/route-target/)
+
+[Completed plan](../../../.plans/c_done/26-07-27-history.md)
+
+[Missing](./does-not-exist.md)
+
+[Wrong case](../../readme.md)
+
+Retired path: `docs/strategy/old-page.md`.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-broken/docs/architecture/product/route-target.md

@@ -0,0 +1,8 @@
+---
+title: "Route target"
+description: "Existing target for a published route reference"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-clean/.plans/c_done/26-07-27-history.md

@@ -0,0 +1,3 @@
+---
+plan_state: completed
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-clean/docs/README.md

@@ -0,0 +1,8 @@
+---
+title: "Readme"
+description: "Case-exactness target"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-clean/docs/architecture/product/links.md

@@ -0,0 +1,20 @@
+---
+title: "Links"
+description: "Every link on this page resolves"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+[Sibling](./route-target.md)
+
+[Published route](/architecture/product/route-target/)
+
+[Exact case](../../README.md)
+
+[Completed plan](../../../.plans/c_done/26-07-27-history.md)
+
+```
+[Inside a fence](./does-not-exist.md)
+```

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-clean/docs/architecture/product/route-target.md

@@ -0,0 +1,8 @@
+---
+title: "Route target"
+description: "Existing target for a published route reference"
+document_type: architecture
+status: canonical
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/test_check.py

@@ -0,0 +1,166 @@
+"""LAY-011 — every local link in a Markdown page resolves.
+
+Ported from `compliance_new/checks/layout/references/test.sh`. Same two
+corpora (`link-targets-clean`, `link-targets-broken`), same scenario names,
+same file contents — the shell tree's `cd` + `ADL_CHANGED_FILES` invocation
+replaced by the row's real `engine.scope` narrowing applied by hand (see
+`graded` below), then `References.graded` called directly.
+
+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
+`References.graded` directly against a hand-built `Context`/`FileSet` rather
+than going through `runner.run`/`checks.lookup` — the same bypass
+`docs/markdown_ast/test_check.py` and `docs/indexes/test_check.py` use 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.
+
+Not ported: the shell suite's "no set: could not run" and wiring-dispatch
+cases. Both asserted a shell-only mechanism (`ADL_CHANGED_FILES` unset,
+`dispatch_contract` resolving a row to a script path) that this architecture
+does not have — `graded` always receives an explicit `FileSet`, so "handed
+nothing to grade" is an empty/non-matching set, a clean no-op, never a
+could-not-run.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from helpers import corpus, corpus_files
+
+from adl_compliance.checks.layout.references import References
+from adl_compliance.core import scope
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.verdict import Outcome, decide
+from adl_compliance.policy.registry import load
+
+CORPORA = corpus("layout", "references")
+ROW = load().by_id("LAY-011")
+
+
+def graded(root: pathlib.Path, given: tuple[str, ...] | None = None):
+    """The row's real `engine.scope` — `{<docs>,<plans>,<specs>}/**` less
+    `.plans/c_done/**` — applied to the given set exactly as `runner.run`
+    would, then handed to the check being tested."""
+    files = corpus_files(root) if given is None else given
+    narrowed = FileSet(paths=scope.intersect(ROW.resolved_scope(), files))
+    ctx = Context(root=root, row=ROW, inputs={"docs_root": root / "docs"})
+    findings = tuple(References().graded(ctx, narrowed))
+    return decide(ROW, findings, 0, ())
+
+
+def test_the_row_declares_the_gate_this_check_ports() -> None:
+    assert ROW.domain == "layout"
+    assert ROW.name == "references"
+
+
+def test_a_page_whose_every_link_resolves_is_silent() -> None:
+    """Asserted first. Without it, every case below also passes against a
+    check that reports every link it finds — the four resolving links, a
+    published route rewritten to its `.md` form, an exact-case parent
+    reference, and a path that climbs out of docs/ into `.plans/c_done/`, plus
+    a fifth link inside a fenced block that must not be read at all."""
+    verdict = graded(CORPORA / "link-targets-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_broken_links_are_reported_exactly() -> None:
+    verdict = graded(CORPORA / "link-targets-broken")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+
+    rendered = verdict.render()
+    assert (
+        "docs/architecture/product/links.md:16: missing local reference "
+        "./does-not-exist.md" in rendered
+    ), rendered
+
+    # The case rule, and the reason the corpus commits `docs/README.md`: on a
+    # case-insensitive filesystem `Path("docs/readme.md").exists()` is TRUE, so
+    # a check that tested existence alone would call this link resolved. It is
+    # wrong by case and by nothing else.
+    assert (
+        "docs/architecture/product/links.md:18: missing local reference "
+        "../../readme.md" in rendered
+    ), rendered
+
+    # A separate scanner from the link parser above — it reads the raw line,
+    # not a Markdown link, so an inline-code mention still counts.
+    assert "stale retired docs path docs/strategy/old-page.md" in rendered, rendered
+
+    # The three defects are the corpus's only defects. More than three means
+    # one of the four resolving links, or the fenced one, was reported too.
+    assert len(verdict.findings) == 3, rendered
+    assert all(f.rule == "LAY-011" for f in verdict.findings), rendered
+    # The rule id is the gate's own. A finding printed under a neighbour's id
+    # sends the reader to the wrong check — 58866d2, for LAY-008.
+    assert not any(f.rule == "LAY-010" for f in verdict.findings), rendered
+
+
+def test_a_page_outside_the_given_set_is_not_graded() -> None:
+    """The broken corpus is unchanged on disk and its links are still wrong,
+    but only the clean route target is in the given set, so there is nothing
+    to grade."""
+    verdict = graded(
+        CORPORA / "link-targets-broken",
+        given=("docs/architecture/product/route-target.md",),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_completed_plan_resolves_as_a_target_though_excluded_as_a_source() -> None:
+    """The row's scope excludes `.plans/c_done/**` as a SOURCE — a completed
+    plan is a historical record, not rewritten when its named paths move — but
+    the same path still resolves as a link TARGET read straight off disk.
+    Narrowing the given set to just the linking page (dropping the `.plans/`
+    file from the set entirely) must not turn that resolving link into a
+    missing one."""
+    verdict = graded(
+        CORPORA / "link-targets-clean",
+        given=("docs/architecture/product/links.md", "docs/architecture/product/route-target.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_redeclared_docs_tree_still_catches_a_stale_retired_reference(
+    tmp_path: pathlib.Path,
+) -> None:
+    """The SILENT false pass `RETIRED_PATH` shipped with.
+
+    `RETIRED_PATH` was a hardcoded `docs/strategy/` literal, scanned across
+    raw line text. A repository whose docs root is not the packaged default
+    had a real stale mention -- written with its own redeclared prefix -- go
+    unmatched: no error, no finding, indistinguishable from a page carrying
+    no stale reference at all.
+
+    A real page under a redeclared docs root, genuinely mentioning a retired
+    `<root>/strategy/...` path: ungraded before the fix, caught after."""
+    import yaml
+
+    from adl_compliance.policy.registry import Registry, effective_trees, policy_text
+
+    root = tmp_path / "repo"
+    page = root / "documentation" / "architecture" / "note.md"
+    page.parent.mkdir(parents=True)
+    page.write_text(
+        "See documentation/strategy/2025-roadmap.md for the retired plan.\n",
+        encoding="utf-8",
+    )
+
+    trees = {"docs": "documentation"}
+    document = yaml.safe_load(policy_text("gate-registry.yaml"))
+    registry = Registry.model_validate(document, context={"trees": trees})
+    row = registry.by_id("LAY-011")
+
+    files = ("documentation/architecture/note.md",)
+    narrowed = FileSet(paths=scope.intersect(row.resolved_scope(effective_trees(trees)), files))
+    ctx = Context(root=root, row=row, inputs={"docs_root": root / "documentation"})
+    findings = tuple(References().graded(ctx, narrowed))
+    verdict = decide(row, findings, 0, ())
+    assert any(
+        "stale retired docs path" in f.message for f in verdict.findings
+    ), (
+        f"a real stale reference under a redeclared docs tree went "
+        f"unreported: {verdict.render()}"
+    )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/__init__.py

@@ -0,0 +1,11 @@
+"""The `layout.root-closed-set` gate.
+
+A folder rather than a module because this gate GRADES A NAMED SET (the
+declared root shape); anything else in here is what it grades.
+"""
+
+from __future__ import annotations
+
+from .check import RootClosedSet
+
+__all__ = ["RootClosedSet"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/check.py

@@ -0,0 +1,135 @@
+"""LAY-012 — the repository root is a closed set.
+
+Every top-level file and directory must be declared below. A new root entry is
+a deliberate structural decision, so this gate fails closed: anything not on
+these lists is a failure until someone adds it here on purpose.
+
+Two rules, split across the hooks exactly the way the base class draws the
+line:
+
+    graded      undeclared entries. A path with no "/" in the GIVEN SET is a
+                root FILE; the first segment of any other path names a root
+                DIRECTORY. An entry is undeclared because it is IN THE SET, not
+                because it is on disk (K-29..K-31) — narrowing the set is the
+                honest way to write the clean case: same tree, and the only
+                difference is what the caller handed over, exactly as a diff
+                that touched nothing undeclared would look in production.
+
+    structural  declared-but-missing entries. Reads DISK by design: a rename or
+                deletion can drop a top-level tree the repository contract
+                still promises with no file inside it changing, so this arm
+                probes the ALLOWED_* names directly rather than the given set.
+                `README.md` is exempted — carried over from `check-root-layout.sh`,
+                which skips it for the same reason (not restated there beyond
+                the `continue`).
+
+ALLOWED_FILES and ALLOWED_DIRS are the closed set itself: named requirements,
+not scope, and the list cannot grow with the tree.
+
+Ported from `compliance_new/checks/layout/root-closed-set/check.sh` with one
+correction verified against that script's own fixture and against this
+checkout's real root: the shell array holds the literal strings ".attributes"
+and ".ignore" where every other trace of intent — the committed fixture (whose
+files are actually named ".gitattributes" and ".gitignore", the latter's
+sibling literally commented "a declared top-level file"), the real repository
+root, and `check-root-layout.sh`'s own prose (which shows the same corruption:
+"`e --show-toplevel`", "` ls-files`", "` init`", each missing a "git" that
+belongs there) — agrees the intended names are ".gitattributes" and
+".gitignore". Running the shell check unmodified against its own fixture
+confirms the bug: the "clean" case it is supposed to pass reports 4 findings
+instead of 0 (".gitattributes"/".gitignore" as undeclared, ".attributes"/
+".ignore" as declared-but-missing). Corrected here rather than reproduced,
+since reproducing it would make this port fail against the very fixture it
+was told to carry over. See this check's dispatch notes for the un-ported
+`RULE_ID=LAY-011` quirk (deliberately kept) and the shell env-var guard
+(deliberately not ported — the runner-owned Context/FileSet contract has no
+"unset" state to guard against).
+"""
+
+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
+from ....policy.root_shape import (
+    ALLOWED_ROOT_DIRS,
+    ALLOWED_ROOT_FILES,
+    REQUIRED_ROOT_FILES,
+)
+
+
+class RootClosedSet(Check):
+    id: ClassVar[str] = "LAY-012"
+
+    # `check-root-layout.sh` hardcodes `RULE_ID=LAY-011`, not LAY-012 — its own
+    # row's id. Ported as-is rather than corrected to the row id: `rule` naming
+    # a different literal than `id` is an established, tolerated shape
+    # elsewhere in this package (`docs/ledger`'s DOC-009/KNW-002,
+    # `pipeline/phase_disjoint`'s PIP-004/MET-001), and `test.sh` asserts the
+    # literal "LAY-011 " prefix on every finding line — changing it here would
+    # port a different gate than the one `test.sh` describes.
+    rule: ClassVar[str] = "LAY-011"
+
+    # PERMITTED at the root — not required to be present. The two are different
+    # rules and this gate used to run them off one list: `structural` asserted
+    # that every allowed entry EXISTS, so declaring `.cursorrules` permissible
+    # also declared it mandatory. On a repository that simply does not use half
+    # of them, an allowlist became a manifest and reported a missing file for
+    # each. A closed set says "nothing outside this"; it says nothing at all
+    # about what must be inside it.
+    #
+    # The contents below are also deliberately language-agnostic where they can
+    # be. This package is installed into arbitrary repositories, and its own
+    # config module states the principle these lists were breaking: "a path
+    # outside this package, written inside it, is a dependency on this
+    # particular checkout's shape."
+    ALLOWED_FILES: ClassVar[frozenset[str]] = ALLOWED_ROOT_FILES
+
+    # PERMITTED at the root, same as the files above: present is fine, absent
+    # is fine. Several entries here name trees no longer in use anywhere
+    # (`.code-review-graph_old`, `.plans`, `.specs`) and they cost nothing while
+    # they only permit; under the old manifest reading, each was a finding.
+    ALLOWED_DIRS: ClassVar[frozenset[str]] = ALLOWED_ROOT_DIRS
+
+    # What a repository must actually HAVE at its root, as opposed to what it
+    # is permitted to have. Kept deliberately tiny: this package is installed
+    # into repositories whose shape it does not know, and every entry here is a
+    # demand made of all of them.
+    REQUIRED_FILES: ClassVar[frozenset[str]] = REQUIRED_ROOT_FILES
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        for want in sorted(self.REQUIRED_FILES):
+            if not ctx.path(want).is_file():
+                yield self.report(
+                    want, "required top-level file is missing",
+                    f"create {want} — it is the entry point for anyone, human or "
+                    "agent, arriving at this repository",
+                )
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        # The root listing, recovered from the given set: a path with no "/"
+        # is a root file, and the first segment of any other path names a root
+        # directory.
+        dirs: set[str] = set()
+        root_files: set[str] = set()
+        for path in files:
+            if "/" in path:
+                dirs.add(path.split("/", 1)[0])
+            else:
+                root_files.add(path)
+
+        for name in sorted(dirs):
+            if name not in self.ALLOWED_DIRS:
+                yield self.report(
+                    name, "undeclared top-level directory",
+                    f"declare {name}/ in ALLOWED_DIRS, or move it into an owning tree",
+                )
+        for name in sorted(root_files):
+            if name not in self.ALLOWED_FILES:
+                yield self.report(
+                    name, "undeclared top-level file",
+                    f"declare {name} in ALLOWED_FILES, or move it into an owning tree",
+                )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.agents/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.changeset/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.claude/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.code-review-graph/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.code-review-graph_old/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.codex/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.cursor/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.cursorrules

@@ -0,0 +1 @@
+root-layout corpus: a declared top-level file.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.dockerignore

@@ -0,0 +1 @@
+root-layout corpus: a declared top-level file.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.docs/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.donors/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.gitattributes

@@ -0,0 +1 @@
+root-layout corpus: a declared top-level file.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.kimi-code/declared.txt

@@ -0,0 +1 @@
+root-layout corpus: content under a declared top-level directory.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.lfsconfig

@@ -0,0 +1 @@
+root-layout corpus: a declared top-level file.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.mcp.json

@@ -0,0 +1 @@
+root-layout corpus: a declared top-level file.