pi-dev-team 0.2.0

package/hooks/token_efficiency_review.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Python port of hooks/token-efficiency-review.sh (#607 / #572 Phase 3).
+
+PostToolUse hook for Write/Edit — checks file length, CLAUDE.md length,
+and function length. Emits advisory warnings on stdout; never blocks.
+
+Contract (docs/python-hook-contract.md):
+    Input : PostToolUse JSON on stdin
+    Output: Advisory warnings on stdout, or empty
+    Exit  : Always 0
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+try:
+    from token_efficiency_limits import (  # type: ignore[import-not-found]
+        CLAUDE_MD_CHAR_LIMIT,
+        FILE_LINE_LIMIT,
+    )
+    from token_efficiency_limits import char_count as _char_count
+    from token_efficiency_limits import is_claude_md_file as _is_claude_md_file
+except ImportError:
+    # Fail-open per the hook contract: never let a missing sibling module
+    # break advisory output. Mirror the shared defaults and logic.
+    CLAUDE_MD_CHAR_LIMIT = 5000
+    FILE_LINE_LIMIT = 500
+
+    def _is_claude_md_file(path: Path) -> bool:
+        return path.name.lower() == "claude.md"
+
+    def _char_count(path: Path) -> int:
+        return len(path.read_text(encoding="utf-8", errors="replace"))
+
+
+# The .sh's awk pattern: function-declaration heuristics for common
+# languages. Three alternatives (top-level function keyword; const/let/var =
+# fn; indented method opening) — the same set the .sh emits.
+_FUNC_START_RE = re.compile(
+    r"^\s*(async\s+)?function\s+[a-zA-Z_]"
+    r"|"
+    r"^\s*(const|let|var)\s+[a-zA-Z_]+\s*=\s*(async\s+)?\("
+    r"|"
+    r"^\s+[a-zA-Z_]+\s*\([^)]*\)\s*\{"
+)
+
+
+_SOURCE_EXTS = (
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".py",
+    ".rb",
+    ".go",
+    ".rs",
+    ".java",
+    ".cs",
+)
+
+
+def _extract_path(payload: dict) -> str:
+    """Mirror `.tool_input.file_path // .tool_input.path // .file_path // .path`."""
+    tool_input = payload.get("tool_input") or {}
+    return (
+        tool_input.get("file_path")
+        or tool_input.get("path")
+        or payload.get("file_path")
+        or payload.get("path")
+        or ""
+    )
+
+
+def _read_json(raw: bytes) -> dict:
+    try:
+        return json.loads(raw or b"{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def _check_claude_md(path: Path) -> str | None:
+    """Character-count check for CLAUDE.md files."""
+    if not _is_claude_md_file(path):
+        return None
+    try:
+        count = _char_count(path)
+    except OSError:
+        return None
+    if count > CLAUDE_MD_CHAR_LIMIT:
+        return (
+            f"Token: CLAUDE.md is {count} chars (limit: {CLAUDE_MD_CHAR_LIMIT}). "
+            "Move detailed examples to docs/ or skills."
+        )
+    return None
+
+
+def _line_count_from_lines(lines: list[str]) -> int:
+    return len(lines)
+
+
+def _long_functions_from_lines(lines: list[str], limit: int = 50) -> list[str]:
+    """Return a list of `  Line N: <name> (<len> lines)` for functions
+    longer than `limit`. Mirrors the .sh's awk block."""
+    findings: list[str] = []
+    func_start = 0
+    func_name = ""
+    lineno = 0
+    for line in lines:
+        lineno += 1
+        if _FUNC_START_RE.search(line):
+            if func_start > 0 and lineno - func_start > limit:
+                findings.append(
+                    f"  Line {func_start}: {func_name} ({lineno - func_start} lines)"
+                )
+            func_start = lineno
+            name = line.lstrip()
+            # Strip anything after `(` or `{` — matches bash sub()s.
+            name = re.sub(r"[({].*", "", name)
+            func_name = name
+    if func_start > 0 and lineno - func_start > limit:
+        findings.append(
+            f"  Line {func_start}: {func_name} ({lineno - func_start} lines)"
+        )
+    return findings
+
+
+def _check_source_file(path: Path) -> list[str]:
+    """Return warning lines for source-file length + long functions.
+
+    Reads the file's content exactly once and reuses the resulting lines for
+    both checks (line-count, long-function scan)."""
+    warnings: list[str] = []
+    if path.suffix.lower() not in _SOURCE_EXTS:
+        return warnings
+    try:
+        lines = path.read_text(errors="replace").splitlines()
+    except OSError:
+        return warnings
+    lc = _line_count_from_lines(lines)
+    if lc > FILE_LINE_LIMIT:
+        warnings.append(
+            f"Token: File is {lc} lines (limit: {FILE_LINE_LIMIT}). Large files "
+            "require more context tokens — consider splitting."
+        )
+    long_funcs = _long_functions_from_lines(lines)
+    if long_funcs:
+        warnings.append(
+            "Token: Long functions detected (limit: 50 lines). "
+            "Split into smaller units:\n" + "\n".join(long_funcs)
+        )
+    return warnings
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.buffer.read()
+    except (OSError, ValueError):
+        raw = b""
+    payload = _read_json(raw)
+    file_path_str = _extract_path(payload)
+    if not file_path_str:
+        return 0
+    file_path = Path(file_path_str)
+    if not file_path.is_file():
+        return 0
+
+    warnings: list[str] = []
+    claude_md_warning = _check_claude_md(file_path)
+    if claude_md_warning:
+        warnings.append(claude_md_warning)
+    warnings.extend(_check_source_file(file_path))
+
+    if warnings:
+        # The .sh formats WARNINGS by concatenating each warning with a
+        # leading newline, then echoing $WARNINGS. That produces a leading
+        # newline before the first warning. Reproduce for byte-parity.
+        print()
+        print("\n".join(warnings))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/verify_guard.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Python port of hooks/verify-guard.sh (#608 / #572 Phase 3), escalated to a
+hard stop for stuck loops (#708).
+
+PreToolUse Bash hook — detects repeated identical verify invocations
+within a session. Once the same normalized command has run THRESHOLD
+consecutive times with **zero** intervening Edit/Write/NotebookEdit calls
+(tracked via verify_guard_edit_marker.py, its PreToolUse sibling on the
+Write|Edit|NotebookEdit matcher), it BLOCKS the command instead of merely
+warning — that combination is a genuinely stuck loop, not the ordinary
+RED/GREEN/REFACTOR pattern of re-running the same command after each real
+edit. Any edit observed since the previous verify run resets the counter,
+same as a different command does, so legitimate TDD repeats are never
+blocked.
+
+Contract (docs/python-hook-contract.md):
+    Input : PreToolUse JSON on stdin (hook_event_name, session_id,
+            tool_input.command, cwd)
+    Output: Warning on stdout below threshold; `[BLOCK]`-prefixed message
+            at/above threshold (unless DEV_TEAM_VERIFY_THRESHOLD=0)
+    Exit  : 0 below threshold, or when DEV_TEAM_VERIFY_THRESHOLD=0;
+            2 (block) at/above threshold with threshold > 0
+    Env   : DEV_TEAM_VERIFY_THRESHOLD (default 3), TMPDIR
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from boundary_events import emit_boundary_event as _emit_boundary_event
+from verify_guard_state import (
+    cksum,
+    read_state,
+    state_file,
+    state_key,
+    write_state,
+)
+
+
+def emit_boundary_event(*args, **kwargs) -> None:
+    """Local safety net (#859): even a misbehaving helper must never affect
+    this hook's exit code, stdout, or stderr."""
+    try:
+        _emit_boundary_event(*args, **kwargs)
+    except Exception:  # noqa: BLE001, S110 - fail-open by design
+        pass
+
+
+# Verify-class command detector — mirrors
+# `session_log.classify.VERIFY_RE`, which
+# plugins/dev-team/scripts/session_report.py's `--profile maintainer`
+# aliases.
+_VERIFY_RE = re.compile(
+    r"\b("
+    r"npm (run )?(test|lint|build)"
+    r"|pytest|bats|eslint|tsc|go test|cargo (test|build)|mvn"
+    r"|gradle|make( |$)|vitest|jest|ruff|mypy|shellcheck"
+    r")\b"
+)
+
+
+def _read_payload() -> dict:
+    try:
+        raw = sys.stdin.buffer.read()
+    except (OSError, ValueError):
+        return {}
+    try:
+        return json.loads(raw or b"{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def main() -> int:
+    payload = _read_payload()
+    cmd = str(payload.get("tool_input", {}).get("command") or "")
+    if not cmd:
+        return 0
+
+    # Only fire on verify-class commands.
+    if not _VERIFY_RE.search(cmd):
+        return 0
+
+    session_id = str(payload.get("session_id") or "")
+    cwd = str(payload.get("cwd") or "")
+    key = state_key(session_id, cwd)
+    path = state_file(key)
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return 0
+
+    # Normalize the command (collapse whitespace) for comparison.
+    norm_cmd = " ".join(cmd.split())
+    norm_hash = cksum(norm_cmd)
+
+    try:
+        threshold = int(os.environ.get("DEV_TEAM_VERIFY_THRESHOLD", "3"))
+    except ValueError:
+        threshold = 3
+
+    prev = read_state(path)
+    prev_hash = str(prev.get("hash") or "")
+    prev_count = int(prev.get("count") or 0)
+    edited_since_prev = bool(prev.get("edited"))
+
+    # Consecutive count increments only when the exact same normalized
+    # command runs again with NO edit in between — an edit resets the
+    # counter exactly like a different command does (existing behavior).
+    if norm_hash == prev_hash and not edited_since_prev:
+        count = prev_count + 1
+    else:
+        count = 1
+
+    # Persist state. This run has "consumed" any pending edit signal, so
+    # the flag is cleared here; verify_guard_edit_marker.py sets it again
+    # the next time an Edit/Write/NotebookEdit call is observed.
+    write_state(path, {"hash": norm_hash, "count": count, "edited": False})
+
+    # Match the historical `[ "$count" -ge "$THRESHOLD" ]` semantics —
+    # threshold=0 always fires on the first run too. The "set to 0 to
+    # suppress" message is technically misleading for the advisory (byte
+    # parity with the original .sh is the contract there), but threshold=0
+    # DOES fully suppress the new block below: escalating a hook whose own
+    # docs claim to be a full opt-out would violate that opt-out.
+    if count < threshold:
+        return 0
+
+    if threshold <= 0:
+        print(
+            f"verify-guard: This verify command has run {count} consecutive "
+            "times without a code change."
+        )
+        print(
+            "  If the tests are still failing, change the code rather than "
+            "re-running the same command."
+        )
+        print("  To suppress this warning, set DEV_TEAM_VERIFY_THRESHOLD=0.")
+        emit_boundary_event(
+            cwd, "verify_guard", "Bash", "warn", "verify-repeat-threshold", session_id
+        )
+        return 0
+
+    print(
+        f"[BLOCK] verify-guard: This verify command has run {count} "
+        "consecutive times without a code change."
+    )
+    print()
+    print(
+        "  No Edit/Write/NotebookEdit happened between these runs — that's a "
+        "stuck loop, not TDD's RED/GREEN/REFACTOR pattern (which always has "
+        "a real edit between repeats of the same command)."
+    )
+    print(
+        "  Run a systematic-debugging pass (see the systematic-debugging "
+        "skill) to find the root cause, then make the code change the "
+        "tests are waiting for before re-running this command."
+    )
+    print(
+        "  If the root cause is understood but unresolvable in scope, stop "
+        "and escalate per /build's Escalation step instead of retrying "
+        "again."
+    )
+    print("  To suppress this block, set DEV_TEAM_VERIFY_THRESHOLD=0.")
+    emit_boundary_event(
+        cwd, "verify_guard", "Bash", "block", "verify-repeat-threshold", session_id
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/verify_guard_edit_marker.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""verify_guard_edit_marker.py — PreToolUse hook (#708), sibling of
+verify_guard.py.
+
+Matcher: `Write|Edit|NotebookEdit`. Stamps verify_guard.py's per-session
+state file to record that a real code edit happened since the last
+verify-class Bash command. verify_guard.py reads this flag to tell a
+genuinely stuck loop (same verify command, zero intervening edits) apart
+from ordinary TDD re-verification (RED, GREEN, REFACTOR each legitimately
+re-run the same command, but each preceded by an edit) before escalating
+to a hard block.
+
+This hook itself never warns or blocks — it only records a fact for its
+sibling to read.
+
+Contract (docs/python-hook-contract.md):
+    Input : PreToolUse JSON on stdin (session_id, cwd)
+    Output: none
+    Exit  : always 0 (silent-pass)
+    Env   : TMPDIR
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from verify_guard_state import (
+    read_state,
+    state_file,
+    state_key,
+    write_state,
+)
+
+
+def _read_payload() -> dict:
+    try:
+        raw = sys.stdin.buffer.read()
+    except (OSError, ValueError):
+        return {}
+    try:
+        return json.loads(raw or b"{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def main() -> int:
+    payload = _read_payload()
+    session_id = str(payload.get("session_id") or "")
+    cwd = str(payload.get("cwd") or "")
+    key = state_key(session_id, cwd)
+    path = state_file(key)
+
+    data = read_state(path)
+    data["edited"] = True
+    # Preserve existing hash/count if present; a session with no verify
+    # run yet simply gets an "edited" marker no verify_guard.py call will
+    # ever compare against (a differing/absent hash already resets its
+    # counter), so no need to seed hash/count here.
+    write_state(path, data)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/version_check.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Python port of hooks/version-check.sh (#609 / #572 Phase 3).
+
+Claude Code PostToolUse hook — checks once per day whether the plugin repo
+has upstream updates. If updates are available, prints a notice suggesting
+`/upgrade`.
+
+Contract (docs/python-hook-contract.md):
+    Input : PostToolUse JSON on stdin (ignored)
+    Output: Update notice on stdout, or nothing if up-to-date
+    Cache : /tmp/adt-version-check-<date> — daily cache prevents repeated
+            checks; replays cached message if any
+    Exit  : Always 0 (advisory, never blocks)
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def _cache_dir() -> Path:
+    """Mirror the .sh's hard-coded `/tmp` for the daily cache path.
+
+    The bash script writes to `/tmp/adt-version-check-<date>` unconditionally
+    — no `${TMPDIR:-/tmp}` fallback. Windows Git Bash treats `/tmp` as the
+    MSYS-mounted temp directory, so the same literal is portable across the
+    three platforms this port targets. Byte-parity with the .sh requires
+    the same literal here.
+
+    ``DEV_TEAM_VERSION_CHECK_CACHE_DIR``, when set, overrides this — a
+    test-only escape hatch (#1574) so pytest can give each worker/run its
+    own cache path instead of racing on the one real, shared `/tmp` file.
+    Production callers never set it, so real behavior is unchanged.
+    """
+    override = os.environ.get("DEV_TEAM_VERSION_CHECK_CACHE_DIR")
+    return Path(override) if override else Path("/tmp")
+
+
+def _today_cache_file() -> Path:
+    # Local wall-clock date for a daily cache filename, not a comparison —
+    # mirrors the ported .sh's `date +%Y-%m-%d`, which also uses local time.
+    today = datetime.now().strftime("%Y-%m-%d")  # noqa: DTZ005
+    return _cache_dir() / f"adt-version-check-{today}"
+
+
+def _plugin_dir() -> Path:
+    """The plugin's repo root — one level up from hooks/."""
+    return Path(__file__).resolve().parent.parent
+
+
+def _git(args, cwd: Path, timeout: float = 5.0):
+    """Run git with the given args and cwd, capturing output. Returns the
+    CompletedProcess; caller inspects returncode. Any FileNotFoundError
+    (git absent) or timeout returns None."""
+    try:
+        return subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+
+
+def _is_git_repo(plugin_dir: Path) -> bool:
+    r = _git(["rev-parse", "--is-inside-work-tree"], plugin_dir, timeout=2.0)
+    return r is not None and r.returncode == 0
+
+
+def _default_branch(plugin_dir: Path) -> str:
+    r = _git(["symbolic-ref", "refs/remotes/origin/HEAD"], plugin_dir, timeout=2.0)
+    if r is None or r.returncode != 0:
+        return "main"
+    ref = r.stdout.strip()
+    # Strip the `refs/remotes/origin/` prefix if present.
+    prefix = "refs/remotes/origin/"
+    if ref.startswith(prefix):
+        return ref[len(prefix) :]
+    return ref or "main"
+
+
+def _fetch(plugin_dir: Path, timeout: float = 5.0) -> bool:
+    """Fetch quietly with a short timeout. Returns True on success."""
+    r = _git(["fetch", "origin", "--quiet"], plugin_dir, timeout=timeout)
+    return r is not None and r.returncode == 0
+
+
+def _commits_behind(plugin_dir: Path, branch: str) -> int:
+    r = _git(
+        ["rev-list", "--count", f"HEAD..origin/{branch}"],
+        plugin_dir,
+        timeout=2.0,
+    )
+    if r is None or r.returncode != 0:
+        return 0
+    try:
+        return int(r.stdout.strip())
+    except ValueError:
+        return 0
+
+
+def main() -> int:
+    # Consume stdin (required by the hook protocol).
+    try:
+        sys.stdin.read()
+    except (OSError, ValueError):
+        pass
+
+    cache_file = _today_cache_file()
+    if cache_file.is_file():
+        # Already checked today — replay cached message if any.
+        try:
+            cached = cache_file.read_text()
+        except OSError:
+            cached = ""
+        # Bash: `CACHED=$(cat "$CACHE_FILE")` strips trailing newlines the
+        # same way command substitution does. Then `[ -n "$CACHED" ] &&
+        # echo "$CACHED"` prints only when non-empty and re-adds one LF.
+        # Match both: rstrip newlines, print with a single trailing LF iff
+        # anything remains.
+        stripped = cached.rstrip("\n")
+        if stripped:
+            print(stripped)
+        return 0
+
+    plugin_dir = _plugin_dir()
+
+    if not _is_git_repo(plugin_dir):
+        # Not a git repo (vendored copy) — skip silently but cache.
+        try:
+            cache_file.touch()
+        except OSError:
+            pass
+        return 0
+
+    if not _fetch(plugin_dir):
+        # Network too slow / fetch failed — skip silently, don't cache so it
+        # retries later.
+        return 0
+
+    branch = _default_branch(plugin_dir)
+    behind = _commits_behind(plugin_dir, branch)
+
+    if behind > 0:
+        msg = (
+            f"📦 dev-team@bfinster: {behind} update(s) available. "
+            "Run /upgrade to update."
+        )
+        try:
+            cache_file.write_text(msg + "\n")
+        except OSError:
+            pass
+        print(msg)
+    else:
+        # Up to date — cache empty result so subsequent same-day fires skip.
+        try:
+            cache_file.touch()
+        except OSError:
+            pass
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())