phase-loop-runtime 0.2.0__tar.gz

phase_loop_runtime-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include protocol/protocol.md
+recursive-include src/phase_loop_runtime *.py py.typed
+recursive-include src/phase_loop_runtime/baml_src *.baml
+recursive-include src/phase_loop_runtime/advisor_board *.toml *.md

phase_loop_runtime-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: phase-loop-runtime
+Version: 0.2.0
+Summary: Harness-neutral phase-loop orchestration runtime and CLI
+Author: ViperJuice
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ViperJuice/agent-harness
+Project-URL: Repository, https://github.com/ViperJuice/agent-harness
+Project-URL: Issues, https://github.com/ViperJuice/agent-harness/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: baml-py<0.223,>=0.222
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: consiliency-contract<0.5.0,>=0.3.0
+Requires-Dist: jsonschema<5,>=4
+Requires-Dist: tomli<3,>=2; python_version < "3.11"
+
+# phase-loop-runtime
+
+The harness-neutral **phase-loop** orchestration runtime and CLI. It drives the
+roadmap → plan → execute workflow by dispatching each phase to whatever harness you
+choose (Claude / Codex / Gemini / OpenCode); the runtime itself makes no model calls.
+Part of the public [`agent-harness`](https://github.com/ViperJuice/agent-harness)
+monorepo (Apache-2.0).
+
+## Install
+
+Most users should use the repo's installer (it also installs the workflow skills):
+
+```sh
+git clone https://github.com/ViperJuice/agent-harness
+agent-harness/install-agent-harness.sh --harness claude
+```
+
+To install just this runtime package directly (e.g. as a pinned dependency):
+
+```sh
+# isolated tool install:
+uv tool install "git+https://github.com/ViperJuice/agent-harness@v0.1.5#subdirectory=phase-loop-runtime"
+# …or into the current environment:
+pip install "git+https://github.com/ViperJuice/agent-harness@v0.1.5#subdirectory=phase-loop-runtime"
+```
+
+This exposes two console scripts — `phase-loop` and `codex-phase-loop` — both calling
+`phase_loop_runtime.cli:main`. The canonical protocol document ships in the wheel as
+package data and is also installed to `share/phase-loop-runtime/protocol/protocol.md`.
+
+## Roadmap validation
+
+Lint a phase-plan roadmap spec (required headings, unique aliases, acyclic dependency
+DAG, IF-gate reconciliation, lane-count hints) via the always-installed runtime:
+
+```sh
+phase-loop validate-roadmap specs/phase-plans-v1.md
+# module form — only when phase_loop_runtime is on the ACTIVE python's path (a pip
+# install into your env); under `uv tool install` isolation use the console command:
+python3 -m phase_loop_runtime.roadmap_lint specs/phase-plans-v1.md
+```
+
+Both wrap `phase_loop_runtime.roadmap_lint` (the single source of truth). Exit 0 =
+clean; non-zero prints each issue on stderr.
+
+## Workflow skills bundle
+
+The runtime also installs the harness-neutral workflow-skills bundle. The skill
+sources live in the sibling [`phase-loop-skills/`](../phase-loop-skills) directory,
+with unprefixed base directories and optional `_overrides/<harness>/` overlays.
+
+```sh
+phase-loop install --harness codex --source <path-to>/phase-loop-skills --symlink --dry-run
+phase-loop install --harness codex --source <path-to>/phase-loop-skills --symlink --apply
+```
+
+Path resolution is provided by `phase_loop_runtime.skill_paths`, which keeps handoffs
+repo-local, preserves harness-specific reflection roots, and documents the default
+install roots for Claude, Codex, Gemini, and OpenCode.
+
+## Closeout ownership gate & operator break-glass
+
+When a phase verifies green but the executor touched files outside the plan's declared
+owned-files globs, the **graduated closeout gate** classifies the beyond-ownership
+remainder (`closeout_classifier.classify_unowned_path`):
+
+- SAFE classes (`docs`, `plans`, `handoffs`, `config_nonsource`) auto-commit as a
+  recorded `soft` exception.
+- UNSAFE classes (`source`, `ci`, `secrets`, `lockfile`) block with
+  `closeout_scope_violation`.
+
+The operator escape is `phase-loop run --phase <P> --closeout-allow-unowned "<reason>"`
+(also valid on `resume`/`dry-run`; reason required and non-empty; `--phase` required,
+bounding the override to a single phase). It folds the `source`/`ci`/`lockfile`
+remainder into the closeout commit as a recorded `break_glass` exception carrying the
+reason. **`secrets` are never break-glassable** — a `.env*`/`*.pem`/`secrets/**` path
+blocks regardless of the reason. See `protocol.md` → "Closeout Exceptions".
+
+The closeout verdict is runner-authoritative: when the runner rejects a child's
+closeout, the persisted `terminal-summary.json` reflects the runner's blocking verdict
+(the child's self-reported `complete`/`passed` is not overlaid back), preventing a
+stale "complete" summary from reconcile-skipping the work on the next run.

phase_loop_runtime-0.2.0/README.md

@@ -0,0 +1,82 @@
+# phase-loop-runtime
+
+The harness-neutral **phase-loop** orchestration runtime and CLI. It drives the
+roadmap → plan → execute workflow by dispatching each phase to whatever harness you
+choose (Claude / Codex / Gemini / OpenCode); the runtime itself makes no model calls.
+Part of the public [`agent-harness`](https://github.com/ViperJuice/agent-harness)
+monorepo (Apache-2.0).
+
+## Install
+
+Most users should use the repo's installer (it also installs the workflow skills):
+
+```sh
+git clone https://github.com/ViperJuice/agent-harness
+agent-harness/install-agent-harness.sh --harness claude
+```
+
+To install just this runtime package directly (e.g. as a pinned dependency):
+
+```sh
+# isolated tool install:
+uv tool install "git+https://github.com/ViperJuice/agent-harness@v0.1.5#subdirectory=phase-loop-runtime"
+# …or into the current environment:
+pip install "git+https://github.com/ViperJuice/agent-harness@v0.1.5#subdirectory=phase-loop-runtime"
+```
+
+This exposes two console scripts — `phase-loop` and `codex-phase-loop` — both calling
+`phase_loop_runtime.cli:main`. The canonical protocol document ships in the wheel as
+package data and is also installed to `share/phase-loop-runtime/protocol/protocol.md`.
+
+## Roadmap validation
+
+Lint a phase-plan roadmap spec (required headings, unique aliases, acyclic dependency
+DAG, IF-gate reconciliation, lane-count hints) via the always-installed runtime:
+
+```sh
+phase-loop validate-roadmap specs/phase-plans-v1.md
+# module form — only when phase_loop_runtime is on the ACTIVE python's path (a pip
+# install into your env); under `uv tool install` isolation use the console command:
+python3 -m phase_loop_runtime.roadmap_lint specs/phase-plans-v1.md
+```
+
+Both wrap `phase_loop_runtime.roadmap_lint` (the single source of truth). Exit 0 =
+clean; non-zero prints each issue on stderr.
+
+## Workflow skills bundle
+
+The runtime also installs the harness-neutral workflow-skills bundle. The skill
+sources live in the sibling [`phase-loop-skills/`](../phase-loop-skills) directory,
+with unprefixed base directories and optional `_overrides/<harness>/` overlays.
+
+```sh
+phase-loop install --harness codex --source <path-to>/phase-loop-skills --symlink --dry-run
+phase-loop install --harness codex --source <path-to>/phase-loop-skills --symlink --apply
+```
+
+Path resolution is provided by `phase_loop_runtime.skill_paths`, which keeps handoffs
+repo-local, preserves harness-specific reflection roots, and documents the default
+install roots for Claude, Codex, Gemini, and OpenCode.
+
+## Closeout ownership gate & operator break-glass
+
+When a phase verifies green but the executor touched files outside the plan's declared
+owned-files globs, the **graduated closeout gate** classifies the beyond-ownership
+remainder (`closeout_classifier.classify_unowned_path`):
+
+- SAFE classes (`docs`, `plans`, `handoffs`, `config_nonsource`) auto-commit as a
+  recorded `soft` exception.
+- UNSAFE classes (`source`, `ci`, `secrets`, `lockfile`) block with
+  `closeout_scope_violation`.
+
+The operator escape is `phase-loop run --phase <P> --closeout-allow-unowned "<reason>"`
+(also valid on `resume`/`dry-run`; reason required and non-empty; `--phase` required,
+bounding the override to a single phase). It folds the `source`/`ci`/`lockfile`
+remainder into the closeout commit as a recorded `break_glass` exception carrying the
+reason. **`secrets` are never break-glassable** — a `.env*`/`*.pem`/`secrets/**` path
+blocks regardless of the reason. See `protocol.md` → "Closeout Exceptions".
+
+The closeout verdict is runner-authoritative: when the runner rejects a child's
+closeout, the persisted `terminal-summary.json` reflects the runner's blocking verdict
+(the child's self-reported `complete`/`passed` is not overlaid back), preventing a
+stale "complete" summary from reconcile-skipping the work on the next run.