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

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

@@ -0,0 +1,140 @@
+"""DOC-004 — a collection's catalog must move with its pages.
+
+Each of docs/{architecture,research,compliance,operations}/ owns exactly one
+catalog: docs/<collection>/index.md. If the given set adds, renames, or
+modifies a page in a collection -- or modifies a page the catalog does not yet
+declare -- then that collection's index.md must be part of the SAME given set,
+or the catalog has silently drifted one change at a time.
+
+Scope per collection: `*.md`, plus `*.yaml`/`*.yml` registers under
+docs/compliance/. Excluded: the collection index.md itself, AGENTS.md /
+CLAUDE.md control files, and docs/architecture/product/ (hand-maintained
+outside the catalog contract).
+
+  graded    the given set is the whole rule. There is no `structural` probe:
+            an absent catalog reads as "declares nothing", the same as the
+            shell version's `declared_targets` returning an empty set for a
+            missing index.md, so a page changing while its catalog is simply
+            gone is still reported through the normal "not declared" path.
+
+Ported from compliance_new/checks/docs/index-updated/check.sh. That script's
+own history note applies here too: there used to be a `--staged` mode and a
+`--paths` mode, and the second survived only because the first read `git`
+for per-path statuses (A/R/D/M). With the set arriving from outside carrying
+no statuses, both modes had already collapsed into the one rule that never
+needed a status -- a path is a trigger when its collection's catalog does not
+declare it -- and that is the only rule ported here. The "page left the
+collection" / REMOVE-the-entry branch documented in that script as dead code
+in production (`removal=True`, never constructed) is not carried over either.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from pathlib import Path
+from typing import ClassVar
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+
+
+class IndexUpdated(Check):
+    id: ClassVar[str] = "DOC-004"
+    rule: ClassVar[str] = "DOC-004"
+
+    inputs: ClassVar[dict[str, str]] = {"docs_root": "<docs>"}
+    """FIXED 2026-09-16 (K-42 sweep, SILENT form, approved): every path below
+    was built or matched against a hardcoded `docs/...` literal --
+    `_collection_of`'s `parts[0] != "docs"` membership test, `index_rel`'s
+    f-string, and `_declared_targets`' own f-string. A repository declaring a
+    different docs root had every real page's `_collection_of` return `None`,
+    so `triggers` stayed empty for every collection and the gate reported
+    clean having examined nothing -- the same shape `CONTENT` had in
+    `docs.semantics`."""
+
+    COLLECTIONS: ClassVar[tuple[str, ...]] = (
+        "architecture",
+        "research",
+        "compliance",
+        "operations",
+    )
+    EXCLUDED_NAMES: ClassVar[frozenset[str]] = frozenset(
+        {"AGENTS.md", "CLAUDE.md", "index.md", "index.mdx"}
+    )
+    EXEMPT_SUBTREES: ClassVar[dict[str, tuple[str, ...]]] = {"architecture": ("product",)}
+
+    LINK: ClassVar[re.Pattern[str]] = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        docs_root = ctx.relative(ctx.inputs["docs_root"])
+        changed: set[str] = set()
+        # Each entry: a path this rule considers "changed and possibly
+        # undeclared" for that collection. The shell version's tuple also
+        # carried a reason string and a removal flag; the reason is fixed (this
+        # rule has exactly one), and removal is never True (see module docstring).
+        triggers: dict[str, list[str]] = {collection: [] for collection in self.COLLECTIONS}
+        declared_cache: dict[str, set[str]] = {}
+
+        for raw in files:
+            rel = raw.replace("\\", "/").strip()
+            if not rel:
+                continue
+            changed.add(rel)
+            collection = self._collection_of(docs_root, rel)
+            if collection is None or not self._in_scope(docs_root, collection, rel):
+                continue
+            if collection not in declared_cache:
+                declared_cache[collection] = self._declared_targets(ctx, docs_root, collection)
+            inner = Path(rel).relative_to(Path(docs_root) / collection).as_posix()
+            if inner not in declared_cache[collection]:
+                triggers[collection].append(rel)
+
+        for collection in self.COLLECTIONS:
+            if not triggers[collection]:
+                continue
+            index_rel = f"{docs_root}/{collection}/index.md"
+            if index_rel in changed:
+                continue
+            for rel in triggers[collection]:
+                yield self.report(
+                    rel,
+                    f"{collection} catalog {index_rel} not updated "
+                    "(modified and not declared in the catalog)",
+                    f"add {rel} to {index_rel} in this same change",
+                )
+
+    def _collection_of(self, docs_root: str, rel: str) -> str | None:
+        parts = rel.split("/")
+        if len(parts) < 3 or parts[0] != docs_root or parts[1] not in self.COLLECTIONS:
+            return None
+        return parts[1]
+
+    def _in_scope(self, docs_root: str, collection: str, rel: str) -> bool:
+        parts = Path(rel).relative_to(Path(docs_root) / collection).parts
+        if Path(rel).name in self.EXCLUDED_NAMES:
+            return False
+        exempt = self.EXEMPT_SUBTREES.get(collection, ())
+        if parts and parts[0] in exempt:
+            return False
+        suffix = Path(rel).suffix
+        if suffix == ".md":
+            return True
+        return suffix in {".yaml", ".yml"} and collection == "compliance"
+
+    def _declared_targets(self, ctx: Context, docs_root: str, collection: str) -> set[str]:
+        body = self.text(ctx, f"{docs_root}/{collection}/index.md")
+        if body is None:
+            return set()
+        targets: set[str] = set()
+        for match in self.LINK.finditer(body):
+            target = match.group(2).strip()
+            if target.startswith(("http://", "https://", "mailto:", "#", "/", "../")):
+                continue
+            target = target.split("#", 1)[0].strip().replace("\\", "/")
+            if target.startswith("./"):
+                target = target[2:]
+            if target:
+                targets.add(target)
+        return targets

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/index_updated/fixtures/index-updated-clean/docs/architecture/foo.md

@@ -0,0 +1,7 @@
+---
+title: Foo
+---
+
+# Foo
+
+A page in the architecture collection its catalog already declares.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/index_updated/fixtures/index-updated-clean/docs/architecture/index.md

@@ -0,0 +1,10 @@
+---
+title: Architecture catalog
+description: Fixture catalog that already lists foo.md.
+---
+
+# Architecture catalog
+
+| Page | Summary |
+| --- | --- |
+| [Foo](foo.md) | already declared |

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/index_updated/fixtures/index-updated-violation/docs/architecture/foo.md

@@ -0,0 +1,7 @@
+---
+title: Foo
+---
+
+# Foo
+
+A page in the architecture collection that its catalog does not yet declare.

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/docs/index_updated/fixtures/index-updated-violation/docs/architecture/index.md

@@ -0,0 +1,9 @@
+---
+title: Architecture catalog
+description: Fixture catalog that does not yet list foo.md.
+---
+
+# Architecture catalog
+
+| Page | Summary |
+| --- | --- |

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

@@ -0,0 +1,98 @@
+"""DOC-004 — a collection's catalog must move with its pages.
+
+Ported from compliance_new/checks/docs/index-updated/test.sh, whose three
+rule assertions this mirrors one-for-one against the same committed corpora:
+a page changed without its catalog is a finding; the same violating corpus is
+silent once the catalog is in the same given set; and a corpus whose catalog
+already declares the page is silent even though the catalog itself never
+appears in the set.
+
+Not ported: `test.sh`'s fourth case (`ADL_CHANGED_FILES` unset -> exit 2)
+and its closing `dispatch_contract` call. Both are shell-runner plumbing --
+"no set given" and "the row resolves" -- with no equivalent at the `Check`
+level here: `graded(ctx, files)` is always handed a `FileSet`, and row
+resolution is `policy.registry`'s job, exercised by its own tests.
+"""
+
+from __future__ import annotations
+
+from helpers import corpus, verdict_for
+
+from adl_compliance.core.verdict import Outcome
+
+CORPORA = corpus("docs", "index-updated")
+
+
+def test_a_changed_page_without_its_catalog_is_reported() -> None:
+    """foo.md changed, its catalog does not declare it, and the catalog itself
+    is not in this given set."""
+    verdict = verdict_for(
+        "DOC-004", CORPORA / "index-updated-violation", given=("docs/architecture/foo.md",)
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert (
+        "DOC-004 docs/architecture/foo.md: architecture catalog "
+        "docs/architecture/index.md not updated" in verdict.render()
+    )
+
+
+def test_the_catalog_moving_in_the_same_set_is_not_reported() -> None:
+    """Same corpus, same violation on disk -- but the catalog is also in the
+    given set, which this rule reads as "being handled in this change"."""
+    verdict = verdict_for(
+        "DOC-004",
+        CORPORA / "index-updated-violation",
+        given=("docs/architecture/foo.md", "docs/architecture/index.md"),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_page_already_declared_in_its_catalog_is_not_reported() -> None:
+    """foo.md changed, but its catalog already declares it -- the catalog
+    itself need not be in the set at all."""
+    verdict = verdict_for(
+        "DOC-004", CORPORA / "index-updated-clean", given=("docs/architecture/foo.md",)
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_redeclared_docs_tree_is_still_graded(tmp_path) -> None:
+    """The SILENT false pass this check shipped with.
+
+    `_collection_of`'s `parts[0] != "docs"` membership test, plus `index_rel`
+    and `_declared_targets`' own `docs/...` f-strings, all assumed the
+    packaged default. A repository declaring `docs = "documentation"` had
+    every real page's `_collection_of` return `None` -- `triggers` stayed
+    empty for every collection, and the gate reported clean having examined
+    nothing. It was ARMED in exactly that state on enact-m5 and
+    enact-repo-controls-m5 (both declare `docs = "docs"`, so the literal was
+    accidentally correct there).
+
+    Same corpus shape as `index-updated-violation`, committed again under
+    `documentation/` instead of `docs/`: a real page changed, its catalog
+    does not declare it, and the catalog itself is not in this given set --
+    ungraded before the fix, caught after."""
+    import shutil
+
+    import yaml
+
+    from adl_compliance import runner
+    from adl_compliance.policy.registry import Registry, effective_trees, policy_text
+
+    corpus = CORPORA / "index-updated-violation"
+    root = tmp_path / "repo"
+    shutil.copytree(corpus / "docs", root / "documentation")
+
+    trees = {"docs": "documentation"}
+    document = yaml.safe_load(policy_text("gate-registry.yaml"))
+    registry = Registry.model_validate(document, context={"trees": trees})
+    row = registry.by_id("DOC-004")
+
+    verdict = runner.run(
+        row, root, ("documentation/architecture/foo.md",), trees=effective_trees(trees),
+    )
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert (
+        "DOC-004 documentation/architecture/foo.md: architecture catalog "
+        "documentation/architecture/index.md not updated" in verdict.render()
+    ), verdict.render()

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

@@ -0,0 +1,12 @@
+"""The `docs.indexes` gate.
+
+A folder rather than a module because this gate GRADES A DOCUMENT (the
+registered-index register, `docs-knowledge-indexes.yaml`) and that document
+belongs beside the check that reads it.
+"""
+
+from __future__ import annotations
+
+from .check import Indexes
+
+__all__ = ["Indexes"]

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

@@ -0,0 +1,378 @@
+"""DOC-008 — every registered knowledge index matches the pages it governs.
+
+Ported from `compliance_new/checks/docs/indexes/check.sh`
+(`compliance/checks/documentation/check-knowledge-indexes.sh` in the shell
+tree's own comments). One rule id, `KNW-001`, covering several distinct
+defects against `docs-knowledge-indexes.yaml`'s registered catalogues:
+
+  * the register itself is missing, invalid, or names a duplicate id/path;
+  * a registered index file, or its governed root, is absent;
+  * the index file (when it is itself in the given set) is missing a required
+    frontmatter field or a required section heading;
+  * the index's catalogue table omits a governed page, lists one outside the
+    governed inventory, or lists the same page twice.
+
+The register is POLICY THIS PACKAGE OWNS: it defines which catalogues exist in
+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).
+
+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
+all (`_affected`), and the inventory comparison IS the given set narrowed to a
+governed root, never a directory walk. There is no `structural` probe: the
+shell version's own comment is explicit that scope arithmetic is the runner's,
+never the check's (K-09, K-29..K-31), and that holds just as much for "which
+registry entries are even in play" as for "which files are in a page's
+inventory".
+
+Two things this port keeps rather than "fixes", because they are exactly what
+the shell script did and no fixture exercises the alternative:
+
+  * A required-section heading is matched as a RAW (unescaped) regex fragment,
+    exactly as the shell version's `rg -qi "^#+[[:space:]]+${heading}[[:space:]]*$"`
+    did — a heading containing a regex metacharacter would behave as a pattern,
+    not a literal. No shipped registry entry's heading contains one.
+  * The shell version's frontmatter extraction can only ever find a block when
+    line 1 is exactly `---`; anything else leaves its temp file empty, which the
+    shell pipeline (`yq -o=json '.' | jq '... has($field) ...'`) would then fail
+    on hard (`null` has no keys) under `set -euo pipefail`. No committed fixture
+    triggers that path. This port treats "no parseable frontmatter block" as
+    every required field being absent — reported, not a crash — which is
+    strictly more informative and never fires on a conforming document.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+import yaml
+
+from ....core.check import Check
+from ....core.context import Context, FileSet
+from ....core.finding import Report
+
+@dataclass(frozen=True)
+class _Entry:
+    """One `indexes[]` row, extracted the way the shell version's `jq`
+    projection did: named fields, with the same defaults (`recursive` false,
+    `inventory` "exact") for whatever the document omits."""
+
+    id: str
+    path: str
+    kind: str
+    root: str
+    recursive: bool = False
+    inventory: str = "exact"
+    extensions: tuple[str, ...] = field(default_factory=tuple)
+    excludes: tuple[str, ...] = field(default_factory=tuple)
+    frontmatter: tuple[str, ...] = field(default_factory=tuple)
+    sections: tuple[str, ...] = field(default_factory=tuple)
+
+
+class Indexes(Check):
+    id: ClassVar[str] = "DOC-008"
+    rule: ClassVar[str] = "KNW-001"
+
+    resources: ClassVar[dict[str, str]] = {"registry": "docs-knowledge-indexes.yaml"}
+
+    LINK: ClassVar[re.Pattern[str]] = re.compile(r"\]\(([^)]*)\)")
+    SCHEME: ClassVar[re.Pattern[str]] = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*://")
+    IGNORED_NAMES: ClassVar[frozenset[str]] = frozenset({"index.md", "AGENTS.md", "CLAUDE.md"})
+
+    def graded(self, ctx: Context, files: FileSet) -> Iterable[Report]:
+        registry_path = ctx.inputs["registry"]
+        shown = ctx.relative(registry_path)
+
+        body = self.text(ctx, registry_path)
+        if body is None:
+            yield self.report(
+                shown,
+                "required index registry is missing",
+                f"create {shown} with a schema_version and at least one index entry",
+            )
+            return
+
+        entries = self._parse(body)
+        if entries is None:
+            yield self.report(
+                shown,
+                "invalid registry schema",
+                f"set schema_version: 1 and a non-empty indexes list in {shown}",
+            )
+            return
+
+        yield from self._duplicate_ids_or_paths(shown, entries)
+
+        given = tuple(files)
+        given_set = set(given)
+        for entry in entries:
+            yield from self._grade_entry(ctx, shown, entry, given, given_set)
+
+    # ------------------------------------------------------------- the registry
+
+    def _parse(self, body: str) -> tuple[_Entry, ...] | None:
+        try:
+            loaded = yaml.safe_load(body)
+        except yaml.YAMLError:
+            return None
+        if not isinstance(loaded, dict):
+            return None
+        if loaded.get("schema_version") != 1:
+            return None
+        raw_indexes = loaded.get("indexes")
+        if not isinstance(raw_indexes, list) or len(raw_indexes) == 0:
+            return None
+
+        entries: list[_Entry] = []
+        for item in raw_indexes:
+            if not isinstance(item, dict):
+                continue
+            entries.append(
+                _Entry(
+                    id=str(item.get("id", "")),
+                    path=str(item.get("path", "")),
+                    kind=str(item.get("kind", "")),
+                    root=str(item.get("root", "")),
+                    recursive=bool(item.get("recursive", False)),
+                    inventory=str(item.get("inventory") or "exact"),
+                    extensions=tuple(item.get("include_extensions") or ()),
+                    excludes=tuple(item.get("exclude_prefixes") or ()),
+                    frontmatter=tuple(item.get("required_frontmatter") or ()),
+                    sections=tuple(item.get("required_sections") or ()),
+                )
+            )
+        return tuple(entries)
+
+    def _duplicate_ids_or_paths(self, shown: str, entries: tuple[_Entry, ...]) -> Iterable[Report]:
+        for label, values in (
+            ("id", [e.id for e in entries]),
+            ("path", [e.path for e in entries]),
+        ):
+            for duplicate in self._duplicates(values):
+                yield self.report(
+                    shown,
+                    f"duplicate {label} {duplicate}",
+                    f"remove or rename the duplicate entry '{duplicate}' in {shown}",
+                )
+
+    @staticmethod
+    def _duplicates(values: Iterable[str]) -> list[str]:
+        counts: dict[str, int] = {}
+        for value in values:
+            counts[value] = counts.get(value, 0) + 1
+        return sorted(value for value, count in counts.items() if count > 1)
+
+    # --------------------------------------------------------------- one entry
+
+    def _grade_entry(
+        self,
+        ctx: Context,
+        shown: str,
+        entry: _Entry,
+        given: tuple[str, ...],
+        given_set: set[str],
+    ) -> Iterable[Report]:
+        index = entry.path
+        governed = entry.root
+
+        # An entry nothing in the given set touches is not audited at all —
+        # set logic, not phase logic (see module docstring).
+        if not self._affected(given_set, index, governed):
+            return
+
+        if not ctx.path(index).is_file():
+            yield self.report(
+                index,
+                "registered index is missing",
+                f"create {index}, or remove its entry from {shown}",
+            )
+            return
+
+        if not ctx.path(governed).is_dir():
+            yield self.report(
+                index,
+                f"governed root is missing: {governed}",
+                f"create the governed root directory {governed}, or update the "
+                "registry entry to the correct root",
+            )
+
+        index_dir = index.rsplit("/", 1)[0] if "/" in index else ""
+        if index_dir:
+            index_dir += "/"
+
+        # Frontmatter and section headings are properties of the index FILE,
+        # so they are checked exactly when that file is itself in the given set.
+        if index in given_set:
+            yield from self._grade_index_document(ctx, index, entry)
+
+        if entry.inventory == "exempt":
+            return
+
+        actual = self._actual(ctx, given, entry)
+        declared_raw = self._declared_raw(ctx, index, index_dir, entry, given_set)
+        declared = sorted(set(declared_raw))
+
+        for missing in sorted(set(actual) - set(declared)):
+            yield self.report(
+                index,
+                f"catalog missing {missing}",
+                f"add an entry for {missing} to the catalog table in {index}",
+            )
+        for extra in sorted(set(declared) - set(actual)):
+            yield self.report(
+                index,
+                f"catalog entry is outside inventory {extra}",
+                f"remove the catalog entry for {extra} from {index}, or move {extra} under {governed}",
+            )
+        for duplicate in self._duplicates(declared_raw):
+            yield self.report(
+                index,
+                f"duplicate catalog entry {duplicate}",
+                f"remove the duplicate catalog entry {duplicate} from {index}",
+            )
+
+    @staticmethod
+    def _affected(given_set: set[str], index: str, governed: str) -> bool:
+        if index in given_set:
+            return True
+        prefix = governed + "/"
+        return any(p.startswith(prefix) for p in given_set)
+
+    # ---------------------------------------------------------- the index file
+
+    def _grade_index_document(self, ctx: Context, index: str, entry: _Entry) -> Iterable[Report]:
+        body = self.text(ctx, index)
+        if body is None:
+            return
+        frontmatter = self._frontmatter(body)
+        for field_name in entry.frontmatter:
+            value = frontmatter.get(field_name) if frontmatter else None
+            if value in (None, "", []):
+                yield self.report(
+                    index,
+                    f"missing required frontmatter field {field_name}",
+                    f"add the '{field_name}' frontmatter field to {index}",
+                )
+        for heading in entry.sections:
+            if not self._has_heading(body, heading):
+                yield self.report(
+                    index,
+                    f"missing required section {heading}",
+                    f"add a '{heading}' section heading to {index}",
+                )
+
+    def _has_heading(self, body: str, heading: str) -> bool:
+        pattern = re.compile(rf"#+[ \t]+{heading}[ \t]*", re.IGNORECASE)
+        return any(pattern.fullmatch(line) for line in body.splitlines())
+
+    @staticmethod
+    def _frontmatter(body: str) -> dict[str, object] | None:
+        lines = body.splitlines()
+        if not lines or lines[0].strip() != "---":
+            return None
+        for offset, line in enumerate(lines[1:], start=1):
+            if line.strip() != "---":
+                continue
+            try:
+                loaded = yaml.safe_load("\n".join(lines[1:offset]))
+            except yaml.YAMLError:
+                return None
+            return loaded if isinstance(loaded, dict) else None
+        return None
+
+    # -------------------------------------------------------------- inventory
+
+    def _actual(self, ctx: Context, given: tuple[str, ...], entry: _Entry) -> list[str]:
+        governed = entry.root
+        prefix = governed + "/"
+        out: list[str] = []
+        for path in given:
+            if not path.startswith(prefix):
+                continue
+            relative = path[len(prefix) :]
+            if not entry.recursive and "/" in relative:
+                continue
+            if not ctx.path(path).is_file():
+                continue
+            name = path.rsplit("/", 1)[-1]
+            if name in self.IGNORED_NAMES:
+                continue
+            if not self._ext_included(entry.extensions, name):
+                continue
+            if self._is_excluded(entry.excludes, relative):
+                continue
+            out.append(path)
+        return sorted(set(out))
+
+    def _declared_raw(
+        self,
+        ctx: Context,
+        index: str,
+        index_dir: str,
+        entry: _Entry,
+        given_set: set[str],
+    ) -> list[str]:
+        body = self.text(ctx, index)
+        if body is None:
+            return []
+        governed = entry.root
+        out: list[str] = []
+        for line in body.splitlines():
+            if entry.kind == "documentation-catalog" and "|" not in line:
+                continue
+            for match in self.LINK.finditer(line):
+                target = self._resolve_link(ctx, index_dir, match.group(1))
+                if target is None:
+                    continue
+                target_name = target.rsplit("/", 1)[-1]
+                if target_name in self.IGNORED_NAMES:
+                    continue
+                # BOTH sides of the comparison are restricted to the given
+                # set, or they are not comparable (see module docstring).
+                if target not in given_set:
+                    continue
+                relative = (
+                    target[len(governed) + 1 :]
+                    if target.startswith(governed + "/")
+                    else target
+                )
+                if self._is_excluded(entry.excludes, relative):
+                    continue
+                if not self._ext_included(entry.extensions, target_name):
+                    continue
+                if entry.kind == "specification-family":
+                    parent = target.rsplit("/", 1)[0] if "/" in target else target
+                    if parent != governed:
+                        continue
+                out.append(target)
+        return out
+
+    def _resolve_link(self, ctx: Context, index_dir: str, raw: str) -> str | None:
+        if raw.startswith("<"):
+            raw = raw[1:]
+        if raw.endswith(">"):
+            raw = raw[:-1]
+        raw = raw.split("#", 1)[0]
+        if raw.startswith("./"):
+            raw = raw[2:]
+        if not raw or raw.startswith("/") or self.SCHEME.match(raw):
+            return None
+        for candidate in (index_dir + raw, index_dir + raw + ".md", index_dir + raw + "/index.md"):
+            if ctx.path(candidate).is_file():
+                return candidate
+        return None
+
+    @staticmethod
+    def _ext_included(extensions: tuple[str, ...], name: str) -> bool:
+        return "." + name.rsplit(".", 1)[-1] in extensions
+
+    @staticmethod
+    def _is_excluded(excludes: tuple[str, ...], relative: str) -> bool:
+        return any(prefix and relative.startswith(prefix) for prefix in excludes)