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

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

@@ -0,0 +1,387 @@
+"""DOC-009 — the Markdown plan-event ledger at `plans/LEDGER.md`.
+
+The ledger is a single Markdown table, the shape the estate already writes in
+`plans/GAPS-AND-FINDINGS.md`:
+
+    # Ledger
+
+    | Date | Id | Area | Event | Refs |
+    | --- | --- | --- | --- | --- |
+    | 2026-09-15 | plans-tree-rebuilt | plans | Board owns state now | `plans/AGENTS.md` |
+
+INVERTED 2026-09-17 (owner ruling, recorded in `plans/GAPS-AND-FINDINGS.md`):
+this gate REQUIRED `plans/LEDGER.yaml` and reported any `plans/LEDGER.md` as a
+finding ("hard-cut Markdown ledger must be removed"), while LAY-006
+(`layout.markdown-trees`) listed `*/LEDGER.md` as an allowed markdown root. One
+concept, two formats, two gates ruling opposite ways. Markdown wins — the
+estate has ast-grep markdown tooling to scan it — so both halves reverse: the
+required document is now the Markdown table, and a leftover `LEDGER.yaml` is
+the transitional finding.
+
+Every assertion the YAML form made is still made, read off table cells instead
+of mapping keys: kebab-case `id` and its uniqueness, an ISO `date` that is a
+real calendar day, is not in the future, and descends newest-first, a non-empty
+`area`, a non-empty `event` no longer than `EVENT_LIMIT`, and `refs` that are
+repository-relative paths which exist. Two mechanisms did not survive the
+format change and are recorded here rather than dropped quietly:
+
+  * `schema_version: 1` has no Markdown carrier. A version key in a table
+    column would be repeated per row and mean nothing; its job — "this is a
+    ledger and it is the shape I know" — is done by the header row, which must
+    read exactly `| Date | Id | Area | Event | Refs |`. A document whose header
+    does not match is not recognised as a ledger, which is the same refusal.
+  * `yaml.YAMLError` -> `CouldNotRun` has no analogue: Markdown always parses.
+    The broken-shape role it carried passes to a data row whose cell count does
+    not match the header, which raises `CouldNotRun` for the same reason the
+    YAML version did for a non-mapping entry — a broken document, not a graded
+    finding about its content.
+
+Shape is `structural`: the ledger is a single NAMED PATH this gate opens
+directly, never a member of the given set — those rules read ONE registered
+artifact, not a file set.
+
+FRESHNESS 2026-09-27 (owner ruling, gap `DOC-009 grades the ledger's shape
+but never its freshness`, `plans/GAPS-AND-FINDINGS.md`): shape alone let a
+ledger nobody had appended to in months pass every run, because nothing
+asserted that a change to `plans/` brought a ledger entry with it. `graded`
+now carries that half, reading the GIVEN SET the same way `docs.index-
+updated` (DOC-004) does for a collection's catalog: `files` arrives already
+narrowed to this row's `engine.scope` (`<plans>/*.md`, `<plans>/**/*.md`,
+plus the `<docs>` patterns and the legacy `LEDGER.yaml` entry), so this rule
+narrows further to paths under the plans root and drops the ledger and its
+retired YAML form — touching either is a fact ABOUT the ledger, not a plan
+that needs one. Any plan left over is a trigger; the ledger itself must also
+be in the given set, or the plan changed with no ledger entry in the same
+change. A whole-tree run with no real change set intersects to an empty
+`FileSet` under `exhaustive=True` and is refused by the runner before this
+check ever executes (`runner.applicable_files`) — a could-not-run, never a
+silent "nothing to flag" pass.
+
+check.sh's own `ADL_CHANGED_FILES`-unset probe (exit 2 "run this through
+run.sh, not by hand") has no analogue: `Check.run(ctx, files)` always receives a
+`FileSet` argument, so there is no "unset" state to test (K-18). The nearest
+faithful equivalent — the caller declaring an exhaustive, empty set — is
+exercised in `test_check.py`, the same substitution `DOC-006`'s test makes.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from datetime import date
+from typing import ClassVar
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun
+from ....core.finding import Report
+
+
+class DocsLedger(Check):
+    id: ClassVar[str] = "DOC-009"
+    rule: ClassVar[str] = "KNW-002"
+
+    inputs: ClassVar[dict[str, str]] = {"plans_root": "<plans>"}
+    """FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): the ledger paths
+    were hardcoded `plans/...` literals, opened as NAMED paths. A repository
+    whose plans root is not the packaged default had its real ledger fail that
+    open, and this gate reported "required ledger is missing" -- a visible,
+    wrong finding, not a silent pass. `LEDGER.md`/`LEDGER.yaml` stay literal
+    below the resolved root: the settled document name, not a resolvable
+    path."""
+
+    def _ledger(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['plans_root'])}/LEDGER.md"
+
+    def _legacy_yaml(self, ctx: Context) -> str:
+        return f"{ctx.relative(ctx.inputs['plans_root'])}/LEDGER.yaml"
+
+    ID_KEBAB: ClassVar[re.Pattern[str]] = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+    ISO_DATE: ClassVar[re.Pattern[str]] = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$")
+    URI_SCHEME: ClassVar[re.Pattern[str]] = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*://")
+
+    EVENT_LIMIT: ClassVar[int] = 99
+
+    #: The header this gate recognises, lowercased. A document without it is
+    #: not a ledger -- the Markdown carrier of the old `schema_version: 1`.
+    COLUMNS: ClassVar[tuple[str, ...]] = ("date", "id", "area", "event", "refs")
+
+    #: The same row as an author writes it, for every `fix` line below.
+    HEADER: ClassVar[str] = "| Date | Id | Area | Event | Refs |"
+
+    #: A `|` that is not backslash-escaped ends a cell, so an event may carry a
+    #: literal pipe as `\|` without shifting every column after it.
+    CELL_SPLIT: ClassVar[re.Pattern[str]] = re.compile(r"(?<!\\)\|")
+
+    DELIMITER_CELL: ClassVar[re.Pattern[str]] = re.compile(r"^:?-{3,}:?$")
+
+    #: Refs are written as inline code, the `_join_code` convention the crate
+    #: map renderer already uses -- including its em dash for "none".
+    REF_CODE: ClassVar[re.Pattern[str]] = re.compile(r"^`([^`]*)`$")
+    NO_REFS: ClassVar[str] = "—"
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        ledger = self._ledger(ctx)
+        legacy_yaml = self._legacy_yaml(ctx)
+        if ctx.path(legacy_yaml).is_file():
+            yield self.report(
+                legacy_yaml,
+                "superseded YAML ledger must be removed",
+                f"move the entries of {legacy_yaml} into the {ledger} table and "
+                f"delete it; the ledger is Markdown now",
+            )
+
+        body = self.text(ctx, ledger)
+        if body is None:
+            yield self.report(
+                ledger, "required ledger is missing",
+                f"create {ledger} with a '{self.HEADER}' table holding at least one row",
+            )
+            return
+
+        rows = self._rows(ledger, body)
+        if not rows:
+            yield self.report(
+                ledger,
+                f"the ledger must hold a '{self.HEADER}' table with at least one entry",
+                f"add the '{self.HEADER}' header, its '| --- |' delimiter row and at "
+                f"least one entry row to {ledger}",
+            )
+            return
+
+        yield from self._grade_rows(ctx, ledger, rows)
+
+    # ----------------------------------------------------------------- freshness
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        """A plan that changes must bring a ledger entry with it.
+
+        `files` is already narrowed to `engine.scope` by the runner, so every
+        path here is a plans/docs markdown change (or the legacy YAML ledger)
+        that was actually part of THIS given set. Narrow further to the plans
+        root, drop the ledger and its retired YAML form -- changing either is
+        a fact about the ledger, not a plan needing one -- and whatever is
+        left is a plan that moved without the ledger moving with it, unless
+        the ledger is ALSO in the given set (the same "moving in the same
+        set" proof `docs.index-updated` (DOC-004) uses for a catalog).
+        """
+        ledger = self._ledger(ctx)
+        legacy_yaml = self._legacy_yaml(ctx)
+        plans_root = ctx.relative(ctx.inputs["plans_root"])
+        prefix = plans_root + "/"
+
+        given = set(files)
+        if ledger in given:
+            return
+
+        triggers = sorted(
+            path
+            for path in given
+            if path.startswith(prefix) and path not in (ledger, legacy_yaml)
+        )
+        for path in triggers:
+            yield self.report(
+                path,
+                f"plan changed without a {ledger} entry",
+                f"add an entry for {path} to {ledger} in this same change",
+            )
+
+    # -------------------------------------------------------------- table shape
+
+    @classmethod
+    def _rows(cls, ledger: str, body: str) -> list[tuple[int, list[str]]]:
+        """The ledger table's data rows, each with its 1-based line number.
+
+        Empty when the document holds no recognisable ledger table at all --
+        no matching header, or a header the `| --- |` delimiter does not
+        follow. Both are the same refusal and the caller reports them as one.
+        """
+        lines = body.splitlines()
+        for index, line in enumerate(lines):
+            header = cls._cells(line)
+            if header is None or tuple(cell.lower() for cell in header) != cls.COLUMNS:
+                continue
+
+            delimiter = cls._cells(lines[index + 1]) if index + 1 < len(lines) else None
+            if delimiter is None or not all(
+                cls.DELIMITER_CELL.match(cell) for cell in delimiter
+            ):
+                return []
+
+            rows: list[tuple[int, list[str]]] = []
+            for number, rest in enumerate(lines[index + 2 :], start=index + 3):
+                cells = cls._cells(rest)
+                if cells is None:
+                    break
+                if len(cells) != len(cls.COLUMNS):
+                    # The Markdown analogue of a YAML entry that is not a
+                    # mapping: `.value.id` has nothing to index. A broken
+                    # document shape, not a graded finding about its content.
+                    raise CouldNotRun(
+                        f"{ledger}:{number}: row has {len(cells)} cells, not the "
+                        f"{len(cls.COLUMNS)} the header declares"
+                    )
+                rows.append((number, cells))
+            return rows
+        return []
+
+    @classmethod
+    def _cells(cls, line: str) -> list[str] | None:
+        """A table row's cells, stripped, or None when the line is not a row."""
+        stripped = line.strip()
+        if len(stripped) < 2 or not stripped.startswith("|") or not stripped.endswith("|"):
+            return None
+        return [
+            cell.replace("\\|", "|").strip()
+            for cell in cls.CELL_SPLIT.split(stripped)[1:-1]
+        ]
+
+    # ------------------------------------------------------------------ grading
+
+    def _grade_rows(
+        self, ctx: Context, ledger: str, rows: list[tuple[int, list[str]]]
+    ) -> Iterable[Report]:
+        seen: set[str] = set()
+        previous: str | None = None
+        today = date.today().isoformat()
+
+        for ordinal, (line, cells) in enumerate(rows, start=1):
+            label = f"row[{ordinal}]"
+            entry_date, entry_id, area, event, refs = cells
+
+            if not self.ID_KEBAB.match(entry_id):
+                yield self.report(
+                    ledger, f"{label}.id: must be lower-kebab-case",
+                    f"rewrite {label}.id to lower-kebab-case (e.g. my-entry-id)",
+                    line=line,
+                )
+            if entry_id in seen:
+                yield self.report(
+                    ledger, f"{label}.id: duplicate ID {entry_id}",
+                    f"give {label} a unique id ({entry_id} is already used by an earlier row)",
+                    line=line,
+                )
+            else:
+                seen.add(entry_id)
+
+            if not self._valid_date(entry_date):
+                yield self.report(
+                    ledger, f"{label}.date: must be YYYY-MM-DD",
+                    f"set {label}.date to YYYY-MM-DD format",
+                    line=line,
+                )
+            else:
+                if entry_date > today:
+                    yield self.report(
+                        ledger, f"{label}.date: cannot be in the future",
+                        f"set {label}.date to today ({today}) or earlier",
+                        line=line,
+                    )
+                if previous is not None and entry_date > previous:
+                    yield self.report(
+                        ledger, f"{label}: rows must be newest-first",
+                        f"reorder {label} so dates descend newest-first",
+                        line=line,
+                    )
+                previous = entry_date
+
+            if not area:
+                yield self.report(
+                    ledger, f"{label}.area: must be a non-empty string",
+                    f"set a non-empty {label}.area",
+                    line=line,
+                )
+
+            if not event:
+                yield self.report(
+                    ledger, f"{label}.event: must be a non-empty string",
+                    f"set a non-empty {label}.event",
+                    line=line,
+                )
+            if len(event) > self.EVENT_LIMIT:
+                yield self.report(
+                    ledger,
+                    f"{label}.event: must be at most {self.EVENT_LIMIT} characters",
+                    f"shorten {label}.event to {self.EVENT_LIMIT} characters or fewer",
+                    line=line,
+                )
+
+            yield from self._grade_refs(ctx, ledger, label, line, refs)
+
+    def _grade_refs(
+        self, ctx: Context, ledger: str, label: str, line: int, cell: str
+    ) -> Iterable[Report]:
+        """The refs cell: a comma-separated list of `backticked` paths.
+
+        An empty cell, or the em dash the estate writes for an empty list, is
+        the Markdown spelling of `refs: []` -- a list with nothing in it, which
+        the YAML form accepted too.
+        """
+        if not cell or cell == self.NO_REFS:
+            return
+
+        for piece in cell.split(","):
+            written = piece.strip()
+            if not written:
+                yield self.report(
+                    ledger, f"{label}.refs: references must be non-empty strings",
+                    f"remove or fill in the empty ref in {label}.refs",
+                    line=line,
+                )
+                continue
+
+            quoted = self.REF_CODE.match(written)
+            if quoted is None:
+                yield self.report(
+                    ledger,
+                    f"{label}.refs: each reference must be inline code: {written}",
+                    f"write the ref '{written}' in {label}.refs as `{written}`, and "
+                    f"separate refs with commas",
+                    line=line,
+                )
+                continue
+
+            ref = quoted.group(1).strip()
+            if not ref:
+                yield self.report(
+                    ledger, f"{label}.refs: references must be non-empty strings",
+                    f"remove or fill in the empty ref in {label}.refs",
+                    line=line,
+                )
+                continue
+
+            path = ref.split("#", 1)[0]
+            if (
+                path.startswith("/")
+                or self.URI_SCHEME.match(path)
+                or path == "."
+                or path.startswith("./")
+            ):
+                yield self.report(
+                    ledger,
+                    f"{label}.refs: reference must be repository-relative: {ref}",
+                    f"rewrite the ref '{ref}' in {label}.refs to a repository-relative path",
+                    line=line,
+                )
+            elif not ctx.path(path).exists():
+                yield self.report(
+                    ledger,
+                    f"{label}.refs: missing or case-mismatched path: {ref}",
+                    f"fix the path or case of '{ref}' in {label}.refs so it matches a real "
+                    "repository path",
+                    line=line,
+                )
+
+    @classmethod
+    def _valid_date(cls, value: str) -> bool:
+        """check.sh's `valid_date`: format, then real Gregorian calendar
+        bounds (Python's `date()` constructor already enforces the same
+        month/day/leap-year rule the shell function hand-rolled)."""
+        if not cls.ISO_DATE.match(value):
+            return False
+        year, month, day = int(value[0:4]), int(value[5:7]), int(value[8:10])
+        try:
+            date(year, month, day)
+        except ValueError:
+            return False
+        return True

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/ledger/fixtures/ledger-bad-date/plans/LEDGER.md

@@ -0,0 +1,5 @@
+# Ledger
+
+| Date | Id | Area | Event | Refs |
+| --- | --- | --- | --- | --- |
+| 2026-02-30 | not-a-real-calendar-day | docs | an entry whose date is well-formed but not a real day | — |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/ledger/fixtures/ledger-clean/plans/LEDGER.md

@@ -0,0 +1,6 @@
+# Ledger
+
+| Date | Id | Area | Event | Refs |
+| --- | --- | --- | --- | --- |
+| 2026-01-02 | seed-ledger-fixture | docs | seed a clean ledger fixture for docs.ledger | `plans/LEDGER.md` |
+| 2026-01-01 | ledger-became-markdown | docs | the plan-event ledger is a Markdown table now, not YAML | — |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/ledger/fixtures/ledger-empty-table/plans/LEDGER.md

@@ -0,0 +1,4 @@
+# Ledger
+
+| Date | Id | Area | Event | Refs |
+| --- | --- | --- | --- | --- |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/ledger/fixtures/ledger-long-event/plans/LEDGER.md

@@ -0,0 +1,5 @@
+# Ledger
+
+| Date | Id | Area | Event | Refs |
+| --- | --- | --- | --- | --- |
+| 2026-01-01 | over-long-event | docs | an entry whose event text runs well past the ninety-nine character limit this gate has always enforced | — |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/ledger/fixtures/ledger-violation/plans/LEDGER.md

@@ -0,0 +1,5 @@
+# Ledger
+
+| Date | Id | Area | Event | Refs |
+| --- | --- | --- | --- | --- |
+| 2026-01-01 | Not-Kebab-Case | docs | an entry whose id is not lower-kebab-case | — |