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

phase_loop_runtime/_contract_docs/phase-loop/harness-skill-matrix.md

@@ -0,0 +1,125 @@
+# Phase-Loop Harness Skill Matrix
+
+This document is the SKILLPACK manifest and canonical skill namespace contract
+for dotfiles-hosted phase-loop workflow skills. It freezes the active harness
+workflow names, source roots, and recommended install roots before bootstrap,
+sync, cleanup, parity, and bridge-soak phases change install behavior or remove
+vestigial paths.
+The path inventory for the public harness substrate is
+`docs/phase-loop/harness-substrate-manifest.md`; this matrix owns workflow
+names only.
+
+Harness workflow skill names follow:
+
+`<harness>-<workflow>`
+
+The rule applies to harness-local workflow skills for Codex, Claude Code,
+Gemini CLI, and OpenCode. Pi Agent role-style skills and governed-pipeline
+`.pipeline/skills/**` are explicit namespace exceptions.
+
+## Canonical Workflow Skills
+
+| Workflow | Codex | Claude Code | Gemini CLI | OpenCode |
+| --- | --- | --- | --- | --- |
+| advisor-board | `codex-advisor-board` | `claude-advisor-board` | `gemini-advisor-board` | `opencode-advisor-board` |
+| phase-roadmap-builder | `codex-phase-roadmap-builder` | `claude-phase-roadmap-builder` | `gemini-phase-roadmap-builder` | `opencode-phase-roadmap-builder` |
+| plan-phase | `codex-plan-phase` | `claude-plan-phase` | `gemini-plan-phase` | `opencode-plan-phase` |
+| execute-phase | `codex-execute-phase` | `claude-execute-phase` | `gemini-execute-phase` | `opencode-execute-phase` |
+| phase-loop | `codex-phase-loop` | `claude-phase-loop` | `gemini-phase-loop` | `opencode-phase-loop` |
+| plan-detailed | `codex-plan-detailed` | `claude-plan-detailed` | `gemini-plan-detailed` | `opencode-plan-detailed` |
+| execute-detailed | `codex-execute-detailed` | `claude-execute-detailed` | `gemini-execute-detailed` | `opencode-execute-detailed` |
+| task-contextualizer | `codex-task-contextualizer` | `claude-task-contextualizer` | `gemini-task-contextualizer` | `opencode-task-contextualizer` |
+| skill-improvement-planner | `codex-skill-improvement-planner` | `claude-skill-improvement-planner` | `gemini-skill-improvement-planner` | `opencode-skill-improvement-planner` |
+| skill-editor | `codex-skill-editor` | `claude-skill-editor` | `gemini-skill-editor` | `opencode-skill-editor` |
+| run-train | `codex-run-train` | `claude-run-train` | `gemini-run-train` | `opencode-run-train` |
+
+Canonical source roots (CANON / IF-0-CANON-1 — the authored skill *sources* now
+live in this repo under `skills-src/<harness>/`; the dotfiles `*-config` roots
+remain valid build inputs during the cutover via an explicit `--source`):
+
+- Codex: `skills-src/codex/**`
+- Claude Code: `skills-src/claude/**`
+- Gemini CLI: `skills-src/gemini/**`
+- OpenCode: `skills-src/opencode/**`
+
+Recommended install roots:
+
+- Codex: `~/.codex/skills`
+- Claude Code: `~/.claude/skills`
+- Gemini CLI: `~/.gemini/skills`
+- OpenCode: `~/.config/opencode/skills`
+
+## Pi Agent Exception
+
+Pi Agent uses role-style skills rather than the `<harness>-<workflow>` harness
+matrix. The intentional exceptions are:
+
+- `phase-loop-supervisor`
+- `phase-loop-repair`
+- `phase-loop-closeout`
+
+These names are allowed because Pi Agent consumes repo-local
+`phase-loop-pi/**` prompts, skills, extensions, and `pi-config/**` installation
+metadata as an adapter role surface. They are not an unnormalized harness
+workflow family.
+
+## Route Compatibility
+
+Direct Codex, direct Gemini, and direct OpenCode launcher routes remain
+compatibility-supported during this roadmap. This contract normalizes workflow
+skill names and metadata; it does not collapse those routes into Pi Agent.
+
+Claude Code execution continues to use the first-party non-interactive
+`claude -p` path. Claude Code bridge and workflow skills describe that route;
+they do not imply Anthropic API-key execution or Pi provider fallback.
+
+## Vestigial Workflow Candidates
+
+Historical unprefixed `claude-config/skills/plan-phase/**` and
+`claude-config/skills/execute-phase/**` are vestigial workflow candidates.
+Current inventory shows handoff and reflection residue under those paths, not
+active `SKILL.md` definitions. They are not deleted, archived, or promoted by
+DFSKILLCONTRACT.
+
+Later cleanup may classify those paths as archived history or remove them only
+after source lookup, bootstrap, sync-skills, expected skill packs, docs, and
+downstream governed-pipeline compatibility proof agree.
+
+DFSKILLCLEAN records the current cleanup classifications and canonical
+replacement names in `docs/phase-loop/legacy-skill-cleanup.md`.
+
+DFSKILLGOVSOAK records the governed bridge compatibility release gate in
+`docs/phase-loop/dfskillgovsoak.md`, including governed-pipeline mirrored
+scenarios, dotfiles-only scenarios, temporary legacy alias rejection coverage,
+and the optional live adapter proof boundary.
+
+## Downstream Namespace Boundary
+
+Governed-pipeline `.pipeline/skills/**` is a separate product/runtime
+namespace. Those skills are governed-pipeline-owned pipeline overlays, not
+dotfiles harness workflow skills, and dotfiles normalization must not rewrite,
+rename, install, or validate them as `<harness>-<workflow>` skills.
+
+Dotfiles closeout and launch metadata may mention canonical harness workflow
+skill names as bridge vocabulary, expected skill pack metadata, or next-action
+metadata. Governed-pipeline remains responsible for `.pipeline/skills/**`
+manifest policy, source-bundle emission, closeout ingest, mirror updates,
+canonical refresh, replan, and projection decisions.
+Downstream consumers must not treat Host bootstrap, Shell config, SSH setup,
+MCP gateway setup, generic 1Password setup, raw/private evidence, provider
+payloads, or local environment values as prerequisites for these workflow skill
+names.
+
+## DFSKILLCONTRACT Gates
+
+- IF-0-DFSKILLCONTRACT-1: this matrix freezes the active
+  `<harness>-<workflow>` names and the Pi role-style exception.
+- IF-0-DFSKILLCONTRACT-2: governed-pipeline `.pipeline/skills/**` is a
+  separate namespace that dotfiles normalization must not rewrite.
+- IF-0-DFSKILLCONTRACT-3: historical unprefixed `plan-phase` and
+  `execute-phase` paths are vestigial workflow candidates for later cleanup.
+- IF-0-DFSKILLCONTRACT-4: direct Codex, direct Gemini, and direct OpenCode
+  routes remain compatibility-supported, and Claude Code continues through
+  `claude -p`.
+- IF-0-SKILLPACK-1: this SKILLPACK manifest freezes the active workflow skill
+  names and install targets for Codex, Claude Code, Gemini, and OpenCode.

