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

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

@@ -22,9 +22,13 @@ from __future__ import annotations
 
 import pathlib
 
+import pytest
+
+from adl_compliance import runner
 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.errors import CouldNotRun
 from adl_compliance.core.verdict import Outcome, decide
 from adl_compliance.policy.registry import load
 
@@ -218,3 +222,193 @@ def test_a_redeclared_estate_still_allows_and_excludes_the_resolved_entries(
         f"real files under redeclared roots were wrongly reported outside "
         f"the allowed docs trees: {findings}"
     )
+
+
+# ---------------------------------------------- per-repository root declarations
+def graded_declaring(tmp_path, declarations: dict[str, str], given: tuple[str, ...]):
+    """`graded`, plus what the repository declared about its own root
+    (`[controls.compliance.root]` arrives as the `root-files` / `root-dirs`
+    declarations)."""
+    ctx = Context(root=tmp_path, row=ROW, declarations=declarations)
+    findings = tuple(MarkdownTrees().graded(ctx, FileSet(paths=given)))
+    return decide(ROW, findings, 0, ())
+
+
+def test_a_non_standard_root_markdown_file_is_reported_without_a_declaration(tmp_path) -> None:
+    """STATUS.md and DRIFT.md are not on the central list any more, so the
+    exclusion they used to ride in on is gone."""
+    verdict = graded_declaring(tmp_path, {}, ("STATUS.md", "DRIFT.md"))
+    assert sorted(f.path for f in verdict.findings) == ["DRIFT.md", "STATUS.md"], verdict.render()
+    assert all(
+        f.message == "documentation file outside the allowed docs trees" for f in verdict.findings
+    )
+
+
+def test_a_declared_root_markdown_file_is_excluded(tmp_path) -> None:
+    verdict = graded_declaring(
+        tmp_path, {"root-files": "STATUS.md, DRIFT.md"}, ("STATUS.md", "DRIFT.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declaration_excludes_only_the_names_it_lists(tmp_path) -> None:
+    """Without this, the case above also passes against a gate that stops
+    grading Markdown as soon as any declaration is present."""
+    verdict = graded_declaring(
+        tmp_path, {"root-files": "STATUS.md"}, ("STATUS.md", "STRAY.md", "backend/notes.md"),
+    )
+    assert sorted(f.path for f in verdict.findings) == ["STRAY.md", "backend/notes.md"], (
+        verdict.render()
+    )
+
+
+def test_a_declared_root_name_is_excluded_at_the_root_only(tmp_path) -> None:
+    """`fnmatch`'s `*` crosses `/`, but the declared name is matched EXACTLY: a
+    nested file of the same name is not the declared root file."""
+    verdict = graded_declaring(tmp_path, {"root-files": "STATUS.md"}, ("backend/STATUS.md",))
+    assert [f.path for f in verdict.findings] == ["backend/STATUS.md"], verdict.render()
+
+
+def test_a_declared_name_is_matched_literally_not_as_a_glob(tmp_path) -> None:
+    """`_matches_any` uses `fnmatchcase`, so a declared name carrying glob
+    characters must be escaped: `a[b].md` excludes that file and not `ab.md`."""
+    verdict = graded_declaring(tmp_path, {"root-files": "a[b].md"}, ("a[b].md", "ab.md"))
+    assert [f.path for f in verdict.findings] == ["ab.md"], verdict.render()
+    verdict = graded_declaring(tmp_path, {"root-files": "*.md"}, ("anything.md",))
+    assert [f.path for f in verdict.findings] == ["anything.md"], verdict.render()
+
+
+def test_a_root_dirs_declaration_does_not_exclude_a_root_markdown_file(tmp_path) -> None:
+    verdict = graded_declaring(tmp_path, {"root-dirs": "STATUS.md"}, ("STATUS.md",))
+    assert [f.path for f in verdict.findings] == ["STATUS.md"], verdict.render()
+
+
+def test_a_declared_root_mdx_file_is_excluded_too(tmp_path) -> None:
+    """This gate grades `.md` and `.mdx`; a declared root name in either
+    extension must be honoured or the declaration looks ignored."""
+    verdict = graded_declaring(tmp_path, {"root-files": "STATUS.mdx"}, ("STATUS.mdx",))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ---------------------------------------- per-repository Markdown roots
+# `[controls.compliance.markdown].roots` arrives as one `markdown-roots`
+# declaration, a comma-separated list of repository-relative directories. A
+# declared root only ever ADDS allowlist entries, so absent means stricter --
+# the same direction `specs_root` has always had, reached through the config
+# route instead of an input only a hand-built Context could carry.
+DECLARED_ROOTS = "markdown-roots"
+CONTENT_PAGES = (
+    "apps/marketing/src/content/use-cases/a.md",
+    "apps/marketing/index.md",
+    "apps/platform/src/content/docs/docs/b.md",
+)
+
+
+def test_without_a_markdown_roots_declaration_content_pages_are_reported(tmp_path) -> None:
+    """The measured finding this declaration exists for: Astro content-collection
+    pages sit under `apps/`, outside every tree LAY-006 knows. Absent the
+    declaration they are still reported -- the declaration widens, nothing else does."""
+    verdict = graded_declaring(tmp_path, {}, CONTENT_PAGES)
+    assert sorted(f.path for f in verdict.findings) == sorted(CONTENT_PAGES), verdict.render()
+
+
+def test_a_declared_markdown_root_admits_every_page_beneath_it(tmp_path) -> None:
+    verdict = graded_declaring(
+        tmp_path,
+        {DECLARED_ROOTS: "apps/marketing,apps/platform/src/content"},
+        CONTENT_PAGES,
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declared_markdown_root_admits_mdx_too(tmp_path) -> None:
+    """This gate grades `.md` and `.mdx`; a root admitting one suffix and
+    reporting the other would look like the declaration was half ignored."""
+    verdict = graded_declaring(
+        tmp_path,
+        {DECLARED_ROOTS: "apps/marketing"},
+        ("apps/marketing/src/content/page.mdx", "apps/marketing/page.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_each_declared_markdown_root_admits_only_itself(tmp_path) -> None:
+    """A declared root must not become a hole: a sibling directory sharing its
+    prefix, a different subtree of the same parent, and an undeclared root are
+    all still reported."""
+    stray = (
+        "apps/marketing-old/a.md",
+        "apps/other/b.md",
+        "apps/platform/src/other/c.md",
+        "apps/platform/src/content-extra/d.md",
+        "marketing/e.md",
+    )
+    verdict = graded_declaring(
+        tmp_path,
+        {DECLARED_ROOTS: "apps/marketing,apps/platform/src/content"},
+        (*CONTENT_PAGES, *stray),
+    )
+    assert sorted(f.path for f in verdict.findings) == sorted(stray), verdict.render()
+
+
+def test_declaring_only_one_root_leaves_the_other_reported(tmp_path) -> None:
+    verdict = graded_declaring(tmp_path, {DECLARED_ROOTS: "apps/marketing"}, CONTENT_PAGES)
+    assert [f.path for f in verdict.findings] == ["apps/platform/src/content/docs/docs/b.md"], (
+        verdict.render()
+    )
+
+
+def test_a_declared_markdown_root_tolerates_whitespace_empties_and_a_trailing_slash(
+    tmp_path,
+) -> None:
+    verdict = graded_declaring(
+        tmp_path,
+        {DECLARED_ROOTS: " apps/marketing/ , ,apps/platform/src/content// "},
+        CONTENT_PAGES,
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_declared_markdown_root_is_matched_literally_not_as_a_glob(tmp_path) -> None:
+    """`_matches_any` is `fnmatchcase`, so a declared root carrying glob
+    characters must be escaped or it would admit more than it names."""
+    verdict = graded_declaring(
+        tmp_path, {DECLARED_ROOTS: "apps/[x]"}, ("apps/[x]/a.md", "apps/x/b.md"),
+    )
+    assert [f.path for f in verdict.findings] == ["apps/x/b.md"], verdict.render()
+    verdict = graded_declaring(tmp_path, {DECLARED_ROOTS: "apps/*"}, ("apps/anything/a.md",))
+    assert [f.path for f in verdict.findings] == ["apps/anything/a.md"], verdict.render()
+
+
+def test_the_declared_roots_are_named_in_the_remedy(tmp_path) -> None:
+    """The remedy quotes the SAME set the rule graded against, so a reader is
+    never sent somewhere the gate does not accept -- and a declared root is one
+    of the places it does."""
+    verdict = graded_declaring(tmp_path, {DECLARED_ROOTS: "apps/marketing"}, ("stray/x.md",))
+    assert "apps/marketing/*.md" in verdict.findings[0].fix, verdict.render()
+
+
+@pytest.mark.parametrize(
+    "bad",
+    ["/etc", "/", "..", "../outside", "apps/../secrets", ".", "./apps", "apps/./x", "apps//x"],
+)
+def test_a_malformed_declared_markdown_root_is_could_not_run_never_a_wider_allowlist(
+    tmp_path, bad: str
+) -> None:
+    """An absolute path, a `..` or `.` segment, or an empty segment names no
+    directory this repository owns. Treating it as a root could only WIDEN the
+    allowlist, so the gate refuses to run rather than grade against it."""
+    ctx = Context(root=tmp_path, row=ROW, declarations={DECLARED_ROOTS: bad})
+    with pytest.raises(CouldNotRun, match=DECLARED_ROOTS):
+        tuple(MarkdownTrees().graded(ctx, FileSet(paths=("stray/x.md",))))
+
+
+def test_a_malformed_declared_markdown_root_is_could_not_run_through_the_runner(tmp_path) -> None:
+    (tmp_path / "stray").mkdir()
+    (tmp_path / "stray" / "x.md").write_text("x\n", encoding="utf-8")
+    verdict = runner.run(
+        ROW, tmp_path, ("stray/x.md",), exhaustive=True,
+        declarations={DECLARED_ROOTS: "../outside"},
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert DECLARED_ROOTS in verdict.message

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

@@ -1,12 +1,17 @@
-"""LAY-016 — no open plans and no open gaps: the limit is zero.
+"""LAY-016 — at most ten open plans and at most ten open gaps, by default.
 
 Plans and linked gap items use the exact board-state vocabulary shared with
 LAY-009. An unraised gap and a gap linked to active work both remain open. A
 gap linked to terminal work is stale register content and must be deleted.
 
-OPEN_LIMIT was 10 until 2026-09-27 (Tarun: "limit is zero" — see
-`docs/operations/repo-controls-copy-notes.md` for the quote and decision).
-Any open plan or open gap row is now a finding; there is no headroom.
+The two caps are independent and each is `OPEN_LIMIT` (10) unless the
+repository declares its own, as `--declare open-gaps=N` / `--declare
+open-plans=N` (`[controls.compliance.limits].open_gaps` / `.open_plans` in its
+adl-config.toml). `open_gaps_limit` / `open_plans_limit` resolve them: absent
+is the default, and a value that is not a base-10 positive integer is
+could-not-run, never a quiet fall back to the default. The engine default is
+not raised; a repository states the count it carries today and ratchets it
+down.
 """
 
 from __future__ import annotations
@@ -28,7 +33,11 @@ class OpenWorkCap(Check):
     inputs: ClassVar[dict[str, str]] = {"plans_root": "<plans>"}
     whole_scope: ClassVar[bool] = True
 
+    # The engine default for each cap. A repository states its own with the
+    # `open-gaps` / `open-plans` declarations; see `open_gaps_limit`.
     OPEN_LIMIT: ClassVar[int] = 10
+    OPEN_GAPS_DECLARATION: ClassVar[str] = "open-gaps"
+    OPEN_PLANS_DECLARATION: ClassVar[str] = "open-plans"
     FEATURES: ClassVar[str] = "features"
     SPEC: ClassVar[str] = "spec.md"
     REGISTER: ClassVar[str] = "GAPS-AND-FINDINGS.md"
@@ -48,12 +57,46 @@ class OpenWorkCap(Check):
     UNRAISED: ClassVar[frozenset[str]] = frozenset(("", "-", "—", "TBD"))
     EXCERPT: ClassVar[int] = 60
 
+    def open_gaps_limit(self, ctx: Context) -> int:
+        """The open-gap cap in force: the declared one, else `OPEN_LIMIT`."""
+        return self._declared_limit(ctx, self.OPEN_GAPS_DECLARATION, "open_gaps")
+
+    def open_plans_limit(self, ctx: Context) -> int:
+        """The open-plan cap in force: the declared one, else `OPEN_LIMIT`."""
+        return self._declared_limit(ctx, self.OPEN_PLANS_DECLARATION, "open_plans")
+
+    def _declared_limit(self, ctx: Context, declaration: str, key: str) -> int:
+        """One cap's declared value, else `OPEN_LIMIT`.
+
+        ASCII digits only, so `+20`, `1_0`, ` 20` and full-width digits are
+        refused, which `int()` alone would accept. A declaration that cannot be
+        read as a positive integer is could-not-run: falling back to the default
+        would grade the repository against a cap it explicitly replaced.
+        """
+        declared = ctx.declarations.get(declaration)
+        if declared is None:
+            return self.OPEN_LIMIT
+        if re.fullmatch(r"[0-9]+", declared) is None or int(declared) < 1:
+            raise CouldNotRun(
+                f"declaration {declaration}={declared!r} is not a base-10 positive "
+                f"integer; set [controls.compliance.limits].{key} to a whole number "
+                "of at least 1"
+            )
+        return int(declared)
+
     def graded(self, ctx: Context, files: FileSet) -> Iterable[Finding]:
+        # Both caps are resolved before either is graded, so an unreadable
+        # declaration is could-not-run even when the cap it names is not the
+        # one being exceeded.
+        plans_limit = self.open_plans_limit(ctx)
+        gaps_limit = self.open_gaps_limit(ctx)
+
         yield from self._cap(
             "plans",
             f"{self._plans(ctx)}/{self.FEATURES}",
             self._open_plans(ctx, set(files)),
-            "finish or remove every open Feature; none may stay open",
+            plans_limit,
+            f"finish or remove open Features until no more than {plans_limit} remain",
         )
 
         open_gaps, stale_gaps = self._gaps(ctx, set(files))
@@ -62,16 +105,19 @@ class OpenWorkCap(Check):
             "gaps",
             f"{self._plans(ctx)}/{self.REGISTER}",
             open_gaps,
-            "finish linked work and delete its gap row, or resolve unraised gaps; "
-            "none may stay open",
+            gaps_limit,
+            "finish linked work and delete its gap row, or resolve unraised gaps, "
+            f"until no more than {gaps_limit} remain",
         )
 
-    def _cap(self, subject: str, path: str, open_items: list[str], fix: str) -> Iterator[Finding]:
-        if len(open_items) <= self.OPEN_LIMIT:
+    def _cap(
+        self, subject: str, path: str, open_items: list[str], limit: int, fix: str
+    ) -> Iterator[Finding]:
+        if len(open_items) <= limit:
             return
         yield self.report(
             path,
-            f"{len(open_items)} open {subject}, cap is {self.OPEN_LIMIT}: "
+            f"{len(open_items)} open {subject}, cap is {limit}: "
             + "; ".join(open_items),
             fix,
         )

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import pathlib
+import re
 
 import pytest
 
@@ -80,7 +81,7 @@ def test_the_committed_clean_corpus_is_silent() -> None:
 
 @pytest.mark.parametrize(
     "status",
-    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
 )
 def test_each_exact_active_plan_state_counts_as_open(
     tmp_path: pathlib.Path, status: str
@@ -178,7 +179,7 @@ def test_a_partial_file_set_counts_the_complete_plan_tree(
 
 @pytest.mark.parametrize(
     "status",
-    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
 )
 def test_unraised_and_each_linked_active_gap_state_both_count_as_open(
     tmp_path: pathlib.Path, status: str
@@ -328,3 +329,258 @@ def test_exactly_ten_open_gaps_pass_and_eleven_fail_with_every_row(
     finding = next(f for f in eleven.findings if "open gaps" in f.message)
     for n in range(1, 12):
         assert f"Unraised gap {n}" in finding.message
+
+
+# ------------------------------------------------- the two caps are declarable
+# `[controls.compliance.limits].open_gaps` / `.open_plans` reach the engine as
+# `--declare open-gaps=N` / `--declare open-plans=N`. The engine default stays
+# ten for each; a repository that carries more open work today states its own
+# cap in its adl-config.toml, and a value the engine cannot read is a
+# could-not-run, never a quiet fall back to ten. The two caps are independent.
+GAPS_DECLARATION = "open-gaps"
+PLANS_DECLARATION = "open-plans"
+
+
+def grade_declared(
+    root: pathlib.Path,
+    declarations: dict[str, str],
+    paths: tuple[str, ...] | None = None,
+):
+    """`grade`, with declarations. Does not catch CouldNotRun: some tests expect it raised."""
+    if paths is None:
+        paths = tuple(str(path.relative_to(root)) for path in root.rglob("*") if path.is_file())
+    ctx = Context(
+        row=ROW, root=root, inputs={"plans_root": root / "plans"}, declarations=declarations
+    )
+    return decide(ROW, tuple(OpenWorkCap().run(ctx, FileSet(paths=paths))), advisories=())
+
+
+def gaps(count: int) -> dict[str, str]:
+    return register(*(unraised(n) for n in range(1, count + 1)))
+
+
+def test_no_declaration_keeps_the_engine_default_of_ten() -> None:
+    ctx = Context(row=ROW, root=CLEAN)
+    assert OpenWorkCap().open_gaps_limit(ctx) == 10
+    assert OpenWorkCap().open_plans_limit(ctx) == 10
+    assert OpenWorkCap.OPEN_LIMIT == 10
+
+
+def test_a_declared_gap_cap_is_the_effective_gap_cap_and_leaves_the_plan_cap() -> None:
+    ctx = Context(row=ROW, root=CLEAN, declarations={GAPS_DECLARATION: "37"})
+    assert OpenWorkCap().open_gaps_limit(ctx) == 37
+    assert OpenWorkCap().open_plans_limit(ctx) == 10
+
+
+def test_a_declared_plan_cap_is_the_effective_plan_cap_and_leaves_the_gap_cap() -> None:
+    ctx = Context(row=ROW, root=CLEAN, declarations={PLANS_DECLARATION: "11"})
+    assert OpenWorkCap().open_plans_limit(ctx) == 11
+    assert OpenWorkCap().open_gaps_limit(ctx) == 10
+
+
+def test_a_declared_gap_cap_accepts_gaps_the_default_would_refuse(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, gaps(14))
+    assert grade(root).outcome is Outcome.FINDINGS
+    result = grade_declared(root, {GAPS_DECLARATION: "14"})
+    assert result.outcome is Outcome.CLEAN, result.render()
+    assert result.findings == ()
+
+
+def test_a_declared_plan_cap_accepts_plans_the_default_would_refuse(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, features(12))
+    assert grade(root).outcome is Outcome.FINDINGS
+    result = grade_declared(root, {PLANS_DECLARATION: "12"})
+    assert result.outcome is Outcome.CLEAN, result.render()
+    assert result.findings == ()
+
+
+def test_over_a_declared_gap_cap_the_finding_names_the_declared_cap_not_ten(
+    tmp_path: pathlib.Path,
+) -> None:
+    result = grade_declared(build(tmp_path, gaps(16)), {GAPS_DECLARATION: "15"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    assert len(result.findings) == 1
+    text = result.render()
+    assert "16 open gaps, cap is 15" in text, text
+    assert "cap is 10" not in text, text
+    for n in range(1, 17):
+        assert f"Unraised gap {n}" in text
+
+
+def test_over_a_declared_plan_cap_the_finding_names_the_declared_cap_not_ten(
+    tmp_path: pathlib.Path,
+) -> None:
+    result = grade_declared(build(tmp_path, features(13)), {PLANS_DECLARATION: "12"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    assert len(result.findings) == 1
+    text = result.render()
+    assert "13 open plans, cap is 12" in text, text
+    assert "cap is 10" not in text, text
+
+
+@pytest.mark.parametrize("cap", (1, 3, 10, 25))
+def test_exactly_the_declared_gap_cap_passes_and_one_more_fails(
+    tmp_path: pathlib.Path, cap: int
+) -> None:
+    declared = {GAPS_DECLARATION: str(cap)}
+    at_cap = grade_declared(build(tmp_path / "at", gaps(cap)), declared)
+    over = grade_declared(build(tmp_path / "over", gaps(cap + 1)), declared)
+    assert at_cap.outcome is Outcome.CLEAN, at_cap.render()
+    assert over.outcome is Outcome.FINDINGS, over.render()
+    assert f"{cap + 1} open gaps, cap is {cap}" in over.render()
+
+
+@pytest.mark.parametrize("cap", (1, 3, 10, 25))
+def test_exactly_the_declared_plan_cap_passes_and_one_more_fails(
+    tmp_path: pathlib.Path, cap: int
+) -> None:
+    declared = {PLANS_DECLARATION: str(cap)}
+    at_cap = grade_declared(build(tmp_path / "at", features(cap)), declared)
+    over = grade_declared(build(tmp_path / "over", features(cap + 1)), declared)
+    assert at_cap.outcome is Outcome.CLEAN, at_cap.render()
+    assert over.outcome is Outcome.FINDINGS, over.render()
+    assert f"{cap + 1} open plans, cap is {cap}" in over.render()
+
+
+def test_a_declared_cap_below_ten_refuses_what_the_default_would_accept(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, {**gaps(5), **features(5)})
+    assert grade(root).outcome is Outcome.CLEAN
+    result = grade_declared(root, {GAPS_DECLARATION: "4", PLANS_DECLARATION: "4"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    text = result.render()
+    assert "5 open gaps, cap is 4" in text, text
+    assert "5 open plans, cap is 4" in text, text
+
+
+def test_declaring_ten_grades_exactly_like_no_declaration(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, {**gaps(11), **features(11)})
+    declared = grade_declared(root, {GAPS_DECLARATION: "10", PLANS_DECLARATION: "10"})
+    default = grade(root)
+    assert declared.outcome is default.outcome is Outcome.FINDINGS
+    assert [f.render() for f in declared.findings] == [f.render() for f in default.findings]
+    assert "11 open gaps, cap is 10" in declared.render()
+    assert "11 open plans, cap is 10" in declared.render()
+
+
+def test_the_gap_cap_does_not_move_the_plan_cap(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, {**gaps(15), **features(11)})
+    result = grade_declared(root, {GAPS_DECLARATION: "15"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    assert len(result.findings) == 1
+    text = result.render()
+    assert "11 open plans, cap is 10" in text, text
+    assert "open gaps" not in text, text
+
+
+def test_the_plan_cap_does_not_move_the_gap_cap(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, {**gaps(11), **features(15)})
+    result = grade_declared(root, {PLANS_DECLARATION: "15"})
+    assert result.outcome is Outcome.FINDINGS, result.render()
+    assert len(result.findings) == 1
+    text = result.render()
+    assert "11 open gaps, cap is 10" in text, text
+    assert "open plans" not in text, text
+
+
+def test_both_caps_declared_together_each_apply_to_their_own_count(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, {**gaps(37), **features(11)})
+    result = grade_declared(root, {GAPS_DECLARATION: "37", PLANS_DECLARATION: "11"})
+    assert result.outcome is Outcome.CLEAN, result.render()
+    one_below = grade_declared(root, {GAPS_DECLARATION: "36", PLANS_DECLARATION: "10"})
+    assert one_below.outcome is Outcome.FINDINGS, one_below.render()
+    text = one_below.render()
+    assert "37 open gaps, cap is 36" in text, text
+    assert "11 open plans, cap is 10" in text, text
+
+
+def test_an_unrelated_declaration_does_not_change_either_cap(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, {**gaps(11), **features(11)})
+    result = grade_declared(
+        root,
+        {"license": "Proprietary", "root-dirs": "apps", "scripts-direct-files": "20"},
+    )
+    text = result.render()
+    assert "11 open gaps, cap is 10" in text, text
+    assert "11 open plans, cap is 10" in text, text
+
+
+def test_the_remedy_states_the_effective_cap_and_never_hard_codes_ten(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, {**gaps(16), **features(13)})
+    result = grade_declared(root, {GAPS_DECLARATION: "15", PLANS_DECLARATION: "12"})
+    by_subject = {
+        ("gaps" if "open gaps" in f.message else "plans"): f.fix for f in result.findings
+    }
+    assert "no more than 15 remain" in by_subject["gaps"], by_subject
+    assert "no more than 12 remain" in by_subject["plans"], by_subject
+    for fix in by_subject.values():
+        assert re.search(r"\bten\b", fix, re.IGNORECASE) is None, fix
+
+
+def test_the_default_remedy_states_the_cap_as_a_number(tmp_path: pathlib.Path) -> None:
+    result = grade(build(tmp_path, {**gaps(11), **features(11)}))
+    assert len(result.findings) == 2
+    for finding in result.findings:
+        assert "no more than 10 remain" in finding.fix, finding.fix
+        assert re.search(r"\bten\b", finding.fix, re.IGNORECASE) is None, finding.fix
+
+
+UNREADABLE = ["abc", "0", "-3", "2.5", "", "+20", "1_0", "２０"]
+
+
+@pytest.mark.parametrize("value", UNREADABLE)
+@pytest.mark.parametrize("name", (GAPS_DECLARATION, PLANS_DECLARATION))
+def test_an_unreadable_declared_cap_could_not_run(
+    tmp_path: pathlib.Path, name: str, value: str
+) -> None:
+    """Never a silent fall back to ten: not a base-10 positive integer is loud."""
+    root = build(tmp_path, {**features(1), **gaps(1)})
+    with pytest.raises(CouldNotRun) as raised:
+        grade_declared(root, {name: value})
+    message = str(raised.value)
+    assert name in message, message
+    assert repr(value) in message, message
+    assert could_not_run(ROW, message).outcome is Outcome.COULD_NOT_RUN
+
+
+def test_a_bad_declaration_for_the_cap_that_is_not_exceeded_is_still_could_not_run(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Eleven gaps exceed the gap cap; the unreadable plan cap must still not be skipped."""
+    root = build(tmp_path, gaps(11))
+    with pytest.raises(CouldNotRun, match=PLANS_DECLARATION):
+        grade_declared(root, {PLANS_DECLARATION: "abc"})
+
+
+def test_a_declared_cap_reaches_the_check_through_the_runner(tmp_path: pathlib.Path) -> None:
+    root = build(tmp_path, {**features(11), **gaps(12)})
+    universe = tuple(
+        str(path.relative_to(root)) for path in root.rglob("*") if path.is_file()
+    )
+
+    def run(declarations: dict[str, str] | None):
+        return runner.run(
+            ROW,
+            root,
+            universe,
+            exhaustive=True,
+            declarations=declarations,
+            trees={"plans": "plans"},
+        )
+
+    default = run(None)
+    assert default.outcome is Outcome.FINDINGS, default.render()
+    declared = run({GAPS_DECLARATION: "12", PLANS_DECLARATION: "11"})
+    assert declared.outcome is Outcome.CLEAN, declared.render()
+    refused = run({GAPS_DECLARATION: "abc"})
+    assert refused.outcome is Outcome.COULD_NOT_RUN, refused.render()
+    assert GAPS_DECLARATION in refused.message