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

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

@@ -0,0 +1,438 @@
+"""LAY-009 — the `plans/` tree's shape, and each file's agreement with the
+work item it is named for.
+
+    plans/
+    ├── AGENTS.md
+    ├── templates/
+    │   ├── feature.md
+    │   └── backlog-item.md
+    └── features/
+        └── az<id>-<slug>/
+            ├── spec.md
+            └── items/
+                └── az<id>-<slug>.md
+
+Two ideas carry the whole layout, and both are checked here.
+
+**The folder is the parent.** An item's Feature is the directory it sits in, so
+the relationship cannot be mistyped — there is no back-pointer to keep in step
+with reality. What CAN drift is the frontmatter's claim about which work item a
+file describes, so that is what this gate compares.
+
+**The filename is the identity.** `az<id>` means the board allocated the id
+before the file was written, so a file is named correctly from its first save
+and never renamed. A filename whose id disagrees with its own `work_item:` is
+the one way this rots, and it rots silently: every tool keeps working, and the
+file simply describes a different work item than its name claims.
+
+Replaces the earlier `.plans/a_new|b_committed|c_done` lifecycle tree. That
+design mirrored a work item's state in a directory name, which meant two
+authorities for one fact. State now lives only on the board and files do not
+move, so `plan_state` and `approval_state` went with it.
+"""
+
+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.finding import Finding
+from ..plan_metadata import PlanMetadata
+
+
+class PlansLayout(Check):
+    id: ClassVar[str] = "LAY-009"
+    rule: ClassVar[str] = "LAY-009"
+
+    # Resolved, not hardcoded. This literal was used BOTH ways in one check: a
+    # loud probe (`ctx.path(self._plans(ctx)).is_dir()`) and a silent `startswith`
+    # filter (`_under`). The probe fires first and masks the filter today, but a
+    # filter that drops every candidate when a tree is redeclared is the CON-002
+    # shape -- a clean pass over nothing -- and it should not survive behind a
+    # guard that happens to run earlier.
+    inputs: ClassVar[dict[str, str]] = {"plans_root": "<plans>"}
+
+    FEATURES: ClassVar[str] = "features"
+    TEMPLATES: ClassVar[str] = "templates"
+    ITEMS: ClassVar[str] = "items"
+    SPEC: ClassVar[str] = "spec.md"
+
+    # Supporting documents, named by ROLE and not by topic. The topic is already
+    # the directory (`az355-channels-humans-and-agents`), so a file called
+    # `CHANNELS-HANDOVER.md` states it twice and states it differently in the next
+    # feature. A closed set keeps the property the two-file rule was protecting:
+    # you can tell what a file is from its name, in every feature, without opening
+    # it. Adding a name here later is cheap; leaving the set open is how a tree
+    # ends up with HANDOVER.md, handover-v2.md and channels-notes.md side by side.
+    SUPPORTING: ClassVar[tuple[str, ...]] = ("handoff.md", "review.md")
+
+    ROOT_DIRS: ClassVar[tuple[str, ...]] = ("features", "templates")
+    # `GAPS-AND-FINDINGS.md` sits here because its own rows say where they go:
+    # each becomes an item file "parented under the same Feature as the plan it
+    # was found from". It is a register OF plans work, so it belongs beside the
+    # plans, not at the repository root. `root_shape.REGISTERS` still permits a
+    # register at root for repositories that keep one there -- that is an
+    # allowlist, not a requirement, so nothing breaks by leaving.
+    # `LEDGER.md`, not `LEDGER.yaml`. Owner ruling 2026-09-17: the plan-event
+    # ledger is Markdown, because the estate already has ast-grep markdown and
+    # yq frontmatter tooling to scan it, and a YAML register beside a tree of
+    # Markdown was the odd one out.
+    #
+    # Three gates held an opinion on this file and they did not agree: LAY-006
+    # allowed `*/LEDGER.md`, DOC-009 required `LEDGER.yaml` and reported the
+    # Markdown form as "legacy", and this list allowed only the YAML. A
+    # repository could not satisfy all three at once -- enact-m5's conversion
+    # failed here the moment it succeeded elsewhere.
+    ROOT_ALLOWED_FILES: ClassVar[tuple[str, ...]] = (
+        "AGENTS.md", "CLAUDE.md", "LEDGER.md", "GAPS-AND-FINDINGS.md",
+    )
+    IGNORED: ClassVar[str] = ".DS_Store"
+
+    # az<work item id>-<kebab-slug>
+    FEATURE_DIR: ClassVar[re.Pattern[str]] = re.compile(r"^az([0-9]+)-[a-z0-9]+(-[a-z0-9]+)*$")
+    ITEM_FILE: ClassVar[re.Pattern[str]] = re.compile(r"^az([0-9]+)-[a-z0-9]+(-[a-z0-9]+)*\.md$")
+
+    WORK_ITEM_LINE: ClassVar[re.Pattern[str]] = PlanMetadata.WORK_ITEM_LINE
+    EPIC_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^epic:\s*(.+)$")
+    TYPE_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^type:\s*(.+)$")
+    TITLE_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^title:\s*(.+)$")
+    STATUS_LINE: ClassVar[re.Pattern[str]] = PlanMetadata.STATUS_LINE
+    MODIFIED_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^last_update:\s*(.+)$")
+    SOURCES_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^sources:\s*$")
+
+    ITEM_TYPES: ClassVar[tuple[str, ...]] = ("pbi", "bug")
+    FEATURE_TYPE: ClassVar[str] = "feature"
+
+    # The board's own states. `status` here mirrors the work item, not a
+    # document lifecycle, so `draft` and `stable` are wrong in this tree.
+    #
+    # This gate checks the value is a REAL state; it cannot check the value is
+    # the CURRENT one, because that needs the board. A file whose status has
+    # gone stale is the known cost of keeping the field at all.
+    STATUSES: ClassVar[tuple[str, ...]] = PlanMetadata.WORK_ITEM_STATUSES
+
+    # A work item reference is the URL you can click, not a bare id: the id is
+    # already in the filename, so repeating it as a number adds nothing, while
+    # the link takes a reader to the board.
+    WORK_ITEM_URL: ClassVar[re.Pattern[str]] = PlanMetadata.WORK_ITEM_URL
+
+    ISO_8601: ClassVar[re.Pattern[str]] = re.compile(
+        r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+    )
+
+    # The lifecycle tree this layout replaced. Named so a half-migrated repo
+    # gets a pointed finding rather than silence about a directory the gate no
+    # longer has any opinion on.
+    #
+    # FIXED 2026-09-16 (K-42 sweep, SILENT form): the three `plans/a_new` etc.
+    # entries were hardcoded, probed with `ctx.path(legacy).is_dir()`. A
+    # repository whose plans root is not the packaged default had a real,
+    # still-unmigrated legacy directory fail that probe silently -- no
+    # finding, indistinguishable from an already-clean migration. `.plans`
+    # (no slash-suffix) is a different, older tree name that was never nested
+    # under `plans/`, so it stays a bare literal; the three below are built
+    # from the resolved root in `_legacy`.
+    LEGACY_NAMES: ClassVar[tuple[str, ...]] = ("a_new", "b_committed", "c_done")
+
+    # ------------------------------------------------------------- structural
+
+    def _plans(self, ctx: Context) -> str:
+        return ctx.relative(ctx.inputs["plans_root"])
+
+    def _legacy(self, ctx: Context) -> tuple[str, ...]:
+        plans = self._plans(ctx)
+        return tuple(f"{plans}/{name}" for name in self.LEGACY_NAMES)
+
+    def structural(self, ctx: Context) -> Iterable[Finding]:
+        if not ctx.path(self._plans(ctx)).is_dir():
+            yield self.report(
+                self._plans(ctx),
+                "plans root is missing",
+                f"create {self._plans(ctx)}/ with features/ and templates/ subdirectories",
+            )
+            return
+
+        features = f"{self._plans(ctx)}/{self.FEATURES}"
+        if not ctx.path(features).is_dir():
+            yield self.report(
+                features,
+                "features directory is missing",
+                f"create {features}/, one az<id>-<slug>/ directory per Feature",
+            )
+
+        for legacy in self._legacy(ctx):
+            if ctx.path(legacy).is_dir():
+                yield self.report(
+                    legacy,
+                    "lifecycle-state directory is no longer part of the layout",
+                    f"move the documents in {legacy} into "
+                    f"{features}/az<id>-<slug>/ and delete the directory; "
+                    "state lives on the board, not in a directory name",
+                )
+
+    # ------------------------------------------------------------------ graded
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Finding]:
+        given = set(files)
+        yield from self._root_entries(ctx, given)
+        yield from self._template_entries(self._plans(ctx), given)
+        yield from self._feature_dirs(ctx, given)
+
+    # --------------------------------------------------------------- indexing
+
+    @staticmethod
+    def _under(parent: str, paths: Iterable[str]) -> set[str]:
+        """Direct children of `parent` among `paths`, files and directories
+        alike — a path two levels down contributes its intermediate directory."""
+        prefix = f"{parent}/"
+        out: set[str] = set()
+        for path in paths:
+            if not path.startswith(prefix):
+                continue
+            rest = path[len(prefix) :]
+            if not rest:
+                continue
+            out.add(f"{parent}/{rest.split('/')[0]}")
+        return out
+
+    # -------------------------------------------------------------- root walk
+
+    def _root_entries(self, ctx: Context, given: set[str]) -> Iterator[Finding]:
+        for entry in sorted(self._under(self._plans(ctx), given)):
+            name = entry.rsplit("/", 1)[-1]
+            if name == self.IGNORED:
+                continue
+            if ctx.path(entry).is_dir():
+                if name not in self.ROOT_DIRS:
+                    yield self.report(
+                        entry,
+                        "directory must be features/ or templates/",
+                        f"move {entry} out of {self._plans(ctx)}/, or rename it to "
+                        "features/ or templates/",
+                    )
+            elif name not in self.ROOT_ALLOWED_FILES:
+                yield self.report(
+                    entry,
+                    # Derived from the constant, never restated. The hardcoded
+                    # version had drifted twice over: it named `LEDGER.yaml`,
+                    # which is no longer allowed, and omitted
+                    # `GAPS-AND-FINDINGS.md`, which is -- so it was wrong about
+                    # both ends of the same four-item list it was describing.
+                    f"direct plans files must be one of: {', '.join(self.ROOT_ALLOWED_FILES)}",
+                    f"move {entry} into its Feature directory under "
+                    f"{self._plans(ctx)}/{self.FEATURES}/",
+                )
+
+    # ---------------------------------------------------------- templates walk
+
+    def _template_entries(self, plans: str, given: set[str]) -> Iterator[Finding]:
+        templates = f"{plans}/{self.TEMPLATES}"
+        for entry in sorted(self._under(templates, given)):
+            name = entry.rsplit("/", 1)[-1]
+            if name == self.IGNORED:
+                continue
+            if not name.endswith(".md"):
+                yield self.report(
+                    entry,
+                    "plan templates must be direct Markdown files",
+                    f"flatten {entry} into a .md file directly under {templates}",
+                )
+
+    # ----------------------------------------------------------- features walk
+
+    def _feature_dirs(self, ctx: Context, given: set[str]) -> Iterator[Finding]:
+        features = f"{self._plans(ctx)}/{self.FEATURES}"
+        for entry in sorted(self._under(features, given)):
+            name = entry.rsplit("/", 1)[-1]
+            if name == self.IGNORED:
+                continue
+
+            if not ctx.path(entry).is_dir():
+                yield self.report(
+                    entry,
+                    "features/ holds one directory per Feature, not loose files",
+                    f"move {entry} into {features}/az<id>-<slug>/",
+                )
+                continue
+
+            match = self.FEATURE_DIR.match(name)
+            if not match:
+                yield self.report(
+                    entry,
+                    "Feature directory must be named az<work item id>-<kebab-slug>",
+                    f"rename {entry} to az<id>-<slug>, using the id of the "
+                    "Feature work item it describes",
+                )
+                continue
+
+            yield from self._feature_contents(ctx, entry, int(match.group(1)), given)
+
+    def _feature_contents(
+        self, ctx: Context, feature_dir: str, feature_id: int, given: set[str]
+    ) -> Iterator[Finding]:
+        spec = f"{feature_dir}/{self.SPEC}"
+        if not ctx.path(spec).is_file():
+            yield self.report(
+                spec,
+                "Feature directory must hold a spec.md",
+                f"add {spec} from plans/templates/feature.md",
+            )
+        else:
+            yield from self._check_spec(ctx, spec, feature_id)
+
+        for entry in sorted(self._under(feature_dir, given)):
+            name = entry.rsplit("/", 1)[-1]
+            if name in (self.IGNORED, self.SPEC, self.ITEMS):
+                continue
+            if name in self.SUPPORTING:
+                # A supporting document carries the same frontmatter as everything
+                # else in this tree. Without it a handoff is an undated wall of prose
+                # that names no work item -- readable today, unattributable in a month,
+                # which is the state CHANNELS-HANDOVER.md was in at the repository root.
+                yield from self._common(ctx, entry, self.text(ctx, entry) or "", feature_id)
+                continue
+            allowed = ", ".join((self.SPEC, *self.SUPPORTING, f"{self.ITEMS}/"))
+            yield self.report(
+                entry,
+                f"a Feature directory holds {allowed} only",
+                f"rename it to one of {', '.join(self.SUPPORTING)}, move it into {feature_dir}/{self.ITEMS}/, or remove it",
+            )
+
+        items = f"{feature_dir}/{self.ITEMS}"
+        for entry in sorted(self._under(items, given)):
+            name = entry.rsplit("/", 1)[-1]
+            if name == self.IGNORED:
+                continue
+            match = self.ITEM_FILE.match(name)
+            if not match:
+                yield self.report(
+                    entry,
+                    "backlog item must be named az<work item id>-<kebab-slug>.md",
+                    f"rename {entry} to az<id>-<slug>.md, using the id of the "
+                    "work item it describes",
+                )
+                continue
+            yield from self._check_item(ctx, entry, int(match.group(1)), feature_id)
+
+    # ------------------------------------------------------------- frontmatter
+
+    @staticmethod
+    def _field(body: str, pattern: re.Pattern[str]) -> str | None:
+        return PlanMetadata.field(body, pattern)
+
+    def _work_item_id(self, body: str) -> tuple[int | None, str | None]:
+        """The id in `work_item:`, and why it could not be read."""
+        return PlanMetadata.work_item_id(body)
+
+    def _common(self, ctx: Context, path: str, body: str, expected_id: int) -> Iterator[Finding]:
+        """The frontmatter every document in this tree carries."""
+        if self._field(body, self.TITLE_LINE) is None:
+            yield self.report(path, "missing title", f"add `title:` to {path}")
+
+        status = self._field(body, self.STATUS_LINE)
+        if status is None:
+            yield self.report(
+                path,
+                "missing status",
+                f"add `status:` to {path}, one of: {', '.join(self.STATUSES)}",
+            )
+        elif status not in self.STATUSES:
+            yield self.report(
+                path,
+                f"status {status!r} is not a work item state",
+                f"set status in {path} to one of: {', '.join(self.STATUSES)}; "
+                "it mirrors the board, not a document lifecycle",
+            )
+
+        modified = self._field(body, self.MODIFIED_LINE)
+        if modified is None:
+            yield self.report(
+                path, "missing last_update", f"add `last_update:` to {path}"
+            )
+        elif not self.ISO_8601.match(modified):
+            yield self.report(
+                path,
+                f"last_update {modified!r} is not ISO-8601 UTC",
+                f"set last_update in {path} to YYYY-MM-DDTHH:MM:SSZ",
+            )
+
+        found_id, why = self._work_item_id(body)
+        if why == "missing":
+            yield self.report(
+                path,
+                "missing work_item link",
+                f"add `work_item:` to {path} as the full board URL "
+                f"(.../_workitems/edit/{expected_id})",
+            )
+        elif why:
+            yield self.report(
+                path,
+                "work_item must be a board URL, not a bare id",
+                f"set work_item in {path} to "
+                f"https://dev.azure.com/<org>/<project>/_workitems/edit/{expected_id}",
+            )
+        elif found_id != expected_id:
+            yield self.report(
+                path,
+                f"work_item {found_id} disagrees with az{expected_id}",
+                f"point work_item at {expected_id} in {path}, or rename to "
+                f"az{found_id}",
+            )
+
+    def _check_spec(self, ctx: Context, spec: str, feature_id: int) -> Iterator[Finding]:
+        body = self.text(ctx, spec) or ""
+        yield from self._common(ctx, spec, body, feature_id)
+
+        declared = self._field(body, self.TYPE_LINE)
+        if declared != self.FEATURE_TYPE:
+            yield self.report(
+                spec,
+                f"type must be {self.FEATURE_TYPE!r} (got {declared!r})",
+                f"set `type: {self.FEATURE_TYPE}` in {spec}",
+            )
+
+        epic = self._field(body, self.EPIC_LINE)
+        if epic is None:
+            yield self.report(
+                spec,
+                "spec.md must name the Epic its Feature hangs under",
+                f"add `epic:` to {spec} as the board URL; it is authored, never "
+                "tool-created, so a wrong id fails loudly at parenting time",
+            )
+        elif not self.WORK_ITEM_URL.match(epic):
+            yield self.report(
+                spec,
+                "epic must be a board URL, not a bare id",
+                f"set epic in {spec} to https://dev.azure.com/.../_workitems/edit/<id>",
+            )
+
+        if not any(self.SOURCES_LINE.match(line) for line in body.splitlines()):
+            yield self.report(
+                spec,
+                "spec.md must link the documents it derives from",
+                f"add a `sources:` list to {spec} pointing at the docs/ pages "
+                "behind it; a spec with none cannot have its reasoning retraced",
+            )
+
+    def _check_item(
+        self, ctx: Context, item: str, item_id: int, feature_id: int
+    ) -> Iterator[Finding]:
+        body = self.text(ctx, item) or ""
+        yield from self._common(ctx, item, body, item_id)
+
+        declared = self._field(body, self.TYPE_LINE)
+        if declared is None:
+            yield self.report(
+                item,
+                "missing type",
+                f"add `type: pbi` or `type: bug` to {item}",
+            )
+        elif declared not in self.ITEM_TYPES:
+            yield self.report(
+                item,
+                f"type {declared!r} is not pbi or bug",
+                f"set type in {item} to pbi (Product Backlog Item) or bug",
+            )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/AGENTS.md

