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

phase_loop_runtime/skills_bundle/claude-run-train/README.md

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

phase_loop_runtime/skills_bundle/claude-run-train/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: claude-run-train
+description: "Harness Code entry point for the cross-repo release-train coordinator. Use when the user wants to run, resume, or inspect a multi-repo train roadmap: draft PRs across all nodes in topo order, gather train-level review, then merge sequentially with downstream re-verification."
+---
+
+# Harness Run Train
+
+Thin bridge for the `phase-loop run-train` coordinator. All preflight,
+draft-PR sequencing, train-level review, sequential merge, and downstream
+re-verify logic lives in the runtime; this skill is the human entry point only.
+Do NOT re-implement or contradict runtime guarantees here.
+
+## Core Rules
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+- Use the repo-local CLI: `phase-loop run-train --train <train-roadmap-file>`.
+- Pass `--governed` to enable the merge phase (train-level review + sequential
+  merge + downstream re-verify). Omitting `--governed` stops at `drafts_open`.
+- Do NOT invoke `phase-loop run` on the train roadmap file — that is the
+  per-repo loop and will not orchestrate a multi-repo train.
+- Do NOT merge, force-push, or close PRs outside the coordinator; the runtime
+  enforces the partial-merge and false-green guards.
+- Inspect `phase-loop train-status --train <file>` to check the ledger without
+  modifying state.
+
+## Inputs
+
+- Train roadmap path: a Markdown file with `## Nodes` listing
+  `### Node: <repo> / <plan>` entries with `**Depends on:**` and
+  `**Channel:**` fields.
+- Optional `--governed` flag: activates train-level review → sequential merge →
+  downstream re-verify.
+- Optional `--ledger <path>`: explicit ledger path for crash-resume.
+
+## Workflow
+
+1. Resolve the train roadmap path (explicit arg or the user-supplied path).
+2. Run preflight:
+   `phase-loop run-train --train <file> --dry-run` (or inspect logs for
+   preflight errors before the first real run).
+3. Open draft PRs across all nodes in topo order:
+   `phase-loop run-train --train <file>`
+   The coordinator runs each repo's `run_loop` in series; a preflight failure
+   stops before any PR is opened.
+4. After all draft PRs are open (`status=drafts_open`), gather review:
+   `phase-loop run-train --train <file> --governed`
+   The train-level panel reviews the full set of draft changes.
+5. On approval, the coordinator merges upstream nodes first, then re-verifies
+   each downstream node against the upstream MERGED SHA before merging it.
+   A re-verify failure halts the merge at that node; upstream merges are
+   forward-only (never reverted).
+6. Inspect the outcome: `phase-loop train-status --train <file>`.
+
+## Failure Diagnostics
+
+- `preflight_failed`: one or more nodes failed preflight checks; zero PRs were
+  opened. Fix the reported issues and re-run.
+- `drafts_open`: draft PRs opened; merge phase not yet run. Pass `--governed`
+  to continue to review and merge.
+- `review_halted`: the train-level panel did not approve; `terminal_blocker`
+  carries `human_required=False` (the block is a non-human review terminal).
+  No nodes were merged. Re-run after addressing review findings.
+- `merge_halted`: upstream node(s) merged but a downstream re-verify failed;
+  the failed node and all its dependents are blocked. The forward-only guard
+  means already-merged nodes stay merged. Fix the integration issue and resume.
+- `merge_failed`: a merge call returned an error (e.g. conflict, branch
+  protection). The ledger records the failed node as `blocked`. Fix and resume.
+
+## Resume
+
+The coordinator is crash-resumable. If a run is interrupted, re-invoke the
+same command with `--governed`; the ledger state drives which nodes are skipped
+(already merged), re-verified (upstream merged but downstream not yet merged),
+or retried (blocked).

phase_loop_runtime/skills_bundle/claude-skill-editor/README.md

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

