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

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# verify_harness.sh — pre-flight capability check for claude-execute-phase.
+#
+# Usage:
+#     verify_harness.sh [merge-target]
+#
+#     merge-target    Defaults to 'main'.
+#
+# Checks (all run; exit code reflects aggregate — non-zero if any FAIL):
+#   (1) `git` + `git worktree` available
+#   (2) Running inside a git work tree (`rev-parse --show-toplevel` succeeds)
+#   (3) Merge target branch exists locally
+#   (4) Working tree is clean (no uncommitted changes)
+#   (5) `.gitignore` mentions worktree paths — WARN only
+#
+# Does NOT exercise EnterWorktree itself — that's a Claude tool, not a CLI.
+# The SKILL's Step 2 tells the LLM to follow this script with a throwaway-
+# teammate probe that calls EnterWorktree and reports whether the tool is
+# available in the teammate's registry.
+
+set -uo pipefail
+
+target="${1:-main}"
+
+errors=0
+warnings=0
+
+pass() { echo "verify_harness: PASS — $*"; }
+warn() { echo "verify_harness: WARN — $*" >&2; warnings=$((warnings + 1)); }
+fail() { echo "verify_harness: FAIL — $*" >&2; errors=$((errors + 1)); }
+
+# (1) git + worktree subcommand
+if ! command -v git >/dev/null 2>&1; then
+    fail "(1) git not found on PATH"
+elif ! git worktree list >/dev/null 2>&1; then
+    fail "(1) 'git worktree' subcommand unavailable"
+else
+    pass "(1) git + git-worktree available"
+fi
+
+# (2) inside a git work tree
+toplevel=""
+if toplevel="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+    pass "(2) inside git work tree: $toplevel"
+else
+    fail "(2) not inside a git work tree"
+fi
+
+# (3) merge target branch exists locally
+if git show-ref --verify --quiet "refs/heads/$target"; then
+    pass "(3) merge target '$target' exists locally"
+else
+    fail "(3) merge target '$target' does not exist locally (try: git fetch origin $target:$target)"
+fi
+
+# (4) working tree clean (allowlist excludes orchestrator-owned paths)
+#
+# Allowlist: paths that may appear in `git status --porcelain` during normal
+# phase execution without blocking dispatch:
+#   `?? .claude/worktrees/`    — untracked dir holding live lane worktrees
+#   `?? .claude/claude-execute-phase-state.json` — orchestrator state file
+#
+# Everything else (including gitignore-exempted `.index_metadata.json`, any
+# tracked-file modification, any other untracked file) must be committed,
+# stashed, or explicitly resolved via AskUserQuestion BEFORE dispatch —
+# no orchestrator-side rationalization.
+dirty_lines="$(git status --porcelain 2>/dev/null | \
+    grep -vE '^\?\? \.claude/worktrees/?$|^\?\? \.claude/claude-execute-phase-state\.json$' || true)"
+dirty_count=0
+if [[ -n "$dirty_lines" ]]; then
+    dirty_count=$(echo "$dirty_lines" | wc -l)
+fi
+if [[ "$dirty_count" -eq 0 ]]; then
+    pass "(4) working tree clean (or only allowlisted orchestrator paths dirty)"
+else
+    fail "(4) working tree has $dirty_count non-allowlisted uncommitted change(s); commit, stash, or abort before /claude-execute-phase. Offending paths:"
+    echo "$dirty_lines" | sed 's/^/verify_harness:     /' >&2
+fi
+
+# (5) .gitignore covers worktree paths — WARN only, not a hard-fail.
+gitignore="$toplevel/.gitignore"
+if [[ -f "$gitignore" ]]; then
+    if grep -qE '^(\.worktrees/?|\.claude/worktrees/?)' "$gitignore"; then
+        pass "(5) .gitignore covers worktree paths"
+    else
+        warn "(5) .gitignore does not list '.worktrees/' or '.claude/worktrees/'; claude-execute-phase will append on first run"
+    fi
+else
+    warn "(5) no .gitignore at $gitignore"
+fi
+
+echo "verify_harness: summary — $errors error(s), $warnings warning(s)"
+if [[ "$errors" -gt 0 ]]; then
+    exit 1
+fi
+exit 0

