@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.30 → 0.1.32

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

@@ -31,13 +31,12 @@ from typing import ClassVar
 
 from ....core.check import Check
 from ....core.context import Context, FileSet
+from ....core.declarations import declared_root_files
 from ....core.finding import Report
 from ....policy.root_shape import (
     GOVERNANCE,
     GUIDES,
     REGISTERS,
-    ROOT_FILES_DECLARATION,
-    declared_root_names,
 )
 
 
@@ -49,12 +48,10 @@ class RootMarkdownAllowlist(Check):
         "workflows_root": "<workflows>",
         "plans_root": "<plans>",
         "docs_root": "<docs>",
-        "rust_root": "<rust>",
-        "frontend_root": "<frontend>",
     }
     """FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): every
-    `backend/...`/`frontend/...`/`.workflows/...`/`plans/...`/`.specs/...`/
-    `docs/...` entry below was a hardcoded literal, tested with `==`/
+    `.workflows/...`/`plans/...`/`docs/...` entry below was a hardcoded
+    literal, tested with `==`/
     `startswith` inside `_allowed_markdown`. A repository whose corresponding
     root is not the packaged default had a real, legitimately-allowed
     Markdown file fail every one of those tests, and the gate reported it as
@@ -63,19 +60,8 @@ class RootMarkdownAllowlist(Check):
     stays literal: named documents and code-asset trees, not resolvable
     paths."""
 
-    # A tree that EXISTS needs a guide. Previously these were three absolute
-    # requirements, which meant a repository without a `.specs/` tree was told
-    # to create a guide for a directory it had deliberately never made — and
-    # `.plans/` was named with a dot this layout no longer uses, so the guide
-    # 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.
-    #
-    # `.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")
+    # A tree that EXISTS needs a guide; `.workflows/` is deliberately not listed (machine-managed).
+    GUIDED_INPUTS: ClassVar[tuple[str, ...]] = ("plans_root", "docs_root")
 
     # Trees whose Markdown this repository does not author: vendored provider
     # documentation, and archives kept for reference. Renaming a README inside
@@ -83,7 +69,6 @@ class RootMarkdownAllowlist(Check):
     UNOWNED_ROOTS: ClassVar[tuple[str, ...]] = (
         ".agents-archive/",
         ".claude-plugin/",
-        ".donors/",
         "node_modules/",
         "scripts-archive/",
         "workflows-archived/",
@@ -112,53 +97,8 @@ class RootMarkdownAllowlist(Check):
         ".opencode/",
     )
 
-    # Ported from repo-hygiene/check-markdown-placement.py during the
-    # repo-hygiene -> .workflows dissolution (2026-08-04): explicit non-guide
-    # Markdown assets retained outside the published knowledge trees.
-    # Donor absorb triage: every commit of the 2026-08-12 donor fast-forward
-    # with an ABSORB / NOT USEFUL verdict. Tracked deliberately so the
-    # verdicts stay reviewable. Genuinely no resolvable tree prefix.
-    GOVERNANCE_FILES: ClassVar[frozenset[str]] = frozenset({".donors/MANIFEST.md"})
-    RUST_GOVERNANCE_SUFFIXES: ClassVar[frozenset[str]] = frozenset(
-        {"CHANGELOG.md", "crates/enact-session/src/backend/codex_init_prompt.md"}
-    )
-    FRONTEND_GOVERNANCE_SUFFIXES: ClassVar[frozenset[str]] = frozenset({"CHANGELOG.md"})
-    # repo-hygiene/CHANGELOG.md and repo-hygiene/LORE_COMMIT_IDS.md were
-    # deleted outright during the repo-hygiene -> .workflows dissolution — no
-    # successor entry.
-    WORKFLOWS_GOVERNANCE_SUFFIXES: ClassVar[frozenset[str]] = frozenset({"COVERAGE.md"})
-
-    # Genuinely no resolvable tree prefix -- "compliance" here is not
-    # `<compliance>` (that resolves to `compliance_py`); this is a distinct,
-    # literal historical path, unexamined by this fix.
-    RETAINED_MARKDOWN_FILES: ClassVar[frozenset[str]] = frozenset({"compliance/fixtures.md"})
-    # Three entries for now-parked trees stood here. Both trees are gone from
-    # the checkout and neither path is tracked, so the entries allowlisted
-    # nothing while keeping this file in violation of meta.parked-references.
-    WORKFLOWS_RETAINED_SUFFIXES: ClassVar[frozenset[str]] = frozenset(
-        {"config/exceptions/KNOWN-ISSUES.md"}
-    )
     CODE_ASSET_ROOTS: ClassVar[tuple[str, ...]] = (
         ".claude/skills/",
-        "agent/docs/",
-    )
-    RUST_CODE_ASSET_SUFFIXES: ClassVar[tuple[str, ...]] = (
-        "crates/enact-app/assets/builtin-assistants/rules/",
-        "crates/enact-app/assets/builtin-skills/",
-        "crates/enact-extension/tests/fixtures/builtin-skills-fixture/",
-    )
-    FRONTEND_CODE_ASSET_SUFFIXES: ClassVar[tuple[str, ...]] = (
-        ".claude/",
-        ".gemini/",
-        "examples/",
-    )
-    FRONTEND_LOCAL_DOC_SUFFIXES: ClassVar[tuple[str, ...]] = (
-        "packages/",
-        "scripts/",
-        "tests/e2e/",
-    )
-    FRONTEND_LOCAL_DOC_NAMES: ClassVar[frozenset[str]] = frozenset(
-        {"README.en.md", "MIGRATION.md"}
     )
 
     def structural(self, ctx: Context) -> Iterable[Report]:
@@ -167,7 +107,11 @@ class RootMarkdownAllowlist(Check):
         # file in the set" but "is the tree missing a required guide", which
         # no file set can answer — the set never contains a path that was
         # never created.
-        for tree in self.GUIDED_TREES:
+        for name in self.GUIDED_INPUTS:
+            declared = ctx.inputs.get(name)
+            if declared is None:
+                continue
+            tree = ctx.relative(declared)
             if not ctx.path(tree).is_dir():
                 continue
             guide = f"{tree}/AGENTS.md"
@@ -187,6 +131,7 @@ class RootMarkdownAllowlist(Check):
         # A path in the set that is not a file on disk is a DELETION, not a
         # finding: a removed Markdown file cannot violate an allowlist. Same
         # filter check.sh's `is_file()` applied to `ADL_CHANGED_FILES`.
+        declared_root_files(ctx.declarations)
         for path in sorted(files.existing(ctx.root)):
             # check.sh: `path.endswith("/README.md") or (path != "README.md"
             # and path.endswith("README.md"))` — the first clause already
@@ -209,9 +154,9 @@ class RootMarkdownAllowlist(Check):
                 yield self.report(
                     path,
                     "tracked Markdown is outside the root allowlist",
-                    f"move {path} under an allowed tree (docs/, plans/, .specs/, "
-                    ".changeset/, etc.), or, if it is a root-level Markdown file "
-                    "this repository genuinely carries, declare it under "
+                    f"move {path} under an allowed tree (docs/, plans/, etc.), or, "
+                    "if it is a Markdown file this repository genuinely carries, "
+                    "declare it under "
                     "[controls.compliance.root] files in this repository's "
                     "adl-config.toml",
                 )
@@ -219,9 +164,6 @@ class RootMarkdownAllowlist(Check):
     def _allowed_markdown(self, ctx: Context, path: str) -> bool:
         if path == "README.md":
             return True
-        # ADR-095 admits this one root-relative verification contract by
-        # literal name.
-        #
         # `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,
@@ -239,9 +181,7 @@ class RootMarkdownAllowlist(Check):
         # (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
-        ):
+        if path in declared_root_files(ctx.declarations):
             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
@@ -259,19 +199,6 @@ class RootMarkdownAllowlist(Check):
         plans_root = ctx.relative(ctx.inputs["plans_root"])
         if path.startswith(f"{plans_root}/") and path.endswith(".md"):
             return True
-        # Widening: a repository with no specs tree simply allows nothing on its
-        # account. Shrinking an allowlist can only add findings, never hide one.
-        specs_input = ctx.inputs.get("specs_root")
-        if specs_input is not None:
-            specs_root = ctx.relative(specs_input)
-            if path == f"{specs_root}/AGENTS.md" or (
-                path.startswith(f"{specs_root}/") and path.endswith(".md")
-            ):
-                return True
-        if path.startswith(".changeset/") and path.endswith(".md"):
-            return True
-        if path == ".donors/MANIFEST.md":
-            return True
         docs_root = ctx.relative(ctx.inputs["docs_root"])
         if path.startswith(f"{docs_root}/") and path.endswith(".md"):
             return True
