pi-dev-team 0.2.0

package/hooks/lib/knowledge_index_paths.py

@@ -0,0 +1,88 @@
+"""knowledge_index_paths — single source of truth for which path edits must
+trigger an index rebuild/freshness check.
+
+Python port of hooks/lib/knowledge-index-paths.sh (#575 / #572 Cluster A).
+
+Imported (not executed) by the Python siblings of the three .sh callers:
+  - hooks/knowledge-index.py                   (PostToolUse regenerator)
+  - hooks/pre-commit-knowledge-index.py        (pre-commit freshness gate)
+  - tests/agents/… anchor-citation gate        (still bats today; the .py
+                                                port will import this module)
+
+`is_corpus_path()` answers "does an edit here change indexed content and
+need a rebuild" — that is a broader set than "is this file a top-level
+index entry" (owned by build_knowledge_index.py's `discover_files()`, which
+walks only the first two shapes below). Deliberately two different
+questions, not two copies of one: a references/*.md file is never itself an
+index entry, but editing it changes the *summary* of the SKILL.md section
+that includes it, so it must trigger the same rebuild as editing that
+SKILL.md directly.
+
+Rebuild triggers:
+  - plugins/dev-team/knowledge/*.md                    (top-level .md only;
+                                                        also an index entry)
+  - plugins/dev-team/skills/<name>/SKILL.md            (also an index entry)
+  - plugins/dev-team/skills/<name>/references/*.md     (NOT an index entry —
+                                                        only feeds another
+                                                        entry's summary, via
+                                                        build_knowledge_index.py's
+                                                        `<!-- include:
+                                                        references/<name>.md
+                                                        -->` marker
+                                                        resolution, Step 1.1
+                                                        of plans/
+                                                        test-improve-context-loading-strategy.md)
+
+Excluded:
+  - plugins/dev-team/knowledge/schemas/**   (json schemas, not docs)
+  - everything else (agents/, commands/, docs/, README.md, …)
+
+Anchor: top-level knowledge .md, <skills-dir>/<one segment>/SKILL.md, OR
+<skills-dir>/<one segment>/references/<one segment>.md. A leading `(^|/)`
+allows repo-relative or absolute paths.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+# Regex matching corpus paths (POSIX ERE from the .sh sibling, ported to
+# Python re syntax). Anchor: end-of-string; a leading segment is optional so
+# absolute and repo-relative inputs both match. Alternation covers the three
+# corpus shapes: top-level knowledge markdown, per-skill SKILL.md, and
+# per-skill references/*.md (spliced into a SKILL.md summary via include
+# markers — see the module docstring above).
+CORPUS_REGEX: str = (
+    r"(^|/)plugins/dev-team/"
+    r"(knowledge/[^/]+\.md|skills/[^/]+/SKILL\.md|skills/[^/]+/references/[^/]+\.md)$"
+)
+
+_CORPUS_RE = re.compile(CORPUS_REGEX)
+
+
+def is_corpus_path(path: str) -> bool:
+    """Return True iff `path` is part of the indexed corpus.
+
+    Byte-parity with the .sh's `_is_corpus_path`. Windows backslash paths
+    do NOT match — the corpus is a forward-slash convention and Git Bash
+    surfaces forward slashes even on Windows.
+    """
+    if not path:
+        return False
+    return _CORPUS_RE.search(path) is not None
+
+
+def filter_corpus_paths(paths: Iterable[str]) -> list[str]:
+    """Return the input list filtered to corpus paths, preserving order.
+
+    Convenience for hook callers that receive a batch of changed files and
+    want only the ones the index cares about. Order-preserving because
+    downstream builds are order-sensitive (see build_knowledge_index.py).
+    """
+    return [p for p in paths if is_corpus_path(p)]
+
+
+__all__ = ("CORPUS_REGEX", "filter_corpus_paths", "is_corpus_path")

package/hooks/lib/mcp_json_repowise.py

@@ -0,0 +1,177 @@
+"""Shared repowise `.mcp.json` detection + relocation (#1747).
+
+`repowise init`/`repowise update` unconditionally writes a `mcpServers.
+repowise` entry into the project-root `.mcp.json`, baking in the invoking
+machine's absolute filesystem path (a known, currently-open upstream bug:
+repowise-dev/repowise#1117). When `.mcp.json` is git-tracked — a team may
+legitimately commit it to distribute other MCP servers (`codegraph`, an
+internal org server) that don't bake in a local path — that entry breaks
+for every other clone/teammate.
+
+`detect()` is the single shared predicate both consumers of this module
+need: `project-init/SKILL.md`'s `.mcp.json` standing check (which calls
+`relocate()` via this module's CLI) and `hooks/mcp_json_repowise_nudge.py`
+(the SessionStart hook that prompts an already-initialized project to
+re-run `/project-init`). Implemented once here so the two can never drift
+out of sync on what counts as "needs fixing."
+
+`relocate()` registers at `local` scope BEFORE stripping the tracked entry
+— never the reverse — so a failed `claude mcp add` (CLI missing, timeout,
+non-zero exit) leaves `.mcp.json` untouched rather than deleting the only
+registration that existed. Every other `mcpServers` entry is preserved
+byte-for-byte; only the `repowise` key is ever touched.
+
+Stdlib-only. Python 3.10+. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+_MCP_JSON_NAME = ".mcp.json"
+_SERVER_NAME = "repowise"
+
+
+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _dump_json(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def is_tracked(mcp_json_path: Path, cwd: Path) -> bool:
+    """True iff `mcp_json_path` exists and `git ls-files --error-unmatch`
+    (run with `cwd`) confirms it's tracked. False on any git failure (not a
+    repo, git missing, timeout) — never raises."""
+    if not mcp_json_path.is_file():
+        return False
+    try:
+        completed = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", mcp_json_path.name],
+            cwd=str(cwd),
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return completed.returncode == 0
+
+
+def detect(cwd: Path) -> dict | None:
+    """The shared predicate: the `repowise` `mcpServers` entry iff
+    `<cwd>/.mcp.json` exists, is git-tracked, AND carries a `repowise` key.
+    None on anything else, including any internal failure — this must
+    never raise, since both callers treat None as "nothing to do"."""
+    try:
+        mcp_json_path = Path(cwd) / _MCP_JSON_NAME
+        if not is_tracked(mcp_json_path, Path(cwd)):
+            return None
+        servers = _load_json(mcp_json_path).get("mcpServers")
+        if not isinstance(servers, dict):
+            return None
+        entry = servers.get(_SERVER_NAME)
+        return entry if isinstance(entry, dict) else None
+    except Exception:  # noqa: BLE001 - fail-open: a detection bug must never propagate
+        return None
+
+
+def strip_entry(mcp_json_path: Path) -> bool:
+    """Remove only the `repowise` key from `mcp_json_path`'s `mcpServers`
+    object, preserving every other entry untouched. Drops the `mcpServers`
+    key entirely if removing `repowise` leaves it empty. Idempotent: a
+    no-op (returns False, no write) when there's nothing to strip."""
+    config = _load_json(mcp_json_path)
+    servers = config.get("mcpServers")
+    if not isinstance(servers, dict) or _SERVER_NAME not in servers:
+        return False
+    servers.pop(_SERVER_NAME)
+    if servers:
+        config["mcpServers"] = servers
+    else:
+        config.pop("mcpServers", None)
+    _dump_json(mcp_json_path, config)
+    return True
+
+
+def _register_local_scope(repo_root: Path) -> bool:
+    """`claude mcp add repowise --scope local -- repowise mcp <repo_root>
+    --transport stdio`. True on exit 0; False on any failure (`claude` CLI
+    missing, non-zero exit, timeout) — never raises. Deliberately re-derives
+    `args` from the CURRENT repo root rather than reusing the stripped
+    entry's own `args` — those carry the OLD, wrong machine's path, which is
+    exactly the bug being fixed."""
+    try:
+        completed = subprocess.run(
+            [
+                "claude", "mcp", "add", _SERVER_NAME, "--scope", "local",
+                "--", _SERVER_NAME, "mcp", str(repo_root), "--transport", "stdio",
+            ],
+            cwd=str(repo_root),
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return completed.returncode == 0
+
+
+def relocate(
+    cwd: Path, *, register: Callable[[Path], bool] = _register_local_scope
+) -> str:
+    """Detect -> register at local scope -> strip from the tracked file, in
+    that order (never strip-then-register — see module docstring). Returns
+    one of:
+        "not-tracked"       -- .mcp.json missing, or not git-tracked
+        "no-repowise-entry" -- tracked, but no repowise key to relocate
+        "relocated"         -- registered locally and stripped
+        "relocate-failed"   -- repowise entry found, but `claude mcp add`
+                                failed; .mcp.json is left untouched
+
+    `register` is injectable (stdlib `Callable`, defaulting to the real
+    `claude mcp add` call) so callers/tests can verify both branches
+    without a real `claude` CLI or a live MCP registration. Never raises.
+    """
+    cwd = Path(cwd)
+    entry = detect(cwd)
+    if entry is None:
+        return "no-repowise-entry" if is_tracked(cwd / _MCP_JSON_NAME, cwd) else "not-tracked"
+
+    if not register(cwd):
+        return "relocate-failed"
+
+    strip_entry(cwd / _MCP_JSON_NAME)
+    return "relocated"
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=["relocate"])
+    parser.add_argument("--cwd", default=".")
+    args = parser.parse_args()
+
+    if args.action == "relocate":
+        print(relocate(Path(args.cwd).resolve()))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

package/hooks/lib/metrics_query.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""metrics_query.py — typed/faceted query helper over metrics event streams (#1169).
+
+`dev-team`'s `metrics/*.jsonl` streams (see `knowledge/telemetry-schema.md`)
+are greppable but every consumer hand-rolls `jq`. This is a thin, generic
+filter/facet reader over any single stream so `/session-review` and ad-hoc
+use can slice without bespoke `jq` — no assumptions about which streams
+exist, since sibling issues (#1166 `workflow-states.jsonl`, #1168
+`iteration-journal.jsonl`) land in parallel and may or may not be present in
+any given worktree/checkout.
+
+Field-name heterogeneity (documented, not papered over)
+--------------------------------------------------------
+`telemetry-schema.md` shows every stream uses slightly different field
+names for the same *concept*. This module does not assume one canonical
+schema; each facet tries a short, documented list of candidate field names
+in priority order and uses the first one present on a given entry:
+
+  * `--type` (event/category facet) tries, in order: `event` (e.g.
+    `telemetry.jsonl`'s `command`/`skill`/`gate`), `type` (e.g.
+    `config-changelog.jsonl`'s `amend`/`approval`/...), `hook` (e.g.
+    `boundary-events.jsonl`, `gate-bypass.jsonl`, `refactor-freeze.jsonl`),
+    `workflow` (e.g. `workflow-states.jsonl`'s `ship`/`autoship`/`build`).
+    This order runs from the most stream-specific "this IS an event type"
+    field name to the more generic ones, so a stream that happens to define
+    both `event` and `hook` (none currently do) still resolves
+    unambiguously.
+  * `--gate-outcome` tries, in order: `decision` (e.g.
+    `boundary-events.jsonl`'s `block`/`warn`/`bypass`/`intervention`/
+    `revert`), then `outcome` (e.g. `telemetry.jsonl`'s `fired`/`bypassed`,
+    `autoship-log.jsonl`'s `success`/`convergence_failure`). `decision`
+    first because it is the more specific/deliberate name for a gate's
+    verdict; `outcome` is the broader fallback used by streams with no
+    dedicated `decision` field.
+  * `--since` (inclusive lower bound) tries, in order: `ts`, then
+    `timestamp`. Comparison is a plain lexical string compare, valid only
+    because every emitter in this repo stamps `%Y-%m-%dT%H:%M:%SZ` UTC
+    (confirmed against `boundary_events.py` and `workflow_state.py`), which
+    sorts identically lexically and chronologically.
+  * `until` (inclusive upper bound, symmetric to `since`; #1461) tries the
+    same `ts`/`timestamp` fallback order and the same lexical comparison.
+    Python-API-only today (no `--until` CLI flag) — added for
+    `hooks/lib/review_gate_corroboration.py`'s recency-window read, which
+    needs both bounds to select entries strictly between a gate file's mtime
+    and that mtime minus a window.
+  * `--session` matches the `session_id` field only — every stream that
+    carries a session join key names it identically.
+
+All provided filters compose with AND. Malformed JSON lines are skipped,
+not fatal — these streams are hand-authored-adjacent, append-only logs and
+a single corrupt line must never break a query over the rest of the file.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+
+_TYPE_FIELDS = ("event", "type", "hook", "workflow")
+_GATE_OUTCOME_FIELDS = ("decision", "outcome")
+_TS_FIELDS = ("ts", "timestamp")
+
+
+def _first_present(entry: dict, candidates) -> str | None:
+    for field in candidates:
+        if field in entry and entry[field] is not None:
+            return entry[field]
+    return None
+
+
+def load_stream(path) -> Iterator[dict]:
+    """Yield parsed JSON objects from a JSONL file, skipping malformed lines.
+
+    Non-dict JSON values (e.g. a bare string or number on a line) are also
+    skipped, since every stream is a sequence of JSON objects.
+    """
+    path = Path(path)
+    if not path.is_file():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(entry, dict):
+            yield entry
+
+
+def filter_entries(
+    entries: Iterable[dict],
+    event_type: str | None = None,
+    session_id: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    gate_outcome: str | None = None,
+) -> Iterator[dict]:
+    """Apply every provided filter (AND-composed) to `entries`, a pure filter.
+
+    Each filter is skipped entirely when its argument is `None`, so calling
+    with no filters is an identity pass-through — omitting `until` behaves
+    exactly as before its addition (#1461).
+    """
+    for entry in entries:
+        if event_type is not None and _first_present(entry, _TYPE_FIELDS) != event_type:
+            continue
+        if session_id is not None and entry.get("session_id") != session_id:
+            continue
+        if since is not None:
+            ts = _first_present(entry, _TS_FIELDS)
+            if not isinstance(ts, str) or ts < since:
+                continue
+        if until is not None:
+            ts = _first_present(entry, _TS_FIELDS)
+            if not isinstance(ts, str) or ts > until:
+                continue
+        if gate_outcome is not None and _first_present(entry, _GATE_OUTCOME_FIELDS) != gate_outcome:
+            continue
+        yield entry
+
+
+def facet_count(entries: Iterable[dict], field: str) -> dict:
+    """Value -> count breakdown of `field` across `entries`.
+
+    Entries missing `field` are omitted from the result entirely (not
+    counted under e.g. a `None` bucket) since an absent field is a schema
+    mismatch, not a meaningful facet value.
+    """
+    counts: dict = {}
+    for entry in entries:
+        if field not in entry or entry[field] is None:
+            continue
+        value = entry[field]
+        key = value if isinstance(value, str) else json.dumps(value, sort_keys=True)
+        counts[key] = counts.get(key, 0) + 1
+    return counts
+
+
+def _stream_path(cwd, stream: str) -> Path:
+    base = Path(cwd) if cwd else Path.cwd()
+    # Read-only query: migrate=False so a mere query never migrates a legacy
+    # file or creates .claude/metrics/ as a side effect.
+    return artifact_paths.resolve_file("metrics", f"{stream}.jsonl", base, migrate=False)
+
+
+def cmd_query(args) -> int:
+    path = _stream_path(args.cwd, args.stream)
+    entries = list(
+        filter_entries(
+            load_stream(path),
+            event_type=args.type,
+            session_id=args.session,
+            since=args.since,
+            gate_outcome=args.gate_outcome,
+        )
+    )
+
+    if args.facet:
+        counts = facet_count(entries, args.facet)
+        for value, count in sorted(counts.items(), key=lambda kv: -kv[1]):
+            print(f"{value}\t{count}")
+        return 0
+
+    if args.format == "json-array":
+        print(json.dumps(entries, indent=2))
+    else:
+        for entry in entries:
+            print(json.dumps(entry, separators=(",", ":")))
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--cwd", default=None, help="Project directory (default: cwd)")
+    ap.add_argument("--stream", required=True, help="Stream name, resolves to .claude/metrics/<name>.jsonl")
+    ap.add_argument("--type", default=None, help="Event-type facet; see module docstring for field fallback order")
+    ap.add_argument("--session", default=None, help="Filter on the session_id field")
+    ap.add_argument("--since", default=None, help="ISO-8601 lower bound on the ts/timestamp field")
+    ap.add_argument("--gate-outcome", dest="gate_outcome", default=None, help="Gate decision/outcome facet")
+    ap.add_argument("--facet", default=None, help="Print value->count breakdown for this field instead of matches")
+    ap.add_argument("--format", choices=["jsonl", "json-array"], default="jsonl")
+    ap.set_defaults(func=cmd_query)
+
+    parsed = ap.parse_args(argv)
+    return parsed.func(parsed)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())