phase_loop_runtime/skills_bundle/claude-skill-editor/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: claude-skill-editor
+description: "Harness Code skill editor. Applies plans from <harness>-skill-improvement-planner, updates targeted skills, and archives consumed reflections after successful edits."
+---
+
+# <harness>-skill-editor
+
+## Runtime State
+
+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.
+
+Applies the plan produced by `<harness>-skill-improvement-planner` to the target SKILL.md files. Interprets each recommendation, edits the file, mirrors across repos if the skill is dual-homed, and archives the reflections the plan consumed so they won't drive another pass.
+
+## Pipeline
+
+Harness meta-skill source changes move through three tiers:
+
+1. Canonical source: `<harness>-config/<harness>-skills/<harness>-<skill>/SKILL.md`.
+2. Harness-neutral bundle: `vendor/phase-loop-skills/<bare-skill>/SKILL.md`, currently bundle-derived-from-codex.
+3. Installed runtime roots: `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/`, and `~/.opencode/skills/`.
+
+Edit only the canonical source tier during skill-editor runs. Leave the neutral bundle and installed runtime roots stale until the end-of-v36 cutover. After successful edits, report that the required follow-up is bundle regeneration from the codex-derived source path plus `./bootstrap.sh`, which installs the bundle with `python3 -m phase_loop_runtime.cli install --source vendor/phase-loop-skills --symlink --apply`.
+
+## When to use
+
+- Right after a `<harness>-skill-improvement-planner` run. Its handoff points here.
+- The user names a plan file explicitly and wants it applied.
+
+## When NOT to use
+
+- No plan file exists → run `/<harness>-skill-improvement-planner` first.
+- User wants to edit a skill's instructions by hand → this skill is for applying a structured plan, not arbitrary edits.
+
+## Inputs
+
+| Arg | Required | Meaning |
+|---|---|---|
+| `<plan-path>` | no | Absolute path to a plan produced by `<harness>-skill-improvement-planner`. Default: read `resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/latest.md`'s `artifact:` field. |
+| `--dry-run` | no | Parse the plan and print what WOULD change without editing any files. |
+| `--no-push` | no | Commit but skip `git push`. Default: push. |
+| `--no-mirror` | no | Edit dotfiles only; skip team-repo mirror. |
+
+## Workflow
+
+### Step 0 — Resolve plan path
+
+If `<plan-path>` passed, use it verbatim.
+
+Else read `resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/latest.md`:
+
+- Validate YAML frontmatter `from: <harness>-skill-improvement-planner`. On mismatch → flag via `AskUserQuestion` with `[use anyway, provide plan path, abort]`.
+- Validate timestamp < 7 days old. On staleness → same AskUserQuestion.
+- Extract `artifact:` → this is the plan path.
+
+If neither source yields a path, stop and ask the user to provide one via `AskUserQuestion`.
+
+### Step 1 — Parse the plan
+
+Read the plan file. Extract:
+
+- **Frontmatter** — YAML block at top. Fields:
+  - `from: <harness>-skill-improvement-planner` (validate)
+  - `timestamp:`
+  - `min_reflections:`
+  - `reflections_consumed:` — list of absolute paths (this is the archival worklist)
+- **Recommendations per skill** — `### <skill-name>` subheadings under `## Recommendations by skill`. For each subheading, collect every `**Change**:` bullet with its `**Rationale**:` and `**Supporting reflections**:` lines.
+- **Cross-cutting recommendations** — same structure under `## Cross-cutting recommendations`; these name multiple skills each.
+- **Speculative / low-confidence notes** — record but do not act on.
+- **Contradictions surfaced** — record and print to user; do not auto-resolve. If contradictions exist, surface before applying and offer to skip affected recommendations.
+
+Build a per-skill work list. Each entry: `(skill_name, change_text, rationale, supporting_reflection_versions)`.
+
+### Step 2 — Validate
+
+- Every `reflections_consumed` path exists on disk. If any are missing → warn the user; skip them for archival but continue with edits.
+- Every target skill named in recommendations has a canonical SKILL.md at `<harness>-config/<harness>-skills/<harness>-<skill>/SKILL.md` when working in this dotfiles repo; use `resolve_skill_bundle_root("claude")/<skill>/SKILL.md` only as a runtime fallback when no canonical source path exists. If missing → fail that recommendation, note in the outcome report.
+- Detect double-application: if the plan's timestamp is already recorded in `resolve_skill_bundle_root("claude")/<harness>-skill-editor/applied-plans.log`, ask via `AskUserQuestion` with `[apply again, abort]` — applying twice is usually wrong.
+
+On `--dry-run`, skip to Step 7 (print the worklist and exit).
+
+### Step 3 — Apply recommendations (per-recommendation frontier-tier Agent)
+
+For each recommendation, spawn an Agent to apply it. Resolve `<frontier>` from the `<harness>-execute-phase` Model tiers table.
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: "<frontier-model-id>",
+  name: "<harness>-skill-editor-<skill>-<seq>",
+  prompt: <contents of assets/editor_prompt.md>
+        + "\n\n# Target skill\n<skill-name>"
+        + "\n\n# Target SKILL.md path\n<absolute path>"
+        + "\n\n# Change to apply\n<change text>"
+        + "\n\n# Rationale\n<rationale text>"
+)
+```
+
+The Agent has Read/Edit/Write tools. It reads the target SKILL.md, applies the specified change in directive-only style (preserving house style), and reports outcome JSON: `{applied: bool, files_modified: [path], diff_summary: "...", error: "..."}`.
+
+Track per-recommendation outcomes. Don't stop on individual failures — collect them all for the final report.
+
+Dispatch in parallel where safe: multiple recommendations targeting different skills can run concurrently. Multiple recommendations targeting the **same** skill must serialize (sequential Edit calls to the same file can conflict).
+
+### Step 4 — Mirror to team repo (if `--no-mirror` not set)
+
+For each successfully edited dotfiles SKILL.md at `~/code/dotfiles/<harness>-config/skills/<skill>/`, check whether a counterpart exists in `~/code/<harness>-code-skills/` (under `planning-chain/`, `efficiency-kit/`, or `meta/`).
+
+- If counterpart exists → `cp` the edited SKILL.md over.
+- If absent → note in the outcome report; the skill either isn't shipped to the team repo, or is at a non-standard path the mirror didn't find.
+
+Skip mirror for scripts in `_shared/` (they map to `tools/` in the team repo); mirror those only if explicitly edited — same pattern via cp.
+
+### Step 5 — Archive consumed reflections
+
+Per the plan's archival directive. For each reflection in `reflections_consumed`:
+
+1. Collect every recommendation that cited this reflection (via `**Supporting reflections**`).
+2. If ALL citing recommendations succeeded → archive the reflection:
+   ```bash
+   mkdir -p <reflection-parent>/archive
+   mv <reflection> <reflection-parent>/archive/<basename>
+   ```
+3. If ANY citing recommendation failed → leave the reflection in place so next cycle can reconsider.
+
+A reflection cited by zero surviving recommendations (e.g., its theme was rejected as repo-specific) is still archived — it's been considered.
+
+### Step 6 — Commit + push
+
+Dotfiles:
+
+```bash
+cd ~/code/dotfiles
+git add -A <harness>-config/skills/
+git commit -m "chore(skills): apply improvement plan <plan-timestamp>
+
+Applied N of M recommendations from <plan-path>. See the plan file for
+per-skill details. Reflections consumed this run moved to each skill's
+reflections/<repo_hash>/<branch_slug>/archive/ subdirectory.
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
+```
+
+Team repo (if edits landed there):
+
+```bash
+cd ~/code/<harness>-code-skills
+git add -A
+git commit -m "chore: mirror skill edits from dotfiles improvement plan <plan-timestamp>"
+```
+
+`git push` in both unless `--no-push`.
+
+Append the plan's timestamp + path to `resolve_skill_bundle_root("claude")/<harness>-skill-editor/applied-plans.log` so Step 2's double-apply check has state to read.
+
+### Step 7 — Close-out (standard pattern)
+
+Resolve paths:
+
+```bash
+REFLECTION_PATH=$(python3 resolve_skill_bundle_root("claude")/_shared/next_reflection_path.py <harness>-skill-editor)
+REPO_LOCAL_HANDOFF=<repo>/.dev-skills/handoffs/<harness>-skill-editor/latest.md
+SKILL_MD=resolve_skill_bundle_root("claude")/<harness>-skill-editor/SKILL.md
+```
+
+Spawn ONE close-out agent on the `frontier` tier. It writes both files via the Write tool:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: "<frontier-model-id>",
+  name: "<harness>-skill-editor-closeout",
+  prompt: """
+    Review the skill at <SKILL_MD> and the current execution transcript.
+    Produce TWO files via the Write tool.
+
+    FILE 1 — REPO-AGNOSTIC reflection → write to <REFLECTION_PATH>
+
+      # <harness>-skill-editor reflection — <ISO>
+
+      ## What worked
+      - <bullet about the SKILL's instructions>
+
+      ## Improvements to SKILL.md
+      - <specific, actionable change>
+
+      Do NOT reference this project or the specific plan applied.
+
+    FILE 2 — REPO-SPECIFIC handoff → write to <REPO_LOCAL_HANDOFF>
+
+      ---
+      from: <harness>-skill-editor
+      timestamp: <ISO>
+      artifact: <plan path that was applied>
+      ---
+
+      # Handoff
+
+      ## Summary
+      <applied N of M recommendations from the plan; archived K reflections.>
+
+      ## Key decisions made this run
+      - <which recommendations were skipped and why, e.g., contradictions
+         surfaced, target skill missing, agent error>
+
+      ## Files changed this run
+      - <SKILL.md paths + commit SHAs>
+
+      ## Next skill
+      - Usually no immediate next skill — the pipeline has closed the loop.
+        A new `/<harness>-phase-roadmap-builder` run will pick up the improved
+        instructions naturally.
+  """
+)
+```
+
+Exit message to user:
+
+> Applied `<N>` of `<M>` recommendations from `<plan-path>`.
+> `<K>` reflections archived.
+> Reflection saved to `<REFLECTION_PATH>`.
+> Handoff written to `<REPO_LOCAL_HANDOFF>`.
+> Required cutover follow-up: regenerate the bundle from the codex-derived source path and run `./bootstrap.sh`.
+>
+> Recommended next step: run `/clear`. The improved skill instructions take effect on the next pipeline invocation.
+
+## Failure policy
+
+- **Agent can't apply an edit** → mark recommendation failed, preserve its supporting reflections, continue with others.
+- **Target skill missing** → mark failed, preserve its reflections, continue.
+- **Plan file malformed** → surface to user via `AskUserQuestion`, offer abort.
+- **Contradictions in plan** → print both sides, ask user which (or neither) to apply, continue with the rest.
+- **Commit or push fails** → report to user; leave the working tree as-is for inspection.
+
+## Reference files
+
+- `assets/editor_prompt.md` — the full prompt given to each edit Agent.
+
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+## Closeout
+
+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.

