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

phase_loop_runtime/skills_bundle/opencode-execute-phase/scripts/cleanup_lane_worktrees.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# cleanup_lane_worktrees.sh — remove lane worktrees and their auto-named
+# branches after a phase merges.
+#
+# Usage:
+#     cleanup_lane_worktrees.sh <branch-pattern>
+#
+#     <branch-pattern>    Glob applied to each worktree's branch name (the
+#                         short name, not refs/heads/…). Defaults to
+#                         'worktree-*' so the common case works with no arg.
+#
+# Behavior:
+#   - Enumerates every worktree via `git worktree list --porcelain`.
+#   - Skips the orchestrator's own worktree (identified by matching the
+#     `git rev-parse --show-toplevel` of the current cwd).
+#   - For each remaining worktree whose branch matches <branch-pattern>:
+#       * `git worktree remove --force <path>`
+#       * If the branch also matches 'worktree-*' or 'phase/*/sl-*',
+#         `git branch -D <branch>` (salvage footgun: -D, not -d).
+#   - Never blocks the phase: exit 0 even on individual cleanup failures;
+#     each failure is logged to stderr.
+#
+# Rationale: Step 7 post-merge cleanup. Keeps human-named branches intact
+# (skills/*, feature/*, fix/*) even when accidentally matched by glob.
+
+set -uo pipefail
+
+pattern="${1:-worktree-*}"
+
+# Resolve orchestrator's anchored worktree so we don't try to delete it.
+orch_root=""
+if orch_root="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+    :
+fi
+
+removed=0
+skipped=0
+
+# Parse `git worktree list --porcelain`. Each record is separated by a blank line:
+#     worktree <path>
+#     HEAD <sha>
+#     branch refs/heads/<name>
+while IFS= read -r block; do
+    # `git worktree list --porcelain` actually yields one line per key; we
+    # collapse them back into records here.
+    [[ -z "$block" ]] && continue
+    key="${block%% *}"
+    value="${block#* }"
+    case "$key" in
+        worktree)
+            wt_path="$value"
+            wt_branch=""
+            ;;
+        branch)
+            # value looks like 'refs/heads/worktree-sl-1'
+            wt_branch="${value#refs/heads/}"
+            ;;
+        HEAD) ;;   # ignore
+        detached) wt_branch="" ;;
+    esac
+    # When we hit a new `worktree` line, the previous record is complete —
+    # but the block-mode loop above feeds us line-by-line. We process each
+    # line and finalize when we hit a record boundary below.
+done < <(git worktree list --porcelain)
+
+# Process each worktree block (re-read cleanly; the above was an artifact).
+while IFS= read -r path; do
+    [[ -z "$path" ]] && continue
+    # Skip orchestrator's anchor.
+    if [[ "$path" == "$orch_root" ]]; then
+        skipped=$((skipped + 1))
+        continue
+    fi
+    # Resolve this worktree's branch.
+    branch="$(git -C "$path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
+    if [[ -z "$branch" || "$branch" == "HEAD" ]]; then
+        # Detached HEAD worktree — skip.
+        skipped=$((skipped + 1))
+        continue
+    fi
+    # Apply the branch pattern.
+    # shellcheck disable=SC2053
+    if [[ "$branch" != $pattern ]]; then
+        skipped=$((skipped + 1))
+        continue
+    fi
+    # Remove the worktree.
+    if git worktree remove --force "$path" 2>/dev/null; then
+        removed=$((removed + 1))
+    else
+        echo "cleanup_lane_worktrees: failed to remove worktree $path (branch=$branch)" >&2
+        continue
+    fi
+    # Delete the branch only if it's an auto-named pattern.
+    if [[ "$branch" == worktree-* || "$branch" == phase/*/sl-* ]]; then
+        if ! git branch -D "$branch" 2>/dev/null; then
+            echo "cleanup_lane_worktrees: failed to delete branch $branch" >&2
+        fi
+    fi
+done < <(git worktree list --porcelain | awk '$1 == "worktree" { print $2 }')
+
+echo "cleanup_lane_worktrees: removed $removed, skipped $skipped"
+exit 0

phase_loop_runtime/skills_bundle/opencode-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/opencode-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/opencode-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/opencode-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