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

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

@@ -0,0 +1,194 @@
+"""DOC-011 — every Markdown page under docs/ has a lower-kebab stem.
+
+The rule being tested, restated from the gate's own docstring:
+
+    for every `.md` file in scope, the filename stem must full-match
+    `^[a-z0-9]+(-[a-z0-9]+)*$`, with exact-name exemptions for the standing
+    tree guides `AGENTS.md` and `CLAUDE.md`. Non-`.md` files are not graded
+    at all -- docs trees legitimately hold .png/.html/.csv/.yaml assets, and
+    the rule is about page names, not asset names.
+
+Ported in the same shape `docs/closed_set/test_check.py` uses: ONE corpus,
+and the clean case is the same tree with the violating entries left out of
+the given set -- exactly what a commit touching nothing violating looks like
+in production.
+
+Every test calls `DocsFilename` directly rather than through `runner.run`/
+`decide`, bypassing row-scope narrowing and registry lookup; the row is still
+loaded from the real registry because it is the Context's `row`. The row's
+scope excludes (`proposals/`, `compliance/`, guides, `index.md`) are the
+runner's business and are proven by the end-to-end CLI runs recorded in
+`docs/operations/repo-controls-copy-notes.md`, not replayed here -- this
+corpus deliberately carries no fixture for them.
+"""
+
+from __future__ import annotations
+
+from helpers import corpus, corpus_files
+
+from adl_compliance.checks.docs.filename import DocsFilename
+from adl_compliance.core.context import Context, FileSet
+from adl_compliance.core.finding import Finding
+from adl_compliance.policy.registry import load
+
+CORPUS = corpus("docs", "filename")
+ROW = load().by_id("DOC-011")
+
+# Every violation shape the rule names, kept out of the clean set.
+VIOLATING = (
+    "docs/research/UI-CONTRACT.md",
+    "docs/architecture/user_profile.md",
+    "docs/architecture/getting started.md",
+    "docs/architecture/-leading-hyphen.md",
+    "docs/architecture/trailing-hyphen-.md",
+    "docs/architecture/double--hyphen.md",
+)
+
+# In the corpus, never findings: exempt guide names (root and nested),
+# the standing catalog/ledger names, non-Markdown assets (including one
+# with a deliberately violating stem), and a path that merely lookalikes
+# the docs/ prefix.
+NOT_FINDINGS = (
+    "docs.md",
+    "docs/AGENTS.md",
+    "docs/CLAUDE.md",
+    "docs/architecture/AGENTS.md",
+    "docs/index.md",
+    "docs/notes.md",
+    "docs/reference.html",
+    "docs/assets/diagram.png",
+    "docs/assets/UI-CONTRACT.png",
+)
+
+CONFORMING = (
+    "docs/architecture/ui-contract.md",
+    "docs/architecture/nested/page-here.md",
+    "docs/research/2026-10-experiment.md",
+)
+
+
+def clean_set() -> tuple[str, ...]:
+    return tuple(p for p in corpus_files(CORPUS) if p not in VIOLATING)
+
+
+def findings_for(given: tuple[str, ...]) -> tuple[Finding, ...]:
+    ctx = Context(root=CORPUS, row=ROW, inputs={"docs_root": CORPUS / "docs"})
+    return tuple(DocsFilename().run(ctx, FileSet(paths=given)))
+
+
+def messages_for(given: tuple[str, ...]) -> tuple[str, ...]:
+    return tuple(f.render() for f in findings_for(given))
+
+
+def test_the_premise_holds() -> None:
+    """Asserted, not assumed: a mistyped path would leave the clean set
+    identical to the full corpus and every case below would agree for
+    nothing."""
+    all_files = corpus_files(CORPUS)
+    for path in (*VIOLATING, *NOT_FINDINGS, *CONFORMING):
+        assert path in all_files, path
+    assert len(clean_set()) == len(all_files) - len(VIOLATING)
+
+
+def test_conforming_stems_are_silent() -> None:
+    findings = findings_for(clean_set())
+    assert findings == (), tuple(f.render() for f in findings)
+
+
+def test_an_uppercase_stem_is_reported() -> None:
+    """The real consumer case: the Enact tree carries
+    docs/architecture/frontend/UI-CONTRACT.md; the gate must name it.
+    (The fixture sits under research/ because this checkout's filesystem
+    is case-insensitive and cannot hold it beside the lowercase
+    ui-contract.md in the same directory.)"""
+    messages = messages_for(corpus_files(CORPUS))
+    assert any(
+        "docs/research/UI-CONTRACT.md" in m and "is not lower-kebab" in m
+        for m in messages
+    ), messages
+
+
+def test_an_underscored_stem_is_reported() -> None:
+    messages = messages_for(corpus_files(CORPUS))
+    assert any("user_profile.md" in m for m in messages), messages
+
+
+def test_a_spaced_stem_is_reported() -> None:
+    messages = messages_for(corpus_files(CORPUS))
+    assert any("getting started.md" in m for m in messages), messages
+
+
+def test_a_leading_hyphen_is_reported() -> None:
+    """A leading hyphen makes the first run empty; full-match fails."""
+    messages = messages_for(corpus_files(CORPUS))
+    assert any("-leading-hyphen.md" in m for m in messages), messages
+
+
+def test_a_trailing_hyphen_is_reported() -> None:
+    """A trailing hyphen makes the last run empty; full-match fails."""
+    messages = messages_for(corpus_files(CORPUS))
+    assert any("trailing-hyphen-.md" in m for m in messages), messages
+
+
+def test_a_double_hyphen_is_reported() -> None:
+    """A double hyphen leaves an empty segment between the dashes; the
+    `(?:-[a-z0-9]+)*` repeat cannot cross it."""
+    messages = messages_for(corpus_files(CORPUS))
+    assert any("double--hyphen.md" in m for m in messages), messages
+
+
+def test_guide_names_are_exempt_at_any_depth() -> None:
+    """AGENTS.md and CLAUDE.md are the standing tree-guide names the other
+    docs gates exclude too; the exemption is by exact name, so it holds in
+    nested directories as well as at the docs root."""
+    text = "\n".join(messages_for(corpus_files(CORPUS)))
+    assert "docs/AGENTS.md" not in text
+    assert "docs/CLAUDE.md" not in text
+    assert "docs/architecture/AGENTS.md" not in text
+
+
+def test_the_standing_page_names_are_silent() -> None:
+    """`index.md` (the standing catalog name, also scope-excluded) and
+    `notes.md` (the task ledger) carry conforming stems; both stay silent."""
+    text = "\n".join(messages_for(corpus_files(CORPUS)))
+    assert "docs/index.md" not in text
+    assert "docs/notes.md" not in text
+
+
+def test_non_markdown_files_are_not_graded() -> None:
+    """The rule grades `.md` pages only. `docs/assets/UI-CONTRACT.png` pins
+    the sharp edge: a violating STEM in a non-Markdown file is not a
+    finding, or every diagram beside a UI contract page would fail."""
+    text = "\n".join(messages_for(corpus_files(CORPUS)))
+    assert "docs/reference.html" not in text
+    assert "docs/assets/diagram.png" not in text
+    assert "docs/assets/UI-CONTRACT.png" not in text
+
+
+def test_every_finding_is_tagged_doc_011() -> None:
+    findings = findings_for(corpus_files(CORPUS))
+    assert findings
+    assert all(f.rule == "DOC-011" for f in findings), tuple(
+        f.render() for f in findings
+    )
+
+
+def test_a_lookalike_prefix_is_ignored() -> None:
+    """`docs.md` is a root-level file whose name is the tree name plus the
+    extension; the gate's prefix carries a trailing slash, so it is outside
+    docs/ entirely."""
+    assert "docs.md" in corpus_files(CORPUS)
+    text = "\n".join(messages_for(corpus_files(CORPUS)))
+    assert "docs.md" not in text
+
+
+def test_an_empty_set_grades_nothing() -> None:
+    """Every violating stem is still on disk. A check that grades only what
+    it is handed must report none of them against an empty given set."""
+    findings = findings_for(())
+    assert findings == ()
+
+
+def test_a_path_outside_docs_is_ignored() -> None:
+    findings = findings_for(("documentation/UI-CONTRACT.md",))
+    assert findings == ()

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

