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

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

@@ -0,0 +1,98 @@
+"""The check registry: row id -> the class implementing it.
+
+One module per gate, under its DOMAIN — the same `checks/<domain>/<name>` shape
+the registry row declares and the shell tree used, so a row and its
+implementation are found the same way.
+
+Explicit, not a package scan. A check that is written but not listed here is not
+wired, exactly as an ast-grep rule that is written but given no registry row is
+not a gate. Both are supported end states; neither is a half-finished one, and a
+scan would blur the difference.
+"""
+
+from __future__ import annotations
+
+from ..core.check import Check
+from .coverage.backend_crate import BackendCrate
+from .coverage.backend_ratchet import BackendRatchet
+from .coverage.baseline import CoverageBaseline
+from .coverage.config_committed import CoverageConfigCommitted
+from .coverage.full import CoverageFull
+from .docs.adr_lifecycle import AdrLifecycle
+from .docs.closed_set import DocsClosedSet
+from .docs.english_only import DocsEnglishOnly
+from .docs.index_updated import IndexUpdated
+from .docs.indexes import Indexes
+from .docs.ledger import DocsLedger
+from .docs.markdown_ast import MarkdownAst
+from .docs.okf_profile import OkfProfile
+from .docs.semantics import DocsSemantics
+from .layout.agents_layout import AgentsLayout
+from .layout.ci_paths import CiPaths
+from .layout.directory_ratchet import DirectoryRatchet
+from .layout.markdown_trees import MarkdownTrees
+from .layout.open_work_cap import OpenWorkCap
+from .layout.placement import Placement
+from .layout.plans_layout import PlansLayout
+from .layout.profile_data import ProfileData
+from .layout.references import References
+from .layout.root_closed_set import RootClosedSet
+from .layout.root_markdown_allowlist import RootMarkdownAllowlist
+from .layout.scripts_size_depth import ScriptsSizeDepth
+from .lfs.integrity import Integrity
+from .pipeline.phase_disjoint import PhaseDisjoint
+from .release.changeset_plan import ChangesetPlan
+from .release.version_release import VersionRelease
+from .repository.banned_commands import BannedCommands
+from .repository.ignored_paths import IgnoredPaths
+from .repository.license_declared import LicenseDeclared
+from .repository.lockfile_integrity import LockfileIntegrity
+
+CHECKS: tuple[type[Check], ...] = (
+    AdrLifecycle,
+    AgentsLayout,
+    BackendCrate,
+    BackendRatchet,
+    BannedCommands,
+    ChangesetPlan,
+    CiPaths,
+    CoverageBaseline,
+    CoverageConfigCommitted,
+    CoverageFull,
+    DirectoryRatchet,
+    DocsClosedSet,
+    DocsEnglishOnly,
+    DocsLedger,
+    DocsSemantics,
+    IgnoredPaths,
+    IndexUpdated,
+    Indexes,
+    Integrity,
+    LicenseDeclared,
+    LockfileIntegrity,
+    MarkdownAst,
+    MarkdownTrees,
+    OkfProfile,
+    OpenWorkCap,
+    PhaseDisjoint,
+    Placement,
+    PlansLayout,
+    ProfileData,
+    References,
+    RootClosedSet,
+    RootMarkdownAllowlist,
+    ScriptsSizeDepth,
+    VersionRelease,
+)
+
+_BY_ID: dict[str, type[Check]] = {check.id: check for check in CHECKS}
+
+if len(_BY_ID) != len(CHECKS):  # pragma: no cover — a wiring mistake, caught at import
+    raise RuntimeError("two checks claim the same row id")
+
+
+def lookup(gate_id: str) -> type[Check]:
+    return _BY_ID[gate_id]
+
+
+__all__ = ["CHECKS", "lookup"]

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

@@ -0,0 +1 @@
+"""docs."""

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/__init__.py

