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

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

@@ -0,0 +1,138 @@
+"""LAY-004 — ported from `compliance_new/checks/layout/directory-ratchet/test.sh`.
+
+Three committed corpora, same names and shapes as the shell fixtures:
+`directory-ratchet-clean` (one baselined single-file directory, nothing else),
+`directory-ratchet-unbaselined` (an unbaselined single-file directory, plus a
+control: eleven single-file subdirectories of a parent that itself holds zero
+direct files), and `directory-ratchet-excluded` (the row's own `!` exclusions
+under test, run twice against the same files through two Row variants that
+differ by exactly those two patterns).
+
+Each fixture carries its own `grants.yaml` at its own root, passed as the
+`register` input override — the same mechanism `DOC-006`'s test uses for its
+packaged profile register, not a path nested to match `policy/config.toml`'s
+tree mapping, which is exactly the coupling that broke this port once already
+(P-14).
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance import runner
+from adl_compliance.core.verdict import Outcome
+from adl_compliance.checks.layout.directory_ratchet.check import DirectoryRatchet
+from adl_compliance.policy.registry import load
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+ROW = load().by_id("LAY-004")
+
+
+def corpus_files(root: pathlib.Path) -> tuple[str, ...]:
+    return tuple(
+        sorted(
+            str(path.relative_to(root))
+            for path in root.rglob("*")
+            if path.is_file() and path.name != "grants.yaml"
+        )
+    )
+
+
+def run(case: str, *, scope: tuple[str, ...] | None = None) -> object:
+    directory = FIXTURES / case
+    row = ROW
+    if scope is not None:
+        row = row.model_copy(update={"engine": row.engine.model_copy(update={"scope": scope})})
+    return runner.run(
+        row, directory, corpus_files(directory),
+        inputs={row.id: {"register": directory / "grants.yaml"}},
+    )
+
+
+def test_a_fully_baselined_tree_passes() -> None:
+    verdict = run("directory-ratchet-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_unbaselined_single_file_directory_is_reported() -> None:
+    verdict = run("directory-ratchet-unbaselined")
+    assert verdict.outcome is Outcome.FINDINGS
+    paths = {f.path for f in verdict.findings if f.rule == "DIR-001"}
+    assert "frontend/packages/desktop/src/renderer/fresh" in paths
+    assert "frontend/packages/desktop/src/renderer/solo" not in paths
+
+
+def test_a_subdirectory_alone_never_trips_the_rule() -> None:
+    """`many` holds eleven subdirectories and zero direct files of its own, so it
+    needs no baseline entry; each subdirectory holds exactly one file and IS
+    reported. Both halves matter, or this corpus is silent by accident."""
+    verdict = run("directory-ratchet-unbaselined")
+    paths = {f.path for f in verdict.findings if f.rule == "DIR-001"}
+    assert "frontend/packages/desktop/src/renderer/many" not in paths
+    assert "frontend/packages/desktop/src/renderer/many/sub1" in paths
+
+
+def test_the_row_exclusions_silence_locales_and_vendored_cargo() -> None:
+    verdict = run("directory-ratchet-excluded")
+    assert verdict.outcome is Outcome.FINDINGS
+    paths = {f.path for f in verdict.findings}
+    assert not any("locales" in p for p in paths)
+    assert not any("vendored-crate" in p for p in paths)
+    assert "frontend/packages/desktop/src/renderer/fresh" in {
+        f.path for f in verdict.findings if f.rule == "DIR-001"
+    }
+
+
+def test_falsifiability_without_the_row_exclusions() -> None:
+    """The same corpus, read through a Row differing by exactly the two `!`
+    patterns. Without this, the rejections above would pass just as well
+    against a row whose exclusions never matched anything."""
+    unscoped = tuple(
+        pattern for pattern in ROW.engine.scope
+        if not (pattern.startswith("!") and ("locales" in pattern or "Cargo.toml" in pattern))
+    )
+    assert len(unscoped) == len(ROW.engine.scope) - 2
+
+    verdict = run("directory-ratchet-excluded", scope=unscoped)
+    assert verdict.outcome is Outcome.FINDINGS
+    paths = {f.path for f in verdict.findings if f.rule == "DIR-001"}
+    assert any("locales" in p for p in paths)
+    assert any("vendored-crate" in p for p in paths)
+
+
+def test_the_ratchet_register_is_not_a_grant_catalogue() -> None:
+    """`structural_grant = True` forces the allowance to 0 regardless of the
+    row's own `grants:` field. Passing the register's size as the allowance is
+    the trap: a failing gate would report green."""
+    verdict = run("directory-ratchet-unbaselined")
+    assert verdict.granted == 0
+    assert verdict.outcome is Outcome.FINDINGS
+
+
+def test_an_absent_register_is_could_not_run_not_a_clean_pass() -> None:
+    """The baseline is the REPOSITORY's, so a repository without one has nothing
+    graded — and nothing graded is could-not-run.
+
+    This gate shipped its register as package data: one donor repository's whole
+    directory shape, 88 of 104 lines naming `backend/crates/enact-*`,
+    `frontend/packages/desktop/*` and `infra/stacks/*`. No repository in this
+    estate has any of those trees, so every one of them hit
+    `registered tree directory is missing: backend/crates` on the first entry —
+    a gate reporting another repo's layout as this repo's defect.
+    """
+    directory = FIXTURES / "directory-ratchet-clean"
+    verdict = runner.run(
+        ROW, directory, corpus_files(directory),
+        inputs={ROW.id: {"register": directory / "does-not-exist.yaml"}},
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "no directory-ratchet register" in verdict.message
+    assert "never a clean pass" in verdict.message
+
+
+def test_the_register_is_not_packaged_data() -> None:
+    """The regression guard. Re-adding a `resources` entry here would ship one
+    repository's baseline to every other repository again."""
+    assert "register" in DirectoryRatchet.inputs
+    assert "register" not in DirectoryRatchet.resources
+    assert DirectoryRatchet.inputs["register"].startswith("<")

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

