pi-dev-team 0.2.0

package/hooks/session_learning_trigger.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""session_learning_trigger.py — SessionEnd hook (Python port of session-learning-trigger.sh).
+
+Counts sessions and dispatches background session-analysis at threshold.
+
+CONSENT : off by default. Set `DEV_TEAM_AUTO_REVIEW=on` to enable.
+THRESHOLD: `DEV_TEAM_AUTO_REVIEW_THRESHOLD` (default 5) sessions before dispatch.
+STATE    : counter persisted in `<cwd>/.claude/metrics/learning-loop-state.json`.
+
+Posture: fail-open. Every I/O error exits 0 without crashing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+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))
+
+import artifact_paths
+import telemetry_consent
+
+try:
+    from atomic_state import locked_state, race_window_delay
+except ImportError:  # pragma: no cover
+    import contextlib as _contextlib
+
+    @_contextlib.contextmanager
+    def locked_state(_path: Path):  # type: ignore[misc]
+        yield
+
+    def race_window_delay(_env_var: str) -> None:  # type: ignore[misc]
+        return None
+
+
+def _load_counter(state_file: Path) -> int:
+    """Return the persisted counter, recovering to 0 on any error."""
+    if not state_file.is_file():
+        return 0
+    try:
+        data = json.loads(state_file.read_text())
+    except (OSError, ValueError):
+        return 0
+    counter = data.get("counter")
+    if isinstance(counter, int) and counter >= 0:
+        return counter
+    if isinstance(counter, str) and counter.isdigit():
+        return int(counter)
+    return 0
+
+
+def _write_state(state_file: Path, counter: int) -> None:
+    """Atomically write `{"counter": N}` to `state_file`. Fail-open on any error."""
+    try:
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            prefix=".learning-loop-state-",
+            suffix=".json",
+            dir=str(state_file.parent),
+        )
+    except OSError:
+        return
+    try:
+        with os.fdopen(fd, "w") as handle:
+            # `jq -nc` in bash writes with a trailing newline — match it so the
+            # parity harness's side-effect tree hash lines up.
+            handle.write(json.dumps({"counter": counter}, separators=(",", ":")) + "\n")
+        os.replace(tmp_path, state_file)
+    except OSError:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+
+
+def _resolve_session_report(hook_dir: Path) -> Path:
+    """`plugins/dev-team/scripts/session_report.py`, resolved from a shipped
+    hook's install location.
+
+    Until #2047, this resolved to the repo-root `scripts/session_extract.py`
+    that only a monorepo dev checkout carries — deliberately never shipped
+    inside the plugin, so `_dispatch_background_analysis` had to treat a
+    missing target as the normal case for every downstream install (#1649
+    already fixed a dangling-path defect against that exact coupling, but
+    could only ever make the monorepo-checkout case work, never the shipped
+    one). `session_report.py --profile maintainer` (#2046) IS shipped, so
+    this now resolves to a file that genuinely exists on every install —
+    closing #1779 for this consumer specifically.
+
+    `hook_dir` is `plugins/dev-team/hooks`; `scripts/` is a sibling one
+    level up (`hooks` -> `dev-team` -> `scripts`), not three — the extra
+    `../..` this function needed while targeting the repo root is gone now
+    that the target lives inside the same plugin tree as the hook itself.
+    """
+    return (hook_dir / ".." / "scripts" / "session_report.py").resolve()
+
+
+def _dispatch_background_analysis(
+    cwd: Path, session_id: str | None, hook_dir: Path
+) -> None:
+    """Fire-and-forget background analysis run.
+
+    Skips entirely, rather than composing a shell command guaranteed to fail,
+    when `session_report.py` isn't present — a defensive check kept for a
+    broken/partial install, since a normal one (every downstream install,
+    per #2047) now ships it. When it IS present but the dispatch itself
+    fails, the failure is logged to `metrics_dir/session-learning-errors.log`
+    rather than swallowed by a bare `|| true`, so a future regression here
+    is visible instead of permanently silent (#1649).
+    """
+    session_report = _resolve_session_report(hook_dir)
+    if not session_report.is_file():
+        return
+    pending = artifact_paths.resolve_file("metrics", "pending-review.jsonl", cwd)
+
+    prompt = (
+        "Run the session-analysis agent and output each finding as a JSONL "
+        "entry to stdout with fields: queued_at (ISO-8601 UTC now), source "
+        "(session-learning-trigger), session_id, findings (array of objects "
+        "with lever, evidence, target_artifact, proposed_change, route)"
+    )
+
+    session_id_args = []
+    if session_id:
+        # --session-id shares the parent's prompt-cache prefix (~26% cost cut)
+        session_id_args = ["--session-id", session_id]
+
+    metrics_dir = artifact_paths.metrics_dir(cwd)
+    try:
+        metrics_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+
+    # Compose a shell script that runs asynchronously — same fire-and-forget
+    # semantics as bash's `( ... ) &`.
+    #
+    # session_report.py's stderr is appended to a log file, not discarded
+    # (#1649): the `|| true` still keeps this line from aborting the rest of
+    # the chain on failure (though it never would — these are `;`-joined,
+    # not `&&`), but a failure here previously left zero evidence anywhere.
+    # `2>>` (append) rather than `2>` so repeated dispatches accumulate a
+    # history instead of each one erasing the last.
+    extract_log = metrics_dir / "session-learning-errors.log"
+    shell_body = (
+        f"python3 {shell_quote(str(session_report))} --profile maintainer --since last "
+        f">/dev/null 2>>{shell_quote(str(extract_log))} || true; "
+        # Template must END in the Xs (no `.jsonl` suffix): BSD mktemp
+        # substitutes only a trailing run, so `.pending-XXXXXX.jsonl` yields
+        # that name verbatim and the SECOND dispatch dies with "File exists" —
+        # which `2>/dev/null || exit 0` below swallows, silently disabling
+        # session-learning extraction on macOS from then on (issue #1993).
+        f"tmp_out=$(mktemp {shell_quote(str(metrics_dir / '.pending-XXXXXX'))} "
+        "2>/dev/null) || exit 0; "
+        f"if claude {' '.join(shell_quote(a) for a in session_id_args)} "
+        f"--dangerously-skip-permissions --print {shell_quote(prompt)} "
+        '>"$tmp_out" 2>/dev/null; then '
+        f'cat "$tmp_out" >> {shell_quote(str(pending))} 2>/dev/null || true; fi; '
+        'rm -f "$tmp_out"'
+    )
+
+    try:
+        subprocess.Popen(
+            ["sh", "-c", shell_body],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except (FileNotFoundError, OSError):
+        pass
+
+
+def shell_quote(value: str) -> str:
+    """Portable-ish single-quote quoting for POSIX sh."""
+    return "'" + value.replace("'", "'\"'\"'") + "'"
+
+
+def main() -> int:
+    if os.environ.get("DEV_TEAM_AUTO_REVIEW", "") != "on":
+        return 0
+    if not telemetry_consent.is_enabled():
+        return 0
+
+    # bash requires jq; Python does not, but keep parity on the "no jq" exit
+    # for hosts that intentionally strip it (fail-open discipline).
+    if shutil.which("jq") is None:
+        return 0
+
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw)
+    except (TypeError, ValueError):
+        return 0
+
+    cwd_str = payload.get("cwd") if isinstance(payload, dict) else None
+    cwd = Path(cwd_str) if isinstance(cwd_str, str) and cwd_str else Path.cwd()
+    if not cwd.is_dir():
+        cwd = Path.cwd()
+
+    session_id = payload.get("session_id") if isinstance(payload, dict) else None
+    if not isinstance(session_id, str) or not session_id:
+        session_id = None
+
+    threshold_env = os.environ.get("DEV_TEAM_AUTO_REVIEW_THRESHOLD", "5")
+    try:
+        threshold = int(threshold_env)
+    except ValueError:
+        threshold = 5
+
+    state_file = artifact_paths.resolve_file("metrics", "learning-loop-state.json", cwd)
+    hook_dir = Path(__file__).resolve().parent
+
+    # Serialize the load-increment-write so two SessionEnd hooks ending in the
+    # same cwd near-simultaneously each advance the counter exactly once
+    # instead of racing and losing an increment (#1501). The write itself is
+    # already atomic (tempfile + os.replace in _write_state); the lock closes
+    # the remaining read-modify-write gap. Fail-open: unlockable → runs
+    # unlocked. The dispatch stays outside the lock — it is fire-and-forget and
+    # must not hold the lock across a subprocess spawn.
+    dispatch = False
+    with locked_state(state_file):
+        counter = _load_counter(state_file) + 1
+        race_window_delay("DEV_TEAM_SESSION_LEARNING_TEST_DELAY_MS")
+        if counter >= threshold:
+            _write_state(state_file, 0)
+            dispatch = True
+        else:
+            _write_state(state_file, counter)
+
+    if dispatch:
+        _dispatch_background_analysis(cwd, session_id, hook_dir)
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/hooks/skills_index.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""skills_index.py — Claude Code PostToolUse hook (Python port of skills-index.sh).
+
+When an Edit or Write touches `plugins/dev-team/skills/<name>/SKILL.md`,
+regenerate `plugins/dev-team/docs/skills.md` by shelling out to the
+skills-index builder. The catalog is derived from each SKILL.md's `name` /
+`description` frontmatter so editing a skill keeps the catalog current with
+no manual step — a CI freshness gate (`--check`) is the strict net behind it.
+
+Sibling of `knowledge_index.py` (rebuilds `knowledge/index.json`); kept
+separate so each index has its own trigger, builder, and test seam.
+
+Posture: fail-open. Any internal error (missing builder, malformed stdin,
+builder non-zero exit) → exit 0 with a single `[skills-index]`-tagged stderr
+line. The hook MUST never block an Edit.
+
+Feedback: `[skills-index] rebuilt` on success, `[skills-index] rebuild
+failed: <reason>` on failure. Silent when the touched file is not a SKILL.md.
+
+Input : JSON on stdin (PostToolUse contract: `tool_name`,
+        `tool_input.file_path`).
+Output: stderr feedback when a SKILL.md is touched; otherwise silent. Exit 0.
+
+Env (TEST-ONLY injection seams):
+  SKILLS_INDEX_BUILDER — override the builder path. Production callers MUST
+                         NOT set this; it is resolved from the hook's own
+                         location.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+_SKILL_PATH_RE = re.compile(r"/?plugins/dev-team/skills/[^/]+/SKILL\.md$")
+
+
+def _default_builder() -> Path:
+    hook_dir = Path(__file__).resolve().parent
+    return hook_dir / "lib" / "build_skills_index.py"
+
+
+def _resolve_builder() -> Path:
+    override = os.environ.get("SKILLS_INDEX_BUILDER")
+    return Path(override) if override else _default_builder()
+
+
+def _touches_skill_definition(file_path: str) -> bool:
+    return bool(file_path) and bool(_SKILL_PATH_RE.search(file_path))
+
+
+def _extract_fields(raw: str):
+    try:
+        payload = json.loads(raw)
+    except (TypeError, ValueError):
+        return None, None
+    if not isinstance(payload, dict):
+        return None, None
+    tool_name = payload.get("tool_name") or ""
+    tool_input = payload.get("tool_input") or {}
+    file_path = tool_input.get("file_path") or ""
+    return (
+        tool_name if isinstance(tool_name, str) else "",
+        file_path if isinstance(file_path, str) else "",
+    )
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    tool_name, file_path = _extract_fields(raw)
+    if tool_name is None:
+        return 0  # malformed stdin — silent per fail-open
+
+    if tool_name not in {"Edit", "Write"}:
+        return 0
+
+    if not _touches_skill_definition(file_path):
+        return 0
+
+    builder = _resolve_builder()
+
+    with tempfile.NamedTemporaryFile("w+", delete=False) as stderr_capture:
+        stderr_path = stderr_capture.name
+    try:
+        try:
+            with open(stderr_path, "w") as stderr_sink:
+                argv = (
+                    [sys.executable, str(builder)]
+                    if str(builder).endswith(".py")
+                    else ["bash", str(builder)]
+                )
+                completed = subprocess.run(
+                    argv,
+                    stdout=subprocess.DEVNULL,
+                    stderr=stderr_sink,
+                    check=False,
+                )
+        except (FileNotFoundError, OSError) as exc:
+            print(f"[skills-index] rebuild failed: {exc}", file=sys.stderr)
+            return 0
+
+        if completed.returncode == 0:
+            print("[skills-index] rebuilt", file=sys.stderr)
+        else:
+            try:
+                with open(stderr_path) as fh:
+                    first_line = fh.readline().rstrip("\n") or "unknown"
+            except OSError:
+                first_line = "unknown"
+            print(f"[skills-index] rebuild failed: {first_line}", file=sys.stderr)
+    finally:
+        try:
+            os.unlink(stderr_path)
+        except OSError:
+            pass
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())