@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

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

@@ -9,9 +9,13 @@ nothing to contribute.
 Four rules, evaluated independently per path (a single path can trip more than
 one):
 
-  1. root allowlist    a file with no `/` must be on the enumerated allowlist
-                        of files legitimately committed at the repository root.
-  2. apps/ retired      any path under the retired `apps/` tree.
+  1. root allowlist    a file with no `/` must be on the allowlist of files
+                        legitimately committed at the repository root: the
+                        central set in `policy/root_shape.py` plus whatever the
+                        repository itself declares (`root-files`).
+  2. apps/ retired      any path under the retired `apps/` tree -- unless the
+                        repository declares `apps` among its root directories
+                        (`root-dirs`), which says `apps/` is live there.
   3. stray artifacts    a throwaway extension (`.log`/`.tmp`/`.bak`/`.swp`,
                          checked STRICTLY, everywhere) or a screenshot/image
                          basename outside the enumerated asset directories.
@@ -45,7 +49,12 @@ 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_FILES
+from ....policy.root_shape import (
+    ALLOWED_ROOT_FILES,
+    ROOT_DIRS_DECLARATION,
+    allowed_root_files,
+    declared_root_names,
+)
 
 
 class Placement(Check):
@@ -62,6 +71,10 @@ class Placement(Check):
     # `.attributes` and `.ignore`, which LAY-012 had long since corrected to
     # `.gitattributes` and `.gitignore` — so the same file was permitted by one
     # gate and reported by the other.
+    #
+    # This is the CENTRAL default only. What is actually graded is the effective
+    # set, `allowed_root_files(ctx.declarations)`: this plus the names the
+    # repository declares under `[controls.compliance.root] files`.
     ROOT_ALLOWLIST: ClassVar[frozenset[str]] = ALLOWED_ROOT_FILES
 
     THROWAWAY_SUFFIXES: ClassVar[tuple[str, ...]] = (
@@ -139,24 +152,34 @@ class Placement(Check):
         )
 
     def _md_src_trees(self, ctx: Context) -> tuple[str, ...]:
-        return self.MD_SRC_TREES_LITERAL + (f"{ctx.relative(ctx.inputs['rust_root'])}/",)
+        # Decision for a tree declared absent (`rust = ""`, which drops
+        # `rust_root` from the resolved inputs): the rust root only contributes
+        # an extra PREFIX to the trees whose `src/` Markdown is reported, so a
+        # repository with no Rust tree has nothing under it to report and
+        # contributes nothing. The literal `agent/` tree still governs. This read
+        # `ctx.inputs['rust_root']` unguarded -- a `KeyError` traceback (exit 1),
+        # not a verdict, on any `.md` path.
+        rust_root = ctx.inputs.get("rust_root")
+        if rust_root is None:
+            return self.MD_SRC_TREES_LITERAL
+        return self.MD_SRC_TREES_LITERAL + (f"{ctx.relative(rust_root)}/",)
 
     def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
         # `LC_ALL=C sort` in the shell is a byte-order sort; Python's default
         # string ordering matches it for the ASCII repository-relative paths
         # this row ever sees.
         for relative in sorted(files):
-            yield from self._root_allowlist(relative)
-            yield from self._apps_retired(relative)
+            yield from self._root_allowlist(ctx, relative)
+            yield from self._apps_retired(ctx, relative)
             yield from self._stray_artifact(ctx, relative)
             yield from self._md_sprawl(ctx, relative)
 
     # -- Rule 1: root-level allowlist ---------------------------------------
 
-    def _root_allowlist(self, relative: str) -> Iterable[Report]:
+    def _root_allowlist(self, ctx: Context, relative: str) -> Iterable[Report]:
         if "/" in relative:
             return
-        if relative in self.ROOT_ALLOWLIST:
+        if relative in allowed_root_files(ctx.declarations):
             return
         # The allowlist is ~60 entries. Printing all of them per finding buries
         # the one fact the line is reporting, and five findings produced three
