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

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

@@ -0,0 +1,12 @@
+"""The `docs.okf-profile` 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 OkfProfile
+
+__all__ = ["OkfProfile"]

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

@@ -0,0 +1,210 @@
+"""DOC-006 — every document satisfies the OKF profile its path selects.
+
+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.
+
+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;
+  * 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.
+
+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`,
+`b_committed`, `c_done`), which made the repository a second authority on a
+fact the board already owned. Documents no longer move, so there is no second
+copy of the state to disagree with.
+
+**The shell version needed four mechanisms to do this and this needs one.** It
+ran an awk pass to extract frontmatter into one flat file per document under
+`$TMPDIR`, an ast-grep scan with `--filter '^okf-'` over those extracted files to
+assert YAML SHAPE, a second awk pass over a pre-built profile lookup for the
+field rules, and an `rg` pass plus a third awk for headings. Every one of those
+existed because bash cannot parse YAML. `yaml.safe_load` can, so the structural
+lane is not dropped — it is subsumed: a document whose frontmatter is not valid
+YAML fails at the parse, which is exactly what the `okf-*` rules were asserting.
+
+Profile selection is LAST MATCH WINS, the same rule the row's `engine.scope`
+uses. It has to be: `docs/architecture/**` and `docs/architecture/decisions/**`
+both cover an ADR, and the ADR profile is declared second.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Annotated, ClassVar
+
+import yaml
+from pydantic import Field
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.errors import CouldNotRun, SchemaInvalid
+from ....core.finding import Report
+from ....core.models import StrictModel
+from ....core.scope import matches
+
+
+class Profile(StrictModel):
+    type: str
+    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)] = ()
+
+    headings: Annotated[
+        tuple[Annotated[tuple[str, ...], Field(strict=False)], ...], Field(strict=False)
+    ] = ()
+    """Groups. Each group is satisfied by ANY one of its headings, which is how
+    one profile covers documents that legitimately name the same section
+    differently — "Verification" or "Evidence" or "Source"."""
+
+
+class ProfileRegister(StrictModel):
+    version: str
+    common_required: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+    common_optional: Annotated[tuple[str, ...], Field(strict=False)] = ()
+    profiles: Annotated[tuple[Profile, ...], Field(min_length=1, strict=False)]
+
+
+class OkfProfile(Check):
+    id: ClassVar[str] = "DOC-006"
+    rule: ClassVar[str] = "DOC-006"
+
+    resources: ClassVar[dict[str, str]] = {"profiles": "docs-okf-profiles.yaml"}
+    """The register is POLICY THIS PACKAGE OWNS — it means nothing without this
+    check and this check grades nothing without it — so it ships beside the
+    check rather than being fetched from the consumer's tree by path."""
+
+    DELIMITER: ClassVar[str] = "---"
+    STATUSES: ClassVar[tuple[str, ...]] = ("draft", "stable")
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        register = self._register(ctx)
+        documents = FileSet(paths=tuple(sorted(p for p in files if p.endswith(".md"))))
+
+        for relative in documents.existing(ctx.root):
+            body = self.text(ctx, relative)
+            if body is None:
+                continue
+            frontmatter = self._frontmatter(body)
+            if frontmatter is None:
+                yield self.report(
+                    relative, "no parseable YAML frontmatter",
+                    f"add a {self.DELIMITER}-delimited YAML frontmatter block at the top "
+                    "of the file",
+                )
+                continue
+            yield from self._grade(relative, body, frontmatter, register)
+
+    # ------------------------------------------------------------- the register
+
+    def _register(self, ctx: Context) -> ProfileRegister:
+        try:
+            return self.parse_yaml(ctx, ctx.inputs["profiles"], ProfileRegister)
+        except SchemaInvalid as exc:
+            # COULD NOT RUN, not a finding. Without the register this gate has
+            # no profiles to grade against, so every verdict it could reach
+            # would be derived from a document it could not read — and reporting
+            # that as a clean pass is the silent green this estate keeps paying
+            # for (F-05).
+            raise CouldNotRun(f"OKF profile register is unusable: {exc.detail}") from exc
+
+    @staticmethod
+    def _select(register: ProfileRegister, relative: str) -> Profile | None:
+        """Last match wins — `docs/architecture/decisions/**` after `docs/architecture/**`."""
+        selected = None
+        for profile in register.profiles:
+            if any(matches(pattern, relative) for pattern in profile.paths):
+                selected = profile
+        return selected
+
+    # ---------------------------------------------------------- the frontmatter
+
+    def _frontmatter(self, body: str) -> Mapping[str, object] | None:
+        lines = body.splitlines()
+        if not lines or lines[0].strip() != self.DELIMITER:
+            return None
+        for index, line in enumerate(lines[1:], start=1):
+            if line.strip() != self.DELIMITER:
+                continue
+            try:
+                loaded = yaml.safe_load("\n".join(lines[1:index]))
+            except yaml.YAMLError:
+                return None
+            return loaded if isinstance(loaded, dict) else None
+        return None
+
+    # ---------------------------------------------------------------- the rules
+
+    def _grade(
+        self, relative: str, body: str, frontmatter: Mapping[str, object],
+        register: ProfileRegister,
+    ) -> Iterable[Report]:
+        profile = self._select(register, relative)
+        if profile is None:
+            yield self.report(
+                relative, "no OKF profile matches this path",
+                "move the file under a path an OKF profile covers, or add a profile "
+                "entry for it",
+            )
+            return
+
+        declared_type = frontmatter.get("type")
+        if 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):
+                yield self.report(
+                    relative, f"missing required OKF field {field}",
+                    f"add the {field} field to the frontmatter",
+                )
+        for field in profile.required:
+            if not frontmatter.get(field):
+                yield self.report(
+                    relative, f"missing profile field {field}",
+                    f"add the {field} field required by this document's OKF profile",
+                )
+
+        status = frontmatter.get("status")
+        if status not in self.STATUSES:
+            yield self.report(
+                relative, f"invalid OKF status {status!r}",
+                f"set status to one of: {', '.join(self.STATUSES)}",
+            )
+
+        yield from self._headings(relative, body, profile)
+
+    def _headings(self, relative: str, body: str, profile: Profile) -> Iterable[Report]:
+        present = [
+            line.lstrip("#").strip()
+            for line in body.splitlines()
+            if line.startswith("#")
+        ]
+        for group in profile.headings:
+            if any(any(wanted in heading for heading in present) for wanted in group):
+                continue
+            rendered = ", ".join(group)
+            yield self.report(
+                relative, f"missing one of headings: {rendered}",
+                f"add one of the required headings: {rendered}",
+            )

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

@@ -0,0 +1,119 @@
+version: "0.2"
+
+# Frontmatter conventions (enforced by docs.okf-profile via compliance/yaml/rules/):
+# | Field                    | Format                                              |
+# |--------------------------|-----------------------------------------------------|
+# | 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
+# maintained: every document claimed to be generated by a human at a timestamp
+# that was whatever the author happened to type. Git records who wrote a file
+# and when, accurately, and a field that duplicates git badly is worse than no
+# field at all.
+common_required:
+  - type
+  - title
+  - description
+  - status
+
+common_optional:
+  - verified
+  - resource
+  - tags
+  - stale_after
+
+# Four profiles, deliberately.
+#
+# 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.
+#
+#   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/**
+#
+# plans/ is NOT here. Its frontmatter answers to the Azure DevOps board, not to
+# OKF, and LAY-009 owns it.
+
+profiles:
+  - type: Architecture
+    paths:
+      - docs/architecture/**
+    document_type: architecture
+    required:
+      - sources
+      - related
+    headings:
+      - ["Purpose", "Scope"]
+      - ["Target", "Boundary", "Component", "Topology"]
+      - ["Invariant", "Constraint", "Security", "Failure"]
+      - ["Verification", "Evidence", "Source"]
+
+  - type: Architecture Decision Record
+    paths:
+      - docs/architecture/decisions/**
+      - docs/decisions/**
+    document_type: adr
+    required:
+      - decision_id
+      - decision_date
+      - sources
+      - related
+    headings:
+      - ["Context"]
+      - ["Decision"]
+      - ["Consequences"]
+      - ["Alternatives", "Rationale"]
+      - ["Verification", "Evidence", "Source"]
+
+  # DISABLED 2026-09-15 — pending a real compliance audit.
+  #
+  # The profile demands control_ids, owner, review_frequency and evidence_retention:
+  # genuine audit metadata, not something a writer can infer from the document. The one
+  # page under docs/compliance/ is a running gap register — a chronological log of
+  # findings with their evidence — which is not a compliance assessment any more than a
+  # knowledge index is a document about the system (see 5e257e0, which excluded indexes
+  # for the same reason). Re-enable with the audit, not before.
+  # - type: Compliance Assessment
+  #   paths:
+  #     - docs/compliance/**
+  #   document_type: compliance
+  #   required:
+  #     - control_ids
+  #     - owner
+  #     - review_frequency
+  #     - evidence_retention
+  #     - sources
+  #     - stale_after
+  #     - related
+  #   headings:
+  #     - ["Scope", "Obligation"]
+  #     - ["Control"]
+  #     - ["Evidence", "Retention"]
+  #     - ["Gap", "Remediation", "Risk"]
+  # 
+  # # How this repository is operated: the standing procedures, including the
+  # # triage / build / release contracts. Not architecture (what the system is)
+  # # and not a decision record (why it is that way) -- what a person or an agent
+  # # actually does, step by step.
+
+  - type: Operations
+    paths:
+      - docs/operations/**
+    document_type: operations
+    required:
+      - sources
+      - related
+    headings:
+      - ["Purpose", "Scope", "When"]
+      - ["Procedure", "Command", "Steps", "Mode"]
+      - ["Credentials", "Access", "Sign"]
+      - ["Verification", "Evidence", "Check"]
+

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-profile-clean/docs/architecture/demo.md

@@ -0,0 +1,17 @@
+---
+type: Architecture
+title: Demo
+description: Fixture architecture page
+status: draft
+generated:
+  by: process:test
+  at: '2026-08-22T00:00:00Z'
+document_type: architecture
+sources:
+  - resource: repository:fixture
+related:
+  - docs/architecture/demo.md
+---
+# Purpose
+
+# Target

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

@@ -0,0 +1,8 @@
+version: "1"
+common_required: [type, title, description, status, generated]
+profiles:
+  - type: Architecture
+    paths: [docs/architecture/**]
+    document_type: architecture
+    required: [sources, related]
+    headings: [[Purpose], [Target]]

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/okf_profile/fixtures/okf-profile-violation/docs/architecture/bad-status.md

@@ -0,0 +1,17 @@
+---
+type: Architecture
+title: Bad status
+description: Fixture for invalid status
+status: canonical
+generated:
+  by: process:test
+  at: '2026-08-22T00:00:00Z'
+document_type: architecture
+sources:
+  - resource: repository:fixture
+related:
+  - docs/architecture/bad-status.md
+---
+# Purpose
+
+# Target

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

@@ -0,0 +1,8 @@
+version: "1"
+common_required: [type, title, description, status, generated]
+profiles:
+  - type: Architecture
+    paths: [docs/architecture/**]
+    document_type: architecture
+    required: [sources, related]
+    headings: [[Purpose], [Target]]

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

@@ -0,0 +1,49 @@
+"""DOC-006 — ported from `compliance_new/checks/docs/okf-profile/test.sh`.
+
+Two fixtures, matching the shell version's exact scenarios: a compliant
+Architecture page, and one with an invalid `status` value. Each corpus carries
+its own cut-down profile register, passed as the `profiles` input override —
+the packaged production register is not what these two scenarios are about.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from adl_compliance import runner
+from adl_compliance.core.verdict import Outcome
+from adl_compliance.policy.registry import load
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+ROW = load().by_id("DOC-006")
+
+
+def run(case: str) -> object:
+    directory = FIXTURES / case
+    given = tuple(
+        str(p.relative_to(directory))
+        for p in directory.rglob("*.md")
+    )
+    return runner.run(
+        ROW, directory, given,
+        inputs={ROW.id: {"profiles": directory / "docs-okf-profiles.yaml"}},
+    )
+
+
+def test_a_compliant_architecture_page_passes() -> None:
+    verdict = run("okf-profile-clean")
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_an_invalid_status_value_is_reported() -> None:
+    verdict = run("okf-profile-violation")
+    assert verdict.outcome is Outcome.FINDINGS
+    assert any("invalid OKF status" in f.message for f in verdict.findings), verdict.render()
+
+
+def test_no_set_is_could_not_run() -> None:
+    verdict = runner.run(
+        ROW, FIXTURES / "okf-profile-violation", (), exhaustive=True,
+        inputs={ROW.id: {"profiles": FIXTURES / "okf-profile-violation" / "docs-okf-profiles.yaml"}},
+    )
+    assert verdict.outcome is Outcome.COULD_NOT_RUN

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

@@ -0,0 +1,159 @@
+"""`docs/compliance/gaps/gap-register.yaml` and its sibling
+`security-findings-register.yaml` — the two compliance registers graded by a
+`docs` gate (`docs.semantics`, field-level) and a `layout` gate
+(`layout.docs-layout`, existence-only), neither ported yet.
+
+Not a check. It lives beside `checks/docs/register.py`'s only precedent in this
+package, `checks/coverage/register.py`: two gates read one document, so one
+strict model is declared once and both import it — `docs.semantics` as
+`from ..register import ...` and `layout.docs-layout` as
+`from ...docs.register import ...`. A second, independently-declared model
+over the same YAML would disagree with this one the moment either check grew a
+field, exactly as `checks/coverage/register.py`'s docstring records for
+`COV-002`/`COV-003`.
+
+This is the one genuinely CROSS-domain register in the estate — every other
+shared document (the coverage register, the Rust policy JSON) is read by two
+checks that already share a domain. `core/` holds no precedent for a register
+like this: every module there (`models`, `context`, `check`, `finding`,
+`errors`, `scope`, `verdict`) is package framework with no domain content of
+its own, and putting compliance's own YAML schema there would mean framework
+code importing subject matter it does not grade. `docs` is chosen over
+`layout` as the home because `docs.semantics` is the gate that actually reads
+every field below; `layout.docs-layout` only confirms the two files parse.
+
+Both models are transcribed from the documents on disk at
+`docs/compliance/gaps/{gap-register,security-findings-register}.yaml`
+(2026-08-29), not from either check's shell predecessor:
+
+  - `check-docs-semantics.sh`'s `check_yaml_records` grades every gap record
+    against `owner risk status evidence review_frequency retention source
+    remediation remediation_link` and forbids `duration objective
+    exit_criteria staffing phases`; it does not touch the security-findings
+    register at all.
+  - `check-docs-layout.sh` grades neither register's fields — it only asserts
+    that `docs/compliance/gaps/gap-register.yaml` and
+    `docs/compliance/gaps/security-findings-register.yaml` exist as files.
+
+`GapRegister` therefore matches every field the semantics gate actually reads,
+plus the metadata/summary envelope every one of the 203 current records
+carries identically. `SecurityFindingsRegister` matches the full document shape
+even though no ported check yet reads a field of it, because the shared model
+is the point: a future `docs.semantics` extension and `layout.docs-layout`
+both grade the same schema, never two.
+
+Every list-typed field carries `strict=False`, the same escape hatch
+`checks/coverage/register.py` documents on `acceptedFormats`: `StrictModel`'s
+`strict=True` means a parsed YAML `list` is not a valid `tuple` on its own, so
+without it every list field here would reject the very documents it exists to
+read.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+from ...core.models import StrictModel
+
+
+class GapMetadata(StrictModel):
+    title: str
+    assessment_date: str
+    source_matrix: str
+    canonical_artifacts: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+    maintenance_rule: str
+
+
+class GapSummary(StrictModel):
+    total_gaps: int
+    open: int
+    closed: int
+    partial_design_controls: int
+    controls_without_sufficient_repository_evidence: int
+
+
+class GapRecord(StrictModel):
+    """One entry under `gaps:`. Every field here is required because all 203
+    current records carry all twelve — `check_yaml_records` grades nine of them
+    (`owner risk status evidence review_frequency retention source remediation
+    remediation_link`) plus `id`; `control_id`/`framework`/`title` are read by
+    no gate yet but are present on every record and are not optional data.
+    """
+
+    id: str
+    control_id: str
+    framework: str
+    title: str
+    owner: str
+    risk: str
+    status: str
+    evidence: str
+    review_frequency: str
+    retention: str
+    source: str
+    remediation: str
+    remediation_link: str
+
+
+class GapRegister(StrictModel):
+    schema_version: str
+    metadata: GapMetadata
+    summary: GapSummary
+    gaps: Annotated[tuple[GapRecord, ...], Field(min_length=1, strict=False)]
+
+
+class SecurityFindingsMetadata(StrictModel):
+    title: str
+    assessment_date: str
+    assessment_type: str
+    scope: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+    limitations: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+    related_artifacts: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+
+
+class SeverityCounts(StrictModel):
+    critical: int
+    high: int
+    medium: int
+    low: int
+
+
+class ComponentCounts(StrictModel):
+    enact_backend: int
+    enact_agent_rs: int
+    enact_frontend: int
+
+
+class SecurityFindingsSummary(StrictModel):
+    total_findings: int
+    by_severity: SeverityCounts
+    by_component: ComponentCounts
+
+
+class SecurityFinding(StrictModel):
+    """One entry under `findings:`. `remediation_slice` is genuinely optional —
+    of the 18 current findings, 9 carry a string value, 3 (e.g. `SEC-BE-011`)
+    set it explicitly `null`, and 6 (e.g. `SEC-BE-003`) omit the key entirely,
+    so the default is what a strict, key-required field would reject on those
+    six.
+    """
+
+    id: str
+    severity: str
+    component: str
+    title: str
+    location: str
+    related_controls: Annotated[tuple[str, ...], Field(min_length=1, strict=False)]
+    remediation_slice: str | None = None
+    status: str
+    evidence: str
+    remediation: str
+
+
+class SecurityFindingsRegister(StrictModel):
+    schema_version: str
+    metadata: SecurityFindingsMetadata
+    summary: SecurityFindingsSummary
+    findings: Annotated[tuple[SecurityFinding, ...], Field(min_length=1, strict=False)]

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

@@ -0,0 +1,12 @@
+"""The `docs.semantics` gate.
+
+A folder rather than a module because this gate GRADES DOCUMENTS, and they
+belong beside the check that reads them. `check.py` is the rule; the fixtures
+are what it grades.
+"""
+
+from __future__ import annotations
+
+from .check import DocsSemantics
+
+__all__ = ["DocsSemantics"]