@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,225 @@
+"""LAY-016 — no open plans and no open gaps: the limit is zero.
+
+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.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Iterator
+from typing import ClassVar
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun
+from ....core.finding import Finding
+from ..plan_metadata import PlanMetadata
+
+
+class OpenWorkCap(Check):
+    id: ClassVar[str] = "LAY-016"
+    rule: ClassVar[str] = "LAY-016"
+    inputs: ClassVar[dict[str, str]] = {"plans_root": "<plans>"}
+    whole_scope: ClassVar[bool] = True
+
+    OPEN_LIMIT: ClassVar[int] = 10
+    FEATURES: ClassVar[str] = "features"
+    SPEC: ClassVar[str] = "spec.md"
+    REGISTER: ClassVar[str] = "GAPS-AND-FINDINGS.md"
+    IGNORED: ClassVar[str] = ".DS_Store"
+    COLUMNS: ClassVar[tuple[str, ...]] = (
+        "Found",
+        "Finding",
+        "From plan",
+        "Item file",
+        "Work item",
+    )
+    DIVIDER_CELL: ClassVar[re.Pattern[str]] = re.compile(r"^:?-{3,}:?$")
+    WORK_ITEM_LINK: ClassVar[re.Pattern[str]] = re.compile(
+        r"^\[([0-9]+)\]"
+        r"\((https://dev\.azure\.com/\S+/_workitems/edit/([0-9]+)/?)\)$"
+    )
+    UNRAISED: ClassVar[frozenset[str]] = frozenset(("", "-", "—", "TBD"))
+    EXCERPT: ClassVar[int] = 60
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Finding]:
+        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",
+        )
+
+        open_gaps, stale_gaps = self._gaps(ctx, set(files))
+        yield from stale_gaps
+        yield from self._cap(
+            "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",
+        )
+
+    def _cap(self, subject: str, path: str, open_items: list[str], fix: str) -> Iterator[Finding]:
+        if len(open_items) <= self.OPEN_LIMIT:
+            return
+        yield self.report(
+            path,
+            f"{len(open_items)} open {subject}, cap is {self.OPEN_LIMIT}: "
+            + "; ".join(open_items),
+            fix,
+        )
+
+    def _plans(self, ctx: Context) -> str:
+        return ctx.relative(ctx.inputs["plans_root"])
+
+    def _open_plans(self, ctx: Context, given: set[str]) -> list[str]:
+        features = f"{self._plans(ctx)}/{self.FEATURES}"
+        prefix = f"{features}/"
+        names = {
+            path[len(prefix) :].split("/")[0]
+            for path in given
+            if path.startswith(prefix) and path[len(prefix) :]
+        }
+        open_plans: list[str] = []
+        for name in sorted(names):
+            if name == self.IGNORED or not ctx.path(f"{features}/{name}").is_dir():
+                continue
+            spec = f"{features}/{name}/{self.SPEC}"
+            if spec not in given:
+                raise CouldNotRun(
+                    f"{spec} is not in the widened Git-visible file set; an on-disk "
+                    "spec outside that set cannot establish plan state"
+                )
+            body = self.text(ctx, spec)
+            if body is None:
+                raise CouldNotRun(
+                    f"{spec} is missing; an unreadable plan state cannot be counted"
+                )
+            status = self._status(body, spec)
+            if status in PlanMetadata.ACTIVE_STATUSES:
+                open_plans.append(name)
+        return open_plans
+
+    def _status(self, body: str, path: str) -> str:
+        status = PlanMetadata.field(body, PlanMetadata.STATUS_LINE)
+        if status not in PlanMetadata.WORK_ITEM_STATUSES:
+            shown = "missing" if status is None else repr(status)
+            raise CouldNotRun(
+                f"{path} has {shown} status; expected an exact work item state: "
+                f"{', '.join(PlanMetadata.WORK_ITEM_STATUSES)}"
+            )
+        return status
+
+    def _gaps(self, ctx: Context, given: set[str]) -> tuple[list[str], list[Finding]]:
+        register = f"{self._plans(ctx)}/{self.REGISTER}"
+        if register not in given:
+            return [], []
+        body = self.text(ctx, register)
+        if body is None:
+            raise CouldNotRun(
+                f"{register} is in the widened Git-visible file set but cannot be read"
+            )
+
+        rows = [
+            (number, self._cells(line))
+            for number, line in enumerate(body.splitlines(), start=1)
+            if line.lstrip().startswith("|")
+        ]
+        if not rows:
+            raise CouldNotRun(f"{register} exists but holds no Markdown table")
+        if tuple(rows[0][1]) != self.COLUMNS:
+            raise CouldNotRun(
+                f"{register} has columns {rows[0][1]}, expected {list(self.COLUMNS)}"
+            )
+
+        open_gaps: list[str] = []
+        stale: list[Finding] = []
+        for number, cells in rows[1:]:
+            if len(cells) != len(self.COLUMNS):
+                raise CouldNotRun(
+                    f"{register}:{number} has {len(cells)} cells; expected "
+                    f"{len(self.COLUMNS)}, so its work-item column cannot be identified"
+                )
+            if all(self.DIVIDER_CELL.match(cell) for cell in cells):
+                continue
+
+            label = f"line {number}: {cells[0]} {self._excerpt(cells[1])}"
+            work_item_cell = self._plain(cells[4])
+            if work_item_cell in self.UNRAISED:
+                open_gaps.append(label)
+                continue
+
+            linked = self.WORK_ITEM_LINK.match(work_item_cell)
+            if linked is None or linked.group(1) != linked.group(3):
+                raise CouldNotRun(
+                    f"{register}:{number} has malformed work item link "
+                    f"{work_item_cell!r}; use [id](https://dev.azure.com/.../_workitems/edit/id)"
+                )
+            linked_id = int(linked.group(1))
+            item_path = self._plain(cells[3])
+            item_match = re.fullmatch(
+                rf"{re.escape(self._plans(ctx))}/{self.FEATURES}/"
+                r"az[0-9]+-[a-z0-9]+(?:-[a-z0-9]+)*/items/"
+                r"az([0-9]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md",
+                item_path,
+            )
+            if item_match is None or int(item_match.group(1)) != linked_id:
+                raise CouldNotRun(
+                    f"{register}:{number} item file {item_path!r} must be a normalized "
+                    f"repository-relative {self._plans(ctx)}/features/az<feature>-<slug>/"
+                    f"items/az{linked_id}-<slug>.md path"
+                )
+            if item_path not in given:
+                raise CouldNotRun(
+                    f"{register}:{number} item file {item_path!r} is not in the widened "
+                    "Git-visible file set; an on-disk path outside that set cannot "
+                    "establish linked work state"
+                )
+            item_body = self.text(ctx, item_path)
+            if item_body is None:
+                raise CouldNotRun(
+                    f"{register}:{number} names item file {item_path!r}, but it is missing"
+                )
+            found_id, why = PlanMetadata.work_item_id(item_body)
+            if why or found_id != linked_id:
+                raise CouldNotRun(
+                    f"{item_path} must carry a work_item link for {linked_id}; "
+                    f"found {why or found_id}"
+                )
+            status = self._status(item_body, item_path)
+            if status in PlanMetadata.ACTIVE_STATUSES:
+                open_gaps.append(label)
+            elif status in PlanMetadata.TERMINAL_STATUSES:
+                stale.append(
+                    self.report(
+                        register,
+                        f"closed gap remains in the register at {label}; linked item "
+                        f"{linked_id} is {status}",
+                        f"delete line {number} from {register}; closed gaps no longer remain",
+                        line=number,
+                    )
+                )
+        return open_gaps, stale
+
+    @staticmethod
+    def _plain(value: str) -> str:
+        stripped = value.strip()
+        if len(stripped) >= 2 and stripped.startswith("`") and stripped.endswith("`"):
+            return stripped[1:-1].strip()
+        return stripped
+
+    @staticmethod
+    def _cells(line: str) -> list[str]:
+        inner = line.strip().removeprefix("|").removesuffix("|")
+        return [cell.strip().replace(r"\|", "|") for cell in re.split(r"(?<!\\)\|", inner)]
+
+    def _excerpt(self, value: str) -> str:
+        flat = " ".join(value.split())
+        return flat if len(flat) <= self.EXCERPT else f"{flat[: self.EXCERPT]}…"

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/open_work_cap/fixtures/open-work-cap-clean/plans/GAPS-AND-FINDINGS.md

@@ -0,0 +1,5 @@
+# Gaps and findings
+
+| Found | Finding | From plan | Item file | Work item |
+| --- | --- | --- | --- | --- |
+| 2026-09-17 | One unraised gap | spec.md | TBD | TBD |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/open_work_cap/fixtures/open-work-cap-clean/plans/features/az601-clean/spec.md

@@ -0,0 +1,10 @@
+---
+type: feature
+title: A clean feature
+status: New
+epic: https://dev.azure.com/org/project/_workitems/edit/500
+work_item: https://dev.azure.com/org/project/_workitems/edit/601
+last_update: 2026-09-17T00:00:00Z
+---
+
+# A clean feature

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

@@ -0,0 +1,330 @@
+"""LAY-016 — the exact active-work lifecycle and the ten-item boundary."""
+
+from __future__ import annotations
+
+import pathlib
+
+import pytest
+
+from adl_compliance import runner
+from adl_compliance.checks.layout.open_work_cap import OpenWorkCap
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.errors import CouldNotRun
+from adl_compliance.core.verdict import Outcome, could_not_run, decide
+from adl_compliance.policy.registry import load
+
+ROW = load().by_id("LAY-016")
+AZ = "https://dev.azure.com/org/project/_workitems/edit"
+CLEAN = pathlib.Path(__file__).parent / "fixtures" / "open-work-cap-clean"
+HEADER = (
+    "| Found | Finding | From plan | Item file | Work item |\n"
+    "| --- | --- | --- | --- | --- |\n"
+)
+
+
+def spec(status: str, item: int) -> str:
+    return f"---\ntype: feature\nstatus: {status}\nwork_item: {AZ}/{item}\n---\n"
+
+
+def item(status: str, item_id: int) -> str:
+    return f"---\ntype: bug\nstatus: {status}\nwork_item: {AZ}/{item_id}\n---\n"
+
+
+def features(count: int, status: str = "New") -> dict[str, str]:
+    return {
+        f"plans/features/az{600 + n}-feature-{n}/spec.md": spec(status, 600 + n)
+        for n in range(1, count + 1)
+    }
+
+
+def register(*rows: str) -> dict[str, str]:
+    return {"plans/GAPS-AND-FINDINGS.md": HEADER + "".join(rows)}
+
+
+def unraised(n: int, finding: str | None = None) -> str:
+    return (
+        f"| 2026-09-17 | {finding or f'Unraised gap {n}'} | spec.md | TBD | TBD |\n"
+    )
+
+
+def linked(n: int, path: str) -> str:
+    return (
+        f"| 2026-09-17 | Linked gap {n} | spec.md | `{path}` | "
+        f"[{n}]({AZ}/{n}) |\n"
+    )
+
+
+def build(root: pathlib.Path, files: dict[str, str]) -> pathlib.Path:
+    for relative, body in files.items():
+        target = root / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+    return root
+
+
+def grade(root: pathlib.Path, paths: tuple[str, ...] | None = None):
+    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"})
+    try:
+        reports = tuple(OpenWorkCap().run(ctx, FileSet(paths=paths)))
+    except CouldNotRun as exc:
+        return could_not_run(ROW, str(exc))
+    return decide(ROW, reports, advisories=())
+
+
+def test_the_committed_clean_corpus_is_silent() -> None:
+    verdict = grade(CLEAN)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    "status",
+    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+)
+def test_each_exact_active_plan_state_counts_as_open(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    verdict = grade(build(tmp_path, features(11, status)))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "11 open plans, cap is 10" in verdict.render()
+
+
+@pytest.mark.parametrize("status", ("Done", "Removed"))
+def test_each_exact_terminal_plan_state_is_closed(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    tree = features(10)
+    tree.update(
+        {
+            f"plans/features/az999-{status.casefold()}/spec.md": spec(status, 999),
+        }
+    )
+    verdict = grade(build(tmp_path, tree))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize("status", ("Active", "Closed", "Completed", "new", ""))
+def test_a_plan_status_outside_the_exact_board_vocabulary_is_could_not_run(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    verdict = grade(
+        build(
+            tmp_path,
+            {"plans/features/az601-invalid/spec.md": spec(status, 601)},
+        )
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "work item state" in verdict.message
+
+
+def test_a_plan_spec_must_belong_to_the_git_visible_file_set(
+    tmp_path: pathlib.Path,
+) -> None:
+    spec_path = "plans/features/az601-feature/spec.md"
+    item_path = "plans/features/az601-feature/items/az701-visible-item.md"
+    build(
+        tmp_path,
+        {
+            spec_path: spec("New", 601),
+            item_path: item("New", 701),
+        },
+    )
+    verdict = grade(tmp_path, paths=(item_path,))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert spec_path in verdict.message
+    assert "Git-visible file set" in verdict.message
+
+
+def test_status_text_in_the_body_cannot_set_a_plan_state(tmp_path: pathlib.Path) -> None:
+    body = "---\ntype: feature\n---\n\n# Notes\n\nstatus: Done\n"
+    verdict = grade(
+        build(tmp_path, {"plans/features/az601-body-status/spec.md": body})
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "missing status" in verdict.message
+
+
+def test_exactly_ten_open_plans_pass_and_eleven_fail_with_every_name(
+    tmp_path: pathlib.Path,
+) -> None:
+    ten = grade(build(tmp_path / "ten", features(10)))
+    eleven = grade(build(tmp_path / "eleven", features(11)))
+    assert ten.outcome is Outcome.CLEAN, ten.render()
+    assert eleven.outcome is Outcome.FINDINGS, eleven.render()
+    finding = next(f for f in eleven.findings if "open plans" in f.message)
+    for n in range(1, 12):
+        assert f"az{600 + n}-feature-{n}" in finding.message
+
+
+def test_a_partial_file_set_counts_the_complete_plan_tree(
+    tmp_path: pathlib.Path,
+) -> None:
+    root = build(tmp_path, features(11))
+    universe = tuple(features(11))
+
+    verdict = runner.run(
+        ROW,
+        root,
+        ("plans/features/az601-feature-1/spec.md",),
+        exhaustive=False,
+        universe=universe,
+        trees={"plans": "plans"},
+    )
+
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "11 open plans, cap is 10" in verdict.render()
+
+
+@pytest.mark.parametrize(
+    "status",
+    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+)
+def test_unraised_and_each_linked_active_gap_state_both_count_as_open(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    item_path = "plans/features/az601-feature/items/az701-active-gap.md"
+    tree = {
+        **register(unraised(1), *(linked(701, item_path) for _ in range(10))),
+        "plans/features/az601-feature/spec.md": spec("Done", 601),
+        item_path: item(status, 701),
+    }
+    verdict = grade(build(tmp_path, tree))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "11 open gaps, cap is 10" in verdict.render()
+
+
+@pytest.mark.parametrize("status", ("Done", "Removed"))
+def test_each_linked_terminal_gap_state_must_be_deleted_from_the_register(
+    tmp_path: pathlib.Path, status: str
+) -> None:
+    item_path = "plans/features/az601-feature/items/az701-closed-gap.md"
+    tree = {
+        **register(linked(701, item_path)),
+        "plans/features/az601-feature/spec.md": spec("Done", 601),
+        item_path: item(status, 701),
+    }
+    verdict = grade(build(tmp_path, tree))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "closed gap" in verdict.render().casefold()
+    assert "delete" in verdict.findings[0].fix.casefold()
+
+
+@pytest.mark.parametrize(
+    "work_item",
+    (
+        "ticket 701",
+        f"[701]({AZ}/702)",
+        f"701 ({AZ}/701)",
+    ),
+)
+def test_a_malformed_work_item_cell_is_could_not_run_not_a_raised_gap(
+    tmp_path: pathlib.Path, work_item: str
+) -> None:
+    row = f"| 2026-09-17 | Gap | spec.md | `item.md` | {work_item} |\n"
+    verdict = grade(build(tmp_path, register(row)))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "work item link" in verdict.message
+
+
+def test_a_linked_gap_requires_the_named_item_file(tmp_path: pathlib.Path) -> None:
+    verdict = grade(
+        build(
+            tmp_path,
+            register(linked(701, "plans/features/az601-feature/items/az701-missing.md")),
+        )
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "item file" in verdict.message
+
+
+@pytest.mark.parametrize("spelling", ("absolute", "parent-relative"))
+def test_a_linked_gap_rejects_an_item_path_outside_the_repository(
+    tmp_path: pathlib.Path, spelling: str
+) -> None:
+    outside = tmp_path.parent / f"{tmp_path.name}-outside"
+    outside_item = (
+        outside
+        / "plans/features/az601-feature/items/az701-outside-gap.md"
+    )
+    outside_item.parent.mkdir(parents=True, exist_ok=True)
+    outside_item.write_text(item("New", 701), encoding="utf-8")
+    if spelling == "absolute":
+        item_path = str(outside_item)
+    else:
+        item_path = str(outside_item.relative_to(tmp_path.parent))
+        item_path = f"../{item_path}"
+    verdict = grade(build(tmp_path, register(linked(701, item_path))))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "normalized repository-relative" in verdict.message
+
+
+def test_a_linked_gap_item_must_belong_to_the_git_visible_file_set(
+    tmp_path: pathlib.Path,
+) -> None:
+    item_path = "plans/features/az601-feature/items/az701-untracked-gap.md"
+    tree = {
+        **register(linked(701, item_path)),
+        "plans/features/az601-feature/spec.md": spec("Done", 601),
+        item_path: item("New", 701),
+    }
+    build(tmp_path, tree)
+    verdict = grade(tmp_path, paths=("plans/GAPS-AND-FINDINGS.md",))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "Git-visible file set" in verdict.message
+
+
+def test_a_linked_gap_with_an_invalid_item_state_is_could_not_run(
+    tmp_path: pathlib.Path,
+) -> None:
+    item_path = "plans/features/az601-feature/items/az701-invalid-gap.md"
+    tree = {
+        **register(linked(701, item_path)),
+        "plans/features/az601-feature/spec.md": spec("Done", 601),
+        item_path: item("Closed", 701),
+    }
+    verdict = grade(build(tmp_path, tree))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "work item state" in verdict.message
+
+
+def test_an_escaped_pipe_in_a_finding_does_not_break_the_table(
+    tmp_path: pathlib.Path,
+) -> None:
+    rows = tuple(unraised(n, rf"Gap {n} uses a \| b") for n in range(1, 11))
+    verdict = grade(build(tmp_path, register(*rows)))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_short_all_dash_divider_row_is_could_not_run(tmp_path: pathlib.Path) -> None:
+    malformed = {"plans/GAPS-AND-FINDINGS.md": HEADER.splitlines()[0] + "\n| --- | --- |\n"}
+    verdict = grade(build(tmp_path, malformed))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "2 cells" in verdict.message
+
+
+def test_an_on_disk_register_outside_the_git_visible_set_is_not_read(
+    tmp_path: pathlib.Path,
+) -> None:
+    spec_path = "plans/features/az601-feature/spec.md"
+    tree = {
+        spec_path: spec("Done", 601),
+        **register(*(unraised(n) for n in range(1, 12))),
+    }
+    build(tmp_path, tree)
+    verdict = grade(tmp_path, paths=(spec_path,))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_exactly_ten_open_gaps_pass_and_eleven_fail_with_every_row(
+    tmp_path: pathlib.Path,
+) -> None:
+    ten = grade(build(tmp_path / "ten", register(*(unraised(n) for n in range(1, 11)))))
+    eleven = grade(
+        build(tmp_path / "eleven", register(*(unraised(n) for n in range(1, 12))))
+    )
+    assert ten.outcome is Outcome.CLEAN, ten.render()
+    assert eleven.outcome is Outcome.FINDINGS, eleven.render()
+    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

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

@@ -0,0 +1,12 @@
+"""The `layout.placement` 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 Placement
+
+__all__ = ["Placement"]