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

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

phase_loop_runtime/skills_bundle/claude-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/claude-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/claude-plan-detailed/README.md

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