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

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

@@ -1,10 +1,11 @@
-"""LAY-008 — ported from `compliance_new/checks/layout/placement/test.sh`.
+"""LAY-008 — ported from `compliance_new/checks/layout/placement/test.sh`; rebuilt to its
+throwaway-and-image rule only (Tarun 2026-10-08: PBI 599/601).
 
-Two corpora, same names and file shapes as the shell fixtures:
-`placement-allowed` (the 11 enumerated product paths that must stay silent)
-and `placement-stray` (one path per rule that must fire: a screenshot outside
-every enumerated asset directory, a markdown file inside a crate `src/` tree,
-and a file under retired `apps/`).
+Two corpora, same names as the shell fixtures: `placement-allowed` (paths that
+must stay silent) and `placement-stray` (one path per rule that must fire: a
+screenshot and a file under retired `apps/`). PBI 598 (Tarun, 2026-10-08)
+deleted the enumerated product asset directories and the `src/` Markdown sprawl
+rule, so the allowed corpus no longer holds product-asset paths.
 
 The shell `test.sh` drives `check.sh` DIRECTLY with the whole corpus as
 `ADL_CHANGED_FILES` — it does not go through `gate-runner.sh`'s row-scope
@@ -61,17 +62,7 @@ def _whole_corpus(root: pathlib.Path) -> tuple[str, ...]:
 def graded_directly(root: pathlib.Path, paths: tuple[str, ...]) -> Verdict:
     """Bypasses row-scope narrowing entirely — the check's OWN filtering
     only. Mirrors the shell test's direct `check.sh` invocation."""
-    # Every root is a RESOLVED INPUT now, not a class constant -- the packaged
-    # defaults, which every fixture below already uses.
-    ctx = Context(
-        root=root, row=ROW,
-        inputs={
-            "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
-            "specs_root": root / ".specs",
-        },
-    )
+    ctx = Context(root=root, row=ROW)
     findings = tuple(Placement().graded(ctx, FileSet(paths=paths)))
     return decide(ROW, findings, 0, ())
 
@@ -89,82 +80,72 @@ def run_via_row_scope(
             f"engine.scope matches no file on disk ({' | '.join(ROW.engine.scope)}); "
             "a scope selecting nothing is could-not-run, never a clean pass",
         )
-    # Every root is a RESOLVED INPUT now, not a class constant -- the packaged
-    # defaults, which every fixture below already uses.
-    ctx = Context(
-        root=root, row=ROW,
-        inputs={
-            "docs_root": root / "docs",
-            "rust_root": root / "backend",
-            "frontend_root": root / "frontend",
-            "specs_root": root / ".specs",
-        },
-    )
+    ctx = Context(root=root, row=ROW)
     findings = tuple(Placement().run(ctx, narrowed))
     return decide(ROW, findings, 0, ())
 
 
-def test_the_enumerated_product_paths_are_all_silent() -> None:
-    """Every allowed path is actually graded, not narrowed out of the set —
-    all 11 enumerated paths, exactly as the shell test asserts, or a
-    corpus drift would go unnoticed."""
+def test_the_allowed_corpus_is_all_silent() -> None:
+    """Every allowed path is actually graded, not narrowed out of the set."""
     given = _whole_corpus(ALLOWED)
-    assert len(given) == 10, given
+    assert len(given) == 1, given
     verdict = graded_directly(ALLOWED, given)
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
     assert verdict.findings == ()
 
 
+def test_an_image_in_a_former_product_asset_directory_is_now_reported() -> None:
+    """PBI 598: no hardcoded asset directory; a formerly exempt path is a stray image."""
+    former = (
+        "frontend/public/pwa/icon-192.png",
+        "backend/crates/assets/logos/tools/coding/tool.png",
+        "docs/assets/research/mobile-reference/shot.png",
+    )
+    verdict = graded_directly(ALLOWED, former)
+    assert sorted(f.path for f in verdict.findings) == sorted(former), verdict.render()
+
+
 def test_out_of_place_paths_are_reported() -> None:
+    """PBI 599/601: apps/ is no longer retired, so only the screenshot is reported."""
     given = _whole_corpus(STRAY)
-    assert len(given) == 3, given
+    assert len(given) == 2, given
     verdict = graded_directly(STRAY, given)
     assert verdict.outcome is Outcome.FINDINGS
