pi-dev-team 0.2.0

package/scripts/build_rollback_point.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""build_rollback_point.py — resolve + record slice rollback points (#865).
+
+A plan's optional slice-level `**Rollback point:**` field is symbolic — a
+concrete SHA cannot be known when the plan is written. Values are one of
+`slice-start` (default meaning: HEAD at slice dispatch), `wave-start`,
+`plan-start`, or an explicit git ref. `/build` resolves the symbolic value
+to a concrete SHA at slice dispatch and records it in the slice's build
+bookkeeping so a dead-end escalation (issue #864) can name the exact revert
+boundary: "revert to <sha> (<symbolic>)".
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_SYMBOLIC_VALUES = ("slice-start", "wave-start", "plan-start")
+
+
+def resolve_rollback_point(
+    symbolic: str,
+    *,
+    repo_root: str,
+    slice_start: str | None = None,
+    wave_start: str | None = None,
+    plan_start: str | None = None,
+) -> str:
+    """Resolve a symbolic rollback value (or an explicit ref) to a concrete
+    commit SHA. Raises `ValueError` if the ref cannot be resolved, and
+    `ValueError` if a symbolic value is requested but its anchor ref wasn't
+    supplied (the caller — `/build` — always has these three at dispatch
+    time)."""
+    mapping = {
+        "slice-start": slice_start,
+        "wave-start": wave_start,
+        "plan-start": plan_start,
+    }
+    if symbolic in mapping:
+        ref = mapping[symbolic]
+        if not ref:
+            raise ValueError(
+                f"rollback point '{symbolic}' requires its anchor ref to be supplied"
+            )
+    else:
+        ref = symbolic  # explicit ref, e.g. a SHA or tag
+
+    result = subprocess.run(
+        ["git", "rev-parse", ref],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise ValueError(f"could not resolve ref {ref!r}: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def _load(path: Path) -> dict[str, dict]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def record_rollback_point(path: Path, slice_id: str, symbolic: str, sha: str) -> None:
+    """Persist `{slice_id: {"symbolic", "sha", "recorded_at"}}` to `path`,
+    merging with any existing entries for other slices."""
+    data = _load(path)
+    data[slice_id] = {
+        "symbolic": symbolic,
+        "sha": sha,
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def get_rollback_point(path: Path, slice_id: str) -> dict | None:
+    """Retrieve the recorded rollback point for `slice_id`, or `None`."""
+    return _load(path).get(slice_id)
+
+
+def _is_ancestor(candidate_sha: str, of_ref: str, repo_root: str) -> bool:
+    """True when `candidate_sha` is an ancestor of `of_ref` (or equal to
+    it) in `repo_root`'s history — `git merge-base --is-ancestor` exits 0
+    for a real ancestor/self, non-zero otherwise (including when either
+    ref can't be resolved in this repo at all)."""
+    result = subprocess.run(
+        ["git", "merge-base", "--is-ancestor", candidate_sha, of_ref],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def find_rollback_point_by_symbolic(
+    path: Path,
+    symbolic: str,
+    *,
+    repo_root: str | None = None,
+    ancestor_of: str | None = None,
+) -> dict | None:
+    """Find a recorded entry (any slice) whose `symbolic` value matches, or
+    `None` if none qualifies.
+
+    Used by `/build` Step 7's degenerate branch-base fallback (issue #916):
+    when `git merge-base` resolution collapses to `HEAD` (or fails outright
+    — e.g. a single-branch/no-remote repo), the plan-start commit already
+    resolved for a `Rollback point: plan-start` slice (issue #865) is a
+    trustworthy alternative base, distinct from a ref that merely happens
+    to equal `HEAD`.
+
+    `memory/build-rollback.json` is a flat, unscoped store that is never
+    cleared between plans or builds sharing a worktree — the first
+    `symbolic` match by insertion order could be a stale SHA left behind by
+    an unrelated earlier build. When both `repo_root` and `ancestor_of` are
+    supplied, a candidate is only accepted when its `sha` is actually an
+    ancestor of `ancestor_of` (typically the current `HEAD`) via
+    `git merge-base --is-ancestor` — a stale entry from a different branch
+    history will not satisfy this and is skipped in favor of the next
+    match, or `None` if no entry qualifies. Callers that omit both
+    (`repo_root`/`ancestor_of`) get the unfiltered first match, matching
+    the CLI default when `--repo`/`--ancestor-of` aren't passed."""
+    for entry in _load(path).values():
+        if entry.get("symbolic") != symbolic:
+            continue
+        if repo_root is not None and ancestor_of is not None:
+            sha = entry.get("sha")
+            if not sha or not _is_ancestor(sha, ancestor_of, repo_root):
+                continue
+        return entry
+    return None
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="build_rollback_point.py",
+        description="Resolve and record a slice's rollback point (issue #865).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    resolve_p = sub.add_parser("resolve", help="Resolve a symbolic value to a SHA.")
+    resolve_p.add_argument("--symbolic", required=True)
+    resolve_p.add_argument("--repo", default=".")
+    resolve_p.add_argument("--slice-start")
+    resolve_p.add_argument("--wave-start")
+    resolve_p.add_argument("--plan-start")
+
+    record_p = sub.add_parser("record", help="Record a resolved rollback point.")
+    record_p.add_argument("--path", type=Path, required=True)
+    record_p.add_argument("--slice", required=True)
+    record_p.add_argument("--symbolic", required=True)
+    record_p.add_argument("--sha", required=True)
+
+    get_p = sub.add_parser("get", help="Retrieve a recorded rollback point.")
+    get_p.add_argument("--path", type=Path, required=True)
+    get_p.add_argument("--slice", required=True)
+
+    get_by_symbolic_p = sub.add_parser(
+        "get-by-symbolic",
+        help="Find any recorded rollback point by its symbolic value (issue #916).",
+    )
+    get_by_symbolic_p.add_argument("--path", type=Path, required=True)
+    get_by_symbolic_p.add_argument("--symbolic", required=True)
+    get_by_symbolic_p.add_argument(
+        "--repo",
+        help="Repo root to validate the candidate SHA's ancestry in. "
+        "Pair with --ancestor-of to reject stale entries from an unrelated "
+        "build sharing this worktree's memory/ store.",
+    )
+    get_by_symbolic_p.add_argument(
+        "--ancestor-of",
+        help="Only accept a candidate whose SHA is an ancestor of this ref "
+        "(typically HEAD). Requires --repo.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "resolve":
+        try:
+            sha = resolve_rollback_point(
+                args.symbolic,
+                repo_root=args.repo,
+                slice_start=args.slice_start,
+                wave_start=args.wave_start,
+                plan_start=args.plan_start,
+            )
+        except ValueError as exc:
+            sys.stderr.write(f"build-rollback-point: {exc}\n")
+            return 2
+        print(sha)
+        return 0
+
+    if args.command == "record":
+        record_rollback_point(args.path, args.slice, args.symbolic, args.sha)
+        print(f"Recorded rollback point for slice {args.slice}: {args.sha}")
+        return 0
+
+    if args.command == "get":
+        entry = get_rollback_point(args.path, args.slice)
+        if entry is None:
+            sys.stderr.write(
+                f"build-rollback-point: no rollback point recorded for slice {args.slice}\n"
+            )
+            return 1
+        print(json.dumps(entry))
+        return 0
+
+    if args.command == "get-by-symbolic":
+        entry = find_rollback_point_by_symbolic(
+            args.path,
+            args.symbolic,
+            repo_root=args.repo,
+            ancestor_of=args.ancestor_of,
+        )
+        if entry is None:
+            sys.stderr.write(
+                f"build-rollback-point: no rollback point recorded with symbolic {args.symbolic!r}\n"
+            )
+            return 1
+        print(json.dumps(entry))
+        return 0
+
+    return 2  # pragma: no cover — argparse enforces a valid subcommand
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/build_slice_scope.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""build_slice_scope.py — freeze-scope wiring for `/build` (issue #865).
+
+Auto-freeze is OPT-IN VIA PLAN METADATA: a top-level `**Scope enforcement:**
+freeze` line in the plan enables it. Declared per-slice `**Files:**` alone
+only feeds `plan_waves.py`'s scope-mismatch warnings (see `plan_waves.py`) —
+it never freezes anything by itself.
+
+When engaged, `/build` calls this script at slice dispatch to write
+`freeze-state.json` (the same contract `/freeze` writes and
+`hooks/pre_tool_guard.py` already enforces) into the `--hooks-dir` the
+caller passes — `/build` passes `<worktree>/.claude/hooks`, matching
+`hooks/pre_tool_guard.py`'s per-repo `.claude/hooks/freeze-state.json`
+resolution via `hooks/lib/artifact_paths.py` (issue #1890); the writer here
+takes the directory as a plain argument and has no opinion of its own on
+which directory that should be — with `allowed_patterns` equal to
+the slice's declared paths **plus a fixed bookkeeping allowlist** (the plan
+file itself, `.claude/memory/**`, `.claude/metrics/**`, and the AC3-exempt
+`metrics/verify-log.jsonl`) — without which `/build` could not update its
+own Build Progress checkboxes, `.claude/memory/build-phase.json`, or its
+own exempt verify-log entry. At slice completion, `/build` calls this
+script again to clear the state.
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE / "lib"))
+
+import plan_parse
+
+_SCOPE_ENFORCEMENT_RE = re.compile(
+    r"^\*\*Scope enforcement:?\*\*\s*:?\s*(.+)$", re.IGNORECASE | re.MULTILINE
+)
+_TOKEN_SPLIT_RE = re.compile(r"[,\s]+")
+
+FREEZE_STATE_FILENAME = "freeze-state.json"
+
+
+def scope_enforcement_enabled(plan_text: str) -> bool:
+    """True when the plan's top-level `**Scope enforcement:** freeze` line
+    is present (case-insensitive). Any other value (or its absence) means
+    declared Files feeds mismatch warnings only — no auto-freeze."""
+    match = _SCOPE_ENFORCEMENT_RE.search(plan_text)
+    if not match:
+        return False
+    return match.group(1).strip().lower().startswith("freeze")
+
+
+def declared_files_for_slice(plan_text: str, slice_id: str) -> list[str]:
+    """Return the tokenized slice-level `**Files:**` declaration for
+    `slice_id`, or `[]` when the slice declares none."""
+    rows = plan_parse.parse_slices(plan_text.splitlines())
+    for sid, _deps, files_raw in rows:
+        if sid == slice_id:
+            return [f for f in _TOKEN_SPLIT_RE.split(files_raw) if f]
+    return []
+
+
+def bookkeeping_allowlist(plan_path: Path) -> list[str]:
+    """The fixed allowlist every freeze must include so `/build` never
+    self-blocks its own progress writes: the plan file itself, plus
+    `.claude/memory/**`, `.claude/metrics/**`, and the AC3-exempt
+    `metrics/verify-log.jsonl` (deliberately not relocated under `.claude/`
+    — see docs/artifact-migration.md)."""
+    return [
+        plan_path.name,
+        ".claude/memory/**",
+        ".claude/metrics/**",
+        "metrics/verify-log.jsonl",
+    ]
+
+
+def build_allowed_patterns(plan_path: Path, plan_text: str, slice_id: str) -> list[str]:
+    declared = declared_files_for_slice(plan_text, slice_id)
+    return declared + bookkeeping_allowlist(plan_path)
+
+
+def write_freeze_state(hooks_dir: Path, allowed_patterns: list[str]) -> Path:
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    state_path = hooks_dir / FREEZE_STATE_FILENAME
+    payload = {
+        "active": True,
+        "allowed_patterns": allowed_patterns,
+        "frozen_at": datetime.now(timezone.utc).isoformat(),
+    }
+    state_path.write_text(json.dumps(payload, indent=2) + "\n")
+    return state_path
+
+
+def clear_freeze_state(hooks_dir: Path) -> Path:
+    """Remove the freeze-state file — mirrors `/unfreeze`'s `rm -f`."""
+    state_path = hooks_dir / FREEZE_STATE_FILENAME
+    if state_path.exists():
+        state_path.unlink()
+    return state_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="build_slice_scope.py",
+        description="Engage/clear /build's per-slice freeze scope lock (issue #865).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    enabled_p = sub.add_parser(
+        "enabled", help="Exit 0 if the plan opts into freeze scope enforcement."
+    )
+    enabled_p.add_argument("plan", type=Path)
+
+    engage_p = sub.add_parser(
+        "engage", help="Write freeze-state.json scoped to a slice's declared Files."
+    )
+    engage_p.add_argument("plan", type=Path)
+    engage_p.add_argument("--slice", required=True)
+    engage_p.add_argument("--hooks-dir", type=Path, required=True)
+
+    clear_p = sub.add_parser("clear", help="Clear freeze-state.json.")
+    clear_p.add_argument("--hooks-dir", type=Path, required=True)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "enabled":
+        plan_text = args.plan.read_text(encoding="utf-8")
+        if scope_enforcement_enabled(plan_text):
+            print("enabled")
+            return 0
+        print("disabled")
+        return 1
+
+    if args.command == "engage":
+        plan_text = args.plan.read_text(encoding="utf-8")
+        allowed = build_allowed_patterns(args.plan, plan_text, args.slice)
+        state_path = write_freeze_state(args.hooks_dir, allowed)
+        print(f"Freeze engaged for slice {args.slice}: {state_path}")
+        print(f"Allowed patterns: {', '.join(allowed)}")
+        return 0
+
+    if args.command == "clear":
+        state_path = clear_freeze_state(args.hooks_dir)
+        print(f"Freeze cleared: {state_path}")
+        return 0
+
+    return 2  # pragma: no cover — argparse enforces a valid subcommand
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/build_wave.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Python port of scripts/build-wave.sh (#611 / #572 Phase 3).
+
+Emit the build's wave schedule, derived from plan_waves.py. Each wave lists
+its members and a deterministic reconcile order (members sorted) so a wave
+merges reproducibly regardless of completion order:
+
+    { "schema": "build-wave/v1",
+      "waves": [ { "wave": 1, "members": [...], "reconcile_order": [...] } ],
+      "collisions": [...] }
+
+Exits non-zero if the plan is invalid (cycle / missing / unknown — surfaced by
+plan_waves.py) OR if any wave has a declared same-file collision: a wave with
+a collision must not be built concurrently, so the build refuses it here.
+
+Usage: build_wave.py <plan.md>
+
+Delegates DAG analysis to plan_waves.py (the authoritative implementation
+until its own port lands per #572). Once plan_waves.py is ported to Python,
+switch the subprocess call for a direct import.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _here() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def _run_plan_waves(plan_file: str) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr) from `plan_waves.py <plan.md>`."""
+    plan_waves = _here() / "plan_waves.py"
+    completed = subprocess.run(
+        [sys.executable, str(plan_waves), plan_file],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return completed.stdout, completed.returncode, completed.stderr
+
+
+def _reshape(waves_json: dict) -> dict:
+    """Reshape plan-waves output into the build-wave/v1 schedule schema."""
+    reshaped_waves = []
+    for i, members in enumerate(waves_json.get("waves", []), start=1):
+        reshaped_waves.append(
+            {
+                "wave": i,
+                "members": members,
+                "reconcile_order": sorted(members),
+            }
+        )
+    return {
+        "schema": "build-wave/v1",
+        "waves": reshaped_waves,
+        "collisions": waves_json.get("collisions", []),
+    }
+
+
+def main(argv: list) -> int:
+    if len(argv) < 2 or not argv[1] or not os.path.isfile(argv[1]):
+        print("usage: build_wave.py <plan.md>", file=sys.stderr)
+        return 2
+
+    plan_file = argv[1]
+    stdout, code, stderr = _run_plan_waves(plan_file)
+    if code != 0:
+        # Propagate plan_waves.py's error output verbatim + exit code.
+        sys.stderr.write(stderr)
+        return code
+
+    try:
+        waves_json = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        print(f"build-wave: plan_waves.py emitted invalid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    reshaped = _reshape(waves_json)
+    # jq default pretty-print uses 2-space indent, sort keys, LF terminator.
+    print(json.dumps(reshaped, indent=2))
+
+    # Refuse a schedule that contains a same-wave file collision.
+    collisions = waves_json.get("collisions") or []
+    if collisions:
+        print(
+            "build-wave: same-wave file collision(s) — cannot build this "
+            "wave concurrently:",
+            file=sys.stderr,
+        )
+        for c in collisions:
+            slices = " + ".join(c.get("slices", []))
+            print(
+                f"  wave {c.get('wave')}: {slices} both touch {c.get('file')}",
+                file=sys.stderr,
+            )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))