claude-dev-env 2.18.0 → 2.20.0

package/.agents/skills/AGENTS.md

@@ -35,15 +35,15 @@ contracts, runtime scripts). Map: `skills/_shared/.claude/CLAUDE.md`. End-of-run
 
 **PR review and convergence**
 
-- `shared-extraction-audit` — audits workflow packages for helpers that belong in shared libraries; extracts in small tested CLs
-- `name-by-capability-audit` — audits PR paths/titles for driver/motive words on reusable capability code
+- `pr-shared-extraction` — audits workflow packages for helpers that belong in shared libraries; extracts in small tested CLs
+- `pr-name-by-capability` — audits PR paths/titles for driver/motive words on reusable capability code
 - `review-tier` — classifies `review_tier_constants` from change axes, hard triggers, and user overrides
 - `review-router` — resolves and arms one supported `route_review_config` route through the registered Agent|Task gate
-- `pr-cleanup` — one-agent end-to-end PR cleanup: extraction → naming → sr-loop → small-cl; apply and validate fixes as they return
+- `pr-cleanup` — one-agent end-to-end PR cleanup: extraction → naming → sr-loop → pr-small-cl; apply and validate fixes as they return
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready
 - `e-code-review` — max-recall code review at a selectable effort level
 - `e-simplify` — cleanup-only pass on the current diff
-- `small-cl` — the Small CLs guide for scope and split decisions
+- `pr-small-cl` — the Small CLs guide for scope and split decisions
 
 **Research and discovery**
 - `everything-search` — file-system search via the Everything `es.exe` CLI on Windows

package/.agents/skills/_shared/AGENTS.md

@@ -37,6 +37,7 @@
 | `pr-loop/gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
 | `pr-loop/post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
 | `pr-loop/precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `pr-loop/preflight-proposal.md` | `@~/.claude/_shared/pr-loop/preflight-proposal.md` |
 | `pr-loop/state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
 | `pr-loop/worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
 | `pr-loop/scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |

package/.agents/skills/_shared/pr-loop/AGENTS.md

@@ -26,6 +26,7 @@ Open a stub, then load the `@` target:
 | `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
 | `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
 | `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `preflight-proposal.md` | `@~/.claude/_shared/pr-loop/preflight-proposal.md` |
 | `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
 | `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
 | `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |

