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

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/architecture/product/stable-recommendation.md

@@ -0,0 +1,12 @@
+---
+title: "Stable recommendation"
+description: "Why a stable page still recommends"
+document_type: architecture
+status: stable
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+## Recommendation
+
+Pick one.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/architecture/product/target-narration.md

@@ -0,0 +1,10 @@
+---
+title: "Target narration"
+description: "Why the boundary page narrates delivery"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---
+
+This boundary is not yet implemented.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/architecture/team/team-overview.md

@@ -0,0 +1,8 @@
+---
+title: "Team overview"
+description: "How the team boundary is drawn"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/compliance/controls/control-matrix.md

@@ -0,0 +1,8 @@
+---
+title: "Control matrix"
+description: "How controls are recorded"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/compliance/controls/control-matrix.yaml

@@ -0,0 +1,17 @@
+controls:
+  - id: EC-A.5.36
+    owner: platform
+    risk: low
+    status: met
+    evidence: control-matrix.md
+    gap: none
+    remediation_link: control-matrix.md
+  - id: EC-A.5.37
+    owner: platform
+    risk: low
+    review_frequency: annual
+    retention: 7y
+    status: met
+    evidence: control-matrix.md
+    gap: none
+    remediation_link: control-matrix.md

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/semantics/fixtures/semantics-violations/docs/research/benchmarks/bad-research.md

@@ -0,0 +1,8 @@
+---
+title: "Bad research"
+description: "Why this research note states nothing"
+document_type: architecture
+status: draft
+last_update: "2026-07-27T00:00:00Z"
+reason: "fixture"
+---

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