@@ -164,13 +187,18 @@ class Placement(Check):
         yield self.report(
             relative,
             f"root: '{relative}' is not on the root allowlist",
-            f"move '{relative}' into an owning subdirectory, or add it to "
-            "policy/root_shape.py if it genuinely belongs at the root",
+            f"move '{relative}' into an owning subdirectory, or declare it under "
+            "[controls.compliance.root] files in this repository's adl-config.toml "
+            "if it genuinely belongs at the root",
         )
 
     # -- Rule 2 (numbered 4 in check.sh): apps/ is retired ------------------
 
-    def _apps_retired(self, relative: str) -> Iterable[Report]:
+    def _apps_retired(self, ctx: Context, relative: str) -> Iterable[Report]:
+        # A repository that declares `apps` as a root directory has said `apps/`
+        # is live there; "apps is retired" would contradict its own declaration.
+        if "apps" in declared_root_names(ctx.declarations, ROOT_DIRS_DECLARATION):
+            return
         if relative.startswith("apps/"):
             yield self.report(
                 relative,

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

@@ -228,3 +228,111 @@ def test_a_redeclared_rust_root_still_catches_md_sprawl(tmp_path: pathlib.Path)
         f"real markdown sprawl under a redeclared rust root went "
         f"unreported: {findings}"
     )