package/.agents/skills/_shared/pr-loop/preflight-proposal.contract.test.mjs

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url))
+const canonicalContractSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../../../_shared/pr-loop/preflight-proposal.md'),
+  'utf8',
+)
+const sharedSkillSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../pr-shared-extraction/SKILL.md'),
+  'utf8',
+)
+const capabilitySkillSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../pr-name-by-capability/SKILL.md'),
+  'utf8',
+)
+const capabilityTaskSeedsSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../pr-name-by-capability/reference/task-seeds.md'),
+  'utf8',
+)
+const reviewSkillSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../e-code-review/SKILL.md'),
+  'utf8',
+)
+const reviewProposalSource = readFileSync(
+  resolve(THIS_DIRECTORY, '../../e-code-review/reference/preflight-proposal.md'),
+  'utf8',
+)
+
+const allSkillContracts = [
+  {
+    name: 'shared extraction audit',
+    skillSource: sharedSkillSource,
+    invocationPattern: /pr-shared-extraction preflight-proposal/,
+    classificationPattern: /priority and target/,
+    expectedDefaultBehavior: 'applies the prioritized fix band by default',
+  },
+  {
+    name: 'name by capability audit',
+    skillSource: capabilitySkillSource,
+    invocationPattern: /pr-name-by-capability preflight-proposal/,
+    classificationPattern: /violation or OK-driver classification/,
+    expectedDefaultBehavior: 'applies the suggested rename direction by default',
+  },
+]
+
+function assertProposalAdapter(skillContract) {
+  const preflightRoutingOffset = skillContract.skillSource.indexOf('`preflight-proposal`')
+  const reportOnlyRoutingOffset = skillContract.skillSource.indexOf('`audit-only`')
+
+  assert.ok(preflightRoutingOffset >= 0, `${skillContract.name} selects proposal mode`)
+  assert.ok(preflightRoutingOffset < reportOnlyRoutingOffset, `${skillContract.name} routes proposal mode first`)
+  assert.match(skillContract.skillSource, skillContract.invocationPattern)
+  assert.match(skillContract.skillSource, skillContract.classificationPattern)
+  assert.match(skillContract.skillSource, new RegExp(skillContract.expectedDefaultBehavior))
+}
+
+function assertTaskRoutingAndNormalMode() {
+  assert.match(sharedSkillSource, /Register this checklist with `update_plan`/)
+  assert.match(capabilitySkillSource, /Register every bullet from `reference\/task-seeds\.md` with `update_plan`/)
+  assert.match(capabilityTaskSeedsSource, /Register each item with `update_plan`/)
+  assert.doesNotMatch(sharedSkillSource, /TodoWrite|TaskCreate/)
+  assert.doesNotMatch(capabilitySkillSource, /TodoWrite|TaskCreate/)
+  assert.doesNotMatch(capabilityTaskSeedsSource, /TodoWrite|TaskCreate/)
+  assert.match(sharedSkillSource, /audit-only` is report-only/)
+  assert.match(capabilitySkillSource, /audit-only` is report-only/)
+}
+
+function assertSharedProposalContract(contractSource) {
+  assert.match(contractSource, /caller-supplied isolated worktree/)
+  assert.match(contractSource, /resolved PR number/)
+  assert.match(contractSource, /immutable base SHA/)
+  assert.match(contractSource, /immutable head SHA/)
+  assert.match(contractSource, /exact `base_sha\.\.\.head_sha` range/)
+  assert.match(contractSource, /require exact equality with the head SHA/)
+  assert.match(contractSource, /immutable proposal identity/)
+  assert.match(contractSource, /deterministic diff hash/)
+  assert.match(contractSource, /changed paths/)
+  assert.match(contractSource, /exact tests and outcomes/)
+  assert.match(contractSource, /selected-candidate-ready proposal evidence/)
+  assert.match(contractSource, /selected or dispositioned proposal collection/)
+  assert.match(contractSource, /Reapplication uses exactly the selected records/)
+}
+
+function assertReviewProposalAdapter() {
+  const preflightRoutingOffset = reviewSkillSource.indexOf('`preflight-proposal`')
+  const refusalRoutingOffset = reviewSkillSource.indexOf('**Refusal — first match wins:**')
+  const allProposalEntryMatches = reviewSkillSource.match(
+    /Route the selected mode through \[reference\/preflight-proposal.md\]\(reference\/preflight-proposal.md\) to establish proposal context/g,
+  ) ?? []
+
+  assert.ok(preflightRoutingOffset >= 0)
+  assert.ok(preflightRoutingOffset < refusalRoutingOffset)
+  assert.equal(allProposalEntryMatches.length, 1)
+  assert.match(reviewSkillSource, /e-code-review preflight-proposal/)
+  assert.match(reviewSkillSource, /`--level <low\|medium\|xhigh>`/)
+  assert.match(reviewSkillSource, /@~\/.claude\/_shared\/pr-loop\/preflight-proposal.md/)
+  assert.match(reviewSkillSource, /Normal mode follows the current level/)
+  assert.match(reviewProposalSource, /Keep Gate 1, Gate 2, the bare code-rules gate, and exact required tests/)
+  assert.match(reviewProposalSource, /review_level: low \| medium \| xhigh/)
+  assert.match(reviewProposalSource, /severity: blocker \| high \| medium \| low \| nit/)
+  assert.match(reviewProposalSource, /verdict: CONFIRMED \| PLAUSIBLE/)
+  assert.match(reviewProposalSource, /outcome: fixed \| no_change_needed \| skipped/)
+}
+
+test('audit modes retain their normal routing behavior', () => {
+  assertTaskRoutingAndNormalMode()
+})
+
+test('one shared contract defines proposal evidence for audit and review skills', () => {
+  for (const eachSkillContract of allSkillContracts) {
+    assertProposalAdapter(eachSkillContract)
+  }
+  assertReviewProposalAdapter()
+  assertSharedProposalContract(canonicalContractSource)
+})

package/.agents/skills/_shared/pr-loop/preflight-proposal.md

@@ -0,0 +1,5 @@
+# Preflight proposal contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/preflight-proposal.md

package/.agents/skills/e-code-review/SKILL.md