@@ -0,0 +1,461 @@
+"""DOC-007 — ported from `compliance_new/checks/docs/semantics/test.sh`.
+
+Two corpora, copied byte-for-byte from the shell tree's committed fixtures
+(`semantics-clean`, `semantics-violations`): one conforming page per branch the
+violations corpus breaks, and eleven separately-defective pages/records.
+
+test.sh's final scenario -- no `ADL_CHANGED_FILES` set, exit 2 -- has no
+Python analogue: `Check.run(ctx, files)` always receives a `FileSet` (K-18), so
+there is no "unset" state to construct. `test_no_set_is_could_not_run` below is
+the same substitution `DOC-006`/`DOC-009`'s tests already make for the
+identical shell contract: the caller declares its set exhaustive, and the
+row's own `engine.scope` matches nothing in an empty set.
+
+test.sh's closing `dispatch_contract DOC-007 pr_validation` proves only that
+the row is well-formed and wired to a profile -- registry-shape and
+profile-wiring assertions belong to `tests/core/test_registry.py`, not to a
+single gate's test module (no other ported check re-asserts it either).
+"""
+
+from __future__ import annotations
+
+import pytest
+from helpers import corpus, corpus_files
+
+from adl_compliance import runner
+from adl_compliance.checks.docs.semantics import DocsSemantics
+from adl_compliance.core.verdict import Outcome
+from adl_compliance.policy.registry import load
+
+CORPORA = corpus("docs", "semantics")
+ROW = load().by_id("DOC-007")
+
+
+@pytest.fixture(autouse=True)
+def _wired(monkeypatch: pytest.MonkeyPatch) -> None:
+    # DOC-007 is not yet in `checks/__init__.py`'s CHECKS tuple -- a later step
+    # wires this wave of checks into the registry in one shot, to avoid
+    # concurrent edits to that shared file. Until then `runner.lookup` cannot
+    # find this row, so its one lookup call is patched to resolve DOC-007 to
+    # this module's class -- everything else (scope intersection, the
+    # structural/graded split, the verdict decision) runs for real.
+    monkeypatch.setattr(runner, "lookup", lambda gate_id: DocsSemantics)
+
+
+def run(case: str, *, given: tuple[str, ...] | None = None) -> object:
+    root = CORPORA / case
+    files = corpus_files(root) if given is None else given
+    return runner.run(ROW, root, files)
+
+
+def test_a_redeclared_docs_tree_is_still_graded(tmp_path) -> None:
+    """The SILENT false pass this check shipped with.
+
+    `CONTENT = "docs"` filtered the given set with a bare `startswith`. A
+    repository declaring `docs = "documentation"` had every real page's path
+    fail `path.startswith("docs/architecture/")` (real paths read
+    `documentation/architecture/...`) — the filter dropped every page before
+    grading, and the gate reported clean having graded nothing. No error, no
+    could-not-run: a green light meaning nothing, and it was ARMED in exactly
+    that state on enact-m5 and enact-repo-controls-m5 (both happen to declare
+    `docs = "docs"`, so the literal was accidentally correct there).
+
+    A real stable architecture page under the redeclared tree, carrying
+    genuine delivery-status prose (`IMPLEMENTATION_STATUS`'s own "is shipped"
+    clause) — ungraded before the fix, caught after."""
+    from adl_compliance.core.context import Context, FileSet
+
+    page = tmp_path / "documentation" / "architecture" / "example.md"
+    page.parent.mkdir(parents=True)
+    page.write_text(
+        "---\n"
+        "title: Example\n"
+        "description: An architecture page under a redeclared docs tree.\n"
+        "status: stable\n"
+        "last_update: '2026-09-15T00:00:00Z'\n"
+        "---\n\n"
+        "# Example\n\n"
+        "This feature is now shipped to every desktop user.\n",
+        encoding="utf-8",
+    )
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": tmp_path / "documentation"})
+    reported = tuple(
+        DocsSemantics().run(ctx, FileSet(paths=("documentation/architecture/example.md",)))
+    )
+    assert any(
+        "stable architecture cannot carry delivery or implementation status" in r.message
+        for r in reported
+    ), f"a genuine delivery-status page under a redeclared docs tree went ungraded: {reported}"
+
+
+def test_conforming_published_pages_are_silent() -> None:
+    """Asserted first. Without it, every assertion below also passes against a
+    check that reports every page it reads."""
+    verdict = run("semantics-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_every_defect_in_the_violations_corpus_is_reported() -> None:
+    """Every page in the corpus is wrong in exactly one way, or not at all."""
+    verdict = run("semantics-violations")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert len(verdict.findings) == 11, verdict.render()
+
+
+def test_architecture_target_delivery_narration_is_reported() -> None:
+    verdict = run("semantics-violations")
+    assert any(
+        f.path == "docs/architecture/product/target-narration.md"
+        and "architecture target cannot carry delivery-status narration" in f.message
+        for f in verdict.findings
+    ), verdict.render()
+
+
+def test_stable_unresolved_recommendation_is_reported() -> None:
+    verdict = run("semantics-violations")
+    assert any(
+        f.path == "docs/architecture/product/stable-recommendation.md"
+        and f.message == "stable architecture cannot contain unresolved recommendation language"
+        for f in verdict.findings
+    ), verdict.render()
+
+
+def test_stable_delivery_status_is_reported() -> None:
+    verdict = run("semantics-violations")
+    assert any(
+        f.path == "docs/architecture/product/stable-delivery.md"
+        and f.message == "stable architecture cannot carry delivery or implementation status"
+        for f in verdict.findings
+    ), verdict.render()
+
+
+@pytest.mark.parametrize(
+    "message",
+    [
+        "research must state question",
+        "research must state method",
+        "research must state evidence",
+        "research must state limits",
+    ],
+)
+def test_bad_research_is_missing_all_four_sections(message: str) -> None:
+    verdict = run("semantics-violations")
+    assert any(
+        f.path == "docs/research/benchmarks/bad-research.md" and f.message == message
+        for f in verdict.findings
+    ), verdict.render()
+
+
+def test_control_matrix_page_missing_review_and_retention() -> None:
+    verdict = run("semantics-violations")
+    messages = {f.message for f in verdict.findings if f.path == "docs/compliance/controls/control-matrix.md"}
+    assert "compliance matrix must state review frequency" in messages, verdict.render()
+    assert "compliance matrix must state evidence retention" in messages, verdict.render()
+
+
+def test_control_record_one_is_missing_two_fields() -> None:
+    """The YAML record pass is a different reader from the Markdown pass
+    above: it walks `- id:` entries and names the record by index."""
+    verdict = run("semantics-violations")
+    messages = {
+        f.message for f in verdict.findings
+        if f.path == "docs/compliance/controls/control-matrix.yaml"
+    }
+    assert "control record 1 missing review_frequency" in messages, verdict.render()
+    assert "control record 1 missing retention" in messages, verdict.render()
+
+
+def test_the_complete_second_control_record_is_not_reported() -> None:
+    """Without this, the two assertions above also pass against a gate that
+    reports every record it reads."""
+    verdict = run("semantics-violations")
+    assert not any(
+        f.path == "docs/compliance/controls/control-matrix.yaml" and "record 2 missing" in f.message
+        for f in verdict.findings
+    ), verdict.render()
+
+
+def test_no_second_level_category_is_ever_reported() -> None:
+    """The governed-category list is gone, so NO subdivision under a collection is
+    reportable — not `team`/`backend` (which the old hardcoded list happened to
+    allow) and not `agents`/`channels`/`sandbox` (which it happened to reject).
+
+    The list was one repository's taxonomy written inside the package: pointed at
+    the next repository it shared no category at all, and produced fourteen findings
+    that read as "your architecture tree is wrong" while meaning "your tree is not
+    the tree this list was written against". What is standard is the COLLECTION,
+    declared once in docs-okf-profiles.yaml; how a repository subdivides inside one
+    is its own business, and a register of permitted subdivisions would only have
+    moved the hardcoding into YAML."""
+    verdict = run("semantics-violations")
+    assert not any("second-level category" in f.message for f in verdict.findings), verdict.render()
+
+
+def test_reported_paths_all_resolve_inside_the_corpus() -> None:
+    """A gate that resolved a repository root instead of reading the directory
+    it was pointed at would name this checkout's own (DOC-007-dirty) docs/
+    pages here."""
+    verdict = run("semantics-violations")
+    root = CORPORA / "semantics-violations"
+    for f in verdict.findings:
+        assert (root / f.path).is_file(), f"{f.path} is not in the corpus\n{verdict.render()}"
+
+
+def test_a_page_outside_the_given_set_is_not_graded() -> None:
+    """Moved from test-documentation-staged-scope.sh's property: a file the
+    gate was not given is not graded, however wrong it is on disk. The
+    violations corpus is untouched and all eleven defects are still there; the
+    given set names one clean page, so there is nothing to report."""
+    verdict = run(
+        "semantics-violations", given=("docs/architecture/team/team-overview.md",),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_no_set_is_could_not_run() -> None:
+    verdict = runner.run(ROW, CORPORA / "semantics-violations", (), exhaustive=True)
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+
+
+def test_an_absent_docs_root_is_a_finding_not_a_pass() -> None:
+    """An absent directory yields an empty set, and an empty set is a clean
+    pass everywhere else in this estate. Without this structural probe the
+    tree losing docs/ entirely would pass in silence."""
+    verdict = runner.run(ROW, corpus("coverage", "baseline") / "passing", given=())
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert "docs content root is missing" in verdict.render()
+
+
+def test_evidence_asset_names_and_captions_grade_beyond_the_committed_corpora() -> None:
+    """`_grade_assets`/`_grade_evidence_captions` are exercised by no committed
+    fixture -- neither corpus commits a research asset or the evidence-caption
+    file -- so this asserts the check runs to completion on a real page set
+    without them present, rather than skipping the branches untested."""
+    root = CORPORA / "semantics-clean"
+    verdict = runner.run(ROW, root, corpus_files(root))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_code_spans_and_fences_are_not_prose(tmp_path: pathlib.Path) -> None:
+    """These rules grade what a page SAYS. A code span is the page quoting a path or a
+    command, not claiming anything about delivery — and `IMPLEMENTATION_STATUS` matched
+    the filename inside `backend/shipped-runtime-imports.test.ts`, and "implemented"
+    inside `agent-loop/v1`, and told the page to move narration it did not contain.
+
+    Six of nine findings against enact-m5 were regex hits rather than statements; this
+    closes the two that were unambiguously code."""
+    from adl_compliance.checks.docs.semantics.check import DocsSemantics
+
+    # inline span: the only occurrence is inside backticks
+    assert not DocsSemantics.IMPLEMENTATION_STATUS.search(
+        DocsSemantics._prose("`backend/shipped-runtime-imports.test.ts` guards the other half").lower()
+    )
+    # ...and the same words outside a span are still caught
+    assert DocsSemantics.IMPLEMENTATION_STATUS.search(
+        DocsSemantics._prose("the coverage ratchet shipped last week").lower()
+    )
+
+
+# --------------------------------------------- "built" is a construction verb
+#
+# Measured, not assumed: every occurrence of `(is|are|was|were|has been|have
+# been) built` across BOTH repositories' docs and plans trees -- 11 of them --
+# is constructional, and not one is a delivery claim:
+#
+#   "the sandbox image is built for `linux/amd64`"   build target
+#   "how a sandbox is built and mounted"             mechanism
+#   "the next turn is built from the channel's posts" data flow
+#   "the in-process servers are built lazily"        mechanism
+#   "was built first and did not ..."                ordering
+#
+# The genuine delivery sense keeps its own clause: `(now|already|currently)
+# built` still fires, as do `not yet built`, `not built` and `unbuilt`. So this
+# narrowing removes false positives without giving up a real signal.
+
+CONSTRUCTIONAL = [
+    "The sandbox image is built for `linux/amd64` and pushed to the registry.",
+    "This section covers how a sandbox is built and mounted.",
+    "The next turn is built from the channel's posts.",
+    "The in-process servers are built lazily in the async getter.",
+    "The engine adapter was built first and did not need the durable path.",
+]
+
+DELIVERY = [
+    "The executor is now built and running in production.",
+    "Fixed workflow execution is not yet built.",
+    "The scheduler is currently built and deployed.",
+    "That path is unbuilt.",
+]
+
+
+def test_constructional_built_is_not_delivery_status() -> None:
+    for sentence in CONSTRUCTIONAL:
+        assert not DocsSemantics.IMPLEMENTATION_STATUS.search(sentence.lower()), sentence
+
+
+def test_genuine_built_delivery_claims_still_fire() -> None:
+    for sentence in DELIVERY:
+        assert DocsSemantics.IMPLEMENTATION_STATUS.search(sentence.lower()), sentence
+
+
+# ------------------------------- "not implemented BY <means>" is not a status
+#
+# Same method. All three occurrences in the corpus are means-of-achievement or
+# a rule's subject, never "this is not done yet":
+#
+#   "they are not implemented by provisioning another sandbox"
+#   "a reference copy ..., not wired into this repository's own pipeline"
+#   "an agent surface config not wired to the shared `.mjs` guard"
+
+MEANS = [
+    "Those are additional Task-executor shapes; they are not implemented by provisioning another sandbox.",
+    "It is a reference copy from enact-m5, not wired into this repository's own pipeline.",
+    "An agent surface config not wired to the shared guard is the subject of that rule.",
+]
+
+
+def test_not_implemented_by_a_means_is_not_delivery_status() -> None:
+    for sentence in MEANS:
+        assert not DocsSemantics.IMPLEMENTATION_STATUS.search(sentence.lower()), sentence
+
+
+def test_a_bare_not_implemented_claim_still_fires() -> None:
+    for sentence in [
+        "The fixed workflow executor is not implemented.",
+        "Retry handling is not implemented, and the gap is tracked separately.",
+        "That surface is not wired.",
+    ]:
+        assert DocsSemantics.IMPLEMENTATION_STATUS.search(sentence.lower()), sentence
+
+
+# ---------------------------------------- the registers/assets, off docs_root
+#
+# GAP_REGISTER / CONTROL_MATRIX / ASSETS_DIR / EVIDENCE_FILE were hardcoded
+# `docs/...` literals -- the same SILENT shape CONTENT had, just four more
+# doors down. None of these four documents exists in any repository in this
+# estate, so each was already a silent no-op on every armed run; a repository
+# that DID commit one, under a redeclared docs tree, would have it go
+# ungraded with no error and no could-not-run. Each test below builds the
+# real document under a redeclared root and proves the specific defect that
+# document's sub-check exists to catch still fires.
+
+
+def test_a_redeclared_docs_tree_still_grades_the_gap_register(tmp_path) -> None:
+    from adl_compliance.core.context import Context, FileSet
+
+    docs_root = tmp_path / "documentation"
+    register = docs_root / "compliance" / "gaps" / "gap-register.yaml"
+    register.parent.mkdir(parents=True)
+    register.write_text(
+        "schema_version: '1'\n"
+        "metadata:\n"
+        "  title: t\n"
+        "  assessment_date: '2026-01-01'\n"
+        "  source_matrix: m\n"
+        "  canonical_artifacts: ['a']\n"
+        "  maintenance_rule: r\n"
+        "summary:\n"
+        "  total_gaps: 1\n"
+        "  open: 1\n"
+        "  closed: 0\n"
+        "  partial_design_controls: 0\n"
+        "  controls_without_sufficient_repository_evidence: 0\n"
+        "gaps:\n"
+        "  - id: G-1\n"
+        "    control_id: C-1\n"
+        "    framework: F\n"
+        "    title: T\n"
+        "    owner: O\n"
+        "    risk: R\n"
+        "    status: open\n"
+        "    evidence: E\n"
+        "    review_frequency: quarterly\n"
+        "    retention: 1y\n"
+        "    source: S\n"
+        "    remediation: fix it\n"
+        "    remediation_link: nonexistent.md\n",
+        encoding="utf-8",
+    )
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": docs_root})
+    reported = tuple(
+        DocsSemantics().run(
+            ctx, FileSet(paths=("documentation/compliance/gaps/gap-register.yaml",))
+        )
+    )
+    assert any("unusable remediation_link" in r.message for r in reported), (
+        f"a gap register with a broken remediation_link, under a redeclared "
+        f"docs tree, went unreported: {reported}"
+    )
+
+
+def test_a_redeclared_docs_tree_still_grades_the_control_matrix(tmp_path) -> None:
+    from adl_compliance.core.context import Context, FileSet
+
+    docs_root = tmp_path / "documentation"
+    matrix = docs_root / "compliance" / "controls" / "control-matrix.yaml"
+    matrix.parent.mkdir(parents=True)
+    matrix.write_text(
+        "controls:\n"
+        "  - id: CTRL-1\n"
+        "    owner: O\n"
+        "    risk: R\n",
+        encoding="utf-8",
+    )
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": docs_root})
+    reported = tuple(
+        DocsSemantics().run(
+            ctx, FileSet(paths=("documentation/compliance/controls/control-matrix.yaml",))
+        )
+    )
+    assert any(
+        "control record 1 missing review_frequency" in r.message for r in reported
+    ), (
+        f"a control matrix missing a required field, under a redeclared docs "
+        f"tree, went unreported: {reported}"
+    )
+
+
+def test_a_redeclared_docs_tree_still_grades_research_assets(tmp_path) -> None:
+    from adl_compliance.core.context import Context, FileSet
+
+    docs_root = tmp_path / "documentation"
+    asset = docs_root / "assets" / "research" / "mobile-reference" / "mobile-reference-01.png"
+    asset.parent.mkdir(parents=True)
+    asset.write_bytes(b"\x89PNG\r\n\x1a\n")
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": docs_root})
+    reported = tuple(
+        DocsSemantics().run(
+            ctx,
+            FileSet(
+                paths=("documentation/assets/research/mobile-reference/mobile-reference-01.png",)
+            ),
+        )
+    )
+    assert any(
+        "research asset name must describe observable evidence" in r.message
+        for r in reported
+    ), (
+        f"a generically-named research asset, under a redeclared docs tree, "
+        f"went unreported: {reported}"
+    )
+
+
+def test_a_redeclared_docs_tree_still_grades_evidence_captions(tmp_path) -> None:
+    from adl_compliance.core.context import Context, FileSet
+
+    docs_root = tmp_path / "documentation"
+    evidence = docs_root / "research" / "field-notes" / "mobile-reference-evidence.md"
+    evidence.parent.mkdir(parents=True)
+    evidence.write_text("Reference screenshot 3 shows the login flow.\n", encoding="utf-8")
+    ctx = Context(root=tmp_path, row=ROW, inputs={"docs_root": docs_root})
+    reported = tuple(
+        DocsSemantics().run(
+            ctx, FileSet(paths=("documentation/research/field-notes/mobile-reference-evidence.md",))
+        )
+    )
+    assert any(
+        "image captions must describe observable evidence" in r.message for r in reported
+    ), (
+        f"a generic evidence caption, under a redeclared docs tree, went "
+        f"unreported: {reported}"
+    )

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

@@ -0,0 +1 @@
+"""layout."""

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

@@ -0,0 +1,12 @@
+"""The `layout.agents-layout` gate.
+
+A folder rather than a module because this gate GRADES A DOCUMENT, and the
+document belongs beside the check that reads it. `check.py` is the rule;
+anything else in here is what it grades.
+"""
+
+from __future__ import annotations
+
+from .check import AgentsLayout
+
+__all__ = ["AgentsLayout"]

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

@@ -0,0 +1,124 @@
+"""LAY-001 — the AGENTS.md / CLAUDE.md hierarchy.
+
+Four rules, split across the two hooks exactly as the base class draws the line:
+
+  structural  the governance files and the bootstrap guides. Named paths with
+              line limits; an absent one is the finding, and an absent file is
+              in no file set.
+  graded      the guide pairs, and the boilerplate advisory. Which guides is
+              the given set's answer.
+
+GOVERNANCE_LIMITS and BOOTSTRAP_GUIDES are NOT scope. They are named
+requirements: the list cannot grow with the tree, and every entry is a question
+about one path.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar
+
+from ....core.check import Check, FileState
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+
+class AgentsLayout(Check):
+    id: ClassVar[str] = "LAY-001"
+    rule: ClassVar[str] = "LAY-001"
+
+    # This gate's own values, and no other module's business. Shared values are
+    # inherited from `core.constants.Constants` via `Check`.
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>", "workflows_root": "<workflows>"}
+    """FIXED 2026-09-16 (K-42 sweep, LOUD form, approved): the `docs/AGENTS.md`
+    entry in GOVERNANCE_LIMITS, and BOOTSTRAP_GUIDES' `.workflows/AGENTS.md`,
+    were hardcoded literals, opened as named paths via `self.state(ctx, ...)`.
+    A repository whose docs or workflows root is not the packaged default had
+    its real guide fail that open, reported "is missing" -- a visible, wrong
+    finding about a file that is right there. `AGENTS.md` stays literal below
+    each resolved root: the settled document name, not a resolvable path."""
+
+    POINTER: ClassVar[str] = "@AGENTS.md"
+    GOVERNANCE_LIMITS: ClassVar[tuple[tuple[str, int], ...]] = (
+        ("AGENTS.md", 200),
+        ("INVARIANTS.md", 100),
+    )
+    DOCS_AGENTS_LIMIT: ClassVar[int] = 80
+    BANNED_BOILERPLATE: ClassVar[tuple[str, ...]] = (
+        "Never run bare",
+        "one stage at a time",
+        "Every integration-branch commit touches",
+    )
+
+    def _governance_limits(self, ctx: Context) -> tuple[tuple[str, int], ...]:
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        return (*self.GOVERNANCE_LIMITS, (f"{docs_root}/AGENTS.md", self.DOCS_AGENTS_LIMIT))
+
+    def _bootstrap_guides(self, ctx: Context) -> tuple[str, ...]:
+        workflows_root = ctx.relative(ctx.inputs["workflows_root"])
+        return (f"{workflows_root}/AGENTS.md",)
+
+    def structural(self, ctx: Context) -> Iterable[Report]:
+        for relative, limit in self._governance_limits(ctx):
+            match self.state(ctx, relative):
+                case FileState.MISSING:
+                    yield self.report(
+                        relative, "is missing",
+                        f"create {relative} with the required governance content",
+                    )
+                case FileState.EMPTY:
+                    yield self.report(
+                        relative, "is empty",
+                        f"add the required governance content to {relative}",
+                    )
+                case FileState.PRESENT:
+                    body = self.text(ctx, relative) or ""
+                    lines = len(body.splitlines())
+                    if lines > limit:
+                        yield self.report(
+                            relative, f"has {lines} lines; limit is {limit}",
+                            f"trim {relative} to {limit} lines or fewer, moving "
+                            "detail into an owned sub-guide",
+                        )
+
+        for guide in self._bootstrap_guides(ctx):
+            match self.state(ctx, guide):
+                case FileState.MISSING:
+                    yield self.report(guide, "is missing", f"create {guide}")
+                case FileState.EMPTY:
+                    yield self.report(guide, "is empty", f"add content to {guide}")
+                case FileState.PRESENT:
+                    pass
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        # The one narrowing scope cannot express: this wants AGENTS.md, and the
+        # row also names the CLAUDE.md siblings because the pairing rule reads
+        # them.
+        guides = sorted(p for p in files if p == "AGENTS.md" or p.endswith("/AGENTS.md"))
+
+        for guide in guides:
+            # `removesuffix` leaves the directory prefix INCLUDING its trailing
+            # slash, or "" at the repository root. Stripping "/AGENTS.md"
+            # instead produced "AGENTS.md/CLAUDE.md" for the root guide.
+            sibling = guide.removesuffix("AGENTS.md") + "CLAUDE.md"
+            body = self.text(ctx, sibling)
+            if body is None:
+                yield self.report(
+                    sibling, f"is missing (expected sibling of {guide})",
+                    f"create {sibling} containing a line exactly '{self.POINTER}'",
+                )
+            elif self.POINTER not in body.splitlines():
+                yield self.report(
+                    sibling, f"must contain a line exactly '{self.POINTER}'",
+                    f"add an exact '{self.POINTER}' line to {sibling}",
+                )
+
+        for guide in guides:
+            body = self.text(ctx, guide)
+            if body is None:
+                continue
+            for pattern in self.present_markers(body, self.BANNED_BOILERPLATE):
+                yield self.advise(
+                    guide,
+                    f"contains repo-wide boilerplate ('{pattern}') — "
+                    "move to root AGENTS.md",
+                )

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/agents_layout/fixtures/.workflows/AGENTS.md

@@ -0,0 +1 @@
+# Workflow guide