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

phase_loop_runtime/__init__.py

@@ -0,0 +1,20 @@
+"""Codex phase loop runner."""
+
+__all__ = [
+    "__version__",
+    "cli",
+    "discovery",
+    "handoff",
+    "maintenance",
+    "models",
+    "observability",
+    "profiles",
+    "reconcile",
+    "render",
+    "runtime_paths",
+    "runner",
+    "state",
+    "state_ops",
+]
+
+__version__ = "0.2.0"

phase_loop_runtime/_contract_docs/phase-loop/extraction-readiness.md

@@ -0,0 +1,90 @@
+# Phase-Loop Extraction Readiness
+
+This document evaluates whether the phase-loop runtime should be extracted from the `dotfiles` repository into a standalone shared agent runtime repo.
+
+## Decision Summary
+
+**Current Status**: Package-ready boundary, extraction not yet performed.
+
+The phase-loop runtime has achieved sufficient architectural maturity and interface stability to be prepared for a standalone repository. The boundary between personal machine configuration (dotfiles) and shared agent orchestration (phase-loop) is now clearly defined, but this roadmap does not move code, create a submodule, or rewrite installation.
+The concrete path boundary is recorded in
+`docs/phase-loop/harness-substrate-manifest.md`; extraction readiness depends
+on that manifest rather than an implicit dotfiles-wide ownership claim.
+If extraction happens later, the standalone repository and package identity is
+`phase-loop-runtime`; it keeps the Python import package `phase_loop_runtime`, the
+neutral command `phase-loop`, and the backward-compatible alias
+`codex-phase-loop`.
+
+Extraction is not required for governed-pipeline v7 execution. Governed-pipeline
+may continue using the current documented CLI, schema, bridge fixture, closeout,
+and canonical `.phase-loop/` state surfaces before and after extraction.
+
+## Evaluation Criteria
+
+| Criterion | Evaluation | Status |
+| :--- | :--- | :--- |
+| **Interface Stability** | The `phase_loop_closeout.v1` schema and CLI surface are frozen in `shared/phase-loop/protocol.md`. | **Passed** |
+| **API Boundary** | A public Python API and CLI entrypoint are documented in `docs/phase-loop/runtime-boundary.md`. | **Passed** |
+| **Cross-Repo Compatibility** | Fixtures for downstream ingestion exist under `vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/`. | **Passed** |
+| **Independence** | Proven mechanically by the DECOUPLE Gate-A clean-room harness (`vendor/phase-loop-runtime/scripts/gate_a_cleanroom.sh`, `tests/test_gate_a_wheel_isolation.py`), which builds a wheel and installs it into an isolated venv with no dotfiles checkout reachable + user-site disabled, in BOTH plugin configurations. (1) Default fleet install (the in-tree dotfiles profile registered under `phase_loop_runtime.profile_commands`): `adoption-bundle`/`sync-skills`/`build-bundle`/`hotfix` are present (each exactly once) and `version`/`status`/`dry-run`/`execute --bundle` + the gp bridge smoke run. (2) The seam (the `profile_commands` group stripped from the installed dist-info): those commands are absent. In BOTH, no resolved import / BAML / skill-root / manifest / command path points under the dotfiles checkout, and `baml_src` resolves via `importlib.resources` package-data. DECOUPLE proves path-independence + the plugin seam in place; physically splitting the dotfiles profile (and its skill roots) into a separate distribution is EXTRACT. | **Passed (Gate A, both configs)** |
+| **Installation Parity** | `bootstrap.sh` can still install phase-loop (as a submodule or package) without breaking dotfiles. | **Passed** |
+| **Substrate Manifest** | `docs/phase-loop/harness-substrate-manifest.md` separates phase-loop substrate paths from host bootstrap, shell, terminal, SSH, generic 1Password, MCP gateway, and unrelated editor configuration. | **Passed** |
+
+## Remaining Package Prerequisites
+
+Before a standalone repository or package move, the extraction owner must:
+
+- Use `phase-loop-runtime` as the package/repository name and choose only the
+  publish strategy.
+- Move only the manifest-listed substrate paths; do not include host bootstrap,
+  shell profile setup, terminal setup, SSH config, generic 1Password setup, MCP
+  gateway setup, unrelated editor configuration, private data, ignored raw data,
+  credentials, evidence-source files, or runner state.
+- Preserve the neutral `phase-loop` command and the backward-compatible
+  `codex-phase-loop` alias.
+- Preserve canonical `.phase-loop/` writes and legacy `.codex/phase-loop/`
+  read fallback behavior.
+- Preserve `phase_loop_closeout.v1`, `phase-source-bundle.v1`, and direct
+  `execute <phase> --bundle --output --mode execute|repair|review` behavior.
+- Add package metadata and CI that run the runtime-boundary, CLI, docs, bridge
+  fixture, adapter proof, and py_compile checks without shell profile sourcing,
+  dotfiles-specific credentials, provider live credentials by default, or
+  ambient `~/.codex` state.
+
+## Extraction Risks and Mitigations
+
+| Risk | Mitigation |
+| :--- | :--- |
+| **Drift** | Use the standalone repo as a git submodule in `dotfiles` to ensure local testing remains valid. |
+| **Dependency Management** | Maintain a strict `requirements.txt` or `pyproject.toml` that doesn't assume dotfiles environments. |
+| **Secret Management** | Keep core imports, parser construction, status rendering, direct bridge diagnostics, and runtime path helpers independent of 1Password, Vercel, Supabase, and other dotfiles-specific credentials. |
+
+## Migration Path
+
+1. **Confirm Move Set**: Use `docs/phase-loop/harness-substrate-manifest.md` and `docs/phase-loop/runtime-boundary.md` as the exact allowlist for source, tests, fixtures, docs, scripts, and wrapper files.
+2. **Move Source**: Relocate only `vendor/phase-loop-runtime/src/phase_loop_runtime/**`, `phase-loop`, `codex-phase-loop`, `shared/phase-loop/protocol.md`, `tests/test_phase_loop*.py`, `vendor/phase-loop-runtime/tests/fixtures/phase_loop_pipeline_bridge/**`, `scripts/smoke-codex-phase-loop`, `scripts/smoke-phase-loop-live-adapters`, and the in-scope `docs/phase-loop/*.md` runtime docs named by the manifest.
+3. **Exclude Dotfiles Environment State**: Do not move host bootstrap outside the listed wrappers, shell config, terminal or Zellij config, SSH config, generic 1Password setup, MCP gateway setup, unrelated editor config, private data, ignored raw data, credentials, evidence-source files, `.phase-loop/**` runner state, or `.codex/phase-loop/**` legacy state.
+4. **Submodule or Package Integration**: Integrate `phase-loop-runtime` back into `dotfiles` as a submodule or package while preserving existing bootstrap behavior.
+5. **Alias Compatibility**: Maintain `phase-loop` and `codex-phase-loop` as separate backward-compatible entrypoints over the same `phase_loop_runtime.cli` parser.
+6. **CI Handoff**: Run runtime-boundary, CLI, docs, bridge fixture, adapter proof, and py_compile checks in default CI without provider credentials; keep authenticated live adapter proof opt-in.
+
+## Downstream Expectations
+
+Downstream repositories (e.g., `governed-pipeline`) should consume the phase-loop runtime via:
+- The frozen `phase_loop_closeout.v1` schema.
+- The standard CLI `execute` command with `--bundle`, `--output`, and
+  `--mode execute|repair|review`; unsupported modes and stale
+  `phase-source-bundle.v1` inputs fail as typed non-human contract blockers.
+- The cross-repo fixtures provided for integration testing.
+- The path inventory in `docs/phase-loop/harness-substrate-manifest.md` when
+  they need to cite dotfiles-hosted harness substrate files.
+
+For governed-pipeline v7, extraction is a non-blocking deployment choice rather
+than a prerequisite. SUBSTRATESOAK may continue against the dotfiles-hosted
+runtime boundary and the same documented surfaces.
+
+## Decision Record
+
+- **Isolated vs. Extracted**: Extraction remains a future option to allow the agent runtime to evolve independently of personal machine setup.
+- **Impact on Dotfiles**: No impact on existing installation flows. `bootstrap.sh` remains the authoritative entrypoint for local setup.
+- **Current Roadmap Boundary**: RUNNERPACK records package prerequisites only; it does not create a submodule, move code, or rewrite bootstrap installation behavior.