@@ -4,13 +4,23 @@ description: >-
   Max-recall code review at a selectable effort level (low, medium, xhigh), with
   optional auto-fix and an auto-execute loop for any level. Triggers:
   /e-code-review, /e-code-review low, /e-code-review medium, /e-code-review
-  xhigh, /e-code-review <level> --fix, /e-code-review <level> loop.
+  xhigh, /e-code-review <level> --fix, /e-code-review <level> loop,
+  /e-code-review preflight-proposal.
 ---
 
 # e-code-review
 
 **Pick a level, run that review, optionally fix and loop.** Each level has its own procedure file. Fix application lives in `reference/fix.md`; repeat-until-clean lives in `reference/loop.md`.
 
+## Mode routing
+
+Resolve the first matching invocation before the normal refusal and loop rules:
+
+1. `preflight-proposal` requires `<pr_number>`, `--level <low|medium|xhigh>`, `--base-sha <immutable SHA>`, `--head-sha <immutable SHA>`, and `--worktree <isolated path>`. The caller supplies `low` as the default level; `medium` and `xhigh` are valid selections. Route the selected mode through [reference/preflight-proposal.md](reference/preflight-proposal.md) to establish proposal context. The mode runs `<review_level> --fix loop` locally and returns selected-candidate-ready proposal evidence.
+2. Normal mode follows the current level, `--fix`, and `loop` behavior.
+
+The proposal mode applies the canonical proposal contract at `@~/.claude/_shared/pr-loop/preflight-proposal.md`. The local extension selects the review level and records finding outcomes. The downstream owner records selected proposal IDs before reapplication; each new finding receives a new ID.
+
 ## Gotchas
 
 - **`low` stays single-pass.** No subagents, no full-file reads: one read pass per target item, one findings pass.
@@ -61,6 +71,7 @@ Detail: `reference/effort-evaluation.md`.
 | `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
 | `reference/fix.md` | Fix application, code-rules gate, skip logging, outcome reporting |
 | `reference/loop.md` | Repeat review/fix rounds until clean |
+| `reference/preflight-proposal.md` | Isolated local review, immutable SHAs, proposal evidence, and mutation boundary |
 | `reference/effort-evaluation.md` | Effort evaluation fixtures, evidence, and skill defaults |
 | `reference/runner-selection.md` | Runner selection map |
 | `scripts/finding_pipeline.py` | Collect every real finding; filter severity only later |

package/.agents/skills/e-code-review/reference/fix.md

@@ -2,6 +2,10 @@
 
 When `--fix` is passed, apply the reviewed findings to the working tree.
 
+## Preflight-proposal mode
+
+When the hub selects `preflight-proposal`, consume the established proposal context, selected review level, and current pull-request head.
+
 ## Resume the finding agent
 
 For each finding, resume the same Agent-tool agent instance that originally
@@ -73,4 +77,4 @@ the fix, or later work fixes it incidentally — call the structured
 findings-report call again with the same findings, each carrying an
 `outcome` (`fixed`, `no_change_needed`, or `skipped`). Do not repeat the
 findings as text. Make that call immediately after the fixes land, before any
-prose summary.
+prose summary.

package/.agents/skills/e-code-review/reference/loop.md

@@ -1,5 +1,9 @@
 # Loop until clean
 
+## Preflight-proposal mode
+
+When the hub selects `preflight-proposal`, continue the review loop with the established proposal context. Proposal mode ends with proposal evidence. Normal mode keeps its GitHub disclosure and Ready actions.
+
 ## Act
 
 `loop` on the hub command authorizes the full cycle. After the effort level procedure returns findings, run the gate sequence below immediately.

package/.agents/skills/e-code-review/reference/mode-contract.test.mjs

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+
+const proposalSource = readFileSync(new URL('./preflight-proposal.md', import.meta.url), 'utf8')
+const fixSource = readFileSync(new URL('./fix.md', import.meta.url), 'utf8')
+const loopSource = readFileSync(new URL('./loop.md', import.meta.url), 'utf8')
+
+function sourceBetweenHeadings(source, fromHeading, toHeading) {
+  const fromOffset = source.indexOf(fromHeading)
+  const toOffset = source.indexOf(toHeading, fromOffset)
+
+  assert.ok(fromOffset >= 0)
+  assert.ok(toOffset > fromOffset)
+
+  return source.slice(fromOffset, toOffset)
+}
+
+function assertReviewLevelExtension() {
+  assert.match(proposalSource, /<review_level> --fix loop/)
+  const allReviewLevelMappings = [
+    ['Omitted override', 'low'],
+    ['`low`', 'low'],
+    ['`medium`', 'medium'],
+    ['`xhigh`', 'xhigh'],
+  ]
+
+  for (const [eachCallerSelection, eachLevel] of allReviewLevelMappings) {
+    const expectedRow = `| ${eachCallerSelection} | \`${eachLevel}\` |`
+    assert.match(proposalSource, new RegExp(expectedRow.replaceAll('|', '\\|')))
+  }
+  assert.match(proposalSource, /`review_level` evidence mirrors the resolved `--level` value/)
+}
+
+function assertProposalHandoffs() {
+  assert.match(proposalSource, /canonical contract owns the immutable range/)
+  const fixModeSource = sourceBetweenHeadings(
+    fixSource,
+    '## Preflight-proposal mode',
+    '## Resume the finding agent',
+  )
+  assert.match(fixModeSource, /consume the established proposal context/)
+  assert.doesNotMatch(fixModeSource, /follow \[preflight-proposal.md\]/)
+  const proposalModeSource = sourceBetweenHeadings(
+    loopSource,
+    '## Preflight-proposal mode',
+    '## Act',
+  )
+  assert.match(proposalModeSource, /continue the review loop with the established proposal context/)
+  assert.doesNotMatch(proposalModeSource, /follow \[preflight-proposal.md\]/)
+  assert.match(proposalModeSource, /Proposal mode ends with proposal evidence/)
+  assert.doesNotMatch(proposalModeSource, /proof-of-work PR comment|gh pr ready/)
+  assert.doesNotMatch(proposalSource, /proof-of-work PR comment|gh pr ready/)
+}
+
+function assertNormalTerminationContract() {
+  const normalTerminalSource = loopSource.slice(loopSource.indexOf('## Terminal outcomes'))
+  assert.match(normalTerminalSource, /proof-of-work PR comment/)
+  assert.match(normalTerminalSource, /gh pr ready/)
+}
+
+test('preflight proposal mode isolates review loops and preserves normal termination behavior', () => {
+  assertReviewLevelExtension()
+  assertProposalHandoffs()
+  assertNormalTerminationContract()
+})

