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

phase_loop_runtime/skill_paths.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+HARNESS_DEFAULT_SKILL_ROOTS: dict[str, Path] = {
+    "claude": Path("~/.claude/skills"),
+    "codex": Path("~/.codex/skills"),
+    "gemini": Path("~/.gemini/skills"),
+    "opencode": Path("~/.config/opencode/skills"),
+}
+
+
+def current_harness(harness: str | None = None) -> str:
+    selected = harness or os.environ.get("PHASE_LOOP_HARNESS") or "codex"
+    normalized = selected.strip().lower()
+    if normalized not in HARNESS_DEFAULT_SKILL_ROOTS:
+        allowed = ", ".join(sorted(HARNESS_DEFAULT_SKILL_ROOTS))
+        raise ValueError(f"unsupported phase-loop harness {selected!r}; expected one of: {allowed}")
+    return normalized
+
+
+def resolve_skill_bundle_root(harness: str | None = None) -> Path:
+    override = os.environ.get("PHASE_LOOP_SKILL_BUNDLE")
+    if override:
+        return Path(override).expanduser()
+    return HARNESS_DEFAULT_SKILL_ROOTS[current_harness(harness)].expanduser()
+
+
+def resolve_skill_helper_root(harness: str | None = None) -> Path:
+    return resolve_skill_bundle_root(harness) / "_shared"
+
+
+def resolve_handoff_root(repo: Path) -> Path:
+    return Path(repo).expanduser().resolve() / ".dev-skills" / "handoffs"
+
+
+def resolve_reflection_root(skill_name: str, harness: str | None = None) -> Path:
+    if not skill_name:
+        raise ValueError("skill_name is required")
+    return resolve_skill_bundle_root(harness) / skill_name / "reflections"

phase_loop_runtime/skill_sources_plugin.py

@@ -0,0 +1,37 @@
+"""Dotfiles skill-sources plugin: the per-harness overlay roots for the bundle.
+
+DISENTANGLE (EXTRACTSKILLS SL-2) moves the per-harness dotfiles overlay roots
+(``claude-config/claude-skills``, ``codex-config/skills``, ``gemini-config/skills``,
+``opencode-config/skills``) out of the generic runtime's
+``skill_inventory.HARNESS_SOURCE_ROOTS`` constant and behind this provider. The
+generic runtime contributes nothing on its own; these roots appear only when this
+plugin is loaded -- either via the ``phase_loop_runtime.skill_sources`` entry-point
+group (declared in pyproject, live in a real install) or via the explicit
+``PHASE_LOOP_SKILL_SOURCE_PLUGINS`` opt-in used in source-mode runs and tests.
+
+The neutral generated bundle is the shared-canonical artifact (it moves to
+agent-harness); these 4 source roots that produce the ``_overrides/`` are the
+dotfiles-OVERLAY and stay in dotfiles, contributed through this seam.
+
+This module is the dotfiles *profile* counterpart to ``dotfiles_profile_plugin``:
+it is allowed to depend on dotfiles-domain knowledge. The roots are single-sourced
+from ``build_bundle.DEFAULT_SOURCES`` so the bundle builder and this overlay seam
+never drift apart.
+"""
+from __future__ import annotations
+
+
+def register_skill_sources() -> dict[str, tuple[str, ...]]:
+    """Return the dotfiles per-harness overlay source roots.
+
+    Single-sourced from ``build_bundle.DEFAULT_SOURCES`` (a ``{harness: path}`` map);
+    each path is wrapped as a one-element tuple to match the
+    ``{harness_target: (root, ...)}`` provider contract consumed by
+    :func:`phase_loop_runtime.skill_inventory.iter_skill_source_roots`.
+
+    Imported lazily to keep ``import phase_loop_runtime.skill_inventory`` clean,
+    matching ``dotfiles_profile_plugin.register_profile_commands``.
+    """
+    from .build_bundle import DEFAULT_SOURCES
+
+    return {harness: (path,) for harness, path in DEFAULT_SOURCES.items()}

phase_loop_runtime/skills_bundle/claude-advisor-board/README.md

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