phase_loop_runtime/_contract_docs/phase-loop/harness-substrate-manifest.md

@@ -0,0 +1,232 @@
+# Phase-Loop Harness Substrate Manifest
+
+This manifest defines the dotfiles paths that downstream repositories may cite
+as the phase-loop harness substrate. It is a path ownership inventory, not a
+schema contract. Shared artifact shapes remain frozen in
+`shared/phase-loop/protocol.md`, and public runtime interfaces remain listed in
+`docs/phase-loop/runtime-boundary.md`.
+Harness workflow skill names, recommended install roots, Pi Agent role-style
+exceptions, and direct route compatibility are frozen in the SKILLPACK manifest
+at `docs/phase-loop/harness-skill-matrix.md`.
+Downstream repositories may cite only the substrate paths listed here; they
+must not treat broad dotfiles paths as Pipeline-owned authority surfaces.
+IF-0-SUBSTRATE-1 freezes that public substrate inventory as only
+`vendor/phase-loop-runtime/**`, CLI wrappers, bridge skills, shared runner
+skills, protocol docs, fixtures, tests, scripts, and canonical `.phase-loop/**`
+state.
+
+## In-Scope Substrate Paths
+
+Downstream harness and pipeline integrations may cite these paths when they
+need a stable reference to the dotfiles-hosted phase-loop substrate.
+
+### Runtime Code
+
+- `vendor/phase-loop-runtime/src/phase_loop_runtime/**`: phase-loop CLI, discovery, runner,
+  reconciliation, launch, state, profile, maintenance, and rendering code.
+- `phase-loop`: neutral CLI wrapper.
+- `codex-phase-loop`: Codex-compatible CLI alias.
+
+### Bridge Skills
+
+- `codex-config/skills/codex-phase-loop/**`: Codex TUI bridge for phase-loop
+  status, resume, dry-run, and bounded runner workflows.
+- `codex-config/skills/codex-plan-phase/**`: Codex phase planning workflow.
+- `codex-config/skills/codex-execute-phase/**`: Codex phase execution workflow.
+- `codex-config/skills/codex-phase-roadmap-builder/**`: Codex roadmap builder
+  workflow.
+- `codex-config/skills/codex-task-contextualizer/**`: Codex subagent briefing
+  workflow.
+
+### Shared Runner Skills
+
+- `shared/skills/code-cli-runner/**`: shared CLI runner substrate for
+  provider-specific execution skills.
+- `shared/skills/codex-cli-runner/**`: Codex CLI runner guidance.
+- `shared/skills/gemini-cli-runner/**`: Gemini runner guidance — drives the
+  Antigravity (`agy`) CLI (the standalone `gemini` CLI was sunset; the phase-loop
+  gemini executor and this runner both target `agy`).
+
+### Protocol and Runtime Docs
+
+- `shared/phase-loop/protocol.md`: canonical shared artifact, closeout,
+  delegation, state, and execution-policy protocol.
+- `docs/phase-loop/runtime-boundary.md`: public CLI, Python API, artifact, and
+  state boundary.
+- `docs/phase-loop/harness-skill-matrix.md`: canonical harness workflow skill
+  naming matrix, Pi Agent exception list, route compatibility statement, and
+  governed-pipeline `.pipeline/skills/**` namespace guard.
+- `docs/phase-loop/spec-discovery-roots.md`: standalone root `specs/**`
+  discovery and legacy `Specs/**` explicit-input guidance.
+- `docs/phase-loop/dfadoptbridge-fixtures.md`: governed-pipeline v11 adoption
+  bridge fixture matrix and SHA-256 metadata field reference.
+- `docs/phase-loop/dfskillgovsoak.md`: governed bridge compatibility release
+  gate, fixture classification, downstream GPSKILLSOAK evidence summary, and
+  optional live proof boundary.
+- `docs/phase-loop/extraction-readiness.md`: optional future extraction record.
+- `docs/phase-loop/granular-execution-policy.md`: runner-owned model and
+  effort policy guidance.
+- `docs/phase-loop/harness-capability-matrix.md`: adapter capability and proof
+  status.
+- `docs/phase-loop/lane-scheduler.md`: lane-scheduler operator contract.
+- `docs/phase-loop/pi-loop-control.md`: PI loop-control integration boundary.
+- `docs/phase-loop/collaborator-bootstrap.md`: collaborator-safe runtime and
+  harness workflow skill install surface for downstream citation.
+- `docs/phase-loop/collaborator-skill-rollback.md`: rollback and uninstall
+  guidance for installed workflow skill packs.
+
+### Fixtures, Tests, and Scripts
+
+- `tests/test_phase_loop*.py`: phase-loop runtime, bridge, policy, adapter,
+  documentation, and protocol contract tests.
+- `vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/**`: canonical closeout and
+  pipeline bridge fixtures. Downstream repositories may cite this path as
+  dotfiles-owned fixture substrate.
+- `scripts/smoke-codex-phase-loop`: offline phase-loop resume and reentry
+  smoke.
+- `scripts/smoke-phase-loop-live-adapters`: authenticated disposable live
+  adapter proof script.
+
+### Runner State Paths
+
+- `.phase-loop/state.json`: canonical current runtime state.
+- `.phase-loop/events.jsonl`: canonical append-only runtime event ledger.
+- `.phase-loop/active-loop.json`: canonical active-loop metadata.
+- `.phase-loop/runs/<run-id>/`: run-local context, launch metadata, logs, and
+  closeout artifacts.
+- `.phase-loop/tui-handoff.md`: operator-readable handoff.
+- `.codex/phase-loop/**`: legacy read fallback only; new writes use
+  `.phase-loop/**`.
+
+## Out-of-Scope Dotfiles Surfaces
+
+The paths and domains below are environment-normalization surfaces. Downstream
+pipeline and harness integrations must not cite them as phase-loop substrate or
+require them for phase-loop compatibility.
+
+- Host bootstrap outside the listed CLI wrappers, including broad
+  `bootstrap.sh` behavior and machine package setup.
+- Shell config such as `.zshrc`, `.bashrc`, aliases, prompts, completions, and
+  profile fragments.
+- Terminal and Zellij config, including terminal themes, panes, layouts, and
+  local session defaults.
+- SSH configuration, host aliases, private keys, agent setup, and tailnet
+  machine access.
+- Generic 1Password setup, vault layout, personal item names, and credential
+  material.
+- MCP gateway setup and personal gateway server configuration outside an
+  explicit phase-loop bridge contract.
+- Unrelated editor configuration, formatters, language-server preferences, and
+  personal IDE state.
+- Private, ignored, raw-data, credential, and evidence-source files unless a
+  phase plan or source bundle explicitly allowlists the exact path or glob.
+- Provider payloads, raw provider transcripts, raw model outputs, and local
+  environment values.
+
+## Downstream Citation Rules
+
+- Cite this manifest for dotfiles path ownership and in-scope substrate
+  inventory.
+- Cite `shared/phase-loop/protocol.md` for artifact schemas, closeout fields,
+  blocker vocabulary, delegation requests, and execution-policy protocol.
+- Cite `docs/phase-loop/runtime-boundary.md` for public CLI, Python API, state,
+  and artifact paths.
+- Cite `docs/phase-loop/harness-skill-matrix.md` for canonical workflow skill
+  names, Pi Agent exceptions, direct launcher compatibility, and the
+  governed-pipeline `.pipeline/skills/**` namespace boundary.
+- Cite `docs/phase-loop/collaborator-bootstrap.md` when a downstream repo needs
+  the collaborator-safe runtime and workflow skill installation contract
+  without inheriting owner-machine bootstrap behavior.
+- Treat any path not listed in the in-scope substrate section as private to the
+  dotfiles repository unless a future roadmap phase adds it here.
+- Treat governed-pipeline downstream mirror location
+  `packages/pipeline-runtime/test/fixtures/phase-loop-bridge/` as a consumer
+  path. Downstream mirror updates, closeout ingest, canonical refresh, replan, and
+  preflight block decisions are governed-pipeline-owned.
+- Do not treat governed-pipeline mirror paths as dotfiles write targets; the
+  mirror is not a dotfiles write target.
+- Treat root `specs/**` as the default standalone future-spec discovery root
+  only when a plan, source bundle, or repo-local config does not override it.
+  Legacy or project-specific seed roots such as `Specs/**` are explicit input
+  roots only.
+- Treat canonical spec adoption, archive manifests, managed mirror manifests,
+  mirror writes, source-truth reconciliation, source-bundle emission, canonical
+  refresh, replan, and preflight block decisions as governed-pipeline-owned.
+- Treat closeout spec-root citations as metadata-only. Dotfiles may emit
+  repo-relative paths, changed-path categories, hashes, source-bundle identity,
+  protected-source roles, advisory reason codes, and evidence refs, but not raw
+  spec bodies, raw diffs, private evidence bytes, credentials, provider
+  payloads, or local environment values.
+- Do not infer Pipeline ownership, protected-source authority, or permission to
+  read or write `.pipeline/**`, governed-pipeline specs, Portal contracts,
+  Greenfield authority files, private evidence, raw data, credentials, ignored
+  outputs, provider-supplied data, legacy `.codex/phase-loop/` state, or local
+  environment files from a broad dotfiles checkout path.
+- Shared runner skill examples must keep Portal and Greenfield mediated through
+  governed-pipeline closeout ingest, Portal projection, and Greenfield metadata-only authority refs. Governed Pipeline owns that closeout ingest boundary. Those references are not direct dotfiles write targets, and they do not make governed-pipeline, Portal, Greenfield,
+  `.pipeline/**`, or a source bundle mandatory for standalone dotfiles
+  planning, execution, bridge, or CLI runner use.
+
+## DFTRUTHSOAK Evidence Surface
+
+DFTRUTHSOAK consumes only the listed substrate paths as dotfiles-owned
+evidence: local standalone closeout behavior, pipeline-required source-bundle
+diagnostics, stale-input blockers, source-truth advisory hints, bridge
+fixtures, and downstream mirror refs. Governed-pipeline remains the owner of
+mirror updates, closeout ingest, canonical refresh, replan, and preflight block
+decisions. Portal projection and Greenfield metadata-only authority refs stay
+contract-mediated downstream evidence and are not direct dotfiles write
+targets.
+
+## DFADOPTBRIDGE Fixture Surface
+
+DFADOPTBRIDGE adds adoption complete, blocked adoption metadata, stale source
+bundle, stale mirror manifest, unmanaged spec input, archive manifest touched,
+standalone non-adoption, deprecated-alias rejection, and redaction rejection
+fixtures under `vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/`. The fixtures are
+metadata-only `phase_loop_closeout.v1` examples for governed-pipeline v11
+adoption ingest. They may be mirrored by governed-pipeline under
+`packages/pipeline-runtime/test/fixtures/phase-loop-bridge/`, but dotfiles does
+not write that downstream mirror path.
+
+Pipeline-required DFADOPTBRIDGE fixtures cite `source_bundle.path`,
+`source_bundle.sha256`, `source_bundle.phase_id`,
+`source_bundle.protected_sources[].path`,
+`source_bundle.protected_sources[].sha256`,
+`source_bundle.protected_sources[].role`, `artifacts.plan_sha256`, and
+`artifacts.evidence_refs[].sha256`. Standalone non-adoption coverage omits
+Pipeline-only bundle identity. The fixtures do not include raw spec bodies, raw
+diffs, provider-supplied data, credentials, local environment values, private
+evidence, or absolute private paths.
+
+## DFADOPTSOAK Release-Gate Boundary
+
+DFADOPTSOAK is the local integration soak for this substrate. It covers
+standalone root `specs/**` advisory closeout hints, explicit non-default
+spec-root intake metadata, unconfigured non-default root non-advisory behavior,
+pipeline-required source-bundle echo, stale-input blockers, v14 bridge fixture
+retention, DFADOPTBRIDGE fixture parity, and unittest-first verification.
+
+The phase consumes governed-pipeline `CADOPTSOAK` as read-only upstream
+metadata. Governed-pipeline remains responsible for mirror copies, adoption
+decisions, archive creation, managed mirror refresh, source-truth
+reconciliation, source-bundle emission, canonical refresh, replan, and preflight
+block decisions. DFADOPTSOAK does not make governed-pipeline, Portal,
+Greenfield, `.pipeline/**`, raw source evidence, raw data, credentials, local
+environment values, ignored outputs, or legacy `.codex/phase-loop/**` state
+dotfiles write targets.
+
+## DFSKILLGOVSOAK Release-Gate Boundary
+
+DFSKILLGOVSOAK is the final v16 normalization release gate for this substrate.
+It consumes dotfiles bridge fixtures, expected skill-pack metadata, launcher
+dry-run proof, documentation checks, and governed-pipeline GPSKILLSOAK as
+read-only evidence. Governed-pipeline mirrored scenarios and dotfiles-only
+scenarios are classified in `vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/README.md`
+and `docs/phase-loop/dfskillgovsoak.md`.
+
+The phase does not require optional live adapter proof and does not authorize
+dotfiles writes to governed-pipeline mirror fixtures, `.pipeline/**`, Portal
+files, Greenfield files, raw/private evidence, credential material, local
+environment values, provider-supplied data, `.phase-loop/**`, or legacy
+`.codex/phase-loop/**` state.