package/.agents/skills/e-code-review/reference/preflight-proposal.md

@@ -0,0 +1,40 @@
+# Review preflight proposal mode
+
+Apply the canonical proposal contract at:
+
+```text
+@~/.claude/_shared/pr-loop/preflight-proposal.md
+```
+
+Use this review extension when the caller selects `preflight-proposal`:
+
+```text
+/e-code-review preflight-proposal <pr_number> --level low --base-sha <base_sha> --head-sha <head_sha> --worktree <isolated_worktree>
+```
+
+## Review extension
+
+The caller resolves the review level before invocation and always passes `--level`. Use this mapping:
+
+| Caller selection | Resolved `--level` |
+|---|---|
+| Omitted override | `low` |
+| `low` | `low` |
+| `medium` | `medium` |
+| `xhigh` | `xhigh` |
+
+The `review_level` evidence mirrors the resolved `--level` value.
+
+Run the selected level as `<review_level> --fix loop`. The selected level owns its normal finding and fix rules. Require `HEAD` to equal the supplied head SHA before each round.
+
+Keep Gate 1, Gate 2, the bare code-rules gate, and exact required tests. Extend the canonical evidence record with:
+
+```yaml
+review_level: low | medium | xhigh
+findings:
+  - severity: blocker | high | medium | low | nit
+    verdict: CONFIRMED | PLAUSIBLE
+    outcome: fixed | no_change_needed | skipped
+```
+
+The canonical contract owns the immutable range, worktree boundary, proposal identity, changed paths, exact tests and outcomes, mutation boundary, and downstream selection.

package/.agents/skills/e-code-review/reference/runner-selection.md

@@ -35,6 +35,7 @@ Open issue for implementation work should link this file and keep PRs small
 ## Related always-on docs
 
 - Skill hub: `../SKILL.md` (levels, fix, loop — not runner internals).
