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

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/references/roadmap-template.md

@@ -0,0 +1,193 @@
+# Roadmap Template (`specs/phase-plans-v<N>.md`)
+
+Emit this exact structure. Heading names are stable IDs that `/claude-plan-phase` parses — do not rename, reorder, or drop required sections.
+
+```markdown
+# <Project Name> — Phase Plan v<N>
+
+> How to use this document: save to `specs/phase-plans-v<N>.md`, then run `/claude-plan-phase <ALIAS>` to produce the lane-level plan for each phase (→ `plans/phase-plan-v<N>-<alias>.md`), then `/claude-execute-phase <alias>` to build it.
+
+---
+
+## Context
+
+<One-page synthesis: the problem, the current state, the refactor/build thesis. Lead with the *why*. If existing code already contains raw material for the refactor, name it — future lane teammates will reuse rather than rewrite.>
+
+---
+
+## Architecture North Star
+
+<ASCII diagram of the target architecture. Optional but load-bearing for structural work. Omit for pure-feature roadmaps where architecture isn't changing.>
+
+```
+  ┌─────────────┐
+  │   Layer A   │
+  └──────┬──────┘
+         │
+  ┌──────▼──────┐
+  │   Layer B   │
+  └─────────────┘
+```
+
+---
+
+## Assumptions (fail-loud if wrong)
+
+1. <Precondition that, if false, invalidates the plan>
+2. ...
+
+---
+
+## Non-Goals
+
+- <Explicitly deferred>
+- ...
+
+---
+
+## Cross-Cutting Principles
+
+1. <Rule that applies across every phase>
+2. ...
+
+---
+
+## Phase Dependency DAG
+
+```
+  P1  <short phase name>
+   │
+   ▼
+  P2A  <name>
+   │
+   ▼
+  P2B  <name>
+   │
+   ▼
+  P3   <name>
+   │
+   ▼
+  P4   <name>
+
+  P6A  <parallel branch>   parallel after P1
+  P6B  <parallel branch>   parallel after P4
+```
+
+---
+
+## Top Interface-Freeze Gates
+
+These gates are the narrowest contracts that unblock downstream phases. `/claude-plan-phase` concretizes each (exact signature/schema) when it plans the owning phase.
+
+1. **IF-0-P1-1** — <symbol / type / endpoint / migration with enough detail to be unambiguous>
+2. **IF-0-P2A-1** — ...
+
+---
+
+## Phases
+
+### Phase 1 — <Name> (P1)
+
+**Objective**
+<One or two sentences stating what this phase achieves.>
+
+**Exit criteria**
+- [ ] <Testable assertion. Checkable by shell command or integration test, not vibes.>
+- [ ] <Testable assertion.>
+
+**Scope notes**
+- <Lane decomposition hint: e.g., "decompose into 3 lanes: (a) identity module, (b) registry updates, (c) walker changes — each owns disjoint files".>
+- <Parallelism advice: e.g., "lane (b) depends on lane (a)'s `compute_repo_id` signature; lane (a) publishes it as IF-0-P1-1 before the others start".>
+- <Single-writer files: any shared file where only one lane may write. List the owner lane here so downstream claude-plan-phase runs respect it.>
+
+**Non-goals**
+- <Explicitly deferred within this phase>
+
+**Key files**
+- <path/to/file.py>
+- ...
+
+**Depends on**
+- (none)
+
+**Produces**
+- IF-0-P1-1
+- IF-0-P1-2
+
+---
+
+### Phase 2A — <Name> (P2A)
+
+**Objective**
+...
+
+**Exit criteria**
+- [ ] ...
+
+**Scope notes**
+- ...
+
+**Non-goals**
+- ...
+
+**Key files**
+- ...
+
+**Depends on**
+- P1
+
+**Produces**
+- IF-0-P2A-1
+
+**Spec closeout policy**
+- schema: `spec_delta_closeout.v1`
+- decision: `<literal>`
+- target surfaces: `<repo-relative paths or globs>`
+- evidence paths: `<repo-relative metadata-only artifacts>`
+- redaction posture: `metadata_only`
+
+---
+
+<... additional phases following the same template ...>
+
+---
+
+## Execution Notes
+
+- **Planning**: `/claude-plan-phase <ALIAS>` for each phase. Phases with no shared DAG ancestor can be planned concurrently (e.g., `<alias-x>` and `<alias-y>`).
+- **Execution**: `/claude-execute-phase <alias>` after each plan is approved. Same cross-phase parallelism applies.
+- **Critical path**: <longest DAG path, e.g., `P1 → P2A → P2B → P3 → P4 → P5`> — wall-clock minimum without speedups.
+- **Parallel branches**: <e.g., `P6A` can start after P1 merge; `P6B` after P4 merge; both finish before final verification>.
+- **Single-writer files across phases**: <list any file that multiple phases might want to touch; name the owning phase for each to prevent cross-phase serialization>.
+
+---
+
+## Acceptance Criteria
+
+- [ ] <End-to-end assertion covering the whole roadmap's outcome>
+- [ ] ...
+
+---
+
+## Verification
+
+<Concrete shell/test commands that prove the roadmap delivered its goals. Runnable end-to-end by the user after the last phase merges.>
+
+```bash
+# Integration test
+<command>
+
+# Performance check
+<command>
+```
+```
+
+## Notes on filling in the template
+
+- The `> How to use` callout at the top is boilerplate — keep it so collaborators know where the file lives and what consumes it.
+- **Delete `## Architecture North Star` entirely if the work isn't structural.** An empty or placeholder diagram is worse than no diagram.
+- `## Assumptions` should be small (3–7 items). If you have 15, some are really constraints — move them to `## Cross-Cutting Principles`.
+- `## Non-Goals` is the scope-creep filter. Be specific: "no new transport layer" > "keep it simple".
+- In the DAG, one node per phase. Use `│ ▼` for serial edges and the `parallel after <X>` label for concurrent branches.
+- Every `IF-0-<ALIAS>-<N>` gate listed in `## Top Interface-Freeze Gates` must also appear in its owning phase's `**Produces**` block, and vice versa. Keep them in sync.
+- Phase aliases are case-insensitive when consumed (`P1` = `p1`), but write them uppercase in the spec and lowercase in filenames (`phase-plan-v1-p1.md`).

