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

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

@@ -0,0 +1,38 @@
+---
+name: gemini-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/gemini-advisor-panel/README.md

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

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

@@ -0,0 +1,38 @@
+---
+name: gemini-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/gemini-execute-detailed/README.md

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

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

@@ -0,0 +1,144 @@
+---
+name: gemini-execute-detailed
+description: "Harness 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 when one Harness thread should implement a bounded plan end to end without
+phase lanes or cross-harness dispatch.
+
+## 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 when available; otherwise use the active
+  session's file-editing tool with the same narrow diff discipline.
+- Keep implementation bounded to the detailed plan's `## Changes` section.
+- 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 keep the starting dirty
+   paths for closeout comparison.
+3. Read the plan artifact in full.
+4. Validate that it contains non-empty `## Changes`, `## Verification`, and
+   `## Acceptance criteria` sections.
+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. Use `apply_patch` or the
+   active file-editing tool for manual edits. If implementation requires a file
+   or behavior not named by the plan, stop and report
+   `dirty worktree from non-plan output`.
+7. Run every command in `## Verification` unless unsafe, unavailable, or blocked
+   by missing credentials. Report each command with pass/fail status.
+8. Compare the final state against each item in `## Acceptance criteria` and
+   report satisfied or unmet status.
+9. Run `git status --short --untracked-files=all` and 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 the detailed plan artifact path, changed files,
+verification command results, acceptance-criteria status, final dirty-path
+classification, and next action or blocker.
+
+
+## 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/gemini-execute-phase/README.md

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