@@ -0,0 +1,12 @@
+"""The `docs.adr-lifecycle` gate.
+
+A folder rather than a module because this gate GRADES A DOCUMENT, and the
+document belongs beside the check that reads it. `check.py` is the rule;
+anything else in here is what it grades.
+"""
+
+from __future__ import annotations
+
+from .check import AdrLifecycle
+
+__all__ = ["AdrLifecycle"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/check.py

@@ -0,0 +1,210 @@
+"""DOC-001 — an ADR's inline `**Status:**` is its decision state, and each state
+owes a different set of backlinks.
+
+  structural  the decisions directory itself. An absent directory yields an
+              empty set, and an empty set is a clean pass everywhere else in
+              this estate — so without this probe the tree losing
+              docs/architecture/decisions/ entirely would pass in silence.
+  graded      the ADRs, which are the given set.
+
+BACKLINK TARGETS ARE RESOLVED, NOT GRADED. `.specs/`, `.plans/` and
+`docs/architecture/` references are read from disk even though the row's scope
+excludes them. That is not a second discovery pass: the set says which ADRs are
+graded, and whether an ADR's own link resolves is a property OF that ADR.
+Filtering targets by the set would make a backlink "broken" whenever the
+referenced plan simply was not in this commit.
+"""
+
+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
+
+
+class AdrLifecycle(Check):
+    id: ClassVar[str] = "DOC-001"
+    rule: ClassVar[str] = "DOC-001"
+
+    inputs: ClassVar[dict[str, str]] = {
+        "docs_root": "<docs>",
+        "plans_root": "<plans>",
+    }
+    """FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): `DECISIONS` (a named
+    path probe) and the `PLANS`/`ARCHITECTURE` regexes plus two message
+    strings (all backlink-target matching against ADR body text) were
+    hardcoded `docs/...`/`plans/...` literals. A repository whose docs or
+    plans root is not the packaged default had its real decisions directory
+    fail the probe ("decisions directory is missing" -- a visible, wrong
+    finding about a directory that is right there), and had every real
+    backlink an ADR actually wrote go unmatched -- OPEN/STABLE then wrongly
+    demanded a link the author already added. LOUD throughout: every failure
+    mode here is a visible false finding, never a quiet pass. `decisions`,
+    `features/az<id>-<slug>/...` and `architecture/...` stay literal below
+    their resolved roots: settled subject matter, not resolvable paths."""
+
+    ADR_FILENAME: ClassVar[re.Pattern[str]] = re.compile(r"/adr-[^/]*\.md$")
+    INLINE_STATUS: ClassVar[re.Pattern[str]] = re.compile(
+        r"\*\*?Status:?\*{0,2}[ \t]*([A-Za-z][A-Za-z ]*)"
+    )
+    FRONTMATTER_STATUS: ClassVar[re.Pattern[str]] = re.compile(r"^status:[ \t]*(.*)$")
+    TRAILING_PUNCTUATION: ClassVar[re.Pattern[str]] = re.compile(r"[—.\-]\s*$")
+
+    # `plans/`, not `.plans/`. 7b8c057 replaced the `.plans/a_new|b_committed|c_done`
+    # lifecycle tree with `plans/features/az<id>-<slug>/`, and this pattern never
+    # followed — so a DECIDED ADR was asked to backlink a directory that had been
+    # deleted by design. It passed here only because no ADR in any managed repository
+    # is DECIDED yet; the first one would have been told to recreate a retired tree.
+
+    VALID_STATES: ClassVar[tuple[str, ...]] = ("OPEN", "DECIDED", "STABLE")
+    # No ACTIVE_PLAN_DIRS or ACTIVE_PLAN_STATES any more. 7b8c057 removed both with the
+    # lifecycle tree: "State now lives only on the board and documents do not move, so
+    # plan_state, approval_state and the state-agrees-with-directory rule are gone with
+    # it." A directory name asserting a work item's state made the repository a second
+    # authority on a fact the board owns. Whether a linked plan is ACTIVE is therefore
+    # no longer a question this gate can answer from disk, and it does not try.
+
+    def _decisions(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['docs_root'])}/decisions"
+
+    def _plans_pattern(self, ctx: Context) -> re.Pattern[str]:
+        plans_root = re.escape(ctx.relative(ctx.inputs["plans_root"]))
+        return re.compile(rf"{plans_root}/features/az[0-9]+-[A-Za-z0-9_./-]+\.md")
+
+    def _architecture_pattern(self, ctx: Context) -> re.Pattern[str]:
+        docs_root = re.escape(ctx.relative(ctx.inputs["docs_root"]))
+        return re.compile(rf"{docs_root}/architecture/[^\s/][A-Za-z0-9_./-]+\.md")
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        decisions = self._decisions(ctx)
+        if not ctx.path(decisions).is_dir():
+            yield self.report(
+                decisions, "decisions directory is missing",
+                f"create {decisions}/ before running this gate",
+            )
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        if not ctx.path(self._decisions(ctx)).is_dir():
+            return
+        # Not every file in that directory is an ADR; the row's scope already
+        # narrowed the set to the directory itself.
+        for adr in sorted(p for p in files if self.ADR_FILENAME.search(p)):
+            yield from self._grade(ctx, adr)
+
+    def _grade(self, ctx: Context, adr: str) -> Iterable[Report]:
+        body = self.text(ctx, adr)
+        if body is None:
+            return
+
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        architecture_guide = f"{docs_root}/architecture/AGENTS.md"
+
+        status = self._inline_status(body)
+        if not status:
+            yield self.report(
+                adr, "no inline **Status:** line found -- state OPEN, DECIDED, or STABLE",
+                "add an inline **Status:** OPEN, DECIDED, or STABLE line to the ADR",
+            )
+            return
+        if status not in self.VALID_STATES:
+            yield self.report(
+                adr,
+                f"status '{status}' is not OPEN/DECIDED/STABLE -- migrate per "
+                f"{architecture_guide}'s ADR decision lifecycle",
+                "set the inline Status to OPEN, DECIDED, or STABLE per "
+                f"{architecture_guide}'s ADR decision lifecycle",
+            )
+            return
+
+        expected = "stable" if status == "STABLE" else "draft"
+        actual = self._frontmatter_status(body)
+        if actual != expected:
+            yield self.report(
+                adr,
+                f"inline status {status} requires frontmatter status '{expected}' "
+                f"(got '{actual or '<missing>'}')",
+                f"set frontmatter status: {expected} to match the inline Status: {status}",
+            )
+
+        decisions = self._decisions(ctx)
+        # Requirements live on the board, reached from the plans tree; there is
+        # no specs tree in the standard any more.
+        specs: list[str] = []
+        plans = sorted(set(self._plans_pattern(ctx).findall(body)))
+        architecture = sorted(
+            ref for ref in set(self._architecture_pattern(ctx).findall(body))
+            if not ref.startswith(f"{decisions}/")
+        )
+
+        for ref in (*specs, *plans, *architecture):
+            if not ctx.path(ref).is_file():
+                yield self.report(
+                    adr, f"lifecycle backlink does not resolve: {ref}",
+                    f"fix or remove the broken backlink {ref} so it resolves under the repo root",
+                )
+
+        architecture_root = f"{docs_root}/architecture/"
+        match status:
+            case "OPEN" if not architecture:
+                yield self.report(
+                    adr,
+                    f"OPEN must backlink to the {architecture_root} page it proposes to "
+                    "change -- add a link to the target north star it discusses",
+                    f"add a {architecture_root} backlink to the page this ADR proposes to change",
+                )
+            case "STABLE" if not architecture:
+                yield self.report(
+                    adr,
+                    f"STABLE must backlink to a {architecture_root} page -- that page is "
+                    "now the sole durable record, link it",
+                    f"add a {architecture_root} backlink recording the durable decision",
+                )
+            case "DECIDED":
+                yield from self._decided(ctx, adr, specs, plans)
+
+    def _decided(
+        self, ctx: Context, adr: str, specs: list[str], plans: list[str]
+    ) -> Iterable[Report]:
+        if not plans:
+            yield self.report(
+                adr,
+                "DECIDED must backlink to a plans/ feature document -- add the plan "
+                "that carries this decision to delivery",
+                "add a plans/features/az<id>-<slug>/ backlink to the feature carrying "
+                "this decision",
+            )
+
+    def _inline_status(self, body: str) -> str | None:
+        for line in body.splitlines():
+            found = self.INLINE_STATUS.search(line)
+            if found:
+                return self.TRAILING_PUNCTUATION.sub("", found.group(1)).strip().upper()
+        return None
+
+    def _frontmatter_status(self, body: str) -> str | None:
+        lines = body.splitlines()
+        if not lines or lines[0] != "---":
+            return None
+        for line in lines[1:]:
+            if line == "---":
+                return None
+            found = self.FRONTMATTER_STATUS.match(line)
+            if found:
+                return found.group(1).strip().lower()
+        return None
+
+    def _active_plan(self, ctx: Context, relative: str) -> bool:
+        if ctx.path(relative).parent.name not in self.ACTIVE_PLAN_DIRS:
+            return False
+        body = self.text(ctx, relative)
+        if body is None:
+            return False
+        for line in body.splitlines():
+            found = self.PLAN_STATE.match(line)
+            if found:
+                return found.group(1).strip().lower() in self.ACTIVE_PLAN_STATES
+        return False

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-bad-status/docs/architecture/overview.md

