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

phase_loop_runtime/skills_bundle/claude-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/claude-phase-loop/README.md

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

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

@@ -0,0 +1,115 @@
+---
+name: claude-phase-loop
+description: "Harness Code bridge for the repo-local phase-loop runner. Use when the user wants phase-loop status, resume, bounded run, dry-run, or monitor flows from Harness."
+---
+
+# Harness Phase Loop
+
+Thin bridge for the repo-local phase-loop runner. This skill points Harness
+operators at the shared loop state and command surface; it does not reimplement
+phase selection, reconciliation, 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 repo-local phase-loop CLI or wrapper documented by the repo; do not invent a second runner.
+- Preserve manual Harness use of `<harness>-phase-roadmap-builder`, `<harness>-plan-phase`, and `<harness>-execute-phase`.
+- Inspect `shared/phase-loop/protocol.md` and `<harness>-config/shared/runtime-state.md` before describing artifact or blocker semantics.
+- Before reporting a human-required access blocker, inspect repo-local docs/config and safe metadata from available CLIs. Never print secret values.
+
+## 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. Prefer `--max-phases 1` unless the user names another bound.
+- `dry-run`: show the commands the runner would launch without executing them.
+- `sync-skills`: audit or repair the installed `<harness>-phase-loop` bridge skill used for local manual reentry.
+
+Keep `run` bounded. If the user asks for an unbounded TUI run, clamp it to
+`--max-phases 1` and say that the bridge keeps interactive runs bounded.
+
+## Shared State Surface
+
+- `.phase-loop/state.json`
+- `.phase-loop/events.jsonl`
+- `.phase-loop/tui-handoff.md`
+- `.phase-loop/runs/<run-id>/heartbeat.json`
+- `.phase-loop/runs/<run-id>/terminal-summary.json`
+
+Use CLI output such as `status --json` and `monitor --once --json` when exact
+machine state is needed.
+
+## What This Bridge Must Cover
+
+- bounded `run`, `dry-run`, `resume`, `status`, and `monitor` flows
+- manual event import expectations from `shared/phase-loop/protocol.md`
+- injected-skill metadata and installed-skill drift guidance from the shared loop state
+- downstream roadmap amendments that invalidate older downstream phase plans or handoffs
+
+## Operator Notes
+
+Repo-sourced injected workflow bundles remain authoritative for autonomous
+phase-loop child launches. Installed workflow skills under `resolve_skill_bundle_root("claude")/`
+are the recommended manual reentry surface, but they are not required for the
+runner to launch or continue work. If the advisory bridge record reports
+`missing_root`, `missing_skill`, or `drifted`, repair the local bridge with
+`codex-phase-loop sync-skills --apply` before trusting manual Harness reentry.
+The injected Harness bundle carries the full workflow pack
+(`<harness>-phase-roadmap-builder`, `<harness>-plan-phase`,
+`<harness>-execute-phase`, and `<harness>-phase-loop`) from the repo-owned source
+tree under `.phase-loop/runs/<run-id>/<harness>-bundle/`.
+
+Use the shared loop state to reason about:
+
+- current `automation` status and `verification_status`
+- whether a blocker is `dirty_worktree_conflict`, `branch_sync_conflict`, or another frozen blocker literal
+- whether the selected harness skill pack matches injected metadata or shows installed-skill drift
+
+If the local TUI may be stale because another harness or shell session drove
+the loop, start from `handoff` or `monitor --once --json` before resuming.
+Manual imports must append shared-protocol events instead of inventing
+harness-private state.
+
+If a downstream roadmap amendment lands, route the next step back through the
+planner and treat older downstream plans as stale.
+
+## 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 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 specs, raw diffs, credentials, provider payloads, local env values, or ignored/private evidence-source contents.
+
+## Command Mapping
+
+- `<harness>-phase-loop handoff`: use `phase-loop handoff` or `codex-phase-loop handoff`.
+- `<harness>-phase-loop status`: use `phase-loop status` or `codex-phase-loop status`.
+- `<harness>-phase-loop state`: use `phase-loop state --json` when exact machine state is needed.
+- `<harness>-phase-loop monitor`: use `phase-loop monitor --once --json`.
+- `<harness>-phase-loop run`: use `phase-loop run --max-phases <N> --closeout-mode manual` unless the operator explicitly chooses another closeout mode.
+- `<harness>-phase-loop dry-run`: use `phase-loop dry-run --max-phases <N>`.
+- `<harness>-phase-loop sync-skills`: use `phase-loop sync-skills --check`, and use `--apply` only when the operator explicitly wants bridge repair.
+
+Harness Code uses the shared runner contract, but autonomous live dispatch is
+proof-blocked until the authenticated non-interactive planning smoke completes
+inside the runner timeout. Manual TUI reentry and manual-import closeout remain
+supported through `.phase-loop/` state. ThawedCode stays grouped with
+Harness only for docs and manual imports; do not claim a separate live
+ThawedCode automation contract unless a later roadmap proves it.

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

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

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