-    assert len(verdict.findings) == 3, verdict.findings
+    assert [f.path for f in verdict.findings] == ["frontend/unapproved/screenshot.png"]
     # LAY-008, not LAY-007: the check used to report under its neighbour's id,
     # and this assertion pinned the bug in place.
     assert all(f.rule == "LAY-008" for f in verdict.findings)
 
 
-def test_a_screenshot_outside_every_enumerated_asset_directory_is_reported() -> None:
+def test_an_undeclared_screenshot_is_reported() -> None:
     given = _whole_corpus(STRAY)
     verdict = graded_directly(STRAY, given)
     paths = {f.path for f in verdict.findings}
     assert "frontend/unapproved/screenshot.png" in paths
 
 
-def test_a_markdown_file_inside_a_crate_src_tree_is_reported() -> None:
-    given = _whole_corpus(STRAY)
-    verdict = graded_directly(STRAY, given)
-    paths = {f.path for f in verdict.findings}
-    assert "backend/crates/enact-session/src/backend/README.md" in paths
-
-
-def test_a_file_under_retired_apps_is_reported() -> None:
-    given = _whole_corpus(STRAY)
-    verdict = graded_directly(STRAY, given)
-    paths = {f.path for f in verdict.findings}
-    assert "apps/legacy/file.ts" in paths
-
-
 def test_a_throwaway_extension_is_reported_strictly_everywhere() -> None:
-    """Rule 3's throwaway-extension arm fires even inside an enumerated asset
-    directory — check.sh's own comment: checked "strictly everywhere",
-    ahead of the asset-directory exemption."""
+    """Rule 3 (throwaway extensions) fires everywhere, per check.sh."""
     verdict = graded_directly(
-        ALLOWED, ("frontend/resources/build.log",),
+        ALLOWED, ("assets/build.log",),
     )
     assert verdict.outcome is Outcome.FINDINGS
     assert len(verdict.findings) == 1
-    assert verdict.findings[0].path == "frontend/resources/build.log"
+    assert verdict.findings[0].path == "assets/build.log"
     assert "throwaway artifact" in verdict.findings[0].message
 
 
-def test_a_root_level_file_off_the_allowlist_is_reported() -> None:
-    verdict = graded_directly(ALLOWED, ("random.txt",))
-    assert verdict.outcome is Outcome.FINDINGS
-    assert verdict.findings[0].path == "random.txt"
-    assert "root allowlist" in verdict.findings[0].message
+def test_rule_1_the_root_allowlist_is_gone() -> None:
+    """PBI 599/601: the root allowlist moved to LAY-012, so a root file off every list is silent here."""
+    verdict = graded_directly(ALLOWED, ("random.txt", "STATUS.md"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert not hasattr(Placement, "ROOT_ALLOWLIST")
+
+
+def test_rule_2_apps_is_not_retired() -> None:
+    """PBI 599/601: a file under `apps/` is graded like any other path."""
+    verdict = graded_directly(ALLOWED, ("apps/legacy/file.ts", "apps/cli/src/main.ts"))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
 def test_a_root_level_allowlisted_file_is_silent() -> None:
@@ -180,159 +161,60 @@ def test_no_set_is_could_not_run() -> None:
     assert verdict.outcome is Outcome.COULD_NOT_RUN
 
 
-def test_a_redeclared_estate_still_exempts_a_real_asset(tmp_path: pathlib.Path) -> None:
-    """The LOUD false-finding ASSET_DIR_TEMPLATES shipped with.
-
-    Every entry was a hardcoded literal, tested with `startswith`/`==` in
-    `_asset_exempt`. A repository whose frontend root is not the packaged
-    default had a real, legitimately-placed themed asset fail that
-    exemption and get reported "looks like a screenshot" -- a visible,
-    wrong finding about a file the exemption exists to admit."""
-    ctx = Context(
-        root=tmp_path, row=ROW,
-        inputs={
-            "docs_root": tmp_path / "docs",
-            "rust_root": tmp_path / "backend",
-            "frontend_root": tmp_path / "webapp",
-            "specs_root": tmp_path / ".specs",
-        },
-    )
-    path = "webapp/packages/desktop/src/renderer/assets/themes/screenshot-dark.png"
-    findings = tuple(Placement().graded(ctx, FileSet(paths=(path,))))
-    assert findings == (), (
-        f"a real themed asset under a redeclared frontend root was wrongly "
-        f"reported as a stray screenshot: {findings}"
-    )
-
-
-def test_a_redeclared_rust_root_still_catches_md_sprawl(tmp_path: pathlib.Path) -> None:
-    """The SILENT false pass MD_SRC_TREES/MD_SRC_EXEMPT shipped with.
-
-    `MD_SRC_TREES`'s `backend/` entry was a hardcoded literal, tested with
-    `startswith` in `_md_sprawl`. A repository whose rust root is not the
-    packaged default had real narrative-doc sprawl inside its `src/` tree
-    fail that `startswith` test, and the gate never examined it at all: no
-    error, no finding, indistinguishable from a repository with no sprawl."""
-    ctx = Context(
-        root=tmp_path, row=ROW,
-        inputs={
-            "docs_root": tmp_path / "docs",
-            "rust_root": tmp_path / "rustcode",
-            "frontend_root": tmp_path / "frontend",
-            "specs_root": tmp_path / ".specs",
-        },
-    )
-    path = "rustcode/crates/enact-example/src/notes.md"
-    findings = tuple(Placement().graded(ctx, FileSet(paths=(path,))))
-    assert any("md-sprawl" in f.message for f in findings), (
-        f"real markdown sprawl under a redeclared rust root went "
-        f"unreported: {findings}"
-    )
-
-
-# ---------------------------------------------- per-repository root declarations
+# ----------------------------------------------- the repository's declared asset dirs
 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",
-        },
-    )
+    """`graded_directly` plus the repository declarations (`asset_dirs` arrives as `asset-dirs`)."""
+    ctx = Context(root=root, row=ROW, declarations=declarations)
     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"))
