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

phase_loop_runtime/verification_evidence_validator.py

@@ -0,0 +1,75 @@
+"""Verification-evidence closeout validator (rigor-v1 P5).
+
+Closes the generic-phase hole: today only `RG` phases or plans opting in via
+`IF-0-RG-1`/`--verification-log` require an evidence artifact, so any other phase
+can self-report `verification_status=passed` with nothing backing it. This
+validator raises a finding for those generic phases too.
+
+Autonomy-first: ``block``-severity, so under the default ``PHASE_LOOP_REVIEW=warn``
+it is recorded and the loop continues; it blocks only on opt-in. The agent
+self-satisfies by attaching a verification artifact or recording a typed opt-out
+reason (``verification_evidence_opt_out``) — no human required.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping
+
+from .closeout_validators import CloseoutContext, ReviewFinding, register_closeout_validator
+from .models import VERIFICATION_EVIDENCE_OPT_OUT_REASONS
+
+
+def _has_verification_artifact(terminal: Mapping) -> bool:
+    """Detect a verification artifact in the same places the upstream gate reads
+    (`closeout._verification_artifact_path`): the nested `artifact_paths` map, or
+    the top-level convenience key the skills tell executors to write."""
+    if terminal.get("verification_artifact_path"):
+        return True
+    artifact_paths = terminal.get("artifact_paths")
+    if isinstance(artifact_paths, Mapping):
+        return bool(
+            artifact_paths.get("verification")
+            or artifact_paths.get("verification_artifact")
+            or artifact_paths.get("verification_log")
+            or artifact_paths.get("root")
+        )
+    return False
+
+
+def _legacy_evidence_gate_owns(phase_alias: str, plan_path: str) -> bool:
+    """True when the existing verification-evidence gate already governs this phase
+    (RG, or a plan opting into IF-0-RG-1/--verification-log). Those are handled
+    upstream in build_phase_loop_closeout, so this validator stays out of them."""
+    if phase_alias.upper() == "RG":
+        return True
+    try:
+        text = Path(plan_path).read_text(encoding="utf-8")
+    except OSError:
+        return False
+    return "IF-0-RG-1" in text or "--verification-log" in text
+
+
+@register_closeout_validator
+def verification_evidence_validator(ctx: CloseoutContext) -> list[ReviewFinding]:
+    reported = str(ctx.terminal.get("verification_status") or ctx.automation.get("verification_status") or "")
+    if reported != "passed":
+        return []
+    if _legacy_evidence_gate_owns(ctx.phase_alias, ctx.plan_path):
+        return []  # owned by the upstream evidence gate
+    if _has_verification_artifact(ctx.terminal):
+        return []  # evidence attached
+    opt_out = str(ctx.terminal.get("verification_evidence_opt_out") or "").strip()
+    if opt_out in VERIFICATION_EVIDENCE_OPT_OUT_REASONS:
+        return []  # declined with a typed reason
+    return [
+        ReviewFinding(
+            code="verification_evidence_missing_generic",
+            reason=(
+                "reported verification_status=passed with no verification_artifact_path; "
+                "attach the runner verification log or record a verification_evidence_opt_out "
+                f"reason ({', '.join(VERIFICATION_EVIDENCE_OPT_OUT_REASONS)})"
+            ),
+            severity="block",
+            blocker_class="review_gate_block",
+        )
+    ]

phase_loop_runtime/visual_evidence_validator.py

@@ -0,0 +1,36 @@
+"""Visual-evidence closeout validator (rigor-v1 P6).
+
+When a phase changes UI/visual surfaces but attaches no visual evidence
+(screenshot path + observed outcome), raise a finding. Autonomy-first:
+``block``-severity, so under the default ``PHASE_LOOP_REVIEW=warn`` it is
+recorded and the loop continues; it blocks only on opt-in. The agent
+self-satisfies by capturing a screenshot (claude-in-chrome / Playwright-via-PMCP)
+and recording its path — no human eyeball is required to pass.
+
+The executor records ``visual_evidence_path`` (and optionally
+``visual_evidence_observed``) in the terminal summary.
+"""
+from __future__ import annotations
+
+from .closeout_validators import CloseoutContext, ReviewFinding, register_closeout_validator
+from .models import ui_change_detected
+
+
+@register_closeout_validator
+def visual_evidence_validator(ctx: CloseoutContext) -> list[ReviewFinding]:
+    if not ui_change_detected(ctx.changed_paths):
+        return []
+    if ctx.terminal.get("visual_evidence_path") or ctx.terminal.get("visual_evidence"):
+        return []  # evidence attached
+    return [
+        ReviewFinding(
+            code="visual_evidence_missing",
+            reason=(
+                "changed a UI/visual surface (*.tsx/jsx/vue/svelte/css or components/**) "
+                "but attached no visual_evidence_path; capture a screenshot "
+                "(claude-in-chrome or Playwright-via-PMCP) and record its path"
+            ),
+            severity="block",
+            blocker_class="review_gate_block",
+        )
+    ]

phase_loop_runtime/worker_pool.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from pathlib import Path
+from time import time
+from typing import Any
+
+from .launcher import LaunchResult, LaunchSpec, launch_with_spec
+from .observability import write_terminal_summary
+from .runtime_paths import phase_loop_dir
+
+
+@dataclass(frozen=True)
+class PhaseWorkerJob:
+    phase: str
+    spec: LaunchSpec
+    log_path: Path | None = None
+    heartbeat_path: Path | None = None
+    dry_run: bool = False
+    stream_output: bool = False
+    heartbeat_interval_seconds: float = 30.0
+    quiet_warning_seconds: float = 300.0
+    quiet_blocker_seconds: float = 900.0
+
+
+@dataclass(frozen=True)
+class PhaseWorkerResult:
+    phase: str
+    result: LaunchResult
+    summary_path: Path
+    terminal_summary: dict[str, object]
+
+
+def worker_summary_path(repo: Path, roadmap: Path, phase: str) -> Path:
+    return phase_loop_dir(repo) / _roadmap_slug(repo, roadmap) / "workers" / f"{phase}.summary.json"
+
+
+def write_worker_summary(repo: Path, roadmap: Path, phase: str, summary: dict[str, Any]) -> Path:
+    path = worker_summary_path(repo, roadmap, phase)
+    write_terminal_summary(path, {"phase": phase, **summary})
+    return path
+
+
+def read_worker_summary(
+    repo: Path,
+    roadmap: Path,
+    phase: str,
+    *,
+    stale_after_seconds: float = 1.0,
+) -> dict[str, Any]:
+    path = worker_summary_path(repo, roadmap, phase)
+    if not path.exists():
+        return {"status": "missing", "path": str(path)}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        stat = path.stat()
+        age_seconds = max(0.0, time() - stat.st_mtime)
+        status = "torn" if age_seconds >= stale_after_seconds and stat.st_size > 0 else "pending"
+        return {
+            "status": status,
+            "path": str(path),
+            "size": stat.st_size,
+            "age_seconds": age_seconds,
+            "error": str(exc),
+        }
+    if not isinstance(data, dict):
+        return {"status": "malformed", "path": str(path), "summary": data}
+    return {"status": "ok", "path": str(path), "summary": data}
+
+
+def run_phase_worker_pool(
+    repo: Path,
+    roadmap: Path,
+    jobs: tuple[PhaseWorkerJob, ...] | list[PhaseWorkerJob],
+    *,
+    max_workers: int | None = None,
+) -> tuple[PhaseWorkerResult, ...]:
+    if not jobs:
+        return ()
+    worker_count = max_workers or min(len(jobs), os.cpu_count() or 1)
+    worker_count = max(1, min(worker_count, len(jobs)))
+    by_phase = {job.phase: index for index, job in enumerate(jobs)}
+    results: list[PhaseWorkerResult] = []
+    with ThreadPoolExecutor(max_workers=worker_count) as executor:
+        futures = {executor.submit(_run_one, repo, roadmap, job): job for job in jobs}
+        for future in as_completed(futures):
+            results.append(future.result())
+    return tuple(sorted(results, key=lambda item: by_phase[item.phase]))
+
+
+def _run_one(repo: Path, roadmap: Path, job: PhaseWorkerJob) -> PhaseWorkerResult:
+    result = launch_with_spec(
+        job.spec,
+        dry_run=job.dry_run,
+        log_path=job.log_path,
+        heartbeat_path=job.heartbeat_path,
+        stream_output=job.stream_output,
+        heartbeat_interval_seconds=job.heartbeat_interval_seconds,
+        quiet_warning_seconds=job.quiet_warning_seconds,
+        quiet_blocker_seconds=job.quiet_blocker_seconds,
+    )
+    summary = {
+        "phase": job.phase,
+        "terminal_status": "blocked" if result.failed else "complete",
+        "verification_status": "blocked" if result.failed else "passed",
+        "returncode": result.returncode,
+        "executor": result.executor,
+        "log_path": result.log_path,
+    }
+    path = write_worker_summary(repo, roadmap, job.phase, summary)
+    return PhaseWorkerResult(phase=job.phase, result=result, summary_path=path, terminal_summary=summary)
+
+
+def _roadmap_slug(repo: Path, roadmap: Path) -> str:
+    try:
+        value = str(roadmap.relative_to(repo))
+    except ValueError:
+        value = roadmap.name
+    return "".join(char if char.isalnum() or char in "._-" else "-" for char in value).strip("-") or "roadmap"

phase_loop_runtime/worktree_index.py

@@ -0,0 +1,270 @@
+"""Git-derived worktree freshness index (CS-0.10a).
+
+Answers "where is the freshest working copy of a path, and who's touching it" by
+reading `git worktree list` and diffing each worktree's branch against the base
+ref (default: `origin/<default-branch>`, falling back to `origin/main`). Purely
+git-derived and READ-ONLY: it never writes repo state, never mutates the working
+tree, and holds no persistent index of its own — every call re-derives the answer
+from `git` at invocation time, so it can't drift from reality the way a cached
+index could.
+
+If a repo has no worktrees beyond the primary one, or none of them touch the
+queried path, the answer collapses to the `origin/main` baseline entry alone —
+there is nothing else to report.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class WorktreeRef:
+    """One entry from `git worktree list --porcelain`."""
+
+    path: str
+    branch: str | None
+    head_sha: str | None
+    bare: bool = False
+    detached: bool = False
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Holder:
+    """A working copy (a worktree, or the `origin/main` baseline) that carries a
+    commit touching the queried path."""
+
+    worktree: str
+    branch: str
+    last_commit_sha: str
+    last_commit_time: str
+
+    def to_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class PathFreshness:
+    path: str
+    holders: tuple[Holder, ...]
+    main_behind: bool
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "holders": [holder.to_json() for holder in self.holders],
+            "main_behind": self.main_behind,
+        }
+
+
+@dataclass(frozen=True)
+class WorktreeIndexReport:
+    base_ref: str
+    worktrees: tuple[WorktreeRef, ...]
+    paths: tuple[PathFreshness, ...]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "base_ref": self.base_ref,
+            "worktrees": [wt.to_json() for wt in self.worktrees],
+            "paths": [pf.to_json() for pf in self.paths],
+        }
+
+
+def _git(repo: Path, *args: str) -> str | None:
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=10,
+        )
+    except Exception:
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None
+
+
+def _is_ancestor(repo: Path, sha: str, ref: str) -> bool:
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), "merge-base", "--is-ancestor", sha, ref],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except Exception:
+        return False
+    return completed.returncode == 0
+
+
+def default_base_ref(repo: Path) -> str:
+    """`origin/<default-branch>` from the remote's HEAD symref, or `origin/main`."""
+    default_remote = _git(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")
+    return default_remote or "origin/main"
+
+
+def list_worktrees(repo: Path) -> tuple[WorktreeRef, ...]:
+    """Parse `git worktree list --porcelain` into `WorktreeRef` entries."""
+    output = _git(repo, "worktree", "list", "--porcelain")
+    if not output:
+        return ()
+
+    entries: list[WorktreeRef] = []
+    path: str | None = None
+    head: str | None = None
+    branch: str | None = None
+    bare = False
+    detached = False
+
+    def flush() -> None:
+        nonlocal path, head, branch, bare, detached
+        if path is not None:
+            entries.append(WorktreeRef(path=path, branch=branch, head_sha=head, bare=bare, detached=detached))
+        path, head, branch, bare, detached = None, None, None, False, False
+
+    for line in output.splitlines():
+        if not line.strip():
+            flush()
+        elif line.startswith("worktree "):
+            flush()
+            path = line[len("worktree "):].strip()
+        elif line.startswith("HEAD "):
+            head = line[len("HEAD "):].strip()
+        elif line.startswith("branch "):
+            branch = line[len("branch "):].strip().removeprefix("refs/heads/")
+        elif line == "bare":
+            bare = True
+        elif line == "detached":
+            detached = True
+    flush()
+    return tuple(entries)
+
+
+def branch_touched_paths(repo: Path, branch: str, base_ref: str) -> tuple[str, ...]:
+    """Repo-relative paths `branch` touches relative to `base_ref` (`git diff --name-only`)."""
+    output = _git(repo, "diff", f"{base_ref}...{branch}", "--name-only")
+    if not output:
+        return ()
+    return tuple(line.strip() for line in output.splitlines() if line.strip())
+
+
+def _last_commit(repo: Path, rev: str, path: str) -> tuple[str, str] | None:
+    output = _git(repo, "log", "-1", "--format=%H\x1f%cI", rev, "--", path)
+    if not output:
+        return None
+    parts = output.split("\x1f")
+    if len(parts) != 2:
+        return None
+    sha, when = parts
+    return sha, when
+
+
+def _path_freshness(
+    repo: Path,
+    path: str,
+    base_ref: str,
+    touched_by_worktree: dict[WorktreeRef, tuple[str, ...]],
+) -> PathFreshness:
+    holders: list[Holder] = []
+
+    baseline = _last_commit(repo, base_ref, path)
+    if baseline is not None:
+        sha, when = baseline
+        holders.append(Holder(worktree="origin/main", branch=base_ref, last_commit_sha=sha, last_commit_time=when))
+
+    main_behind = False
+    for worktree, touched in touched_by_worktree.items():
+        if path not in touched:
+            continue
+        commit = _last_commit(repo, worktree.branch or worktree.head_sha or "HEAD", path)
+        if commit is None:
+            continue
+        sha, when = commit
+        holders.append(
+            Holder(worktree=worktree.path, branch=worktree.branch or "detached", last_commit_sha=sha, last_commit_time=when)
+        )
+        if not _is_ancestor(repo, sha, base_ref):
+            main_behind = True
+
+    return PathFreshness(path=path, holders=tuple(holders), main_behind=main_behind)
+
+
+def build_index(repo: Path, *, base_ref: str | None = None, path: str | None = None) -> WorktreeIndexReport:
+    """Build the freshness index. `path=None` reports every path any active
+    worktree touches relative to `base_ref`; a repo with no diverging worktrees
+    yields an empty `paths` tuple — the answer is `origin/main`."""
+    resolved_base = base_ref or default_base_ref(repo)
+    worktrees = list_worktrees(repo)
+
+    touched_by_worktree: dict[WorktreeRef, tuple[str, ...]] = {}
+    for worktree in worktrees:
+        if worktree.bare or not worktree.branch:
+            continue
+        touched_by_worktree[worktree] = branch_touched_paths(repo, worktree.branch, resolved_base)
+
+    if path is not None:
+        candidate_paths: tuple[str, ...] = (path,)
+    else:
+        seen: dict[str, None] = {}
+        for touched in touched_by_worktree.values():
+            for touched_path in touched:
+                seen.setdefault(touched_path, None)
+        candidate_paths = tuple(sorted(seen))
+
+    paths = tuple(_path_freshness(repo, p, resolved_base, touched_by_worktree) for p in candidate_paths)
+    return WorktreeIndexReport(base_ref=resolved_base, worktrees=worktrees, paths=paths)
+
+
+def render_human(report: WorktreeIndexReport) -> str:
+    lines = [f"base_ref: {report.base_ref}", f"worktrees ({len(report.worktrees)}):"]
+    for worktree in report.worktrees:
+        tag = " [detached]" if worktree.detached else ""
+        lines.append(f"  {worktree.path}  branch={worktree.branch or '-'}{tag}  head={worktree.head_sha or '-'}")
+
+    if not report.paths:
+        lines.append("")
+        lines.append("no divergent paths relative to base_ref — origin/main is the answer")
+        return "\n".join(lines)
+
+    lines.append("")
+    for path_freshness in report.paths:
+        behind = "  [main behind]" if path_freshness.main_behind else ""
+        lines.append(f"{path_freshness.path}{behind}")
+        if not path_freshness.holders:
+            lines.append("    (no holders)")
+            continue
+        for holder in path_freshness.holders:
+            lines.append(
+                f"    {holder.branch:<30} {holder.worktree}  {holder.last_commit_sha[:12]}  {holder.last_commit_time}"
+            )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(prog="phase-loop worktree-index")
+    parser.add_argument("--repo", default=".", help="Repository root (default: cwd).")
+    parser.add_argument("--path", help="Report freshness holders for a single repo-relative path.")
+    parser.add_argument("--base", help="Diff base ref (default: origin/<default-branch>, falling back to origin/main).")
+    parser.add_argument("--json", action="store_true", help="Emit the report as JSON.")
+    # tolerate the leading 'worktree-index' token when dispatched from the main CLI
+    args = parser.parse_args([a for a in (argv or []) if a != "worktree-index"])
+
+    report = build_index(Path(args.repo), base_ref=args.base, path=args.path)
+    if args.json:
+        print(json.dumps(report.to_json(), indent=2))
+    else:
+        print(render_human(report))
+    return 0