phase_loop_runtime/skills_bundle/codex-phase-loop/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/codex-phase-loop/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: codex-phase-loop
+description: "Harness TUI bridge for the repo-local <harness>-phase-loop runner. Use when the user wants phase-loop status, resume, bounded run, dry-run, or skill-maintenance from inside Harness."
+---
+
+# Harness Phase Loop
+
+Thin TUI bridge for the `<harness>-phase-loop` alias of the neutral `phase-loop`
+runner. This skill delegates to the stable `phase-loop` runtime boundary and
+follows the public contract defined in `docs/phase-loop/runtime-boundary.md`.
+This skill does not reimplement phase selection, reconciliation, handoff
+parsing, model policy, event writing, or execution logic.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Use the installed repo command: `<harness>-phase-loop`. Non-Harness
+  control planes should use the neutral `<harness>-config/bin/phase-loop` command.
+- Prefer the outside-TUI runner for full-roadmap execution; this TUI bridge keeps interactive `run` calls bounded and operator-driven.
+- Preserve manual TUI use of `<harness>-phase-roadmap-builder`, `<harness>-plan-phase`, and `<harness>-execute-phase`; this bridge is optional operator convenience.
+- Do not edit OpenCode skills, broaden operator docs, create cloud resources, retrieve secrets, commit, push, merge, or discard unrelated work.
+- Before reporting a human-required access blocker, inspect repo-local docs/config and safe metadata from available CLIs named in `<harness>-config/shared/runtime-state.md`. Never print secret values.
+- If the CLI is missing or its commands differ from this skill, stop and return to the RUNNER phase instead of guessing behavior.
+
+## Inputs
+
+- `handoff`: print the canonical TUI recovery handoff.
+- `status`: report reconciled or current loop state.
+- `monitor`: observe state/heartbeat/terminal summaries without launching phases.
+- `resume`: reconcile durable state and write the current snapshot.
+- `run`: execute a bounded loop run. Always pass `--max-phases <N>`; default to `1` when the user does not specify a bound.
+- `dry-run`: show the commands the runner would launch without executing them.
+- `maintain-skills`: delegate skill-maintenance workflow selection to the runner. Planner-only is the default.
+- `sync-skills`: audit or repair the installed `*-phase-loop` bridge skills used for manual TUI reentry.
+
+Optional flags may be passed through when requested: `--repo`, `--roadmap`, `--phase`, `--model-profile`, `--model`, `--effort`, `--json`, `--observe`, `--no-observe`, `--stream-output`, `--heartbeat-interval-seconds`, `--quiet-warning-seconds`, `--quiet-blocker-seconds`, `--no-heartbeat`, `--closeout-mode`, `--bypass-approvals`, `--poll-seconds`, `--timeout-seconds`, `--notify-command`, `--notify-on`, `--once`, `--min-reflections`, `--apply-skill-edits`, `--allow-skill`, and `--improvement-plan`.
+
+## Preflight
+
+1. Resolve the repo root and run `git status --short`.
+2. Confirm `<harness>-phase-loop --help` lists `status`, `resume`, `run`, `dry-run`, and `maintain-skills`.
+3. For commands that need a roadmap, let the CLI discover it unless the user supplied `--roadmap`; do not reimplement roadmap or phase selection in the skill text.
+4. If unrelated dirty work overlaps files the runner would modify, report `human_required=true` with `blocker_class=dirty_worktree_conflict` instead of continuing.
+5. **Branch-governance preflight (issue #83).** In pipeline-mode with branchgov on (the default), a dispatch switches to `consiliency/pipeline/<v>` cut from `origin/main`. If the roadmap is committed only on the operator's own branch (unpushed / ahead of `origin/main`), the runtime guard refuses cleanly with a `branch_sync_conflict` blocker (`human_required=true`) rather than crashing — push the roadmap to the base, or pass `--allow-branchgov` to switch anyway (it then still fails cleanly if the roadmap isn't on the base). The runtime guard is the authoritative fail-safe; see `docs/phase-loop/branchgov-preflight.md`.
+
+
+## Runner Evidence Contract
+
+Use artifact-backed re-verdicting for blocked gates: a gate changes verdict only by rerunning the originally specified runner check and reading the runner-owned artifact. proxy evidence requires a roadmap amendment before the bridge reports the gate as passed. When both canonical `.phase-loop/` state and legacy `.codex/phase-loop/` compatibility files exist, canonical `.phase-loop/` state takes precedence for status, monitor, resume, reconcile, and repair decisions.
+
+
+## Spec Delta Closeout
+
+Phase-loop handoffs and terminal closeouts must preserve one `spec_delta_closeout.v1` decision from the executor: `no_spec_delta`, `roadmap_amendment`, `canonical_spec_update`, `governed_pipeline_refresh`, `mirror_cutover_required`, `dotfiles_skill_source_update`, or `human_source_judgment_required`. Treat missing or malformed spec-closeout evidence as a repairable automation blocker with `blocker_class=contract_bug`, unless the decision is `human_source_judgment_required`. The record is metadata-only with `redaction_posture=metadata_only`: keep target surfaces, evidence paths, decision literals, IF gates, and artifact names, but never raw specification bodies, raw patch bodies, credentials, provider-supplied payloads, local environment values, or ignored/private evidence-source contents.
+
+## Command Mapping
+
+- `<harness>-phase-loop handoff`: run `<harness>-phase-loop handoff`.
+- `<harness>-phase-loop status`: run `<harness>-phase-loop status`.
+- `<harness>-phase-loop resume`: run `<harness>-phase-loop resume`.
+- `<harness>-phase-loop state`: run `<harness>-phase-loop state --json` when exact machine state is needed.
+- `<harness>-phase-loop monitor`: run `<harness>-phase-loop monitor --once --json` for a single machine-readable observation.
+- `<harness>-phase-loop monitor --notify-command <cmd>`: run monitor with callback-by-exception; the command receives redacted JSON on stdin.
+- `<harness>-phase-loop run`: run `<harness>-phase-loop run --max-phases <N>`.
+- `<harness>-phase-loop dry-run`: run `<harness>-phase-loop dry-run --max-phases <N>`.
+- `<harness>-phase-loop run --observe`: run `<harness>-phase-loop run --max-phases <N> --observe`; launch artifacts are written by default, so this flag is compatibility-only.
+- `<harness>-phase-loop dry-run --observe`: run `<harness>-phase-loop dry-run --max-phases <N> --observe`; launch artifacts are written by default, so this flag is compatibility-only.
+- `<harness>-phase-loop maintain-skills`: run `<harness>-phase-loop maintain-skills`.
+- `<harness>-phase-loop maintain-skills --observe`: run `<harness>-phase-loop maintain-skills --observe`; launch artifacts are written by default, so this flag is compatibility-only.
+- `<harness>-phase-loop maintain-skills --apply-skill-edits --improvement-plan <path> --allow-skill <<harness>-* skill>`: run apply-enabled maintenance only when the user explicitly requests skill edits and names the allowed Harness skill targets.
+- `<harness>-phase-loop sync-skills`: run `<harness>-phase-loop sync-skills --check` unless the user explicitly asks to repair drift.
+- `<harness>-phase-loop sync-skills --apply`: run apply mode only when the user explicitly wants local bridge-skill repair for manual reentry.
+
+Keep `run` bounded. If the user requests an unbounded run, choose `--max-phases 1` and say that the bridge keeps TUI-initiated runs bounded.
+
+Use the shared loop state to inspect injected-skill metadata and
+installed-skill drift before blaming a missing capability on the runner
+contract. Repo-sourced injected workflow bundles remain authoritative for
+autonomous child launches; installed workflow skills under `resolve_skill_bundle_root("codex")/`
+are the recommended manual reentry surface but are not a runtime prerequisite.
+If the advisory bridge record reports `missing_root`, `missing_skill`, or
+`drifted`, repair the local `<harness>-phase-loop` bridge with
+`<harness>-phase-loop sync-skills --apply` before relying on
+manual reentry.
+
+Harness is live-supported, but nested Harness-on-Harness disposable proof remains a
+known operator caveat. If the requested action is a full Harness live smoke, run
+it from a normal shell session rather than an active Harness thread. Active
+Harness-thread runs may still observe or exercise the non-Harness live matrix.
+
+When supervising a loop from a TUI, launch artifacts are written by default. If
+the TUI session has been idle while another control plane ran the loop, first run
+`<harness>-phase-loop handoff` or read
+`.phase-loop/tui-handoff.md`. That file is the canonical human-readable
+entrypoint and links to `.phase-loop/state.json`,
+`.phase-loop/events.jsonl`, `.phase-loop/runs/`, and the latest run
+log when known. Use `<harness>-phase-loop state --json` when exact
+machine state is needed. Creating `.phase-loop/stop` pauses the loop
+before the next phase launch; remove it before continuing.
+
+Use `<harness>-phase-loop run --max-phases <N> --observe
+--closeout-mode <manual|commit|push>` for execution. Use
+`<harness>-phase-loop monitor` for observation only. Monitor mode
+can be polled by a human, TUI, or external supervisor and can notify on
+`blocked`, `stale`, `complete`, `awaiting_phase_closeout`, `operator_halt`, or
+`terminal_exit` transitions through `--notify-command`. The notification
+payload is redacted JSON and points back to the same canonical state, ledger,
+handoff, heartbeat, terminal summary, and log files.
+
+Observed runs write `.phase-loop/runs/<run-id>/heartbeat.json` and
+`.phase-loop/runs/<run-id>/terminal-summary.json`. The handoff,
+`state --json`, and `monitor --once --json` surface elapsed time, child process
+liveness, seconds since the log changed, quiet level, heartbeat status,
+terminal status, recommended action, and a paste-ready nudge prompt. Use the
+nudge prompt only as an operator action in the owning TUI/session; the runner
+does not automatically kill, retry, duplicate, or inject prompts into child
+harnesses.
+
+Pipeline-aware dotfiles runs may also emit adjacent Pipeline closeout export
+metadata as `phase_loop_closeout.v1` in terminal summaries and event metadata.
+This is not a second shared closeout: preserve exactly one shared
+`automation:` block, treat `.phase-loop/` as authoritative state, and keep
+Governed Pipeline ingest outside dotfiles. Human-required Pipeline closeout
+metadata must include only redacted access attempts: source, probe, result,
+details, and timestamp, never secret values.
+
+Manual standalone bridge use remains valid without governed-pipeline, Portal,
+Greenfield, `.pipeline/**`, or a source bundle. In pipeline_required runs,
+Portal lifecycle state, Greenfield reduction, and Greenfield metadata-only authority refs are mediated through governed-pipeline closeout ingest and
+projection; protected-source freshness stays governed-pipeline-owned, and they are not dotfiles write targets. Do not infer reads or writes
+to `.pipeline/**`, governed-pipeline specs, Portal contracts, Greenfield
+authority files, raw evidence, provider-supplied payloads, credentials, or legacy
+`.codex/phase-loop/` state unless the active plan and source bundle explicitly
+own the exact path or glob. Legacy `.codex/phase-loop/` compatibility-only
+artifacts must not supersede canonical `.phase-loop/` state.
+The active plan and source bundle explicitly own the exact path or glob before
+protected bridge inputs or outputs may be used.
+Greenfield authority files remain outside dotfiles write ownership.
+Legacy `.codex/phase-loop/` state is compatibility-only and never authority.
+
+If execution discovers steering that changes downstream work, amend the nearest
+downstream roadmap phase that is not already executing. After that amendment,
+older downstream phase plans or handoffs whose roadmap metadata no longer
+matches are stale and must route back through `<harness>-plan-phase` before any
+further execution.
+
+When a phase is `awaiting_phase_closeout`, `manual` remains the default policy.
+Operators may opt into `--closeout-mode commit` to preserve trusted
+phase-owned dirty output locally, or `--closeout-mode push` to attempt the same
+local preservation and then push only when topology is clean and the push
+target is explicit or unambiguous. The handoff and `state --json` should be the
+source of truth for the latest closeout mode, commit SHA, push target, refusal
+reason, and verification status.
+
+When a phase is `blocked` with `human_required=false`, the runner may launch one
+bounded repair turn for that phase instead of treating the blocker as an
+operator stop. Repair launch is fail-closed: it requires trusted machine
+context for the current phase, including the current terminal summary and the
+active phase plan artifact. The repair turn must inspect
+`.phase-loop/state.json`, `.phase-loop/events.jsonl`,
+`.phase-loop/tui-handoff.md` or `<harness>-phase-loop handoff`, and verify
+`<harness>-phase-loop status --json` before and after edits. It should fix local
+roadmap/plan drift, apply closeout only when the recorded policy allows it,
+append a `manual_repair` event only when it clears the blocker, or convert the
+blocker to a frozen human-required taxonomy entry if investigation shows real
+operator input is needed.
+
+If an execute child returns without completion evidence and leaves the target
+repo dirty, including cases where the plan artifact still classifies the phase
+as `planned`, the runner treats that as a non-human repair blocker unless the
+dirty paths were already present outside the selected roadmap/plan artifacts.
+Rerunning the loop should launch a bounded repair turn only when that trusted
+context exists; otherwise it should fail closed and point the operator back to
+`.phase-loop/tui-handoff.md`, `<harness>-phase-loop handoff`, and
+`<harness>-phase-loop status --json`.
+
+If a planning child exits successfully but does not create the expected current
+phase-plan artifact, the runner must classify the phase as `blocked` with
+`human_required=false` and `blocker_class=repeated_verification_failure`. This
+usually means the child returned a proposed plan in prose instead of writing the
+artifact. The TUI handoff and terminal summary are the source of truth for the
+recovery command.
+
+Blocker meanings:
+
+- `awaiting_phase_closeout`: verified phase-owned dirty output needs explicit `manual`, `commit`, or `push` closeout.
+- `dirty_worktree_conflict`: dirty paths are unowned, pre-existing, or otherwise unsafe for automatic closeout.
+- `repeated_verification_failure`: a deterministic artifact or verification contract failed after a bounded attempt.
+- `admin_approval`: the loop found a real admin action, branch protection, or policy prerequisite.
+- `operator_halt`: `.phase-loop/stop` paused the loop before the next launch.
+
+The runner also records `git_topology` in `state.json`, `events.jsonl`, and the
+TUI handoff. Use it to detect whether the loop is operating from a PR branch,
+an alternate push ref, or a local branch ahead of its base. If the surrounding
+pipeline knows the intended target, it may set `PHASE_LOOP_BASE_REF`,
+`PHASE_LOOP_TARGET_PUSH_REF`, `PHASE_LOOP_PR_HEAD_REF`,
+`PHASE_LOOP_PR_BASE_REF`, or `PHASE_LOOP_PR_URL` before invoking the CLI.
+
+Release-dispatch phases are guarded by the CLI before child launch. If a plan is
+marked `phase_loop_mutation: release_dispatch`, dirty release-affecting paths or
+a branch/base-ref mismatch produce a blocked handoff instead of dispatching the
+external workflow. A roadmap-level complete handoff means all phases are
+complete and the target repo worktree is clean; it should not include a resume
+command.
+
+Child Harness launches default to `--sandbox danger-full-access`. Pass `--bypass-approvals` only when the user explicitly wants fully non-interactive child execution in an externally trusted sandbox.
+
+Write-capable parallel execution requires machine-verified disjoint lanes and
+scheduler-owned worktree assignments before fanout. Do not treat a prompt,
+plan note, or native harness team capability as enough to bypass runner-owned
+lane safety. Claude Code CLI exception wording means local Claude Code CLI
+execution through the phase-loop launcher, not Anthropic API-key execution or
+PI provider fallback. Harness and Gemini fallback wording remains CLI-based and
+reason-coded.
+
+## Human-Required Blockers
+
+When the CLI reports or implies `human_required=true`, preserve its `blocker_class`, `blocker_summary`, `required_human_inputs`, `access_attempts`, and `automation.status` in the final response. If the blocker is access-related and the CLI did not already record safe probes, perform metadata-only probes from `<harness>-config/shared/runtime-state.md` before asking the user to act.
+
+If `.phase-loop/tui-handoff.md` exists, use its plain-language blocker
+summary and required action as the user-facing explanation, then verify exact
+state from `state.json` or `<harness>-phase-loop state --json` before resuming.
+
+Use only the frozen blocker taxonomy: `missing_secret`, `account_or_billing_setup`, `admin_approval`, `destructive_operation`, `ambiguous_roadmap_selection`, `product_decision_missing`, `dirty_worktree_conflict`, `branch_sync_conflict`, `stalled_child_observation`, `repeated_verification_failure`, or `unretryable_external_outage`.
+
+## Manual Fallback
+
+If the runner cannot be used but a manual phase command is clear from durable state or CLI output, report that command instead of reconstructing runner behavior. Valid manual fallbacks are:
+
+- `<harness>-phase-roadmap-builder <roadmap_or_spec>`
+- `<harness>-plan-phase <roadmap_path> <phase_alias>`
+- `<harness>-execute-phase <plan_path>`
+- `<harness>-skill-improvement-planner`
+- `<harness>-skill-editor --improvement-plan <path> --allow-skill <<harness>-* skill>`
+
+## Verification
+
+Use the narrowest command that proves the requested bridge action:
+
+- `<harness>-phase-loop --help`
+- `<harness>-phase-loop handoff`
+- `<harness>-phase-loop status`
+- `<harness>-phase-loop dry-run --max-phases 1 --observe`
+
+For roadmap-level closeout, also inspect `.phase-loop/state.json`,
+`.phase-loop/events.jsonl`, relevant handoffs, and path-scoped `git status`
+instead of trusting a running transcript alone.

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/README.md

@@ -0,0 +1 @@
+Harness-specific overlay files for this workflow skill.

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: codex-phase-roadmap-builder
+description: "Harness-optimized roadmap planner. Use when the user wants to turn a conversation, architecture discussion, or markdown spec into a multi-phase roadmap for later Harness planning and execution. Creates or extends versioned phase roadmap specs in execution mode, but in Plan Mode returns a proposed plan only. Do not use for single bounded changes; use <harness>-plan-detailed instead."
+---
+
+# Harness Phase Roadmap Builder
+
+Builds a multi-phase roadmap that downstream `<harness>-plan-phase` can turn into implementation lanes. This is the Harness port of the Claude-oriented roadmap builder; do not edit or depend on the original skill at runtime.
+
+`shared/phase-loop/protocol.md` is the canonical shared contract for roadmap
+closeout `automation:` metadata, including `next_skill`, `next_command`, and
+`verification_status`.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Preserve Plan Mode boundaries. In Plan Mode, inspect files and produce a `<proposed_plan>` roadmap only; do not create or edit repo-tracked files.
+- In Default mode, write the roadmap artifact only after enough context is available.
+- During planning-only roadmap creation, do not execute test suites, builds, formatters, generators, or migrations. Capture end-to-end verification commands in the roadmap without running them.
+- Use local truth first: read named specs, `AGENTS.md`, and repo docs the user explicitly points at. Do not invent phases from vague context.
+- Use PMCP for external capability research when current docs or third-party tooling facts affect the roadmap. Prefer `gateway_catalog_search`, then `gateway_describe`, then `gateway_invoke`; use Context7 for library/product docs. Use Bright Data only if PMCP exposes it in the current environment.
+- Before asking the user for credentials, account setup, infrastructure state, admin action, or another access blocker, inspect repo-local docs/config and safe read-only or metadata-only state from available CLIs: `op`, `gh`, `vercel`/`npx vercel`, `supabase`/`npx supabase`, `gcloud`, `wrangler`, `cloudflared`, and `gam`. Never record secret values.
+- Use `request_user_input` only when available; in Default mode ask one concise plain-text question only if a missing decision would make the roadmap wrong.
+- Prefer fewer serial phases and more parallel work inside each phase. A phase boundary exists only when a contract must freeze before downstream work starts.
+- Keep release preparation and release dispatch in separate phases when a workflow needs both. The prepare phase owns version, changelog, release-doc, workflow-input, and evidence edits; the dispatch phase owns clean-tree preflight and external release triggering, and downstream plans should mark it with `phase_loop_mutation: release_dispatch`.
+- Do not spawn subagents unless the user explicitly asks for agents, subagents, delegation, or parallel agent work.
+
+## Inputs
+
+- Optional spec path: markdown file to fold into the roadmap.
+- Optional output path: default `specs/phase-plans-v<N>.md`, choosing the highest existing version or `v1` if none exists.
+- Append mode: if the output roadmap exists, add phases without rewriting prior phases unless the user explicitly requests a replacement.
+
+## Workflow
+
+1. Resolve repo root with `git rev-parse --show-toplevel`, then inspect:
+   - the named spec, if any;
+   - `AGENTS.md` and `CLAUDE.md`, if present;
+   - existing `specs/phase-plans-v*.md`;
+   - markdown files the user named.
+2. Choose create or append mode:
+   - Create mode writes a full roadmap.
+   - Append mode reads existing aliases, phase numbers, dependencies, and interface gates, then appends only new phases.
+3. Write top-level context:
+   - `Context`
+   - `Architecture North Star` when structural
+   - `Assumptions`
+   - `Non-Goals`
+   - `Cross-Cutting Principles`
+4. Decompose into phases:
+   - serial phases only at interface-freeze boundaries;
+   - sibling phases for independent subtrees;
+   - at least two likely lanes per implementation phase unless it is a preamble or interface-only phase;
+   - explicit `Depends on` and `Produces` entries.
+5. Add:
+   - `Top Interface-Freeze Gates`;
+   - `Phase Dependency DAG`;
+   - `Execution Notes` that name which phases can be planned or executed concurrently;
+   - end-to-end `Verification` commands.
+6. Validate mechanically, then by eye:
+   - run `phase-loop validate-roadmap <output-path>` (or `python3 -m phase_loop_runtime.roadmap_lint <output-path>`) — always available wherever the phase-loop runtime is installed; it mechanically checks stable headings, unique aliases, acyclic DAG, IF-gate reconciliation, and the lane-count hint. Fix every reported issue, then confirm by eye:
+   - stable headings are present;
+   - implementation units use `## Phases` and `### Phase N — <Name> (<ALIAS>)` consistently;
+   - implementation-unit headings and suggested next commands do not use `Step`, `Slice`, `Stage`, `Phase Flow`, or other non-phase synonyms unless the user explicitly requested a different taxonomy;
+   - aliases are unique;
+   - dependency graph is acyclic;
+   - every produced gate has a producing phase;
+   - append mode did not silently rewrite old phases.
+
+## Artifact Contract
+
+Use this shape so `<harness>-plan-phase` can parse it:
+
+```markdown
+# Phase roadmap v<N>
+
+## Context
+
+## Architecture North Star
+
+## Assumptions
+
+## Non-Goals
+
+## Cross-Cutting Principles
+
+## Top Interface-Freeze Gates
+- IF-0-<ALIAS>-<N> — <frozen contract>
+
+## Phases
+
+### Phase N — <Name> (<ALIAS>)
+**Objective**
+
+**Exit criteria**
+- [ ] <testable criterion>
+
+**Scope notes**
+
+**Non-goals**
+
+**Key files**
+
+**Depends on**
+- (none)
+
+**Produces**
+- IF-0-<ALIAS>-<N> — <contract>
+
+## Phase Dependency DAG
+
+## Execution Notes
+
+## Verification
+```
+
+
+
+## Spec Delta Policy
+
+Every roadmap phase must declare its expected `spec_delta_closeout.v1` policy. Add a phase-local `**Spec closeout policy**` block that names `schema: spec_delta_closeout.v1`, the expected decision (`no_spec_delta`, `roadmap_amendment`, `canonical_spec_update`, `governed_pipeline_refresh`, `mirror_cutover_required`, `dotfiles_skill_source_update`, or `human_source_judgment_required`), target surfaces, evidence paths, `redaction_posture: metadata_only`, and any non-human `blocker_class=contract_bug` routing for missing or malformed evidence. Use `no_spec_delta` for phases that do not change reusable specs, `dotfiles_skill_source_update` for dotfiles-owned skill/source updates, and downstream routing decisions such as `governed_pipeline_refresh` or `mirror_cutover_required` only as metadata-only deferrals, not as write authorization.
+
+## Verification Contract
+
+Roadmap phases must set the expectation that downstream plans include machine-checkable verification commands and an effective `automation.suite_command`. If a phase depends on operational evidence that cannot be machine-checked directly, name the operational evidence artifact and the runner-stamped amendment mechanism that records it. proxy evidence requires a roadmap amendment before any downstream plan treats it as a gate verdict.
+
+## Closeout
+
+In Default mode, write the roadmap with `apply_patch`, then run `git status --short -- <artifact>`. If the artifact is untracked or modified and the user did not explicitly forbid staging, run `git add <artifact>` and include the `_reviews.md` sibling if one was produced. Rerun `git status --short -- <artifact>` and report `Artifact state: staged|tracked|modified|unstaged|blocked`. Do not commit unless the user asked for a commit.
+
+Before final response and handoff, choose the next phase to plan from the roadmap DAG. If at least one phase is ready, report `Next phase: <alias> - <phase name>` and `Next command: <harness>-plan-phase <artifact> <alias>`. If no phase should be planned next, report `Next phase: none - <reason>` and `Next command: none - <reason>`.
+
+Add a machine-readable automation handoff that agrees with the human-readable next step fields. Closeout payload shape is defined by `EmitPhaseCloseout` in `phase_loop_runtime/baml_src/emit_phase_closeout.baml` (if that path is absent in the checkout, use the operator/prompt-supplied field contract or the installed `phase_loop_runtime` package — the missing vendored BAML source is not a blocker); keep skill text focused on value selection and handoff routing, not duplicated field ceremony.
+
+Before final response, write a reflection for every non-trivial run. Write it to `resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/reflections/<repo_hash>/<branch_slug>/<run_id>.md`. The reflection must include `## Run context` with skill name, ISO timestamp, repo, branch, commit, and artifact path if any, followed by `## What worked`, `## What didn't`, and `## Improvements to SKILL.md`. skip only when no artifact was produced AND no decision was made AND the run was pure inspection.
+
+If no phase should be planned next, set `next_skill: none`, `next_command: none`, `next_model_hint: none`, and keep `automation.status=complete` when the roadmap is complete or `automation.status=blocked` when progress needs a human decision. Blocked access or decision cases must use the frozen blocker taxonomy from `<harness>-config/shared/runtime-state.md`, include redacted `access_attempts` when relevant, and set `required_human_inputs` to non-secret requested inputs only.
+
+Manual TUI runs remain valid without the outer phase loop. When `.phase-loop/` exists, treat it as the authoritative runner state; legacy `.codex/phase-loop/` files are compatibility artifacts only and must not block or supersede canonical `.phase-loop/` state. When canonical `.phase-loop/state.json` or `tui-handoff.md` lags behind the newer `.phase-loop/events.jsonl` plus live git topology, reconcile current phase state from the ledger and `git status --short`/HEAD and cite that reconciliation; stale handoff text is not blocking. Only append a legacy `manual` source event to `.codex/phase-loop/events.jsonl` for standalone manual compatibility when no canonical `.phase-loop/` runtime exists, using the same `automation.status`, `next_skill`, `next_command`, `next_model_hint`, `next_effort_hint`, `human_required`, `blocker_class`, `blocker_summary`, `required_human_inputs`, `verification_status`, `artifact`, and `artifact_state` values.
+
+Resolve closeout writes through `shared/phase-loop/handoff_path.py` and the repo-local handoff resolver; legacy harness handoff roots are read only for migration. Follow `<harness>-config/shared/runtime-state.md` and use Harness paths only:
+
+- Reflection: `resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `<repo>/.dev-skills/handoffs/<harness>-phase-roadmap-builder/<run_id>.md`
+- Latest handoff pointer: `<repo>/.dev-skills/handoffs/<harness>-phase-roadmap-builder/latest.md`
+
+Handoff frontmatter must include `from: <harness>-phase-roadmap-builder`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, `artifact:`, `artifact_state:`, `next_skill:`, `next_command:`, and `next_phase:`. Update `latest.md` with the same handoff content.
+
+If roadmap creation is blocked by credentials, account setup, infrastructure state, admin action, or other access prerequisites, write a handoff with `human_required=true` and redacted `access_attempts` entries before asking the user to act. Each `access_attempts` entry must include `source`, `probe`, `result`, `details`, and `timestamp`, and `details` may report only metadata such as command availability, account or project identity, vault/item/field names, environment variable names, presence, and validation status.

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/assets/review_prompt.md

@@ -0,0 +1,19 @@
+Review the following multi-phase roadmap document produced by `/claude-phase-roadmap-builder`. The roadmap describes a sequence of phases that `/claude-plan-phase` will decompose into swim lanes; the goal of the roadmap format is to maximize end-to-end parallel execution time.
+
+Assess, concretely:
+
+1. **Phase-count justification** — is any phase actually two or more independent bodies of work that could have been sibling lanes within a single phase? A new phase is only justified when downstream work genuinely cannot proceed until an upstream contract is finalized. Flag phases whose `**Depends on**` is vacuous or whose subtrees are independent.
+
+2. **Cross-phase parallelism in the DAG** — does the `## Phase Dependency DAG` call out every sibling-pair opportunity (the `P6A || P6B parallel after P1` pattern)? Any two phases with no shared ancestor in the DAG should be labeled parallel. Flag missed opportunities.
+
+3. **Freeze narrowness** — each `**Produces**` entry should name a concrete, narrow symbol / endpoint / schema / migration, not a broad surface. Flag any produces line that reads "the full X module" or "the API of Y" instead of a specific symbol.
+
+4. **Non-Goals completeness** — list three things likely to scope-creep during execution (common scope-creep drifts in a project of this type). For each, confirm whether `## Non-Goals` explicitly defers it. Flag silent scope creep vectors.
+
+5. **Assumptions fail-loud check** — are there silent assumptions embedded in `## Context` or `## Cross-Cutting Principles` that should have been listed as numbered assumptions in `## Assumptions`? Flag any that, if wrong, would invalidate the plan.
+
+Additionally: if any `**Produces**` IF-gate (`IF-0-<ALIAS>-<N>`) is referenced in `## Top Interface-Freeze Gates` but not listed in its owning phase's `**Produces**` block, or vice versa, flag the mismatch.
+
+Be specific. Cite phase aliases (P1, P2A, P2B, …), line numbers, and the exact assertion at issue. Prefer "Phase P3's `Produces: IF-0-P3-1` is 'the plugin API' — not narrow; should name the specific `plugins_for(repo_id)` function signature" over general critique.
+
+ARTIFACT:

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/references/parallelization-heuristics.md

@@ -0,0 +1,111 @@
+# Parallelization Heuristics
+
+Extended rules for phase/lane decomposition. The goal is to minimize wall-clock time to deliver the full roadmap. The main SKILL.md carries the seven core rules; this doc expands them for edge cases.
+
+## Core model
+
+- **Phases are serial checkpoints.** Each phase closes an interface freeze that the next phase consumes. Wall-clock cost of a phase = wall-clock cost of its slowest lane.
+- **Lanes within a phase are parallel.** Multiple teammates, disjoint files, same wave.
+- **Total wall time ≈ sum over critical path of (slowest lane per phase).** Minimize this sum.
+
+## Rule 1 — Fewer phases, more lanes
+
+If two bodies of work can both start from today's codebase and don't depend on each other's output, they go in the same phase as sibling lanes. Do not split them into sequential phases just because they touch different modules.
+
+**Counter-example (don't do this):**
+
+```
+Phase 1 — Auth module
+Phase 2 — Billing module   ← billing doesn't depend on auth; why is it a separate phase?
+```
+
+**Correct:**
+
+```
+Phase 1
+  Lane 1 — Auth module
+  Lane 2 — Billing module
+```
+
+## Rule 2 — A phase boundary exists only at a necessary interface freeze
+
+Ask: "Can any work in the next phase start before this phase's output is final?" If yes, the phase boundary is arbitrary — collapse it.
+
+The only legitimate reason to introduce a phase boundary:
+
+- Downstream lanes need an interface (signature, schema, enum, migration number) that must be fixed before they can write code against it.
+- That interface is not yet fixed (either doesn't exist or is subject to change).
+
+If the interface is already stable (in the existing codebase, in a vendored library, in a finalized spec), no phase boundary is needed — parallelize now.
+
+## Rule 3 — Prefer narrow, early freezes
+
+A freeze on "the authentication module" blocks a lot. A freeze on "`login(email, password) -> Session`" blocks almost nothing. Write the tightest possible contract in the `**Produces**` block.
+
+Narrow freezes let you push more lanes into earlier phases. Phase 1 can freeze the minimum surface; Phase 2 starts on the wider surface while Phase 1's lanes fill in the implementation.
+
+**Anti-pattern**: `**Produces**: full implementation of X`. That's not a freeze, that's just done work. A freeze is a contract about shape, not content.
+
+## Rule 4 — Split fat phases into parallel sibling phases
+
+When a phase has two or more subtrees that don't share an interface dependency on each other, split them into parallel-safe sibling phases. Use the aliased-branch pattern:
+
+```
+P6A — Dep hygiene           parallel after P1
+P6B — Docs alignment        parallel after P4
+```
+
+Sibling phases with distinct aliases let `/claude-execute-phase` schedule them concurrently instead of serially.
+
+**Test**: if `Phase N` lists `Depends on: P3` and `Phase N+1` also lists `Depends on: P3`, and neither lists the other, they are siblings. Mark them as `NA` / `NB` aliases, not `N` / `N+1`.
+
+## Rule 5 — ≥2 lanes per phase (with exceptions)
+
+A single-lane phase is a code smell. Investigate:
+
+- Is the work actually a single atomic unit? → Likely belongs as one lane inside an adjacent phase, not its own phase.
+- Is the work too coarse? → Split the file-ownership further until ≥2 disjoint lanes emerge.
+- Is it a pure interface-freeze phase (Phase 0 / Phase 1 preamble)? → This is the exception. Mark `Scope notes` with "preamble / interface-only phase — single lane justified".
+
+The validator enforces this rule but allows the preamble escape hatch via explicit `Scope notes` marking.
+
+## Rule 6 — Parallelism hints in Scope notes
+
+Every phase's `Scope notes` must make the parallelization plan machine-readable to `/claude-plan-phase`:
+
+- Suggested lane count (e.g., "decompose into 3 lanes").
+- Disjoint-file partitions per lane (e.g., "lane A owns `auth/**`, lane B owns `billing/**`, lane C owns `shared/types.ts`").
+- Single-writer files (e.g., "`routes/index.ts` is single-writer; lane A owns it, others append via imports").
+- Test-file placement (e.g., "tests go in each lane's directory; no shared test fixture file").
+
+Without these hints, `/claude-plan-phase` has to re-derive the partition from scratch, which it may do incorrectly.
+
+## Rule 7 — Cross-phase parallelism in the DAG
+
+Two phases can execute concurrently when the DAG shows no path between them. Identify these explicitly:
+
+- Annotate the DAG with `parallel after <X>` on branch phases.
+- List cross-phase parallelism in `## Execution Notes` so `/claude-execute-phase` doesn't serialize by default.
+
+Critical path = longest path from root phases to the terminal phase. If you can split a node on the critical path into a sibling pair (Rule 4), the critical path shrinks.
+
+## Anti-patterns
+
+- **Waterfall in disguise**: `Phase 1 — Design; Phase 2 — Implement; Phase 3 — Test.` This is one phase with three task types, not three phases. Tests are written before impl (TDD) within each real phase.
+- **Phase-per-module**: "Phase 1 = auth, Phase 2 = billing, Phase 3 = notifications." Almost always wrong — these should be sibling lanes in one phase unless they genuinely depend on each other's interfaces.
+- **Vague freezes**: `**Produces**: improved database layer`. Not a freeze. Specify the symbols, types, or migration numbers that will be stable.
+- **Too-wide freezes**: `**Produces**: full public API of module X`. Downstream lanes will need to wait for every function in X to be final, not just the ones they call. Freeze only what's consumed.
+- **Phantom phase dependencies**: listing `Depends on: P2` in `P3` when P3 only needs one symbol from P2 that P2 freezes on day one. Either narrow the freeze so P3 can start immediately, or promote the freeze to P1 where it belongs.
+
+## Diagnostic questions
+
+When sizing phases, ask:
+
+1. What's the minimum interface `Phase N+1` needs from `Phase N`?
+2. Can that interface be frozen on `Phase N`'s first day instead of its last?
+3. If yes — move the freeze earlier and parallelize. If no — you've found the real phase boundary.
+4. Inside `Phase N`, what are the natural file-ownership partitions?
+5. Are any of those partitions independent enough to be lanes that won't block each other?
+6. Is there any file multiple lanes want to write? If yes, assign a single owner and have others append via imports or extension points.
+
+Answering these yields a roadmap where the critical path is the actual minimum serialization inherent in the work — not arbitrary process overhead.