@@ -0,0 +1,8 @@
+---
+title: Overview
+status: stable
+---
+
+# Overview
+
+The target picture this corpus's ADR backlinks to.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-bad-status/docs/decisions/adr-901-proposed.md

@@ -0,0 +1,10 @@
+---
+title: Proposed decision
+status: draft
+---
+
+# ADR-901: Proposed decision
+
+**Status:** PROPOSED
+
+The target page is [the overview](docs/architecture/overview.md).

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-broken-backlink/docs/decisions/adr-902-dangling.md

@@ -0,0 +1,11 @@
+---
+title: Dangling decision
+status: stable
+---
+
+# ADR-902: Dangling decision
+
+**Status:** STABLE
+
+The durable record is [the overview](docs/architecture/overview.md), which this
+corpus deliberately does not contain.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-clean/docs/architecture/overview.md

@@ -0,0 +1,8 @@
+---
+title: Overview
+status: stable
+---
+
+# Overview
+
+The target picture this corpus's ADR backlinks to.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-clean/docs/decisions/adr-900-example.md

@@ -0,0 +1,10 @@
+---
+title: Example decision
+status: stable
+---
+
+# ADR-900: Example decision
+
+**Status:** STABLE
+
+The durable record is [the overview](docs/architecture/overview.md).

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-frontmatter-mismatch/.plans/b_committed/26-08-08-lifecycle-fixture.md

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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-frontmatter-mismatch/.specs/demo/lifecycle.md