+- Preflight proposal: `preflight-proposal.md` (immutable range, local runner, proposal evidence).
 - Medium procedure: `medium.md`.
 - Shared worker spawn (when applicable):
   `packages/claude-dev-env/_shared/pr-loop/worker-spawn.md` in the package tree.

package/.agents/skills/pr-cleanup/SKILL.md

@@ -1,99 +1,129 @@
 ---
 name: pr-cleanup
 description: >-
-  Clean a PR end-to-end with one coding agent: shared-extraction-audit,
-  name-by-capability-audit, sr-loop, then small-cl — apply and validate fixes
-  as they return. Use when the user asks for /pr-cleanup or full PR cleanup
-  (place, name, converge, then shrink).
+  Refine pull requests through parallel placement and capability-name audits,
+  focused delivery sizing, and a final simplify and code-review loop. Triggers:
+  /pr-cleanup, run PR cleanup, full PR cleanup, extraction audit, capability
+  naming audit, simplify and review a PR, and split a cleaned PR.
 ---
 
 # PR cleanup
 
-One coding agent cleans a pull request end-to-end: put code in the right place,
-name it for what it does, run the converging cleanup loop, then shrink the
-change into a reviewable size.
+## Contents
 
-This skill is host-neutral. Any coding agent that can edit the PR head, run
-scoped tests, and invoke the composed skills may run it.
+- [Principle](#principle)
+- [When this applies](#when-this-applies)
+- [Composition](#composition)
+- [Task seeding](#task-seeding)
+- [Process](#process)
+- [Promotion gates](#promotion-gates)
+- [Finish report](#finish-report)
+- [File index](#file-index)
 
-## When to use
+## Principle
 
-- `/pr-cleanup <PR>` or “run pr-cleanup on this PR”
-- A PR needs extraction + naming + sr-loop + a smaller reviewable slice in one pass
+One coding agent owns the cleanup outcome. `pr-refinement` coordinates parallel
+preflight audits and produces findings, tested proposals, a combined change map,
+and a delivery decision for the cleanup owner. Parent-to-child promotion uses
+exact commit ancestry and fresh child-head checks.
 
-## Inputs
+## When this applies
 
-- Target: PR URL, number, or branch (required). Missing → ask:
-  `Give a GitHub PR number or URL for pr-cleanup.`
-- Repo: take from the PR URL when given; otherwise the user’s default monitored repo
+Use this skill for a pull request that needs placement review, capability
+naming, cleanup convergence, and a focused delivery boundary.
 
-## Composition (run in this order)
+Required input: a pull request URL, number, or branch. If the target is missing,
+respond exactly: `Give a GitHub PR number, URL, or branch for pr-cleanup.`
 
-| Step | Skill | Role |
-|------|--------|------|
-| 1 | `shared-extraction-audit` | Wrong *place* (workflow package vs shared library) |
-| 2 | `name-by-capability-audit` | Wrong *name* (driver word on reusable capability) |
-| 3 | `sr-loop` / `e-simplify` then `e-code-review` | Converging simplify + high-effort review with `--fix` |
-| 4 | `small-cl` | Split / shrink into a focused reviewable PR |
+Use the repository that owns the target pull request. Keep every pull request in
+draft state until its applicable Ready gate is complete. Keep merge authority
+with the user.
 
-All four run under **one coding agent session** on the same worktree / PR head.
-For sr-loop advisor consults, bind `team-advisor` as a second session at equal
-tier when the host supports it (see `team-advisor` and the advisor docs).
+## Composition
 
-## Fix-as-you-go (required)
+| Skill | Role | Evidence |
+|---|---|---|
+| `pr-refinement` | Run the parallel audits, combine findings, and coordinate implementation shape | Change map and delivery decision |
+| `pr-shared-extraction` | Find reusable behavior that belongs in `shared_utils` | Placement findings and tested proposal |
+| `pr-name-by-capability` | Find driver or motive words on reusable capability surfaces | Naming findings and rename directions |
+| `pr-small-cl` | Choose one coherent pull request or an ordered replacement stack | Focused boundary and dependencies |
+| `source-command-sr-loop` | Run `e-simplify`, then `e-code-review low --fix` until clean | Review passes, fixes, and validation |
 
-Some of these skills can report without changing code. For **pr-cleanup**, that
-is not enough:
+## Task seeding
 
-1. **Stream findings** — as each audit/loop returns an item (offense, rename,
-   simplify fix, review finding), treat it as work to do now, not a backlog.
-2. **Apply the fix** on the PR head (or the first small-cl increment if already
-   splitting) before moving on to the next item when practical.
-3. **Validate** after each applied fix: scoped tests beside touched files (or
-   `py_compile` / package tests when there is no adjacent suite). No test theater.
-4. **Commit + push** after each validated changing pass (one concern per commit
-   when possible; keep the PR draft).
-5. **Do not** finish with an audit-only report while known P0/P1 fixes sit
-   unapplied — either fix them or hard-block with why.
-
-If the user says **audit-only**, stop after reports and skip apply / small-cl.
+At skill start, register every item in `reference/task-seeds.md` as a session
+task through `TaskCreate`, `TodoWrite`, or the host task equivalent. Work from
+that task list. Mark each task complete with `PASS`, `FAIL` plus file and line
+evidence, or `N/A` plus the reason.
 
 ## Process
 
-1. Resolve PR → convert to draft if needed; clean worktree of the PR head;
-   never mark ready for review.
-2. Run the four composed skills in order on that head:
-   - `shared-extraction-audit` in the **implement** band (not audit-only)
-   - `name-by-capability-audit`; apply clear rename directions (or ones the user
-     already approved), noting rename direction in the commit message
-   - `sr-loop`: Phase A `e-simplify`, Phase B `e-code-review` at **xhigh** with
-     `--fix` (not the default low); consult `team-advisor` before the first
-     write and after writes + validation
-   - Apply fixes as each pass returns findings; validate → commit → push
-3. After the loop converges (or nits-only stop): run **small-cl** — identify the
-   first coherent reviewable increment; if the PR is still too wide, split or
-   retitle/scope per small-cl (do not invent extra PRs unless the user asked).
-4. Return the finish report below. Merge-ready email / chat delivery is owned by
-   the caller (for example a PR monitor host), not this skill.
-
-## Hard rules
-
-- No test theater.
-- Real spawn/behavior validation when the PR claims an external binary path.
-- Prefer cleanup; functional only for correctness. Label each commit
-  `cleanup` vs `functional`.
-- Keep the PR draft. Never mark ready for review during this skill.
-- Extraction before rename when both apply to the same symbol (move, then name
-  the new home).
-- small-cl last — shrink only after place / name / cleanup are settled enough
-  that the slice is honest.
+### 1. Resolve the target
+
+Resolve the pull request, repository, parent head SHA, and intended child
+boundary. Record the immutable parent preflight SHA before creating worktrees.
+
+### 2. Run `pr-refinement`
+
+Run [pr-refinement](../pr-refinement/SKILL.md). Record its combined change map,
+audit findings, locations, priorities, destinations or rename directions,
+validation evidence, and worker worktrees.
+
+### 3. Choose the delivery shape
+
+Use [pr-small-cl](../pr-small-cl/SKILL.md) after the audit findings are
+combined. Record the first pull request boundary, dependencies, tests, and
+follow-up work.
+
+### 4. Implement the selected shape
+
+Apply every actionable finding in dependency order. Keep preflight parent scope
+read-only until the cleanup owner selects and reapplies tested proposals.
+Validate each changed surface with its production-path tests. Commit each
+validated concern and keep the resulting pull request in draft state.
+
+### 5. Run `source-command-sr-loop`
+
+Run [source-command-sr-loop](../source-command-sr-loop/SKILL.md). Record the
+review passes, fixes, skips, tests, and commit SHAs.
+
+### 6. Promote and report
+
+After the applicable gate passes, complete the [Finish report](#finish-report).
+
+## Promotion gates
+
+Run preflight work in isolated worktrees from the recorded parent SHA. Apply
+selected changes in the parent cleanup worktree after the owner selects the
+tested proposals.
+
+Promote the parent only after every actionable finding has an applied fix or an
+exact disposition. Record the remote parent Ready state and exact
+`parent_ready_sha`.
+
+Create the child from its intended pre-parent base and merge the exact
+`parent_ready_sha`. Prove that SHA is an ancestor of the child head with
+`git merge-base --is-ancestor <parent_ready_sha> <child_head>` and record exit
+code `0`.
+
+Reapply every relevant fix to the child. Rerun child tests, `e-simplify`, and
+`e-code-review` after the merge. Record the new child head and every validation
+result before promoting the child to Ready.
+
+Use `reference/task-seeds.md` and `reference/process-inventory.md` to record promotion evidence.
 
 ## Finish report
 
-- PR / repo / starting_sha / ending_sha
-- Per step: extraction findings applied, naming violations applied, sr-loop
-  passes + commits, small-cl outcome (kept / split plan)
-- `commits_pushed` with cleanup|functional labels
-- `validation_ran` + outcomes
-- `hard_block` or null
-- `draft_still: true`
+- Pull request or stack URLs.
+- `pr-refinement` outcome.
+- `source-command-sr-loop` passes, commits, and validation results.
+- Parent-ready and child-ready SHAs when a child is promoted.
+- Remaining hard block, or `null`.
+
+## File index
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Hub for refinement, cleanup convergence, promotion gates, and reporting |
+| `reference/task-seeds.md` | Ordered session tasks for audits, delivery, validation, and promotion |
+| `reference/process-inventory.md` | Process classes, evidence homes, and paired task checks |

package/.agents/skills/pr-cleanup/reference/process-inventory.md

@@ -0,0 +1,15 @@
+# PR cleanup process inventory
+
+| Step | Class | Home | Evidence | Paired test |
+|---|---|---|---|---|
+| Resolve PR and immutable parent SHA | deterministic | `task-seed:reference/task-seeds.md` | Target record and parent SHA | task-tool |
+| Create isolated preflight worktrees | deterministic | `task-seed:reference/task-seeds.md` | Worktree paths and base SHA | task-tool |
+| Run parallel preflight streams | borderline | `SKILL.md` and `task-seed:reference/task-seeds.md` | Stream reports and worker availability | task-tool |
+| Apply or disposition findings | judgment | `SKILL.md` and `task-seed:reference/task-seeds.md` | Changed diff or exact disposition | task-tool |
+| Validate parent head | deterministic | `task-seed:reference/task-seeds.md` | Scoped test and confirmation results | task-tool |
+| Promote parent and record exact Ready SHA | deterministic | `task-seed:reference/task-seeds.md` | Remote parent Ready state and SHA | task-tool |
+| Merge exact parent SHA into child | deterministic | `task-seed:reference/task-seeds.md` | Child merge commit and parent SHA | task-tool |
+| Prove parent SHA ancestry | deterministic | `task-seed:reference/task-seeds.md` | `git merge-base --is-ancestor` exit code `0` | task-tool |
+| Reapply relevant fixes to child | judgment | `SKILL.md` and `task-seed:reference/task-seeds.md` | Child diff and reapplication record | task-tool |
+| Validate child and rerun confirmations | deterministic | `task-seed:reference/task-seeds.md` | New child-head tests, simplify, and review results | task-tool |
+| Promote child and report | deterministic | `task-seed:reference/task-seeds.md` | Child Ready state and finish report | task-tool |

package/.agents/skills/pr-cleanup/reference/task-seeds.md

@@ -0,0 +1,20 @@
+# PR cleanup task seeds
+
+Register each numbered item as one session task before work starts. Complete
+each task with evidence from the stated gate.
+
+1. Resolve the target PR, repository, parent head SHA, and child boundary.
+2. Create isolated preflight worktrees from the immutable parent preflight SHA.
+3. Run the shared-extraction, capability-name, `e-simplify`, and `e-code-review` preflight streams in parallel when available.
+4. Record each stream's worktree, base SHA, findings, proposed patch, and validation evidence.
+5. Keep parent merge, rebase, push, and Ready operations unavailable during preflight.
+6. Select, apply, validate, or exactly disposition every actionable preflight finding in the one-agent parent cleanup worktree.
+7. Run parent scoped tests and cleanup/review confirmation checks.
+8. Promote the parent to Ready and record the exact remote `parent_ready_sha`.
+9. Create the child from its intended pre-parent base and merge the exact `parent_ready_sha`.
+10. Prove `parent_ready_sha` is an ancestor of the child head and record the exit code.
+11. Reapply every relevant preflight fix to the child.
+12. Run child scoped tests on the new child head.
+13. Rerun `e-simplify` and `e-code-review` on the new child head.
+14. Promote the child to Ready after all child evidence passes.
+15. Write the finish report with SHAs, evidence, states, and hard blocks.