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

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

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

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

@@ -0,0 +1,113 @@
+---
+name: opencode-phase-loop
+description: "OpenCode 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 OpenCode."
+---
+
+# OpenCode Phase Loop
+
+Thin bridge for the repo-local phase-loop runner. This skill points OpenCode
+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 OpenCode 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`
+- `status`
+- `monitor`
+- `resume`
+- `run`
+- `dry-run`
+- `sync-skills`
+
+Keep `run` bounded. Prefer `--max-phases 1` unless the user names another
+bound.
+
+## 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("opencode")/` 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 OpenCode reentry.
+
+Use the shared loop state to reason about:
+
+- current `automation` status and `verification_status`
+- whether a blocker is `branch_sync_conflict`, `dirty_worktree_conflict`, or another frozen blocker literal
+- whether the selected harness skill pack matches injected metadata or shows installed-skill drift
+- whether the latest OpenCode launch used explicit `<harness> run` metadata for
+  `--agent`, provider-qualified `--model`, optional `--variant`, and recorded
+  permission posture instead of silently accepting permissive defaults
+
+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.
+
+OpenCode is live-supported through the shared runner contract. Keep explicit
+permission posture, selected agent, provider-qualified model, and optional
+reasoning variant visible in launch metadata rather than assuming permissive
+defaults are acceptable.

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

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

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

@@ -0,0 +1,147 @@
+---
+name: opencode-phase-roadmap-builder
+description: "OpenCode-optimized roadmap planner. Use when the user wants to turn a conversation, architecture discussion, or markdown spec into a multi-phase roadmap for later OpenCode 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."
+---
+
+# OpenCode Phase Roadmap Builder
+
+Builds a multi-phase roadmap that downstream `<harness>-plan-phase` can turn into implementation lanes. This is the OpenCode port of the Claude-oriented roadmap builder; do not edit or depend on the original skill at runtime.
+
+## Shared Protocol
+
+Follow `shared/phase-loop/protocol.md` for the shared closeout contract.
+Roadmap-builder closeout must emit `automation:` metadata that agrees with the
+human-readable `Next phase`, `next_skill`, `next_command`, and
+`verification_status` fields.
+
+## 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.
+- 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.
+- 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;
+   - 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 the active session's file-editing tool, 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.
+
+If a roadmap edit changes downstream scope, amend the nearest downstream phase
+that is not already executing and treat any older downstream phase plan or
+handoff as stale until it is regenerated.
+
+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.
+
+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 OpenCode 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.

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