@@ -0,0 +1,7 @@
+---
+type: Specification
+title: Lifecycle fixture
+description: Fixture requirement record
+status: draft
+generated: {by: test, at: 2026-08-01T00:00:00Z}
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-frontmatter-mismatch/docs/decisions/adr-903-frontmatter-mismatch.md

@@ -0,0 +1,11 @@
+---
+title: Frontmatter mismatch
+status: stable
+---
+
+# ADR-903: Frontmatter mismatch
+
+**Status: DECIDED.**
+
+Requirement: .specs/demo/lifecycle.md
+Plan: .plans/b_committed/26-08-08-lifecycle-fixture.md

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-inactive-plan/.plans/c_done/26-08-08-completed-fixture.md

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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-inactive-plan/.specs/demo/lifecycle.md

@@ -0,0 +1,7 @@
+---
+type: Specification
+title: Lifecycle fixture
+description: Fixture requirement record
+status: draft
+generated: {by: test, at: 2026-08-01T00:00:00Z}
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/fixtures/adr-lifecycle-inactive-plan/docs/decisions/adr-904-completed-plan.md

@@ -0,0 +1,11 @@
+---
+title: Completed plan
+status: draft
+---
+
+# ADR-904: Completed plan
+
+**Status: DECIDED.**
+
+Requirement: .specs/demo/lifecycle.md
+Plan: .plans/c_done/26-08-08-completed-fixture.md

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/adr_lifecycle/test_check.py

