@ahmed-g-gad/apothem 0.1.1

package/src/apothem/audit/scan_stale_tokens.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: MIT
+
+"""Detect hard-coded model identifiers, version pins, and stale dates.
+
+Why this scan exists. Narrative artifacts that bake a specific model
+identifier (``claude-3-opus-20240229``), a SemVer literal embedded in
+prose ("requires foo >= 1.2.3"), or an "as of <date>" claim referring
+to a date older than twelve months become stale silently. Stale claims
+mislead readers and violate the visual-leverage staleness invariant
+that says current-reality assertions carry their own freshness proof.
+This scan surfaces every occurrence so refit phases can replace each
+with a parameterised reference, a relative date, or an updated value
+with a fresh verification stamp.
+
+What this scan covers. Three regex families:
+
+- **Model-identifier literals.** ``claude-(2|3|3-opus|3-5-sonnet|3-5-haiku
+  |3-7-sonnet|opus-4|sonnet-4|haiku-4|opus-4-1|sonnet-4-1|opus-4-5|sonnet-4-5
+  |opus-4-7|sonnet-4-6|haiku-4-5)`` and dated suffixes like
+  ``-20240229``. Any literal occurrence is a finding (the ecosystem
+  resolves model selection through the host's settings; a baked
+  identifier defeats that surface).
+- **SemVer-in-prose.** A SemVer triple appearing inside narrative
+  Markdown that is not adjacent to a known version-pinning surface
+  (``CHANGELOG.md`` entries are exempt; lines containing ``version:``
+  or ``semver:`` keys are exempt).
+- **Stale "as-of" date claims.** ``\\bas of (\\d{4}-\\d{2}-\\d{2})\\b`` and
+  ``\\bverified:?\\s+(\\d{4}-\\d{2}-\\d{2})\\b`` patterns; any matched
+  date older than 12 months from the run's wall-clock is a finding.
+
+What this scan excludes. The repository's own ``CHANGELOG.md`` (where
+SemVer literals legitimately mark release entries) and lines containing
+the literal phrase ``deprecated:`` (which document retirement, not
+current behavior). Memory and plan-artifact records are excluded by
+the shared narrative-surface filter.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _scan_lib import (
+    CONTENT_ROOT,
+    NARRATIVE_CLASSES,
+    SEVERITY_MEDIUM,
+    Hit,
+    WalkCallback,
+    emit_json,
+    load_inventory,
+    walk_narrative_surfaces,
+)
+
+# Match Anthropic-family model identifiers including dated suffixes.
+# Cover the full pre-4 family plus the 4.x cohort (opus / sonnet / haiku
+# at the 4-0 / 4-1 / 4-5 / 4-6 / 4-7 minor-version axis as documented in
+# the active CLAUDE.md environment block).
+_MODEL_PATTERN = re.compile(
+    r"\bclaude-("
+    r"2(?:\.\d+)?(?:-\w+)*"
+    r"|3-(?:opus|sonnet|haiku)(?:-\d{8})?"
+    r"|3[-.]5-(?:opus|sonnet|haiku)(?:-\d{8})?"
+    r"|3[-.]7-(?:opus|sonnet|haiku)(?:-\d{8})?"
+    r"|(?:opus|sonnet|haiku)-4(?:[-.]\d+)?(?:-\d{8})?(?:\[[^\]]+\])?"
+    r")\b"
+)
+
+# SemVer triple captured in two narrowly-scoped contexts:
+#   (a) v-prefixed (`v1.2.3` / `v1.2.3-rc1`) — the canonical pin shape.
+#   (b) bare triple anchored to a version-context keyword on the same
+#       line (``version``, ``release``, ``upgraded to``, ``bump to``).
+# A bare ``X.Y.Z`` without context is far more often a section number
+# (``§4.8.6``), an issue reference (``#1.2.3``), or a regex / literal
+# than a stale version pin; constraining context kills the false-positive
+# class that dominated the un-constrained match.
+_SEMVER_V_PREFIXED = re.compile(
+    r"(?<![\w.])v(\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?)\b"
+)
+_SEMVER_BARE = re.compile(r"(?<![\w.§#])(\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?)\b")
+_VERSION_CONTEXT_RE = re.compile(
+    r"\b(version|release|upgrade(?:d)? to|bump(?:ed)? to|requires|"
+    r"depends on|pin(?:ned)? to)\b",
+    re.IGNORECASE,
+)
+
+# Phrases that anchor a date reference to a freshness claim.
+_AS_OF_PATTERN = re.compile(
+    r"\b(?:as of|valid as of|verified|verified:|last verified|"
+    r"last updated|updated:?)\s+(\d{4}-\d{2}-\d{2})\b",
+    re.IGNORECASE,
+)
+
+# Lines exempt from the SemVer-in-prose finding because they live in
+# legitimate version-pinning contexts.
+_SEMVER_EXEMPT_PATTERNS = (
+    re.compile(r"^\s*version\s*:\s*", re.IGNORECASE),
+    re.compile(r"^\s*semver\s*:\s*", re.IGNORECASE),
+    re.compile(r"^\s*##\s*\[\d", re.IGNORECASE),  # CHANGELOG ## [0.1.5]
+    re.compile(r"\bdeprecated:?\b", re.IGNORECASE),
+)
+
+# File-level exemption: the project's CHANGELOG legitimately enumerates
+# SemVer release entries; date claims there are release dates, not
+# freshness claims.
+_FILE_EXEMPT_FROM_SEMVER = frozenset({"CHANGELOG.md"})
+
+# URL prefixes that anchor version strings to legitimate references
+# (badge image URLs, package-registry links, GitHub release pages, etc.).
+# A SemVer match inside a URL is not narrative drift.
+_URL_MARKER_RE = re.compile(r"https?://|\bshields\.io|\bbadgen\.net")
+
+# A SemVer match is suppressed when the only context is a configuration
+# surface that legitimately pins versions: lock files, manifests, hook
+# configs. We restrict the SemVer-in-prose scan to Markdown files only;
+# this set captures the Markdown-extension whitelist.
+_SEMVER_SCAN_SUFFIXES = frozenset({".md", ".markdown"})
+
+
+def _stale_date_threshold() -> date:
+    """Return the cutoff date older than which 'as-of' claims are stale.
+
+    Twelve months is the staleness window applied uniformly across the
+    audit. A shorter window would over-flag legitimate stable claims;
+    a longer one would let genuinely-stale assertions persist.
+    """
+    return datetime.now(timezone.utc).date() - timedelta(days=365)
+
+
+def _scan_model_ids(rel: str, lineno: int, line: str) -> list[Hit]:
+    """Emit a hit per literal model identifier on the line."""
+    hits: list[Hit] = []
+    for match in _MODEL_PATTERN.finditer(line):
+        token = match.group(0)
+        hits.append(
+            Hit(
+                file=rel,
+                line=lineno,
+                signal=f"hard-coded-model-identifier: {token}",
+                severity=SEVERITY_MEDIUM,
+                remediation=(
+                    "Replace the literal model identifier with a reference"
+                    " resolved through the host's model selection surface;"
+                    " bake-in defeats the indirection that lets operators"
+                    " upgrade."
+                ),
+            )
+        )
+    return hits
+
+
+def _scan_semver_prose(rel: str, lineno: int, line: str) -> list[Hit]:
+    """Emit a hit per SemVer literal that is not URL-anchored or
+    inside a configuration-pin context.
+
+    Two match channels: ``v``-prefixed pins (always flagged when not in
+    an exempt context) and bare triples (flagged only when a
+    version-context keyword appears on the same line).
+    """
+    if any(p.search(line) for p in _SEMVER_EXEMPT_PATTERNS):
+        return []
+    if _URL_MARKER_RE.search(line):
+        return []
+    hits: list[Hit] = []
+    for match in _SEMVER_V_PREFIXED.finditer(line):
+        token = match.group(0)
+        hits.append(_semver_hit(rel, lineno, token))
+    if _VERSION_CONTEXT_RE.search(line):
+        for match in _SEMVER_BARE.finditer(line):
+            token = match.group(0)
+            hits.append(_semver_hit(rel, lineno, token))
+    return hits
+
+
+def _semver_hit(rel: str, lineno: int, token: str) -> Hit:
+    """Construct the canonical SemVer-in-prose hit record."""
+    return Hit(
+        file=rel,
+        line=lineno,
+        signal=f"semver-in-prose: {token}",
+        severity=SEVERITY_MEDIUM,
+        remediation=(
+            "Move the version pin to a configuration surface"
+            " (manifest, schema, version file) or convert the"
+            " prose claim into a parameterised reference."
+        ),
+    )
+
+
+def _scan_stale_dates(
+    rel: str, lineno: int, line: str, stale_cutoff: date
+) -> list[Hit]:
+    """Emit a hit per 'as-of' claim whose date predates the staleness
+    cutoff."""
+    hits: list[Hit] = []
+    for match in _AS_OF_PATTERN.finditer(line):
+        date_str = match.group(1)
+        try:
+            claim_date = date.fromisoformat(date_str)
+        except ValueError:
+            continue
+        if claim_date >= stale_cutoff:
+            continue
+        age_days = (stale_cutoff - claim_date).days + 365
+        hits.append(
+            Hit(
+                file=rel,
+                line=lineno,
+                signal=(
+                    f"stale-as-of-claim: {date_str} (~{age_days // 30} months old)"
+                ),
+                severity=SEVERITY_MEDIUM,
+                remediation=(
+                    "Re-verify the claim against current state and update"
+                    " the date stamp, or restate the claim with a"
+                    " parameterised reference that does not require"
+                    " periodic re-verification."
+                ),
+            )
+        )
+    return hits
+
+
+def _is_markdown(path_str: str) -> bool:
+    """Return True if the file path looks like a Markdown document."""
+    return Path(path_str).suffix.lower() in _SEMVER_SCAN_SUFFIXES
+
+
+def _scan_callback(stale_cutoff: date) -> WalkCallback:
+    """Build the per-file scanner closure."""
+
+    def _walk(path: Path, record: dict[str, Any], content: str) -> list[Hit]:
+        rel = record["path"]
+        is_md = _is_markdown(rel)
+        file_exempt_semver = Path(rel).name in _FILE_EXEMPT_FROM_SEMVER
+        in_fence = False
+        hits: list[Hit] = []
+        for lineno, line in enumerate(content.splitlines(), start=1):
+            if line.lstrip().startswith("```"):
+                in_fence = not in_fence
+                continue
+            hits.extend(_scan_model_ids(rel, lineno, line))
+            if is_md and not in_fence and not file_exempt_semver:
+                hits.extend(_scan_semver_prose(rel, lineno, line))
+            hits.extend(_scan_stale_dates(rel, lineno, line, stale_cutoff))
+        return hits
+
+    return _walk
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--inventory",
+        type=Path,
+        default=Path(".audit/inventory.json"),
+    )
+    parser.add_argument("--root", type=Path, default=CONTENT_ROOT)
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(".audit/drift-stale-tokens.json"),
+    )
+    args = parser.parse_args(argv)
+
+    if not args.inventory.exists():
+        print(
+            f"error: inventory not found at {args.inventory}",
+            file=sys.stderr,
+        )
+        return 1
+
+    records, sha = load_inventory(args.inventory)
+    cutoff = _stale_date_threshold()
+    hits = walk_narrative_surfaces(records, args.root, _scan_callback(cutoff))
+    emit_json(args.output, "scan_stale_tokens", hits, sha)
+    narrative_count = sum(1 for r in records if r.get("class") in NARRATIVE_CLASSES)
+    by_signal: dict[str, int] = {}
+    for h in hits:
+        kind = h.signal.split(":", 1)[0]
+        by_signal[kind] = by_signal.get(kind, 0) + 1
+    summary = ", ".join(f"{k}={v}" for k, v in sorted(by_signal.items()))
+    print(
+        f"scan_stale_tokens: {len(hits)} hit(s) across "
+        f"{narrative_count} narrative files [{summary or 'none'}]"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/audit/synthesize_drift.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: MIT
+
+"""Synthesise the eight drift-scan outputs into a single findings doc.
+
+Why this tool exists. The eight drift scans each emit a per-scan
+JSON document; the audit-gate consolidation needs one human-readable
+view ranking every finding by severity, grouping by file, and
+pointing at the right refit pass. This tool produces
+``drift-findings.md`` — the canonical synthesis surface.
+
+Severity ranking:
+
+- HIGH: secret leaks, conflicting directives, broken internal links,
+  plans-discipline violations, missing CLAUDE.md mandatory blocks.
+- MEDIUM: stale tokens, frontmatter violations, AI-surfaces drift,
+  most non-banner emails, model identifiers.
+- LOW: optional-surface presence informational hits, smart-quote /
+  whitespace issues (none currently scanned).
+
+What this tool does NOT do. It does not assign verdicts (the
+classification-matrix is the verdict surface) and it does not
+re-run the scans (each scanner runs independently first).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Final
+
+_SCAN_FILES: Final[list[tuple[str, str]]] = [
+    ("scan_drift_features", ".audit/drift-feature-refs.json"),
+    ("scan_stale_tokens", ".audit/drift-stale-tokens.json"),
+    ("check_links", ".audit/drift-broken-links.json"),
+    ("scan_frontmatter", ".audit/drift-frontmatter.json"),
+    ("conflicting-directives", ".audit/drift-conflicting-directives.json"),
+    ("scan_secrets_pii", ".audit/drift-secrets-pii.json"),
+    ("scan_plans_discipline", ".audit/drift-plans-discipline.json"),
+    ("scan_ai_surfaces_coarse", ".audit/drift-ai-surfaces-coarse.json"),
+]
+
+_SEVERITY_ORDER: Final[list[str]] = ["HIGH", "MEDIUM", "LOW"]
+
+
+@dataclass(frozen=True)
+class Finding:
+    scanner: str
+    file: str
+    line: int
+    signal: str
+    severity: str
+    remediation: str
+
+
+def _load_scan(scanner: str, path: Path) -> tuple[list[Finding], dict[str, Any]]:
+    """Return ``(findings, envelope)`` for one scan's output."""
+    if not path.exists():
+        return [], {"missing": True}
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    findings = [
+        Finding(
+            scanner=scanner,
+            file=h.get("file", ""),
+            line=int(h.get("line", 0) or 0),
+            signal=h.get("signal", ""),
+            severity=h.get("severity", "LOW"),
+            remediation=h.get("remediation", ""),
+        )
+        for h in payload.get("hits", [])
+    ]
+    envelope = {
+        "scanner": scanner,
+        "hit-count": payload.get("hit-count", len(findings)),
+        "missing": False,
+    }
+    return findings, envelope
+
+
+def _gather(audit_root: Path) -> tuple[list[Finding], list[dict[str, Any]]]:
+    all_findings: list[Finding] = []
+    envelopes: list[dict[str, Any]] = []
+    for scanner, rel_path in _SCAN_FILES:
+        findings, envelope = _load_scan(scanner, audit_root / Path(rel_path).name)
+        all_findings.extend(findings)
+        envelopes.append(envelope)
+    return all_findings, envelopes
+
+
+def _group_by_severity(
+    findings: Iterable[Finding],
+) -> dict[str, list[Finding]]:
+    by_sev: dict[str, list[Finding]] = defaultdict(list)
+    for f in findings:
+        by_sev[f.severity].append(f)
+    return by_sev
+
+
+def _group_by_scanner(
+    findings: Iterable[Finding],
+) -> dict[str, list[Finding]]:
+    by_scanner: dict[str, list[Finding]] = defaultdict(list)
+    for f in findings:
+        by_scanner[f.scanner].append(f)
+    return by_scanner
+
+
+def _emit_markdown(
+    findings: list[Finding],
+    envelopes: list[dict[str, Any]],
+    out_path: Path,
+) -> None:
+    by_sev = _group_by_severity(findings)
+    by_scanner = _group_by_scanner(findings)
+    lines: list[str] = []
+    lines.append("# Drift Findings")
+    lines.append("")
+    lines.append(
+        "Synthesised from the eight drift scans. Severity ranking per"
+        " the synthesis-pass criteria; grouping is by severity first,"
+        " then by scanner, then by file."
+    )
+    lines.append("")
+    lines.append("## Per-scan summary")
+    lines.append("")
+    lines.append("| Scanner | Hit count | Status |")
+    lines.append("|---------|----------:|--------|")
+    for env in envelopes:
+        if env.get("missing"):
+            lines.append(f"| `{env['scanner']}` | — | output absent |")
+        else:
+            lines.append(f"| `{env['scanner']}` | {env['hit-count']} | scan ran |")
+    lines.append("")
+    lines.append("## Severity totals")
+    lines.append("")
+    lines.append("| Severity | Count |")
+    lines.append("|----------|------:|")
+    for sev in _SEVERITY_ORDER:
+        lines.append(f"| {sev} | {len(by_sev.get(sev, []))} |")
+    lines.append("")
+    for sev in _SEVERITY_ORDER:
+        sev_findings = by_sev.get(sev, [])
+        if not sev_findings:
+            continue
+        lines.append(f"## {sev} severity ({len(sev_findings)} findings)")
+        lines.append("")
+        per_scanner = _group_by_scanner(sev_findings)
+        for scanner in sorted(per_scanner.keys()):
+            scanner_findings = per_scanner[scanner]
+            lines.append(f"### `{scanner}` — {len(scanner_findings)} {sev} hit(s)")
+            lines.append("")
+            lines.append("| File | Line | Signal | Remediation |")
+            lines.append("|------|-----:|--------|-------------|")
+            for f in sorted(scanner_findings, key=lambda x: (x.file, x.line)):
+                signal = f.signal.replace("|", r"\|")
+                remediation = f.remediation.replace("|", r"\|")
+                # Truncate long signal text for table readability.
+                if len(signal) > 100:
+                    signal = signal[:97] + "..."
+                if len(remediation) > 140:
+                    remediation = remediation[:137] + "..."
+                lines.append(f"| `{f.file}` | {f.line} | {signal} | {remediation} |")
+            lines.append("")
+    lines.append("## Per-scanner total")
+    lines.append("")
+    lines.append("| Scanner | Total hits |")
+    lines.append("|---------|-----------:|")
+    for scanner in sorted(by_scanner.keys()):
+        lines.append(f"| `{scanner}` | {len(by_scanner[scanner])} |")
+    lines.append("")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--audit-dir",
+        type=Path,
+        default=Path(".audit"),
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(".audit/drift-findings.md"),
+    )
+    args = parser.parse_args(argv)
+
+    findings, envelopes = _gather(args.audit_dir)
+    _emit_markdown(findings, envelopes, args.output)
+
+    by_sev = _group_by_severity(findings)
+    summary = ", ".join(f"{sev}={len(by_sev.get(sev, []))}" for sev in _SEVERITY_ORDER)
+    print(
+        f"synthesize_drift: {len(findings)} total findings "
+        f"[{summary}] across {len(envelopes)} scans -> {args.output}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/benchmarks/README.md

@@ -0,0 +1,33 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# benchmarks
+
+> **Role.** Per-class performance benchmark drivers. Each script runs an artifact class's representative invocations, measures runtime, compares against the class budget declared in `rules/performance-discipline.md` §1, and exits 0 on PASS / non-zero on FAIL with a measured-vs-budget delta.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bench_hooks.py` | Hook-handler runtime benchmark against the per-event budgets (`--event=<name>`). |
+| `bench_tests.py` | Test-suite runtime benchmark against the per-suite budgets (full suite and per-module). |
+| `bench_agents.py` | Agent-spawn runtime benchmark against the per-spawn budget. |
+| `bench_validate_ecosystem.py` | Verify-ecosystem-sweep runtime benchmark against the composite and per-check budgets. |
+| `__init__.py` | Package marker. |
+
+## Conventions
+
+- Budgets are operator-editorial at apply time; the recommended baselines align with the hook-timeout values in the harness configuration and `rules/performance-discipline.md` §1.
+- Budget exceedances surface as high-priority Performance-axis findings.
+
+## Operating in this folder
+
+- **Budget constant is the single source.** Each driver declares its class's budget as a module-level `Final` constant; it stays aligned with the budget table in `../rules/performance-discipline.md` §1 and the harness hook-timeout values — a budget change is mirrored in both places in the same change-set.
+- **Exit code is the verdict.** 0 = PASS, non-zero = FAIL with a measured-vs-budget delta line. A scaffold driver with no wired fixture reports the budget and exits 0 so the verifier surface stays usable.
+- **Path resolution is anchored relative to `__file__`** (the drivers sit four parents below the repository root); do not hard-code an absolute path.
+- **Adding a driver:** declare the class's budget constant, implement the measurement against the representative invocation, and return the exit-code verdict with a delta line on FAIL. **Revising a budget:** cite a concrete driver (measured workload increase, infrastructure change, dependency upgrade, or rule citation) and update the rule table in the same change-set.
+- Validate a change with `python -m ruff check`, `python -m mypy` for the in-scope modules, and `python -m pytest` (benchmark-driver tests).
+
+## Related
+
+- [`rules/performance-discipline.md`](../rules/performance-discipline.md) — the per-class budget table the drivers verify.
+- [`hooks/`](../hooks/) — the hook handlers `bench_hooks.py` measures.

package/src/apothem/benchmarks/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+
+"""Per-class performance-budget verifiers for the ecosystem."""

package/src/apothem/benchmarks/bench_agents.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+
+"""Agent-spawn runtime benchmark per the per-spawn budget in
+`src/apothem/rules/performance-discipline.md` §1.
+
+Spawn budget: 60 seconds for any of the four agent patterns
+(research / audit / quality / generation).
+
+Agent spawns are exercised through the host harness rather than via a
+direct subprocess call; the script stands as a budget anchor with a
+representative-invocation hook that operators wire to their harness.
+When no harness fixture is provided, the script reports the budget and
+exits with the scaffold marker (return code 0) so the verifier surface
+remains usable while detailed fixtures land.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Final
+
+_BUDGET: Final[float] = 60.0
+_PATTERNS: Final[tuple[str, ...]] = ("research", "audit", "quality", "generation")
+
+
+def _representative_spawn() -> float | None:
+    """Return wall-clock seconds for a representative agent spawn.
+
+    Returns ``None`` when no harness fixture is wired; the caller then
+    reports the budget without a measurement.
+    """
+    # Harness fixtures are operator-editorial; without one wired, no
+    # measurement is attempted. Wire a representative spawn through the
+    # host harness here when one becomes available.
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bench_agents")
+    parser.add_argument(
+        "--pattern",
+        required=True,
+        choices=_PATTERNS,
+        help="Agent pattern to benchmark.",
+    )
+    args = parser.parse_args(argv)
+
+    elapsed = _representative_spawn()
+    if elapsed is None:
+        print(
+            f"SCAFFOLD: pattern={args.pattern} budget={_BUDGET}s "
+            "(no harness fixture wired; measurement skipped)"
+        )
+        return 0
+    if elapsed <= _BUDGET:
+        print(f"PASS: agent {args.pattern} = {elapsed:.3f}s (budget {_BUDGET}s)")
+        return 0
+    print(f"FAIL: agent {args.pattern} = {elapsed:.3f}s exceeds budget {_BUDGET}s")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())