phase_loop_runtime/skills_bundle/claude-skill-editor/assets/editor_prompt.md

@@ -0,0 +1,72 @@
+# Editor prompt
+
+You are applying **one** recommendation from a skill improvement plan to **one** target SKILL.md. The recommendation was produced by an aggregator that distilled multiple reflection files; you're the last link in the chain.
+
+## Your inputs
+
+- **Target skill** — the skill's name (e.g., `claude-plan-phase`).
+- **Target SKILL.md path** — absolute path.
+- **Change to apply** — a natural-language instruction in directive-only imperative form.
+- **Rationale** — why this change was proposed (one clause).
+
+(These are appended to the end of this prompt by the caller.)
+
+## Your task
+
+1. `Read` the target SKILL.md in full.
+2. Interpret the change. Find the specific location in the file where it applies. If the change names a step, heading, or section (e.g., "In Step 5 of claude-plan-phase/SKILL.md, add a bullet after 'Apply the claude-task-contextualizer checklist' stating: …"), locate that anchor.
+3. Apply the change with `Edit`. Preserve:
+   - **Directive-only house style.** Imperative form. No war stories, no stats, no narrative justification. Reasons stated in one clause.
+   - **Existing structure.** Headings, tables, lists stay where they are unless the change explicitly moves them.
+   - **Exact whitespace.** Match indentation (tabs vs spaces) from the surrounding lines.
+   - **Existing cross-references.** If the change adds a new rule, don't accidentally break a pointer from another section.
+4. Verify: `Read` the modified region after editing. Confirm the change landed in the right place and the surrounding text still makes sense.
+
+## Refusing to apply
+
+You **must** refuse (and report `applied: false`) if any of:
+
+- The change names a specific project, codebase, domain, filename outside this skill, or company — the plan should have rejected these, but a slipped one surfaces here. Say so in `error`.
+- The change is too vague to pin to a specific location ("improve Step 5 somehow"). Say so in `error` and quote the vague phrasing.
+- The target file doesn't have the anchor the change references (e.g., "after 'Apply the claude-task-contextualizer checklist'" but no such line exists). Say so in `error` and list what you searched for.
+- Applying would contradict an instruction already present (without the change text acknowledging the contradiction). Say so in `error`.
+
+Do not attempt partial or creative application in any of these cases — better to fail cleanly and let the planner's next cycle reconsider.
+
+## House style reference
+
+Before editing, skim the skill's existing prose to match tone. The pattern across this repo:
+
+- Every rule uses imperative form ("Do X.", "Run Y."). Not "You should do X" or "X is recommended."
+- Rationale is a single clause ("because downstream lanes depend on it") rather than a paragraph.
+- No self-referential filler ("The skill is designed to…"). Just the directive.
+- Tables over prose where a table fits.
+- References to other skills use `/<skill-name>` (the invocation form) not `<skill-name>/SKILL.md` (the filesystem form), unless specifically naming a file.
+
+## Your response
+
+After editing (or deciding not to), return a single JSON object on stdout:
+
+```json
+{
+  "applied": true,
+  "files_modified": ["/abs/path/to/SKILL.md"],
+  "diff_summary": "Added bullet to Step 5 brief-construction list specifying that phase Exit criteria must be copied verbatim, not paraphrased.",
+  "error": null
+}
+```
+
+Or on failure:
+
+```json
+{
+  "applied": false,
+  "files_modified": [],
+  "diff_summary": null,
+  "error": "Change references 'after \"Apply the claude-task-contextualizer checklist\"' but no such line exists in the target file. Closest match: 'Apply the `/claude-task-contextualizer` checklist to every brief.' — unclear if these are the same anchor."
+}
+```
+
+Keep `diff_summary` to one sentence. Keep `error` specific enough that the planner's next run can address it.
+
+Do not output anything before the JSON object.

