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

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

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

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

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

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

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

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

@@ -0,0 +1,144 @@
+---
+name: opencode-execute-detailed
+description: "OpenCode bounded-plan executor for one detailed implementation plan with verification, acceptance reduction, and mandatory reflection closeout."
+---
+
+# OpenCode Execute Detailed
+
+Executes one detailed plan artifact produced by `<harness>-plan-detailed`. Use
+this when one OpenCode 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/opencode-execute-phase/README.md

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

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

@@ -0,0 +1,196 @@
+---
+name: opencode-execute-phase
+description: "OpenCode-optimized executor for a `<harness>-plan-phase` lane plan. Use when the user wants OpenCode to implement a planned phase. Executes lanes with clean git preflight, owned-file boundaries, verification, and optional explicit worker-subagent fanout for disjoint lanes."
+---
+
+# OpenCode Execute Phase
+
+Executes a phase plan produced by `<harness>-plan-phase`. The default executor is the main OpenCode 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.
+- Keep lane ownership boundaries. If implementation requires touching another lane's files, stop and revise the plan or ask the user.
+- 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.
+
+OpenCode lane launches must preserve explicit delivery and permission
+metadata: `<harness> run`, `--dir`, `--agent`, provider-qualified `--model`,
+optional `--variant`, `--format json`, and the shared context file. 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;
+   - 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:
+   - when the selected executor is OpenCode live, keep the launch contract
+     explicit around `<harness> run`, `--dir`, `--agent`, provider-qualified
+     `--model`, optional `--variant`, `--format json`, and the shared
+     `context_file` artifact;
+   - record OpenCode permission posture explicitly and refuse permissive
+     defaults unless the runner intentionally opts in;
+   - treat installed-skill drift as warning-only metadata when injected repo
+     context is present and the child otherwise succeeds;
+   - 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;
+   - 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`.
+
+
+## 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 bounded phase execution, closeout expectations, 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.
+
+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, and use the phrase `manual event` when standalone compatibility event import applies. 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 OpenCode 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/opencode-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}"

phase_loop_runtime/skills_bundle/opencode-execute-phase/scripts/audit_lane_file_touches.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+audit_lane_file_touches.py — audit a lane's commit against the plan's
+disjoint-owned-files contract.
+
+Usage:
+    audit_lane_file_touches.py <lane-sha> <plan-doc-path> <this-lane-id>
+
+Emits EXACTLY one token on stdout, exit 0 always (verdict is on stdout
+for the orchestrator to act on):
+
+  CLEAN
+    - Every file touched by <lane-sha> (vs its first-parent ancestor)
+      falls within <this-lane-id>'s `Owned files` globs from the plan
+      doc.
+
+  PEER_INTRUSION
+    - One or more files touched match some OTHER lane's `Owned files`
+      globs. The lane wandered into a peer's territory. Orchestrator
+      surfaces to user for merge/no-merge decision — defensive cross-
+      lane test-mock edits happen and are usually benign, but should be
+      reviewed rather than surfacing as a later merge conflict.
+
+  ORPHAN_FILES
+    - One or more files touched fall OUTSIDE every lane's globs. The
+      teammate worked outside any declared lane scope — probable bug.
+
+Any combination of intrusion + orphan is reported with intrusion winning.
+Details (which peer, which files) are written to stderr.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+
+_SL_SECTION_RE = re.compile(r"^###\s+(SL-\d+)\b.*$", re.MULTILINE)
+_OWNED_BULLET_RE = re.compile(
+    r"^\s*-\s*\*\*Owned files\*\*\s*:\s*(.*?)\s*$",
+    re.IGNORECASE,
+)
+_CODE_TOKEN_RE = re.compile(r"`([^`]+)`")
+
+
+def _fail(msg: str) -> None:
+    print(f"audit_lane_file_touches: {msg}", file=sys.stderr)
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except Exception as exc:
+        _fail(f"cannot read {path}: {exc}")
+        sys.exit(2)
+
+
+def _extract_lanes_body(src: str) -> str:
+    """Return the body between '## Lanes' and the next '## '."""
+    lines = src.splitlines()
+    out: List[str] = []
+    in_section = False
+    for line in lines:
+        if line.startswith("## ") and line.strip() == "## Lanes":
+            in_section = True
+            continue
+        if in_section and line.startswith("## "):
+            break
+        if in_section:
+            out.append(line)
+    return "\n".join(out)
+
+
+def _parse_owned_globs(lanes_body: str) -> Dict[str, List[str]]:
+    """Map SL-N -> list of owned globs as declared in the plan."""
+    matches = list(_SL_SECTION_RE.finditer(lanes_body))
+    result: Dict[str, List[str]] = {}
+    for idx, m in enumerate(matches):
+        sl_id = m.group(1)
+        start = m.end()
+        end = matches[idx + 1].start() if idx + 1 < len(matches) else len(lanes_body)
+        body = lanes_body[start:end]
+        globs: List[str] = []
+        for line in body.splitlines():
+            mb = _OWNED_BULLET_RE.match(line)
+            if not mb:
+                continue
+            raw = mb.group(1)
+            tokens = _CODE_TOKEN_RE.findall(raw)
+            globs.extend(t.strip() for t in tokens if t.strip())
+        # Drop annotation-only items like "(NEW)" / "(DELETE)".
+        globs = [
+            g.split()[0].strip() for g in globs
+            if g and not g.startswith("(")
+        ]
+        result[sl_id] = globs
+    return result
+
+
+def _glob_to_regex(pattern: str) -> re.Pattern:
+    """Minimal glob → regex. ** → any depth; * → any non-/; ? → one non-/."""
+    s = pattern.strip("`").strip()
+    esc = re.escape(s)
+    esc = esc.replace(r"\*\*", ".*").replace(r"\*", "[^/]*").replace(r"\?", "[^/]")
+    return re.compile("^" + esc + "$")
+
+
+def _touched_files(sha: str) -> List[str]:
+    """Files changed by <sha> relative to its first parent."""
+    try:
+        r = subprocess.run(
+            ["git", "diff", "--name-only", f"{sha}^..{sha}"],
+            capture_output=True, text=True, check=True,
+        )
+    except subprocess.CalledProcessError:
+        # Commit has no parent (e.g., root) — fall back to diff against empty tree.
+        r = subprocess.run(
+            ["git", "show", "--name-only", "--pretty=", sha],
+            capture_output=True, text=True, check=True,
+        )
+    return [line for line in r.stdout.splitlines() if line.strip()]
+
+
+def main(argv: List[str]) -> int:
+    if len(argv) != 4:
+        _fail("usage: audit_lane_file_touches.py <lane-sha> <plan-doc-path> <this-lane-id>")
+        return 2
+
+    lane_sha = argv[1]
+    plan_path = Path(argv[2])
+    this_lane = argv[3]
+
+    if not plan_path.exists():
+        _fail(f"plan doc not found: {plan_path}")
+        return 2
+
+    src = _read(plan_path)
+    lanes_body = _extract_lanes_body(src)
+    owned_map = _parse_owned_globs(lanes_body)
+
+    if this_lane not in owned_map:
+        _fail(f"lane {this_lane} not found in plan doc's `## Lanes` section")
+        return 2
+
+    # Compile regexes per lane.
+    compiled: Dict[str, List[re.Pattern]] = {
+        sl: [_glob_to_regex(g) for g in globs]
+        for sl, globs in owned_map.items()
+    }
+
+    touched = _touched_files(lane_sha)
+
+    def match_any(path: str, pats: List[re.Pattern]) -> bool:
+        return any(p.match(path) for p in pats)
+
+    intrusions: Dict[str, List[str]] = {}
+    orphans: List[str] = []
+    clean: List[str] = []
+    for path in touched:
+        if match_any(path, compiled[this_lane]):
+            clean.append(path)
+            continue
+        peer_hit: Optional[str] = None
+        for sl, pats in compiled.items():
+            if sl == this_lane:
+                continue
+            if match_any(path, pats):
+                peer_hit = sl
+                break
+        if peer_hit is not None:
+            intrusions.setdefault(peer_hit, []).append(path)
+        else:
+            orphans.append(path)
+
+    # Emit verdict. Intrusion takes precedence over orphan (intrusion is more actionable).
+    if intrusions:
+        for peer, paths in sorted(intrusions.items()):
+            _fail(f"{this_lane} touched files owned by {peer}: {paths}")
+        if orphans:
+            _fail(f"{this_lane} also touched orphan files (no lane owns): {orphans}")
+        print("PEER_INTRUSION")
+        return 0
+
+    if orphans:
+        _fail(f"{this_lane} touched files outside any lane's Owned files: {orphans}")
+        print("ORPHAN_FILES")
+        return 0
+
+    print("CLEAN")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))