feat(assessors): add adr_frontmatter_completeness assessor with central ADR repo support (#512, #513)

Adds a new `adr_frontmatter_completeness` assessor (Tier 3, 2% weight) that
scores repos on whether ADR files contain structured YAML frontmatter with
required `status` and `applies_to` fields. Supports both local ADR directories
and a centrally maintained ADR repository via config.

## New assessor: adr_frontmatter_completeness

Scoring:
- ≥80% of ADR files have valid frontmatter → pass (100)
- 50–79% → partial/fail (60)
- <50% → fail (0)
- No ADR files found → skipped

Valid statuses cover MADR (Proposed, Accepted, Implementable, Implemented,
Replaced, Deprecated, Superseded, Approved) and adr-tools (active, superseded,
draft) conventions.

## Central ADR repository support

Configure via `.agentready-config.yaml`:

```yaml
adr_source:
  repo: /path/to/local/clone   # locally cloned central ADR repo
  path: ADR                    # relative path within that repo
```

When configured, ADRs are read from the central repo and filtered by their
`applies_to` frontmatter field matching the assessed repo name. Supports
wildcard (`"*"`), short name, full org/repo, and list matching.

No network calls — the central repo must be locally cloned. Gracefully skips
if the path does not exist or no ADRs match.

## Fix: architecture_decisions respects central ADR repos

`ArchitectureDecisionsAssessor` now passes when `adr_source` is configured and
the central repo path exists and contains ADRs that match the repo via
applies_to, rather than penalising repos that deliberately maintain ADRs
centrally.

## Weight rebalancing (Tier 3)

Added `adr_frontmatter_completeness: 0.02`. Funded by reducing
`architecture_decisions` (2% → 1%) and `progressive_disclosure` (2% → 1%).
Also synced `default_weight` values in ArchitectureDecisionsAssessor,
OpenAPISpecsAssessor, StructuredLoggingAssessor, and ProgressiveDisclosureAssessor
to match default-weights.yaml. Total weights remain 1.0.

## Shared utility module

Extracted `parse_frontmatter` into `assessors/_adr_utils.py` to avoid a
circular import between `adr_frontmatter` and `adr_sources`.

Closes #512, #513

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Dannyb48

src/agentready/assessors/__init__.py

@@ -6,6 +6,7 @@
 v2.0.0: Updated with evidence-based rebalancing (ETH Zurich, Red Hat, Anthropic).
 """
 
+from .adr_frontmatter import AdrFrontmatterAssessor
 from .base import BaseAssessor
 from .code_quality import (
     CyclomaticComplexityAssessor,
@@ -54,7 +55,12 @@
 )
 from .verification import SingleFileVerificationAssessor
 
-__all__ = ["create_all_assessors", "BaseAssessor", "LockFilesAssessor"]
+__all__ = [
+    "create_all_assessors",
+    "BaseAssessor",
+    "LockFilesAssessor",
+    "AdrFrontmatterAssessor",
+]
 
 
 def create_all_assessors() -> list[BaseAssessor]:
@@ -91,12 +97,13 @@ def create_all_assessors() -> list[BaseAssessor]:
         DesignIntentAssessor(),  # 3% (moved from T3)
         DbtDataTestsAssessor(),  # dbt conditional
         DbtProjectStructureAssessor(),  # dbt conditional
-        # Tier 3 Important — 13% total (7 attributes)
-        ArchitectureDecisionsAssessor(),  # 2%
+        # Tier 3 Important — 13% total (8 attributes)
+        ArchitectureDecisionsAssessor(),  # 1%
+        AdrFrontmatterAssessor(),  # 2% (2.4 - ADR Frontmatter Completeness)
         OpenAPISpecsAssessor(),  # 2%
         CyclomaticComplexityAssessor(),  # 2%
         StructuredLoggingAssessor(),  # 1%
-        ProgressiveDisclosureAssessor(),  # 2% (moved from T4)
+        ProgressiveDisclosureAssessor(),  # 1% (moved from T4)
         ArchitecturalBoundaryAssessor(),  # 2% (ADR B.1)
         ThreatModelAssessor(),  # 2% (ADR B.2)
         # Tier 4 Advanced — 2% total (2 attributes, 1% each)

src/agentready/assessors/_adr_utils.py

@@ -0,0 +1,23 @@
+"""Shared helpers for ADR assessor modules.
+
+Extracted to avoid a circular import between adr_frontmatter and adr_sources.
+"""
+
+import yaml
+
+
+def parse_frontmatter(content: str) -> dict | None:
+    """Extract YAML frontmatter from a markdown string.
+
+    Returns a dict if a valid frontmatter block is found, empty dict
+    for an empty block, or None if no block exists or YAML is invalid.
+    """
+    if not content.startswith("---"):
+        return None
+    end = content.find("---", 3)
+    if end == -1:
+        return None
+    try:
+        return yaml.safe_load(content[3:end]) or {}
+    except yaml.YAMLError:
+        return None

src/agentready/assessors/adr_frontmatter.py

@@ -0,0 +1,265 @@
+"""ADR Frontmatter Completeness assessor.
+
+Scores repositories on whether ADR files contain structured YAML
+frontmatter with required fields (status + applies_to).
+"""
+
+from pathlib import Path
+
+from ..models.attribute import Attribute
+from ..models.finding import Finding, Remediation
+from ..models.repository import Repository
+from ._adr_utils import parse_frontmatter
+from .adr_sources import CentralAdrSource, LocalAdrSource
+from .base import BaseAssessor
+
+# Title Case entries follow MADR convention; lowercase entries follow adr-tools convention.
+# "Accepted", "Implementable", "Superseded", "Approved" cover the Konflux/CNCF MADR variant.
+VALID_STATUSES: frozenset[str] = frozenset(
+    [
+        # MADR core
+        "Proposed",
+        "Accepted",
+        "Implementable",
+        "Implemented",
+        "Replaced",
+        "Deprecated",
+        "Superseded",
+        "Approved",
+        # adr-tools lowercase
+        "active",
+        "superseded",
+        "draft",
+    ]
+)
+
+
+
+def classify_adr_file(path: Path) -> str:
+    """Classify a single ADR markdown file.
+
+    Returns one of:
+    - "valid"          — frontmatter present, status + applies_to valid
+    - "incomplete"     — frontmatter present but field(s) missing/invalid
+    - "no_frontmatter" — no leading --- block
+    """
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return "no_frontmatter"
+
+    fm = parse_frontmatter(content)
+    if fm is None:
+        return "no_frontmatter"
+
+    status = fm.get("status")
+    applies_to = fm.get("applies_to")
+
+    # status must be present, non-empty string, and in the allowed set
+    if not status or not isinstance(status, str) or status not in VALID_STATUSES:
+        return "incomplete"
+
+    # applies_to must be present and non-empty (string or non-empty list)
+    if applies_to is None:
+        return "incomplete"
+    if not isinstance(applies_to, (str, list)):
+        return "incomplete"
+    if isinstance(applies_to, str) and not applies_to.strip():
+        return "incomplete"
+    if isinstance(applies_to, list) and not applies_to:
+        return "incomplete"
+
+    return "valid"
+
+
+def score_from_coverage(valid: int, total: int) -> tuple[str, float]:
+    """Compute (status_label, score) from valid/total ADR counts.
+
+    Args:
+        valid: Number of valid ADRs.
+        total: Total number of ADRs (valid + incomplete + no_frontmatter).
+
+    Returns:
+        Tuple of (status_label, score) where status_label is one of
+        "pass", "partial", or "fail", and score is 0.0, 60.0, or 100.0.
+    """
+    if total == 0:
+        return ("pass", 100.0)
+    coverage = valid / total
+    if coverage >= 0.80:
+        return ("pass", 100.0)
+    elif coverage >= 0.50:
+        return ("partial", 60.0)
+    else:
+        return ("fail", 0.0)
+
+
+class AdrFrontmatterAssessor(BaseAssessor):
+    """Assesses ADR frontmatter completeness (status + applies_to fields).
+
+    Tier 3 Important (2% weight). Structured frontmatter enables automated
+    tooling to filter ADRs by applicability, status, and lifecycle stage.
+    """
+
+    @property
+    def attribute_id(self) -> str:
+        """Unique identifier used to register and look up this assessor."""
+        return "adr_frontmatter_completeness"
+
+    @property
+    def tier(self) -> int:
+        """Tier 3 — Important."""
+        return 3
+
+    @property
+    def attribute(self) -> Attribute:
+        """Attribute metadata including name, category, and default weight."""
+        return Attribute(
+            id=self.attribute_id,
+            name="ADR Frontmatter Completeness",
+            category="Documentation Standards",
+            tier=self.tier,
+            description=(
+                "ADR files contain structured YAML frontmatter with required "
+                "status and applies_to fields"
+            ),
+            criteria="≥80% of ADR files have valid frontmatter",
+            default_weight=0.02,
+        )
+
+    def assess(self, repository: Repository) -> Finding:
+        """Score ADR frontmatter completeness using LocalAdrSource or CentralAdrSource.
+
+        If repository.config.adr_source is set, uses CentralAdrSource to
+        read ADRs from a locally cloned central repo filtered by applies_to.
+        Otherwise, uses LocalAdrSource to scan the assessed repo's filesystem.
+
+        Returns skipped if no ADR files are found or the central repo path
+        does not exist.
+        """
+        adr_source_config = (
+            repository.config.adr_source if repository.config is not None else None
+        )
+
+        if adr_source_config is not None:
+            return self._assess_central(repository, adr_source_config)
+
+        return self._assess_local(repository)
+
+    def _assess_local(self, repository: Repository) -> Finding:
+        """Assess using LocalAdrSource (default path)."""
+        source = LocalAdrSource()
+        adr_dir = source.find_adr_dir(repository)
+
+        if adr_dir is None:
+            return Finding.skipped(
+                self.attribute,
+                "No ADR files found in standard locations",
+            )
+
+        adr_files = source.get_adr_files(adr_dir)
+        return self._score_files(adr_files, adr_dir)
+
+    def _assess_central(self, repository: Repository, config: dict) -> Finding:
+        """Assess using CentralAdrSource (central repo path)."""
+        local_path_str = config.get("repo", "")
+        if not local_path_str:
+            return Finding.skipped(
+                self.attribute, "Central ADR repo: 'repo' path not configured"
+            )
+        local_path = Path(local_path_str)
+        adr_path = config.get("path") or "ADR"
+
+        if not local_path.exists():
+            return Finding.skipped(
+                self.attribute,
+                f"Central ADR repo not found at {local_path}",
+            )
+
+        source = CentralAdrSource(local_path=local_path, adr_path=adr_path)
+
+        try:
+            total_in_central = sum(
+                1 for p in source.adr_dir.iterdir() if p.suffix == ".md" and p.is_file()
+            )
+        except OSError:
+            total_in_central = 0
+
+        matched_files = source.get_matching_adr_files(repository.name)
+
+        if not matched_files:
+            return Finding.skipped(
+                self.attribute,
+                f"No ADRs in central repo match applies_to: {repository.name}",
+            )
+
+        extra_evidence = [
+            f"ADR source: {source.adr_dir}/ (central repo)",
+            (
+                f"Filtered by applies_to: {repository.name} "
+                f"({len(matched_files)} of {total_in_central} total ADRs matched)"
+            ),
+        ]
+        return self._score_files(
+            matched_files, source.adr_dir, extra_evidence=extra_evidence
+        )
+
+    def _score_files(
+        self,
+        adr_files: list[Path],
+        adr_dir: Path,
+        extra_evidence: list[str] | None = None,
+    ) -> Finding:
+        """Classify files, compute coverage, and build Finding."""
+        counts: dict[str, int] = {"valid": 0, "incomplete": 0, "no_frontmatter": 0}
+        for f in adr_files:
+            label = classify_adr_file(f)
+            counts[label] += 1
+
+        total = len(adr_files)
+        valid = counts["valid"]
+        status_label, score = score_from_coverage(valid, total)
+
+        pct = int(valid / total * 100) if total > 0 else 100
+        measured_value = f"{valid}/{total} ADRs valid ({pct}%)"
+        evidence = [
+            f"ADR location: {adr_dir}",
+            (
+                f"{valid} valid, {counts['incomplete']} incomplete, "
+                f"{counts['no_frontmatter']} no-frontmatter ({total} total)"
+            ),
+        ]
+        if extra_evidence:
+            evidence.extend(extra_evidence)
+
+        remediation = None
+        if status_label != "pass":
+            remediation = Remediation(
+                summary="Add YAML frontmatter with status and applies_to to all ADR files",
+                steps=[
+                    "Add a frontmatter block at the top of each ADR file",
+                    "Include 'status' (one of: Proposed, Accepted, Implementable, Implemented, Replaced, Deprecated, Superseded, Approved, active, superseded, draft)",
+                    "Include 'applies_to' (repo name, list of repos, or '*' for all)",
+                    "Aim for ≥80% of ADRs to have valid frontmatter",
+                ],
+                tools=[],
+                commands=[],
+                examples=[
+                    "---\nstatus: Implemented\napplies_to: my-service\n---\n# ADR 0001: ..."
+                ],
+                citations=[],
+            )
+
+        # "partial" is reported as "fail" with score=60 (Finding requires pass/fail)
+        finding_status = "pass" if status_label == "pass" else "fail"
+
+        return Finding(
+            attribute=self.attribute,
+            status=finding_status,
+            score=score,
+            measured_value=measured_value,
+            threshold="≥80% valid ADRs",
+            evidence=evidence,
+            remediation=remediation,
+            error_message=None,
+        )