pi-dev-team 0.2.0

package/scripts/build_wave_reconcile.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Python port of scripts/build-wave-reconcile.sh (#612 / #572 Phase 3).
+
+Serially merge a wave's completed slice branches into an integration branch,
+then gate on the full suite before the next wave.
+
+Order-independent: branches are merged in a deterministic (sorted) order.
+Because same-wave slices touch disjoint files (build-wave.py's collision gate
+guarantees it) the merged tree is identical regardless of the order slices
+finished. If two branches unexpectedly touch the same file, the merge
+conflicts — the script halts LOUDLY (exit 1, names the file) and **picks no
+side** (it aborts the merge), starting no next-wave slice.
+
+Usage:
+  build_wave_reconcile.py --into <branch> --base <ref> [--test-cmd CMD] <slice-branch>...
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shlex
+import subprocess
+import sys
+from collections.abc import Sequence
+
+# Default hard ceiling for --test-cmd so a hung suite can never block the
+# wave pipeline indefinitely. Override (test-only injection seam) via
+# BUILD_WAVE_RECONCILE_TEST_CMD_TIMEOUT.
+_DEFAULT_TEST_CMD_TIMEOUT_SECONDS = 1800.0
+
+# Characters that require real shell interpretation (pipes, chaining,
+# redirects, expansion, globs, backticks). A --test-cmd containing none of
+# these is a plain word list and can run directly (no shell hop needed).
+_SHELL_METACHARACTERS_RE = re.compile(r"[|&;<>$`*?~]")
+
+
+def _test_cmd_timeout_seconds() -> float:
+    raw = os.environ.get("BUILD_WAVE_RECONCILE_TEST_CMD_TIMEOUT")
+    if raw:
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    return _DEFAULT_TEST_CMD_TIMEOUT_SECONDS
+
+
+def _git(args: Sequence[str], capture: bool = True) -> subprocess.CompletedProcess:
+    """Run `git <args>` with stdout+stderr captured by default."""
+    return subprocess.run(
+        ["git", *args],
+        capture_output=capture,
+        text=True,
+        check=False,
+    )
+
+
+def _branch_exists(name: str) -> bool:
+    r = _git(["rev-parse", "--verify", "--quiet", name])
+    return r.returncode == 0
+
+
+def _checkout_existing(into: str) -> int:
+    r = _git(["checkout", into])
+    if r.returncode != 0:
+        print(
+            f"build-wave-reconcile: cannot check out existing integration "
+            f"branch '{into}'.",
+            file=sys.stderr,
+        )
+        return 2
+    return 0
+
+
+def _create_from_base(into: str, base: str) -> int:
+    r = _git(["checkout", "-B", into, base])
+    if r.returncode != 0:
+        print(
+            f"build-wave-reconcile: cannot create integration branch '{into}' "
+            f"from '{base}'.",
+            file=sys.stderr,
+        )
+        return 2
+    return 0
+
+
+def _merge_branch(branch: str) -> int:
+    r = _git(["merge", "--no-ff", "--no-edit", branch])
+    if r.returncode != 0:
+        # Capture conflicted paths BEFORE aborting.
+        diff = _git(["diff", "--name-only", "--diff-filter=U"])
+        conflicted = ", ".join(
+            line for line in diff.stdout.splitlines() if line.strip()
+        )
+        _git(["merge", "--abort"])
+        print(
+            f"build-wave-reconcile: CONFLICT — same-wave branches touch "
+            f"'{conflicted}'.",
+            file=sys.stderr,
+        )
+        print(
+            "  No side was chosen (merge aborted). Halting; start no next-wave slice.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def _run_test_cmd(cmd: str) -> int:
+    """Run the caller-supplied gate, bounded by a hard timeout so a hung
+    suite can never block the pipeline indefinitely.
+
+    Bash used `eval` with stdout+stderr silenced — mirror that exactly for
+    byte-parity of the diagnostic line. A command with no shell
+    metacharacters is a plain word list and runs directly (list-form,
+    shell=False); a command that chains, pipes, redirects, or expands
+    still needs the shell to interpret it (list-form can't express that
+    syntax), so it runs via shell=True as before.
+    """
+    timeout = _test_cmd_timeout_seconds()
+    use_shell = bool(_SHELL_METACHARACTERS_RE.search(cmd))
+    args: str | list[str] = cmd if use_shell else shlex.split(cmd)
+    try:
+        proc = subprocess.run(
+            args,
+            shell=use_shell,
+            capture_output=True,
+            check=False,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(
+            f"build-wave-reconcile: full-suite gate TIMED OUT after {timeout:g}s "
+            f"('{cmd}'). Halting before the next wave.",
+            file=sys.stderr,
+        )
+        return 1
+    except (OSError, ValueError) as e:
+        print(
+            f"build-wave-reconcile: full-suite gate FAILED ('{cmd}'): {e}. "
+            "Halting before the next wave.",
+            file=sys.stderr,
+        )
+        return 1
+    if proc.returncode != 0:
+        print(
+            f"build-wave-reconcile: full-suite gate FAILED ('{cmd}'). "
+            "Halting before the next wave.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+def _parse_argv(argv: list[str]) -> argparse.Namespace | int:
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument("--into", default="")
+    ap.add_argument("--base", default="")
+    ap.add_argument("--test-cmd", dest="test_cmd", default="")
+    ap.add_argument("branches", nargs="*")
+    # Preserve the bash script's error contract: any unknown option or missing
+    # required flag exits 2 with the same usage line.
+    known: list[str] = []
+    branches: list[str] = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok in ("--into", "--base", "--test-cmd"):
+            if i + 1 >= len(argv):
+                _usage()
+                return 2
+            known.extend([tok, argv[i + 1]])
+            i += 2
+        elif tok.startswith("-"):
+            print(f"unknown option: {tok}", file=sys.stderr)
+            return 2
+        else:
+            branches.append(tok)
+            i += 1
+    parsed = ap.parse_args(known)
+    parsed.branches = branches
+    if not parsed.into or not parsed.base or not parsed.branches:
+        _usage()
+        return 2
+    return parsed
+
+
+def _usage() -> None:
+    # Match the .sh's exact wording (name kept as `build-wave-reconcile.sh`)
+    # so bash and python emit byte-identical stderr on usage errors — the
+    # parity harness gates on this.
+    print(
+        "usage: build-wave-reconcile.sh --into <branch> --base <ref> "
+        "[--test-cmd CMD] <slice-branch>...",
+        file=sys.stderr,
+    )
+
+
+def main(argv: list[str]) -> int:
+    parsed = _parse_argv(argv)
+    if isinstance(parsed, int):
+        return parsed
+
+    into: str = parsed.into
+    base: str = parsed.base
+    test_cmd: str = parsed.test_cmd
+    branches: list[str] = parsed.branches
+
+    # Deterministic merge order → reproducible tree regardless of caller order.
+    sorted_branches = sorted(branches)
+
+    # If $INTO exists, reconcile onto its current tip so caller WIP commits
+    # (spec/plan on the integration branch made before or between waves) stay
+    # in the ancestry. Only create $INTO fresh from $BASE when it does not
+    # exist yet — resetting an existing $INTO to $BASE would silently discard
+    # those WIP commits.
+    if _branch_exists(into):
+        rc = _checkout_existing(into)
+    else:
+        rc = _create_from_base(into, base)
+    if rc != 0:
+        return rc
+
+    for branch in sorted_branches:
+        rc = _merge_branch(branch)
+        if rc != 0:
+            return rc
+
+    if test_cmd:
+        rc = _run_test_cmd(test_cmd)
+        if rc != 0:
+            return rc
+
+    # Match the .sh's exact status suffix. Bash does:
+    #   suite gate ${TESTCMD:+passed}${TESTCMD:-skipped}.
+    # Which expands to 'passed<TESTCMD>' when TESTCMD is set, and
+    # 'skipped' when it's not. That's a shell-substitution quirk in the
+    # .sh, not a spec — but byte-parity is the contract.
+    gate_status = f"passed{test_cmd}" if test_cmd else "skipped"
+
+    print(
+        f"build-wave-reconcile: merged {len(sorted_branches)} slice "
+        f"branch(es) into '{into}'; suite gate {gate_status}."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/build_worktree_baseref.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Python port of scripts/build-worktree-baseref.sh (#587 / #572 Phase 2).
+
+Detects the effective worktree.baseRef setting so /build can warn loudly
+(never mutate) when it is not "head".
+
+Issue #553 / plans/build-worktree-inherits-caller-head.md Slice 1.
+
+Background: Claude Code's `worktree.baseRef: "head"` setting makes
+isolation:"worktree" Agent-tool dispatch branch child worktrees from the
+caller's local HEAD instead of origin/<default> ("fresh", the default).
+docs/spikes/worktree-baseref-head-spike.md empirically confirmed this
+setting is honored only at project (.claude/settings.json) and user
+(~/.claude/settings.json) scope — NOT at project-local
+(.claude/settings.local.json) or plugin (plugins/<name>/settings.json)
+scope. This script's default search order reflects only the two scopes
+that are actually honored.
+
+Usage:
+    build_worktree_baseref.py detect
+
+Prints exactly one token to stdout and always exits 0 (degrade-never-abort):
+    head    — effective setting is "head"
+    fresh   — effective setting is "fresh"
+    unset   — no honored settings file sets worktree.baseRef
+    unknown — detection failed — treat as fail-safe
+
+Env vars (TEST-ONLY injection seam):
+    BASEREF_SETTINGS_PATHS   colon-separated list of settings files,
+                             highest precedence first. Defaults to
+                             ".claude/settings.json:$HOME/.claude/settings.json".
+
+Stdlib-only (json/os/pathlib/sys). See ADR 0014.
+
+Refs: #572, #577, #553.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _default_settings_paths() -> str:
+    home = os.environ.get("HOME", "")
+    return f".claude/settings.json:{home}/.claude/settings.json"
+
+
+def _settings_paths() -> list[str]:
+    raw = os.environ.get("BASEREF_SETTINGS_PATHS")
+    if raw is None:
+        raw = _default_settings_paths()
+    # Preserve the .sh's colon-separated parsing including empty segments
+    # (the `[ -n "$f" ] || continue` guard skips them).
+    return [p for p in raw.split(":") if p]
+
+
+def _load_worktree_baseref(path: Path) -> str | None:
+    """Return the .worktree.baseRef value from `path`, or None on any error.
+
+    None distinguishes 'file unreadable or malformed' (skip to next file)
+    from an empty string (parseable but no baseRef — also skip).
+    """
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    wt = data.get("worktree")
+    if not isinstance(wt, dict):
+        return None
+    value = wt.get("baseRef")
+    if not isinstance(value, str):
+        return None
+    return value
+
+
+def _detect() -> str:
+    """Walk settings files in precedence order. First honored value wins.
+
+    Every file that fails to parse or lacks the key is skipped rather than
+    aborting the whole detection. The .sh also gates on `command -v jq`;
+    the .py has no such external dependency but keeps the 'unknown' exit
+    reserved for future contract expansion.
+    """
+    for raw in _settings_paths():
+        path = Path(raw)
+        if not path.is_file():
+            continue
+        value = _load_worktree_baseref(path)
+        if value == "head" or value == "fresh":
+            return value
+    return "unset"
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else list(argv)
+    if not args or args[0] != "detect":
+        # Byte-parity with the .sh's usage message: name it after the .sh
+        # executable so operators searching for the exact string in logs
+        # find it regardless of which implementation ran.
+        sys.stderr.write("Usage: build-worktree-baseref.sh detect\n")
+        return 2
+    sys.stdout.write(_detect() + "\n")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/check_agent_scope.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Validate that every review agent declares a body-level Scope: field.
+
+``Scope:`` is a body-level declaration, not frontmatter (issue #1333 — it is
+not part of the official Claude Code sub-agent contract; see
+plugins/marketplace-dev/knowledge/agent-contract.json).
+
+Exit 0 if all review agents have a Scope: line in their body.
+Exit 1 with a list of offending agents if any are missing.
+
+Usage:
+    python3 check_agent_scope.py [--agents-dir <path>]
+
+The agents directory defaults to plugins/dev-team/agents/ relative to the
+repo root (inferred from this script's location).
+"""
+
+# Keeps PEP 585 annotations (`list[str]`) as strings, so this module imports on
+# the floor ADR 0014 sets for shipped code.
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+# The `agents/` directory root is the shared, resolved single source of
+# truth in hooks/lib (#1904 item 3) — scripts/ -> hooks/lib/ is the correct
+# dependency direction (see review_agent_registry.py's own docstring). This
+# script globs all agents/*.md (not just *-review.md), so it uses only
+# default_agents_dir() for the directory path — never
+# registered_review_agent_names()/find_review_agent_files(), which are
+# review-agent-specific.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "hooks" / "lib"))
+
+# Review agents are the agents named in the Review Agents section of
+# knowledge/agent-registry.md.  Rather than parsing that file we check all
+# agents/*.md files that contain a 'description:' frontmatter field and are
+# not one of the well-known non-review agents.  The exclusion set is shared
+# with select_lenses.py (#1516) — see scripts/lib/review_roster.py.
+from review_agent_registry import default_agents_dir
+from review_roster import NON_REVIEW_AGENTS
+from review_roster import SCOPE_LINE_RE as SCOPE_RE
+
+
+def has_frontmatter(text: str) -> bool:
+    """True if the file opens with a YAML frontmatter block."""
+    return text.startswith("---") and "---" in text[3:]
+
+
+def strip_frontmatter(text: str) -> str:
+    """Return the body (everything after the frontmatter block)."""
+    if not text.startswith("---"):
+        return text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return text
+    after = text.find("\n", end + 1)
+    return text[after + 1:] if after != -1 else ""
+
+
+def declares_scope(body: str) -> bool:
+    """True if the body contains a Scope: line (scalar or block-list)."""
+    return any(SCOPE_RE.match(line) for line in body.splitlines())
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        default=None,
+        help="Path to the agents/ directory (default: auto-detect from script location)",
+    )
+    args = parser.parse_args()
+
+    if args.agents_dir is not None:
+        agents_dir = args.agents_dir
+    else:
+        agents_dir = default_agents_dir()
+
+    if not agents_dir.is_dir():
+        print(f"ERROR: agents directory not found: {agents_dir}", file=sys.stderr)
+        return 1
+
+    missing: list[str] = []
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = agent_file.stem
+        if name in NON_REVIEW_AGENTS:
+            continue
+        text = agent_file.read_text(encoding="utf-8")
+        if not has_frontmatter(text):
+            # No frontmatter — skip (not an agent file)
+            continue
+        body = strip_frontmatter(text)
+        if not declares_scope(body):
+            missing.append(name)
+
+    if missing:
+        print("FAIL: the following review agents are missing a 'Scope:' body declaration:")
+        for name in missing:
+            print(f"  - {name}")
+        print(
+            "\nAdd one of: 'Scope: always' (language-agnostic, every diff), a bullet list "
+            "of glob patterns (file-type-scoped), 'Scope: added-only' + globs (only newly-"
+            "added matching files), or 'Scope: on-demand' (never per-diff — dispatched by "
+            "name or by /repo-review).  See plugins/dev-team/docs/developer-notes.md."
+        )
+        return 1
+
+    print(f"OK: all {len(list(agents_dir.glob('*.md'))) - len(NON_REVIEW_AGENTS)} "
+          f"review agents declare a Scope: field.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_agent_tool_mapping.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Validate the non-review agent→code-intelligence-tool mapping (#1108).
+
+#1102 granted the 24 read-only ``*-review`` agents a fixed MCP tool set
+(``check_review_agent_mcp_tools.py``). #1108 extends the grant to the non-review
+team agents by **tier**:
+
+- **narrow** — codegraph + the four Repowise tools (``BASE_MCP_TOOLS``):
+  ``software-engineer``, ``mutation-kill``, ``qa-engineer``, ``data-flow-tracer``.
+  ``data-flow-tracer`` additionally gets a scoped ``Bash(graphify *)`` grant (its
+  sole execution capability — it invokes the Graphify CLI for cross-layer traces).
+- **rationale** — the narrow set plus ``get_why`` (code-existence rationale):
+  ``adr-author``, ``architect``, ``security-engineer``, ``platform-engineer``,
+  ``codebase-recon``.
+
+Coverage is the **union** of two branches so a named target is always validated
+even when it carries no persona marker, and a *new* team agent can't silently
+escape the mapping:
+
+- (a) every agent named in ``TIER_CONFIG`` — deterministic coverage of the known
+  targets (``codebase-recon`` is ``Enforcement: script``; ``mutation-kill`` carries
+  neither persona marker — branch (b) alone would miss both).
+- (b) the structural sweep — team agents detected by a ``## Behavioral Guidelines``
+  section *or* an ``Enforcement: script`` body line (not frontmatter — issue
+  #1333), minus ``*-review.md``, minus the documented ``EXCLUSIONS``. A swept
+  agent in neither ``TIER_CONFIG`` nor ``EXCLUSIONS`` is *unclassified* and
+  fails — the self-extension net.
+
+A granted MCP tool whose server is absent is inert at runtime; agents fall back to
+Read/Grep/Glob.
+
+Usage (repo-root-relative — this script mutates the agent files next to
+wherever it itself resides, so it must run against the maintainer's own
+checkout, never a `${CLAUDE_PLUGIN_ROOT}`-qualified installed-cache path):
+    python3 plugins/dev-team/scripts/check_agent_tool_mapping.py [--agents-dir <path>]
+    python3 plugins/dev-team/scripts/check_agent_tool_mapping.py --fix     # append missing tier tools
+    python3 plugins/dev-team/scripts/check_agent_tool_mapping.py --json     # machine-readable report
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "lib"))
+# The `agents/` directory root is the shared, resolved single source of
+# truth in hooks/lib (#1904 item 3) — scripts/ -> hooks/lib/ is the correct
+# dependency direction (see review_agent_registry.py's own docstring).
+sys.path.insert(0, str(Path(__file__).parent.parent / "hooks" / "lib"))
+
+from mcp_tool_grants import (
+    BASE_MCP_TOOLS,
+    GET_WHY,
+    build_json_report,
+    run_grants_check,
+)
+from review_agent_registry import default_agents_dir
+
+# Tiers ---------------------------------------------------------------------
+NARROW = list(BASE_MCP_TOOLS)
+RATIONALE = BASE_MCP_TOOLS + [GET_WHY]
+_GRAPHIFY_BASH = "Bash(graphify *)"
+
+# The canonical non-review mapping. Each agent → the tool names its tier requires
+# in `tools:` (merge target, never a replacement — existing grants are preserved).
+TIER_CONFIG = {
+    "software-engineer": NARROW,
+    "mutation-kill": NARROW,
+    "qa-engineer": NARROW,
+    "data-flow-tracer": NARROW + [_GRAPHIFY_BASH],
+    "adr-author": RATIONALE,
+    "architect": RATIONALE,
+    "security-engineer": RATIONALE,
+    "platform-engineer": RATIONALE,
+    "codebase-recon": RATIONALE,
+}
+
+# Team agents the structural sweep surfaces but the mapping deliberately does NOT
+# grant (dispatch-only, non-code-structure roles). Exactly the swept agents absent
+# from TIER_CONFIG — no more, no less. `session-analysis` and `mutation-kill` carry
+# neither marker, so the sweep never surfaces them (they need no exclusion entry;
+# mutation-kill is covered via TIER_CONFIG).
+EXCLUSIONS = {
+    "orchestrator",
+    "product-manager",
+    "ui-ux-designer",
+    "tech-writer",
+    "progress-guardian",
+}
+
+_BEHAVIORAL_RE = re.compile(r"^##\s+Behavioral Guidelines\s*$", re.MULTILINE)
+_ENFORCEMENT_RE = re.compile(r"^Enforcement:\s*script\s*$", re.MULTILINE)
+
+
+def is_team_agent(text: str) -> bool:
+    """True if the file is a team agent per agent-audit §2c's markers.
+
+    A team agent carries a ``## Behavioral Guidelines`` section OR declares
+    ``Enforcement: script`` (a body-level declaration, not frontmatter — issue
+    #1333 — marking a script-enforced prose spec: still a team agent for
+    coverage purposes, just persona-exempt).
+    """
+    return bool(_BEHAVIORAL_RE.search(text) or _ENFORCEMENT_RE.search(text))
+
+
+def swept_agents(agents_dir: Path) -> list[str]:
+    """Structural sweep (branch b): team agents minus *-review, sorted by stem."""
+    out = []
+    for path in sorted(agents_dir.glob("*.md")):
+        if path.name.endswith("-review.md"):
+            continue
+        if is_team_agent(path.read_text(encoding="utf-8")):
+            out.append(path.stem)
+    return out
+
+
+def _targets(agents_dir: Path) -> dict[str, tuple[Path, list[str]]]:
+    return {name: (agents_dir / f"{name}.md", required) for name, required in TIER_CONFIG.items()}
+
+
+def _unclassified(covered: list[str]) -> list[str]:
+    return sorted(name for name in covered if name not in TIER_CONFIG and name not in EXCLUSIONS)
+
+
+def evaluate(agents_dir: Path) -> dict:
+    """Return the mapping report: covered set, offenders, unclassified.
+
+    covered = union of TIER_CONFIG keys (branch a) and the sweep (branch b).
+    offenders = {agent: missing tools} for covered config agents under-granted.
+    unclassified = swept team agents in neither TIER_CONFIG nor EXCLUSIONS.
+    """
+    swept = swept_agents(agents_dir)
+    covered = sorted(set(TIER_CONFIG) | set(swept))
+    offenders, _fixed, _unfixable = run_grants_check(_targets(agents_dir))
+
+    return {
+        "covered": covered,
+        "swept": swept,
+        "offenders": offenders,
+        "unclassified": _unclassified(covered),
+    }
+
+
+def apply_fixes(agents_dir: Path) -> dict[str, list[str]]:
+    """Append missing tier tools to each under-granted config agent. Returns fixed map.
+
+    Unclassified agents are not auto-fixed (they need a human classification
+    decision) — the caller reports them and exits non-zero.
+    """
+    _offenders, fixed, _unfixable = run_grants_check(_targets(agents_dir), apply_fix=True)
+    return fixed
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--agents-dir", type=Path, default=None)
+    parser.add_argument("--fix", action="store_true", help="append missing tier tools")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    agents_dir = args.agents_dir or default_agents_dir()
+    if not agents_dir.is_dir():
+        print(f"ERROR: agents directory not found: {agents_dir}", file=sys.stderr)
+        return 1
+
+    swept = swept_agents(agents_dir)
+    covered = sorted(set(TIER_CONFIG) | set(swept))
+    offenders, fixed, unfixable = run_grants_check(_targets(agents_dir), apply_fix=args.fix)
+    unclassified = _unclassified(covered)
+    rc = 1 if (offenders or unclassified) else 0
+
+    if args.json:
+        # --json owns stdout: emit ONLY the JSON object.
+        report = build_json_report(
+            "agent-tool-mapping",
+            covered,
+            offenders,
+            ok=(rc == 0),
+            fixed=fixed,
+            unfixable=unfixable,
+            unclassified=unclassified,
+            notes={"swept": swept},
+        )
+        print(json.dumps(report, indent=2))
+        return rc
+
+    if args.fix:
+        if fixed:
+            for name, added in fixed.items():
+                print(f"FIXED: {name} — added {', '.join(added)}")
+        else:
+            print("OK: all mapped agents already grant their tier tools.")
+
+    if offenders:
+        print("FAIL: non-review agents missing their tier's code-intelligence tools:")
+        for name, missing in offenders.items():
+            print(f"  - {name}: missing {', '.join(missing)}")
+        print("\nRun: python3 plugins/dev-team/scripts/check_agent_tool_mapping.py --fix")
+    if unclassified:
+        print("FAIL: team agents in neither the mapping nor the exclusion list "
+              "(classify each into TIER_CONFIG or EXCLUSIONS):")
+        for name in unclassified:
+            print(f"  - {name}")
+    if rc == 0:
+        print(f"OK: all {len(covered)} covered agents match the tool mapping.")
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())