pi-dev-team 0.2.0

package/scripts/lib/deterministic_recon.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""deterministic_recon — structural reconnaissance without LLM.
+
+The deterministic half of `codebase_recon.py` (this file's sibling one
+directory up): produces a recon envelope conforming (approximately) to
+`../../knowledge/schemas/recon-envelope-v1.json` by running file-system and
+grep-based heuristics. It covers the structural fields (repo metadata,
+languages, entry points, security surface by grep) but produces empty
+`architecture.notable_anti_patterns` and thin prose in `architecture.summary`
+since those need reasoning — `codebase_recon.py` fills that gap with an
+optional LLM step (`claude -p`) layered on top of this module's output.
+
+Usage:
+    python3 ${CLAUDE_PLUGIN_ROOT}/scripts/lib/deterministic_recon.py <target-path> [<output-json>]
+
+Emits JSON to stdout (or to <output-json> if given).
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+LANGUAGE_BY_EXT = {
+    ".py": "Python", ".js": "JavaScript", ".jsx": "JavaScript",
+    ".ts": "TypeScript", ".tsx": "TypeScript", ".go": "Go",
+    ".java": "Java", ".kt": "Kotlin", ".rb": "Ruby",
+    ".rs": "Rust", ".php": "PHP", ".cs": "C#", ".scala": "Scala",
+    ".swift": "Swift", ".sh": "Shell", ".bash": "Shell",
+    ".sql": "SQL", ".yml": "YAML", ".yaml": "YAML",
+}
+
+ENTRY_POINT_SIGNALS = [
+    # (pattern, kind)
+    (re.compile(r"^#!/usr/bin/env (?:python3?|bash|sh)"), "cli"),
+    (re.compile(r"if __name__ == ['\"]__main__['\"]:"), "cli"),
+    (re.compile(r"app\.(listen|run)\s*\("), "http-server"),
+    (re.compile(r"uvicorn\.run\s*\("), "http-server"),
+    (re.compile(r"@app\.(get|post|put|delete|patch)\s*\("), "http-server"),
+    (re.compile(r"@router\.(get|post|put|delete|patch)\s*\("), "http-server"),
+    (re.compile(r"server\.listen\s*\("), "http-server"),
+    (re.compile(r"exports\.handler\s*="), "lambda"),
+]
+
+SECURITY_SURFACE_PATTERNS = {
+    "auth_paths": [
+        re.compile(r"\b(login|logout|jwt\.sign|jwt\.verify|oauth|passport|authenticat|authoriz|session)\b", re.IGNORECASE),
+    ],
+    "network_egress": [
+        re.compile(r"\b(fetch\(|axios\.|httpx\.|requests\.(get|post|put|delete)|http\.Get\(|URLSession|urllib\.request\.)"),
+    ],
+    "secrets_referenced": [
+        re.compile(r"(process\.env\.[A-Z_]+|os\.environ(?:\.get)?(?:\[|\()|os\.getenv\(|ENV\[)"),
+    ],
+    "crypto_calls": [
+        re.compile(r"\b(crypto\.|hashlib\.|bcrypt|scrypt|argon2|ed25519|AES\.new|Cipher\(|\.encrypt\(|\.decrypt\()"),
+    ],
+    "ml_models_loaded": [
+        re.compile(r"\b(onnx\.load|pickle\.loads?|joblib\.load|torch\.load|AutoModel\.from_pretrained|SafeTensors\.load)\b"),
+    ],
+}
+
+SENSITIVE_FILE_PATTERNS = [
+    re.compile(r"\.env(\.[a-z]+)?$", re.IGNORECASE),
+    re.compile(r"\.(pem|key|p12|pfx|crt)$", re.IGNORECASE),
+    re.compile(r"credentials?", re.IGNORECASE),
+    re.compile(r"secret", re.IGNORECASE),
+    re.compile(r"id_(rsa|ed25519|ecdsa|dsa)", re.IGNORECASE),
+]
+
+
+def detect_package_manager(root: Path) -> str:
+    has = {
+        "npm": (root / "package-lock.json").exists(),
+        "pnpm": (root / "pnpm-lock.yaml").exists(),
+        "yarn": (root / "yarn.lock").exists(),
+        "poetry": (root / "poetry.lock").exists(),
+        "pipenv": (root / "Pipfile.lock").exists(),
+        "pip": (root / "requirements.txt").exists(),
+        "go-modules": (root / "go.mod").exists(),
+        "cargo": (root / "Cargo.lock").exists(),
+        "maven": (root / "pom.xml").exists(),
+        "gradle": (root / "build.gradle").exists() or (root / "build.gradle.kts").exists(),
+    }
+    present = [k for k, v in has.items() if v]
+    if len(present) == 0:
+        return "unknown"
+    if len(present) == 1:
+        return present[0]
+    return "mixed"
+
+
+def detect_monorepo(root: Path) -> tuple[bool, list[str]]:
+    pkg_json = root / "package.json"
+    if pkg_json.exists():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8", errors="replace"))
+            if isinstance(data.get("workspaces"), list):
+                return True, [str(w) for w in data["workspaces"]]
+            if isinstance(data.get("workspaces"), dict):
+                packages = data["workspaces"].get("packages", [])
+                return True, [str(w) for w in packages]
+        except (json.JSONDecodeError, OSError):
+            pass
+    # Conventional monorepo shape — packages/ + apps/ + services/ dirs present
+    has_ws_dirs = [(root / d).is_dir() for d in ("packages", "apps", "services")]
+    if sum(has_ws_dirs) >= 1:
+        # Not a formal monorepo but has workspace-like structure
+        all_workspaces = []
+        for d in ("packages", "apps", "services"):
+            if (root / d).is_dir():
+                for sub in (root / d).iterdir():
+                    if sub.is_dir():
+                        all_workspaces.append(f"{d}/{sub.name}")
+        return bool(all_workspaces), all_workspaces
+    return False, []
+
+
+def walk_source_files(root: Path) -> list[Path]:
+    """Walk the tree, skipping common junk directories."""
+    skip_dirs = {".git", "node_modules", ".venv", "venv", "__pycache__",
+                 "dist", "build", ".tox", ".mypy_cache", ".ruff_cache",
+                 "target", ".next", ".nuxt"}
+    out: list[Path] = []
+    for p in root.rglob("*"):
+        if not p.is_file():
+            continue
+        if any(part in skip_dirs for part in p.parts):
+            continue
+        out.append(p)
+    return out
+
+
+def enumerate_languages(files: list[Path]) -> list[dict]:
+    counts: Counter[str] = Counter()
+    for f in files:
+        lang = LANGUAGE_BY_EXT.get(f.suffix.lower())
+        if lang:
+            counts[lang] += 1
+    return [
+        {"name": name, "file_count": count, "dominant_framework": None}
+        for name, count in counts.most_common()
+        if count >= 3
+    ]
+
+
+def identify_entry_points(files: list[Path], root: Path) -> list[dict]:
+    out: list[dict] = []
+    for f in files:
+        if f.suffix.lower() not in {".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".java", ".rb", ".sh"}:
+            continue
+        try:
+            text = f.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        lines = text.splitlines()
+        for i, line in enumerate(lines[:200], start=1):  # check first 200 lines
+            for pattern, kind in ENTRY_POINT_SIGNALS:
+                if pattern.search(line):
+                    rel = str(f.relative_to(root))
+                    rationale = f"Pattern match at line {i}: {line.strip()[:80]}"
+                    lang = LANGUAGE_BY_EXT.get(f.suffix.lower(), "unknown")
+                    # Dedupe on path
+                    if not any(ep["path"] == rel for ep in out):
+                        out.append({
+                            "path": rel,
+                            "kind": kind,
+                            "rationale": rationale,
+                            "language": lang,
+                        })
+                    break  # one signal per file is enough
+    # Package.json main
+    pkg_json = root / "package.json"
+    if pkg_json.exists():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8", errors="replace"))
+            main = data.get("main")
+            if main:
+                rel = main.lstrip("./")
+                if not any(ep["path"] == rel for ep in out):
+                    out.append({
+                        "path": rel,
+                        "kind": "module-index",
+                        "rationale": "Listed as 'main' in package.json",
+                        "language": "JavaScript/TypeScript",
+                    })
+        except (json.JSONDecodeError, OSError):
+            pass
+    return out
+
+
+def identify_dependencies(root: Path) -> dict:
+    deps: dict[str, list[str]] = {}
+
+    # Python requirements.txt
+    req = root / "requirements.txt"
+    if req.exists():
+        try:
+            text = req.read_text(encoding="utf-8")
+            pkgs = [line.split("==")[0].split(">=")[0].split("<=")[0].strip()
+                    for line in text.splitlines()
+                    if line.strip() and not line.strip().startswith("#")]
+            _classify_deps(pkgs, deps)
+        except OSError:
+            pass
+
+    # Node package.json
+    pkg_json = root / "package.json"
+    if pkg_json.exists():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8", errors="replace"))
+            pkgs = list((data.get("dependencies") or {}).keys())
+            _classify_deps(pkgs, deps)
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return deps
+
+
+def _classify_deps(pkgs: list[str], deps: dict):
+    """Heuristic classification of deps into web/data/crypto/auth/messaging/ml."""
+    buckets = {
+        "web": {"express", "fastapi", "flask", "django", "koa", "hapi", "starlette", "sanic", "bottle"},
+        "data": {"sqlalchemy", "mongodb", "mongoose", "pg", "mysql2", "redis", "psycopg2", "pymongo", "cassandra-driver"},
+        "crypto": {"pycryptodome", "cryptography", "bcrypt", "argon2", "scrypt", "jsonwebtoken", "jose"},
+        "auth": {"passport", "pyjwt", "python-jose", "authlib", "jsonwebtoken", "oauth2"},
+        "messaging": {"nats-py", "aio-pika", "kafka-python", "pika", "amqplib"},
+        "ml": {"onnx", "torch", "tensorflow", "scikit-learn", "joblib", "safetensors"},
+    }
+    for pkg in pkgs:
+        pkg_lower = pkg.lower()
+        for bucket, names in buckets.items():
+            if pkg_lower in names or any(pkg_lower.startswith(n) for n in names):
+                deps.setdefault(bucket, []).append(pkg)
+                break
+        else:
+            deps.setdefault("other_notable", []).append(pkg)
+
+
+def grep_security_surface(files: list[Path], root: Path) -> dict:
+    out: dict[str, list[str]] = {k: [] for k in SECURITY_SURFACE_PATTERNS}
+    out["csp_headers"] = []
+    for f in files:
+        if f.suffix.lower() not in {".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".java", ".rb"}:
+            continue
+        try:
+            text = f.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        rel = str(f.relative_to(root))
+        for kind, patterns in SECURITY_SURFACE_PATTERNS.items():
+            if any(p.search(text) for p in patterns) and rel not in out[kind]:
+                out[kind].append(rel)
+    return out
+
+
+def probe_git_history(root: Path, notes: list | None = None) -> dict:
+    """Probe branch/activity/sensitive-file history.
+
+    `notes` (#1651): an optional sink for degrade warnings. The
+    sensitive-file scan shells out to `git log --all --name-only` under a
+    timeout, and swallowing that timeout leaves `sensitive_file_history`
+    empty — indistinguishable from "scanned the whole history, found
+    nothing." On a large repo those are opposite conclusions, and the empty
+    one reads as the reassuring answer. When a sink is supplied, a degraded
+    probe says so; #1636 established this pattern for the jsonschema-absent
+    case in `codebase_recon.py` rather than degrading silently.
+    """
+    out: dict[str, Any] = {
+        "branches": {"current": "", "main_count": 0, "feature_count": 0, "names": []},
+        "recent_activity": {"last_commit_date": "1970-01-01T00:00:00Z", "commits_last_30d": 0, "authors_last_30d": 0},
+        "sensitive_file_history": [],
+    }
+    if not (root / ".git").exists():
+        return out
+
+    try:
+        branches = subprocess.run(["git", "-C", str(root), "branch", "--list"],
+                                  capture_output=True, text=True, timeout=10, check=False).stdout.splitlines()
+        branch_names = [b.strip().lstrip("* ") for b in branches]
+        current = subprocess.run(["git", "-C", str(root), "rev-parse", "--abbrev-ref", "HEAD"],
+                                 capture_output=True, text=True, timeout=10, check=False).stdout.strip()
+        out["branches"]["current"] = current
+        out["branches"]["names"] = branch_names[:20]
+        out["branches"]["main_count"] = sum(1 for b in branch_names if b in ("main", "master", "develop"))
+        out["branches"]["feature_count"] = max(0, len(branch_names) - out["branches"]["main_count"])
+
+        last = subprocess.run(["git", "-C", str(root), "log", "-1", "--format=%cI"],
+                              capture_output=True, text=True, timeout=10, check=False).stdout.strip()
+        if last:
+            out["recent_activity"]["last_commit_date"] = last
+
+        commits = subprocess.run(
+            ["git", "-C", str(root), "log", "--since=30 days ago", "--oneline"],
+            capture_output=True, text=True, timeout=10, check=False,
+        ).stdout.strip().splitlines()
+        authors = subprocess.run(
+            ["git", "-C", str(root), "log", "--since=30 days ago", "--format=%ae"],
+            capture_output=True, text=True, timeout=10, check=False,
+        ).stdout.strip().splitlines()
+        out["recent_activity"]["commits_last_30d"] = len(commits)
+        out["recent_activity"]["authors_last_30d"] = len({a for a in authors if a})
+
+        # Sensitive file history — files ever touched
+        tree_files = subprocess.run(
+            ["git", "-C", str(root), "log", "--all", "--name-only", "--format="],
+            capture_output=True, text=True, timeout=30, check=False,
+        ).stdout.splitlines()
+        for path in {p for p in tree_files if p}:
+            for pattern in SENSITIVE_FILE_PATTERNS:
+                if pattern.search(path):
+                    in_tree = (root / path).exists()
+                    out["sensitive_file_history"].append({
+                        "path": path,
+                        "in_current_tree": in_tree,
+                        "appeared_in_history": True,
+                        "first_seen_commit": None,
+                        "removed_commit": None,
+                    })
+                    break
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError) as exc:
+        if notes is not None:
+            kind = (
+                "timed out"
+                if isinstance(exc, subprocess.TimeoutExpired)
+                else "failed"
+            )
+            notes.append(
+                f"DEGRADED: the git-history probe {kind}, so branch, recent-activity, "
+                "and sensitive-file-history fields are partial or empty. An empty "
+                "sensitive_file_history here does NOT mean none was found — the scan "
+                "did not complete."
+            )
+    return out
+
+
+def build_architecture(files: list[Path], root: Path) -> dict:
+    """Identify layers from directory naming. Summary is thin without LLM."""
+    known_layers = ["domain", "core", "adapters", "infrastructure", "ports",
+                    "handlers", "routes", "services", "repositories", "models",
+                    "controllers", "views", "backend", "frontend", "api", "worker"]
+    layer_files: dict[str, list[str]] = {}
+    for f in files:
+        for layer in known_layers:
+            if f"/{layer}/" in str(f) or str(f).startswith(f"{layer}/"):
+                rel_dir = str(f.parent.relative_to(root))
+                layer_files.setdefault(layer, [])
+                if rel_dir not in layer_files[layer]:
+                    layer_files[layer].append(rel_dir)
+                break
+
+    layers = [
+        {"name": k, "paths": sorted(set(v))[:5], "purpose": ""}
+        for k, v in layer_files.items() if len(v) >= 1
+    ]
+
+    # Summary is deterministic but thin
+    summary_parts = []
+    if layers:
+        layer_names = [layer["name"] for layer in layers]
+        summary_parts.append(f"Code organized into {len(layers)} identifiable layer(s): {', '.join(layer_names)}.")
+    else:
+        summary_parts.append("No conventional layer structure detected.")
+
+    return {
+        "summary": " ".join(summary_parts) + " [Deterministic recon — LLM narrative skipped.]",
+        "layers": layers,
+        "notable_anti_patterns": [],  # Requires LLM
+    }
+
+
+def build_recon(root: Path) -> dict:
+    root = root.resolve()
+    files = walk_source_files(root)
+    monorepo, workspaces = detect_monorepo(root)
+
+    # Built before the envelope so probes can append degrade warnings to it
+    # (#1651). `probe_git_history` mutates this list in place, and the dict
+    # literal below evaluates that call before reading `notes`, so anything
+    # appended during the probe is present in the emitted envelope.
+    notes = [
+        (
+            "Deterministic recon produced by "
+            "plugins/dev-team/scripts/lib/deterministic_recon.py. No LLM reasoning "
+            "applied; semantic fields (architecture.summary prose, "
+            "notable_anti_patterns) are omitted or minimal."
+        )
+    ]
+
+    return {
+        "schema_version": "1.0",
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "repo": {
+            "name": root.name,
+            "root": str(root),
+            "package_manager": detect_package_manager(root),
+            "monorepo": monorepo,
+            "workspaces": workspaces,
+            "vcs": {
+                "kind": "git" if (root / ".git").exists() else "none",
+                "remote_host": None,
+                "default_branch": None,
+            },
+        },
+        "entry_points": identify_entry_points(files, root),
+        "languages": enumerate_languages(files),
+        "dependencies": identify_dependencies(root),
+        "architecture": build_architecture(files, root),
+        "security_surface": grep_security_surface(files, root),
+        "git_history": probe_git_history(root, notes),
+        "notes": notes,
+    }
+
+
+def main() -> int:
+    if len(sys.argv) < 2 or len(sys.argv) > 3:
+        print("usage: deterministic_recon.py <target-path> [<output-json>]", file=sys.stderr)
+        return 2
+
+    target = Path(sys.argv[1])
+    if not target.is_dir():
+        print(f"error: target is not a directory: {target}", file=sys.stderr)
+        return 2
+
+    recon = build_recon(target)
+
+    if len(sys.argv) == 3:
+        out_path = Path(sys.argv[2])
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with out_path.open("w") as f:
+            json.dump(recon, f, indent=2)
+        print(f"wrote {out_path}", file=sys.stderr)
+    else:
+        json.dump(recon, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lib/mcp_tool_grants.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Shared plumbing for the code-intelligence MCP tool-grant checks.
+
+Three sibling check scripts consume this module as peers — none is any other's
+library:
+
+- ``check_review_agent_mcp_tools.py`` — the 24 read-only ``*-review`` agents, all
+  granted the same ``BASE_MCP_TOOLS`` set (#1102).
+- ``check_agent_tool_mapping.py`` — the non-review team agents, granted per-tier
+  sets built from ``BASE_MCP_TOOLS`` (± ``GET_WHY``) (#1108).
+- ``check_security_assessment_mcp_tools.py`` — the security-assessment plugin's
+  code-reading agents, granted the same ``BASE_MCP_TOOLS`` set as the review-agent
+  check above, but discovered via a named roster rather than a filename glob
+  (#1388).
+
+This module owns the canonical tool-name constants and the frontmatter
+``tools:``-line parse/fix plumbing all three checks need. The fix helpers take a
+caller-supplied ``required`` list so each check can request its own set (the
+5-name review/narrow set, or the 6-name rationale set) without duplicating the
+merge logic.
+"""
+
+import re
+
+# CodeGraph + the four Repowise tools granted to every read-only review agent,
+# and the shared base of the non-review tiers (#1102's canonical set). A granted
+# tool whose MCP server is absent is simply unavailable at runtime (no error);
+# agents fall back to Read/Grep/Glob.
+BASE_MCP_TOOLS = [
+    "mcp__codegraph__codegraph_explore",
+    "mcp__plugin_repowise_repowise__get_context",
+    "mcp__plugin_repowise_repowise__get_symbol",
+    "mcp__plugin_repowise_repowise__search_codebase",
+    "mcp__plugin_repowise_repowise__get_risk",
+]
+
+# The rationale/decision tier additionally grants get_why (code-existence
+# rationale) — see check_agent_tool_mapping.py.
+GET_WHY = "mcp__plugin_repowise_repowise__get_why"
+
+# Reassigned-tools tier (#1467): health scoring and dead-code detection granted
+# to specific review agents in place of get_risk/search_codebase — see
+# check_review_agent_mcp_tools.py's REASSIGNED_TOOLS mapping.
+GET_HEALTH = "mcp__plugin_repowise_repowise__get_health"
+GET_DEAD_CODE = "mcp__plugin_repowise_repowise__get_dead_code"
+
+# Match the inline `tools:` line only. Group 1 (`tools:` + horizontal space) and
+# group 3 (trailing horizontal space) use `[ \t]` — NOT `\s` — so the match can
+# never cross a newline into a YAML block-scalar/sequence form
+# (`tools:\n  - Read`). Group 2 is the inline value (no newline).
+_TOOLS_RE = re.compile(r"^(tools:[ \t]*)([^\n]*?)([ \t]*)$", re.MULTILINE)
+
+
+def parse_tools(text):
+    """Return the comma-separated tokens on the inline ``tools:`` line, or None.
+
+    Returns None when there is no ``tools:`` line, or when it has no inline value
+    (an empty line, or a YAML block form with the list on following lines) — such
+    a line is not safely appendable, so callers treat None as *unfixable* rather
+    than mangling it.
+    """
+    m = _TOOLS_RE.search(text)
+    if not m:
+        return None
+    value = m.group(2).strip()
+    if not value:
+        return None
+    return [tok.strip() for tok in value.split(",") if tok.strip()]
+
+
+def _server_wildcard_forms(name):
+    """Return the ``mcp__<server>__*`` and bare ``mcp__<server>`` forms that
+    satisfy a specific ``mcp__<server>__<tool>`` grant requirement, per
+    agent-contract.json's tools: value_format ("mcp__<server> or
+    mcp__<server>__*" grants every tool from that server).
+    """
+    parts = name.split("__")
+    if len(parts) < 3 or parts[0] != "mcp":
+        return ()
+    server = "__".join(parts[:2])
+    return (f"{server}__*", server)
+
+
+def _is_satisfied(name, present):
+    """True if ``name`` is granted exactly, or via a server-wide wildcard grant."""
+    if name in present:
+        return True
+    return any(form in present for form in _server_wildcard_forms(name))
+
+
+def _compute_missing(present, required):
+    """Return the ``required`` names not satisfied by the ``present`` grant set."""
+    return [name for name in required if not _is_satisfied(name, present)]
+
+
+def missing_tools(text, required):
+    """Return the ``required`` tool names absent from the agent's ``tools:`` line.
+
+    A required ``mcp__<server>__<tool>`` name is considered present when the
+    agent instead grants ``mcp__<server>__*`` or bare ``mcp__<server>`` —
+    both equivalent, broader grants per the official contract.
+
+    Returns the full ``required`` list when the agent has no parseable ``tools:``
+    line at all.
+    """
+    tokens = parse_tools(text)
+    if tokens is None:
+        return list(required)
+    return _compute_missing(set(tokens), required)
+
+
+def fix_tools_line(text, required):
+    """Append any missing ``required`` names to the ``tools:`` line. Idempotent.
+
+    Returns ``(new_text, added_names)``. Order-preserving: existing tokens keep
+    their order; missing names are appended in ``required`` order. A line already
+    containing every required name is returned unchanged (``added == []``). A file
+    with no parseable ``tools:`` line is returned unchanged (``added == []``).
+    """
+    m = _TOOLS_RE.search(text)
+    if not m:
+        return text, []
+    tokens = parse_tools(text)
+    if tokens is None:
+        # No inline value (block form or empty) — unfixable, never mangle it.
+        return text, []
+    added = _compute_missing(set(tokens), required)
+    if not added:
+        return text, []
+    new_tokens = tokens + added
+    new_line = m.group(1) + ", ".join(new_tokens)
+    new_text = text[: m.start()] + new_line + text[m.end() - len(m.group(3)) :]
+    return new_text, added
+
+
+def run_grants_check(targets, apply_fix=False):
+    """Single read+parse pass per target, shared by all three grant-check scripts.
+
+    ``targets`` is ``{name: (path, required)}``. Each target's file is read from
+    disk **at most once** regardless of ``apply_fix`` — the offender computation
+    below reuses the (possibly just-fixed) in-memory text rather than re-reading,
+    which is what let ``--fix`` runs silently do a second full read+parse pass
+    per file in the three callers before this helper existed (#1392).
+
+    Returns ``(offenders, fixed, unfixable)``:
+      - ``offenders``: ``{name: [missing tool names]}``, reflecting the
+        post-fix state when ``apply_fix`` is true.
+      - ``fixed``: ``{name: [tool names added]}`` — populated only when
+        ``apply_fix`` is true.
+      - ``unfixable``: ``[name, ...]`` — targets whose file exists but has no
+        appendable inline ``tools:`` line — populated only when ``apply_fix``
+        is true (mirrors each caller's prior ``apply_fixes()`` semantics).
+    """
+    offenders = {}
+    fixed = {}
+    unfixable = []
+    for name, (path, required) in targets.items():
+        if not path.is_file():
+            offenders[name] = list(required)
+            continue
+        text = path.read_text(encoding="utf-8")
+        if apply_fix:
+            if parse_tools(text) is None:
+                unfixable.append(name)
+            else:
+                new_text, added = fix_tools_line(text, required)
+                if added:
+                    path.write_text(new_text, encoding="utf-8")
+                    fixed[name] = added
+                    text = new_text
+        missing = missing_tools(text, required)
+        if missing:
+            offenders[name] = missing
+    return offenders, fixed, unfixable
+
+
+def build_json_report(check, evaluated, offenders, ok, fixed=None, unfixable=None, unclassified=None, notes=None):
+    """Build the common ``--json`` envelope shared by all three grant-check scripts (#1393).
+
+    Each script's ``--json`` output previously diverged in shape (``reviewed`` vs
+    ``covered``, an ``unclassified`` key present on two scripts but absent on the
+    third, ``fixed``/``unfixable`` only appearing conditionally on ``--fix``) — a
+    caller wanting to aggregate "which grant checks are failing" across scripts had
+    no uniform surface to read. This helper gives every script the same top-level
+    keys, always present, so a future aggregator never needs a per-script branch:
+
+    - ``check``: a stable slug identifying which script produced the report.
+    - ``evaluated``: every target name the check looked at.
+    - ``offenders``: ``{name: [missing tool names]}`` (post-fix state if fixed).
+    - ``unclassified``: names present but classified into neither a required nor
+      an excluded bucket — ``[]`` when the check has no such concept.
+    - ``fixed`` / ``unfixable``: from ``run_grants_check`` — empty when detection
+      only (no ``--fix``).
+    - ``ok``: the caller's own exit-code decision, passed through rather than
+      re-derived here — some checks (e.g. the review-agent script's skill-prose
+      check) fail for reasons ``offenders``/``unclassified`` alone don't capture,
+      so this helper must not guess at "ok" from the other fields.
+    - ``notes``: a namespaced bag for the one or two fields that are genuinely
+      script-specific (e.g. ``skill_missing_phrases``, ``swept``) rather than
+      forcing every script into an identical key set that doesn't fit.
+    """
+    return {
+        "check": check,
+        "evaluated": list(evaluated),
+        "offenders": offenders,
+        "unclassified": list(unclassified or []),
+        "fixed": fixed or {},
+        "unfixable": list(unfixable or []),
+        "ok": ok,
+        "notes": notes or {},
+    }