phase_loop_runtime/skills_bundle/gemini-execute-phase/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: gemini-execute-phase
+description: "Harness-optimized executor for a `<harness>-plan-phase` lane plan. Use when the user wants Harness to implement a planned phase. Executes lanes with clean git preflight, owned-file boundaries, verification, and optional explicit worker-subagent fanout for disjoint lanes."
+---
+
+# Harness Execute Phase
+
+Executes a phase plan produced by `<harness>-plan-phase`. The default executor is the main Harness thread. Worker subagents are optional and only used when the user explicitly asks for subagents, delegation, or parallel execution.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Read the full phase plan before editing.
+- Preserve user work. Never revert changes you did not make.
+- Use the active session's file-editing tool for manual edits.
+- When implementation depends on current external documentation, use PMCP first. Context7 is the preferred path for library docs; Bright Data or other search/scrape tools may be used only when `gateway_catalog_search` shows they are available.
+- Follow `shared/phase-loop/protocol.md` for shared closeout, manual event, installed-skill drift, and roadmap amendment behavior.
+- In injected phase-loop repair launches, do not edit `.phase-loop/` or claim `manual_repair` ledger writes unless the launch explicitly permits and confirms them; emit one valid shared `automation:` closeout so the parent runner can reconcile state.
+- Keep lane ownership boundaries. If implementation requires touching another lane's files, stop and revise the plan or ask the user.
+- Treat ignored, private, raw-data, credential, and evidence-source files as read-protected unless the phase plan or source bundle explicitly allowlists the exact path or glob for read access. Do not infer permission from nearby owned output paths, old memory, or prior phases.
+- Before final closeout, compare `git status --short` dirty paths against the active plan's owned files and control artifacts. If any generated path is unowned, ignored without explicit allowlist/staging policy, or derived from unauthorized raw/private inputs, stop with `dirty_worktree_conflict` instead of calling the phase complete.
+- Do not run destructive git commands such as `git reset --hard` or `git checkout -- <path>` unless the user explicitly requested that operation.
+- Do not commit, push, or merge unless the user asked for those git actions.
+
+## Runner-Owned Lane Work Units
+
+Injected HARNESSLANE runs may include a `HarnessLaneAssignment` from
+`shared/phase-loop/protocol.md`. Treat that assignment as the work-unit
+contract: execute only the selected `lane_id`, write only the listed
+`owned_files`, treat `consumed_interfaces` as read-only, and emit one shared
+`automation:` closeout for that work unit. Installed-skill drift is
+warning-only when the repo-injected context is present.
+
+Harness thinking control must use runner-supported aliases such as
+`phase-loop-execute-medium` or `phase-loop-review-high`. Review, reducer,
+verify, and closeout prompts are distinct from implementation prompts. If the
+selected policy is unsupported by the active harness, stop with a typed
+non-human blocker instead of silently downgrading.
+
+## Inputs
+
+- Plan path: default latest `plans/phase-plan-*.md`.
+- `--dry-run`: parse and print the lane schedule without editing.
+- `--parallel`: allowed only when the user explicitly requests parallel worker execution.
+
+If no plan path is explicit, first check the current repo and branch handoff from `<harness>-plan-phase` using `<harness>-config/shared/runtime-state.md`: read the repo-local handoff resolver target `.dev-skills/handoffs/<harness>-plan-phase/latest.md`, validate `from`, `repo`, `repo_root`, `branch`, `branch_slug`, `commit`, and `artifact`, then use the artifact only if it exists under the current repo root. Ignore missing or mismatched handoffs unless the user explicitly asks to reuse cross-branch state.
+
+## Preflight
+
+1. Resolve repo root and plan path.
+2. Run `git status --short`.
+3. Run `git status --short -- <plan_path>` and warn if the plan is untracked.
+4. If the tree has unrelated dirty files, leave them alone and scope edits around them.
+5. Parse:
+   - interface gates;
+   - lane DAG;
+   - owned files;
+   - any explicit read allowlists for ignored, private, raw-data, credential, or evidence-source paths;
+   - task lists;
+   - verification commands;
+   - optional `Dispatch Hints` from the roadmap or plan using the frozen
+     vocabulary from `shared/phase-loop/protocol.md`.
+6. Validate producer dependencies:
+   - any lane that consumes another lane's findings, interfaces, or artifacts must list that producer lane in `Depends on`;
+   - any lane that writes a synthesized artifact must be downstream of every producer lane it summarizes;
+   - if dependencies are missing, stop and require a plan correction before execution.
+7. For `--dry-run`, report the topological lane order and stop.
+
+## Execution Workflow
+
+1. Execute lanes in topological order.
+2. For each lane:
+   - read the owned files and related tests;
+   - write or update tests first when practical;
+   - implement only lane-scoped changes;
+   - run lane verification (normalize any phase-plan pytest `-k` selector whose prose terms contain spaces — e.g. `remote connect` becomes `'remote and connect'` — or quote it; a bare spaced `-k` term is an executor-side normalization, not a plan blocker);
+   - run any phase-level checks that cover touched files.
+3. After each lane:
+   - inspect `git diff -- <owned files>`;
+   - confirm no peer-owned files were modified;
+   - run `git status --short` and confirm every new or modified path is either lane-owned or a planning/control artifact;
+   - for any phase-owned generated path under an ignored parent, confirm the plan/source bundle explicitly allows it to be preserved or force-staged;
+   - record completed gates.
+4. After all lanes:
+   - run the full phase verification commands;
+   - if execution discoveries change downstream work, amend the nearest
+     downstream roadmap phase that is not already executing;
+   - treat any older downstream phase plan or handoff as stale after a roadmap
+     amendment and route the next step back through `<harness>-plan-phase`;
+   - describe the change explicitly as a roadmap amendment in the final
+     closeout;
+   - summarize changed files, tests run, and any residual risks.
+
+## Optional Worker Fanout
+
+Use worker subagents only when the user explicitly authorizes parallel agent work and the DAG-ready lanes are disjoint.
+
+For every worker brief:
+
+- State that they are not alone in the codebase.
+- Assign exact owned files or globs.
+- List files they may read but not edit.
+- Tell them not to revert unrelated changes.
+- Require a final response with changed paths, tests run, failures, and blockers.
+- Do not give two workers overlapping write ownership.
+
+The main thread remains responsible for integrating results, reviewing diffs, running final verification, and resolving conflicts.
+
+## Failure Policy
+
+- Test failure in a lane: diagnose once, fix within the lane if the cause is local, otherwise stop and report.
+- Ownership violation: stop and revise the plan before continuing.
+- Missing dependency or unclear interface: stop and route back through planning.
+- Verification command unavailable: report the missing tool and run the closest available static check only if it is meaningful.
+- Use only the frozen blocker taxonomy from `shared/phase-loop/protocol.md`,
+  including `missing_secret`, `dirty_worktree_conflict`,
+  `branch_sync_conflict`, and `repeated_verification_failure`.
+- Installed-skill conflicts are warnings when the injected repo bundle was
+  delivered successfully; they do not block an otherwise valid shared closeout.
+
+
+## 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. A prior run's terminal-summary is authoritative for reconcile-or-skip only when that closeout was accepted; a rejected or blocked prior closeout — regardless of any self-reported `complete`/`passed` — must not be reconciled against. On a re-run, re-do and re-verify the phase work from scratch rather than skipping on a stale summary.
+
+
+## Spec Delta Closeout
+
+Before final closeout, choose exactly one `spec_delta_closeout.v1` decision: `no_spec_delta`, `roadmap_amendment`, `canonical_spec_update`, `governed_pipeline_refresh`, `mirror_cutover_required`, `dotfiles_skill_source_update`, or `human_source_judgment_required`. Cite metadata-only evidence paths such as the active plan, lane closeouts, targeted pytest output, and `git diff --check` output. Preserve the phase plan's target surfaces and `redaction_posture=metadata_only`; do not include raw specification bodies, raw patch bodies, credentials, provider-supplied payloads, local environment values, or evidence-source contents. Missing or malformed spec-closeout evidence is a repairable automation blocker with `blocker_class=contract_bug` unless the decision is `human_source_judgment_required`.
+
+## Closeout
+
+### Manifest lifecycle
+
+After plan validation and before lane execution, perform a best-effort `plan-manifest append` lifecycle update through `phase_loop_runtime.plan_manifest.update_lifecycle` to mark the matching `type=phase` entry `executing` with run metadata. During closeout, update the same entry to `completed` or `failed` with verification metadata, reflection metadata, produced-gate metadata, `if_gates_produced`, and dirty-worktree summary fields as available. `if_gates_produced` must list only the IF gates the active phase produces per its own plan; never carry a prior phase's gate forward into this phase's closeout. Manifest lifecycle failures are non-fatal during the dual-mode window: emit a ledger warning, mention the warning in the mandatory reflection, and preserve the existing phase closeout JSON, verification, active-session file-editing tool language, and dirty-worktree behavior.
+
+Before final closeout, run `git status --short -- <plan_path> <roadmap_path>` for every consumed or updated planning artifact. If any planning artifact is untracked or modified and the user did not explicitly forbid staging, run `git add <path>` for each artifact. Rerun status and report `Artifact state: staged|tracked|modified|unstaged|blocked` for each artifact. Do not commit unless requested. Repo-local handoff files are operational state: do not `git add` an ignored handoff alongside the plan artifact unless the plan's owned-files/allowlist explicitly includes the handoff directory; leave ignored handoffs ignored and exclude them from artifact-state reporting.
+
+Also run a whole-tree `git status --short` closeout audit. Classify every dirty path as phase-owned, planning/control, pre-existing unrelated, or unowned. For ignored phase-owned outputs that must be preserved, verify an explicit plan/source-bundle allowlist or staging policy before using `git add -f`; otherwise report a repairable `dirty_worktree_conflict`. Precedence for a verified phase: when required verification passed and the ONLY uncommitted paths are phase-owned outputs this run was not authorized to commit, report `terminal_status=awaiting_phase_closeout` and let the runner's graduated closeout gate commit them — do NOT report `dirty_worktree_conflict`; reserve that conflict for unowned, unauthorized-ignored, or overlapping-unrelated dirty paths. Never report `complete` while unowned generated files, unauthorized ignored outputs, or outputs derived from unauthorized raw/private reads remain in the worktree.
+
+Determine the next step before final response and handoff:
+
+- If the current phase is incomplete or verification failed, report `Next phase: <current alias> - blocked: <blocker>` and `Next command: none - <blocker>`.
+- If another generated phase plan is ready, report `Next phase: <next alias> - execution ready` and `Next command: <harness>-execute-phase <next_plan_path>`.
+- If the roadmap has an unplanned ready phase, report `Next phase: <next alias> - planning ready` and `Next command: <harness>-plan-phase <roadmap_path> <next_alias>`.
+- If the roadmap needs extension, report `Next phase: none - roadmap extension needed` and `Next command: <harness>-phase-roadmap-builder <roadmap_path>`.
+- If all phases are complete, report `Next phase: none - roadmap complete` and `Next command: none - roadmap complete`.
+
+Add a machine-readable `automation:` handoff with `verification_status` that agrees with the human-readable next step fields. 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.
+
+Before final response, write a reflection for every non-trivial run. Write it to `resolve_skill_bundle_root("codex")/<harness>-execute-phase/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.
+
+Report:
+
+- lanes completed;
+- files changed;
+- planning artifact tracking state;
+- next phase and next command;
+- verification commands and results;
+- commands not run and why;
+- follow-up risks or manual checks.
+
+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>-execute-phase/reflections/<repo_hash>/<branch_slug>/<run_id>.md`
+- Handoff: `<repo>/.dev-skills/handoffs/<harness>-execute-phase/<run_id>.md`
+- Latest handoff pointer: `<repo>/.dev-skills/handoffs/<harness>-execute-phase/latest.md`
+
+Handoff frontmatter must include `from: <harness>-execute-phase`, `timestamp:`, `repo:`, `repo_root:`, `branch:`, `branch_slug:`, `commit:`, `run_id:`, `artifact:`, `artifact_state:`, `next_skill:`, `next_command:`, and `next_phase:`. Put open follow-up items in the body, and update `latest.md` with the same handoff content.
+
+
+## Publication mode
+
+After verified phase work, select exactly one of three modes. **Default to (a) unless a
+clear interactive signal is present** — a run missing BOTH the adapter prompt prefix AND
+`PHASE_LOOP_RUN_MODE` is AMBIGUOUS and MUST be treated as (a) (fail safe toward the runner).
+
+- (a) Runner-managed closeout (incl. governed mode), OR ambiguous mode. If this is the
+  phase-loop adapter (the prompt begins with `<harness>-execute-phase <plan>` from a
+  pipeline run dir), or `PHASE_LOOP_RUN_MODE` is set (autonomous/governed), OR neither
+  interactive signal is clearly present, the RUNNER owns closeout and commit. Do NOT
+  independently publish — defer entirely to runner closeout (`awaiting_phase_closeout` /
+  runner commit). Publishing here would bypass the governed pre-merge review panel.
+- (b) Interactive orchestrator on a clean, non-protected feature branch (a clear
+  interactive signal, and the merge target passed the merge-target safety gate). After the
+  Step-9 clean-tree state, push the merge-target branch and open a PR (`gh pr create`,
+  `--draft` if dependencies remain or verification was partial/skipped, else ready) instead
+  of leaving the lane merge only local.
+- (c) Merge target is `main` or a protected branch. Already STOPPED at the merge-target
+  safety gate before any lane merge — never merge lanes onto `main`/protected. Re-target a
+  feature branch or take explicit instruction.
+
+This applies only to interactive (non-runner) completion; it never overrides
+`awaiting_phase_closeout`, the runner's deliberate non-complete terminal. Allowed runner
+hygiene (forced lane-worktree removal, `branch -D`, `sweep_stale_worktrees.sh`) is
+unchanged — the destructive-op ban targets publication branches/worktrees holding
+unmerged work.