phase_loop_runtime/skills_bundle/claude-advisor-board/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: claude-advisor-board
+description: Run a customizable cross-vendor advisor board (formerly advisor-panel; that name remains a working alias) through the agent-harness runtime primitive when a high-stakes change needs independent review evidence.
+---
+
+# Advisor Board
+
+Use this skill when a plan, implementation diff, release closeout, or other high-stakes artifact needs an independent cross-vendor review board. This skill was formerly named `advisor-panel`; that name still resolves as an alias, so existing instructions that say "advisor-panel" keep working.
+
+## Source Of Truth
+
+The advisor-board (formerly advisor-panel) implementation is owned by `agent-harness`:
+
+- Runtime primitive: `phase_loop_runtime.panel_invoker`
+- Board model: `phase_loop_runtime.advisor_board` (seats, boards, resolver, validation)
+- Entry points: `available_panel_legs`, `invoke_panel`, and `invoke_panel_request` (from a `PanelRequest`)
+- Governed workflow integration: phase-loop governed review/pre-merge paths
+
+Do not call dotfiles advisor-panel scripts, copy provider-specific shell scripts, or introduce a separate implementation in the skill body. The skill is a thin operator guide over the runtime primitive.
+
+## Use
+
+1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
+2. For a standalone smoke or diagnostic, build a metadata-only review artifact and call `phase_loop_runtime.panel_invoker.invoke_panel`.
+3. Require every leg to end with `AGREE`, `PARTIALLY AGREE`, or `DISAGREE`.
+4. Treat `EMPTY`, `TIMEOUT`, `ERROR`, `DEGRADED`, and `UNAVAILABLE` as structured evidence, not successful reviews.
+5. Keep provider API keys out of the environment; the runtime strips known API-key variables and uses local subscription CLIs.
+
+## Standalone Smoke Shape
+
+```python
+from phase_loop_runtime.panel_invoker import available_panel_legs, invoke_panel
+
+artifact = "Review artifact with acceptance criteria and verification evidence."
+panel = invoke_panel(artifact, available_panel_legs())
+for leg in panel.legs:
+    print(leg.leg, leg.status)
+```

phase_loop_runtime/skills_bundle/claude-advisor-panel/README.md

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

phase_loop_runtime/skills_bundle/claude-advisor-panel/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: claude-advisor-panel
+description: Run a customizable cross-vendor advisor board (formerly advisor-panel; that name remains a working alias) through the agent-harness runtime primitive when a high-stakes change needs independent review evidence.
+---
+
+# Advisor Board
+
+Use this skill when a plan, implementation diff, release closeout, or other high-stakes artifact needs an independent cross-vendor review board. This skill was formerly named `advisor-panel`; that name still resolves as an alias, so existing instructions that say "advisor-panel" keep working.
+
+## Source Of Truth
+
+The advisor-board (formerly advisor-panel) implementation is owned by `agent-harness`:
+
+- Runtime primitive: `phase_loop_runtime.panel_invoker`
+- Board model: `phase_loop_runtime.advisor_board` (seats, boards, resolver, validation)
+- Entry points: `available_panel_legs`, `invoke_panel`, and `invoke_panel_request` (from a `PanelRequest`)
+- Governed workflow integration: phase-loop governed review/pre-merge paths
+
+Do not call dotfiles advisor-panel scripts, copy provider-specific shell scripts, or introduce a separate implementation in the skill body. The skill is a thin operator guide over the runtime primitive.
+
+## Use
+
+1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
+2. For a standalone smoke or diagnostic, build a metadata-only review artifact and call `phase_loop_runtime.panel_invoker.invoke_panel`.
+3. Require every leg to end with `AGREE`, `PARTIALLY AGREE`, or `DISAGREE`.
+4. Treat `EMPTY`, `TIMEOUT`, `ERROR`, `DEGRADED`, and `UNAVAILABLE` as structured evidence, not successful reviews.
+5. Keep provider API keys out of the environment; the runtime strips known API-key variables and uses local subscription CLIs.
+
+## Standalone Smoke Shape
+
+```python
+from phase_loop_runtime.panel_invoker import available_panel_legs, invoke_panel
+
+artifact = "Review artifact with acceptance criteria and verification evidence."
+panel = invoke_panel(artifact, available_panel_legs())
+for leg in panel.legs:
+    print(leg.leg, leg.status)
+```

phase_loop_runtime/skills_bundle/claude-execute-detailed/README.md

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