@@ -279,53 +206,6 @@ class RootMarkdownAllowlist(Check):
         # shell (I-41) — its Markdown is a separate concern from docs/.
         if path.startswith(".docs/") and path.endswith(".md"):
             return True
-        # Ported enact-integration-specific exceptions (see class attributes
-        # above).
-        if path in self.GOVERNANCE_FILES or path in self.RETAINED_MARKDOWN_FILES:
-            return True
-        # 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 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
-        if path in {f"{workflows_root}/{suffix}" for suffix in self.WORKFLOWS_RETAINED_SUFFIXES}:
-            return True
         if any(path.startswith(code_root) for code_root in self.CODE_ASSET_ROOTS):
             return True
-        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 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 (
-            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

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

@@ -7,7 +7,7 @@ Markdown file — the two violators live inside the same conforming tree, so a
 corpus flips between clean and broken by changing only which paths are in the
 given set, exactly as test.sh's own comment describes. `root-markdown-missing-
 guide/` holds only the four files the structural rule reads, with
-`.specs/AGENTS.md` absent.
+`docs/AGENTS.md` absent.
 
 This check is not yet wired into `checks/__init__.py` (a later step wires this
 port's whole wave into the registry in one shot, to avoid concurrent edits to
@@ -29,7 +29,7 @@ Registry-row note, not fixed here (this task does not touch
 `'**/README.md'`, with no `'**/*.md'` companion of the kind LAY-006 carries for
 the identical reason (see that row's own comment). Read through `runner.run`,
 every nested non-README path in the clean corpus (`.plans/AGENTS.md`,
-`docs/AGENTS.md`, `.changeset/some-change.md`, ...) would be narrowed away
+`docs/AGENTS.md`, `docs/architecture/note.md`, ...) would be narrowed away
 before this check ever ran — which is exactly why every test below calls the
 check directly with the full given set, rather than through the row's scope.
 """
@@ -38,9 +38,12 @@ from __future__ import annotations
 
 import pathlib
 
+import pytest
+
 from adl_compliance.checks.layout.root_markdown_allowlist import RootMarkdownAllowlist
 from adl_compliance.core import scope
 from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.errors import CouldNotRun
 from adl_compliance.core.verdict import Outcome, decide
 from adl_compliance.policy.registry import load
 
@@ -59,14 +62,11 @@ CLEAN_GIVEN = (
     "CLAUDE.md",
     "CHANGELOG.md",
     "RELEASE.md",
-    "INDEPENDENT-VERIFICATION.md",
     "README.md",
     ".workflows/AGENTS.md",
     ".plans/AGENTS.md",
-    ".specs/AGENTS.md",
     "docs/AGENTS.md",
     "docs/architecture/note.md",
-    ".changeset/some-change.md",
 )
 # Every file the clean corpus actually holds on disk, violators included —
 # the shape a tree-scoped phase (or test.sh's `corpus_set` with no explicit
@@ -91,10 +91,7 @@ def graded(root: pathlib.Path, given: tuple[str, ...]):
         inputs={
             "workflows_root": root / ".workflows",
             "plans_root": root / "plans",
-            "specs_root": root / ".specs",
             "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
         },
     )
     findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
@@ -110,10 +107,7 @@ def structural(root: pathlib.Path):
         inputs={
             "workflows_root": root / ".workflows",
             "plans_root": root / "plans",
-            "specs_root": root / ".specs",
             "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
         },
     )
     findings = tuple(RootMarkdownAllowlist().structural(ctx))
@@ -130,10 +124,7 @@ def full(root: pathlib.Path, given: tuple[str, ...]):
         inputs={
             "workflows_root": root / ".workflows",
             "plans_root": root / "plans",
-            "specs_root": root / ".specs",
             "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
         },
     )
     findings = tuple(RootMarkdownAllowlist().run(ctx, FileSet(paths=given)))
@@ -239,7 +230,6 @@ def test_a_tree_that_does_not_exist_is_not_asked_for_a_guide() -> None:
     did."""
     reported = {f.path for f in structural(MISSING_GUIDE).findings}
     assert "specs/AGENTS.md" not in reported
-    assert ".specs/AGENTS.md" not in reported
 
 
 def test_a_workflows_tree_without_a_guide_is_not_a_finding(tmp_path: pathlib.Path) -> None:
@@ -292,9 +282,9 @@ def test_a_plugin_root_readme_is_a_published_description(tmp_path: pathlib.Path)
     given = (
         "AGENTS.md",
         "README.md",
-        ".claude-plugin/enact-repo/README.md",
-        ".codex-plugin/enact-repo/README.md",
-        ".cursor-plugin/enact-repo/README.md",
+        ".claude-plugin/my-repo/README.md",
+        ".codex-plugin/my-repo/README.md",
+        ".cursor-plugin/my-repo/README.md",
     )
     verdict = graded(tmp_path, given)
     assert not [
@@ -309,7 +299,7 @@ def test_a_redeclared_estate_still_allows_the_resolved_tree_exceptions(
     """The LOUD false-finding this check shipped with.
 
     Every `backend/...`/`frontend/...`/`.workflows/...`/`plans/...`/
-    `.specs/...`/`docs/...` entry in `_allowed_markdown` was a hardcoded
+    `docs/...` entry in `_allowed_markdown` was a hardcoded
     literal. A repository whose roots are not the packaged defaults had a
     real, legitimately-allowed Markdown file (a crate's CHANGELOG, a
     workflows coverage note, a docs page) fail every one of those tests and
@@ -327,19 +317,13 @@ def test_a_redeclared_estate_still_allows_the_resolved_tree_exceptions(
         "documentation/AGENTS.md",
         "documentation/architecture/note.md",
         "automation/AGENTS.md",
-        "automation/COVERAGE.md",
-        "rustcode/CHANGELOG.md",
-        "webapp/CHANGELOG.md",
     )
     ctx = Context(
         root=tmp_path, row=ROW,
         inputs={
             "workflows_root": tmp_path / "automation",
             "plans_root": tmp_path / "roadmap",
-            "specs_root": tmp_path / "specifications",
             "docs_root": tmp_path / "documentation",
-            "rust_root": tmp_path / "rustcode",
-            "frontend_root": tmp_path / "webapp",
         },
     )
     findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
@@ -350,6 +334,19 @@ def test_a_redeclared_estate_still_allows_the_resolved_tree_exceptions(
     )
 
 
+def test_no_legacy_estate_file_is_admitted_by_name(tmp_path: pathlib.Path) -> None:
+    given = (
+        "compliance/fixtures.md",
+        ".workflows/config/exceptions/KNOWN-ISSUES.md",
+        ".workflows/COVERAGE.md",
+    )
+    for rel in given:
+        (tmp_path / rel).parent.mkdir(parents=True, exist_ok=True)
+        (tmp_path / rel).write_text("x\n", encoding="utf-8")
+    verdict = graded(tmp_path, given)
+    assert sorted(f.path for f in verdict.findings) == sorted(given), verdict.render()
+
+
 # ---------------------------------------------- per-repository root declarations
 def graded_declaring(root: pathlib.Path, declarations: dict[str, str], given: tuple[str, ...]):
     """`graded`, plus what the repository declared about its own root
@@ -361,10 +358,7 @@ def graded_declaring(root: pathlib.Path, declarations: dict[str, str], given: tu
         inputs={
             "workflows_root": root / ".workflows",
             "plans_root": root / "plans",
-            "specs_root": root / ".specs",
             "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
         },
     )
     findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
@@ -448,18 +442,12 @@ def test_the_central_names_are_allowed_without_reading_the_context() -> None:
     assert RootMarkdownAllowlist()._allowed_markdown(None, "GAPS-AND-FINDINGS.md")  # type: ignore[arg-type]
 
 
-# ------------------------------------------------- a tree declared absent
-def test_rust_and_frontend_declared_absent_contribute_nothing_to_the_allowlist(
+# ------------------------------------------- deleted rust and frontend trees
+def test_the_former_rust_and_frontend_entries_admit_nothing(
     tmp_path: pathlib.Path,
 ) -> None:
-    """`rust = ""` and `frontend = ""` drop `rust_root` and `frontend_root` from
-    the resolved inputs. Here they only ever ADD allowlist entries (the governance
-    suffixes and code-asset roots beneath them), so absent they contribute
-    nothing and the file is reported -- strictly stricter, never a silent pass.
-    A stray root-level Markdown file reached `ctx.inputs["rust_root"]` unguarded
-    and raised `KeyError`, a traceback with exit 1, measured against enact-combined
-    with `--tree rust= --tree frontend=`."""
-    _touch(tmp_path, "NOTES.md", "backend/crates/enact-app/assets/builtin-skills/s.md")
+    """PBI 598: the rust and frontend suffix admissions are deleted with their trees."""
+    _touch(tmp_path, "NOTES.md", "backend/crates/app/assets/builtin-skills/s.md")
     ctx = Context(
         root=tmp_path, row=ROW,
         inputs={
@@ -468,23 +456,83 @@ def test_rust_and_frontend_declared_absent_contribute_nothing_to_the_allowlist(
             "docs_root": tmp_path / "docs",
         },
     )
-    given = ("NOTES.md", "backend/crates/enact-app/assets/builtin-skills/s.md")
+    given = ("NOTES.md", "backend/crates/app/assets/builtin-skills/s.md")
     findings = tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=given)))
     assert sorted(f.path for f in findings) == sorted(given), findings
     assert all(f.message == "tracked Markdown is outside the root allowlist" for f in findings)
 
 
-def test_a_declared_rust_tree_still_admits_its_governance_files(tmp_path: pathlib.Path) -> None:
-    """The other half: with the tree declared, the same entries still admit."""
-    _touch(tmp_path, "rust/CHANGELOG.md")
+# ---------------------------------------- PBI 601: INDEPENDENT-VERIFICATION.md
+def test_independent_verification_is_a_declaration_not_a_central_name(
+    tmp_path: pathlib.Path,
+) -> None:
+    """PBI 601: INDEPENDENT-VERIFICATION.md left the central list; reported undeclared, silent once declared."""
+    _touch(tmp_path, "INDEPENDENT-VERIFICATION.md")
+    undeclared = graded_declaring(tmp_path, {}, ("INDEPENDENT-VERIFICATION.md",))
+    assert [f.path for f in undeclared.findings] == ["INDEPENDENT-VERIFICATION.md"]
+    declared = graded_declaring(
+        tmp_path, {"root-files": "INDEPENDENT-VERIFICATION.md"}, ("INDEPENDENT-VERIFICATION.md",)
+    )
+    assert declared.findings == ()
+
+
+def test_an_arbitrary_tree_markdown_file_is_outside_the_allowlist(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, "changes/some-change.md")
+    verdict = graded_declaring(tmp_path, {}, ("changes/some-change.md",))
+    assert [f.path for f in verdict.findings] == ["changes/some-change.md"], verdict.render()
+
+
+def test_the_remedy_names_only_trees_the_gate_admits(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, "STRAY.md")
+    [finding] = graded_declaring(tmp_path, {}, ("STRAY.md",)).findings
+    assert "docs/, plans/" in finding.fix
+    assert "etc.)" in finding.fix
+
+
+def _guides(tmp_path: pathlib.Path, plans: str, docs: str):
     ctx = Context(
         root=tmp_path, row=ROW,
-        inputs={
-            "workflows_root": tmp_path / "workflows",
-            "plans_root": tmp_path / "plans",
-            "docs_root": tmp_path / "docs",
-            "rust_root": tmp_path / "rust",
-            "frontend_root": tmp_path / "web",
-        },
+        inputs={"workflows_root": tmp_path / ".workflows", "plans_root": tmp_path / plans, "docs_root": tmp_path / docs},
     )
-    assert tuple(RootMarkdownAllowlist().graded(ctx, FileSet(paths=("rust/CHANGELOG.md",)))) == ()
+    return [f.path for f in RootMarkdownAllowlist().structural(ctx)]
+
+
+def test_the_guided_trees_are_the_declared_ones(tmp_path: pathlib.Path) -> None:
+    (tmp_path / "roadmap").mkdir()
+    (tmp_path / "documentation").mkdir()
+    (tmp_path / "plans").mkdir()
+    assert _guides(tmp_path, "roadmap", "documentation") == ["roadmap/AGENTS.md", "documentation/AGENTS.md"]
+
+
+def test_an_undeclared_default_tree_is_not_asked_for_a_guide(tmp_path: pathlib.Path) -> None:
+    (tmp_path / "plans").mkdir()
+    (tmp_path / "docs").mkdir()
+    assert _guides(tmp_path, "roadmap", "documentation") == []
+
+
+DONORS = ".donors/MANIFEST.md"
+
+
+def test_a_declared_nested_root_file_is_allowed(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, DONORS)
+    verdict = graded_declaring(tmp_path, {"root-files": DONORS}, (DONORS,))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_undeclared_nested_root_file_is_a_finding(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, DONORS)
+    verdict = graded_declaring(tmp_path, {}, (DONORS,))
+    assert [f.path for f in verdict.findings] == [DONORS], verdict.render()
+
+
+def test_a_declaration_admits_only_the_exact_nested_path(tmp_path: pathlib.Path) -> None:
+    _touch(tmp_path, "other/MANIFEST.md")
+    verdict = graded_declaring(tmp_path, {"root-files": DONORS}, ("other/MANIFEST.md",))
+    assert [f.path for f in verdict.findings] == ["other/MANIFEST.md"], verdict.render()
+
+
+@pytest.mark.parametrize("bad", ["../x.md", "/x.md", "a/../x.md", "a//x.md", "docs/*.md", "a/./x.md"])
+def test_a_malformed_root_file_declaration_is_could_not_run(tmp_path: pathlib.Path, bad: str) -> None:
+    _touch(tmp_path, "STATUS.md")
+    with pytest.raises(CouldNotRun, match="root-files"):
+        graded_declaring(tmp_path, {"root-files": bad}, ("STATUS.md",))

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

@@ -66,7 +66,7 @@ class ScriptsSizeDepth(Check):
 
     # `<workflows>` indirection, not the literal `.workflows/scripts` this held
     # until 2026-09-15. That literal is a consumer path inside the package
-    # (K-42), and it was not a near-miss: enact-m5 keeps CI in `workflows/`
+    # (K-42), and it was not a near-miss: a managed repository keeps CI in `workflows/`
     # while `.workflows/` is repo-controls' own install artefact, so the gate
     # reported `missing .workflows/scripts` and then called all 44 real scripts
     # "outside scripts root" — 45 findings, none of them true. The remedy it

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

@@ -131,7 +131,7 @@ def test_the_rows_scope_selects_nothing_from_an_empty_given_set() -> None:
 def test_the_scripts_root_follows_the_declared_tree(tmp_path: Path) -> None:
     """The regression guard for a literal `.workflows/scripts` in the package.
 
-    enact-m5 keeps CI in `workflows/` while `.workflows/` is repo-controls' own
+    a managed repository keeps CI in `workflows/` while `.workflows/` is repo-controls' own
     install artefact, so the hardcoded constant made this gate report
     `missing .workflows/scripts` and then call all 44 real scripts "outside
     scripts root" — 45 findings, not one of them true. Its printed remedy was

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/lfs/integrity/check.py

@@ -44,7 +44,7 @@ length: the WORKTREE file is not a safe source, because a correctly-tracked LFS
 file is a pointer in Git and is smudged back to full content on disk, so a check
 reading the worktree flags the very files that are doing the right thing.
 check.sh called that risk "latent, not hypothetical". It was measured on
-2026-10-01 against enact-combined: `live-probes/local/chat-local/output/
+2026-10-01 against the combined repository: `live-probes/local/chat-local/output/
 evidence/probe-result-video.webm` has `git check-attr filter` = lfs, a committed
 blob of 132 bytes (`git cat-file -s :path`) and a 1,170,147-byte worktree file,
 and the worktree-reading version of this check reported it as a violation. No

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/lfs/integrity/test_check.py

@@ -356,7 +356,7 @@ def test_a_pointer_header_over_the_threshold_under_a_non_matching_rule_is_report
 # graded where. A path with NO committed fact is graded by its worktree file, as
 # before -- the existing cases above all run that way, with no facts at all.
 
-SMUDGED = 1_170_147  # the measured size of a real smudged LFS file on enact-combined
+SMUDGED = 1_170_147  # the measured size of a real smudged LFS file on the combined repository
 POINTER_SIZE = 132  # `git cat-file -s` of the pointer committed for it
 
 
@@ -808,20 +808,24 @@ def test_a_compliance_tree_declared_absent_drops_the_register(tmp_path: Path) ->
     assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
 
 
-def test_a_compliance_tree_missing_from_the_map_is_could_not_run_naming_what_to_declare(
+def test_a_compliance_tree_missing_from_the_map_drops_the_register_and_grades_bare(
     tmp_path: Path,
 ) -> None:
-    # PINS A GAP, not a goal. `resolve_inputs` expands every declared input before
-    # it reaches the widening branch, so a tree ABSENT from the map (neither a path
-    # nor "") is could-not-run even for a widening input -- reproduced through the
-    # real CLI on enact-combined with no `--tree compliance=...`. The message names
-    # exactly what to declare, and both repositories in this estate declare it. The
-    # fix is in `runner.resolve_inputs`, not in this check; this test flips with it.
+    # PBI 599/601: an absent register means no grants, never could-not-run; the excused file is reported.
     root = ratcheted(tmp_path, {"photo.png": BIG}, {"photo.png": RECORDED})
     trees = {name: path for name, path in fixture_trees().items() if name != "compliance"}
     verdict = runner.run(ROW, root, corpus_files(root), trees=trees, declared_trees=trees)
-    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
-    assert "[controls.compliance.trees].compliance" in verdict.message
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
+
+
+def test_a_declared_compliance_tree_with_no_folder_grants_nothing(tmp_path: Path) -> None:
+    root = build(tmp_path, {"photo.png": BIG})
+    trees = {**fixture_trees(), "compliance": "compliance"}
+    assert not (root / "compliance").exists()
+    verdict = runner.run(ROW, root, corpus_files(root), trees=trees, declared_trees=trees)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert [(f.rule, f.path) for f in verdict.findings] == [("LFS-002", "photo.png")]
 
 
 # --------------------------------------------------------- the register's shape

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/banned_commands/__init__.py

@@ -1,12 +1,5 @@
-"""The `repository.no-banned-commands` gate.
+"""Shared scanner (`base.py`) and fixture corpus for REP-004 and REP-006.
 
-A folder even though this gate grades no document of its own: uniform depth
-means every `check.py` sits at exactly `checks/*/*/check.py`, so a relative
-import out of a check is right for all of them or wrong for all of them.
+Holds no `check.py`: each gate has its own folder, `legacy_search/` and
+`vcs_in_scripts/`, because the layout is one `check.py` per registry row.
 """
-
-from __future__ import annotations
-
-from .check import BannedCommands
-
-__all__ = ["BannedCommands"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/banned_commands/base.py

@@ -0,0 +1,42 @@
+"""The scanner behind REP-004 and REP-006; see `docs/operations/adl-compliance-invariants.md`."""
+
+from __future__ import annotations
+
+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
+from ....core.scripts import is_shell_script
+
+
+class BannedCommand(Check):
+    """The shared scanner. Not registered; a gate subclasses it."""
+
+    WORD: ClassVar[str]
+    """The forbidden command, assembled by the subclass and never spelled whole."""
+
+    MESSAGE: ClassVar[str]
+    FIX: ClassVar[str]
+
+    BOUNDARY: ClassVar[str] = r"(?:^|[;&|()`\s'\"])"
+    """A command START, backtick included."""
+
+    TRAILING: ClassVar[str] = r"(?:\s|$)"
+
+    COMMENT: ClassVar[re.Pattern[str]] = re.compile(r"^\s*#")
+    """A whole-line comment only; a trailing comment stays flagged."""
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        targets = sorted(p for p in files if is_shell_script(p, lambda p=p: self.text(ctx, p)))
+        pattern = re.compile(f"{self.BOUNDARY}{re.escape(self.WORD)}{self.TRAILING}")
+        for relative in FileSet(paths=tuple(targets)).existing(ctx.root):
+            for line, found in self.scan(ctx, relative, pattern):
+                # `found.string` is the line: `scan` matches line by line.
+                if self.COMMENT.match(found.string):
+                    continue
+                yield self.report(
+                    relative, f"{self.MESSAGE} ({found.string.strip()})", self.FIX, line=line,
+                )