+def test_a_declared_asset_dir_admits_an_image_at_any_depth() -> None:
+    verdict = graded_declaring(
+        {"asset-dirs": "web/public,docs/assets"},
+        ("web/public/logo.png", "web/public/deep/er/icon.JPG", "docs/assets/shot/screenshot-1.png"),
+    )
     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_an_undeclared_image_is_reported_beside_a_declaration() -> None:
+    """A gate that stops grading images once any declaration is present must fail this."""
+    verdict = graded_declaring(
+        {"asset-dirs": "web/public"}, ("web/public/logo.png", "web/other/logo.png", "logo.png")
+    )
+    assert sorted(f.path for f in verdict.findings) == ["logo.png", "web/other/logo.png"]
 
 
-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_an_asset_dir_is_a_directory_not_a_name_prefix() -> None:
+    verdict = graded_declaring({"asset-dirs": "web/public"}, ("web/public-extra/logo.png",))
+    assert [f.path for f in verdict.findings] == ["web/public-extra/logo.png"]
 
 
-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_a_declared_asset_dir_does_not_admit_a_throwaway_file() -> None:
+    verdict = graded_declaring({"asset-dirs": "web/public"}, ("web/public/build.log",))
+    assert [f.path for f in verdict.findings] == ["web/public/build.log"]
+    assert "throwaway" in verdict.findings[0].message
 
 
-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_trailing_slash_in_a_declared_asset_dir_is_tolerated() -> None:
+    verdict = graded_declaring({"asset-dirs": "web/public/"}, ("web/public/logo.png",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
 
-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_a_malformed_asset_dir_is_could_not_run() -> None:
+    import pytest
 
+    from adl_compliance.core.errors import CouldNotRun
 
-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()
+    for bad in ("/abs", "a/../b", "./x"):
+        with pytest.raises(CouldNotRun, match="asset-dirs"):
+            graded_declaring({"asset-dirs": bad}, ("a/logo.png",))
 
 
-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
+def test_the_row_scope_is_every_file_and_excludes_fixtures() -> None:
+    assert scope.in_scope(ROW.engine.scope, "logo.png")
+    assert scope.in_scope(ROW.engine.scope, "deep/er/notes.log")
+    assert not scope.in_scope(ROW.engine.scope, "checks/x/fixtures/logo.png")
+    assert ROW.title == "Reject throwaway files and undeclared image placement"

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

@@ -84,12 +84,13 @@ class PlansLayout(Check):
     # Three gates held an opinion on this file and they did not agree: LAY-006
     # allowed `*/LEDGER.md`, DOC-009 required `LEDGER.yaml` and reported the
     # Markdown form as "legacy", and this list allowed only the YAML. A
-    # repository could not satisfy all three at once -- enact-m5's conversion
+    # repository could not satisfy all three at once -- a managed repository's conversion
     # failed here the moment it succeeded elsewhere.
     ROOT_ALLOWED_FILES: ClassVar[tuple[str, ...]] = (
         "AGENTS.md", "CLAUDE.md", "LEDGER.md", "GAPS-AND-FINDINGS.md",
     )
     IGNORED: ClassVar[str] = ".DS_Store"
+    KEEP: ClassVar[str] = ".gitkeep"
 
     # az<work item id>-<kebab-slug>
     FEATURE_DIR: ClassVar[re.Pattern[str]] = re.compile(r"^az([0-9]+)-[a-z0-9]+(-[a-z0-9]+)*$")
@@ -245,11 +246,26 @@ class PlansLayout(Check):
 
     def _feature_dirs(self, ctx: Context, given: set[str]) -> Iterator[Finding]:
         features = f"{self._plans(ctx)}/{self.FEATURES}"
-        for entry in sorted(self._under(features, given)):
+        entries = sorted(self._under(features, given))
+        # `.gitkeep` is allowed in features/ only until the first Feature folder exists.
+        has_feature = any(
+            self.FEATURE_DIR.match(entry.rsplit("/", 1)[-1]) and ctx.path(entry).is_dir()
+            for entry in entries
+        )
+        for entry in entries:
             name = entry.rsplit("/", 1)[-1]
             if name == self.IGNORED:
                 continue
 
+            if name == self.KEEP and not ctx.path(entry).is_dir():
+                if has_feature:
+                    yield self.report(
+                        entry,
+                        "features/ no longer needs .gitkeep: a Feature folder exists",
+                        f"delete {entry} now that the first Feature exists",
+                    )
+                continue
+
             if not ctx.path(entry).is_dir():
                 yield self.report(
                     entry,

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

@@ -165,6 +165,55 @@ def test_a_loose_file_in_features_is_reported(tmp_path: pathlib.Path) -> None:
     assert any("one directory per Feature" in f.message for f in verdict.findings)
 
 
+# LAY-009: an empty features/ may hold `.gitkeep`; the first Feature folder retires it.
+
+def _plans_files(*extra: str) -> dict[str, str]:
+    return {"plans/AGENTS.md": "x", **{path: "" for path in extra}}
+
+
+def test_a_gitkeep_alone_in_an_empty_features_directory_is_silent(
+    tmp_path: pathlib.Path,
+) -> None:
+    verdict = graded_directly(build(tmp_path, _plans_files("plans/features/.gitkeep")))
+    assert not any(".gitkeep" in f.path for f in verdict.findings), verdict.render()
+    assert not any("one directory per Feature" in f.message for f in verdict.findings)
+
+
+def test_a_gitkeep_beside_a_feature_is_reported_and_names_the_deletion(
+    tmp_path: pathlib.Path,
+) -> None:
+    files = {
+        "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+        "plans/features/.gitkeep": "",
+    }
+    verdict = graded_directly(build(tmp_path, {"plans/AGENTS.md": "x", **files}))
+    kept = [f for f in verdict.findings if f.path == "plans/features/.gitkeep"]
+    assert len(kept) == 1, verdict.render()
+    assert "delete plans/features/.gitkeep" in kept[0].fix
+    assert "first Feature" in kept[0].fix
+
+
+def test_any_other_loose_file_is_still_reported_beside_a_gitkeep(
+    tmp_path: pathlib.Path,
+) -> None:
+    verdict = graded_directly(
+        build(tmp_path, _plans_files("plans/features/.gitkeep", "plans/features/stray.md"))
+    )
+    paths = {f.path for f in verdict.findings}
+    assert "plans/features/stray.md" in paths
+    assert "plans/features/.gitkeep" not in paths
+
+
+def test_a_gitkeep_is_only_the_features_directorys_exemption(tmp_path: pathlib.Path) -> None:
+    """Strictness: the allowance is for `features/` alone, not a Feature folder."""
+    files = {
+        "plans/features/az1-x/spec.md": FEATURE.format(work_item=1),
+        "plans/features/az1-x/.gitkeep": "",
+    }
+    verdict = graded_directly(build(tmp_path, {"plans/AGENTS.md": "x", **files}))
+    assert any(f.path == "plans/features/az1-x/.gitkeep" for f in verdict.findings)
+
+
 def test_a_feature_directory_not_named_az_id_is_reported(tmp_path: pathlib.Path) -> None:
     verdict = graded_directly(
         build(tmp_path, {"plans/features/coverage/spec.md": FEATURE.format(work_item=1)})

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

@@ -1,4 +1,4 @@
-"""LAY-011 — every local link in a Markdown page under docs/.plans/.specs
+"""LAY-011 — every local link in a Markdown page under docs/plans
 resolves, exactly (case included), and no page still points at a retired
 docs/strategy/ path.
 

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/references/fixtures/link-targets-broken/docs/architecture/guides/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/guides/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/guides/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/docs/architecture/guides/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/guides/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/guides/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

@@ -72,7 +72,7 @@ def test_broken_links_are_reported_exactly() -> None:
 
     rendered = verdict.render()
     assert (
-        "docs/architecture/product/links.md:16: missing local reference "
+        "docs/architecture/guides/links.md:16: missing local reference "
         "./does-not-exist.md" in rendered
     ), rendered
 
@@ -81,7 +81,7 @@ def test_broken_links_are_reported_exactly() -> None:
     # 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 "
+        "docs/architecture/guides/links.md:18: missing local reference "
         "../../readme.md" in rendered
     ), rendered
 
@@ -104,7 +104,7 @@ def test_a_page_outside_the_given_set_is_not_graded() -> None:
     to grade."""
     verdict = graded(
         CORPORA / "link-targets-broken",
-        given=("docs/architecture/product/route-target.md",),
+        given=("docs/architecture/guides/route-target.md",),
     )
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
 
@@ -118,7 +118,7 @@ def test_a_completed_plan_resolves_as_a_target_though_excluded_as_a_source() ->
     missing one."""
     verdict = graded(
         CORPORA / "link-targets-clean",
-        given=("docs/architecture/product/links.md", "docs/architecture/product/route-target.md"),
+        given=("docs/architecture/guides/links.md", "docs/architecture/guides/route-target.md"),
     )
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
 

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

@@ -58,13 +58,13 @@ 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 (
     ALLOWED_ROOT_DIRS,
     ALLOWED_ROOT_FILES,
     REQUIRED_ROOT_FILES,
     allowed_root_dirs,
-    allowed_root_files,
 )
 
 
@@ -100,7 +100,7 @@ class RootClosedSet(Check):
 
     # 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
+    # (`.code-review-graph_old`, `.plans`) and they cost nothing while
     # they only permit; under the old manifest reading, each was a finding.
     #
     # The CENTRAL default. The effective set is
@@ -135,7 +135,7 @@ class RootClosedSet(Check):
                 root_files.add(path)
 
         allowed_dirs = allowed_root_dirs(ctx.declarations)
-        allowed_files = allowed_root_files(ctx.declarations)
+        allowed_files = ALLOWED_ROOT_FILES | declared_root_files(ctx.declarations)
         for name in sorted(dirs):
             if name not in allowed_dirs:
                 yield self.report(

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/root_closed_set/fixtures/.notes/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/test_check.py

@@ -41,8 +41,15 @@ def clean_set() -> tuple[str, ...]:
     )
 
 
+# PBI 599/601: the corpus declares its dirs (`root-dirs`) and files (`root-files`) as a real repository does.
+CORPUS_DIRS = {
+    "root-dirs": "backend,dev,docker,frontend,infra,.docs,.notes,.donors",
+    "root-files": "CLAUDE-INVARIANTS.md,INDEPENDENT-VERIFICATION.md",
+}
+
+
 def verdict_for(given: tuple[str, ...]) -> Verdict:
-    ctx = Context(root=CORPUS, row=ROW)
+    ctx = Context(root=CORPUS, row=ROW, declarations=CORPUS_DIRS)
     reported = tuple(RootClosedSet().run(ctx, FileSet(paths=given)))
     findings = tuple(r for r in reported if isinstance(r, Finding))
     advisories = tuple(r for r in reported if isinstance(r, Advisory))