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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-over-cap/docs/guide/c.md

@@ -0,0 +1 @@
+c

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-over-cap/docs/short/only.md

@@ -0,0 +1 @@
+only

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-over-cap/grants.yaml

@@ -0,0 +1,4 @@
+schema_version: 2
+over_children_baseline:
+  archive/src: 4
+single_file_baseline: {}

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/held/a.md

@@ -0,0 +1 @@
+a

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/held/b.md

@@ -0,0 +1 @@
+b

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/held/c.md

@@ -0,0 +1 @@
+c

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/held/d.md

@@ -0,0 +1 @@
+d

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/shrunk/a.md

@@ -0,0 +1 @@
+a

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/docs/shrunk/b.md

@@ -0,0 +1 @@
+b

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-stale/grants.yaml

@@ -0,0 +1,6 @@
+schema_version: 2
+docs_pages:
+  baseline:
+    docs/shrunk: 3
+    docs/gone: 2
+    docs/held: 4

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-unusable/docs/guide/a.md

@@ -0,0 +1 @@
+a

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-unusable/docs/guide/b.md

@@ -0,0 +1 @@
+b

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-unusable/docs/guide/c.md

@@ -0,0 +1 @@
+c

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/directory_size/fixtures/docs-size-unusable/grants.yaml

@@ -0,0 +1,3 @@
+schema_version: 2
+max_children:
+  docs: [unclosed

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

@@ -0,0 +1,345 @@
+"""DOC-012 — the page-count cap for every directory directly under docs/.
+
+Ten committed corpora, the runner-driven shape LAY-004's test uses:
+`docs-size-clean` (every directory within the engine-default cap of 15),
+`docs-size-default-cap` (sixteen pages in one directory, no declared cap —
+DIR-004 names the default; the old-style register beside it proves a register
+without a `docs_pages` section is no exemption), `docs-size-over-cap` (DIR-004
+with an in-cap control beside it), `docs-size-exempt` (a baseline entry
+exempts its directory up to the recorded number), `docs-size-grew` (DIR-005,
+a directory past its recorded exemption), `docs-size-stale` (DIR-006's two
+kept cases, shrunk-under-cap and directory-gone, with a still-valid baseline
+entry beside them), `docs-size-no-section` (an old-style register holds no
+exemptions, so the cap is enforced bare over its five-page directory),
+`docs-size-decisions` (the flat ADR log is exempt by rule at any depth, with
+an over-cap directory beside it proving the corpus is not silent by
+accident), `docs-size-assets` (non-`.md` assets, dot-prefixed pages, and
+paths outside docs/ are not counted, at the runner level and — reading the
+check directly, the way DOC-011's test does — at the check level), and
+`docs-size-unusable` (a register that exists but is not valid YAML —
+could-not-run, the ruling's kept exception).
+
+V2 (owner ruling 2026-10-02, replacing v1 the same day): the cap lives in
+`[controls.compliance.limits].docs_pages_per_directory` (engine default 15),
+NOT in the register. The register is exemptions ONLY — a `docs_pages.baseline`
+entry exempts its directory up to the recorded number; no entry means no
+exemption, so an ABSENT register or a register without a `docs_pages` section
+grades STRICTER (the widening input's normal contract — v1's "ratchets sit
+ON TOP" absence-is-clean exception belonged to LAY-004, whose configuration
+IS the register; DOC-012's configuration is the declared limit). Two tests
+below are the v1 tests reworked for the flip, and say so. At zero exemptions
+the register file has no meaning and is deleted — adl-azdo's own was.
+
+Each fixture carries its own `grants.yaml` at its own root, passed as the
+`register` input override — the same mechanism LAY-004's test uses. The cap
+travels as the `docs-pages-per-directory` declaration, the same channel
+LAY-014's tests use for `scripts-direct-files`. `docs_root` needs no
+override: the corpora are laid out in the fixture tree shape and
+`conftest.py` declares it once for the suite.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance import runner
+from adl_compliance.checks.docs.directory_size import DocsDirectorySize
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.finding import Finding
+from adl_compliance.core.verdict import Outcome
+from adl_compliance.policy.registry import load
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+ROW = load().by_id("DOC-012")
+
+
+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, *, register: str = "grants.yaml", cap: str | None = None) -> object:
+    directory = FIXTURES / case
+    declarations = {} if cap is None else {DocsDirectorySize.PAGES_DECLARATION: cap}
+    return runner.run(
+        ROW, directory, corpus_files(directory),
+        inputs={ROW.id: {"register": directory / register}},
+        declarations=declarations,
+    )
+
+
+def findings_for(
+    root: pathlib.Path, given: tuple[str, ...], *, cap: str | None = None
+) -> tuple[Finding, ...]:
+    """The check read directly, bypassing row-scope narrowing — the honest way
+    to prove the CHECK's own filters (prefix, `.md`, dot-components,
+    liveness), which the runner's scope intersection could otherwise be
+    mistaken for."""
+    declarations = {} if cap is None else {DocsDirectorySize.PAGES_DECLARATION: cap}
+    ctx = Context(
+        root=root, row=ROW,
+        inputs={"register": root / "grants.yaml", "docs_root": root / "docs"},
+        declarations=declarations,
+    )
+    return tuple(DocsDirectorySize().run(ctx, FileSet(paths=given)))
+
+
+# ------------------------------------------------------------------ the cap
+
+
+def test_a_tree_within_the_default_cap_passes() -> None:
+    """No declaration, cap 15, every directory well under it."""
+    verdict = run("docs-size-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert not verdict.findings
+    assert not verdict.advisories
+
+
+def test_a_directory_over_the_default_cap_is_dir_004() -> None:
+    verdict = run("docs-size-default-cap")
+    assert verdict.outcome is Outcome.FINDINGS
+    findings = [f for f in verdict.findings if f.rule == "DIR-004"]
+    assert len(findings) == 1, tuple(f.render() for f in verdict.findings)
+    finding = findings[0]
+    assert finding.path == "docs/guide"
+    assert finding.message == "16 pages (max 15), no ratchet entry"
+    assert finding.fix == (
+        "add a docs_pages baseline entry for docs/guide to the ratchet "
+        "register, or split the directory"
+    )
+
+
+def test_a_declared_cap_wins_over_the_default() -> None:
+    """The same three-page corpus is clean under a declared cap of 3 and
+    reported under a declared cap of 2 — the declaration, not the default,
+    is the limit in force (no down-only ratchet, same as LAY-014)."""
+    assert run("docs-size-over-cap", cap="3").outcome is Outcome.CLEAN
+    assert run("docs-size-over-cap", cap="2").outcome is Outcome.FINDINGS
+
+
+def test_a_malformed_cap_declaration_is_could_not_run() -> None:
+    """Mirrors LAY-014's `direct_file_limit`: a value that is not a base-10
+    positive integer is could-not-run naming
+    `[controls.compliance.limits].docs_pages_per_directory`, never a quiet
+    fall back to the default."""
+    verdict = run("docs-size-over-cap", cap="banana")
+    assert verdict.outcome is Outcome.COULD_NOT_RUN
+    assert "docs_pages_per_directory" in verdict.message
+    verdict = run("docs-size-over-cap", cap="0")
+    assert verdict.outcome is Outcome.COULD_NOT_RUN
+    assert "docs_pages_per_directory" in verdict.message
+
+
+# -------------------------------------------- the register is exemptions only
+
+
+def test_an_absent_register_enforces_the_cap_bare() -> None:
+    """REWORKED from v1's `test_an_absent_register_means_nothing_is_ratcheted`,
+    which asserted the opposite. Owner ruling 2026-10-02 (v2): the register
+    holds EXEMPTIONS, not configuration — if it is not there, no exemptions
+    are allowed, so the cap is enforced bare and the over-cap directory
+    reports. (v1's "ratchets sit ON TOP" absence-is-clean reading belonged to
+    LAY-004, whose configuration IS the register; DOC-012's configuration is
+    the declared limit, so absence here grades STRICTER — the widening
+    input's normal contract.)"""
+    verdict = run("docs-size-over-cap", register="does-not-exist.yaml", cap="2")
+    assert verdict.outcome is Outcome.FINDINGS
+    findings = [f for f in verdict.findings if f.rule == "DIR-004"]
+    assert len(findings) == 1, tuple(f.render() for f in verdict.findings)
+    assert findings[0].path == "docs/guide"
+
+
+def test_a_register_without_a_docs_pages_section_enforces_the_cap_bare() -> None:
+    """REWORKED from v1's `test_a_register_without_a_docs_pages_section_passes_clean`,
+    which asserted the opposite under the v1 ruling. Same v2 reasoning as the
+    absent-register case, one step milder: the register EXISTS and parses —
+    it just names no exemptions, so the five-page directory reports against a
+    declared cap of 3."""
+    verdict = run("docs-size-no-section", cap="3")
+    assert verdict.outcome is Outcome.FINDINGS
+    findings = [f for f in verdict.findings if f.rule == "DIR-004"]
+    assert len(findings) == 1, tuple(f.render() for f in verdict.findings)
+    assert findings[0].path == "docs/guide"
+    assert findings[0].message == "5 pages (max 3), no ratchet entry"
+
+
+def test_a_baseline_entry_exempts_its_directory_up_to_the_recorded_number() -> None:
+    """The exemption channel itself: three pages against a declared cap of 2
+    are CLEAN because the register records `docs/guide: 3` — the entry
+    forgives the directory up to the count it was recorded at (growing past
+    it is DIR-005, reported separately)."""
+    verdict = run("docs-size-exempt", cap="2")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert not verdict.findings
+
+
+# ------------------------------------------------------------------ DIR-004
+
+
+def test_an_over_cap_directory_with_no_entry_is_dir_004() -> None:
+    verdict = run("docs-size-over-cap", cap="2")
+    assert verdict.outcome is Outcome.FINDINGS
+    findings = [f for f in verdict.findings if f.rule == "DIR-004"]
+    assert len(findings) == 1, tuple(f.render() for f in verdict.findings)
+    finding = findings[0]
+    assert finding.path == "docs/guide"
+    assert finding.message == "3 pages (max 2), no ratchet entry"
+    assert finding.fix == (
+        "add a docs_pages baseline entry for docs/guide to the ratchet "
+        "register, or split the directory"
+    )
+    assert "docs/short" not in {f.path for f in verdict.findings}
+
+
+def test_the_register_is_not_a_grant_catalogue() -> None:
+    """`structural_grant = True` forces the allowance to 0 regardless of the
+    row's `grants:` field — the same arithmetic LAY-004 pins: the register is
+    spent BEFORE counting, never subtracted after."""
+    verdict = run("docs-size-over-cap", cap="2")
+    assert verdict.granted == 0
+    assert verdict.outcome is Outcome.FINDINGS
+
+
+# ------------------------------------------------------------------ DIR-005
+
+
+def test_a_directory_that_grew_past_its_baseline_is_dir_005() -> None:
+    verdict = run("docs-size-grew", cap="2")
+    assert verdict.outcome is Outcome.FINDINGS
+    findings = [f for f in verdict.findings if f.rule == "DIR-005"]
+    assert len(findings) == 1, tuple(f.render() for f in verdict.findings)
+    finding = findings[0]
+    assert finding.path == "docs/guide"
+    assert finding.message == "3 pages (baseline 2)"
+    assert finding.fix == (
+        "reduce docs/guide back to at most 2 pages, or raise its "
+        "docs_pages baseline entry"
+    )
+    # The entry exists, so DIR-004 must NOT fire alongside DIR-005.
+    assert not [f for f in verdict.findings if f.rule == "DIR-004"]
+
+
+# ------------------------------------------------------------------ DIR-006
+
+
+def test_a_baseline_entry_shrunk_under_the_cap_is_dir_006() -> None:
+    verdict = run("docs-size-stale", cap="3")
+    stale = [f for f in verdict.findings if f.rule == "DIR-006"]
+    assert len(stale) == 2, tuple(f.render() for f in verdict.findings)
+    by_path = {f.path: f for f in stale}
+    shrunk = by_path["docs/shrunk"]
+    assert shrunk.message == "ratchet entry is no longer required"
+    assert shrunk.fix == (
+        "delete docs/shrunk's stale docs_pages baseline entry from the "
+        "ratchet register"
+    )
+    # The directory-gone case: the entry names a directory the tree no
+    # longer holds. Grading ABSENCE, exactly like LAY-004's DIR-003.
+    assert "docs/gone" in by_path
+
+
+def test_a_still_valid_baseline_entry_is_not_reported() -> None:
+    """`docs/held` holds 4 pages over the declared cap of 3 with a recorded
+    baseline of 4 — over the cap but AT its recorded number, so neither
+    DIR-004 (the entry exists) nor DIR-005 (it did not grow) fires, and
+    DIR-006 must not either (4 is still over the cap, so the entry is
+    load-bearing)."""
+    verdict = run("docs-size-stale", cap="3")
+    assert "docs/held" not in {f.path for f in verdict.findings}
+
+
+# ------------------------------------------------------- unusable registers
+
+
+def test_a_register_that_exists_but_is_unusable_is_could_not_run() -> None:
+    """The kept exception through both ruling shapes: a register that exists
+    but cannot be parsed may be mid-edit; grading it as "no exemptions" would
+    silently drop every baseline it names. Could-not-run either way."""
+    verdict = run("docs-size-unusable", cap="2")
+    assert verdict.outcome is Outcome.COULD_NOT_RUN
+    assert "unusable" in verdict.message
+
+
+def test_a_register_that_exists_but_is_not_a_file_is_could_not_run() -> None:
+    directory = FIXTURES / "docs-size-over-cap"
+    verdict = runner.run(
+        ROW, directory, corpus_files(directory),
+        inputs={ROW.id: {"register": directory}},
+        declarations={DocsDirectorySize.PAGES_DECLARATION: "2"},
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN
+    assert "exists but is not a file" in verdict.message
+
+
+# --------------------------------------------------------- the rule's filters
+
+
+def test_decisions_is_exempt_at_any_depth() -> None:
+    """The flat ADR log is exempt by rule (owner ruling 2026-10-02, flat by
+    design per the docs convention), at the log root and below it. `guide` is
+    over the same cap and MUST be reported — without it the corpus would be
+    silent by accident."""
+    verdict = run("docs-size-decisions", cap="2")
+    assert verdict.outcome is Outcome.FINDINGS
+    assert {f.path for f in verdict.findings} == {"docs/guide"}
+    assert all(f.rule == "DIR-004" for f in verdict.findings)
+
+
+def test_assets_dotfiles_and_outside_paths_are_not_counted() -> None:
+    """Through the runner: `guide` holds 2 visible pages beside 3 non-`.md`
+    assets; counting assets would report it (5 over the declared cap of 3).
+    `plans/` and the root `docs.md` never reach the check — the row's scope
+    is the runner's business — but they are in the given set, so a check that
+    counted them would say so here."""
+    verdict = run("docs-size-assets", cap="3")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert not verdict.findings
+
+
+def test_the_check_itself_skips_assets_dotfiles_and_outside_paths() -> None:
+    """Read directly, with the dot-prefixed files the runner may or may not
+    hand over: the counted set is `a.md`, `b.md`, `sub/nested.md` — the
+    dot-prefixed pages, the assets, the `plans/` tree and the root `docs.md`
+    lookalike are all invisible to the rule. Counting any of them would push
+    `guide` over the declared cap of 3 and report it."""
+    directory = FIXTURES / "docs-size-assets"
+    findings = findings_for(directory, corpus_files(directory), cap="3")
+    assert findings == (), tuple(f.render() for f in findings)
+
+
+def test_a_deleted_file_is_not_counted() -> None:
+    """The `is_file` liveness check, LAY-004's discipline: a set may name a
+    file this commit deleted. Handed the two live paths and one ghost under a
+    declared cap of 2, the count stays at the cap — no finding."""
+    directory = FIXTURES / "docs-size-over-cap"
+    given = (
+        "docs/guide/a.md",
+        "docs/guide/b.md",
+        "docs/guide/ghost.md",  # in the set, deleted from disk
+        "docs/short/only.md",
+    )
+    findings = findings_for(directory, given, cap="2")
+    assert findings == (), tuple(f.render() for f in findings)
+
+
+def test_an_empty_set_grades_nothing() -> None:
+    findings = findings_for(FIXTURES / "docs-size-over-cap", (), cap="2")
+    assert findings == ()
+
+
+# --------------------------------------------------------------- the wiring
+
+
+def test_the_register_is_not_packaged_data() -> None:
+    """The regression guard, same shape as LAY-004's: re-adding a `resources`
+    entry here would ship one repository's exemption register to every other
+    repository (the K-42 defect)."""
+    assert "register" in DocsDirectorySize.inputs
+    assert "register" not in DocsDirectorySize.resources
+    assert DocsDirectorySize.inputs["register"].startswith("<")
+    assert "docs_root" in DocsDirectorySize.inputs

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

@@ -190,15 +190,28 @@ class DocsEnglishOnly(Check):
 
     # ------------------------------------------------------ subject-matter scope
 
-    def _i18n_owner(self, ctx: Context) -> str:
-        return f"{ctx.relative(ctx.inputs['frontend_src'])}/mobile/src/i18n"
+    def _i18n_owner(self, ctx: Context) -> str | None:
+        # Decision for a tree declared absent (`frontend = ""`, which drops
+        # `frontend_src` from the resolved inputs): this input only contributes
+        # the i18n OWNER exemption, an extra path that excuses translated strings
+        # beneath it. A repository with no frontend tree has no such directory, so
+        # there is no exemption to grant -- Han text anywhere is graded by the rule
+        # as written, and the generic locale-directory exemption below still
+        # applies. This read `ctx.inputs['frontend_src']` unguarded -- a `KeyError`
+        # traceback (exit 1), not a verdict, on any file.
+        frontend_src = ctx.inputs.get("frontend_src")
+        if frontend_src is None:
+            return None
+        return f"{ctx.relative(frontend_src)}/mobile/src/i18n"
 
-    def _excluded(self, relative: str, i18n_owner: str) -> bool:
+    def _excluded(self, relative: str, i18n_owner: str | None) -> bool:
         # 1. Hidden paths, by decision. Every component is tested.
         if any(part.startswith(".") for part in relative.split("/")):
             return True
-        # 2. The one named i18n owner exemption.
-        if relative == i18n_owner or relative.startswith(i18n_owner + "/"):
+        # 2. The one named i18n owner exemption (absent when the frontend tree is).
+        if i18n_owner is not None and (
+            relative == i18n_owner or relative.startswith(i18n_owner + "/")
+        ):
             return True
         # 3. Any locale-named data directory, anywhere.
         if self.LOCALE_DIR.search(relative):

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

@@ -191,3 +191,38 @@ def test_an_unreadable_office_archive_is_reported_not_silently_skipped(
     verdict = graded_directly(tmp_path, ("broken.docx",))
     assert verdict.outcome is Outcome.FINDINGS, verdict.render()
     assert verdict.findings[0].message == "unreadable Office archive on this line"
+
+
+def test_a_frontend_tree_declared_absent_leaves_only_the_locale_directory_exemption(
+    tmp_path: pathlib.Path,
+) -> None:
+    """`frontend = ""` drops `frontend_src` from the resolved inputs. It only
+    contributes the i18n OWNER exemption (an extra path), so absent that
+    exemption does not exist -- but the generic locale-directory exemption
+    still does, and Han text elsewhere is still reported. This was a
+    `KeyError: 'frontend_src'` traceback (exit 1) on any file, measured against
+    enact-combined with `--tree rust= --tree frontend=`."""
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "page.ts").write_text("const label = '一'\n", encoding="utf-8")
+    (tmp_path / "web" / "mobile" / "src" / "i18n").mkdir(parents=True)
+    (tmp_path / "web" / "mobile" / "src" / "i18n" / "strings.ts").write_text(
+        "export const label = '一'\n", encoding="utf-8"
+    )
+    (tmp_path / "web" / "i18n" / "locales" / "zh-CN").mkdir(parents=True)
+    (tmp_path / "web" / "i18n" / "locales" / "zh-CN" / "strings.ts").write_text(
+        "export const label = '一'\n", encoding="utf-8"
+    )
+    ctx = Context(root=tmp_path, row=ROW)
+    findings = tuple(
+        DocsEnglishOnly().graded(
+            ctx,
+            FileSet(
+                paths=(
+                    "src/page.ts",
+                    "web/mobile/src/i18n/strings.ts",
+                    "web/i18n/locales/zh-CN/strings.ts",
+                )
+            ),
+        )
+    )
+    assert sorted(f.path for f in findings) == ["src/page.ts", "web/mobile/src/i18n/strings.ts"], findings

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

@@ -0,0 +1,7 @@
+"""DOC-011 — `docs.filename`."""
+
+from __future__ import annotations
+
+from .check import DocsFilename
+
+__all__ = ["DocsFilename"]

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

@@ -0,0 +1,91 @@
+"""DOC-011 -- every Markdown page under `docs/` has a lower-kebab stem.
+
+The rule this gate grades, stated in full:
+
+    For every `.md` file in scope, the filename stem must full-match
+    `^[a-z0-9]+(-[a-z0-9]+)*$` -- lower-kebab: runs of `[a-z0-9]` joined by
+    single hyphens, nothing else. Exact-name exemptions: `AGENTS.md` and
+    `CLAUDE.md`, the standing tree-guide names the other docs gates exclude
+    from grading too (DOC-006's scope carries them; `layout.agents-layout`
+    governs them). Non-`.md` files are NOT graded: docs trees legitimately
+    hold `.png`/`.html`/`.csv`/`.yaml` assets, and the rule is about page
+    names, not asset names -- a `UI-CONTRACT.png` beside a fixed
+    `UI-CONTRACT.md` is not a finding.
+
+The row's scope mirrors DOC-006 (`docs.okf-profile`) exactly -- `<docs>/**`
+with the same `proposals/`, `compliance/`, guide, and `index.md` excludes --
+so both docs/ content gates walk the same tree (see the registry row's
+comment for the carried-over rationale).
+
+SCOPE OF THE RULE, DECIDED 2026-10-02 (orchestrator correction): an earlier
+shape of this gate enforced ADR naming (`adr-<NNN>-<slug>.md`) over
+`<docs>/decisions/**`; that reading invented a rule the brief did not carry.
+This gate is the kebab-stem rule above; ADR naming may become its own gate
+later and is deliberately not graded here -- every well-formed ADR name
+(`adr-001-organization-workspace-tenancy.md`) is kebab-conforming anyway,
+so the two rules only diverge on legacy prose names, which this gate reports
+by the kebab rule wherever they sit under docs/.
+
+There is no `structural` half, the same call DOC-010 (`docs.closed-set`)
+makes: every rule here is answered from the GIVEN SET, and a repository
+whose docs/ tree holds no `.md` page is permitted, not failing.
+
+The check-level filters, in order: the path must sit under the resolved
+`docs_root` (a lookalike `docs.md` beside the tree is outside it), the file
+must be `.md`, and the basename must not be one of the two exempt guide
+names. The row's scope excludes (`proposals/`, `compliance/`, guides,
+`index.md`) are the runner's narrowing; the guide-name exemption is repeated
+here because it is a property of the RULE (a name may not be lower-kebab and
+still be correct), not of one scope.
+
+Like DOC-010, `docs_root` is read straight from `ctx.inputs` -- a missing
+docs tree is a misconfiguration this gate has no lenient mode for, and
+adl-azdo declares `docs = "docs"`.
+"""
+
+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 DocsFilename(Check):
+    id: ClassVar[str] = "DOC-011"
+    rule: ClassVar[str] = "DOC-011"
+
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>"}
+    """The same named input DOC-001 and DOC-010 declare for the same reason
+    (K-42: a hardcoded `"docs"` literal silently drops every page when a
+    repository names its documentation tree something else)."""
+
+    KEBAB: ClassVar[re.Pattern[str]] = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+    """The stem grammar, anchored by `fullmatch`: one or more runs of
+    `[a-z0-9]`, single-hyphen joined. Uppercase, underscores, spaces,
+    leading/trailing/double hyphens all fail the full match."""
+
+    GUIDE_NAMES: ClassVar[frozenset[str]] = frozenset({"AGENTS.md", "CLAUDE.md"})
+    """The standing tree-guide names, exempt by exact basename at any depth
+    -- the rule-level pair to the scope excludes the row carries."""
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        prefix = f"{docs_root}/"
+        for path in files:
+            if not path.startswith(prefix):
+                continue
+            name = path.rsplit("/", 1)[-1]
+            if not name.endswith(".md") or name in self.GUIDE_NAMES:
+                continue
+            stem = name[: -len(".md")]
+            if not self.KEBAB.fullmatch(stem):
+                yield self.report(
+                    path,
+                    f"{stem} is not lower-kebab ([a-z0-9]+(-[a-z0-9]+)*)",
+                    f"rename {path} so the stem is lower-kebab -- words of "
+                    "[a-z0-9] joined by single hyphens",
+                )

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

@@ -0,0 +1,3 @@
+# AGENTS fixture
+
+Standing tree guide name; the gate exempts it by exact name.

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

@@ -0,0 +1,3 @@
+# CLAUDE fixture
+
+Standing tree guide name; the gate exempts it by exact name.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/-leading-hyphen.md

@@ -0,0 +1,3 @@
+# Leading hyphen
+
+Stem begins with a hyphen; the first run must be [a-z0-9]+.

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

@@ -0,0 +1,3 @@
+# Architecture guide
+
+Nested tree guide; the gate exempts the name at any depth.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/double--hyphen.md

@@ -0,0 +1,3 @@
+# Double hyphen
+
+A double hyphen leaves an empty segment between the dashes.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/getting started.md

@@ -0,0 +1,3 @@
+# Getting started
+
+Space-separated stem.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/nested/page-here.md

@@ -0,0 +1,3 @@
+# Nested page
+
+Conforming stem several directories below docs/.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/trailing-hyphen-.md

@@ -0,0 +1,3 @@
+# Trailing hyphen
+
+Stem ends with a hyphen; the last run must be [a-z0-9]+.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/ui-contract.md

@@ -0,0 +1,4 @@
+# UI contract
+
+Uppercase stem -- the real violation shape from the Enact consumer tree
+(docs/architecture/frontend/UI-CONTRACT.md).

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/architecture/user_profile.md

@@ -0,0 +1,3 @@
+# User profile
+
+Underscore-separated stem.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/assets/UI-CONTRACT.png

@@ -0,0 +1,2 @@
+PNG asset with a violating STEM -- still not graded, because the rule
+grades Markdown pages only and this file is not .md.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/assets/diagram.png

@@ -0,0 +1 @@
+PNG asset placeholder; non-Markdown files are not graded.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/index.md

@@ -0,0 +1,4 @@
+# Index
+
+Standing catalog name; excluded from the row scope, and its stem is
+conforming anyway.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/notes.md

@@ -0,0 +1,3 @@
+# Notes
+
+The task ledger; a conforming stem.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/filename/fixtures/docs/reference.html

@@ -0,0 +1 @@
+<!doctype html><title>reference</title>