+
+
+# ---------------------------------------------- per-repository root declarations
+def graded_declaring(
+    declarations: dict[str, str], paths: tuple[str, ...], root: pathlib.Path = ALLOWED
+) -> Verdict:
+    """`graded_directly`, plus what the repository declared about its own root
+    (`[controls.compliance.root]` arrives as the `root-files` / `root-dirs`
+    declarations)."""
+    ctx = Context(
+        root=root, row=ROW, declarations=declarations,
+        inputs={
+            "docs_root": root / "docs",
+            "rust_root": root / "backend",
+            "frontend_root": root / "frontend",
+            "specs_root": root / ".specs",
+        },
+    )
+    findings = tuple(Placement().graded(ctx, FileSet(paths=paths)))
+    return decide(ROW, findings, 0, ())
+
+
+def test_a_non_standard_root_file_is_reported_without_a_declaration() -> None:
+    """STATUS.md is not on the central list any more: without the repository
+    declaring it, it is an undeclared root file."""
+    verdict = graded_declaring({}, ("STATUS.md",))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [f.path for f in verdict.findings] == ["STATUS.md"]
+    assert "root allowlist" in verdict.findings[0].message
+
+
+def test_a_declared_root_file_is_accepted() -> None:
+    verdict = graded_declaring({"root-files": "STATUS.md,DRIFT.md"}, ("STATUS.md", "DRIFT.md"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declaration_admits_only_the_names_it_lists() -> None:
+    """Without this, the case above also passes against a gate that stops
+    grading the root as soon as any declaration is present."""
+    verdict = graded_declaring({"root-files": "STATUS.md"}, ("STATUS.md", "DRIFT.md"))
+    assert [f.path for f in verdict.findings] == ["DRIFT.md"], verdict.render()
+
+
+def test_a_root_dirs_declaration_does_not_admit_a_root_file() -> None:
+    verdict = graded_declaring({"root-dirs": "STATUS.md"}, ("STATUS.md",))
+    assert [f.path for f in verdict.findings] == ["STATUS.md"], verdict.render()
+
+
+def test_the_root_file_remedy_points_at_the_declaration_not_at_source() -> None:
+    """The old remedy sent a reader to edit `policy/root_shape.py` in the shared
+    package. The repository owns the declaration, so the remedy names it."""
+    finding = graded_declaring({}, ("STATUS.md",)).findings[0]
+    assert "[controls.compliance.root]" in finding.fix, finding.fix
+    assert "adl-config.toml" in finding.fix, finding.fix
+    assert "root_shape.py" not in finding.fix, finding.fix
+
+
+def test_apps_stays_retired_unless_the_repository_declares_it() -> None:
+    """The retired-`apps/` rule is active by default, and declaring a DIFFERENT
+    directory does not switch it off."""
+    for declarations in ({}, {"root-dirs": "packaging"}, {"root-files": "apps"}):
+        verdict = graded_declaring(declarations, ("apps/legacy/file.ts",))
+        assert [f.path for f in verdict.findings] == ["apps/legacy/file.ts"], declarations
+        assert "apps-retired" in verdict.findings[0].message
+
+
+def test_a_declared_apps_directory_is_not_retired() -> None:
+    """A declared `apps/` contradicts "apps is retired", so the rule stands down."""
+    for declarations in ({"root-dirs": "apps"}, {"root-dirs": "packaging, apps"}):
+        verdict = graded_declaring(declarations, ("apps/legacy/file.ts", "apps/cli/src/main.ts"))
+        assert verdict.outcome is Outcome.CLEAN, (declarations, verdict.render())
+
+
+def test_enact_config_is_a_built_in_root_file_beside_adl_config() -> None:
+    """Owner decision (Tarun, 2026-10-01): an adl-controlled Enact repository
+    carries BOTH `adl-config.toml` and `enact-config.toml` at its root,
+    permanently. Neither is declared by hand under `[controls.compliance.root]`."""
+    verdict = graded_declaring({}, ("adl-config.toml", "enact-config.toml"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_unknown_root_toml_still_fails_beside_enact_config() -> None:
+    """Without this, the case above also passes against a gate that admits
+    every root `.toml`."""
+    verdict = graded_declaring({}, ("enact-config.toml", "random.toml"))
+    assert [f.path for f in verdict.findings] == ["random.toml"], verdict.render()
+
+
+# ------------------------------------------------- a tree declared absent
+def test_a_rust_tree_declared_absent_contributes_nothing_to_md_sprawl(
+    tmp_path: pathlib.Path,
+) -> None:
+    """`rust = ""` (the repository states it has no Rust tree) drops `rust_root`
+    from the resolved inputs. In `_md_src_trees` that input only ever ADDS a
+    prefix to the trees whose `src/` Markdown is reported, so absent it
+    contributes nothing and the literal `agent/` tree still governs. This was a
+    `KeyError: 'rust_root'` traceback (exit 1, not could-not-run) on any `.md`
+    path, measured against enact-combined with `--tree rust= --tree frontend=`.
+    The rule is not switched off: `agent/**/src/*.md` is still reported."""
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": tmp_path / "docs"})
+    findings = tuple(
+        Placement().graded(
+            ctx,
+            FileSet(paths=("notes/overview.md", "backend/crates/x/src/n.md", "agent/crates/x/src/n.md")),
+        )
+    )
+    assert [f.path for f in findings] == ["agent/crates/x/src/n.md"], findings
+    assert "md-sprawl" in findings[0].message

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

@@ -11,15 +11,20 @@ class PlanMetadata:
 
     WORK_ITEM_STATUSES: ClassVar[tuple[str, ...]] = (
         "New",
+        "In Planning",
+        "Awaiting Approval",
         "Approved",
-        "Committed",
-        "In Progress",
+        "Spec Validation",
+        "In Implementation",
         "In Testing",
+        "In Review",
+        "Updating Docs",
         "Done",
+        "Parked for Removal",
         "Removed",
     )
-    ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[:5])
-    TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[5:])
+    ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[:9])
+    TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[9:])
 
     STATUS_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^status:\s*(.+)$")
     WORK_ITEM_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^work_item:\s*(.+)$")

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

@@ -67,7 +67,7 @@ class PlansLayout(Check):
     # you can tell what a file is from its name, in every feature, without opening
     # it. Adding a name here later is cheap; leaving the set open is how a tree
     # ends up with HANDOVER.md, handover-v2.md and channels-notes.md side by side.