phase_loop_runtime/skills_bundle/codex-phase-roadmap-builder/scripts/validate_roadmap.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""validate_roadmap.py — mechanical lint for phase-plan roadmap specs.
+
+Usage:
+    validate_roadmap.py <roadmap-path>
+
+Thin shim over `phase_loop_runtime.roadmap_lint`, which is the single source of
+truth for roadmap validation and is always available wherever the phase-loop
+runtime is installed. Prefer `phase-loop validate-roadmap <path>` directly; this
+script remains for direct invocation and backward compatibility.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _main() -> int:
+    try:
+        from phase_loop_runtime.roadmap_lint import main
+    except ModuleNotFoundError:
+        sys.stderr.write(
+            "validate_roadmap: phase_loop_runtime is not importable. Install the "
+            "runtime from the public agent-harness (`scripts/install-agent-harness.sh`) "
+            "or run `phase-loop validate-roadmap <path>`.\n"
+        )
+        return 2
+    return main(sys.argv)
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

phase_loop_runtime/skills_bundle/codex-plan-detailed/README.md

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

phase_loop_runtime/skills_bundle/codex-plan-detailed/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: codex-plan-detailed
+description: "Harness detailed planner for one bounded change. Use when the user wants an immediately implementable plan for a bug fix, small feature, or targeted refactor. Researches the repo with local reads by default, optionally uses explicit explorer subagents, and returns a concise plan with changes, docs impact, verification, and acceptance criteria."
+---
+
+# Harness Plan Detailed
+
+Plans one bounded implementation. Use this instead of the phase roadmap pipeline when a single developer or one Harness thread should do the work end to end.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- In Plan Mode, inspect only and return a `<proposed_plan>`.
+- In Default mode, write a plan artifact only if the user asked for one.
+- When invoked outside Plan Mode for a planning request, still produce the plan and handoff artifacts, but do not begin implementation; tell the user Plan Mode was not active.
+- In planning-only runs, do not execute tests, builds, formatters, generators, or other verification commands. List the commands in the plan instead. Run verification only when the user explicitly asks for validation or execution.
+- Research first. Do not propose changes to files you have not located.
+- Use local tools by default: `rg`, `sed`, `find`, `git status`, and targeted file reads.
+- Use PMCP for current external docs only when the answer is not in the repo. Prefer Context7 for library/product documentation and only use Bright Data if PMCP exposes it.
+- Do not spawn subagents unless the user explicitly asks for agents, delegation, or parallel research.
+- Keep the plan bounded. No opportunistic refactors, speculative features, or broad cleanup.
+- If the plan would touch more than ~8 source files or more than 3 conceptually distinct changes, recommend splitting it into multiple bounded plans.
+- line-number-fabrication guard: do not fabricate line numbers. Cite `module.py:NNN` only when the line was read in this session; otherwise hedge the citation or tell the implementer which symbol to search for.
+- When touching a file with a frozen vocabulary or protocol contract, quote the relevant protocol line range in the plan and confirm no new vocabulary is introduced.
+- Write the plan first, then write the handoff serially so the handoff can reference the final plan path and quote final decisions.
+
+## Inputs
+
+- Task description: explicit user text or prior conversation context.
+- Output path: default `plans/detailed-<slug>-<YYYYMMDD-HHMM>.md`.
+
+## Workflow
+
+1. Extract the task. If still unclear after reading local context, ask one concise question.
+2. Gather context:
+   - `git status --short`;
+   - `git log --oneline -5`;
+   - repo root;
+   - `AGENTS.md` and `CLAUDE.md`, if present;
+   - files found by targeted `rg`.
+   Keep the full starting `git status --short --untracked-files=all` output. Before closeout, compare it with the ending status and label every pre-existing untracked file in the handoff as "not an artifact of this plan — do not commit as part of implementation."
+3. Inspect likely implementation and test files.
+4. Decide the smallest coherent implementation.
+5. Enumerate every change with:
+   - file path;
+   - entity;
+   - action: add, modify, or delete;
+   - reason.
+6. Document impact:
+   - list docs or API/schema files that need updates;
+   - if none, state why.
+7. Add dependencies, ordering, verification commands, and acceptance criteria.
+
+Do not run the verification commands while planning unless the user explicitly asked for a validation run. Many test tools write caches or require writable temp directories, so executing them can dirty a smoke-test repo even when source files stay unchanged.
+
+## Plan Template
+
+```markdown
+# Detailed plan: <one-line task summary>
+
+## Task
+<task statement>
+
+## Research summary
+<2-5 sentences with important files and patterns>
+
+## Changes
+
+### `<file-path>` (<create|modify|delete>)
+- `<entity>` — <add|modify|delete> — <reason>
+
+## Documentation impact
+<docs to update, or `None — <reason>.`>
+
+## Dependencies & order
+<blocking order and dependencies>
+
+## Verification
+<concrete shell/test commands and edge cases>
+
+## Acceptance criteria
+- [ ] <testable assertion>
+```
+
+## Quality Bar
+
+- Every changed behavior has a verification path.
+- Acceptance criteria are testable, not aspirational.
+- Plan references concrete files and entities.
+- Documentation impact is explicit.
+- The plan leaves no implementation decisions open.
+
+
+## Verification Contract
+
+Detailed plans must contain machine-checkable verification commands and an effective `automation.suite_command` whenever the runner will execute them. If an acceptance item depends on operational evidence that cannot be machine-checked directly, the plan must name the operational evidence artifact and the runner-stamped amendment mechanism that records it. proxy evidence requires a roadmap or plan amendment before downstream execution relies on it.
+
+## 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.
+
+If writing an artifact, use `apply_patch`, report the path, and do not commit unless requested.
+
+### Manifest write
+
+After the plan artifact path and repo-local handoff path are known, best-effort append a `type=detailed` entry to `plans/manifest.json` through `phase_loop_runtime.plan_manifest.append_entry` (`plan-manifest append`). `append_entry(repo, entry)` takes a typed `phase_loop_runtime.plan_manifest.DotfilesPlanEntry` constructed with keyword fields (`slug`, `file`, `type`, `status`, `created_at`, `updated_at`, `owner_skill`, …), NOT a plain dict — passing a dict fails. Use `phase_loop_runtime.skill_paths` resolver helpers for any reflection or handoff paths needed by the metadata. The manifest entry must record `status=committed`, `slug`, `file`, `created_at`, `updated_at`, `owner_skill=<harness>-plan-detailed`, `task_summary`, `acceptance_criteria_count`, and the handoff path metadata (`handoff_path` / `handoff_ref`). Include a committed lifecycle event with `by=<harness>-plan-detailed` when the helper contract requires lifecycle provenance.
+
+Manifest write failures are non-fatal during the dual-mode window: emit a ledger warning, add the failure to the mandatory reflection, and preserve the existing closeout, handoff, and final response behavior.
+
+Before final response, write a reflection for every non-trivial run. Write it to `resolve_skill_bundle_root("codex")/<harness>-plan-detailed/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 Harness paths only:
+
+- Reflection: `resolve_skill_bundle_root("codex")/<harness>-plan-detailed/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `<repo>/.dev-skills/handoffs/<harness>-plan-detailed/<run_id>.md`
+- Latest handoff pointer: `<repo>/.dev-skills/handoffs/<harness>-plan-detailed/latest.md`
+
+Handoff frontmatter must include `from: <harness>-plan-detailed`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, and `artifact:`. Update `latest.md` with the same handoff content.

