phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/skills_bundle/codex-execute-phase/scripts/parent_tree_leakage_check.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# parent_tree_leakage_check.sh — detect when a teammate's filesystem edits
+# escaped its worktree into the parent checkout, or when EnterWorktree
+# silently fell back to in-place branch creation in the parent.
+#
+# Usage:
+#     parent_tree_leakage_check.sh <lane-id> <owned-globs-file> [<merge-target>]
+#
+#     <lane-id>            Informational only; echoed into stdout for
+#                          orchestrator logging.
+#     <owned-globs-file>   File with one glob pattern per line; these are
+#                          the lane's `Owned files` from the plan doc.
+#                          Passing /dev/null is valid (treat empty globs
+#                          as "nothing is owned" → any dirty file counts
+#                          as unrelated).
+#     <merge-target>       Optional. Branch the phase merges into (default
+#                          "main"). Used by the new PARENT_ON_WRONG_BRANCH
+#                          probe.
+#
+# Behavior: emits EXACTLY one token on stdout, exit 0 always.
+#
+#   CLEAN
+#     - Working tree has no uncommitted changes AND the parent is on the
+#       merge-target branch. No leakage.
+#
+#   LEAKAGE_DETECTED
+#     - Working tree has dirty files AND at least one matches the lane's
+#       owned globs. The teammate wrote into the parent checkout rather
+#       than the worktree; orchestrator should stash or abort before merge.
+#
+#   UNRELATED_DIRTY_TREE
+#     - Working tree has dirty files but NONE match the lane's owned
+#       globs. Probably other orchestrator-level changes; caller decides.
+#
+#   PARENT_ON_WRONG_BRANCH
+#     - Working tree is CLEAN but the parent checkout is on a branch
+#       OTHER than <merge-target>. Symptom of EnterWorktree silently
+#       falling back to in-place branch creation (a name collision is
+#       the typical cause). The lane's commit is usually fine — merge
+#       by SHA, then `git checkout <merge-target>` in the parent before
+#       post-merge worktree cleanup.
+#
+# Implementation notes:
+#   - Runs from the parent checkout (the cwd of the orchestrator's git
+#     context, not the lane's worktree).
+#   - `git status --porcelain` output: `XY <path>` where X/Y are status
+#     codes; we parse the path by stripping the first 3 chars.
+
+set -uo pipefail
+
+if [[ $# -lt 2 || $# -gt 3 ]]; then
+    echo "usage: parent_tree_leakage_check.sh <lane-id> <owned-globs-file> [<merge-target>]" >&2
+    exit 2
+fi
+
+lane_id="$1"
+globs_path="$2"
+merge_target="${3:-main}"
+
+# Load owned globs.
+globs=()
+if [[ -r "$globs_path" && "$globs_path" != "/dev/null" ]]; then
+    while IFS= read -r line; do
+        line="${line%%#*}"
+        line="$(echo -n "$line" | xargs || true)"
+        [[ -z "$line" ]] && continue
+        globs+=("$line")
+    done < "$globs_path"
+fi
+
+# Enumerate dirty paths from the parent checkout.
+dirty_paths=()
+while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    # Status code (first 2 chars) + a space, then the path. Renames use
+    # "R  old -> new"; we take the NEW path.
+    path="${line:3}"
+    if [[ "$path" == *" -> "* ]]; then
+        path="${path#* -> }"
+    fi
+    # Strip surrounding quotes git adds for paths with spaces.
+    path="${path#\"}"
+    path="${path%\"}"
+    dirty_paths+=("$path")
+done < <(git status --porcelain 2>/dev/null)
+
+if [[ ${#dirty_paths[@]} -eq 0 ]]; then
+    # Parent is clean — but is it on the right branch?
+    current_branch="$(git branch --show-current 2>/dev/null || true)"
+    if [[ -n "$current_branch" && "$current_branch" != "$merge_target" ]]; then
+        echo "parent_tree_leakage_check: $lane_id — parent checkout is on branch '$current_branch' (expected '$merge_target')" >&2
+        echo "PARENT_ON_WRONG_BRANCH"
+        exit 0
+    fi
+    echo "CLEAN"
+    exit 0
+fi
+
+# Test each dirty path against the lane's globs.
+is_owned() {
+    local path="$1"
+    local pat
+    for pat in "${globs[@]+"${globs[@]}"}"; do
+        # shellcheck disable=SC2053
+        if [[ "$path" == $pat ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+leakage=false
+for p in "${dirty_paths[@]}"; do
+    if is_owned "$p"; then
+        leakage=true
+        echo "parent_tree_leakage_check: $lane_id — dirty path $p matches owned globs" >&2
+    fi
+done
+
+if [[ "$leakage" == "true" ]]; then
+    echo "LEAKAGE_DETECTED"
+    exit 0
+fi
+echo "UNRELATED_DIRTY_TREE"
+exit 0

phase_loop_runtime/skills_bundle/codex-execute-phase/scripts/post_merge_import_smoke.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# post_merge_import_smoke.sh — verify post-merge Python-package imports.
+#
+# Usage:
+#     post_merge_import_smoke.sh <pkg.dotted.path> [<pkg.another> ...]
+#
+# For each package argument, runs `python -c "import <pkg>"` using the
+# repo-local .venv (falls back to plain `python` if .venv is missing).
+# Emits one line per package:
+#
+#     IMPORT_OK: <pkg>
+#     IMPORT_FAIL: <pkg> — <first-line-of-error>
+#
+# Exit code:
+#   0 — every package imports cleanly
+#   1 — at least one package failed to import
+#   2 — usage error
+#
+# Rationale: a lane that drops or renames a symbol re-exported by an
+# `__init__.py` breaks package load silently — the ImportError only
+# surfaces when some downstream code happens to trigger the import. A
+# post-merge import smoke on every `__init__.py` the lane touched catches
+# this in seconds, before the next wave builds on a broken base.
+#
+# Invocation pattern for the orchestrator (Step 7):
+#     packages="$(git diff --name-only HEAD~..HEAD \
+#         | grep '__init__\.py$' \
+#         | sed 's|/__init__\.py$||; s|/|.|g' \
+#         | sort -u)"
+#     [[ -n "$packages" ]] && bash <script> $packages
+
+set -uo pipefail
+
+if [[ $# -lt 1 ]]; then
+    echo "usage: post_merge_import_smoke.sh <pkg.dotted.path> [<pkg.another> ...]" >&2
+    exit 2
+fi
+
+# Prefer repo-local venv if present.
+python_bin="python"
+if [[ -x ".venv/bin/python" ]]; then
+    python_bin=".venv/bin/python"
+elif [[ -x "venv/bin/python" ]]; then
+    python_bin="venv/bin/python"
+fi
+
+any_fail=0
+for pkg in "$@"; do
+    # Run the import in a subshell; capture stderr.
+    err="$("$python_bin" -c "import ${pkg}" 2>&1 >/dev/null)"
+    rc=$?
+    if [[ $rc -eq 0 ]]; then
+        echo "IMPORT_OK: ${pkg}"
+    else
+        # First line of the error only.
+        first_line="$(echo "$err" | tail -n 1)"
+        echo "IMPORT_FAIL: ${pkg} — ${first_line}"
+        any_fail=1
+    fi
+done
+
+exit $any_fail

phase_loop_runtime/skills_bundle/codex-execute-phase/scripts/pre_merge_destructiveness_check.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# pre_merge_destructiveness_check.sh — classify a lane's merge before
+# performing it, to prevent stale-base destruction of peer-lane work.
+#
+# Usage:
+#     pre_merge_destructiveness_check.sh <lane-sha> <merge-target> <whitelist-path>
+#
+#     <lane-sha>          Commit SHA produced by the lane.
+#     <merge-target>      Branch the lane will be merged into (typically main).
+#     <whitelist-path>    File with one path per line listing destructive
+#                         changes the plan EXPECTS for this lane. Supports
+#                         shell-glob patterns. Use /dev/null if the lane
+#                         is purely additive.
+#
+# Behavior: emits EXACTLY one token on stdout, exit 0 always (verdict is
+# on stdout for the orchestrator to act on).
+#
+#   SAFE
+#     - The ancestor-diff deletion list is empty OR every deletion is
+#       explicitly whitelisted. Proceed with `git merge --no-ff`.
+#
+#   STALE_BASE_DETECTED
+#     - The lane's diff-against-target shows deletions of files that
+#       WEREN'T in the lane's ancestor; i.e. peer lanes merged additions
+#       between the lane's base and target, and `git merge --no-ff` would
+#       revert them. Orchestrator should salvage (cherry-pick the lane's
+#       owned paths) rather than retry.
+#
+#   CONFLICT
+#     - Some other destructive signature that doesn't match either of the
+#       above. Orchestrator should surface to the teammate for manual
+#       resolution.
+#
+# Rationale: Step 7's MANDATORY pre-merge check. A lane that committed
+# against a stale base can wipe peer-lane work on `--no-ff` merge; the
+# naive `git diff main..lane` can't distinguish that from a parallel-
+# branch false positive. Extracting the 3-part diff (naive + ancestor +
+# whitelist) into a script makes the verdict deterministic.
+
+set -uo pipefail
+
+if [[ $# -ne 3 ]]; then
+    echo "usage: pre_merge_destructiveness_check.sh <lane-sha> <merge-target> <whitelist-path>" >&2
+    exit 2
+fi
+
+sha="$1"
+target="$2"
+whitelist_path="$3"
+
+# Load whitelist patterns (one per line; '#' comments OK; blank lines skipped).
+whitelist=()
+if [[ -r "$whitelist_path" && "$whitelist_path" != "/dev/null" ]]; then
+    while IFS= read -r line; do
+        line="${line%%#*}"
+        line="${line//[[:space:]]/}"
+        [[ -z "$line" ]] && continue
+        whitelist+=("$line")
+    done < "$whitelist_path"
+fi
+
+# Primary: deletions in target..lane-sha (naïve diff).
+mapfile -t naive_deletions < <(
+    git diff --diff-filter=D --name-only "$target..$sha" 2>/dev/null
+)
+
+# Disambiguator: deletions in ancestor..lane-sha (what the lane actually
+# did, ignoring what target gained since).
+ancestor="$(git merge-base "$target" "$sha" 2>/dev/null)"
+mapfile -t ancestor_deletions < <(
+    [[ -n "$ancestor" ]] \
+        && git diff --diff-filter=D --name-only "$ancestor..$sha" 2>/dev/null \
+        || true
+)
+
+# Helper: test whether a path matches any whitelist glob.
+is_whitelisted() {
+    local path="$1"
+    local pat
+    for pat in "${whitelist[@]+"${whitelist[@]}"}"; do
+        # shellcheck disable=SC2053
+        if [[ "$path" == $pat ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Case 1: the lane itself did zero deletions (ancestor..lane is additive-only
+# OR all lane-side deletions are whitelisted). The naive deletion list may
+# still show peer-lane additions — which is the stale-base signature.
+lane_did_unwhitelisted_delete=false
+for d in "${ancestor_deletions[@]+"${ancestor_deletions[@]}"}"; do
+    [[ -z "$d" ]] && continue
+    if ! is_whitelisted "$d"; then
+        lane_did_unwhitelisted_delete=true
+        break
+    fi
+done
+
+# Compute naive-but-not-ancestor deletions (files target has that lane
+# never had -> peer lanes added them after lane branched off).
+declare -A ancestor_set=()
+for d in "${ancestor_deletions[@]+"${ancestor_deletions[@]}"}"; do
+    [[ -z "$d" ]] && continue
+    ancestor_set["$d"]=1
+done
+stale_base_deletions=()
+for d in "${naive_deletions[@]+"${naive_deletions[@]}"}"; do
+    [[ -z "$d" ]] && continue
+    if [[ -z "${ancestor_set[$d]+set}" ]]; then
+        stale_base_deletions+=("$d")
+    fi
+done
+
+if [[ "$lane_did_unwhitelisted_delete" == "false" && ${#stale_base_deletions[@]} -eq 0 ]]; then
+    echo "SAFE"
+    exit 0
+fi
+if [[ "$lane_did_unwhitelisted_delete" == "false" && ${#stale_base_deletions[@]} -gt 0 ]]; then
+    # Lane is additive but diff-against-target shows deletions from peer-lane
+    # additions — classic stale base.
+    echo "STALE_BASE_DETECTED"
+    exit 0
+fi
+echo "CONFLICT"
+exit 0

phase_loop_runtime/skills_bundle/codex-execute-phase/scripts/resolve_branch_from_sha.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# resolve_branch_from_sha.sh — map a commit SHA to exactly one local branch.
+#
+# Usage:
+#     resolve_branch_from_sha.sh <commit-sha>
+#
+# Behavior:
+#   - Lists local branches containing the SHA via `git branch --contains`.
+#   - Exit 0 with the branch name on stdout if exactly one local branch matches.
+#   - Exit 1 with a message on stderr if zero or multiple branches match.
+#
+# Rationale (from the claude-execute-phase SKILL):
+#   "Never trust a branch name; resolve by commit SHA from the teammate's
+#    reply envelope." This script enforces that rule mechanically so the
+#    LLM doesn't have to re-derive branch-discovery logic per phase.
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+    echo "usage: resolve_branch_from_sha.sh <commit-sha>" >&2
+    exit 2
+fi
+
+sha="$1"
+
+# Validate the SHA exists first; otherwise `git branch --contains` prints
+# a misleading error.
+if ! git cat-file -e "${sha}^{commit}" 2>/dev/null; then
+    echo "resolve_branch_from_sha: commit not found: $sha" >&2
+    exit 1
+fi
+
+# `--contains` yields lines like "  main" or "* feature/x"; strip the marker.
+mapfile -t candidates < <(
+    git branch --contains "$sha" --format '%(refname:short)' 2>/dev/null | sort -u
+)
+
+case "${#candidates[@]}" in
+    0)
+        echo "resolve_branch_from_sha: no local branch contains $sha" >&2
+        exit 1
+        ;;
+    1)
+        echo "${candidates[0]}"
+        exit 0
+        ;;
+    *)
+        echo "resolve_branch_from_sha: multiple local branches contain $sha: ${candidates[*]}" >&2
+        exit 1
+        ;;
+esac

phase_loop_runtime/skills_bundle/codex-execute-phase/scripts/state.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""
+state.py — JSON CRUD for claude-execute-phase's state file.
+
+Usage:
+    state.py read
+    state.py init <phase-id> <merge-target>
+    state.py set-lane <lane-id> <field>=<value> [<field>=<value> ...]
+    state.py transition <lane-id> <from-status> <to-status>
+    state.py set-gate <gate-id> <status>
+    state.py delete
+
+State file path (env-overridable, default is $PWD/.claude/claude-execute-phase-state.json):
+    STATE_FILE=/path/to/file state.py read
+
+Schema:
+    {
+      "phase_id":      "PHASE-1-repo-identity-default-branch-pinning",
+      "merge_target":  "main",
+      "started_at":    "2026-04-18T00:00:00Z",
+      "updated_at":    "2026-04-18T00:15:00Z",
+      "status":        "running",         # running | complete | halted
+      "lanes": {
+        "SL-1": {
+          "status":        "pending",      # pending | running | verify-ok | merged | failed
+          "commit_sha":    null,
+          "branch":        null,
+          "worktree_path": null,
+          "retries":       0,
+          "notes":         []
+        }
+      },
+      "gates": {
+        "IF-0-P1-1": { "status": "open" }  # open | closed
+      }
+    }
+
+Design notes:
+- `transition` is atomic — it fails if the current status doesn't match <from>.
+  This is the state-machine contract the orchestrator relies on to avoid
+  double-running a lane through a wave.
+- `set-lane` is a permissive write; use it to add commit_sha / branch /
+  worktree_path after dispatch-and-return; do NOT use it for status changes
+  (use `transition` for those).
+- All mutations update `updated_at`. `started_at` is set once by `init`.
+- The file is written atomically (tmp + rename) so concurrent readers never
+  see a truncated file.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+DEFAULT_STATE_PATH = ".claude/claude-execute-phase-state.json"
+LANE_STATUSES = {"pending", "running", "verify-ok", "merged", "failed"}
+GATE_STATUSES = {"open", "closed"}
+PHASE_STATUSES = {"running", "complete", "halted"}
+
+
+def _state_path() -> Path:
+    return Path(os.environ.get("STATE_FILE", DEFAULT_STATE_PATH))
+
+
+def _utc_now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _load() -> Dict[str, Any]:
+    p = _state_path()
+    if not p.exists():
+        _fail(f"state file not found: {p}")
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception as exc:
+        _fail(f"state file unreadable: {exc}")
+    return {}  # unreachable
+
+
+def _save(state: Dict[str, Any]) -> None:
+    state["updated_at"] = _utc_now()
+    p = _state_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(p.suffix + ".tmp")
+    tmp.write_text(json.dumps(state, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    tmp.replace(p)
+
+
+def _fail(msg: str, exit_code: int = 2) -> None:
+    print(f"state.py: {msg}", file=sys.stderr)
+    sys.exit(exit_code)
+
+
+def _coerce_value(raw: str) -> Any:
+    """Convert CLI string -> JSON value. Supports bare null/true/false/integer/float;
+    otherwise treats as string."""
+    if raw == "null":
+        return None
+    if raw == "true":
+        return True
+    if raw == "false":
+        return False
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    return raw
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+
+def cmd_init(phase_id: str, merge_target: str) -> int:
+    if _state_path().exists():
+        _fail(f"state file already exists at {_state_path()} — use `delete` first or `transition`")
+    state = {
+        "phase_id": phase_id,
+        "merge_target": merge_target,
+        "started_at": _utc_now(),
+        "updated_at": _utc_now(),
+        "status": "running",
+        "lanes": {},
+        "gates": {},
+    }
+    _save(state)
+    print(f"state.py: initialized {_state_path()} for {phase_id}")
+    return 0
+
+
+def cmd_read() -> int:
+    state = _load()
+    print(json.dumps(state, indent=2, sort_keys=False))
+    return 0
+
+
+def cmd_set_lane(lane_id: str, assignments: List[str]) -> int:
+    state = _load()
+    lane = state["lanes"].setdefault(
+        lane_id,
+        {
+            "status": "pending",
+            "commit_sha": None,
+            "branch": None,
+            "worktree_path": None,
+            "retries": 0,
+            "notes": [],
+        },
+    )
+    for assignment in assignments:
+        if "=" not in assignment:
+            _fail(f"expected `<field>=<value>`, got {assignment!r}")
+        key, _, raw = assignment.partition("=")
+        key = key.strip()
+        value: Any = _coerce_value(raw.strip())
+        if key == "status":
+            _fail("use `transition` to change status, not `set-lane`")
+        if key == "notes" and isinstance(value, str):
+            # Append to notes list instead of replacing.
+            lane.setdefault("notes", []).append(value)
+        else:
+            lane[key] = value
+    _save(state)
+    return 0
+
+
+def cmd_transition(lane_id: str, frm: str, to: str) -> int:
+    if frm not in LANE_STATUSES:
+        _fail(f"from-status {frm!r} not in {sorted(LANE_STATUSES)}")
+    if to not in LANE_STATUSES:
+        _fail(f"to-status {to!r} not in {sorted(LANE_STATUSES)}")
+    state = _load()
+    lane = state["lanes"].get(lane_id)
+    if lane is None:
+        # Creating on first transition is fine if `from` is "pending".
+        if frm != "pending":
+            _fail(f"lane {lane_id!r} not found and from-status is not `pending`")
+        lane = {
+            "status": "pending",
+            "commit_sha": None,
+            "branch": None,
+            "worktree_path": None,
+            "retries": 0,
+            "notes": [],
+        }
+        state["lanes"][lane_id] = lane
+    if lane["status"] != frm:
+        _fail(
+            f"{lane_id} is in status {lane['status']!r}, not {frm!r}; "
+            f"refusing transition to {to!r}",
+            exit_code=1,
+        )
+    lane["status"] = to
+    _save(state)
+    return 0
+
+
+def cmd_set_gate(gate_id: str, status: str) -> int:
+    if status not in GATE_STATUSES:
+        _fail(f"gate status {status!r} not in {sorted(GATE_STATUSES)}")
+    state = _load()
+    state["gates"][gate_id] = {"status": status}
+    _save(state)
+    return 0
+
+
+def cmd_set_phase(status: str) -> int:
+    if status not in PHASE_STATUSES:
+        _fail(f"phase status {status!r} not in {sorted(PHASE_STATUSES)}")
+    state = _load()
+    state["status"] = status
+    _save(state)
+    return 0
+
+
+def cmd_delete() -> int:
+    p = _state_path()
+    if not p.exists():
+        return 0  # idempotent
+    p.unlink()
+    print(f"state.py: deleted {p}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+
+def main(argv: List[str]) -> int:
+    if len(argv) < 2:
+        _fail("usage: state.py <read|init|set-lane|transition|set-gate|set-phase|delete> [args]")
+    cmd = argv[1]
+    rest = argv[2:]
+    try:
+        if cmd == "read":
+            return cmd_read()
+        if cmd == "init":
+            if len(rest) != 2:
+                _fail("usage: state.py init <phase-id> <merge-target>")
+            return cmd_init(rest[0], rest[1])
+        if cmd == "set-lane":
+            if len(rest) < 2:
+                _fail("usage: state.py set-lane <lane-id> <field>=<value> [<field>=<value> ...]")
+            return cmd_set_lane(rest[0], rest[1:])
+        if cmd == "transition":
+            if len(rest) != 3:
+                _fail("usage: state.py transition <lane-id> <from-status> <to-status>")
+            return cmd_transition(rest[0], rest[1], rest[2])
+        if cmd == "set-gate":
+            if len(rest) != 2:
+                _fail("usage: state.py set-gate <gate-id> <open|closed>")
+            return cmd_set_gate(rest[0], rest[1])
+        if cmd == "set-phase":
+            if len(rest) != 1:
+                _fail("usage: state.py set-phase <running|complete|halted>")
+            return cmd_set_phase(rest[0])
+        if cmd == "delete":
+            return cmd_delete()
+        _fail(f"unknown subcommand: {cmd!r}")
+    except SystemExit:
+        raise
+    except Exception as exc:
+        _fail(f"unexpected error: {exc!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))