@@ -17,8 +17,20 @@ THIS repository and what each one governs, and this gate means nothing without
 it — so it ships as a `resources` entry beside this check (co-located with the
 gate, per `compliance_new/AGENTS.md`'s "a named input lives in the gate's own
 folder"), not fetched from the consumer's tree by path. `docs-knowledge-indexes
-.yaml` here is transcribed byte-for-byte from
-`compliance_new/checks/docs/indexes/docs-knowledge-indexes.yaml` (2026-08-29).
+.yaml` was transcribed byte-for-byte from
+`compliance_new/checks/docs/indexes/docs-knowledge-indexes.yaml` (2026-08-29),
+with one later amendment recorded here rather than left as drift: on
+2026-10-02 the docs-compliance and docs-product entries' `required_frontmatter`
+flipped `document_type` → `type`. The estate's frontmatter vocabulary is the
+OKF profile's — `docs-okf-profiles.yaml`'s `common_required` is
+`[type, title, description, status]` and no profile knows a `document_type`
+key — and twelve of this register's sixteen catalogues already required
+`type` (the other two require no type-family key); these two were the last
+outliers, and an index satisfying every other
+catalogue's vocabulary failed them for a key nothing else in the estate
+writes. The flip is pinned by the `knowledge-indexes-shipped-register-
+{type,legacy}/` corpora in `test_check.py`, which point the `registry` input
+at this shipped file instead of a cut-down fixture copy.
 
 Entirely `graded`: every rule here reads the GIVEN SET, even the ones that look
 at the register alone — an entry the given set never touches is not audited at

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/indexes/docs-knowledge-indexes.yaml

@@ -138,7 +138,7 @@ indexes:
     include_extensions: [.md]
     exclude_names: [index.md, AGENTS.md, CLAUDE.md]
     exclude_prefixes: [product/]
-    required_frontmatter: [title, description, document_type, status, last_update, reason]
+    required_frontmatter: [type, title, description, status, last_update, sources, related]
     required_sections: [Reading order]
     display_status: true
     status_map: {draft: draft, stable: stable}
@@ -150,7 +150,7 @@ indexes:
     recursive: true
     include_extensions: [.md]
     exclude_names: [index.md, AGENTS.md, CLAUDE.md]
-    required_frontmatter: [title, description, document_type, status, last_update, reason]
+    required_frontmatter: [title, description, status, last_update, sources, created]
     required_sections: []
     display_status: true
     status_map: {draft: draft, canonical: canonical, stable: stable}
@@ -162,7 +162,7 @@ indexes:
     recursive: true
     include_extensions: [.md, .yaml, .yml]
     exclude_names: [index.md, AGENTS.md, CLAUDE.md]
-    required_frontmatter: [title, description, document_type, status, last_update, reason]
+    required_frontmatter: [title, description, type, status, last_update, reason]
     required_sections: []
     display_status: true
     status_map: {canonical: stable, draft: draft, '-': metadata}
@@ -174,7 +174,7 @@ indexes:
     recursive: false
     include_extensions: [.md]
     exclude_names: [index.md, AGENTS.md, CLAUDE.md]
-    required_frontmatter: [title, description, document_type, status, last_update, reason]
+    required_frontmatter: [type, title, description, status, last_update, sources, related]
     required_sections: []
     display_status: true
     status_map: {draft: draft, stable: stable}
@@ -186,7 +186,7 @@ indexes:
     recursive: true
     include_extensions: [.md]
     exclude_names: [index.md, AGENTS.md, CLAUDE.md]
-    required_frontmatter: [title, description, document_type, status, last_update, reason]
+    required_frontmatter: [title, description, type, status, last_update, reason]
     required_sections: [Normative, "Input, not authority", The schema itself]
     display_status: false
     inventory: exempt

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/indexes/fixtures/knowledge-indexes-shipped-register-legacy/docs/compliance/index.md

@@ -0,0 +1,10 @@
+---
+title: Compliance
+description: Fixture catalogue for the shipped-register frontmatter tests.
+document_type: compliance
+status: stable
+last_update: 2026-10-02
+reason: fixture for the shipped-register vocabulary tests, not a graded page
+---
+
+# Compliance

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/indexes/fixtures/knowledge-indexes-shipped-register-type/docs/compliance/index.md

@@ -0,0 +1,10 @@
+---
+title: Compliance
+description: Fixture catalogue for the shipped-register frontmatter tests.
+type: compliance
+status: stable
+last_update: 2026-10-02
+reason: fixture for the shipped-register vocabulary tests, not a graded page
+---
+
+# Compliance

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

@@ -1,12 +1,20 @@
 """DOC-008 — ported from `compliance_new/checks/docs/indexes/test.sh`.
 
-Three committed corpora, same scenario names and same file content as the
-shell fixtures under
+Five committed corpora. Three share the shell fixtures' scenario names and
+file content under
 `compliance_new/checks/docs/indexes/fixtures/knowledge-indexes-{clean,
 missing-entry,duplicate}/` — only the registry input is flattened to the
 fixture root rather than nested under the shell tree's own `compliance/
 checks/docs/indexes/` path (see `knowledge-indexes-clean/
-docs-knowledge-indexes.yaml`'s own comment).
+docs-knowledge-indexes.yaml`'s own comment). The remaining two
+(`knowledge-indexes-shipped-register-{type,legacy}/`) hold one
+`docs/compliance/index.md` each and point the `registry` input at the GATE'S
+OWN shipped `docs-knowledge-indexes.yaml` rather than a cut-down fixture
+registry: the first three corpora grade the check's mechanics, but only the
+shipped register's own vocabulary can say whether `type` is required — the
+flip of 2026-10-02 (`document_type` → `type` in the docs-compliance and
+docs-product entries, recorded in `check.py`'s module docstring) is pinned
+by these two.
 
 This wave's checks are wired into `checks/__init__.py` in a later, single pass
 (see the folder's own docstring / the dispatch instructions), so `Indexes` is
@@ -44,16 +52,34 @@ FIXTURES = corpus("docs", "indexes")
 CLEAN = FIXTURES / "knowledge-indexes-clean"
 MISSING_ENTRY = FIXTURES / "knowledge-indexes-missing-entry"
 DUPLICATE = FIXTURES / "knowledge-indexes-duplicate"
+SHIPPED_TYPE = FIXTURES / "knowledge-indexes-shipped-register-type"
+SHIPPED_LEGACY = FIXTURES / "knowledge-indexes-shipped-register-legacy"
 
 ROW = load().by_id("DOC-008")
 
+# The register the package ships beside this check — the policy whose
+# vocabulary the two shipped-register corpora grade.
+SHIPPED_REGISTER = FIXTURES.parent / "docs-knowledge-indexes.yaml"
 
-def _run(root: Path, *, given: Sequence[str] | None = None) -> Verdict:
+
+def _run(
+    root: Path,
+    *,
+    given: Sequence[str] | None = None,
+    registry: Path | None = None,
+) -> Verdict:
     """`runner.run`'s scope-narrow-then-decide, against this check directly —
-    the same bypass `CON-003`'s test uses for an unwired check."""
+    the same bypass `CON-003`'s test uses for an unwired check.
+
+    `registry` defaults to the corpus's own flattened copy; the
+    shipped-register corpora pass the gate folder's own yaml instead."""
     raw = corpus_files(root) if given is None else tuple(given)
     narrowed = FileSet(paths=scope.intersect(ROW.resolved_scope(), raw))
-    ctx = Context(root=root, row=ROW, inputs={"registry": root / "docs-knowledge-indexes.yaml"})
+    ctx = Context(
+        root=root,
+        row=ROW,
+        inputs={"registry": registry if registry is not None else root / "docs-knowledge-indexes.yaml"},
+    )
     try:
         findings = tuple(Indexes().run(ctx, narrowed))
     except CouldNotRun as exc:
@@ -100,3 +126,29 @@ def test_the_omitted_page_outside_the_given_set_is_not_reported() -> None:
     in the given set this time — so there is nothing to compare it against."""
     verdict = _run(MISSING_ENTRY, given=("docs/index.md", "docs/one.md"))
     assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# ------------------------------------------- the shipped register's vocabulary
+
+def test_an_index_satisfying_the_shipped_register_with_type_is_clean() -> None:
+    """The gate's OWN register, not a fixture copy, grades a compliance index
+    carrying the OKF `type` key clean. Decision of 2026-10-02: the
+    docs-compliance and docs-product entries' `required_frontmatter` flipped
+    `document_type` → `type` (see `check.py`'s module docstring) — before the
+    flip this corpus was reported as missing `document_type`."""
+    verdict = _run(SHIPPED_TYPE, registry=SHIPPED_REGISTER)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+def test_an_index_carrying_only_the_legacy_document_type_key_is_reported() -> None:
+    """The flip's converse: an index that still carries `document_type` and no
+    `type` fails the shipped register. Before 2026-10-02 this corpus graded
+    CLEAN, which is exactly the drift the flip removes — the OKF profile
+    (`docs-okf-profiles.yaml`'s `common_required`) knows `type` only."""
+    verdict = _run(SHIPPED_LEGACY, registry=SHIPPED_REGISTER)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert verdict.rules == ["KNW-001"]
+    finding = verdict.findings[0]
+    assert finding.path == "docs/compliance/index.md"
+    assert finding.message == "missing required frontmatter field type"

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

@@ -24,7 +24,6 @@ import pathlib
 import shutil
 from datetime import date, timedelta
 
-import pytest
 import yaml
 
 from adl_compliance import runner

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

@@ -2,17 +2,36 @@
 
 Google Cloud's Open Knowledge Format v0.2. The profile register declares the
 common required fields, and then one profile per document kind: which paths it
-covers, the `type` and `document_type` those documents must declare, the extra
-fields they must carry, and the headings they must contain.
+covers, the `type` those documents must declare (optional: a profile that names
+none leaves the value unconstrained), the extra fields they must carry, and the
+headings they must contain.
 
 Six rules, one rule id, because they are one contract:
 
   * the file has parseable YAML frontmatter at all;
   * some profile covers its path;
-  * `type` and `document_type` match that profile;
+  * `type` matches that profile, where it declares one;
   * every common and profile-specific required field is present;
   * `status` is `draft` or `stable`;
-  * each declared heading group has at least one of its headings present.
+  * each declared heading group has at least one of its headings present;
+  * the frontmatter key set is CLOSED (2026-10-02): a document may carry only
+    the keys its profile admits — `common_required`, `common_optional`, and
+    the profile's own `required` — and every other key is reported by name.
+
+The closed set is the same contract `core/models.py`'s `extra="forbid"`
+grades this package's own policy documents with, applied at the frontmatter
+layer. Required-only grading had the hole in reverse: keys nobody admitted
+accumulated in real documents because nothing rejected them, and the register's
+`common_optional` list — until this rule — was read by no check at all. The
+root agent rule names the workflow the finding drives: admit a new key by
+editing `docs-okf-profiles.yaml` (into `common_optional`, or a profile's
+`required` when every document of that kind must carry it), never ad-hoc in a
+document. The set is closed PER PROFILE, not per register: `created` is in the
+vocabulary because the Research profile requires it, but an architecture page
+carrying it is reported — otherwise every profile's `required` list would leak
+into every other profile by construction. `last_update` sits in
+`common_optional` (not any profile's `required`) because every document kind
+carries it while no document kind must.
 
 The `plan_state`-agrees-with-its-directory rule is gone. It existed because a
 plan's lifecycle state was mirrored in a directory name (`a_new`,
@@ -51,12 +70,14 @@ from ....core.scope import matches
 
 
 class Profile(StrictModel):
-    type: str
+    type: str | None = None
+    """Optional per profile. The Research profile declares none because the
+    pages under `docs/research/` legitimately differ in `type` (Research,
+    Experiment). A profile that names no `type` asserts nothing about its
+    VALUE; the field must still be present, because `common_required` lists
+    it."""
+
     paths: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
-    document_type: str | None = None
-    """Optional per profile. Two of the shipped profiles — Specification and
-    Change Plan — declare none, and a profile that does not name one is not
-    asserting anything about the field."""
 
     required: Annotated[tuple[str, ...], Field(strict=False)] = ()
 
@@ -159,18 +180,11 @@ class OkfProfile(Check):
             return
 
         declared_type = frontmatter.get("type")
-        if declared_type != profile.type:
+        if profile.type is not None and declared_type != profile.type:
             yield self.report(
                 relative, f"type must be '{profile.type}' (got {declared_type!r})",
                 f"set frontmatter type: {profile.type}",
             )
-        declared_document = frontmatter.get("document_type")
-        if profile.document_type is not None and declared_document != profile.document_type:
-            yield self.report(
-                relative,
-                f"document_type must be '{profile.document_type}' (got {declared_document!r})",
-                f"set frontmatter document_type: {profile.document_type}",
-            )
 
         for field in register.common_required:
             if not frontmatter.get(field):
@@ -185,6 +199,8 @@ class OkfProfile(Check):
                     f"add the {field} field required by this document's OKF profile",
                 )
 
+        yield from self._admitted_keys(relative, frontmatter, register, profile)
+
         status = frontmatter.get("status")
         if status not in self.STATUSES:
             yield self.report(
@@ -194,6 +210,37 @@ class OkfProfile(Check):
 
         yield from self._headings(relative, body, profile)
 
+    def _admitted_keys(
+        self,
+        relative: str,
+        frontmatter: Mapping[str, object],
+        register: ProfileRegister,
+        profile: Profile,
+    ) -> Iterable[Report]:
+        """The closed key set: common_required, common_optional, and the
+        profile's own required. Anything else is reported by name, in key
+        order, so a document with three stray keys reports three findings and
+        the fix list reads the same way every time.
+
+        Keys are compared as a SET, not by truthiness: an admitted key with an
+        empty value is the required-fields rule's subject, not this one's.
+        Non-string YAML keys cannot be in the vocabulary and are reported
+        rather than crashing the sort."""
+        admitted = (
+            set(register.common_required)
+            | set(register.common_optional)
+            | set(profile.required)
+        )
+        for key in sorted(frontmatter, key=str):
+            if key in admitted:
+                continue
+            yield self.report(
+                relative, f"unknown OKF frontmatter key {key!r}",
+                "remove the key, or admit it in docs-okf-profiles.yaml: add it "
+                "to common_optional, or to this profile's required if every "
+                "document of this kind must carry it",
+            )
+
     def _headings(self, relative: str, body: str, profile: Profile) -> Iterable[Report]:
         present = [
             line.lstrip("#").strip()

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/docs-okf-profiles.yaml

@@ -5,7 +5,6 @@ version: "0.2"
 # |--------------------------|-----------------------------------------------------|
 # | status                   | unquoted bare scalar: draft | stable (status: draft) |
 # | last_update              | quoted ISO-8601 UTC        : '2026-08-22T00:00:00Z'         |
-# | document_type            | unquoted bare scalar (same rule as status)          |
 # | created, decision_date, …| unquoted bare YYYY-MM-DD dates where present         |
 
 # `generated: {by, at}` used to be here. It was machine provenance nobody
@@ -19,25 +18,55 @@ common_required:
   - description
   - status
 
+# common_optional is the closed key set's safety valve (DOC-006, 2026-10-02):
+# a key here is admitted on every document kind but required of none. The
+# closed-set rule reads this list; nothing else ever did — it existed in the
+# register for a year with no check enforcing it.
+#
+# last_update is admitted here, not in any profile's required: every document
+# kind carries it (it is a frontmatter convention above, and all 25 documents
+# in the adl-azdo corpus have it) while no document kind must — required
+# belongs to fields a profile's headings cannot be written without.
+#
+# related is admitted the same way and for the measured reason: 24 of those 25
+# documents carry it, across every kind — the Architecture and Operations
+# profiles already REQUIRE it, and research pages carry it without their
+# profile requiring it (see test_check.py: the research fixtures deliberately
+# have none). A key the whole corpus conventionally carries but one kind
+# legitimately omits is the definition of optional.
 common_optional:
   - verified
   - resource
   - tags
   - stale_after
+  - last_update
+  - related
 
-# Four profiles, deliberately.
+# Five profiles, deliberately (Compliance is disabled, see below).
 #
 # There were eight. Benchmark, Evaluation, Field Note and Specification declared
 # trees that do not exist -- docs/research/benchmarks, docs/research/evaluations,
 # docs/research/field-notes, .specs -- so seven of the eight graded nothing at
 # all while reading as coverage. A register that describes a documentation set
 # nobody has is worse than a smaller one that describes the real thing: it
-# reports clean because it never matched a file.
+# reports clean because it never matched a file. Those four stay removed.
+#
+# Research is added back (2026-10-01), and not as a return of those four:
+# docs/research/ itself exists in the consuming repositories. enact-combined
+# holds docs/research/cloud-local-research-input.md (type Research) and
+# docs/research/codex-app-server-container-experiment.md (type Experiment), and
+# with no profile covering that path DOC-006 reported "no OKF profile matches
+# this path" for both. The profile is minimal on purpose: one entry for
+# docs/research/**, requiring what both pages carry -- title, description and
+# status through common_required, then last_update and sources -- and nothing else. It declares no `type`, because the two pages
+# differ in it, and no headings, because they share no section structure.
 #
 #   Architecture   what the system is          docs/architecture/**
 #   ADR            why it is that way          docs/architecture/decisions/**, docs/decisions/**
-#   Compliance     what we must show           docs/compliance/**
 #   Operations     how it is operated          docs/operations/**
+#   Task ledger    what each agent task did    docs/notes.md
+#   Research       what is being found out     docs/research/**
+#   (Compliance    what we must show           docs/compliance/** -- disabled, see below)
 #
 # plans/ is NOT here. Its frontmatter answers to the Azure DevOps board, not to
 # OKF, and LAY-009 owns it.
@@ -46,7 +75,6 @@ profiles:
   - type: Architecture
     paths:
       - docs/architecture/**
-    document_type: architecture
     required:
       - sources
       - related
@@ -60,7 +88,6 @@ profiles:
     paths:
       - docs/architecture/decisions/**
       - docs/decisions/**
-    document_type: adr
     required:
       - decision_id
       - decision_date
@@ -84,8 +111,7 @@ profiles:
   # - type: Compliance Assessment
   #   paths:
   #     - docs/compliance/**
-  #   document_type: compliance
-  #   required:
+    #   required:
   #     - control_ids
   #     - owner
   #     - review_frequency
@@ -107,7 +133,6 @@ profiles:
   - type: Operations
     paths:
       - docs/operations/**
-    document_type: operations
     required:
       - sources
       - related
@@ -117,3 +142,29 @@ profiles:
       - ["Credentials", "Access", "Sign"]
       - ["Verification", "Evidence", "Check"]
 
+  # The task ledger: one append-only list of dated lines, one per task start
+  # and finish, that the global agent rule requires in every repository
+  # (docs/notes.md, declared in policy/docs_shape.py). It is an operations
+  # document, but not a procedure: it has no Purpose/Procedure/Credentials
+  # sections and no `related` field, so it gets its own profile rather than
+  # the Operations one above. It is graded for what it really has: OKF
+  # frontmatter with `sources`, and its `## Lines` section.
+  - type: Operations
+    paths:
+      - docs/notes.md
+    required:
+      - sources
+    headings:
+      - ["Lines"]
+
+  # Research: inputs, findings and experiment plans under docs/research/. No
+  # `type` -- the pages there differ (Research, Experiment) -- and no headings;
+  # see the header. Title, description and status come from common_required.
+  # Research pages are dated: `created` (bare YYYY-MM-DD) records when the work
+  # was done -- the date is part of what a research page is.
+  - paths:
+      - docs/research/**
+    required:
+      - created
+      - last_update
+      - sources

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-ledger-clean/docs/notes.md

@@ -0,0 +1,17 @@
+---
+last_update: 2026-09-28T15:10:00Z
+title: Agent notes ledger
+description: Fixture task ledger, one append-only line per task start and finish.
+type: Operations
+status: stable
+sources: packages/agent-settings/assets/GLOBAL-AGENTS.md
+---
+
+# Agent notes ledger
+
+An append-only log; one line when an agent starts a task and one when it finishes.
+
+## Lines
+
+2026-09-28 05:31 claude start: fixture task
+2026-09-28 05:40 claude finish: fixture task