phase_loop_runtime/skills_bundle/gemini-execute-phase/scripts/allocate_worktree_name.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# allocate_worktree_name.sh — emit a collision-impossible worktree name
+# for a swim-lane teammate.
+#
+# Usage:
+#     allocate_worktree_name.sh <sl-id>
+#
+#     <sl-id>   Lane identifier, e.g. "sl-1" or "sl-2b".
+#
+# Emits exactly one line to stdout:
+#     lane-<sl-id>-<UTC-YYYYMMDDHHMMSS>-<4char-random>
+#
+# Rationale: the default `lane-<sl-id>` naming is not unique across rapid
+# consecutive dispatch of in-process teammates — two teammates spawned in
+# the same message can race on the same EnterWorktree slot. The 4-char
+# random suffix + UTC timestamp eliminates the race by construction.
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+    echo "usage: allocate_worktree_name.sh <sl-id>" >&2
+    exit 2
+fi
+
+sl_id="$1"
+ts="$(date -u +%Y%m%dT%H%M%S)"
+rand="$(tr -dc 'a-z0-9' </dev/urandom | head -c 4 || true)"
+if [[ -z "$rand" ]]; then
+    # Extremely unlikely; fall back to $RANDOM-derived 4 chars.
+    rand="$(printf "%04x" "$((RANDOM & 0xFFFF))")"
+fi
+
+echo "lane-${sl_id}-${ts}-${rand}"