@@ -0,0 +1 @@
+# Plans

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/features/az347-test-coverage/items/az351-restore-entrypoint.md

@@ -0,0 +1,9 @@
+---
+type: bug
+title: "Restore the entrypoint"
+status: Committed
+work_item: https://dev.azure.com/org/proj/_workitems/edit/351
+last_update: 2026-09-15T03:20:00Z
+---
+
+# Restore the entrypoint

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/features/az347-test-coverage/spec.md

@@ -0,0 +1,12 @@
+---
+type: feature
+title: "Test coverage"
+status: New
+epic: https://dev.azure.com/org/proj/_workitems/edit/320
+work_item: https://dev.azure.com/org/proj/_workitems/edit/347
+last_update: 2026-09-15T03:20:00Z
+sources:
+  - docs/architecture/workflow-automation.md
+---
+
+# Test coverage

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/templates/feature.md

@@ -0,0 +1 @@
+# Feature template

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-violation/plans/features/az347-test-coverage/items/az351-restore-entrypoint.md

@@ -0,0 +1,9 @@
+---
+type: chore
+title: "Restore the entrypoint"
+status: New
+work_item: https://dev.azure.com/org/proj/_workitems/edit/352
+last_update: 2026-09-15T03:20:00Z
+---
+
+# Restore the entrypoint

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-violation/plans/features/az347-test-coverage/spec.md

@@ -0,0 +1,12 @@
+---
+type: feature
+title: "Test coverage"
+status: New
+epic: https://dev.azure.com/org/proj/_workitems/edit/320
+work_item: https://dev.azure.com/org/proj/_workitems/edit/999
+last_update: 2026-09-15T03:20:00Z
+sources:
+  - docs/architecture/workflow-automation.md
+---
+
+# Test coverage