-    SUPPORTING: ClassVar[tuple[str, ...]] = ("handoff.md", "review.md")
+    SUPPORTING: ClassVar[tuple[str, ...]] = ("handoff.md", "intent.md", "review.md")
 
     ROOT_DIRS: ClassVar[tuple[str, ...]] = ("features", "templates")
     # `GAPS-AND-FINDINGS.md` sits here because its own rows say where they go:

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/features/az347-test-coverage/items/az351-restore-entrypoint.md

@@ -1,7 +1,7 @@
 ---
 type: bug
 title: "Restore the entrypoint"
-status: Committed
+status: Done
 work_item: https://dev.azure.com/org/proj/_workitems/edit/351
 last_update: 2026-09-15T03:20:00Z
 ---

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

@@ -14,7 +14,7 @@ from __future__ import annotations
 
 import pathlib
 
-from helpers import corpus, corpus_files
+from helpers import corpus
 
 from adl_compliance.checks.layout.plans_layout import PlansLayout
 from adl_compliance.core.context import Context, FileSet
@@ -199,8 +199,8 @@ def test_an_extra_file_beside_spec_is_reported(tmp_path: pathlib.Path) -> None:
     # The message ENUMERATES what is allowed, so whoever hits it can correct the
     # file without opening the check. A bare "not allowed" sends the reader here.
     finding = next(f for f in verdict.findings if "Feature directory holds" in f.message)
-    assert finding.message == "a Feature directory holds spec.md, handoff.md, review.md, items/ only"
-    assert "rename it to one of handoff.md, review.md" in finding.fix
+    assert finding.message == "a Feature directory holds spec.md, handoff.md, intent.md, review.md, items/ only"
+    assert "rename it to one of handoff.md, intent.md, review.md" in finding.fix
 
 
 def test_supporting_documents_are_permitted_beside_spec(tmp_path: pathlib.Path) -> None:

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

@@ -62,9 +62,8 @@ class References(Check):
     # 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.)
+    # it the same way. (The gate that owned LAY-010, `layout.profile-data`, was retired
+    # 2026-10-01, so no gate answers to that id now.)
     rule: ClassVar[str] = "LAY-011"
 
     # This gate's own values, and no other module's business. Shared values are

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

@@ -23,8 +23,13 @@ line:
                 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.
+ALLOWED_FILES and ALLOWED_DIRS are the CENTRAL closed set: named requirements,
+not scope, and the list cannot grow with the tree. What is graded is the
+effective set -- the central one plus the names the repository declares under
+`[controls.compliance.root]` in its own adl-config.toml (`files`, `dirs`), which
+reach this gate as `Context.declarations["root-files" | "root-dirs"]`. A
+non-standard root entry is declared by the repository that has it, never added
+here.
 
 Ported from `compliance_new/checks/layout/root-closed-set/check.sh` with one
 correction verified against that script's own fixture and against this
@@ -58,6 +63,8 @@ from ....policy.root_shape import (
     ALLOWED_ROOT_DIRS,
     ALLOWED_ROOT_FILES,
     REQUIRED_ROOT_FILES,
+    allowed_root_dirs,
+    allowed_root_files,
 )
 
 
@@ -86,12 +93,18 @@ class RootClosedSet(Check):
     # 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."
+    #
+    # The CENTRAL default. The effective set is
+    # `allowed_root_files(ctx.declarations)`, computed at grade time.
     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.
+    #
+    # The CENTRAL default. The effective set is
+    # `allowed_root_dirs(ctx.declarations)`, computed at grade time.
     ALLOWED_DIRS: ClassVar[frozenset[str]] = ALLOWED_ROOT_DIRS
 
     # What a repository must actually HAVE at its root, as opposed to what it
@@ -121,15 +134,19 @@ class RootClosedSet(Check):
             else:
                 root_files.add(path)
 
+        allowed_dirs = allowed_root_dirs(ctx.declarations)
+        allowed_files = allowed_root_files(ctx.declarations)
         for name in sorted(dirs):