phase_loop_runtime/_contract_docs/phase-loop/granular-execution-policy.md

@@ -0,0 +1,137 @@
+# Granular Execution Policy
+
+PROFILEDOC freezes the v8 policy posture: high -> medium -> high. Roadmap and phase planning use high or xhigh-capable heavy profiles, lane execution uses medium effort by default, repair remains medium, and reducer, review, verify, skill-maintenance, and runner-owned closeout guidance use high effort. This document is the operator source of truth until v9 moves lane scheduling into runner-owned work units.
+
+## Default profiles
+
+| Product action | Work unit | Default posture | Gemini CLI default model |
+| --- | --- | --- | --- |
+| `roadmap` | `roadmap_build` | high planning | `pro` |
+| `plan` | `phase_plan` | high planning | `pro` |
+| `execute` | `lane_execute` | medium implementation | `auto` |
+| `repair` | `repair` | medium repair | `auto` |
+| `review` | `lane_review` | high review | `pro` |
+| `maintain-skills` | `phase_verify` | high reducer/verify | `pro` |
+
+Closeout stays runner-owned. Manual closeout remains the default, commit-only is the bounded preservation mode after verification, and automatic push is not promoted by PROFILEDOC.
+
+## Policy precedence
+
+Execution policy resolution is deliberately boring and fail-closed:
+
+1. CLI/operator override.
+2. phase-plan policy.
+3. roadmap policy.
+4. `Dispatch Hints`.
+5. registry defaults.
+
+An unsupported model, effort, executor, or capability blocks unless the active policy names an explicit fallback or says to inherit the provider default. Silent provider fallback is not allowed.
+
+## Provider selection
+
+Codex is the default live-supported executor for roadmap, plan, repair, review, and skill-maintenance work. It accepts normalized model and effort metadata directly through the phase-loop launcher.
+
+Simple bounded scheduler-assigned lane execution defaults to Pi Agent. Claude or Anthropic model lanes are the exception: they default to Claude Code CLI unless a phase plan, roadmap, or operator policy explicitly selects a Pi-wrapped Claude route and records the override reason.
+
+Claude Code is proof-blocked for autonomous live closeout. Operators may use Claude Code bridge skills for manual reentry, and runner-brokered Claude child work must stay typed, bounded, and limited to approved `execute`, `repair`, or `review` work.
+
+Gemini CLI is live-supported through the GEMPROBE result `gemini_cli_config_unverified_but_usable`. Default Gemini dispatch uses the CLI's built-in routing aliases: `pro` for planning/review and `auto` for execution/repair. This preserves Gemini CLI fallback behavior and avoids hard-pinning `gemini-3.1-pro-preview` for normal runs. Run-local user-scope `modelConfigs.customAliases` with `thinkingConfig.thinkingLevel` remain available only for explicit phase-loop proof or policy runs that need that stronger thinking-level assertion. Codex and Gemini fallback routes are CLI-based and reason-coded; they must not silently switch to API-key command adapters unless policy explicitly selects `executor=command`. Future Gemini API adapter work is a separate roadmap decision if the CLI route stops meeting the contract.
+
+Pi Agent is the preferred simple bounded lane runner when the phase-loop policy
+selects `executor=pi`. It consumes repo-local `phase-loop-pi/**` and
+`pi-config/**` material through a context-file launch, supports low/medium/high
+effort mapping, and fails closed for unsupported effort or tool-policy requests
+unless the phase policy explicitly provides fallback behavior.
+
+OpenCode is live-supported with explicit permission posture and model provenance recorded in launch metadata. Use it for bounded child work only when the phase policy allows that executor.
+
+The generic command adapter is experimental. It is context-file only, opt-in, and must not pretend arbitrary subprocesses support the same model, effort, auth, or closeout semantics as first-class harnesses.
+
+## Provider rotation examples
+
+Use Codex for the normal bounded path:
+
+```bash
+phase-loop run --repo <repo> --roadmap <roadmap> --executor codex --max-phases 1
+```
+
+Use Gemini CLI with the default routing contract:
+
+```bash
+phase-loop run --repo <repo> --roadmap <roadmap> --executor gemini --max-phases 1 --closeout-mode manual
+```
+
+Use OpenCode for an explicitly allowed phase:
+
+```bash
+phase-loop run --repo <repo> --roadmap <roadmap> --executor opencode --max-phases 1 --closeout-mode commit
+```
+
+Use Claude Code only with the current proof-blocked closeout posture:
+
+```bash
+phase-loop run --repo <repo> --roadmap <roadmap> --executor claude --max-phases 1 --closeout-mode manual
+```
+
+Use a generic command adapter only when the roadmap or phase plan names the wrapper and owned files:
+
+```bash
+phase-loop run --repo <repo> --roadmap <roadmap> --executor command --max-phases 1 --closeout-mode manual
+```
+
+## Metrics and provenance
+
+Every launched work unit records selected harness, model, effort, profile source, policy source, override reason, fallback status, fallback reason, duration, and blocker class in `.phase-loop/metrics.jsonl` and run launch metadata. The metrics prove what was attempted; they do not expose prompts, secrets, OAuth material, command stdout that may contain credentials, or raw provider payloads.
+
+During MIGRATELOOP, review `.phase-loop/metrics.jsonl` before provider
+rotation or scheduler promotion. Serialized lane scheduling may compare
+executor outcomes, but push remains explicit and must not become an automatic
+result of a clean metric row.
+
+## Dispatch Hints
+
+`Dispatch Hints` remain valid when no richer execution policy is present. They may select allowed executors and required capabilities, but they do not authorize unmanaged parallel write targets, dangerous fallback credentials, or silent provider fallback.
+
+`Execution Policy` is limited to model, effort, work-unit defaults,
+lane-specific policy, fallback, policy source, and override reason. Supported
+selectors are `work-unit defaults`, `roadmap`, `plan`, `execute`, `repair`,
+`review`, `maintain-skills`, and lane selectors such as `SL-2`; reducer and
+verification work uses lane selectors with `work-unit=phase_reducer` or
+`work-unit=phase_verify`. Selectors such as `reduce` and `verify` remain
+invalid, and policy precedence stays CLI/operator override, phase-plan policy,
+roadmap policy, `Dispatch Hints`, then registry defaults. A silent downgrade
+or silent provider fallback is forbidden without explicit policy support.
+
+Policy examples must preserve standalone dotfiles workflows and keep
+governed-pipeline closeout ingest, Portal projection, and Greenfield metadata-only authority refs as mediated boundaries, not direct dotfiles write targets. Executor policy never authorizes inferred writes to `.pipeline/**`,
+governed-pipeline specs, Portal contracts, Greenfield authority files, provider
+payloads, credentials, raw evidence, or legacy `.codex/phase-loop/` state.
+
+DFTRUTHSOAK reducer and verification work use lane selectors with
+`work-unit=phase_verify`; execution policy still only carries model, effort,
+work-unit defaults, lane-specific policy, fallback, policy source, and override
+reason. The final truth soak may report standalone closeout, pipeline-required
+closeout, stale-input blockers, source-truth advisory hints, bridge fixtures,
+and downstream mirror refs, but governed-pipeline remains the canonical
+authority for refresh, replan, preflight block, Portal projection, and
+Greenfield metadata-only authority decisions.
+
+DFPROMPTSYNC freezes the prompt-safe field map in
+`docs/phase-loop/dfpromptsync-contract-map.md` and the readiness receipt in
+`docs/phase-loop/dfpromptsync-readiness.md`. Execution policy examples should
+preserve machine-verified disjoint lanes, scheduler-owned worktree assignments,
+Claude Code CLI exception wording, and CLI-based reason-coded Codex/Gemini
+fallback without introducing API-key fallback or prompt-only containment
+claims.
+
+## V9 boundary
+
+PROFILEDOC does not add runner-owned lane scheduling. v9 consumes this default profile and provenance contract before changing lane waves, review reducers, or child work-unit scheduling.
+
+## DFPARSOAK Integrated Soak
+
+DFPARSOAK policy examples use `docs/phase-loop/dfparsoak-receipt.md` and
+`docs/phase-loop/dfparsoak-runbook.md` for final integrated soak evidence
+instead of older downstream plan examples. The receipt preserves Pi default,
+Claude Code CLI exception, Codex CLI fallback, and Gemini CLI fallback metadata
+without introducing API-key fallback or prompt-only containment claims.