@@ -0,0 +1,439 @@
+---
+name: claude-phase-roadmap-builder
+description: "Harness Code roadmap planner. Produces or extends a multi-phase roadmap spec that <harness>-plan-phase can ingest, with phase dependencies and interface-freeze gates."
+---
+
+# <harness>-phase-roadmap-builder
+
+## Runtime State
+
+For reflections, handoffs, and latest handoff pointers, follow `<harness>-config/shared/runtime-state.md`. This repo/branch/run-isolated contract supersedes any older flat closeout examples retained for historical context in this skill.
+
+`shared/phase-loop/protocol.md` is the canonical shared contract for
+`automation:`, `next_skill`, `next_command`, `verification_status`, and
+downstream roadmap-amendment semantics. Harness-specific closeout text must
+agree with that shared protocol.
+
+When this skill runs through the phase-loop Harness adapter, the repo-owned
+injected plugin bundle is authoritative. That bundle carries the full Harness
+workflow pack (`<harness>-phase-roadmap-builder`, `<harness>-plan-phase`,
+`<harness>-execute-phase`, and `<harness>-phase-loop`) even if installed bridge
+skills under `resolve_skill_bundle_root("claude")/` are missing or drifted.
+
+Produces the `specs/phase-plans-v<N>.md` roadmap that `/<harness>-plan-phase` consumes. Digests the prior conversation and any markdown files the user points at, then writes a phased roadmap whose structure maximizes parallel execution. Creates a new roadmap if none exists; appends phases (never edits existing phases) if one does.
+
+## When to use
+
+- User wants to formalize a conversation's plan into a phased roadmap.
+- User points at a markdown spec and asks to "phase it."
+- User wants to add phases to an existing `specs/phase-plans-v*.md`.
+- User wants the output to be ingestible by `/<harness>-plan-phase`.
+
+## When NOT to use
+
+- Single-phase or single-concern change → use `/<harness>-plan-detailed`.
+- Lane-level planning for one phase → the user wants `/<harness>-plan-phase`, not this skill.
+- Pure research / "how does X work" → use `Agent(subagent_type: "Explore")` directly.
+
+## Inputs
+
+| Arg | Required | Meaning |
+|---|---|---|
+| `<spec-path>` | no | Path to an input markdown spec to fold into the roadmap. Optional; conversation context is the primary source. |
+| `--output <path>` | no | Override the default output path. Default: `specs/phase-plans-v<N>.md` at the repo root. |
+| `--append` | no | Force append mode even if the resolved output path is new (rare). |
+| `--review-external` | no | After writing the roadmap, run Gemini + Codex CLIs in parallel to review it. Requires `gemini` and `codex` installed and authenticated. Produces a `_reviews.md` sibling file. |
+
+## Prerequisites
+
+Expected helpers under `.claude/skills/_shared/` (check existence before invocation; fall back inline when absent):
+
+- `_shared/scaffold_docs_catalog.py` — scaffolds the docs catalog. On absence, create `.claude/docs-catalog.json` manually as an empty-array JSON file (`[]`).
+- `_shared/next_reflection_path.py` — legacy helper only; current closeout writes reflections to `resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/reflections/<repo_hash>/<branch_slug>/<run_id>.md`.
+- `_shared/review_with_cli.py` — used only with `--review-external`; required for that flag.
+
+## Mode detection
+
+Resolve the output path in this order:
+1. `--output` override.
+2. Glob `specs/phase-plans-v*.md`; pick the highest version.
+3. If none found, default to `specs/phase-plans-v1.md` (create mode).
+
+If the resolved path exists → **append mode**. Otherwise → **create mode**.
+
+## Deferred tool preloading
+
+Load tools used later in a single query:
+
+```
+ToolSearch(query: "select:AskUserQuestion,ExitPlanMode")
+```
+
+## Workflow — create mode
+
+### Step 0 — Read predecessor handoff (if present)
+
+Handoffs are keyed on the current repo so each workspace has its own slot. Resolve the predecessor path first:
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO_ROOT" ]; then
+  REPO_KEY="_no-git-$(pwd | sha1sum | cut -c1-12)"
+else
+  REPO_KEY="$(basename "$REPO_ROOT")-$(printf '%s' "$REPO_ROOT" | sha1sum | cut -c1-12)"
+fi
+PREDECESSOR_HANDOFF="$(python3 - <<'PYH'
+from importlib import util
+from pathlib import Path
+repo = Path.cwd().resolve()
+spec = util.spec_from_file_location("handoff_path", repo / "shared" / "phase-loop" / "handoff_path.py")
+mod = util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+print(mod.resolve_handoff_path(repo, "<harness>-execute-phase"))
+PYH
+)"
+```
+
+If `$PREDECESSOR_HANDOFF` exists, `Read` it in full — a prior `/<harness>-execute-phase` run may have left context useful for the next roadmap (completed phases, decisions made, gotchas discovered mid-execution). Treat its contents as additional input to Step 1.
+
+Defense-in-depth checks (the repo-key scheme prevents the common cross-project case, but these still catch symlink-shared workspaces, manual file copies, and stale handoffs):
+
+- If the handoff's `from:` field is not `<harness>-execute-phase` or its timestamp is older than 7 days, flag via `AskUserQuestion` with `[use anyway, ignore, abort]`.
+- Parse the handoff's `artifact:` field and verify at least one referenced path resolves under `$(git rev-parse --show-toplevel)`. On mismatch, surface `AskUserQuestion` with `[use anyway, ignore, abort]`.
+
+If absent, proceed — this run is standalone.
+
+### Step 1 — Gather inputs
+
+Sources (permissive but bounded):
+
+1. The current conversation's user turns, assistant plans, and any committed architectural decisions.
+2. The spec path argument, if supplied — `Read` it in full.
+3. `CLAUDE.md` and `AGENTS.md` at the repo root, if present.
+4. Markdown files the user has explicitly named anywhere in the conversation.
+
+Do not grep the repo for additional material. If context is insufficient, stop and ask the user via `AskUserQuestion` — a thin roadmap is worse than one more question.
+
+### Step 1a — Ensure docs catalog exists
+
+Check for the helper before invoking:
+
+```bash
+HELPER="$(git rev-parse --show-toplevel)/.claude/skills/_shared/scaffold_docs_catalog.py"
+if [ -f "$HELPER" ]; then
+  python3 "$HELPER"
+else
+  CATALOG="$(git rev-parse --show-toplevel)/.claude/docs-catalog.json"
+  [ -f "$CATALOG" ] || echo '[]' > "$CATALOG"
+fi
+```
+
+Scaffolds `.claude/docs-catalog.json` if absent; no-op if already present. On helper absence, seed the catalog manually as an empty-array JSON file. The catalog drives the `SL-docs` lane that `<harness>-plan-phase` constructs for every phase. Existence matters more than content at this stage — the catalog will be refreshed (`--rescan`) by each `SL-docs` lane as the roadmap executes.
+
+### Step 2 — Synthesize top-of-document sections
+
+Fill these sections before touching phase decomposition:
+
+- **Context** — one-page synthesis: the problem, current state, the thesis of the refactor/build.
+- **Architecture North Star** — ASCII diagram of the target architecture if the work is structural. Omit if not load-bearing.
+- **Assumptions (fail-loud if wrong)** — numbered list of preconditions; each is something that, if false, invalidates the plan.
+- **Non-Goals** — explicit deferrals. Use to cut scope; silence here causes scope creep later.
+- **Cross-Cutting Principles** — rules that apply across every phase (e.g., "single-writer-per-SQLite-file", "no mocks in integration tests").
+
+### Step 3 — Decompose into phases (parallelization-maximizing)
+
+Apply the heuristics in `references/parallelization-heuristics.md` in order:
+
+1. **Phases are serial checkpoints; lanes within a phase are parallel.** Minimize total wall time by minimizing phase count and maximizing lanes per phase.
+2. **A phase boundary exists only at a necessary interface freeze.** If two bodies of work share no freeze dependency and have disjoint files, they are sibling lanes inside one phase, not sequential phases.
+3. **Prefer narrow, early freezes.** Each phase's `Produces:` lists the tightest contract that unblocks the next phase.
+4. **Split fat phases into parallel sibling phases** when they contain independent subtrees (the `P6A || P6B` pattern).
+5. **Every phase decomposes into ≥2 lanes** unless it is a preamble / interface-freeze-only phase (Phase 1 / P0 are the common exceptions). Single-lane phases are a code smell — merge or split.
+6. **Each phase's `Scope notes` lists explicit parallelism hints**: suggested lane count, candidate disjoint-file partitions, and any single-writer files that would serialize lanes if ignored.
+7. **Identify cross-phase parallelism.** Phases with no shared ancestor in the DAG can run concurrently. Call these out in the DAG.
+8. **Day-1 intra-phase freeze publication.** When one lane's output shape can be published before its implementation lands, declare the shape as an intra-phase freeze so sibling lanes start against the contract rather than waiting.
+9. **Soft upper bound on lanes per phase.** When a phase would contain more than 6–8 lanes AND the lanes partition into independent subtrees sharing no intra-phase freeze, split into sibling phases. When the lanes share intra-phase freezes, keep them in one phase regardless of count.
+
+### Step 4 — Draft Top Interface-Freeze Gates
+
+For each inter-phase freeze, write one `IF-0-<ALIAS>-<N>` entry naming the concrete symbol, schema, or endpoint being frozen. Narrow is better — a gate that names "a dataclass with fields `{a, b, c}`" lets downstream lanes start; "the data model" does not.
+
+### Step 5 — Write each phase section
+
+Use the skeleton from `references/roadmap-template.md`. Each phase MUST contain:
+
+- `**Objective**` — one or two sentences.
+- `**Exit criteria**` — checkbox list (`- [ ] …`), each item testable.
+- `**Scope notes**` — lane decomposition hints, parallelism advice, edge cases.
+- `**Non-goals**` — explicitly deferred.
+- `**Key files**` — paths the phase touches.
+- `**Depends on**` — upstream phase aliases, or `(none)` for roots. Root phases use the exact form `- (none)` with no trailing prose; put explanatory notes on a following bullet or in `Scope notes`.
+- `**Produces**` — `IF-0-<ALIAS>-<N>` entries for freezes this phase publishes.
+
+Phase heading format: `### Phase N — <Name> (<ALIAS>)`. Alias is short, mnemonic, alphanumeric (`P1`, `P2A`, `P2B`, `P3`, …). It becomes the filename token in `phase-plan-v<N>-<alias>.md`.
+
+Runner compatibility hard requirement: every `### Phase ...` heading MUST include `(<ALIAS>)`, even when `--output` writes an alternate path such as `planning/**/phase-roadmap.md` instead of `specs/phase-plans-v<N>.md`. Never write prose-only headings like `### Phase 1 — Foundation`; `phase-loop` and `<harness>-plan-phase` use the alias as the stable phase identifier.
+
+Before writing the artifact, perform an explicit alias-assignment pass:
+
+1. List every runnable phase heading you are about to emit.
+2. Assign one unique uppercase alias per phase.
+3. Rewrite each heading into the exact `### Phase N — <Name> (<ALIAS>)` form.
+4. Ensure the `## Phase Dependency DAG`, `**Depends on**`, `**Produces**`, and `## Execution Notes` sections refer to phases by those aliases, not by prose names or workstream IDs.
+
+Do not substitute `## Phase Decomposition`, `## Workstreams`, or prose "Done when" sections for the canonical `## Phases` structure. Narrative context may exist above the phase list, but runnable roadmap content must be under `## Phases` with aliased phase headings.
+
+### Step 6 — Build Phase Dependency DAG
+
+Render as ASCII. Show serial arrows (`P1 → P2A → P2B`) and parallel branches (`P6A  parallel after P1`). This is the source of truth for the wall-clock schedule.
+
+### Step 7 — Write Execution Notes and Verification
+
+- **Execution Notes**: how to invoke `/<harness>-plan-phase <ALIAS>` for each phase, and `/<harness>-execute-phase <alias>` for each. Call out which phases can be planned and executed concurrently.
+- **Verification**: end-to-end shell commands that prove the whole roadmap delivered its goals. These are the integration tests the user will run after the last phase merges.
+
+### Step 8 — Validate
+
+The validator ships in the always-installed phase-loop runtime, so it does not
+depend on the skill bundle's `scripts/` directory being present. Prefer the CLI:
+
+```bash
+phase-loop validate-roadmap <output-path>
+# equivalent, if you only have the runtime importable and not the console script:
+python3 -m phase_loop_runtime.roadmap_lint <output-path>
+```
+
+Both wrap `phase_loop_runtime.roadmap_lint` (the single source of truth; the
+bundle's `scripts/validate_roadmap.py` is a thin shim over it). Run against the
+exact artifact path written by this invocation, including custom paths such as
+`planning/**/phase-roadmap.md`; do not validate a default
+`specs/phase-plans-v<N>.md` path unless that is the actual output. Fix every
+reported error before handing off. The validator enforces: required headings,
+phase-heading aliases, alias uniqueness, DAG acyclicity, IF-gate ID format,
+Depends-on correctness, and the ≥2-lanes-per-phase rule (with a preamble-phase
+escape hatch).
+
+If neither the `phase-loop` console script nor the `phase_loop_runtime` package
+is importable (an incomplete install), do not hand off a roadmap checked only by
+eye: install the runtime from the public agent-harness
+(`scripts/install-agent-harness.sh`, or `uv tool install
+"git+https://github.com/ViperJuice/agent-harness@v0.1.6#subdirectory=phase-loop-runtime"`)
+or report a blocker. The validator itself is always available once the runtime is
+installed — there is no "validator script missing" blocker.
+
+### Step 8.5 — External CLI review (only if `--review-external`)
+
+Requires `_shared/review_with_cli.py` (see Prerequisites). After the roadmap is written and validated, run:
+
+```bash
+python3 "$(git rev-parse --show-toplevel)/.claude/skills/_shared/review_with_cli.py" \
+  --artifact <output-path> \
+  --prompt-file "$(git rev-parse --show-toplevel)/.claude/skills/<harness>-phase-roadmap-builder/assets/review_prompt.md" \
+  --out <output-path>_reviews.md
+```
+
+If the frontier-model cache is empty, the script prints the discovery prompt to stderr. Surface to the user via `AskUserQuestion` with options `[run discovery now, skip review this run, abort]`.
+
+Tell the user: "Review written to `<output-path>_reviews.md`. Agreements between Gemini and Codex are real signal; divergences are context."
+
+### Step 9 — Write and exit
+
+Write the roadmap to the resolved output path. If you are in plan mode (a plan-mode system reminder is present), call `ExitPlanMode` — the roadmap is the approval surface. If you are NOT in plan mode (adapter/non-interactive or default invocation), do not call `ExitPlanMode`; the written roadmap file is itself the deliverable — present its path and a one-line summary instead. After approval (or after writing, when not in plan mode), the hand-off message is: "Run `/<harness>-plan-phase <ALIAS>` for each phase. Phases with no shared DAG ancestor (e.g., `<list them>`) can be planned concurrently."
+
+## Workflow — append mode
+
+### Step A1 — Read existing roadmap
+
+`Read` the existing `specs/phase-plans-v*.md`. Extract:
+
+- The highest `## Phase N` number.
+- The full existing alias set.
+- The highest `IF-0-<ALIAS>-<N>` sequence number per phase.
+- The existing Phase Dependency DAG edges.
+
+### Step A2 — Identify new phases from context
+
+Apply Step 1 above to gather new context. Then apply Step 3's heuristics to decide which new phases are needed. Do not modify existing phases — additions only. If the new context implies that an existing phase is wrong, stop and tell the user; do not silently edit.
+
+### Step A3 — Assign numbers and aliases
+
+- Phase numbers continue strictly increasing (highest existing + 1, +2, …).
+- New aliases must not collide with existing ones. Extend the convention (`P8`, `P9`, or `P4B` if it branches from an existing `P4`).
+
+### Step A4 — Wire Depends on
+
+For each new phase, list every existing phase it depends on by alias. A new phase that depends on nothing existing is either a new root (rare — possible when introducing a parallel initiative) or misidentified.
+
+### Step A5 — Splice into the document
+
+Insert new phase sections under `## Phases`, after the last existing phase, before `## Execution Notes`. Update two other sections:
+
+- `## Phase Dependency DAG` — add the new nodes and edges.
+- `## Top Interface-Freeze Gates` — append any new `IF-0-<ALIAS>-<N>` entries.
+
+Leave `## Context`, `## Architecture North Star`, `## Assumptions`, `## Non-Goals`, `## Cross-Cutting Principles`, `## Execution Notes`, and `## Verification` alone unless the new phases invalidate a stated assumption — in which case surface the conflict to the user and stop.
+
+### Step A6 — Validate + exit
+
+Same as Step 8, Step 8.5 (if `--review-external`), and Step 9. Validator must pass.
+
+## Output contract
+
+The output file must match `references/roadmap-template.md` structurally. `<harness>-plan-phase` parses stable headings (`## Context`, `### Phase N — <Name> (<ALIAS>)`, `**Objective**`, `**Exit criteria**`, etc.) by regex; non-standard formatting breaks downstream.
+
+## Hand-off
+
+After approval, invoke `/<harness>-plan-phase <ALIAS>` per phase. Phases with no shared ancestor in the DAG can be planned and executed in parallel — note which ones in the hand-off message. The wall-clock critical path is the longest DAG path through the roadmap.
+
+## Close-out — Stage artifact (preservation guarantee)
+
+After `ExitPlanMode` is approved (or, when not in plan mode, after the roadmap file is written), before exiting:
+
+1. Run `git status --short -- <output-path>` and include the `_reviews.md` sibling if `--review-external` produced one.
+2. If the roadmap or review artifact is untracked or modified and the user did not explicitly forbid staging, run `git add <output-path>` plus the review sibling if present.
+3. Rerun `git status --short -- <output-path>` and report `Artifact state: staged|tracked|modified|unstaged|blocked`.
+4. Do not commit unless the user explicitly 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, set `Next phase: <ALIAS> - <phase name>` and `Next command: /<harness>-plan-phase <ALIAS>`. If no phase should be planned next, set `Next phase: none - <reason>` and `Next command: none - <reason>`.
+
+## Close-out — Reflection + Handoff
+
+Stage the roadmap/plan artifacts before writing either close-out file so the deliverable is preserved in the index unless the user explicitly forbade staging.
+
+After artifacts are staged or confirmed tracked, resolve paths:
+
+```bash
+REFLECTION_PATH=resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/reflections/<repo_hash>/<branch_slug>/<run_id>.md
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+REPO_LOCAL_HANDOFF=$(python3 - <<'PYH'
+from importlib import util
+from pathlib import Path
+repo = Path.cwd().resolve()
+spec = util.spec_from_file_location("handoff_path", repo / "shared" / "phase-loop" / "handoff_path.py")
+mod = util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+print(mod.resolve_handoff_path(repo, "<harness>-phase-roadmap-builder"))
+PYH
+)
+mkdir -p "$(dirname "$REPO_LOCAL_HANDOFF")"
+SKILL_MD=resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/SKILL.md
+```
+
+Write BOTH files directly via the Write tool — this is the primary path.
+
+FILE 1 — REPO-AGNOSTIC reflection → write to `<REFLECTION_PATH>`
+
+```
+# <harness>-phase-roadmap-builder reflection — <ISO timestamp>
+
+## Run context
+- Skill: <harness>-phase-roadmap-builder
+- Timestamp: <ISO timestamp>
+- Repo: <repo>
+- Branch: <branch>
+- Commit: <commit>
+- Artifact: <artifact path if any, or none>
+
+## What worked
+- <bullet, about the SKILL's instructions>
+
+## What didn't
+- <bullet, about friction or gaps in the SKILL's instructions>
+
+## Improvements to SKILL.md
+- <specific, actionable change to the instructions>
+```
+
+Do NOT reference this project, codebase, filenames, or domain in FILE 1. Feedback is about how the skill's instructions performed, for a future meta-skill that digests reflections across runs.
+
+FILE 2 — REPO-SPECIFIC handoff → write to `<REPO_LOCAL_HANDOFF>` (per-repo slot; overwrites any prior handoff from this skill in the same repo)
+
+```
+<!--
+  Consumer validation — before acting on this handoff:
+  1. Verify `from:` matches the expected predecessor skill.
+  2. Verify `timestamp:` is within the last 7 days.
+  3. Verify every `artifact:` path resolves under your current
+     `$(git rev-parse --show-toplevel)`. If any path points to a
+     different repo, stop and surface it to the user — the handoff
+     was written against a different workspace.
+-->
+---
+from: <harness>-phase-roadmap-builder
+timestamp: <ISO>
+artifact: <absolute path(s) to roadmap spec + any reviews written>
+artifact_state: <staged|tracked|modified|unstaged|blocked>
+next_skill: <<harness>-plan-phase|none>
+next_command: </<harness>-plan-phase ALIAS|none - reason>
+next_phase: <ALIAS - phase name|none - reason>
+---
+
+# Handoff for the next skill
+
+## Summary
+<2-3 sentences: what was produced, where to find it.>
+
+## Key decisions made this run
+- <numbered, one line each>
+
+## Open items for the next skill
+- <concrete, actionable — e.g., "Lane SL-3 expects the
+  plugins_for(repo_id) signature from IF-0-P3-1; verify it
+  before planning P4">
+
+## Repo-specific gotchas surfaced
+- <things that surprised this run; quirks of THIS codebase>
+
+## Planning artifacts staged this run
+- <path> @ <artifact_state>
+
+## Next skill's likely scope
+- <best-effort forecast of which files/paths the next skill will touch>
+```
+
+Optionally delegate to a spawned frontier-tier Agent instead when independent review with a fresh context window is desired (e.g., after complex runs). Resolve the model via the `<harness>-execute-phase` Model tiers table:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: "<frontier-model-id>",
+  name: "<harness>-phase-roadmap-builder-closeout",
+  prompt: """
+    Review the skill at <SKILL_MD> and the current execution transcript.
+    Write FILE 1 to <REFLECTION_PATH> and FILE 2 to <REPO_LOCAL_HANDOFF> using
+    the schemas defined in the SKILL's Close-out section.
+  """
+)
+```
+
+After the files are written, print to the user:
+
+> Roadmap written to `<spec-path>`.
+> Reflection saved to `<REFLECTION_PATH>`.
+> Handoff written to `<REPO_LOCAL_HANDOFF>`.
+>
+> Recommended next step: run `/clear` to reset your context window, then invoke `/<harness>-plan-phase <ALIAS>`. The next skill reads the handoff automatically.
+
+## Reference files
+
+- `references/roadmap-template.md` — exact structural skeleton to emit.
+- `references/parallelization-heuristics.md` — extended rules for edge cases in phase/lane decomposition.
+
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+
+
+## 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
+
+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.