phase_loop_runtime/skills_bundle/codex-plan-detailed/assets/review_prompt.md

@@ -0,0 +1,25 @@
+Review the following detailed implementation plan produced by `/claude-plan-detailed`. The plan describes one bounded, single-concern change (a bug fix, small feature, or targeted refactor) that one agent or developer will implement end-to-end. The plan follows a fixed template: Task, Research summary, Changes (grouped by file with entity/action/reason), Documentation impact, Dependencies & order, Verification, Acceptance criteria.
+
+Assess, concretely:
+
+1. **Change specificity** — does every bullet under `## Changes` name a concrete entity (class, method, function, migration, table, column, config key)? Flag anything that reads as a vague scope ("improve the auth module", "clean up the handler"), or an action word without an entity ("add validation"). The skill exists specifically to force concreteness; a vague bullet is a real defect.
+
+2. **Modification-over-creation discipline** — any newly-created files or functions that could have been additions to existing files instead? Call these out by name. Acceptable reasons to create new: separation of concerns demands it, no existing home exists, existing code would become unwieldy. Unacceptable reason: "it's cleaner to start fresh."
+
+3. **Scope creep** — compare the Task statement against the Changes list. Flag any change that is NOT on the critical path of the stated task. Common drifts: unrelated refactors of surrounding code, speculative error handling, type annotations on unchanged code, "while I'm here" additions.
+
+4. **Documentation completeness** — is the Documentation impact section consistent with the Changes? For each kind of change, does the affected doc surface get an entry?
+   - User-facing API / CLI change → `README.md` and usually `CHANGELOG.md`.
+   - Public contract change → `AGENTS.md` / `CLAUDE.md` / `llm.txt` / `openapi.*` as applicable.
+   - Architectural shift → `ARCHITECTURE.md` / `DESIGN.md` / relevant `docs/**`.
+   Flag anything that plausibly needs a doc update but isn't listed. Flag anything listed that isn't justified.
+
+5. **Verification concreteness** — every Verification step should be runnable as a shell command or observable behavior. Flag any "manually check that it works," "verify the output looks right," or similar un-runnable item.
+
+6. **Acceptance-criteria testability** — every `- [ ]` item must be a testable assertion. "Users can log in" is not testable; "`POST /api/auth` returns 200 with a valid session cookie for a registered user" is. Flag any item written as prose or aspiration.
+
+7. **Dependency ordering** — if any change depends on another (migration must run before new column is read, shared type must exist before consumers are updated), is that dependency explicitly called out in `## Dependencies & order`? Flag missing ordering constraints.
+
+Be specific. Cite file paths, entity names, and the exact bullet at issue. Prefer "Changes → `src/auth/handler.ts` → `validateToken()` is described as 'improve' but doesn't say what changes — specify the added check or extracted helper" over general critique.
+
+ARTIFACT:

phase_loop_runtime/skills_bundle/codex-plan-phase/README.md

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