@@ -0,0 +1,127 @@
+"""DOC-001 — an ADR's inline `**Status:**` is its decision state.
+
+One corpus per defect, each holding only the files that defect is about. The
+subject is the RULE: that a status outside OPEN/DECIDED/STABLE is caught, that a
+frontmatter mismatch is caught, that a dangling backlink is caught, and that a
+DECIDED ADR pointing only at a finished plan is caught.
+"""
+
+from __future__ import annotations
+
+from helpers import corpus, verdict_for
+
+from adl_compliance.core.verdict import Outcome
+
+CORPORA = corpus("docs", "adr-lifecycle")
+
+
+def test_a_conforming_adr_is_silent() -> None:
+    """Asserted first. Without it, every case below also passes against a check
+    that reports every ADR it reads."""
+    verdict = verdict_for("DOC-001", CORPORA / "adr-lifecycle-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_status_outside_the_lifecycle_is_reported() -> None:
+    verdict = verdict_for("DOC-001", CORPORA / "adr-lifecycle-bad-status")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "is not OPEN/DECIDED/STABLE" in verdict.render()
+
+
+def test_a_dangling_backlink_is_reported() -> None:
+    verdict = verdict_for("DOC-001", CORPORA / "adr-lifecycle-broken-backlink")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "lifecycle backlink does not resolve" in verdict.render()
+
+
+def test_a_frontmatter_mismatch_is_reported() -> None:
+    verdict = verdict_for("DOC-001", CORPORA / "adr-lifecycle-frontmatter-mismatch")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "requires frontmatter status" in verdict.render()
+
+
+def test_a_linked_plan_is_no_longer_graded_on_the_directory_it_sits_in() -> None:
+    """This asserted the opposite until 2026-09-15: a plan under `.plans/c_done/`
+    resolved but was reported because a FINISHED plan cannot carry a decision to
+    delivery, "active" being read from the directory name.
+
+    7b8c057 deleted that convention outright — `.plans/a_new|b_committed|c_done`
+    became `plans/features/az<id>-<slug>/`, and with it went `plan_state`,
+    `approval_state` and the state-agrees-with-directory rule, because "state now
+    lives only on the board and documents do not move". A directory asserting a work
+    item's state made the repository a second authority on a fact the board owns.
+
+    So whether a linked plan is active is no longer answerable from disk, and this
+    gate does not try. What remains is the backlink itself, asserted below. The rule
+    survived the tree's deletion by eighteen months of nobody writing a DECIDED ADR —
+    DOC-001 was armed and green on enact-m5 the whole time."""
+    verdict = verdict_for("DOC-001", CORPORA / "adr-lifecycle-inactive-plan")
+    assert "requires a linked active plan" not in verdict.render()
+
+
+def test_a_redeclared_docs_tree_is_still_graded(tmp_path) -> None:
+    """The LOUD false-finding this check shipped with.
+
+    `DECISIONS` (a named-path probe) and the `ARCHITECTURE` regex were
+    hardcoded `docs/...` literals. A repository whose docs root is not the
+    packaged default had its real decisions directory fail the probe --
+    "decisions directory is missing", a visible, wrong finding about a
+    directory that is right there -- and even past that, a STABLE ADR's real
+    backlink (written with the repository's own redeclared prefix) would
+    never match `ARCHITECTURE`, so the ADR would be wrongly told to add a
+    link it already has.
+
+    Same corpus as `adr-lifecycle-clean`, committed again under
+    `documentation/` instead of `docs/`, with its one backlink rewritten to
+    match: wrongly reported "decisions directory is missing" before the fix,
+    silent after."""
+    import shutil
+
+    import yaml
+
+    from adl_compliance import runner
+    from adl_compliance.policy.registry import Registry, effective_trees, policy_text
+
+    clean = CORPORA / "adr-lifecycle-clean" / "docs"
+    root = tmp_path / "repo"
+    shutil.copytree(clean, root / "documentation")
+    adr = root / "documentation" / "decisions" / "adr-900-example.md"
+    adr.write_text(
+        adr.read_text(encoding="utf-8").replace(
+            "docs/architecture/overview.md", "documentation/architecture/overview.md"
+        ),
+        encoding="utf-8",
+    )
+
+    trees = {"docs": "documentation"}
+    document = yaml.safe_load(policy_text("gate-registry.yaml"))
+    registry = Registry.model_validate(document, context={"trees": trees})
+    row = registry.by_id("DOC-001")
+
+    verdict = runner.run(
+        row, root, ("documentation/decisions/adr-900-example.md",),
+        trees=effective_trees(trees),
+    )
+    assert verdict.outcome is Outcome.CLEAN, (
+        f"a conforming ADR under a redeclared docs tree was wrongly flagged: "
+        f"{verdict.render()}"
+    )
+
+
+def test_an_absent_decisions_directory_is_a_finding_not_a_pass() -> None:
+    """An absent directory yields an empty set, and an empty set is a clean pass
+    everywhere else in this estate. Without this structural probe the tree
+    losing docs/decisions/ entirely would pass in silence."""
+    verdict = verdict_for("DOC-001", corpus("coverage", "baseline") / "passing", given=())
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "decisions directory is missing" in verdict.render()
+
+
+def test_an_adr_outside_the_given_set_is_not_graded() -> None:
+    """The bad-status corpus is unchanged on disk and its ADR is still wrong,
+    but it is not in the set, so there is nothing to grade."""
+    verdict = verdict_for(
+        "DOC-001", CORPORA / "adr-lifecycle-bad-status",
+        given=("docs/architecture/overview.md",),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/__init__.py

@@ -0,0 +1,7 @@
+"""The `docs.closed-set` gate."""
+
+from __future__ import annotations
+
+from .check import DocsClosedSet
+
+__all__ = ["DocsClosedSet"]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/check.py

@@ -0,0 +1,91 @@
+"""DOC-010 — `docs/` is a closed set.
+
+Modelled directly on `layout.root-closed-set` (LAY-012) and its
+`policy/root_shape.py`: every top-level entry directly under `docs/` must be
+declared, and an entry that is not is a finding — never silently skipped.
+
+DOC-007 (`docs.semantics`) already filters to a fixed collection list
+(`architecture`, `research`, `compliance`, `operations`) before it grades a
+single page, but a path outside that list is simply not selected — it never
+reaches a `case`/`else` branch that could name it. Verified against this
+gap's own reproduction: a `docs/totally-made-up/nonsense.md` file, run through
+the full armed gate set, produces zero findings. This gate closes exactly that
+hole, the same way LAY-012 closes it for the repository root: it does not
+grade CONTENT (DOC-007's job), it grades SHAPE.
+
+`ALLOWED_DIRS`/`ALLOWED_FILES` are imported from `policy/docs_shape.py`, not
+redeclared here — see that module's docstring for where each entry was read
+from. A gate that grew its own copy would be the exact drift `root_shape.py`
+was written to stop, aimed one directory lower.
+
+Like LAY-012, there is no `structural` half: these are PERMITTED entries, not
+REQUIRED ones. A repository that has not yet written a `docs/research/` page
+is not missing a finding for it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+from ....policy.docs_shape import ALLOWED_DOCS_DIRS, ALLOWED_DOCS_FILES
+
+
+class DocsClosedSet(Check):
+    id: ClassVar[str] = "DOC-010"
+    rule: ClassVar[str] = "DOC-010"
+
+    # `<docs>` resolves to this repository's declared docs tree (`docs` in
+    # `adl-config.toml`'s `[controls.compliance.trees]`), the same input shape
+    # DOC-007 declares for the same reason (K-42: a hardcoded `"docs"` literal
+    # silently drops every page when a repository names its tree something
+    # else).
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>"}
+
+    ALLOWED_DIRS: ClassVar[frozenset[str]] = ALLOWED_DOCS_DIRS
+    ALLOWED_FILES: ClassVar[frozenset[str]] = ALLOWED_DOCS_FILES
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        prefix = f"{docs_root}/"
+
+        # The docs-root listing, recovered from the GIVEN SET the same way
+        # LAY-012 recovers the repository-root listing: a path one segment
+        # past the prefix is a docs-root FILE; a path with more than one
+        # remaining segment names a docs-root DIRECTORY by its first segment.
+        dirs: set[str] = set()
+        root_files: set[str] = set()
+        for path in files:
+            if not path.startswith(prefix):
+                continue
+            rel = path[len(prefix):]
+            if not rel:
+                continue
+            if "/" in rel:
+                dirs.add(rel.split("/", 1)[0])
+            else:
+                root_files.add(rel)
+
+        for name in sorted(dirs):
+            if name not in self.ALLOWED_DIRS:
+                yield self.report(
+                    f"{docs_root}/{name}",
+                    "undeclared docs/ subfolder",
+                    f"declare {docs_root}/{name}/ in policy/docs_shape.py's "
+                    "ALLOWED_DOCS_DIRS, or move its contents into "
+                    f"{docs_root}/architecture, {docs_root}/research, "
+                    f"{docs_root}/compliance, {docs_root}/operations, or "
+                    f"{docs_root}/decisions",
+                )
+        for name in sorted(root_files):
+            if name not in self.ALLOWED_FILES:
+                yield self.report(
+                    f"{docs_root}/{name}",
+                    "undeclared top-level docs/ file",
+                    f"declare {name} in policy/docs_shape.py's "
+                    f"ALLOWED_DOCS_FILES, or move {docs_root}/{name} into one "
+                    "of its owning subfolders",
+                )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/AGENTS.md

@@ -0,0 +1 @@
+# guide

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/closed_set/fixtures/docs/CLAUDE.md

@@ -0,0 +1 @@
+# guide

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

@@ -0,0 +1 @@
+declared