pi-dev-team 0.2.0

package/scripts/set_autocompact_env.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Merge CLAUDE_AUTOCOMPACT_PCT_OVERRIDE into a project's `.claude/settings.json`.
+
+Used by `/dev-team:setup` (#2177). Merges exactly one key into the `env`
+block, preserving every other key; it never replaces the file wholesale.
+
+    set_autocompact_env.py [--project-dir DIR] [--autocompact-pct N]
+                           [--yes] [--no-autocompact]
+
+Value resolution (all `--yes` / prompt logic lives here, not in SKILL.md):
+
+  existing value | --autocompact-pct | result
+  -------------- | ----------------- | ------------------------------------
+  none           | none              | "40" (prompt default, or --yes)
+  none           | N                 | "N"
+  valid "60"     | none              | kept "60" (prompt Enter keeps it)
+  valid "60"     | N                 | "N"
+  invalid        | none              | replaced with "40" (or prompted value)
+
+The threshold can only be LOWERED by the harness: a value above the
+(reported, unverified) harness default of ~83 is written but warned about.
+
+`--no-autocompact` leaves settings.json untouched and creates
+`.claude/memory/autocompact-nudge-off` so the SessionStart nudge stays quiet.
+
+Exit codes: 0 ok, 2 error. On any error the original file bytes are left
+untouched. Stdlib only; Python 3.10+.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+import tempfile
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+_LIB = Path(__file__).resolve().parents[1] / "hooks" / "lib"
+if str(_LIB) not in sys.path:
+    sys.path.insert(0, str(_LIB))
+
+from autocompact_config import (  # type: ignore[import-not-found]
+    DEFAULT_PCT,
+    HARNESS_DEFAULT_PCT,
+    KEY,
+    detect,
+    validate_pct,
+)
+
+NUDGE_OFF_RELPATH = Path(".claude") / "memory" / "autocompact-nudge-off"
+_TOKENS_ON_200K = 200_000
+
+
+class SetupError(Exception):
+    """A user-facing failure; the settings file was not modified."""
+
+
+def _prompt_text(default: int) -> str:
+    approx = _TOKENS_ON_200K * DEFAULT_PCT // 100 // 1000
+    return (
+        f"Autocompact at what % of the window? [{default}] "
+        f"({DEFAULT_PCT}% ~ {approx}K tokens on a 200K window; "
+        "lower = earlier compaction) "
+    )
+
+
+def _load_settings(path: Path) -> dict:
+    if path.is_symlink():
+        raise SetupError(f"refusing to follow symlink: {path}; not modified")
+    if not path.exists():
+        return {}
+    try:
+        raw = path.read_bytes().decode("utf-8")
+        data = json.loads(raw) if raw.strip() else {}
+    except (OSError, ValueError) as exc:
+        if isinstance(exc, OSError):
+            raise SetupError(f"cannot read {path}: {exc}; not modified") from exc
+        raise SetupError(f"malformed settings.json: {path}; not modified") from exc
+    if not isinstance(data, dict):
+        raise SetupError(f"settings.json top level is not an object: {path}; not modified")
+    if "env" in data and not isinstance(data["env"], dict):
+        raise SetupError(f'"env" is not an object in {path}; not modified')
+    return data
+
+
+def _atomic_write(path: Path, data: dict) -> None:
+    """Write `data` via a unique temp file in the same directory + os.replace.
+
+    mkstemp gives an unpredictable name opened O_EXCL (no planted-symlink or
+    race on a fixed `settings.json.tmp`); the existing file's mode is kept.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_name = None
+    try:
+        fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=".settings.", suffix=".tmp")
+        try:
+            mode = stat.S_IMODE(path.stat().st_mode)
+        except OSError:
+            mode = 0o644
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2)
+            handle.write("\n")
+        os.chmod(tmp_name, mode)
+        os.replace(tmp_name, path)
+    except OSError as exc:
+        if tmp_name is not None:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+        raise SetupError(f"cannot write {path}: {exc}; not modified") from exc
+
+
+def run(
+    project_dir: Path,
+    pct_flag: str | None,
+    assume_yes: bool,
+    no_autocompact: bool,
+    interactive: bool,
+    input_fn: Callable[[str], str] = input,
+    environ: Mapping[str, str] | None = None,
+) -> list[str]:
+    """Apply the setup step; return the stdout lines. Raises SetupError."""
+    if no_autocompact:
+        marker = project_dir / NUDGE_OFF_RELPATH
+        try:
+            marker.parent.mkdir(parents=True, exist_ok=True)
+            marker.touch()
+        except OSError as exc:
+            raise SetupError(f"cannot create {marker}: {exc}") from exc
+        return [f"autocompact left unconfigured; nudge silenced ({marker})"]
+
+    if pct_flag is not None and validate_pct(pct_flag) is None:
+        raise SetupError(f"invalid --autocompact-pct '{pct_flag}': expected integer 1-100")
+
+    path = project_dir / ".claude" / "settings.json"
+    data = _load_settings(path)
+    env_block = data.get("env") or {}
+    existing = env_block.get(KEY)
+    existing_valid = validate_pct(existing) is not None
+    existing_present = KEY in env_block
+
+    lines: list[str] = []
+    # Only the project's settings.json is ever written. A process-env or
+    # settings.local.json entry outranks it, so say so rather than report a
+    # success the harness will not honor.
+    effective = detect(project_dir, os.environ if environ is None else environ)
+    shadow = effective if effective.source in ("process env", "settings.local.json") else None
+    if pct_flag is not None:
+        final = pct_flag
+    else:
+        default = int(existing) if existing_valid else DEFAULT_PCT
+        final = str(default)
+        if interactive and not assume_yes:
+            answer = input_fn(_prompt_text(default)).strip()
+            if answer:
+                if validate_pct(answer) is None:
+                    raise SetupError(f"invalid value '{answer}': expected integer 1-100")
+                final = answer
+
+    if existing_valid and pct_flag is None and final == existing:
+        lines.append(
+            f"kept existing {KEY}={existing} (pass --autocompact-pct to change)"
+        )
+    elif existing_present and not existing_valid:
+        lines.append(f"replaced invalid value '{existing}' with {final}")
+    if int(final) > HARNESS_DEFAULT_PCT:
+        lines.append(
+            f"{final} exceeds the harness default (~{HARNESS_DEFAULT_PCT}%); values above "
+            "the default are ignored, so compaction will still occur at the default"
+        )
+
+    if shadow is not None:
+        lines.append(
+            f"warning: {KEY} is also set in {shadow.source} (value {shadow.raw!r}), which "
+            f"takes precedence over {path}; the value written here will not take effect "
+            "until that entry is removed or corrected"
+        )
+
+    if existing == final:
+        if not lines:
+            lines.append(f"{KEY}={final} already set in {path}")
+        return lines
+
+    data.setdefault("env", {})[KEY] = final
+    _atomic_write(path, data)
+    lines.insert(0, f"set {KEY}={final} in {path}")
+    return lines
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--project-dir", default=".")
+    parser.add_argument("--autocompact-pct", default=None)
+    parser.add_argument("--yes", action="store_true", dest="assume_yes")
+    parser.add_argument("--no-autocompact", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        lines = run(
+            Path(args.project_dir),
+            args.autocompact_pct,
+            args.assume_yes,
+            args.no_autocompact,
+            interactive=sys.stdin.isatty(),
+        )
+    except SetupError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except EOFError:
+        print("no input available; pass --yes or --autocompact-pct", file=sys.stderr)
+        return 2
+    for line in lines:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/ship_resume_guard.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Deterministic /ship resume-guard verdict (#2213).
+
+Replaces the model-applied verdict tree in ``skills/ship`` Step 1a. ``verdict``
+is pure; ``probe`` is the I/O boundary (``gh`` via argv lists, never a shell
+string). Verdicts: ``shipped | monitor | resume | batch-blocked |
+partial-batch | first-run | probe-failed``. ``probe-failed`` is fail-safe —
+the caller must ask the human, never assume ``first-run``.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+
+CLOSE_KEYWORDS = r"(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)"
+
+
+def batch_key(issues: list[int]) -> str:
+    return "issues-" + "-".join(str(n) for n in sorted(issues))
+
+
+def _closes(pr: dict, n: int) -> bool:
+    body = pr.get("body") or ""
+    return bool(re.search(rf"(?i)\b{CLOSE_KEYWORDS}\s+#{n}\b", body)) or \
+        pr.get("headRefName") == f"issue-{n}"
+
+
+def _own_batch_pr(pr: dict, key: str) -> bool:
+    return pr.get("headRefName") == key and not pr.get("isCrossRepository", False)
+
+
+def verdict(issues: list[int], issue_state: dict, prs: list[dict],
+            artifacts: bool) -> dict:
+    """``issue_state``: {n: "OPEN"|"CLOSED"}; ``prs``: gh pr rows (all states)."""
+    batch = len(issues) > 1
+    key = batch_key(issues)
+    closed = [n for n in issues if issue_state.get(n) == "CLOSED"]
+    open_ = [n for n in issues if n not in closed]
+
+    if not open_:
+        return {"verdict": "shipped", "signal": "all-issues-closed", "closed": closed}
+
+    merged = [p for p in prs if p.get("state") == "MERGED"
+              and any(_closes(p, n) for n in open_)]
+    if not batch and merged:
+        return {"verdict": "shipped", "signal": "merged-pr", "pr": merged[0]["number"]}
+
+    own = [p for p in prs if p.get("state") == "OPEN" and batch and _own_batch_pr(p, key)]
+    if own:
+        return {"verdict": "monitor", "signal": "own-batch-pr", "pr": own[0]["number"]}
+    if closed:
+        return {"verdict": "partial-batch", "signal": "mixed-closed-state",
+                "closed": closed, "open": open_}
+
+    blockers = [p for p in prs if p.get("state") == "OPEN"
+                and any(_closes(p, n) for n in open_)]
+    if blockers:
+        if batch:
+            return {"verdict": "batch-blocked", "signal": "foreign-open-pr",
+                    "pr": blockers[0]["number"]}
+        return {"verdict": "monitor", "signal": "open-pr", "pr": blockers[0]["number"]}
+
+    if artifacts:
+        return {"verdict": "resume", "signal": "spec-or-plan-exists"}
+    return {"verdict": "first-run", "signal": "nothing-found"}
+
+
+def _gh(args: list[str]):
+    out = subprocess.run(["gh", *args], capture_output=True, text=True, check=True)
+    return json.loads(out.stdout or "null")
+
+
+def probe(issues: list[int], root: Path):
+    """Return ``(issue_state, prs, artifacts)`` or raise on any probe error."""
+    issue_state = {n: _gh(["issue", "view", str(n), "--json", "state"])["state"]
+                   for n in issues}
+    fields = "number,state,headRefName,body,isCrossRepository"
+    seen: dict[int, dict] = {}
+    queries = [["--search", str(n)] for n in issues]
+    queries += [["--head", f"issue-{n}"] for n in issues]
+    if len(issues) > 1:
+        queries.append(["--head", batch_key(issues)])
+    for q in queries:
+        for pr in _gh(["pr", "list", "--state", "all", "--json", fields, *q]) or []:
+            seen[pr["number"]] = pr
+    return issue_state, list(seen.values()), _artifacts_exist(issues, root)
+
+
+def _artifacts_exist(issues: list[int], root: Path) -> bool:
+    needles = [f"#{n}" for n in issues]
+    for pattern in ("docs/specs/**/plans/*.md", "docs/specs/**/spec.md", "plans/*.md"):
+        for f in root.glob(pattern):
+            try:
+                text = f.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            if any(re.search(rf"{re.escape(t)}\b", text) for t in needles):
+                return True
+    return False
+
+
+def parse_issues(raw: str) -> list[int]:
+    tokens = [t.strip() for t in raw.split(",")]
+    for t in tokens:
+        if not re.fullmatch(r"[0-9]+", t):
+            raise ValueError(f"invalid issue token: {t!r}")
+    return [int(t) for t in tokens]
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--issues", required=True, help="comma-separated issue numbers")
+    p.add_argument("--root", type=Path, default=Path("."))
+    args = p.parse_args(argv)
+    try:
+        issues = parse_issues(args.issues)
+    except ValueError as exc:
+        p.error(str(exc))
+    try:
+        state, prs, artifacts = probe(issues, args.root)
+    except (OSError, subprocess.CalledProcessError, ValueError, KeyError) as exc:
+        print(json.dumps({"verdict": "probe-failed", "error": str(exc)}))
+        return 0
+    print(json.dumps(verdict(issues, state, prs, artifacts)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ship_review_gate.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Decide whether /ship's Review phase is redundant (#2212).
+
+/build's inline checkpoints and Step 6 backstop already record per-lens
+verdicts in ``.claude/metrics/review-verdicts.jsonl`` keyed by
+``(lens, file, content hash)``. When every resolver-selected lens has a
+``pass`` row for every changed file at its CURRENT content, a second
+whole-change ``/code-review`` has nothing left to examine.
+
+Fail-closed: no files, no ledger, an unhashable file, or any missing/failing
+row means ``skip: false`` — the pass runs, exactly as before.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+import select_lenses
+import verdict_scope
+
+
+def decide(files, root: Path, agents_dir: Path, registry: Path) -> dict:
+    files = list(files)
+    if not files:
+        return {"skip": False, "reason": "no-changed-files"}
+    roster, warnings = select_lenses.build_review_roster(agents_dir, registry)
+    lenses, more = select_lenses.applicable_lenses(
+        files, roster, test_files=select_lenses.test_file_subset(files)
+    )
+    warnings = warnings + more
+    if not lenses:
+        return {"skip": False, "reason": "no-applicable-lenses", "warnings": warnings}
+    result = verdict_scope.resolve_for_root({n: files for n in lenses}, root)
+    pending = {k: v for k, v in result["toDispatch"].items() if v}
+    if pending:
+        return {"skip": False, "reason": "uncleared-lens-files", "pending": pending,
+                "warnings": warnings}
+    return {"skip": True, "reason": "all-lenses-cleared-at-current-content",
+            "lenses": sorted(lenses), "warnings": warnings}
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--root", type=Path, default=Path("."))
+    p.add_argument("--files", nargs="*", default=[])
+    p.add_argument("--agents-dir", type=Path, default=_HERE.parent / "agents")
+    p.add_argument("--registry", type=Path,
+                   default=_HERE.parent / "knowledge" / "agent-registry.md")
+    args = p.parse_args(argv)
+    print(json.dumps(decide(args.files, args.root, args.agents_dir, args.registry)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/specs_convention_marker.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Detect the issue-first specs convention opt-in marker (#986).
+
+`/specs` only persists spec artifacts to a GitHub issue (instead of writing
+`docs/specs/<slug>.md`) on a project that has *explicitly* opted into that
+convention. This script classifies whether a project's root `CLAUDE.md`
+declares the opt-in via a literal marker phrase, so no downstream consumer of
+the shipped plugin is silently switched to issue-based persistence just
+because its origin happens to be GitHub.
+
+Prints exactly one of:
+    marker     — root CLAUDE.md exists and contains the marker phrase
+                 ("Specs and plans are GitHub issues here, not files",
+                 markdown emphasis stripped, case-insensitive)
+    no-marker  — root CLAUDE.md exists but does not contain the marker phrase
+    none       — no root CLAUDE.md found (fail-open: callers treat this
+                 identically to "no-marker" — routes to file-based
+                 persistence — never blocks)
+
+This is the primary, literal-match, tested path. A caller MAY still apply
+judgment for an equivalently-worded-but-differently-phrased declaration
+before concluding "no marker" when this script reports `no-marker` or
+`none` — that manual-judgment fallback is deliberately not covered by this
+script or its tests (see plans/issue-986-specs-github-issue-persistence.md's
+Risks & Open Questions).
+
+Reads `<repo-root>/CLAUDE.md` (repo root resolved via
+`git rev-parse --show-toplevel`) unless a path is given as argv[1] (for
+testing, or to point at an arbitrary CLAUDE.md directly).
+
+Usage: specs_convention_marker.py [claude-md-path]
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+MARKER_PHRASE = "specs and plans are github issues here, not files"
+
+
+def has_marker(text: str) -> bool:
+    """Return True if `text` contains the issue-first-specs marker phrase.
+
+    Strips markdown emphasis characters (`*`) and lowercases before matching,
+    so "**Specs and plans are GitHub issues here, not files.**" and other
+    minor emphasis/case variants still match.
+    """
+    if not text:
+        return False
+    normalized = text.replace("*", "").lower()
+    return MARKER_PHRASE in normalized
+
+
+def classify(claude_md_path: Path | None) -> str:
+    """Return "marker", "no-marker", or "none" for a root CLAUDE.md path.
+
+    Fail-open: any read error (missing file, permission error, etc.) yields
+    "none" rather than raising.
+    """
+    if claude_md_path is None:
+        return "none"
+    try:
+        if not claude_md_path.is_file():
+            return "none"
+        text = claude_md_path.read_text(encoding="utf-8")
+    except OSError:
+        return "none"
+    return "marker" if has_marker(text) else "no-marker"
+
+
+def _resolve_repo_root() -> Path | None:
+    """Return the git repo root, or None on any failure (fail-open)."""
+    try:
+        completed = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return None
+    if completed.returncode != 0:
+        return None
+    root = completed.stdout.strip()
+    return Path(root) if root else None
+
+
+def main(argv: list) -> int:
+    if len(argv) > 1 and argv[1]:
+        claude_md_path: Path | None = Path(argv[1])
+    else:
+        root = _resolve_repo_root()
+        claude_md_path = (root / "CLAUDE.md") if root is not None else None
+    print(classify(claude_md_path))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))