pi-dev-team 0.2.0

package/scripts/token_efficiency_review.py

@@ -0,0 +1,322 @@
+"""token_efficiency_review.py — Metrics-based token efficiency reviewer.
+
+Checks files for token-efficiency violations:
+  - CLAUDE.md: character count > 5000 (error), top-level rule count > 200 (error)
+  - Any file: line count > 500 (warning)
+  - .md files: optional LLM quality review (unless --skip-llm)
+
+Exit codes (matches review_result contract):
+  0 = pass (clean)
+  1 = fail (hard errors)
+  2 = warnings only OR LLM check skipped
+
+Usage:
+  python3 ${CLAUDE_PLUGIN_ROOT}/scripts/token_efficiency_review.py --files <path> [<path>...] [--skip-llm]
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from lib.review_result import build_result, main_exit, make_issue, skipped_llm_warning
+
+sys.path.insert(
+    0,
+    str(Path(__file__).resolve().parent.parent / "hooks" / "lib"),
+)
+from token_efficiency_limits import (
+    CLAUDE_MD_CHAR_LIMIT,
+    CLAUDE_MD_RULE_LIMIT,
+    FILE_LINE_LIMIT,
+    is_claude_md_file,
+)
+
+# ---------------------------------------------------------------------------
+# CLAUDE.md checks
+# ---------------------------------------------------------------------------
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Remove YAML frontmatter (--- ... ---) from the top of text."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return text
+    # Find closing ---
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "---":
+            return "\n".join(lines[idx + 1 :])
+    # No closing marker found — treat entire text as body
+    return text
+
+
+def _count_top_level_bullets(text: str) -> int:
+    """Count top-level bullet/numbered list items at indent level 0.
+
+    Patterns counted:
+      - ^- (unordered bullet)
+      - ^\\d+\\. (ordered list item)
+
+    Excludes lines inside YAML frontmatter (already stripped by caller).
+    """
+    count = 0
+    bullet_re = re.compile(r"^(-\s|\d+\.\s)")
+    for line in text.splitlines():
+        if bullet_re.match(line):
+            count += 1
+    return count
+
+
+def check_claude_md(path: Path) -> list[dict]:
+    """Run CLAUDE.md-specific checks. Returns list of issue dicts."""
+    issues: list[dict] = []
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        issues.append(
+            make_issue(
+                "error",
+                "high",
+                str(path),
+                0,
+                f"Cannot read file: {exc}",
+                rule_id="read-error",
+            )
+        )
+        return issues
+
+    # 1. Character count
+    char_count = len(text)
+    if char_count > CLAUDE_MD_CHAR_LIMIT:
+        issues.append(
+            make_issue(
+                "error",
+                "high",
+                str(path),
+                0,
+                (
+                    f"CLAUDE.md exceeds character limit: {char_count} chars "
+                    f"(limit {CLAUDE_MD_CHAR_LIMIT}). Trim or move content to skills."
+                ),
+                "Extract procedures into skill files; remove duplicate or verbose sections.",
+                rule_id="claude-md-char-limit",
+            )
+        )
+
+    # 2. Top-level rule/bullet count
+    body = _strip_frontmatter(text)
+    rule_count = _count_top_level_bullets(body)
+    if rule_count > CLAUDE_MD_RULE_LIMIT:
+        issues.append(
+            make_issue(
+                "error",
+                "high",
+                str(path),
+                0,
+                (
+                    f"CLAUDE.md has {rule_count} top-level bullet/rule items "
+                    f"(limit {CLAUDE_MD_RULE_LIMIT}). Consolidate or move items to skills."
+                ),
+                "Group related rules into a skill file; remove duplicate instructions.",
+                rule_id="claude-md-rule-limit",
+            )
+        )
+
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Line count check
+# ---------------------------------------------------------------------------
+
+
+def check_line_counts(files: list[Path]) -> list[dict]:
+    """Return warning findings for files exceeding FILE_LINE_LIMIT lines."""
+    issues: list[dict] = []
+    for path in files:
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        line_count = len(lines)
+        if line_count > FILE_LINE_LIMIT:
+            issues.append(
+                make_issue(
+                    "warning",
+                    "high",
+                    str(path),
+                    0,
+                    (
+                        f"File exceeds line limit: {line_count} lines "
+                        f"(limit {FILE_LINE_LIMIT}). Consider splitting."
+                    ),
+                    "Extract sections into separate files or skills.",
+                    rule_id="file-line-limit",
+                )
+            )
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# LLM review
+# ---------------------------------------------------------------------------
+
+
+def is_prose_file(path: Path) -> bool:
+    """Return True when the file is a prose/markdown file suitable for LLM review."""
+    return path.suffix.lower() == ".md"
+
+
+def run_llm_review(path: Path) -> list[dict]:
+    """Call claude CLI to review a prose file. Returns warning-severity findings.
+
+    LLM unavailability → returns a single warning finding (exit 2, not 1).
+    """
+    prompt = (
+        "Review this file for LLM anti-patterns that waste tokens in Claude Code config files:\n"
+        "- Role preambles (You are a..., Act as...)\n"
+        "- Conversational filler (Please note, It's important to)\n"
+        "- Redundant context (same info repeated)\n"
+        "- Hedging language (You might want to, Consider)\n"
+        "- Verbose explanations before instructions\n\n"
+        f"File: {path}\n"
+        f"Content:\n{path.read_text(encoding='utf-8', errors='replace')[:3000]}\n\n"
+        "Output a JSON array of findings (may be empty []). Each finding: "
+        '{"message": "...", "line": 0, "suggestedFix": "..."}. '
+        "Do NOT include any text outside the JSON array."
+    )
+    issues: list[dict] = []
+    try:
+        result = subprocess.run(
+            ["claude", "-p", prompt],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            issues.append(
+                make_issue(
+                    "warning",
+                    "high",
+                    str(path),
+                    0,
+                    "LLM review unavailable (claude exited non-zero or no output)",
+                    rule_id="llm-unavailable",
+                )
+            )
+            return issues
+        # Parse JSON output from LLM
+        import json
+
+        raw = result.stdout.strip()
+        # Extract JSON array if surrounded by extra text
+        start = raw.find("[")
+        end = raw.rfind("]")
+        if start == -1 or end == -1:
+            return issues
+        findings = json.loads(raw[start : end + 1])
+        for f in findings:
+            if not isinstance(f, dict):
+                continue
+            issues.append(
+                make_issue(
+                    "warning",  # LLM findings are always warning severity
+                    "medium",
+                    str(path),
+                    int(f.get("line", 0)),
+                    str(f.get("message", "LLM finding")),
+                    str(f.get("suggestedFix", "")),
+                    rule_id="llm-quality",
+                )
+            )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        issues.append(
+            make_issue(
+                "warning",
+                "high",
+                str(path),
+                0,
+                "LLM review skipped (claude not found or timed out)",
+                rule_id="llm-unavailable",
+            )
+        )
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--files",
+        nargs="+",
+        metavar="PATH",
+        default=[],
+        help="Files to review (required)",
+    )
+    parser.add_argument(
+        "--skip-llm",
+        action="store_true",
+        help="Skip LLM quality review; add an llm-skipped warning instead",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.files:
+        print(
+            '{"status":"fail","issues":[{"severity":"error","confidence":"high","file":"","line":0,"message":"No files specified. Use --files <path>...","suggestedFix":"","rule_id":"no-files"}],"summary":""}'
+        )
+        return 1
+
+    files = [Path(p) for p in args.files]
+    errors: list[dict] = []
+    warnings: list[dict] = []
+
+    for path in files:
+        # CLAUDE.md-specific checks
+        if is_claude_md_file(path):
+            for issue in check_claude_md(path):
+                if issue["severity"] == "error":
+                    errors.append(issue)
+                else:
+                    warnings.append(issue)
+
+    # Line count checks for all files
+    warnings.extend(check_line_counts(files))
+
+    # LLM review for prose (.md) files
+    prose_files = [p for p in files if is_prose_file(p)]
+    if args.skip_llm:
+        # Unconditional by design: --skip-llm is explicit intent to skip, so
+        # the warning is recorded whether or not any prose file was in scope.
+        # This was previously an if/else whose two branches were identical
+        # (#1651) — the condition read as though the prose-file case differed,
+        # and it never did.
+        warnings.append(skipped_llm_warning())
+    else:
+        for path in prose_files:
+            warnings.extend(run_llm_review(path))
+
+    summary_parts = []
+    if errors:
+        summary_parts.append(f"{len(errors)} error(s)")
+    if warnings:
+        summary_parts.append(f"{len(warnings)} warning(s)")
+    summary = ", ".join(summary_parts) if summary_parts else "No issues found."
+
+    result = build_result(errors, warnings, summary)
+    return main_exit(result)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/verdict_scope.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""Scope a review dispatch to the delta the verdict ledger hasn't already
+cleared (#2167).
+
+Given a candidate `{lens: [file, ...], ...}` dispatch plan, consult
+`hooks/lib/review_verdicts.py`'s per-lens verdict ledger
+(`.claude/metrics/review-verdicts.jsonl`, written by
+`hooks/review_verdict_recorder.py` on every real review-agent dispatch) and
+split each lens's file list into the files that still need a live dispatch
+and the ones an exact `(lens, file_path, current file_content_hash)` match
+already cleared with outcome `"pass"`.
+
+Shared by both call sites the epic (#2164) names: `/code-review` step 4 (a
+repeat run over an unchanged target set should dispatch nothing) and
+`/build`'s own inline checkpoints (sub-steps 4/6) plus its Step 6 backstop
+(a slice already cleared at a checkpoint has nothing left for the backstop
+to review) -- one resolver, not two independently-drifting copies, mirroring
+`select_lenses.py`'s own shared-between-both-skills precedent.
+
+## Fail-closed, by design (#2167 acceptance criteria)
+
+A file is skipped ONLY on an exact `(lens, file_path, file_content_hash)`
+match whose most-recent ledger row (rows are append-only; the last matching
+row in file order is the most recent) has `outcome == "pass"`. Every other
+case dispatches normally:
+
+- No ledger, an unreadable ledger, or a line `load_verdicts` couldn't parse
+  -- `load_verdicts` itself already degrades these to "no usable rows"
+  (see that function's own docstring); this module inherits that posture
+  without adding a second one.
+- A row whose `plugin_version` is older than the version running now --
+  same source: `load_verdicts` has already excluded it before this module
+  ever sees the row.
+- The file can't be hashed right now (deleted, unreadable, not a regular
+  file, or over `review_verdicts.MAX_HASH_FILE_BYTES`) -- `hash_file`
+  returns `None`, and a `None` hash never matches anything, so the file
+  always stays in `toDispatch`.
+- The most-recent matching row's outcome is `"findings"`, not `"pass"`.
+- No row at all shares this exact `(lens, file_path, file_content_hash)`
+  triple -- a different lens, a different file, or the same file at
+  different content (a hash mismatch) are all "no match".
+
+This is the same ambiguity-resolves-toward-more-work posture
+`select_lenses.py`'s own docstring already documents for its resolver --
+just applied to *whether* a lens/file needs a fresh dispatch rather than
+*which* lenses apply at all.
+
+## Canonicalization (#2167 correctness/security/arch review)
+
+The ledger's own `file_path` is always the writer's canonical, `root`-
+relative POSIX form (`hooks/review_verdict_recorder.py`'s own
+`_resolve_under_cwd`/`canonical_path`). Every candidate file this module is
+handed is canonicalized the SAME way (`_canonicalize_lens_files`,
+`compute_file_hashes`) before either hashing or matching it against a
+ledger row -- comparing a caller's raw spelling (`./a.py`, an absolute
+path) against the writer's canonical one would otherwise silently never
+match, defeating the whole point of this module without ever being wrong
+(a missed skip, never a false one). A file that can't be canonicalized
+(escapes `root`, unresolvable) keeps its raw string as a deliberately
+unmatchable placeholder rather than raising or guessing.
+
+Stdlib-only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_HOOKS_LIB_DIR = _HERE.parent / "hooks" / "lib"
+if str(_HOOKS_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_LIB_DIR))
+
+from instrument_log import append_row  # type: ignore[import-not-found]
+
+# No `except ImportError` fallback (matches `select_lenses.py`'s own rule,
+# #1968): `hooks/lib/` ships inside this same plugin, always present
+# wherever this script runs. A hand-written second copy of
+# `hash_file`/`load_verdicts` is exactly the kind of independently-drifting
+# duplicate that rule exists to prevent -- here it would silently turn every
+# lookup into a guaranteed miss (safe, but defeats the entire point of this
+# module) rather than raising loudly.
+try:
+    from review_verdicts import (  # type: ignore[import-not-found]
+        canonical_path,
+        hash_file,
+        load_verdicts,
+    )
+except ImportError as exc:  # pragma: no cover - broken install, not a supported mode
+    raise ImportError(
+        f"{__name__} requires 'review_verdicts' from the dev-team plugin's "
+        f"hooks/lib, which could not be imported.\n"
+        f"  searched: {_HOOKS_LIB_DIR}\n"
+        f"  exists:   {_HOOKS_LIB_DIR.is_dir()}\n"
+        "This module deliberately has no fallback copy of the hashing/ledger "
+        "read logic -- a divergent stand-in would make every skip decision "
+        "silently wrong. Fix the install or the path rather than re-adding a "
+        "local implementation."
+    ) from exc
+
+_PASS_OUTCOME = "pass"
+
+
+def _latest_matching_verdict(
+    verdicts: list[dict], lens: str, file_path: str, file_hash: str
+) -> dict | None:
+    """The most-recent row (last one in append order) sharing the exact
+    `(lens, file_path, file_content_hash)` triple, or `None` if no row
+    matches at all."""
+    match: dict | None = None
+    for row in verdicts:
+        if (
+            row.get("lens") == lens
+            and row.get("file_path") == file_path
+            and row.get("file_content_hash") == file_hash
+        ):
+            match = row
+    return match
+
+
+def resolve_dispatch(
+    lens_files: dict[str, list[str]],
+    verdicts: list[dict],
+    file_hashes: dict[str, str | None],
+) -> dict:
+    """Pure resolver. `lens_files` maps a lens name to the candidate files
+    already matched to it (by `Scope:`/change-shape/etc. gating upstream --
+    this function narrows *within* that set, it never widens it).
+    `file_hashes` maps each candidate file to its current content hash, or
+    `None` when it couldn't be hashed (see module docstring).
+
+    Returns `{"toDispatch": {lens: [file, ...]}, "skipped": {lens: [{"file":
+    ..., "verdict": <the matched row>}, ...]}, "fullySkippedLenses":
+    [lens, ...]}`. A lens with at least one file left to dispatch appears in
+    `toDispatch` with only those files (its ledger-cleared files are simply
+    absent from that list, not present-but-empty); a lens with EVERY
+    candidate file cleared is absent from `toDispatch` entirely and named in
+    `fullySkippedLenses` -- the caller's signal to not dispatch that lens
+    this round at all. `lens_files` is preserved as the source of truth for
+    "was this lens even a candidate": a lens with an empty candidate list to
+    begin with never appears in any of the three outputs.
+    """
+    to_dispatch: dict[str, list[str]] = {}
+    skipped: dict[str, list[dict]] = {}
+
+    for lens, files in lens_files.items():
+        keep: list[str] = []
+        skip_entries: list[dict] = []
+        for file_path in files:
+            file_hash = file_hashes.get(file_path)
+            row = (
+                _latest_matching_verdict(verdicts, lens, file_path, file_hash)
+                if file_hash
+                else None
+            )
+            if row is not None and row.get("outcome") == _PASS_OUTCOME:
+                skip_entries.append({"file": file_path, "verdict": row})
+            else:
+                keep.append(file_path)
+        if keep:
+            to_dispatch[lens] = keep
+        if skip_entries:
+            skipped[lens] = skip_entries
+
+    fully_skipped = [lens for lens in lens_files if lens in skipped and lens not in to_dispatch]
+
+    return {
+        "toDispatch": to_dispatch,
+        "skipped": skipped,
+        "fullySkippedLenses": fully_skipped,
+    }
+
+
+def compute_file_hashes(files, root: Path) -> dict[str, str | None]:
+    """I/O boundary: hash every file in `files` (deduped), canonicalizing
+    each against `root` first (`review_verdicts.canonical_path` -- #2167
+    review: an absolute path, a `./`-prefixed path, or one outside `root`
+    entirely must never be naively joined onto `root` and hashed as-is). A
+    file that can't be canonicalized, doesn't exist under `root`, or that
+    `hash_file` otherwise can't read, maps to `None` -- never omitted, so a
+    caller iterating `file_hashes` can always find every candidate file's
+    entry."""
+    root_resolved = Path(root).resolve()
+    hashes: dict[str, str | None] = {}
+    for f in dict.fromkeys(files):
+        canonical = canonical_path(f, root)
+        hashes[f] = hash_file(root_resolved / canonical) if canonical is not None else None
+    return hashes
+
+
+def _load_json_arg(value: str):
+    """Load JSON from an inline JSON string, or from a file path when it
+    isn't one.
+
+    Tries the inline parse FIRST (#2167 correctness review): the previous
+    check-path-first order called `Path(value).exists()` on the raw
+    argument, and `Path.exists()` raises `OSError` (`ENAMETOOLONG` on
+    Linux) rather than returning `False` once `value` is a string longer
+    than `PATH_MAX` -- which any real `--lens-files` JSON for a multi-lens,
+    multi-file round easily is (a ~30-file, 10-lens round is already
+    several KB). A JSON literal is never also a path a caller would pass
+    here, so trying the inline parse first costs nothing in the common case
+    and never stats the filesystem with an oversized string."""
+    try:
+        return json.loads(value)
+    except ValueError:
+        return json.loads(Path(value).read_text())
+
+
+def _canonicalize_lens_files(
+    lens_files: dict[str, list[str]], root: Path
+) -> dict[str, list[str]]:
+    """Canonicalize every candidate file against `root` before matching it
+    to the ledger (#2167 review: correctness/security/arch all
+    independently flagged that the writer always stores a canonical,
+    `root`-relative POSIX `file_path`, so comparing a caller's raw string
+    against it -- `./a.py`, an absolute path -- silently never matches a
+    genuine row). A file that can't be canonicalized keeps its RAW string
+    as a deliberately unmatchable placeholder: no genuine ledger row's
+    `file_path` can ever equal an un-canonicalizable string, so it always
+    falls through to `toDispatch` (fail-closed, never a false skip).
+
+    The caller sees the CANONICAL form back in `toDispatch`/`skipped`, not
+    its original spelling -- for every real call site (SKILL.md's own
+    already-`root`-relative file lists, from `changed_file_list.py`'s git
+    diff output) canonicalization is a no-op, so this is not a behavior
+    change there; only a caller passing an absolute or `./`-prefixed path
+    sees its spelling normalized in the response, which still names the
+    same file."""
+    return {
+        lens: [canonical_path(f, root) or f for f in files] for lens, files in lens_files.items()
+    }
+
+
+def resolve_for_root(lens_files: dict[str, list[str]], root: Path) -> dict:
+    """Canonicalize, hash, read the ledger under ``root``, and resolve -- the
+    same pipeline ``main`` runs, exposed so in-process callers (e.g.
+    ``ship_review_gate.py``, #2212) never touch the ledger reader directly."""
+    lens_files = _canonicalize_lens_files(lens_files, root)
+    all_files = [f for files in lens_files.values() for f in files]
+    return resolve_dispatch(lens_files, load_verdicts(root), compute_file_hashes(all_files, root))
+
+
+def _log_skips(lens_files: dict[str, list[str]], result: dict, root: Path) -> None:
+    """Persist this consult's skip counts (#2201) -- fail-open, stdout untouched."""
+    skipped = sum(len(v) for v in result["skipped"].values())
+    append_row(
+        "ledger-skips",
+        {
+            "candidate_pairs": sum(len(v) for v in lens_files.values()),
+            "skipped_pairs": skipped,
+            "fully_skipped_lenses": result["fullySkippedLenses"],
+        },
+        cwd=root,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default=".", help="Repo/worktree root the ledger lives under")
+    parser.add_argument(
+        "--lens-files",
+        required=True,
+        help='JSON (file or inline) mapping lens name to its candidate file list: {"<lens>": ["<file>", ...], ...}',
+    )
+    args = parser.parse_args(argv)
+
+    root = Path(args.root)
+    lens_files = _canonicalize_lens_files(_load_json_arg(args.lens_files), root)
+
+    all_files = [f for files in lens_files.values() for f in files]
+    file_hashes = compute_file_hashes(all_files, root)
+    verdicts = load_verdicts(root)
+
+    result = resolve_dispatch(lens_files, verdicts, file_hashes)
+    _log_skips(lens_files, result, root)
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())