-            if name not in self.ALLOWED_DIRS:
+            if name not in allowed_dirs:
                 yield self.report(
                     name, "undeclared top-level directory",
-                    f"declare {name}/ in ALLOWED_DIRS, or move it into an owning tree",
+                    f"declare {name} under [controls.compliance.root] dirs in this "
+                    "repository's adl-config.toml, or move it into an owning tree",
                 )
         for name in sorted(root_files):
-            if name not in self.ALLOWED_FILES:
+            if name not in allowed_files:
                 yield self.report(
                     name, "undeclared top-level file",
-                    f"declare {name} in ALLOWED_FILES, or move it into an owning tree",
+                    f"declare {name} under [controls.compliance.root] files in this "
+                    "repository's adl-config.toml, or move it into an owning tree",
                 )

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

@@ -120,3 +120,79 @@ def test_the_structural_half_still_runs_on_an_empty_set() -> None:
     still a clean verdict."""
     verdict = verdict_for(())
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ---------------------------------------------- per-repository root declarations
+def verdict_declaring(declarations: dict[str, str], given: tuple[str, ...]) -> Verdict:
+    """`verdict_for`, plus what the repository declared about its own root
+    (`[controls.compliance.root]` arrives as the `root-files` / `root-dirs`
+    declarations)."""
+    ctx = Context(root=CORPUS, row=ROW, declarations=declarations)
+    findings = tuple(
+        r for r in RootClosedSet().run(ctx, FileSet(paths=given)) if isinstance(r, Finding)
+    )
+    return decide(ROW, findings, 0, ())
+
+
+def test_a_non_standard_root_directory_is_undeclared_without_a_declaration() -> None:
+    """`apps/` and `packaging/` are not on the central list any more."""
+    for name in ("apps", "packaging"):
+        verdict = verdict_declaring({}, (f"{name}/cli/main.ts",))
+        assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+        assert [f.path for f in verdict.findings] == [name], verdict.render()
+        assert f"{name}: undeclared top-level directory" in verdict.render()
+
+
+def test_a_declared_root_directory_is_accepted() -> None:
+    verdict = verdict_declaring(
+        {"root-dirs": "apps,packaging"}, ("apps/cli/main.ts", "packaging/npm/package.json"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_non_standard_root_file_is_undeclared_without_a_declaration() -> None:
+    """STATUS.md and DRIFT.md are not on the central list any more."""
+    for name in ("STATUS.md", "DRIFT.md"):
+        verdict = verdict_declaring({}, (name,))
+        assert [f.path for f in verdict.findings] == [name], verdict.render()
+        assert f"{name}: undeclared top-level file" in verdict.render()
+
+
+def test_a_declared_root_file_is_accepted() -> None:
+    verdict = verdict_declaring({"root-files": "STATUS.md, DRIFT.md"}, ("STATUS.md", "DRIFT.md"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declaration_does_not_silence_the_rest_of_the_root() -> None:
+    """Without this, the accept cases above also pass against a gate that stops
+    grading the root once any declaration is present."""
+    verdict = verdict_declaring(
+        {"root-dirs": "apps", "root-files": "STATUS.md"},
+        ("apps/cli/main.ts", "STATUS.md", "unapproved-root/x.md", "undeclared-root-file.txt"),
+    )
+    assert sorted(f.path for f in verdict.findings) == [
+        "unapproved-root", "undeclared-root-file.txt",
+    ], verdict.render()
+
+
+def test_the_files_and_dirs_declarations_do_not_cross() -> None:
+    """A name declared as a directory does not admit a file of that name, and
+    the other way round."""
+    dirs_only = verdict_declaring({"root-dirs": "thing"}, ("thing",))
+    assert [f.path for f in dirs_only.findings] == ["thing"], dirs_only.render()
+    files_only = verdict_declaring({"root-files": "thing"}, ("thing/x.ts",))
+    assert [f.path for f in files_only.findings] == ["thing"], files_only.render()
+
+
+def test_the_remedies_point_at_the_declaration_not_at_source() -> None:
+    """The old remedies said "declare X in ALLOWED_DIRS/ALLOWED_FILES" -- a
+    constant in the shared package. The repository owns the declaration."""
+    by_path = {
+        f.path: f for f in verdict_declaring({}, ("apps/cli/main.ts", "STATUS.md")).findings
+    }
+    directory, file = by_path["apps"], by_path["STATUS.md"]
+    for finding, key in ((directory, "dirs"), (file, "files")):
+        assert "[controls.compliance.root]" in finding.fix, finding.fix
+        assert "adl-config.toml" in finding.fix, finding.fix
+        assert key in finding.fix, finding.fix
+        assert "ALLOWED_" not in finding.fix, finding.fix

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

@@ -32,7 +32,13 @@ 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 GOVERNANCE, GUIDES, REGISTERS
+from ....policy.root_shape import (
+    GOVERNANCE,
+    GUIDES,
+    REGISTERS,
+    ROOT_FILES_DECLARATION,
+    declared_root_names,
+)
 
 
 class RootMarkdownAllowlist(Check):
@@ -64,7 +70,12 @@ class RootMarkdownAllowlist(Check):
     # that does exist at `plans/AGENTS.md` went unseen while a phantom one was
     # demanded. The rule is about trees being documented, not about these exact
     # paths being present.
-    GUIDED_TREES: ClassVar[tuple[str, ...]] = (".workflows", "plans", "specs", "docs")
+    #
+    # `.workflows/` is deliberately not listed (owner decision, 2026-10-01): it is
+    # a machine-managed tree, written wholesale by `adl-repo-controls install` and
+    # never hand-authored, so it does not need a guide of its own. A guide that
+    # does exist there is still admitted by `_allowed_markdown`.
+    GUIDED_TREES: ClassVar[tuple[str, ...]] = ("plans", "specs", "docs")
 
     # Trees whose Markdown this repository does not author: vendored provider
     # documentation, and archives kept for reference. Renaming a README inside
@@ -199,8 +210,10 @@ class RootMarkdownAllowlist(Check):
                     path,
                     "tracked Markdown is outside the root allowlist",
                     f"move {path} under an allowed tree (docs/, plans/, .specs/, "
-                    ".changeset/, etc.), or add an explicit exception in "
-                    "check.py if it is a legitimate case",
+                    ".changeset/, etc.), or, if it is a root-level Markdown file "
+                    "this repository genuinely carries, declare it under "
+                    "[controls.compliance.root] files in this repository's "
+                    "adl-config.toml",
                 )
 
     def _allowed_markdown(self, ctx: Context, path: str) -> bool:
@@ -209,17 +222,27 @@ class RootMarkdownAllowlist(Check):
         # ADR-095 admits this one root-relative verification contract by
         # literal name.
         #
-        # `policy/root_shape.py` is THE list of what may sit at a repository's
+        # `policy/root_shape.py` is THE list of what may sit at EVERY repository's
         # root — GUIDES (AGENTS.md/CLAUDE.md/INVARIANTS.md/…), GOVERNANCE
         # (CONTRIBUTING.md/SECURITY.md/…) and REGISTERS (GAPS-AND-FINDINGS.md,
-        # OPEN-ITEMS.md, STATUS.md, DRIFT.md). This gate used to carry its own
-        # copy of that same set, hardcoded here, and the two had already
-        # drifted apart once (STATUS.md/DRIFT.md were on neither copy). Import
+        # OPEN-ITEMS.md). This gate used to carry its own copy of that same set,
+        # hardcoded here, and the copies had already drifted apart once. Import
         # rather than duplicate, exactly as `layout.markdown-trees` and
         # `layout.placement` already do — one policy, not a fourth copy of it.
         # (Tarun, 2026-09-27.)
+        #
+        # Root Markdown that is NOT standard (a repository's own STATUS.md,
+        # DRIFT.md) is not on that list: the repository declares it under
+        # `[controls.compliance.root] files`, and it arrives below as the
+        # `root-files` declaration. That lookup must stay AFTER this short-circuit —
+        # the central names are answered without a Context at all
+        # (tests/core/test_root_shape.py passes `ctx=None`).
         if path in (GUIDES | GOVERNANCE | REGISTERS):
             return True
+        if "/" not in path and path in declared_root_names(
+            ctx.declarations, ROOT_FILES_DECLARATION
+        ):
+            return True
         # Ported from check-markdown-placement.py: any AGENTS.md/CLAUDE.md
         # guide file is allowed regardless of folder — the AGENTS.md/CLAUDE.md
         # hierarchy is governed separately by layout.agents-layout.
@@ -260,11 +283,25 @@ class RootMarkdownAllowlist(Check):
         # above).
         if path in self.GOVERNANCE_FILES or path in self.RETAINED_MARKDOWN_FILES:
             return True
-        rust_root = ctx.relative(ctx.inputs["rust_root"])
-        frontend_root = ctx.relative(ctx.inputs["frontend_root"])
-        if path in {f"{rust_root}/{suffix}" for suffix in self.RUST_GOVERNANCE_SUFFIXES}:
+        # Decision for a tree declared absent (`rust = ""` / `frontend = ""`, which
+        # drops `rust_root` / `frontend_root` from the resolved inputs): both only
+        # ever ADD allowlist entries -- the governance suffixes and code-asset
+        # roots beneath the tree -- so a repository with no such tree has nothing
+        # there to admit and they contribute nothing. Strictly stricter, never a
+        # silent pass. These were read unguarded (`ctx.inputs["rust_root"]`): a
+        # stray root Markdown file, which every allowance above declines, reached
+        # them and raised `KeyError` -- a traceback with exit 1, not a verdict.
+        rust_input = ctx.inputs.get("rust_root")
+        rust_root = None if rust_input is None else ctx.relative(rust_input)
+        frontend_input = ctx.inputs.get("frontend_root")
+        frontend_root = None if frontend_input is None else ctx.relative(frontend_input)
+        if rust_root is not None and path in {
+            f"{rust_root}/{suffix}" for suffix in self.RUST_GOVERNANCE_SUFFIXES
+        }:
             return True
-        if path in {f"{frontend_root}/{suffix}" for suffix in self.FRONTEND_GOVERNANCE_SUFFIXES}:
+        if frontend_root is not None and path in {
+            f"{frontend_root}/{suffix}" for suffix in self.FRONTEND_GOVERNANCE_SUFFIXES
+        }:
             return True
         if path in {f"{workflows_root}/{suffix}" for suffix in self.WORKFLOWS_GOVERNANCE_SUFFIXES}:
             return True
@@ -272,19 +309,23 @@ class RootMarkdownAllowlist(Check):
             return True
         if any(path.startswith(code_root) for code_root in self.CODE_ASSET_ROOTS):
             return True
-        if any(
+        if rust_root is not None and any(
             path.startswith(f"{rust_root}/{suffix}") for suffix in self.RUST_CODE_ASSET_SUFFIXES
         ):
             return True
-        if any(
+        if frontend_root is not None and any(
             path.startswith(f"{frontend_root}/{suffix}")
             for suffix in self.FRONTEND_CODE_ASSET_SUFFIXES
         ):
             return True
         name = path.rsplit("/", 1)[-1]
-        if name in self.FRONTEND_LOCAL_DOC_NAMES and any(
-            path.startswith(f"{frontend_root}/{suffix}")
-            for suffix in self.FRONTEND_LOCAL_DOC_SUFFIXES
+        if (
+            frontend_root is not None
+            and name in self.FRONTEND_LOCAL_DOC_NAMES
+            and any(
+                path.startswith(f"{frontend_root}/{suffix}")
+                for suffix in self.FRONTEND_LOCAL_DOC_SUFFIXES
+            )
         ):
             return True
         return False