phase_loop_runtime/_contract_docs/phase-loop/pi-loop-control.md

@@ -0,0 +1,247 @@
+# PI Loop Control
+
+The PI package in `phase-loop-pi/` is a minimal operator harness for the neutral phase-loop runner. PI does not own the state machine. The Python `phase-loop` CLI remains authoritative for roadmap selection, phase reconciliation, closeout policy, blockers, handoffs, and monitor events.
+
+## Roles
+
+- `phase-loop`: neutral runner command for CLI, TUI, PI, and other harnesses.
+- `codex-phase-loop`: Codex bridge alias for existing Codex skills and scripts.
+- `.phase-loop/`: canonical runtime artifact root for state, events, runs, stop files, handoffs, active-loop locks, and archives.
+- `.codex/phase-loop/`: legacy compatibility root that remains readable and excluded from git during migration.
+- PI loop control: observes state, runs bounded loop steps, triages non-human blockers, and performs commit-only closeout when explicitly selected.
+- Child harnesses: Codex, Claude Code, Gemini, OpenCode, Pi Agent, or command adapters implement individual roadmap/plan/execute turns.
+
+Pi Agent as `executor=pi` is the preferred simple bounded lane runner. It is
+still a child executor, not the global scheduler, runtime ledger owner,
+worktree allocator, or merge reducer.
+
+Granular execution policy lives at
+`docs/phase-loop/granular-execution-policy.md`. PI should preserve the runner's high -> medium -> high posture: high planning, medium lane execution and repair, and high reducer/review/verify work.
+
+## Install Or Load
+
+Local install:
+
+```bash
+pi install <HOME-REDACTED>/code/dotfiles/phase-loop-pi -l
+```
+
+Direct load when supported by the PI CLI:
+
+```bash
+pi -e <HOME-REDACTED>/code/dotfiles/phase-loop-pi/extensions/phase-loop-tools.ts \
+  -e <HOME-REDACTED>/code/dotfiles/phase-loop-pi/extensions/phase-loop-guardrails.ts \
+  --skill <HOME-REDACTED>/code/dotfiles/phase-loop-pi/skills/phase-loop-supervisor
+```
+
+## Run
+
+Inspect before launch:
+
+```bash
+phase-loop state --repo /path/to/repo --roadmap specs/phase-plans-v1.md --json
+phase-loop monitor --repo /path/to/repo --roadmap specs/phase-plans-v1.md --once --json
+```
+
+Bounded supervised run:
+
+```bash
+phase-loop run --repo /path/to/repo --roadmap specs/phase-plans-v1.md --max-phases 1 --observe
+```
+
+PI wrapper run for an existing roadmap:
+
+```bash
+pi-agent-watch \
+  --repo /path/to/repo \
+  --roadmap specs/phase-plans-v1.md \
+  --phase-executor codex \
+  --max-phases 10 \
+  --closeout-mode commit \
+  --timeout-seconds 14400 \
+  --json
+```
+
+Bounded provider rotation keeps PI's provider model separate from the nested
+child executor. Examples:
+
+```bash
+pi-agent-watch --repo /path/to/repo --roadmap specs/phase-plans-v1.md --phase-executor gemini --closeout-mode manual --json
+pi-agent-watch --repo /path/to/repo --roadmap specs/phase-plans-v1.md --phase-executor opencode --closeout-mode commit --json
+pi-agent-watch --repo /path/to/repo --roadmap specs/phase-plans-v1.md --phase-executor pi --closeout-mode manual --json
+pi-agent-watch --repo /path/to/repo --roadmap specs/phase-plans-v1.md --phase-executor command --closeout-mode manual --json
+```
+
+Automatic push is not a published default. Use manual closeout for inspection
+and commit-only closeout when verified phase-owned output should be preserved
+locally.
+
+`pi-agent-watch` is the appropriate PI entrypoint when a roadmap already
+exists. Roadmap-builder commands are only for creating or extending roadmap
+artifacts, not for consuming an execution-ready roadmap.
+
+PI supervisor prompt:
+
+```text
+Use the phase-loop-supervisor skill. Inspect phase-loop state for /path/to/repo and specs/phase-plans-v1.md. If no active run or human blocker exists, run the existing roadmap through phase_loop_run and report the monitor outcome.
+```
+
+## Watch And Callbacks
+
+Use `phase_loop_monitor` for a one-shot state check. Use `phase_loop_watch` when
+the operator wants PI to wait by exception, a check-by-exception pattern, instead of repeatedly polling by
+hand. Watch mode calls the neutral runner monitor without `--once`, exits on a
+terminal or exception event, and can invoke a local notification command.
+
+Equivalent CLI:
+
+```bash
+phase-loop monitor \
+  --repo /path/to/repo \
+  --roadmap specs/phase-plans-v1.md \
+  --poll-seconds 60 \
+  --timeout-seconds 3600 \
+  --notify-on blocked \
+  --notify-on stale \
+  --notify-on complete \
+  --notify-command 'python3 /path/to/write-phase-loop-event.py' \
+  --json
+```
+
+`notifyCommand` receives the runner notification payload on stdin. Keep
+notification commands local and metadata-only: write an event file, send a
+desktop notification, or call a harness-specific adapter. Watch mode does not guarantee that every TUI can receive an async message unless that TUI provides a
+callback adapter that consumes the notification.
+
+## PI Agent Observability
+
+`phase_loop_watch` lets PI watch the phase loop. `pi-agent-watch` lets an
+outside supervisor watch PI itself. It launches PI with this package loaded and
+writes neutral controller-process artifacts under the target repo:
+
+- `.phase-loop/pi-agent.json`
+- `.phase-loop/pi-agent.log`
+- `.phase-loop/pi-agent-terminal.json`
+
+Example:
+
+```bash
+pi-agent-watch \
+  --repo /path/to/repo \
+  --roadmap specs/phase-plans-v1.md \
+  --provider anthropic \
+  --model claude-opus-4-8 \
+  --thinking high \
+  --max-phases 1 \
+  --closeout-mode commit \
+  --poll-seconds 30 \
+  --timeout-seconds 3600 \
+  --json
+```
+
+PI's provider is independent from the nested phase executor. To supervise with
+PI on an available provider while running phase work through Claude Code CLI,
+set `--phase-executor claude`:
+
+```bash
+pi-agent-watch \
+  --repo /path/to/repo \
+  --roadmap specs/phase-plans-v1.md \
+  --provider openai-codex \
+  --model gpt-5.5 \
+  --thinking high \
+  --phase-executor claude \
+  --claude-execution-mode agent_team \
+  --timeout-seconds 3600 \
+  --json
+```
+
+When PI is launched with `--provider anthropic` and no explicit model, the
+wrapper defaults to `claude-opus-4-8` with `--thinking high` so Anthropic-backed
+supervision uses the heavy model tier by default.
+
+The PI provider model and the nested phase executor model are separate knobs.
+Use `--model` for the model backing PI's loop-control reasoning. Use
+`--phase-model` when the child phase-loop executor must receive an explicit
+model. For Gemini child execution, prefer `--phase-executor gemini` with no
+`--phase-model` so phase-loop can use Gemini CLI routing defaults: `pro` for
+planning/review and `auto` for execution/repair. Use `--phase-model` only for
+explicit proof runs that intentionally pin a custom phase-loop alias or concrete
+model.
+
+Read `.phase-loop/pi-agent.json` before tailing PI logs. It reports PI process
+PID, liveness, elapsed time, seconds since PI output, quiet level, terminal
+status, and the log/terminal artifact paths. `.phase-loop/pi-agent.log` captures
+PI stdout/stderr with secret-shaped values redacted when surfaced through the
+wrapper. These artifacts describe PI controller-process health only; the Python
+`phase-loop` state remains authoritative for roadmap state.
+
+The wrapper launches PI with an explicit `phase_loop_*` tool allowlist, session
+persistence disabled, and ambient context-file loading disabled. That keeps the
+controller focused on the injected phase-loop tools instead of shell-searching
+for runner binaries or carrying state between repos. It also passes
+`PHASE_LOOP_DEFAULT_REPO` and
+`PHASE_LOOP_DEFAULT_ROADMAP` into the extension environment so the tools can
+fall back to the wrapper target if PI emits an empty or nested argument object.
+When `--phase-executor` is provided, it also passes
+`PHASE_LOOP_DEFAULT_EXECUTOR` so `phase_loop_run` deterministically launches the
+requested child harness. When `--claude-execution-mode` is provided, it passes
+`PHASE_LOOP_DEFAULT_CLAUDE_EXECUTION_MODE` so Claude Code can run in `solo`,
+`subagent`, or `agent_team` mode through the phase-loop launcher. Native
+subagents, task lists, teammates, and team delegation remain gated by the
+runner's TEAMGOV eligibility checks; the wrapper only requests the mode.
+When `--max-phases` or `--closeout-mode` is provided, it also passes
+`PHASE_LOOP_DEFAULT_MAX_PHASES` and `PHASE_LOOP_DEFAULT_CLOSEOUT_MODE` so the
+supervisor can call `phase_loop_run` with deterministic loop depth and closeout
+policy instead of relying on prompt prose.
+
+For `executor=pi` lane launches, the phase-loop launcher writes a context-file
+prompt from repo-local `phase-loop-pi/**` and `pi-config/**` sources. That
+prompt must carry the explicit system prompt, tool policy, allowed writes,
+read-only refs, forbidden refs, output roots, verification intent, Greenfield
+authority citations when present, governed-pipeline assignment fields
+(`lane_id`, `wave_id`, `worktree_path`, `base_sha`, `isolation_mode`,
+`owned_files`, `read_only_refs`, `harness_route`, `model`, `effort`, and
+`fallback_reason`), and the shared `automation:` / `phase_loop_closeout.v1`
+closeout requirements. DFPROMPTSYNC records the prompt-safe contract map at
+`docs/phase-loop/dfpromptsync-contract-map.md`.
+
+If `pi --provider anthropic` fails because PI lacks Anthropic API or OAuth
+environment credentials, that does not imply Claude Code CLI is unavailable.
+Use another PI provider for supervision and `--phase-executor claude` when the
+desired child work should use the local `claude` CLI subscription session.
+Validate that child path with metadata-only `claude auth status`.
+
+## Blocker Handling
+
+Use `phase_loop_state` first, then `phase_loop_handoff`, `phase_loop_monitor`, and bounded `tail_run_log` only when the state points to a specific log. PI must not infer completion from narrative logs. `human_required=true` is never bypassed.
+
+For `human_required=false` blockers, PI can propose or perform mechanical repair using the `phase-loop-repair` skill, then call `phase_loop_resume` and re-check machine state.
+
+## Closeout
+
+Default policy is manual. Commit-only closeout is the middle ground for preserving verified phase-owned output without triggering remote CI/CD. Push remains explicit operator policy.
+
+Before closeout, confirm:
+
+- `verification_status=passed`
+- `human_required=false`
+- dirty paths are phase-owned
+- `git diff --check` passes
+
+## Decoupling
+
+The PI package calls `phase-loop`, not `codex-phase-loop`. It does not require Codex skills, Codex TUI state, or `.codex/phase-loop/` as the canonical artifact root. Repos with legacy `.codex/phase-loop/` state remain readable so existing loops are not stranded during migration.
+
+For MIGRATELOOP lane scheduling, PI must read canonical `.phase-loop/` state
+and pass `--lane-scheduler serialized` only when the operator intentionally
+opts into runner-owned lane work units. Plain `phase-loop run --max-phases 1`
+remains the coarse compatibility path.
+
+## DFPARSOAK Integrated Soak
+
+DFPARSOAK consumes the Pi default route through
+`docs/phase-loop/dfparsoak-receipt.md` and
+`docs/phase-loop/dfparsoak-runbook.md`. Pi remains a bounded child runner for
+scheduler-assigned lanes; it does not own scheduling, merge reduction, or
+destructive worktree cleanup.