phase_loop_runtime/skills_bundle/claude-skill-improvement-planner/README.md

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

phase_loop_runtime/skills_bundle/claude-skill-improvement-planner/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: claude-skill-improvement-planner
+description: "Harness Code skill feedback aggregator. Reads workflow skill reflections, groups recurring recommendations, and writes an improvement plan for <harness>-skill-editor."
+---
+
+# <harness>-skill-improvement-planner
+
+## Runtime State
+
+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.
+
+Reads reflection files produced by the planning-chain skills' close-out steps — plus reflections emitted by the meta-skills (`<harness>-skill-improvement-planner`, `<harness>-skill-editor`) themselves — aggregates recurring themes across runs, and writes an improvement plan. Does not edit skills. A separate `<harness>-skill-editor` skill ingests the plan and performs the edits. Including the meta-skills' own reflections closes the self-improvement loop so this planner and the editor can be iterated on with the same pipeline they drive.
+
+## Pipeline
+
+Harness meta-skill source changes move through three tiers:
+
+1. Canonical source: `<harness>-config/<harness>-skills/<harness>-<skill>/SKILL.md`.
+2. Harness-neutral bundle: `vendor/phase-loop-skills/<bare-skill>/SKILL.md`, currently bundle-derived-from-codex.
+3. Installed runtime roots: `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/`, and `~/.opencode/skills/`.
+
+SP-DOC edits only the canonical source tier. Leave the neutral bundle and installed runtime roots stale until the end-of-v36 cutover. The cutover regenerates the bundle from the codex-derived source path and runs `./bootstrap.sh`, which installs the bundle with `python3 -m phase_loop_runtime.cli install --source vendor/phase-loop-skills --symlink --apply`.
+
+## When to use
+
+- The user wants to audit accumulated reflections and decide what to change.
+- Several phases have executed; reflections have built up at `resolve_skill_bundle_root("claude")/<skill>/reflections/`.
+- The user asks about updating skills based on past runs.
+
+## When NOT to use
+
+- User wants to edit a skill directly — they want `/<harness>-skill-editor` (once it exists) or manual edits.
+- No reflections exist yet — the skill will exit with a user-facing message.
+
+## Inputs
+
+| Arg | Required | Meaning |
+|---|---|---|
+| `--target <skill-name>` | no | Plan only for one skill; skip the rest. Default: all five skills (the three pipeline skills plus the two meta-skills). |
+| `--min-reflections <N>` | no | Default 2. Skip skills with fewer new (un-archived) reflections to avoid acting on noise. |
+| `--output <path>` | no | Override the generated plan path. |
+
+## Workflow
+
+### Step 1 — Enumerate reflections
+
+Glob these paths, excluding any `archive/` subdirectory. For each skill, scan both the Harness runtime reflection root and the codex-derived source-controlled reflection root:
+
+- `resolve_skill_bundle_root("claude")/<harness>-phase-roadmap-builder/reflections/**`
+- `resolve_skill_bundle_root("codex")/<harness>-phase-roadmap-builder/reflections/**`
+- `resolve_skill_bundle_root("claude")/<harness>-plan-phase/reflections/**`
+- `resolve_skill_bundle_root("codex")/<harness>-plan-phase/reflections/**`
+- `resolve_skill_bundle_root("claude")/<harness>-execute-phase/reflections/**`
+- `resolve_skill_bundle_root("codex")/<harness>-execute-phase/reflections/**`
+- `resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/reflections/**`
+- `resolve_skill_bundle_root("codex")/<harness>-skill-improvement-planner/reflections/**`
+- `resolve_skill_bundle_root("claude")/<harness>-skill-editor/reflections/**`
+- `resolve_skill_bundle_root("codex")/<harness>-skill-editor/reflections/**`
+
+The last two close the self-improvement loop: this planner and the editor write reflections on their own runs, and those reflections must be aggregated here or the meta-skills can never be improved by their own pipeline. A missing `reflections/` directory for either meta-skill is not an error — they materialize lazily on first close-out.
+
+If `--target <skill>` is set, limit to that one skill.
+
+### Step 2 — Parse each reflection
+
+For each file:
+
+- **Skill name**: parent directory's parent name.
+- **Version**: extract from filename (`<skill>-reflection-v(\d+)\.md`); fall back to mtime for non-standard filenames.
+- **Body**: read; extract the `## What worked` and `## Improvements to SKILL.md` sections. If those headings are absent (older or hand-named reflection), keep the raw body and tag as `unstructured`.
+
+### Step 3 — Gate on minimum
+
+- Total reflections = 0 → print "No reflections to aggregate. Reflections not yet written at `resolve_skill_bundle_root("claude")/<skill>/reflections/`, or all are archived." Exit 0.
+- Per skill: new reflections < `--min-reflections` → skip that skill; note in the plan summary.
+
+### Step 4 — Aggregate via frontier-tier Agent
+
+Resolve the `frontier` tier from `<harness>-execute-phase`'s Model tiers table. Spawn one Agent:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: "<frontier-model-id>",
+  name: "skill-improvement-aggregator",
+  prompt: <contents of assets/aggregator_prompt.md>
+        + "\n\n# Reflections to aggregate\n\n" + <concatenated reflection bodies, grouped by skill, with version tags>
+)
+```
+
+The aggregator prompt (in `assets/aggregator_prompt.md`) instructs the Agent to:
+
+- Identify recurring themes (≥ `--min-reflections` distinct reflections per skill, or ≥ 2 across skills for cross-cutting).
+- Separate high-confidence actionable from speculative one-offs.
+- Flag contradictions.
+- Propose concrete SKILL.md edits in directive-only style.
+- Enforce repo-agnostic output — reject or rewrite any recommendation that names a specific project, codebase, domain, or filename.
+- Cite supporting reflection versions per theme.
+
+### Step 5 — Write the plan file
+
+Resolve the next plan path:
+
+```bash
+N=$(ls resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/plans/ 2>/dev/null | grep -c '^plan-v')
+PLAN_PATH=resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/plans/plan-v$((N+1))-$(date -u +%Y%m%dT%H%M%SZ).md
+```
+
+Write the plan using the template in `## Plan file format` below. The frontmatter's `reflections_consumed` field must list absolute paths to every reflection that was read — this is how the downstream <harness>-skill-editor knows what to archive.
+
+### Step 6 — Close-out (standard artifact-producing pattern)
+
+No cleanup commit needed (plans/ is gitignored; no other files changed). Verify `git status` clean with the allowlist `plans/` and exit.
+
+Resolve close-out paths:
+
+```bash
+REFLECTION_PATH=$(python3 resolve_skill_bundle_root("claude")/_shared/next_reflection_path.py <harness>-skill-improvement-planner)
+REPO_LOCAL_HANDOFF=<repo>/.dev-skills/handoffs/<harness>-skill-improvement-planner/latest.md
+SKILL_MD=resolve_skill_bundle_root("claude")/<harness>-skill-improvement-planner/SKILL.md
+```
+
+Spawn ONE close-out agent on the `frontier` tier. It writes both files directly via the Write tool:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: "<frontier-model-id>",
+  name: "<harness>-skill-improvement-planner-closeout",
+  prompt: """
+    Review the skill at <SKILL_MD> and the current execution transcript.
+    Produce TWO files via the Write tool.
+
+    FILE 1 — REPO-AGNOSTIC reflection → write to <REFLECTION_PATH>
+
+      # <harness>-skill-improvement-planner reflection — <ISO>
+
+      ## What worked
+      - <bullet about the SKILL's instructions>
+
+      ## Improvements to SKILL.md
+      - <specific, actionable change>
+
+      Do NOT reference this project or the specific reflections aggregated
+      this run.
+
+    FILE 2 — REPO-SPECIFIC handoff → write to <REPO_LOCAL_HANDOFF>
+
+      ---
+      from: <harness>-skill-improvement-planner
+      timestamp: <ISO>
+      artifact: <absolute path to plan file>
+      ---
+
+      # Handoff for <harness>-skill-editor
+
+      ## Summary
+      <1–2 sentences: plan path, how many reflections aggregated,
+       how many recommendations produced>
+
+      ## Key decisions made this run
+      - <what themes were promoted vs deferred>
+
+      ## Open items for <harness>-skill-editor
+      - <read the plan at <path>; apply recommendations in order;
+         archive consumed reflections per the plan's directive>
+
+      ## Files to watch for <harness>-skill-editor
+      - <target SKILL.md files named in the plan>
+  """
+)
+```
+
+Exit message to user:
+
+> Plan written to `<PLAN_PATH>`.
+> Reflection saved to `<REFLECTION_PATH>`.
+> Handoff written to `<REPO_LOCAL_HANDOFF>`.
+>
+> Recommended next step: run `/clear`, then invoke `/<harness>-skill-editor <PLAN_PATH>`. The editor will apply the recommendations and archive the reflections this plan consumed. If `/<harness>-skill-editor` isn't installed yet, the plan is still readable and actionable by hand.
+
+## Plan file format
+
+```markdown
+---
+from: <harness>-skill-improvement-planner
+timestamp: <ISO>
+min_reflections: <N>
+reflections_consumed:
+  - /absolute/path/to/reflection1.md
+  - /absolute/path/to/reflection2.md
+  - …
+---
+
+# Skill improvement plan — <ISO>
+
+## Summary
+<1–2 paragraphs: reflections read, skills covered, headline themes, contradictions surfaced.>
+
+## Recommendations by skill
+
+### <skill-name>
+- **Change**: <specific SKILL.md edit, directive-only imperative form>
+  - **Rationale**: <recurring theme this addresses>
+  - **Supporting reflections**: v3, v5, v7
+- …
+
+(Repeat per skill. If a skill had no actionable themes, write: "No recurring themes above the `--min-reflections` threshold.")
+
+## Cross-cutting recommendations
+<themes that affect multiple skills at once>
+
+## Speculative / low-confidence notes
+<one-off feedback worth recording but not acting on yet>
+
+## Contradictions surfaced
+<reflections that disagreed; surface for user judgment>
+
+## Archival directive for <harness>-skill-editor
+
+After successfully applying each recommendation above, move every file listed under `reflections_consumed` (frontmatter) to `<reflections-dir>/archive/<original-filename>`. Create the `archive/` subdirectory if absent. This prevents re-aggregating the same feedback next cycle. If a specific recommendation fails to apply, leave its supporting reflections in place so the next planning pass can reconsider them.
+```
+
+## Archive convention
+
+New convention introduced by this skill (the downstream editor performs the move):
+
+- Path: `resolve_skill_bundle_root("claude")/<skill>/reflections/<repo_hash>/<branch_slug>/archive/<original-filename>`
+- Directory created lazily on first archive.
+- This planner excludes `archive/` when globbing.
+- Already gitignored — `<harness>-config/skills/*/reflections/` in dotfiles covers `archive/` as a subpath.
+
+## Best practices followed
+
+- Directive-only: imperative form, no narratives, no stats.
+- Progressive disclosure: the long aggregator prompt lives in `assets/aggregator_prompt.md`, not inline.
+- Close-out pattern matches the pipeline skills so this skill's own corpus feeds future self-improvement passes.
+- Repo-agnostic enforcement is load-bearing — aggregated reflections drive changes to SKILL.md files that ship to every repo, so any repo-specific leakage would propagate.
+
+## Reference files
+
+- `assets/aggregator_prompt.md` — the full prompt given to the aggregation Agent.
+
+
+Use `phase_loop_runtime.skill_paths` resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.
+
+## Closeout
+
+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.