feat: drift checker additional checks and policy data (Phase 2 Session B) (#8)

Adds the three remaining checks from the Phase 2 design:
broken-refs, required-refs, and stale-counts. Each is a full
Check implementation per the Session A Protocol, even where the
current ecosystem surface is minimal. Extends RepoSnapshot with
meta_standards and meta_required_refs carry-alongs so checks can
resolve against meta-repo policy without a back-channel.

Ships supporting policy data:
- standards/drift-checker.config.json (expanded: globals/types/repos)
- standards/required-refs.json (new; mostly empty per Q2 audit)
- standards/versioning.md (new section on MAJOR/MINOR/PATCH
  semantics for ecosystem standards)

Adds report/gh_summary.py for GitHub Actions step-summary output
(details folds per repo, emoji severity). Wired into cli.py as
--format gh-summary. Session C will wire this into CI.

Preflight audits the full ecosystem (9 repos, 13 agent-context
files) and confirms:
- Zero standards/*.md links exist today -> broken-refs and
  required-refs both silent.
- Aggregate-count narrative exists in 8 of 9 repos, producing
  ~62 stale-counts warnings (warn severity, non-blocking).
- Version-signal still reports the expected 261 MAJOR.MINOR
  drift errors (tool repos at 1.6.3, meta at 1.7.1) that
  Session D mechanically clears.

Also fixes a Session A test coupling: CLI tests now pass a
tmp meta-repo via --meta-repo instead of reading the real
VERSION, so fixture values are stable across meta-repo bumps.

VERSION: 1.7.0 -> 1.7.1. Called PATCH per handoff guidance, but
flagged as defensibly MINOR: the new checks surface warnings on
existing tool-repo content (aggregate narrative), which tool
repos will have to reconcile during the Session D rollout. No
contract-breaking changes to the Session A Protocol or CLI
surface. See PR body for the discussion.

See #1 Phase 2 Session B.

Signed-off-by: 154358121+TMHSDigital@users.noreply.github.com
Made-with: Cursor

Signed-off-by: 154358121+TMHSDigital@users.noreply.github.com

Author: TMHSDigital

VERSION

@@ -1 +1 @@
-1.7.0
+1.7.1

scripts/drift_check/checks/__init__.py

@@ -1,7 +1,17 @@
-"""Registered checks live here. Session A ships ``version_signal`` only.
+"""Registered checks live here.
 
-Session B will add ``broken_refs``, ``required_refs``, ``stale_counts``.
+Session A shipped ``version_signal``. Session B adds ``broken_refs``,
+``required_refs``, and ``stale_counts``. Phase 3 will add more via the
+same ``Check`` Protocol from ``types.py``.
 """
+from .broken_refs import BrokenRefsCheck
+from .required_refs import RequiredRefsCheck
+from .stale_counts import StaleCountsCheck
 from .version_signal import VersionSignalCheck
 
-__all__ = ["VersionSignalCheck"]
+__all__ = [
+    "VersionSignalCheck",
+    "BrokenRefsCheck",
+    "RequiredRefsCheck",
+    "StaleCountsCheck",
+]

scripts/drift_check/checks/broken_refs.py

@@ -0,0 +1,134 @@
+"""Broken standards/*.md references check.
+
+Scans every markdown file in the snapshot for links whose targets live
+under ``standards/``. Resolves each target against the meta-repo's
+``standards/`` directory at snapshot time. Missing target -> ``error``.
+
+Zero surface today — the design-doc preflight found 0 ``standards/*.md``
+links across 13 agent-context files in 9 repos. The check is implemented
+anyway so the plumbing is in place the moment tool repos start linking
+to standards.
+
+Link shapes we care about:
+
+* ``[text](standards/foo.md)``
+* ``[text](standards/foo.md#anchor)`` — fragment checking deferred; we
+  only verify the file exists for now
+* ``[text](../Developer-Tools-Directory/standards/foo.md)`` — tolerated
+  by stripping to the trailing ``standards/foo.md``
+* reference-style ``[text][label]`` + ``[label]: standards/foo.md`` —
+  the label-definition regex below catches these
+* bare URLs to GitHub-hosted standards are NOT checked; contribute
+  a separate check for those when/if they appear
+
+We do NOT follow non-``standards/`` links. That is out of scope for this
+check; it would duplicate a general markdown link checker.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable, List, Tuple
+
+from ..types import Finding, RepoSnapshot
+
+
+NAME = "broken-refs"
+
+# Inline link: ``[text](target)`` where target starts with or contains
+# ``standards/`` and ends with ``.md`` (with optional ``#fragment``).
+_INLINE_LINK_RE = re.compile(
+    rb"\[[^\]]*\]\(\s*([^)\s]*standards/[^)\s#]+\.md(?:#[^)\s]*)?)\s*\)"
+)
+# Reference-style definition: ``[label]: standards/foo.md``
+_REF_DEF_RE = re.compile(
+    rb"^\s*\[[^\]]+\]:\s*([^\s]*standards/[^\s#]+\.md(?:#[^\s]*)?)\s*$",
+    re.MULTILINE,
+)
+
+
+def _iter_standards_links(content: bytes) -> Iterable[Tuple[str, int]]:
+    """Yield ``(target, line_number)`` for every standards link in the
+    file. ``target`` is a decoded string; ``line_number`` is 1-indexed."""
+    for m in _INLINE_LINK_RE.finditer(content):
+        yield m.group(1).decode("utf-8", errors="replace"), content.count(b"\n", 0, m.start()) + 1
+    for m in _REF_DEF_RE.finditer(content):
+        yield m.group(1).decode("utf-8", errors="replace"), content.count(b"\n", 0, m.start()) + 1
+
+
+def _extract_standard_filename(target: str) -> str | None:
+    """Given a link target, return the standards file basename or None.
+
+    ``standards/foo.md`` -> ``foo.md``
+    ``standards/foo.md#anchor`` -> ``foo.md``
+    ``../standards/foo.md`` -> ``foo.md``
+    ``https://github.com/.../standards/foo.md`` -> ``foo.md``
+    """
+    target = target.split("#", 1)[0]
+    marker = "standards/"
+    idx = target.rfind(marker)
+    if idx == -1:
+        return None
+    basename = target[idx + len(marker):].strip("/")
+    if not basename or not basename.endswith(".md"):
+        return None
+    if "/" in basename:
+        # Nested path under standards/. We only ship flat files in
+        # ``standards/``, so a nested path is a broken reference by
+        # construction.
+        return basename
+    return basename
+
+
+class BrokenRefsCheck:
+    name: str = NAME
+
+    def run(self, snapshot: RepoSnapshot) -> Iterable[Finding]:
+        if NAME in snapshot.config.skip_checks:
+            return ()
+
+        out: List[Finding] = []
+        meta_files = snapshot.meta_standards
+
+        for rel_path, file in snapshot.files.items():
+            pragma = next(
+                (p for p in file.pragmas if p.check_name == NAME), None
+            )
+            if pragma is not None:
+                out.append(
+                    Finding(
+                        repo=snapshot.slug,
+                        file=rel_path,
+                        check=NAME,
+                        severity="info",
+                        message=(
+                            "skipped by drift-ignore pragma"
+                            + (f" (reason: {pragma.reason})" if pragma.reason else "")
+                        ),
+                    )
+                )
+                continue
+
+            for target, line in _iter_standards_links(file.content):
+                basename = _extract_standard_filename(target)
+                if basename is None:
+                    continue
+                if basename not in meta_files:
+                    out.append(
+                        Finding(
+                            repo=snapshot.slug,
+                            file=rel_path,
+                            check=NAME,
+                            severity="error",
+                            message=(
+                                f"broken standards reference at line {line}: "
+                                f"{target!r} (standards/{basename} does not "
+                                f"exist in meta-repo)"
+                            ),
+                            suggested_fix=(
+                                f"check the filename; available standards: "
+                                f"{', '.join(sorted(meta_files)) or '(none found)'}"
+                            ),
+                        )
+                    )
+        return out

scripts/drift_check/checks/required_refs.py

@@ -0,0 +1,157 @@
+"""Required standards-references check (Q2 resolution: start permissive).
+
+For each repo, look up the per-type requirements from
+``standards/required-refs.json``. For each ``(file, required_ref)`` pair:
+
+* file missing in the repo -> ``error``
+* file present but lacks a link to the required standards doc -> ``error``
+* otherwise: silent
+
+Today the requirements block is empty (zero tool repos link to
+``standards/*.md``), so this check is silent in practice. The plumbing is
+ready for the moment that changes — at that point, add entries to
+``required-refs.json`` and the check immediately starts enforcing them
+without any code change.
+
+The loader is in this module rather than ``config.py`` to keep the data
+colocated with its consumer; it is only used here.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Iterable, List, Mapping, Sequence
+
+from ..types import Finding, RepoSnapshot
+
+
+NAME = "required-refs"
+
+
+class RequiredRefsError(Exception):
+    """Raised when required-refs.json is present but malformed."""
+
+
+def load_required_refs(path: Path | None) -> Mapping[str, Mapping[str, Sequence[str]]]:
+    """Load and validate ``standards/required-refs.json``.
+
+    Returns a mapping ``{repo_type: {filename: [required_ref, ...]}}``.
+    Missing file -> empty mapping. Malformed JSON or wrong schema ->
+    ``RequiredRefsError``.
+    """
+    if path is None or not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise RequiredRefsError(f"malformed JSON in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RequiredRefsError(f"{path}: expected object at root")
+    reqs = data.get("requirements", {})
+    if not isinstance(reqs, dict):
+        raise RequiredRefsError(f"{path}: 'requirements' must be an object")
+
+    out: dict[str, dict[str, list[str]]] = {}
+    for repo_type, file_map in reqs.items():
+        if not isinstance(file_map, dict):
+            raise RequiredRefsError(
+                f"{path}: requirements[{repo_type!r}] must be an object"
+            )
+        out[repo_type] = {}
+        for fname, refs in file_map.items():
+            if not isinstance(refs, list):
+                raise RequiredRefsError(
+                    f"{path}: requirements[{repo_type!r}][{fname!r}] must be a list"
+                )
+            out[repo_type][fname] = [str(r) for r in refs]
+    return out
+
+
+def _file_links_to(content: bytes, required_ref: str) -> bool:
+    """Return True if ``content`` contains any markdown link whose target
+    resolves to ``required_ref`` (matched by trailing basename)."""
+    basename = required_ref.split("/")[-1]
+    if not basename:
+        return False
+    # Match both inline and reference-style link targets that end with
+    # the required basename (optionally followed by #fragment or whitespace).
+    pattern = re.compile(
+        rb"standards/" + re.escape(basename.encode("utf-8")) + rb"(?:#[^\s)]*)?",
+    )
+    return pattern.search(content) is not None
+
+
+class RequiredRefsCheck:
+    name: str = NAME
+
+    def run(self, snapshot: RepoSnapshot) -> Iterable[Finding]:
+        if NAME in snapshot.config.skip_checks:
+            return ()
+
+        requirements = snapshot.meta_required_refs.get(snapshot.repo_type, {})
+        if not requirements:
+            return ()
+
+        out: List[Finding] = []
+        for file_name, required_refs in requirements.items():
+            if not required_refs:
+                continue
+            rel = Path(file_name)
+            file = snapshot.files.get(rel)
+
+            pragma = None
+            if file is not None:
+                pragma = next(
+                    (p for p in file.pragmas if p.check_name == NAME), None
+                )
+            if pragma is not None:
+                out.append(
+                    Finding(
+                        repo=snapshot.slug,
+                        file=rel,
+                        check=NAME,
+                        severity="info",
+                        message=(
+                            "skipped by drift-ignore pragma"
+                            + (f" (reason: {pragma.reason})" if pragma.reason else "")
+                        ),
+                    )
+                )
+                continue
+
+            if file is None:
+                out.append(
+                    Finding(
+                        repo=snapshot.slug,
+                        file=rel,
+                        check=NAME,
+                        severity="error",
+                        message=(
+                            f"{file_name} is required for {snapshot.repo_type} "
+                            f"repos but is not present"
+                        ),
+                        suggested_fix=(
+                            f"create {file_name} and link to "
+                            f"{', '.join(required_refs)}"
+                        ),
+                    )
+                )
+                continue
+
+            for ref in required_refs:
+                if not _file_links_to(file.content, ref):
+                    out.append(
+                        Finding(
+                            repo=snapshot.slug,
+                            file=rel,
+                            check=NAME,
+                            severity="error",
+                            message=(
+                                f"{file_name} must link to {ref} "
+                                f"(required for {snapshot.repo_type})"
+                            ),
+                            suggested_fix=f"add a link to {ref} in {file_name}",
+                        )
+                    )
+        return out