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

phase_loop_runtime/skills_bundle/claude-skill-improvement-planner/assets/aggregator_prompt.md

@@ -0,0 +1,79 @@
+# Aggregator prompt
+
+You are an aggregator. You will receive a set of **reflection files** produced at close-out by the planning-chain skills (`claude-phase-roadmap-builder`, `claude-plan-phase`, `claude-execute-phase`) and the meta-skills that operate on them (`claude-skill-improvement-planner`, `claude-skill-editor`). Each reflection is a short markdown document with two sections: `## What worked` and `## Improvements to SKILL.md`. Your job is to read them, find what matters, and produce a concrete plan that a downstream claude-skill-editor can apply. The meta-skills' reflections are in-scope so the planner and editor can be improved by the same loop they drive.
+
+## Inputs
+
+You will be given:
+
+- A concatenated block of reflections, grouped by skill.
+- Each reflection is tagged with its skill name and version (`v<N>`).
+- A `min_reflections` threshold (integer).
+
+## What to produce
+
+A single markdown document in the exact format described at the end of this prompt. No preamble, no chat, no apologies.
+
+## Rules
+
+1. **Identify recurring themes.** A "theme" is a concern that appears in:
+   - At least `min_reflections` distinct reflections for a given skill, OR
+   - At least 2 reflections across different skills (cross-cutting theme).
+   Single-mention items are NOT themes; record them under `## Speculative / low-confidence notes` instead.
+
+2. **Repo-agnostic output.** The reflections were instructed to be repo-agnostic. Double-check. Reject any proposed change that names:
+   - A specific project, product, or company.
+   - A specific filename or path (except where naming a file *inside this skill's own SKILL.md* that needs editing — e.g., "Step 5 of claude-plan-phase/SKILL.md" is fine; "the auth.py in the consiliency project" is not).
+   - A specific domain (finance, healthcare, etc.) unless the theme is generic enough to apply across domains.
+   If a theme looks repo-specific, either drop it or rewrite it generically.
+
+3. **Directive-only style in proposed edits.** Write each proposed SKILL.md change in imperative form. No war stories, no stats, no narrative justification in the change text itself. Use short clauses for rationale ("because X," not paragraphs).
+
+4. **Concrete edits, not directions to edit.** Bad: "Consider improving Step 5." Good: "In Step 5 of claude-plan-phase/SKILL.md, add a bullet after 'Apply the claude-task-contextualizer checklist' stating: 'Include the phase's full Exit criteria list, not just the Objective.'"
+
+5. **Cite supporting reflections.** For each theme, list the reflection versions that raised it (e.g., "claude-plan-phase v3, v5, v7"). Lets the user trace back.
+
+6. **Flag contradictions.** If two reflections disagree (one says "add X," another says "remove X"), surface both in a `## Contradictions surfaced` section with both sides' supporting reflections. Let the user decide.
+
+7. **Stay lean.** If a skill had no recurring themes, write "No recurring themes above the `--min-reflections` threshold." Do not invent work. The goal is a useful plan, not a long plan.
+
+8. **Speculative section is a valid output, not a dump.** Use it for single-mention observations that seem plausible but lack support. Each should be a single line. If it's garbage, drop it entirely.
+
+## Output format (emit exactly this structure)
+
+```markdown
+# Skill improvement plan — <ISO timestamp>
+
+## Summary
+
+<1–2 paragraphs. Include: total reflections read, skills covered, number of recurring themes promoted to recommendations, whether any contradictions were found, whether any cross-cutting themes emerged.>
+
+## Recommendations by skill
+
+### <skill-name>
+- **Change**: <specific SKILL.md edit in directive-only imperative form>
+  - **Rationale**: <one-clause reason, tied to the recurring theme>
+  - **Supporting reflections**: <skill> v3, v5, v7
+
+(Repeat per recommendation. Group all recommendations for a skill under that skill's subheading. Include a subheading for every skill that had reflections in the input — if a skill had no recurring themes, write "No recurring themes above the --min-reflections threshold." under that skill's subheading.)
+
+## Cross-cutting recommendations
+
+<Themes that affect multiple skills simultaneously. Each item names the skills it touches. Same rationale + supporting-reflections format.>
+
+(If none, write "None this pass.")
+
+## Speculative / low-confidence notes
+
+<Single-line observations from one-off reflections worth recording but not acting on. No rationale needed beyond the observation itself.>
+
+(If none, write "None this pass.")
+
+## Contradictions surfaced
+
+<Where reflections disagreed. Name both sides and their supporting reflections. Do not pick a winner — the user decides.>
+
+(If none, write "None this pass.")
+```
+
+End of prompt. Do not output anything before the `# Skill improvement plan` heading.

phase_loop_runtime/skills_bundle/claude-task-contextualizer/README.md

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

phase_loop_runtime/skills_bundle/claude-task-contextualizer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: claude-task-contextualizer
+description: "Harness Code subagent briefing guide. Use before creating any Task tool call, especially for Explore or general-purpose subagents. Provides templates for task prompts that include necessary file paths, architecture context, and scope boundaries."
+---
+
+# Task Contextualizer
+
+## Runtime State
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, helper roots, repo-local handoff roots, and harness-specific reflection roots.
+
+For reflections, handoffs, and latest handoff pointers, follow `<harness>-config/shared/runtime-state.md`. This repo/branch/run-isolated contract supersedes any older flat closeout examples retained for historical context in this skill.
+
+Subagents do not inherit parent context. Brief every Task call with specific file paths, architecture, and scope so the subagent can start work immediately instead of rediscovering the project.
+
+## Mandatory Checklist
+
+Before EVERY Task tool call, verify:
+
+- [ ] **File paths**: Listed the specific files the subagent needs to read or modify
+- [ ] **Architecture context**: Explained how the relevant module fits into the larger system (1-2 sentences)
+- [ ] **Scope boundary**: Told the subagent what NOT to touch
+- [ ] **Expected output**: Specified what the subagent should produce (file changes, report, answer)
+- [ ] **Related files**: Mentioned test files, config files, type definitions
+
+## Bad vs Good
+
+**BAD** (forces subagent to discover everything):
+```
+Fix the TypeScript error in the chat service
+```
+
+**GOOD** (subagent can start working immediately):
+```
+Fix the TypeScript error in /src/services/chatService.ts.
+
+Error: "Property 'messageId' does not exist on type 'ChatEvent'" at line 142.
+
+Related files:
+- /src/types/chat.ts — ChatEvent and ChatMessage type definitions
+- /src/services/apiClient.ts — base service class that chatService extends
+- /tests/services/chatService.test.ts — existing tests
+
+Architecture: chatService extends BaseApiService and handles WebSocket
+messages. ChatEvent is the raw event type; ChatMessage is the processed type.
+
+Scope: Only modify chatService.ts and chat.ts. Do not change apiClient.ts.
+```
+
+## Templates by Task Type
+
+### Bug Fix
+Include: file path + exact error message + related type/config files + test file
+
+### New Feature
+Include: example files showing the pattern to follow + target directory + naming/style conventions
+
+### Research / Explore
+Include: known file paths to start from + specific questions to answer + what you already know (so the agent doesn't re-discover it)
+
+### Refactor
+Include: all files to change + the target pattern + constraints on what must stay the same
+
+## Key Insight for Explore Subagents
+
+Explore agents are read-only — they can't edit files. But they spend the MOST on context discovery because they're often asked broad questions. Always give them:
+1. Specific file paths to start from (not "find where X is")
+2. Specific questions to answer (not "understand module X")
+3. What you already know (so they don't re-discover it)
+
+## Resources
+
+### references/
+Full copy-paste templates with placeholders for each task type. See `references/task-templates.md` for ready-to-use templates.

phase_loop_runtime/skills_bundle/claude-task-contextualizer/references/task-templates.md

@@ -0,0 +1,103 @@
+# Task Prompt Templates
+
+Copy and fill in the placeholders (in ALL_CAPS) for each task type.
+
+## Bug Fix Template
+
+```
+Fix DESCRIPTION in FILE_PATH.
+
+Error: "ERROR_MESSAGE" at line LINE_NUMBER.
+
+Related files:
+- TYPE_DEFS_PATH — type definitions used by this file
+- BASE_CLASS_PATH — parent class or service it extends
+- TEST_FILE_PATH — existing tests for this module
+- CONFIG_PATH — relevant config (tsconfig.json, etc.)
+
+Architecture: BRIEF_DESCRIPTION of how this module fits into the system.
+
+Scope: Only modify ALLOWED_FILES. Do not change EXCLUDED_FILES.
+Expected output: Modified files that resolve the type error.
+```
+
+## New Feature Template
+
+```
+Implement FEATURE_DESCRIPTION.
+
+Example to follow: EXAMPLE_FILE_PATH (shows the pattern for similar features)
+Create new files in: TARGET_DIRECTORY
+Naming convention: NAMING_PATTERN (e.g., camelCase, kebab-case)
+
+Related files:
+- ROUTER_OR_INDEX_PATH — where to register/export the new feature
+- TYPE_DEFS_PATH — existing types to reuse or extend
+- TEST_PATTERN_PATH — example test file showing test conventions
+
+Architecture: BRIEF_DESCRIPTION of how new features are structured in this project.
+
+Scope: Create new files in TARGET_DIRECTORY. Register in ROUTER_FILE. Do not modify EXCLUDED_FILES.
+Expected output: New files implementing the feature + registration in index/router.
+```
+
+## Explore / Research Template
+
+```
+Research QUESTION about this codebase.
+
+Start from these files:
+- FILE_1 — BRIEF_DESCRIPTION
+- FILE_2 — BRIEF_DESCRIPTION
+- FILE_3 — BRIEF_DESCRIPTION
+
+What I already know:
+- KNOWN_FACT_1
+- KNOWN_FACT_2
+
+Specific questions to answer:
+1. QUESTION_1
+2. QUESTION_2
+3. QUESTION_3
+
+Expected output: A summary answering each question with file paths and line references.
+```
+
+## Refactor Template
+
+```
+Refactor DESCRIPTION across these files:
+- FILE_1
+- FILE_2
+- FILE_3
+
+Current pattern: CURRENT_PATTERN_DESCRIPTION
+Target pattern: TARGET_PATTERN_DESCRIPTION
+
+Constraints:
+- CONSTRAINT_1 (e.g., "maintain backward compatibility with existing API")
+- CONSTRAINT_2 (e.g., "do not change test files, only source files")
+
+Type definitions: TYPE_DEFS_PATH
+Test file: TEST_FILE_PATH (run after refactor to verify)
+
+Expected output: Modified files following the target pattern. All existing tests must still pass.
+```
+
+## Multi-File Edit Template
+
+```
+Make the following related changes:
+
+1. In FILE_1: CHANGE_DESCRIPTION_1
+2. In FILE_2: CHANGE_DESCRIPTION_2
+3. In FILE_3: CHANGE_DESCRIPTION_3
+
+These changes are related because: RELATIONSHIP_DESCRIPTION
+
+Type definitions: TYPE_DEFS_PATH
+Config: CONFIG_PATH
+
+Verification: After all edits, run VERIFICATION_COMMAND to confirm no errors.
+Scope: Only modify the listed files.
+```

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,154 @@
+---
+name: codex-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.
+- 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` 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.
+10. If the diff touches a user-visible public surface (CLI flags, exported
+    symbols, config/openapi schema, contract docs, `README.md`, `CHANGELOG.md`),
+    record a `doc_delta_decision` in the closeout: `docs_updated`,
+    `docs_follow_up_filed`, or `no_doc_delta` (state why). This is the input the
+    autonomy-first doc-delta review gate checks; it defaults to warn (recorded,
+    non-blocking) and is satisfiable by the agent with no human.
+11. When reporting `verification_status=passed`, attach the verification
+    artifact (`artifact_paths.verification` or `verification_artifact_path`); if
+    the change has no executable verification, record a
+    `verification_evidence_opt_out` reason (`no_executable_verification`,
+    `verification_deferred_to_later_phase`, or `operator_attested_manual`). This
+    is the input the verification-evidence review gate checks (warn by default).
+
+## 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/codex-execute-phase/README.md

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