pi-dev-team 0.2.0

package/hooks/refactor_test_bash_guard.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""refactor_test_bash_guard.py — PreToolUse hook (Bash), issue #906.
+
+The preventive, Bash-aware half of the tests-frozen-during-refactor
+invariant (#813). `refactor_test_freeze_guard.py` blocks Write/Edit at a
+test file during a recorded REFACTOR phase, but Bash-driven edits (`sed -i`,
+`tee`, shell redirection, `mv`/`cp` onto a target, `python -c` with an
+`open(..., "w")`) bypass that guard entirely and were previously only
+caught reactively, after the fact, by `refactor_test_revert_guard.py`
+(PostToolUse) — which reverts/removes the damage once it has already
+landed on disk.
+
+This hook recognizes a conservative library of common file-modifying Bash
+shapes (`hooks/refactor-bash-write-patterns.json`), extracts the apparent
+write target, and — only when a recorded REFACTOR phase is active AND the
+target resolves to a file in the step's `test_files_staged` (or would newly
+create a file `test_file_classify.is_test_file()` classifies as a test) —
+blocks with exit 2 before the command ever runs.
+
+Ambiguous/unparseable commands (no pattern matches, or the matched target
+cannot be confidently resolved) are NEVER blocked: the false-positive budget
+favors letting the command through and relying on
+`refactor_test_revert_guard.py` as the safety net (defense-in-depth, not a
+replacement — see the issue's Non-goals). This is not a general-purpose
+shell parser.
+
+Fails OPEN on any internal error, with one audit line in
+`.claude/metrics/refactor-freeze.jsonl` (hook="bash-freeze") — a broken
+guard must never block work.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _SCRIPT_DIR / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+from boundary_events import emit_boundary_event as _emit_boundary_event
+from refactor_test_freeze_guard import audit
+from stdin_json import read_stdin_json
+from test_file_classify import is_test_file, read_build_phase
+
+
+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
+
+
+_PATTERNS_FILE = _SCRIPT_DIR / "refactor-bash-write-patterns.json"
+
+RECOVERY = (
+    "tests are frozen during REFACTOR; return to the TEST phase, make the "
+    "change there, re-verify green, then re-enter REFACTOR"
+)
+
+# Inline fallback — kept in the same order as the shipped JSON so behavior
+# is byte-identical when the config file is missing or malformed.
+_DEFAULT_PATTERNS: list[tuple[str, str]] = [
+    (
+        "sed-i",
+        r"\bsed\s+-i(?:\.\S+)?\s+(?:-e\s+)?(?:'[^']*'|\"[^\"]*\")\s+(?P<target>[^\s;&|]+)",
+    ),
+    (
+        "perl-i",
+        r"\bperl\s+-i(?:\.\S+)?\s+(?:-[a-zA-Z]+\s+)*(?:'[^']*'|\"[^\"]*\")\s+(?P<target>[^\s;&|]+)",
+    ),
+    ("tee", r"\btee\s+(?:-a\s+)?(?P<target>[^\s;&|]+)"),
+    ("redirect", r"(?<![\w&])>{1,2}(?!\S*&)\s*(?P<target>[^\s;&|>]+)"),
+    (
+        "mv-cp",
+        r"\b(?:mv|cp)\s+(?:-\S+\s+)*(?P<src>[^\s;&|]+)\s+(?P<target>[^\s;&|]+)\s*(?:[;&|]|$)",
+    ),
+    (
+        "python-open-write",
+        r"open\(\s*['\"](?P<target>[^'\"]+)['\"]\s*,\s*['\"](?:w|a|wb|ab|w\+|a\+)['\"]",
+    ),
+]
+
+
+def _load_patterns() -> list[tuple[str, str]]:
+    """Load (id, regex) pairs from the config file, falling back to inline
+    defaults on any error — attempt-and-degrade, matches destructive_guard.py."""
+    try:
+        data = json.loads(_PATTERNS_FILE.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return list(_DEFAULT_PATTERNS)
+    if not isinstance(data, dict):
+        return list(_DEFAULT_PATTERNS)
+    raw = data.get("patterns")
+    if not isinstance(raw, list):
+        return list(_DEFAULT_PATTERNS)
+    pairs: list[tuple[str, str]] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+        rule_id = entry.get("id")
+        regex = entry.get("regex")
+        if isinstance(rule_id, str) and rule_id and isinstance(regex, str) and regex:
+            pairs.append((rule_id, regex))
+    return pairs if pairs else list(_DEFAULT_PATTERNS)
+
+
+def _extract_all_targets(
+    command: str, patterns: list[tuple[str, str]]
+) -> list[tuple[str, str]]:
+    """Return (rule_id, raw_target) for every occurrence of every pattern
+    that matches the command, evaluated independently rather than
+    short-circuited at the first hit (#914).
+
+    A compound command (`;`/`&&`/`|`-joined) can carry a harmless match for
+    an earlier-listed pattern (e.g. a `redirect` onto a scratch file) while,
+    elsewhere in the same string, a later-listed pattern (e.g. `mv-cp`)
+    matches a genuinely dangerous target — stopping at the first *pattern*
+    match let the earlier, unrelated hit mask the real one. The same masking
+    can happen within a single rule too (e.g. two `mv` segments, only the
+    second targeting a test file), so every occurrence of a matching pattern
+    is collected via `re.finditer`, not just its first occurrence via
+    `re.search`. Never raises."""
+    matches: list[tuple[str, str]] = []
+    for rule_id, regex in patterns:
+        try:
+            found = list(re.finditer(regex, command))
+        except re.error:
+            continue
+        for match in found:
+            target = match.groupdict().get("target")
+            if target:
+                matches.append((rule_id, target))
+    return matches
+
+
+def _normalize_target(target: str) -> str:
+    """Strip a matching pair of quotes and a leading './' — best-effort only."""
+    stripped = target.strip()
+    if len(stripped) >= 2 and stripped[0] == stripped[-1] and stripped[0] in ("'", '"'):
+        stripped = stripped[1:-1]
+    stripped = stripped.removeprefix("./")
+    return stripped
+
+
+def _resolve_relative(target: str, project_dir: Path) -> str:
+    """Best-effort project-relative posix path for `target`. Falls back to
+    the normalized target string when it can't be resolved under
+    `project_dir` (e.g. an absolute path outside the project)."""
+    normalized = _normalize_target(target)
+    candidate = Path(normalized)
+    if candidate.is_absolute():
+        try:
+            return candidate.resolve().relative_to(project_dir.resolve()).as_posix()
+        except (OSError, ValueError):
+            return normalized
+    return normalized
+
+
+def _matches_staged_or_new_test(rel_target: str, staged: list[str]) -> bool:
+    if rel_target in staged:
+        return True
+    return is_test_file(rel_target)
+
+
+def evaluate(
+    command: str, project_dir: Path, now: float | None = None
+) -> tuple[int, list[str], str | None]:
+    """Return (exit_code, stdout_lines, matched_rule_id).
+
+    `matched_rule_id` is the pattern id that triggered a block, or None
+    (including for every non-blocking outcome).
+    """
+    if not command:
+        return 0, [], None
+    state, error = read_build_phase(project_dir, now=now)
+    if error is not None:
+        audit(project_dir, "bash-freeze", "fail-open", reason=error)
+        return 0, [], None
+    if state is None or state.get("phase") != "refactor":
+        return 0, [], None
+
+    staged = state.get("test_files_staged", [])
+    for rule_id, raw_target in _extract_all_targets(command, _load_patterns()):
+        rel_target = _resolve_relative(raw_target, project_dir)
+        if not _matches_staged_or_new_test(rel_target, staged):
+            continue
+
+        step = state.get("step") if isinstance(state.get("step"), str) else None
+        audit(project_dir, "bash-freeze", "block", file=rel_target, step=step)
+        step_label = f" (step {step})" if step else ""
+        return (
+            2,
+            [
+                f"[BLOCK] Tests are frozen during REFACTOR{step_label}.",
+                "A refactor step must never change a test — refactoring is",
+                "behavior-preserving by definition (tests-frozen invariant, Rec 4,",
+                "docs/experiments/RECOMMENDATIONS.md).",
+                f"File: {rel_target}",
+                "Recovery: leave REFACTOR and return to the TEST phase, make the",
+                "test change there, re-verify the full suite green (pasted",
+                "evidence), then re-enter REFACTOR.",
+            ],
+            rule_id,
+        )
+    return 0, [], None
+
+
+def main() -> int:
+    project_dir = artifact_paths.project_root()
+    exit_code, lines = 0, []
+    try:
+        payload = read_stdin_json()
+        tool_input = payload.get("tool_input") if isinstance(payload, dict) else None
+        command = ""
+        if isinstance(tool_input, dict):
+            raw = tool_input.get("command")
+            if isinstance(raw, str):
+                command = raw
+        exit_code, lines, rule_id = evaluate(command, project_dir)
+        if exit_code == 2:
+            session_id = (
+                payload.get("session_id") if isinstance(payload, dict) else None
+            )
+            emit_boundary_event(
+                project_dir,
+                "refactor_test_bash_guard",
+                "Bash",
+                "block",
+                rule_id or "bash-write",
+                session_id,
+            )
+    except Exception as exc:  # noqa: BLE001 - fail open — a broken guard never blocks work
+        audit(
+            project_dir,
+            "bash-freeze",
+            "fail-open",
+            reason=f"internal error: {exc}",
+        )
+        return 0
+    for line in lines:
+        print(line)
+    return exit_code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/hooks/refactor_test_freeze_guard.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""refactor_test_freeze_guard.py — PreToolUse hook (Write|Edit), issue #813.
+
+Enforces the tests-frozen-during-refactor invariant mechanically: while
+`/build` has recorded that the current step is in its REFACTOR phase
+(`.claude/memory/build-phase.json`), any Write/Edit targeting a test file is denied
+(exit 2, `[BLOCK]` per docs/python-hook-contract.md). A refactor step must
+never change a test — the invariant held at zero violations across the
+experiment campaigns (Rec 4, docs/experiments/RECOMMENDATIONS.md).
+
+Fails OPEN on any internal error, with one audit line in
+`.claude/metrics/refactor-freeze.jsonl` — a broken guard must never block
+work.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent / "lib"
+sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+from atomic_state import append_line_locked
+from boundary_events import emit_boundary_event as _emit_boundary_event
+from stdin_json import read_stdin_json
+from test_file_classify import is_test_file, read_build_phase
+
+
+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
+
+def _project_dir() -> Path:
+    """Resolve the project root via git, not the possibly-unset/stale
+    CLAUDE_PROJECT_DIR env var."""
+    return artifact_paths.project_root()
+
+
+def audit(
+    project_dir: Path,
+    hook: str,
+    event: str,
+    file: str | None = None,
+    step: str | None = None,
+    reason: str | None = None,
+) -> None:
+    """Append one JSONL audit line under .claude/metrics/refactor-freeze.jsonl.
+
+    Best-effort — a failure to resolve the path, create the directory, or
+    write the line is fail-open: log a diagnostic and never crash the guard.
+    """
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "hook": hook,
+        "event": event,
+        "file": file,
+        "step": step,
+        "reason": reason,
+    }
+    try:
+        path = artifact_paths.resolve_file("metrics", "refactor-freeze.jsonl", project_dir)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        append_line_locked(path, json.dumps(entry) + "\n", fail_open=False)
+    except OSError as exc:
+        sys.stderr.write(f"[refactor_test_freeze_guard] failed to write audit line: {exc}\n")
+
+
+def _extract_file_path(payload: dict | None) -> str:
+    if not isinstance(payload, dict):
+        return ""
+    tool_input = payload.get("tool_input") or {}
+    if not isinstance(tool_input, dict):
+        return ""
+    for key in ("file_path", "path"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return ""
+
+
+def evaluate(
+    file_path: str, project_dir: Path, now: float | None = None
+) -> tuple[int, list[str]]:
+    """Return (exit_code, stdout_lines) for one Write/Edit decision."""
+    if not file_path:
+        return 0, []
+    state, error = read_build_phase(project_dir, now=now)
+    if error is not None:
+        audit(project_dir, "freeze", "fail-open", file=file_path, reason=error)
+        return 0, []
+    if state is None or state.get("phase") != "refactor":
+        return 0, []
+    if not is_test_file(file_path):
+        return 0, []
+    step = state.get("step") if isinstance(state.get("step"), str) else None
+    audit(project_dir, "freeze", "block", file=file_path, step=step)
+    step_label = f" (step {step})" if step else ""
+    return 2, [
+        f"[BLOCK] Tests are frozen during REFACTOR{step_label}.",
+        "A refactor step must never change a test — refactoring is",
+        "behavior-preserving by definition (tests-frozen invariant, Rec 4,",
+        "docs/experiments/RECOMMENDATIONS.md).",
+        f"File: {file_path}",
+        "Recovery: leave REFACTOR and return to the TEST phase, make the test",
+        "change there, re-verify the full suite green (pasted evidence), then",
+        "re-enter REFACTOR.",
+    ]
+
+
+def main() -> int:
+    project_dir = _project_dir()
+    try:
+        payload = read_stdin_json()
+        file_path = _extract_file_path(payload)
+        exit_code, lines = evaluate(file_path, project_dir)
+        if exit_code == 2:
+            session_id = payload.get("session_id") if isinstance(payload, dict) else None
+            emit_boundary_event(
+                project_dir, "refactor_test_freeze_guard", "Write", "block",
+                "refactor-test-freeze", session_id,
+            )
+    except Exception as exc:  # noqa: BLE001  # fail open — a broken guard never blocks work
+        audit(project_dir, "freeze", "fail-open", reason=f"internal error: {exc}")
+        return 0
+    for line in lines:
+        print(line)
+    return exit_code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/hooks/refactor_test_revert_guard.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""refactor_test_revert_guard.py — PostToolUse hook (Bash), issue #813.
+
+The revert half of the tests-frozen-during-refactor enforcement: Bash-driven
+edits bypass the PreToolUse freeze guard, so after each Bash call during a
+recorded REFACTOR phase this hook restores any test file that drifted from
+the staged baseline `/build` captured at the TEST→REFACTOR transition
+(`git add` of the step's test files, recorded in `test_files_staged`).
+
+- Baseline carryover (working tree matches the index) is never reverted.
+- A test file dirtied after the baseline is restored via `git checkout --`.
+- A test file newly created during refactor (untracked, absent from the
+  baseline) is removed — no unreviewed test file is silently left in place.
+- Fails OPEN on unreadable/malformed state or git failure: never reverts on
+  fail-open, one audit line in `metrics/refactor-freeze.jsonl`.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent / "lib"
+sys.path.insert(0, str(_LIB_DIR))
+
+from boundary_events import emit_boundary_event as _emit_boundary_event
+from refactor_test_freeze_guard import audit
+from stdin_json import read_stdin_json
+from test_file_classify import is_test_file, read_build_phase
+
+
+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. Also degrades silently (no
+    error, no extra output) on a tree that predates #859/PR #887 and lacks
+    the boundary-events channel — attempt-and-degrade, same pattern #862
+    uses."""
+    try:
+        _emit_boundary_event(*args, **kwargs)
+    except Exception:  # noqa: BLE001, S110 - fail-open by design
+        pass
+
+
+RECOVERY = (
+    "tests are frozen during REFACTOR; return to the TEST phase, make the "
+    "change there, re-verify green, then re-enter REFACTOR"
+)
+
+
+def _git(project_dir: Path, args: list[str]) -> str | None:
+    """Run git in the project dir; stdout on success, None on any failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            cwd=str(project_dir),
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout
+
+
+def evaluate(
+    project_dir: Path,
+    now: float | None = None,
+    session_id: str | None = None,
+) -> tuple[int, list[str]]:
+    """Return (exit_code, stdout_lines). Always exits 0 — advisory only."""
+    state, error = read_build_phase(project_dir, now=now)
+    if error is not None:
+        audit(project_dir, "revert", "fail-open", reason=error)
+        return 0, []
+    if state is None or state.get("phase") != "refactor":
+        return 0, []
+    step = state.get("step") if isinstance(state.get("step"), str) else None
+    lines: list[str] = []
+
+    # Post-baseline drift on baseline files: the index IS the baseline.
+    baseline = state.get("test_files_staged", [])
+    if baseline:
+        diff_out = _git(project_dir, ["diff", "--name-only", "--"] + baseline)
+        if diff_out is None:
+            audit(
+                project_dir,
+                "revert",
+                "fail-open",
+                step=step,
+                reason="git diff against staged baseline failed",
+            )
+            return 0, lines
+        for dirty in [f for f in diff_out.splitlines() if f.strip()]:
+            restored = _git(project_dir, ["checkout", "--", dirty])
+            if restored is None:
+                audit(
+                    project_dir,
+                    "revert",
+                    "fail-open",
+                    file=dirty,
+                    step=step,
+                    reason="git checkout failed",
+                )
+                continue
+            audit(project_dir, "revert", "revert", file=dirty, step=step)
+            emit_boundary_event(
+                project_dir,
+                "refactor_test_revert_guard",
+                "Bash",
+                "revert",
+                "restore-baseline",
+                session_id,
+            )
+            lines.append(
+                f"ADVISORY: restored test file '{dirty}' to its TEST-phase baseline "
+                f"({RECOVERY})."
+            )
+
+    # Test files created during refactor: untracked and absent from baseline.
+    others_out = _git(project_dir, ["ls-files", "--others", "--exclude-standard"])
+    if others_out is None:
+        audit(
+            project_dir,
+            "revert",
+            "fail-open",
+            step=step,
+            reason="git ls-files --others failed",
+        )
+        return 0, lines
+    for rel in [f for f in others_out.splitlines() if f.strip()]:
+        candidate = project_dir / rel
+        if not is_test_file(str(candidate)):
+            continue
+        try:
+            candidate.unlink()
+        except OSError as exc:
+            audit(
+                project_dir,
+                "revert",
+                "fail-open",
+                file=rel,
+                step=step,
+                reason=f"could not remove: {exc}",
+            )
+            continue
+        audit(project_dir, "revert", "remove", file=rel, step=step)
+        emit_boundary_event(
+            project_dir,
+            "refactor_test_revert_guard",
+            "Bash",
+            "revert",
+            "remove-untracked-test",
+            session_id,
+        )
+        lines.append(
+            f"ADVISORY: removed test file '{rel}' created during REFACTOR "
+            f"({RECOVERY})."
+        )
+    return 0, lines
+
+
+def main() -> int:
+    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd())
+    # The guard inspects disk state, not the payload — but stdin must still
+    # be drained (so the hook runner never blocks on a full pipe) and the
+    # session_id, when present, is worth threading into the boundary-events
+    # emission for cross-stream joins with session-digest.jsonl.
+    payload = read_stdin_json()
+    session_id = payload.get("session_id") if isinstance(payload, dict) else None
+    try:
+        exit_code, lines = evaluate(project_dir, session_id=session_id)
+    except Exception as exc:  # noqa: BLE001 - fail open — never revert, never block
+        audit(project_dir, "revert", "fail-open", reason=f"internal error: {exc}")
+        return 0
+    for line in lines:
+        print(line)
+    return exit_code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())