@@ -0,0 +1,12 @@
+"""The `layout.markdown-trees` gate.
+
+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.
+"""
+
+from __future__ import annotations
+
+from .check import MarkdownTrees
+
+__all__ = ["MarkdownTrees"]

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

@@ -0,0 +1,240 @@
+"""LAY-006 — Markdown documentation must live under a tree the repository declares.
+
+  LAY-006  a Markdown file outside the declared docs trees and not on the
+           exclusion list.
+
+The allowed roots are RESOLVED, not listed: `<docs>`, `<plans>`, `<compliance>`,
+`<rust>`, `<frontend>` and `<workflows>` come from
+`[controls.compliance.trees]`, so a repository that spells a tree differently is
+graded against its own spelling. The only literals left are `*/LEDGER.md` (a
+register beside the tree it records) and the exclusion list below.
+
+This docstring used to read "docs/, .plans/, .specs/, or .changeset/" and three
+of those four were wrong. `.specs` was deleted 2026-09-16 as a path that matched
+nothing in this estate and never could; `.plans` became the resolvable `<plans>`
+when 7b8c057 renamed the tree; `.changeset/*.md` went the same way as `.specs`,
+for the same reason -- zero files across all four repositories. A rule's own
+description is the first thing anyone reads, and this one described the
+pre-migration world.
+
+  LAY-006  a Markdown file outside the allowed docs trees and not on the
+           exclusion list.
+
+Ported from `compliance_new/checks/layout/markdown-trees/check.sh`, which was
+two ` ls-files --cached --others` passes `comm`-ed against each other; the
+pathspecs are now `case` patterns over the given set. The translation is exact
+in one respect worth restating here: bash's `*` in a `case` pattern crosses
+`/` (it is a string match, not filesystem globbing), so a pathspec such as
+`**/x/**` becomes ONE pattern, `*/x/*` — `x/...` at the root is already reached
+by `x/*` on its own line, exactly as the shell version's comment records.
+Python's `fnmatch` translates `*` to `.*` the same way, so it is the faithful
+port rather than `PurePath.match`, `pathlib`'s globbing, or the row's own
+`**`-aware `core.scope` matcher — none of which cross `/` on a single `*`.
+
+Vendor / build output / local-only working state is excluded first, then code
+assets and control artifacts (AGENTS.md, CLAUDE.md, and their siblings), then a
+handful of named one-off paths. What remains is graded against the allowed
+trees; anything in neither list is reported.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from collections.abc import Iterable
+from typing import ClassVar
+
+from ....policy.root_shape import GOVERNANCE, GUIDES, REGISTERS
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+
+
+class MarkdownTrees(Check):
+    id: ClassVar[str] = "LAY-006"
+    rule: ClassVar[str] = "LAY-006"
+
+    MARKDOWN_SUFFIXES: ClassVar[tuple[str, ...]] = (".md", ".mdx")
+
+    # Vendor / build output / local-only working state — never documentation.
+    # Code assets (assistant rules, skill definitions) are runtime content, not
+    # documentation; they live wherever the runtime loads them from. Control
+    # artifacts (per AGENTS.md) are part of the repo control surface, and this
+    # gate never requires them to sit in a doc tree.
+    EXCLUDED: ClassVar[tuple[str, ...]] = (
+        "node_modules/*", "*/node_modules/*",
+        "target/*", "*/target/*",
+        ".cache/*", "./*", ".donors/*", ".venv/*", ".docs/*",
+        "assets/*", "*/assets/*",
+        "skills/*", "*/skills/*",
+        # Agent DEFINITIONS, same reasoning and same shape as the skill
+        # definitions two lines up: `name`/`description`/`model`/`tools`
+        # frontmatter, loaded by the runtime, not read as prose. Caught live
+        # against enact-extensions: `extensions/plugin-dev/agents/{agent-
+        # creator,plugin-validator,skill-reviewer}.md` were reported as
+        # documentation outside the allowed docs trees. COVERAGE COST, stated
+        # not buried: 5 `agents/*.md` files across the four managed repos stop
+        # being graded by this check (enact-extensions 3, enact-m5 2 — the
+        # enact-m5 pair, `docs/architecture/agents/{mcp-servers,
+        # orchestration}.md`, are prose docs already reachable via `docs/*.md`
+        # in ALLOWED below, so this exclusion changes nothing about whether
+        # they are reported, only widens what would also excuse them if they
+        # ever moved outside `docs/`).
+        "agents/*", "*/agents/*",
+        # Root governance and guides come from policy/root_shape.py, the single list
+        # 63cd856 created when three gates were found carrying three drifting copies
+        # of "what may sit at a repository's root". This gate asked the same question
+        # and was not brought in, so it flagged CONTRIBUTING.md and MAINTAINERS.md --
+        # exactly the files d841de1 ruled belong at the root, where a newcomer looks.
+        *sorted(GOVERNANCE | GUIDES | REGISTERS),
+        "AGENTS.md", "CLAUDE.md", "CHANGELOG.md", "RELEASE.md",
+        "INVARIANTS.md", "README.md", "CLAUDE-INVARIANTS.md",
+        "INDEPENDENT-VERIFICATION.md",
+        "*/AGENTS.md", "*/CLAUDE.md", "*/SKILLS.md", "*/CHANGELOG.md",
+        "*/README.md",
+        # A tree's CLAUDE-INVARIANTS.md is the same class of control artifact
+        # as its AGENTS.md and CLAUDE.md above; the root one is allowed two
+        # patterns up and nowhere else.
+        "*/CLAUDE-INVARIANTS.md",
+    )
+
+    # FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): these five patterns
+    # were hardcoded `backend/...`/`frontend/...`/`.workflows/...` literals in
+    # EXCLUDED, matched with `fnmatch`. A repository whose rust/frontend/
+    # workflows root is not the packaged default had a real excluded asset --
+    # a test fixture, a code example, a coverage note -- fail the match and
+    # get reported "outside the allowed docs trees", a visible, wrong finding
+    # about a file this gate was never meant to grade. Every suffix stays
+    # literal below its resolved root: named subject matter, not a resolvable
+    # path.
+    EXCLUDED_TEMPLATES: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("frontend_root", ".claude/*"),
+        ("workflows_root", "changesets/*"),
+        # Two patterns, not three — see check.sh's comment: the nested form
+        # needs its own line because the literal `tests/` anchors it, and
+        # `tests/fixture*/*` already covers the zero-directory case.
+        ("rust_root", "crates/*/tests/fixture*/*"),
+        ("rust_root", "crates/*/tests/*/fixture*/*"),
+        ("rust_root", "crates/enact-session/src/backend/codex_init_prompt.md"),
+        ("frontend_root", "examples/*"),
+        ("workflows_root", "COVERAGE.md"),
+    )
+
+    # Allowlisted Markdown roots.
+    # `plans/`, not `.plans/`: 7b8c057 renamed the tree and `config.toml` now reads
+    # `plans = "plans"`. This list did not follow, so every file in the tree the
+    # registry points at was reported as being outside it -- 18 findings against
+    # enact-m5 alone. The dotted spelling stays alongside it because a repository
+    # that has not migrated yet is not thereby wrong.
+    # FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): `docs/*.md`/
+    # `docs/*.mdx`, `plans/*.md`, and `.specs/*.md` were also hardcoded
+    # literals -- the current packaged default for each tree, spelled out
+    # directly rather than resolved. `.plans/*.md` (legacy dotted spelling)
+    # and bare `specs/*.md` (no documented migration away from `.specs`)
+    # stay literal alternate-spelling allowances, exactly as before -- this
+    # fix only moves the entry that stood for "the packaged default",
+    # leaving the other spelling in each pair untouched.
+    ALLOWED: ClassVar[tuple[str, ...]] = (
+        # `specs/*.md` deleted 2026-09-16. It was copy-paste from the
+        # `plans/`/`.plans/` pair, which stood for a REAL rename. No repository
+        # in this estate has `specs/` or `.specs/`, and nothing records an
+        # undotted spelling as a rename target -- it matched nothing and never
+        # could. The resolvable `<specs>` spelling is handled with the other
+        # declared trees above.
+        # A LEDGER beside the tree it records. `root_shape.REGISTERS` already
+        # permits a register at the repository root "because that is where
+        # someone arriving at the repository looks" -- a per-tree ledger is the
+        # same object scoped to one tree, and this estate already keeps
+        # `plans/LEDGER.yaml` that way.
+        #
+        # Scope of the exception, stated exactly rather than optimistically:
+        # `fnmatch`'s `*` CROSSES `/` (this module's own docstring says so), so
+        # this admits a file named exactly `LEDGER.md` at any depth below the
+        # root -- not just one directory down. It is still bounded by NAME: a
+        # `NOTES.md` or a lowercase `ledger.md` beside it is still reported.
+        "*/LEDGER.md",
+    )
+
+    # The compliance tree is the repository's OWN -- it holds the ratchets and
+    # registers a gate grades this repo against, and where it sits is the
+    # repository's declaration, not this package's choice. A register written in
+    # markdown belongs beside the data it registers, so the declared tree is an
+    # allowed home for `.md` alongside the fixed list above.
+    #
+    # Resolved as an INPUT rather than hardcoded, so `compliance = "compliance"`
+    # (or any other spelling a repo declares) reaches this check the same way it
+    # reaches every other. Hardcoding "compliance/*.md" here would be the
+    # eleventh consumer path frozen into the shared package.
+    inputs: ClassVar[dict[str, str]] = {
+        "registers": "<compliance>",
+        "docs_root": "<docs>",
+        "plans_root": "<plans>",
+        "rust_root": "<rust>",
+        "frontend_root": "<frontend>",
+        "workflows_root": "<workflows>",
+    }
+
+    # `<specs>` only ever ADDS allowlist entries here. enact-m5 has no specs
+    # tree; requiring one would push the owner to declare a directory that does
+    # not exist, and a false declaration is undetectable. Absent -> stricter.
+    widening_inputs: ClassVar[frozenset[str]] = frozenset({"specs_root"})
+
+    def _allowed(self, ctx: Context) -> tuple[str, ...]:
+        allowed = self.ALLOWED
+        # Absent is the fixed list, never a crash. The runner always resolves a
+        # declared input, so this only matters to a caller building a Context by
+        # hand -- which the tests do, and which is a legitimate way to exercise
+        # the fixed list on its own.
+        registers = ctx.inputs.get("registers")
+        if registers is not None:
+            root = ctx.relative(registers)
+            allowed = (*allowed, f"{root}/*.md", f"{root}/*.mdx")
+        docs_root = ctx.inputs.get("docs_root")
+        if docs_root is not None:
+            root = ctx.relative(docs_root)
+            allowed = (*allowed, f"{root}/*.md", f"{root}/*.mdx")
+        plans_root = ctx.inputs.get("plans_root")
+        if plans_root is not None:
+            allowed = (*allowed, f"{ctx.relative(plans_root)}/*.md")
+        specs_root = ctx.inputs.get("specs_root")
+        if specs_root is not None:
+            allowed = (*allowed, f"{ctx.relative(specs_root)}/*.md")
+        return allowed
+
+    def _excluded(self, ctx: Context) -> tuple[str, ...]:
+        excluded = self.EXCLUDED
+        for input_name, suffix in self.EXCLUDED_TEMPLATES:
+            root = ctx.inputs.get(input_name)
+            if root is not None:
+                excluded = (*excluded, f"{ctx.relative(root)}/{suffix}")
+        return excluded
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        allowed = self._allowed(ctx)
+        # The remedy quotes the SAME set the rule graded against, so a reader
+        # cannot be sent somewhere the gate does not accept.
+        declared = tuple(sorted(allowed))
+        excluded = self._excluded(ctx)
+        for relative in sorted(files.with_suffix(*self.MARKDOWN_SUFFIXES)):
+            if self._matches_any(relative, excluded):
+                continue
+            if self._matches_any(relative, allowed):
+                continue
+            yield self.report(
+                relative,
+                "documentation file outside the allowed docs trees",
+                # The remedy names the trees THIS repository declared, resolved
+                # the same way the rule was graded. It used to read
+                # "docs/, plans/, .specs/, or .changeset/" -- two retired trees
+                # and a hardcoded literal -- so a reader following it moved the
+                # file somewhere no repository has, and the gate failed again.
+                # A fix line that cannot be followed is worse than none: it
+                # spends the reader's trust and returns nothing.
+                f"move {relative} under one of this repository's declared doc "
+                f"trees ({', '.join(declared) if declared else 'none declared'}), "
+                "or add it to the exclusion list in this gate if it is a "
+                "legitimate non-doc asset",
+            )
+
+    @staticmethod
+    def _matches_any(path: str, patterns: tuple[str, ...]) -> bool:
+        return any(fnmatch.fnmatchcase(path, pattern) for pattern in patterns)

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/markdown_trees/fixtures/markdown-trees-clean/.plans/a_new/plan.md

@@ -0,0 +1,7 @@
+---
+plan_state: proposed
+---
+
+# A plan
+
+Markdown in an allowed tree.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/markdown_trees/fixtures/markdown-trees-clean/backend/AGENTS.md

@@ -0,0 +1,4 @@
+# AGENTS.md
+
+A control artifact, not a published page. It lives outside the doc trees by
+design and the gate must not report it.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/markdown_trees/fixtures/markdown-trees-clean/docs/page.md

@@ -0,0 +1,7 @@
+---
+title: A published page
+---
+
+# A published page
+
+Markdown in an allowed tree.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/markdown_trees/fixtures/markdown-trees-stray/backend/notes.md

@@ -0,0 +1,4 @@
+# Notes
+
+A documentation page dropped into backend/, where nothing renders or indexes
+it. This is the drift LAY-005 exists to catch.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/markdown_trees/fixtures/markdown-trees-stray/docs/page.md

@@ -0,0 +1,8 @@
+---
+title: A published page
+---
+
+# A published page
+
+Markdown in an allowed tree, so the stray corpus reports one file rather than
+every file.

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

@@ -0,0 +1,220 @@
+"""LAY-006 — ported from `compliance_new/checks/layout/markdown-trees/test.sh`.
+
+Two corpora, committed byte-for-byte from the shell tree's fixtures:
+`markdown-trees-stray/` puts one Markdown page outside every allowed tree
+beside one that IS allowed, so the gate must report exactly the first;
+`markdown-trees-clean/` holds four files, each excluded or allowed for a
+DIFFERENT reason — an allowed tree, a second allowed tree, a control artifact
+(`backend/AGENTS.md`), and a crate test fixture — so that a gate reporting
+every `.md` it sees, or one exclusion family rotting silently, would fail it.
+
+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
+that shared file), so `runner.run` would report "no check implements LAY-006"
+before ever reaching this check's own logic — `lookup()` runs before scope
+narrowing. Every test below therefore calls `MarkdownTrees` directly, the same
+`decide()`-around-`graded()` shape `test_the_whole_set_is_graded_with_no_
+location_filtering` in `repository/banned_commands/test_check.py` already uses
+to bypass row-scope narrowing; nothing here is a new pattern.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance.checks.layout.markdown_trees import MarkdownTrees
+from adl_compliance.core import scope
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.verdict import Outcome, decide
+from adl_compliance.policy.registry import load
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+ROW = load().by_id("LAY-006")
+
+STRAY = FIXTURES / "markdown-trees-stray"
+CLEAN = FIXTURES / "markdown-trees-clean"
+
+STRAY_FILES = ("backend/notes.md", "docs/page.md")
+CLEAN_FILES = (
+    "backend/crates/enact-example/tests/fixtures/sample.md",
+    "backend/AGENTS.md",
+    "docs/page.md",
+)
+
+
+def graded(root: pathlib.Path, given: tuple[str, ...]):
+    # Every root below is a RESOLVED INPUT now, not a class constant -- the
+    # packaged defaults, which every fixture here already uses.
+    ctx = Context(
+        root=root, row=ROW,
+        inputs={
+            "docs_root": root / "docs",
+            "plans_root": root / "plans",
+            "specs_root": root / ".specs",
+            "rust_root": root / "backend",
+            "frontend_root": root / "frontend",
+            "workflows_root": root / ".workflows",
+        },
+    )
+    findings = tuple(MarkdownTrees().graded(ctx, FileSet(paths=given)))
+    return decide(ROW, findings, 0, ())
+
+
+# ---------------------------------------------------------------- violation
+def test_a_markdown_page_outside_the_allowed_trees_is_reported() -> None:
+    verdict = graded(STRAY, STRAY_FILES)
+    assert verdict.outcome is Outcome.FINDINGS
+    assert len(verdict.findings) == 1
+    finding = verdict.findings[0]
+    assert finding.rule == "LAY-006"
+    assert finding.path == "backend/notes.md"
+    assert finding.message == "documentation file outside the allowed docs trees"
+
+
+def test_the_allowed_page_in_the_same_corpus_is_not_reported() -> None:
+    """docs/page.md is in the same corpus and must not also be flagged —
+    exactly one finding, matching test.sh's `rg -c '^LAY-006 '` == 1 assertion."""
+    verdict = graded(STRAY, STRAY_FILES)
+    paths = {f.path for f in verdict.findings}
+    assert "docs/page.md" not in paths
+
+
+# -------------------------------------------------------------------- clean
+def test_a_clean_corpus_of_allowed_and_excluded_paths_reports_nothing() -> None:
+    verdict = graded(CLEAN, CLEAN_FILES)
+    assert verdict.outcome is Outcome.CLEAN
+    assert verdict.findings == ()
+
+
+def test_each_exclusion_family_is_independently_load_bearing() -> None:
+    """Without this, a corpus of nothing but allowed-tree files also passes
+    against a gate that reports every .md it is handed, and either exclusion
+    family (control artifact, crate test fixture) could rot unnoticed."""
+    assert graded(CLEAN, ("backend/AGENTS.md",)).findings == ()
+    assert graded(
+        CLEAN, ("backend/crates/enact-example/tests/fixtures/sample.md",)
+    ).findings == ()
+
+
+# ------------------------------------------- intersection, half one: the set
+def test_the_stray_page_outside_the_given_set_is_not_reported() -> None:
+    """backend/notes.md is still on disk and still stray; it is simply not in
+    the set the gate was handed — test.sh's "intersection, half one" case."""
+    verdict = graded(STRAY, ("docs/page.md",))
+    assert verdict.outcome is Outcome.CLEAN
+
+
+# --------------------------------------------------- no set: could not run
+def test_the_rows_scope_selects_nothing_from_an_empty_given_set() -> None:
+    """test.sh's ADL_CHANGED_FILES-unset case turns into could-not-run
+    through `runner.run`'s generic empty-and-`exhaustive` guard (core/verdict,
+    see AGENTS.md's Applicable scope) — a property of the runner shared by
+    every check, not of this one. Verified at the scope layer directly,
+    because `runner.run` would hit the not-yet-wired `lookup()` first (see
+    module docstring) and never reach that guard."""
+    assert scope.intersect(ROW.resolved_scope(), ()) == ()
+
+
+# ---------------------------------------------------------------- non-.md
+def test_a_non_markdown_file_is_never_graded() -> None:
+    """The gate filters to `.md`/`.mdx` before applying either pattern list —
+    check.sh's `case "$rel" in *.md | *.mdx) ;; *) continue ;; esac`."""
+    assert graded(STRAY, ("backend/notes.txt",)).findings == ()
+
+
+# ------------------------------------------- the declared compliance tree
+def test_a_register_in_the_declared_compliance_tree_is_allowed(tmp_path) -> None:
+    """A markdown register belongs beside the data it registers.
+
+    `ALLOWED` is a fixed tuple, so before this the only homes for a `.md` file
+    were `docs/`, `plans/`, `specs/` and `.changeset/` — and a repository
+    declaring `compliance = "compliance"` (the tree holding its own ratchets)
+    could not put a register there without tripping this gate. The tree is the
+    REPOSITORY's declaration; hardcoding `compliance/*.md` here would have been
+    one more consumer path frozen into the shared package.
+    """
+    ctx = Context(
+        root=tmp_path, row=ROW,
+        inputs={"registers": tmp_path / "compliance"},
+    )
+    findings = tuple(MarkdownTrees().run(ctx, FileSet(paths=("compliance/gaps.md",))))
+    assert findings == (), findings
+
+
+def test_without_a_declared_tree_the_fixed_list_still_governs(tmp_path) -> None:
+    """The fallback must not quietly permit everything."""
+    ctx = Context(root=tmp_path, row=ROW)
+    findings = tuple(MarkdownTrees().run(ctx, FileSet(paths=("compliance/gaps.md",))))
+    assert len(findings) == 1, findings
+    assert "outside the allowed docs trees" in findings[0].message
+
+
+def test_a_ledger_beside_the_tree_it_records_is_allowed(tmp_path) -> None:
+    """`live-probes/LEDGER.md` is an append-only record of probe runs, sitting
+    beside the probes. Moving it under `docs/` was measured and rejected: it is
+    a 59-line table with one heading, and `docs/operations/**` is graded by the
+    OKF operations profile (four heading groups, `sources`, `related`), so the
+    move traded 1 finding for about 5.
+    """
+    ctx = Context(root=tmp_path, row=ROW)
+    assert tuple(MarkdownTrees().run(ctx, FileSet(paths=("live-probes/LEDGER.md",)))) == ()
+
+
+def test_the_ledger_exception_is_bounded_by_name_not_by_depth(tmp_path) -> None:
+    """It must not become a hole any markdown can walk through.
+
+    Honest about what it actually does: `fnmatch`'s `*` crosses `/`, so
+    `*/LEDGER.md` admits that exact filename at ANY depth, not only one
+    directory down. The bound is the NAME, and that is what this pins — a
+    neighbouring `NOTES.md`, or a lowercase `ledger.md`, is still reported.
+    """
+    ctx = Context(root=tmp_path, row=ROW)
+    for stray in ("live-probes/NOTES.md", "live-probes/ledger.md"):
+        findings = tuple(MarkdownTrees().run(ctx, FileSet(paths=(stray,))))
+        assert len(findings) == 1, (stray, findings)
+
+    # nested LEDGER.md is permitted, by the same fnmatch semantics
+    assert tuple(MarkdownTrees().run(ctx, FileSet(paths=("live-probes/sub/LEDGER.md",)))) == ()
+
+
+def test_a_redeclared_estate_still_allows_and_excludes_the_resolved_entries(
+    tmp_path,
+) -> None:
+    """The LOUD false-finding this check shipped with.
+
+    `docs/*.md`/`docs/*.mdx`, `plans/*.md`, `.specs/*.md` in ALLOWED, and the
+    `backend/...`/`frontend/...`/`.workflows/...` entries in EXCLUDED, were
+    all hardcoded literals. A repository whose corresponding root is not the
+    packaged default had a real, legitimately-admitted or -excluded file fail
+    every one of those patterns and get reported "outside the allowed docs
+    trees" -- a visible, wrong finding.
+
+    Every resolved root redeclared away from its packaged default, one real
+    file exercising each fixed template: wrongly flagged before the fix,
+    silent after."""
+    given = (
+        "documentation/page.md",
+        "roadmap/plan.md",
+        "specifications/note.md",
+        "webapp/.claude/notes.md",
+        "automation/changesets/note.md",
+        "rustcode/crates/enact-example/tests/fixture-a/sample.md",
+        "webapp/examples/demo.md",
+        "automation/COVERAGE.md",
+    )
+    ctx = Context(
+        root=tmp_path, row=ROW,
+        inputs={
+            "docs_root": tmp_path / "documentation",
+            "plans_root": tmp_path / "roadmap",
+            "specs_root": tmp_path / "specifications",
+            "rust_root": tmp_path / "rustcode",
+            "frontend_root": tmp_path / "webapp",
+            "workflows_root": tmp_path / "automation",
+        },
+    )
+    findings = tuple(MarkdownTrees().graded(ctx, FileSet(paths=given)))
+    assert findings == (), (
+        f"real files under redeclared roots were wrongly reported outside "
+        f"the allowed docs trees: {findings}"
+    )

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

@@ -0,0 +1,5 @@
+"""LAY-016: cap open plans and gaps."""
+
+from .check import OpenWorkCap
+
+__all__ = ["OpenWorkCap"]