phase_loop_runtime/skills_bundle/claude-execute-detailed/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: claude-execute-detailed
+description: "Harness Code bounded-plan executor for one detailed implementation plan with verification, acceptance reduction, and mandatory reflection closeout."
+---
+
+# Harness Execute Detailed
+
+Executes one detailed plan artifact produced by `<harness>-plan-detailed`.
+Use this for bounded implementation work where a single Harness Code thread can
+carry the change end to end without phase lanes, lane ownership, or worker
+worktrees.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots,
+handoff roots, helper roots, and reflection roots.
+
+- Read the detailed plan artifact before editing.
+- Optionally read `.dev-skills/handoffs/<harness>-plan-detailed/latest.md`
+  when no explicit plan path is supplied, and only trust it if `from:` is
+  `<harness>-plan-detailed`, the repo fields match the current repo, and the
+  artifact path resolves under the current repo root.
+- Preserve user work. Never revert changes you did not make.
+- Use `apply_patch` for manual edits.
+- Keep implementation bounded to the detailed plan's `## Changes` section.
+- Do not add unrelated refactors, speculative validation, or broad cleanup.
+- Treat ignored, private, raw-data, credential, and evidence-source files as
+  read-protected unless the detailed plan explicitly allowlists the exact path
+  or glob for read access.
+- Git safety invariant: never commit to `main` or a protected branch, never commit from
+  a dirty primary checkout, and never commit/push onto a branch this run does not own (a
+  shared or pre-existing colleague branch). When executing a plan, publishing a PR from a
+  dedicated branch is the default outcome (see the Workflow + "## Publication") unless a
+  runner owns closeout, or the user asked for local-only, planning-only, or no-publication
+  work, or verification failed. Never merge, force-push, reset, delete a publication
+  branch/worktree holding unmerged work, or run other destructive git commands without
+  explicit instruction.
+
+## Inputs
+
+- Plan path: explicit detailed plan artifact, or the latest valid
+  `.dev-skills/handoffs/<harness>-plan-detailed/latest.md` artifact.
+- Optional handoff: repo-local handoff from `<harness>-plan-detailed`.
+
+## Workflow
+
+1. Resolve the repo root and detailed plan artifact.
+2. Run `git status --short --untracked-files=all` and preserve the starting
+   dirty-path list for closeout comparison.
+3. Read the plan artifact in full.
+4. Validate that it contains `## Changes`, `## Verification`, and
+   `## Acceptance criteria`. If any section is absent or empty, stop with
+   `acceptance criterion unmet` and explain the missing section.
+5. Best-effort mark the detailed plan manifest entry as `executing` through
+   `phase_loop_runtime.plan_manifest.update_lifecycle` (`plan-manifest append`)
+   after plan validation and before source edits. Use `by=<harness>-execute-detailed`
+   and metadata that identifies the run and plan artifact. Manifest lifecycle
+   failures emit ledger/reflection warnings only and do not abort execution
+   during the dual-mode window.
+6. **Establish the safe working tree BEFORE editing** (unless a runner owns closeout — see step 2 / the Git safety invariant): resolve a fresh base ref (`origin/<default-branch>` after fetch, or an explicit merge target; never a stale local `main`) and select the working tree — reuse the current branch only if it is clean, non-protected, AND owned by this run; otherwise (`main`/a protected branch, a shared/foreign branch, or a dirty primary checkout) create a worktree+branch off the base: `git worktree add <path> -b <branch> <base>` under `/mnt/workspace/worktrees/<project>-<branch-slug>` if `/mnt/workspace` exists, else a repo sibling `../<project>-<branch-slug>`. Do ALL editing, the `git status` snapshots, the dirty-path classification, and verification in that tree — never on `main`/protected/dirty/shared. Then apply the `## Changes` section in declared order. For manual edits, use
+   `apply_patch`. If a requested edit requires a file not listed in
+   `## Changes`, stop and report `dirty worktree from non-plan output` rather
+   than expanding scope silently.
+7. Run every command in `## Verification` unless the command is unsafe,
+   unavailable, or clearly requires credentials not provided by the plan. Report
+   each command with pass/fail status.
+8. Compare the final repository state against every item in
+   `## Acceptance criteria`. Mark each item satisfied or unmet.
+9. Run `git status --short --untracked-files=all` again. Classify every dirty
+   path as plan-owned, pre-existing unrelated, or non-plan output.
+
+## Failure Diagnostics
+
+- `verification failed`: a command from `## Verification` failed after one local
+  diagnosis and repair attempt, or the failure is outside the detailed plan's
+  scope.
+- `acceptance criterion unmet`: a required `## Acceptance criteria` item is not
+  satisfied, or the detailed plan lacks `## Changes`, `## Verification`, or
+  `## Acceptance criteria`.
+- `dirty worktree from non-plan output`: closeout finds a dirty path that was
+  not pre-existing and is not produced by the detailed plan's declared changes.
+- `publication blocked`: a publication precheck failed (no remote / no push auth / no `gh` /
+  branch-name collision / push rejected / unresolved base ref), or publishing would otherwise
+  require committing to `main`/a protected branch or a branch this run does not own. Verified
+  work is preserved locally on a safe branch/worktree; report what blocked the PR.
+
+
+## Runner Verification Evidence
+
+Before reporting a successful closeout, require the runner-owned verification artifact. The closeout must name `verification_artifact_path`, quote the artifact summary line, and must not report `verification_status=passed` unless that artifact exists and supports the executed work. Treat dependency-manifest install refresh and the full suite before closeout as runner-enforced expectations, not optional narrative checks. A blocked gate may be re-verdicted only by rerunning the originally specified runner check; proxy evidence requires a roadmap or plan amendment before the verdict changes.
+
+## Closeout
+
+### Manifest lifecycle
+
+During closeout, best-effort call `phase_loop_runtime.plan_manifest.update_lifecycle` with `completed` when verification and acceptance passed, or `failed` when verification failed, acceptance was unmet, or closeout found non-plan output. Include verification metadata, reflection metadata, dirty-path classification, and the final diagnostic in the lifecycle event. Manifest lifecycle failures are non-fatal during the dual-mode window: emit a ledger warning, record the failure in the mandatory reflection, and preserve the existing detailed executor closeout.
+
+Before final response, write a reflection for every non-trivial run. Write it to
+`resolve_skill_bundle_root("codex")/<harness>-execute-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, followed by `## What worked`,
+`## What didn't`, and `## Improvements to SKILL.md`. Skip only when no artifact
+was executed, no edit was made, and no decision was made.
+
+Final response must include:
+
+- detailed plan artifact path;
+- files changed;
+- verification commands with pass/fail status;
+- acceptance criteria with satisfied/unmet status;
+- final dirty-path classification;
+- next action or blocker using the stable failure diagnostics above.
+
+
+## Publication
+
+After a verified implementation, publishing a PR from the working tree established in
+Workflow step 6 is the default outcome — under the Git safety invariant in Core Rules.
+Defer entirely if a runner / pipeline owns closeout (a phase-loop-runner-driven or adapter
+run, or an explicit runner-owned-closeout instruction): the runner owns commit and closeout.
+Do NOT infer "runner owns closeout" from `verification_artifact_path` — every closeout
+records it; it does not signal a runner. The following applies for human-invoked plan
+execution.
+
+Call `phase_loop_runtime.publishing.publish_from_worktree(repo, owned_paths, draft=<intent>)`
+(IF-0-P1-1 — the runtime publication primitive), supplying the worktree root, the plan's
+owned paths, and the draft/ready intent:
+- `draft=True` when dependencies remain or verification was partial/skipped;
+- `draft=False` when verification is complete (skipped or partial verification never opens
+  a ready PR).
+
+The primitive performs the complete #28 flow in code, not prose:
+
+1. **Preflight.** Confirms the branch is non-protected, non-main, and not in a
+   dirty/unowned state; confirms a remote, push auth, and the `gh` CLI. A preflight
+   failure returns `{status: "publication_blocked", reason: ...}` — keep the committed
+   work on the safe branch/worktree and STOP at publish with `publication blocked`;
+   never on `main`/a protected branch, and never imply a PR exists.
+2. **Stage + audit.** Stages only owned paths (`git add -- <paths>`, never `git add -A`),
+   audits the staged set (rejects any ignored, private, raw-data, credential, or `.env`
+   path; runs `git diff --cached --check`), and fails closed on any violation — path-scoping
+   alone does not catch a secret inside an owned file; the read-protection rules and this
+   audit are the backstop.
+3. **Commit + push.** Commits the audited diff and pushes without force. A rejected push
+   (divergent / non-fast-forward / branch protection) returns `publication_blocked` — never
+   force-push or merge to resolve it.
+4. **Open the PR.** `gh pr create --draft` or ready (`--fill`) per the intent flag.
+
+Returns `{status: "published", branch, head_sha, pr_url}` on success (IF-0-P1-1; report
+`pr_url` in the final response and include `head_sha` in the handoff for downstream
+consumers). Returns `{status: "publication_blocked", reason: <slug>}` on any violation —
+report `publication blocked` with the reason and stop.

phase_loop_runtime/skills_bundle/claude-execute-phase/README.md

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