claude-dev-env 2.18.0 → 2.19.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,89 @@
+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 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/)
+}
+
+test('audit modes retain their normal routing behavior', () => {
+  assertTaskRoutingAndNormalMode()
+})
+
+test('one shared contract defines proposal evidence for both audit skills', () => {
+  for (const eachSkillContract of allSkillContracts) {
+    assertProposalAdapter(eachSkillContract)
+  }
+  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/pr-cleanup/SKILL.md

@@ -1,99 +1,31 @@
 ---
 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).
+description: Refine a pull request, then run the final simplify and code-review loop. Use when the user asks for /pr-cleanup or full PR cleanup.
 ---
 
-# PR cleanup
+# 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.
+Run `pr-refinement`, then run `sr-loop` on its resulting pull request or stack.
 
-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.
+## Workflow
 
-## When to use
+1. Resolve the target pull request and use its head worktree.
+2. Run `pr-refinement`. It owns extraction, capability naming, in-place updates, and a required replacement stack.
+3. Run `sr-loop` on every resulting pull request. Apply findings, run scoped tests, commit, and push each validated change.
+4. Keep every pull request draft. Keep merge authority with the user.
 
-- `/pr-cleanup <PR>` or “run pr-cleanup on this PR”
-- A PR needs extraction + naming + sr-loop + a smaller reviewable slice in one pass
+## Promotion gates
 
-## Inputs
+Run preflight work in isolated worktrees from the recorded parent SHA. Apply selected changes in the parent worktree.
 
-- 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
+Before promoting a child, merge the exact parent-ready SHA. Prove that SHA is an ancestor of the child head. Rerun the child tests, `e-simplify`, and `e-code-review` after the merge.
 
-## Composition (run in this order)
-
-| 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 |
-
-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).
-
-## Fix-as-you-go (required)
-
-Some of these skills can report without changing code. For **pr-cleanup**, that
-is not enough:
-
-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.
-
-## 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.
+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.
+- `sr-loop` passes, commits, and validation results.
+- Parent-ready and child-ready SHAs when a child is promoted.
+- Remaining hard block, or `null`.

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.

package/.agents/skills/{name-by-capability-audit → pr-name-by-capability}/SKILL.md

@@ -1,17 +1,26 @@
 ---
-name: name-by-capability-audit
+name: pr-name-by-capability
 description: >-
   Audit a GitHub PR for name-by-capability violations: driver/motive words on
   reusable capability modules (queues and report routers may keep the driver
   word), then apply capability-oriented renames by default. Triggers:
-  /name-by-capability-audit, name-by-capability audit, audit PR for naming, name
+  /pr-name-by-capability, name-by-capability audit, audit PR for naming, name
   by capability, capability naming review, cert_fix rename check, driver word in
   package name.
 ---
 
 # Name-by-Capability Audit
 
-Audit a GitHub PR against the **name-by-capability** rule. Inspect paths and title wording for driver/motive words on reusable capability code, report findings with a rename direction, and apply the suggested renames by default. An explicit audit-only request ends after the report.
+Audit a GitHub PR against the **name-by-capability** rule. Inspect paths and title wording for driver or motive words on reusable capability code, and report violations with capability-oriented rename directions.
+
+## Mode routing
+
+First-match routing selects the mode before the audit steps:
+
+1. `preflight-proposal` runs `pr-name-by-capability preflight-proposal <pr_number> --base-sha <base_sha> --head-sha <head_sha> --worktree <isolated_worktree>` under the [shared preflight proposal contract](../_shared/pr-loop/preflight-proposal.md). Record each finding with violation or OK-driver classification.
+2. `audit-only` is report-only and ends after the findings report.
+3. A user-supplied rename or fix direction follows the existing normal fix workflow.
+4. Normal mode applies the suggested rename direction by default.
 
 ## Gotchas
 
@@ -21,15 +30,10 @@ Audit a GitHub PR against the **name-by-capability** rule. Inspect paths and tit
 
 ## When this applies
 
-- User invokes `/name-by-capability-audit <PR>` or asks to audit a PR for name-by-capability / capability naming.
+- User invokes `/pr-name-by-capability <PR>` or asks to audit a PR for name-by-capability / capability naming.
 - PR adds or renames packages/modules, or frames a general shared operation with a driver/motive word (`cert_fix`, `cert_closeout`, `portal`, `export`, …).
 
-**First match wins:**
-
-- Missing PR number or URL → respond exactly: `Give a GitHub PR number or URL to audit for name-by-capability.`
-- User requests audit-only → finish the audit report and stop.
-- User gives a rename or fix direction → finish the audit report, then apply the direction they gave.
-- A violation with no user-supplied direction → finish the audit report, then apply the suggested rename direction by default.
+A missing PR number or URL returns exactly: `Give a GitHub PR number or URL to audit for name-by-capability.` Resolved targets follow **Mode routing**.
 
 ## Constraints
 
@@ -39,7 +43,7 @@ Audit a GitHub PR against the **name-by-capability** rule. Inspect paths and tit
 
 ## Process
 
-Register every bullet from `reference/task-seeds.md` on the host task tool (`TodoWrite` / `TaskCreate`). Mark each complete with evidence. Follow those seeds in order — do not restate them here.
+Register every bullet from `reference/task-seeds.md` with `update_plan`. Mark each complete with evidence. Follow those seeds in order — do not restate them here.
 
 Load order for the rule: if `docs/agents/name-by-capability.md` exists, read it first; always keep `reference/rule-checklist.md` as the fallback when the doc is missing. On disagreement after the docs PR merges, prefer the repo doc and update the skill checklist in a follow-up.
 
@@ -47,7 +51,7 @@ Load order for the rule: if `docs/agents/name-by-capability.md` exists, read it
 
 | Peer | Relationship |
 |------|----------------|
-| `shared-extraction-audit` | Layering and extraction (where code lives). Invoke when a path’s *role* is unclear; this skill only scores the *name*. |
+| `pr-shared-extraction` | Layering and extraction (where code lives). Invoke when a path’s *role* is unclear; this skill only scores the *name*. |
 | `reviews` / PR review skills | May invoke this skill by name when naming is in scope |
 
 ## File index
@@ -60,6 +64,8 @@ Load order for the rule: if `docs/agents/name-by-capability.md` exists, read it
 | `reference/fetch-commands.md` | Minimal `gh` fetch for PR naming surface |
 | `reference/report-template.md` | Compact report shape |
 | `reference/task-seeds.md` | Ordered task seeds for the audit run |
+| `../_shared/pr-loop/preflight-proposal.md` | Shared isolated proposal mode and evidence record |
+| `../_shared/pr-loop/preflight-proposal.contract.test.mjs` | Cross-skill mode and contract test |
 
 ## Folder map
 

package/.agents/skills/{name-by-capability-audit → pr-name-by-capability}/reference/offense-examples.md

@@ -1,6 +1,6 @@
 # Offense examples (this repo)
 
-Classify by **role** — the reusable work the surface performs — not by matching a string list. For whether code belongs in `shared_utils` vs a workflow package, invoke `shared-extraction-audit`; this map only scores names.
+Classify by **role** — the reusable work the surface performs — not by matching a string list. For whether code belongs in `shared_utils` vs a workflow package, invoke `pr-shared-extraction`; this map only scores names.
 
 ## Quick classifier
 

package/.agents/skills/{name-by-capability-audit → pr-name-by-capability}/reference/task-seeds.md

@@ -1,9 +1,10 @@
 # Task seeds
 
-Register each item on `TodoWrite` / `TaskCreate` at audit start. Complete with evidence.
+Register each item with `update_plan` at audit start. Complete with evidence.
 
 1. Load the rule: `docs/agents/name-by-capability.md` when present, else `reference/rule-checklist.md` (always keep the skill checklist as fallback).
 2. Fetch PR title, body, and changed/renamed paths via `reference/fetch-commands.md`.
 3. Classify each naming signal as violation, OK driver, or skip (`reference/offense-examples.md` classifier first).
 4. Emit report from `reference/report-template.md`.
-5. Apply the requested or suggested rename direction by default; an explicit audit-only request ends after the report.
+5. After the report, continue with `SKILL.md` **Mode routing**.
+6. For `preflight-proposal`, complete the shared contract referenced by `SKILL.md` **Mode routing**.

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

@@ -0,0 +1,31 @@
+---
+name: pr-refinement
+description: Coordinate shared-extraction and capability-naming audits, then update an existing pull request or publish a required focused GitHub pull-request stack. Use when a user asks to turn a PR architecture audit into extracted shared code and small pull requests.
+---
+
+# PR Refinement
+
+Turn audit findings into a focused existing pull-request update or a required dependency-ordered GitHub pull-request stack.
+
+## Peer skills
+
+1. Run `pr-shared-extraction` for reusable-code placement, canonical shared homes, and extraction findings.
+2. Run `pr-name-by-capability` for module, symbol, path, branch, and pull-request naming findings.
+3. Use `pr-small-cl` to divide approved fixes into coherent, independently reviewable pull requests.
+
+The peer skills own their audit rules and finding priorities.
+
+## Workflow
+
+1. Run both audits in parallel against the same pull request. Keep their findings, locations, priorities, destinations, API directions, and naming directions.
+2. Build one change map. Group findings by shared capability and dependency.
+3. Use `pr-small-cl` to choose the delivery shape. Update the existing pull request when it remains one coherent, reviewable outcome.
+4. Create a replacement pull-request stack when the focused-change review identifies independent increments. Give each pull request one coherent outcome, related tests, a clear verification boundary, and a capability-oriented branch and title. Close the original pull request as superseded and link the replacement stack.
+5. Implement the existing pull request or the replacement stack in dependency order. Earlier pull requests create stable shared foundations. Later pull requests migrate consumers and remove replaced code.
+6. Run scoped production-path tests for each pull request. Record commands and results.
+7. Commit and push each branch. Update the existing pull request, or open draft replacement pull requests in stack order and set every child pull request base to its parent.
+8. Include scope, verification, risks, and stack dependencies in every pull-request body.
+
+## Completion
+
+Deliver a focused, tested, pushed existing pull request, or a replacement stack with explicit parent-child links. Keep merge authority with the user.

package/.agents/skills/{shared-extraction-audit → pr-shared-extraction}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: shared-extraction-audit
+name: pr-shared-extraction
 description: Audits pull requests and packages for general helpers living in workflow-specific code instead of shared_utils, then applies extraction fixes by default in small tested CLs. Use when reviewing PRs for architectural layering, migrating utilities out of cert_fix_queue/theme_dialer_pipeline/skills, auditing "similar offenses", or when the user mentions extraction audit, shared_utils migration, orchestration-only packages, thin wrappers, or layer inversions.
 ---
 
 # Shared Extraction Audit
 
-Audit PRs and packages, report findings, and apply extraction fixes by default to keep **orchestration packages thin** and **shared_utils canonical**.
+Audit PRs and packages for reusable behavior placed in workflow code. Keep **orchestration packages thin** and **shared_utils canonical**.
 
 ## When to use
 
@@ -13,6 +13,14 @@ Audit PRs and packages, report findings, and apply extraction fixes by default t
 - A package grew `fix_one`, `_default_*`, backup upload, rembg session, or residual gates alongside orchestration
 - Before merge: confirm consumers are adapters, not second implementations
 
+## Mode routing
+
+Resolve the first matching mode before the audit steps:
+
+1. `preflight-proposal` runs `pr-shared-extraction preflight-proposal <pr_number> --base-sha <base_sha> --head-sha <head_sha> --worktree <isolated_worktree>` under the [shared preflight proposal contract](../_shared/pr-loop/preflight-proposal.md). Record each finding with priority and target.
+2. `audit-only` is report-only and ends after the findings report.
+3. Normal mode follows the existing audit workflow and applies the prioritized fix band by default.
+
 ## Target architecture
 
 | Layer | Holds | Examples |
@@ -25,7 +33,7 @@ Audit PRs and packages, report findings, and apply extraction fixes by default t
 
 ## Audit workflow
 
-Copy to TodoWrite:
+Register this checklist with `update_plan` and mark each step complete with evidence:
 
 ```
 Shared extraction audit:
@@ -33,9 +41,10 @@ Shared extraction audit:
 - [ ] 2. Map canonical homes already in shared_utils
 - [ ] 3. Grep for offense patterns (see reference/offense-taxonomy.md)
 - [ ] 4. Write prioritized findings (P0–P3)
-- [ ] 5. Apply the prioritized fix band by default; an explicit audit-only request ends after the report
+- [ ] 5. Apply **Mode routing** after the report
 - [ ] 6. Extract in small CLs (~100 lines) + move/adjust tests
-- [ ] 7. Run scoped pytest, commit, push, update PR
+- [ ] 7. Run scoped pytest, then follow the selected mode's mutation boundary
+- [ ] 8. When the mode is `preflight-proposal`, record proposal evidence from the [shared preflight proposal contract](../_shared/pr-loop/preflight-proposal.md) and require downstream owner selection before reapplication
 ```
 
 ### Step 1 — Scope
@@ -97,8 +106,6 @@ Use [reference/offense-taxonomy.md](reference/offense-taxonomy.md). Assign prior
 1. …
 ```
 
-Apply the prioritized fixes after the report by default. An explicit audit-only request ends after the report.
-
 ## Fix workflow
 
 ### Extraction rules
@@ -158,3 +165,13 @@ Provide evidence: pytest output counts, not "should work".
 ## Examples
 
 See [reference/examples.md](reference/examples.md) for cert_fix_queue (#1965) and background_removal (#1954) audits.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Hub — architecture, routing, audit checklist, and fix workflow |
+| `reference/offense-taxonomy.md` | Offense signals and priority guide |
+| `reference/examples.md` | Audit examples and fix order |
+| `../_shared/pr-loop/preflight-proposal.md` | Shared isolated proposal mode and evidence record |
+| `../_shared/pr-loop/preflight-proposal.contract.test.mjs` | Cross-skill mode and contract test |

package/.agents/skills/{small-cl → pr-small-cl}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: small-cl
+name: pr-small-cl
 description: >-
   Scope or split a pull request into a self-contained reviewable increment. Use
   when a user asks to "split this PR", "make this change smaller", or "small CL".

package/.agents/skills/prototype/scripts/test_probe_sandbox_safety.py

@@ -33,6 +33,7 @@ from prototype_scripts_constants.config.probe_sandbox_safety_constants import (
 )
 
 SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+BUILDER_PATH = SCRIPTS_DIRECTORY / "build_sandbox_settings.py"
 PROBE_PATH = SCRIPTS_DIRECTORY / "probe_sandbox_safety.py"
 HOOKS_BLOCKING_DIRECTORY = SCRIPTS_DIRECTORY.parents[3] / "hooks" / "blocking"
 
@@ -52,13 +53,21 @@ ASK_HOOK_SOURCE = (
 ALLOW_HOOK_SOURCE = "import sys\nsys.exit(0)\n"
 
 
-def load_probe_module() -> ModuleType:
-    spec = importlib.util.spec_from_file_location("probe_sandbox_safety", PROBE_PATH)
+def load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
     assert spec is not None
     assert spec.loader is not None
-    probe_module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(probe_module)
-    return probe_module
+    loaded_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+def load_probe_module() -> ModuleType:
+    return load_module_from_path("probe_sandbox_safety", PROBE_PATH)
+
+
+def load_builder_module() -> ModuleType:
+    return load_module_from_path("build_sandbox_settings", BUILDER_PATH)
 
 
 def quoted_command(script_path: Path) -> str:
@@ -123,6 +132,25 @@ def test_main_exits_zero_when_the_real_destructive_hook_denies_in_deny_mode(
     assert exit_code == PROBE_SUCCESS_EXIT_CODE
 
 
+def test_built_deny_environment_denies_real_destructive_hook() -> None:
+    builder_module = load_builder_module()
+    settings_document = builder_module.build_minimal_settings(
+        builder_module.resolve_safety_hook_entries(real_hook_settings_document())
+    )
+    probe_module = load_probe_module()
+    probe_payload = probe_module.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    destructive_hook_tokens = probe_module.parse_command_argv(
+        quoted_command(destructive_hook_path)
+    )
+    is_hook_blocking = probe_module.hook_blocks_probe(
+        destructive_hook_tokens,
+        probe_payload,
+        settings_document["env"],
+    )
+    assert is_hook_blocking is True
+
+
 def test_pii_basename_probe_payload_carries_the_secret() -> None:
     probe = load_probe_module()
     probe_payload = probe.build_probe_payload_for_basename(PII_HOOK_BASENAME)

package/.agents/skills/skill-builder/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: skill-builder
+disable-model-invocation: true
 description: >-
   Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose
   sub-skills, polish description triggers, enforce deterministic scripts. Triggers:

package/.agents/skills-archived/bugteam/SKILL.md

@@ -35,7 +35,7 @@ Use the [review guide](../reviews/SKILL.md#review-workflow) to decide whether a
 changed behavior is a finding. Use the [comment guide](../comments/SKILL.md#writing-useful-review-comments)
 for posted findings and replies, the [description guide](../descriptions/SKILL.md#reviewing-a-description)
 for final PR context, the [emergency guide](../emergencies/SKILL.md#while-the-incident-is-active)
-for active incidents, and the [small-change guide](../small-cl/SKILL.md#reviewable-scope)
+for active incidents, and the [small-change guide](../../skills/pr-small-cl/SKILL.md#reviewable-scope)
 when the diff needs a narrower review boundary.
 
 ## Pre-flight

package/.agents/skills-archived/bugteam/test_skill_additions.py

@@ -26,4 +26,4 @@ def test_skill_routes_judgment_to_canonical_guides() -> None:
     assert "../comments/SKILL.md#writing-useful-review-comments" in skill_text
     assert "../descriptions/SKILL.md#reviewing-a-description" in skill_text
     assert "../emergencies/SKILL.md#while-the-incident-is-active" in skill_text
-    assert "../small-cl/SKILL.md#reviewable-scope" in skill_text
+    assert "../../skills/pr-small-cl/SKILL.md#reviewable-scope" in skill_text

package/.agents/skills-archived/comments/SKILL.md

@@ -59,7 +59,7 @@ needed. Record the resulting decision in the pull request thread.
 
 - Use [reviews](../reviews/SKILL.md#review-workflow) for substantive code
   assessment.
-- Use [small-cl](../small-cl/SKILL.md#responding-to-review) for author-side
+- Use [pr-small-cl](../../skills/pr-small-cl/SKILL.md#responding-to-review) for author-side
   review responses and focused follow-up work.
 - Use [emergencies](../emergencies/SKILL.md#while-the-incident-is-active) for
   urgent production-change communication.

package/.agents/skills-archived/descriptions/SKILL.md

@@ -47,5 +47,5 @@ summary, scope, verification, and risk information aligned with the pull
 request's current contents.
 
 Use [reviews](../reviews/SKILL.md#review-workflow) for substantive code
-assessment and [small-cl](../small-cl/SKILL.md#what-a-focused-pull-request-contains)
+assessment and [pr-small-cl](../../skills/pr-small-cl/SKILL.md#what-a-focused-pull-request-contains)
 to establish a focused scope.

package/.agents/skills-archived/reviews/SKILL.md

@@ -81,5 +81,5 @@ the pull request record.
   or assess pull request context.
 - Use [emergencies](../emergencies/SKILL.md#emergency-classification) to classify
   an urgent production change.
-- Use [small-cl](../small-cl/SKILL.md#when-to-use-this-guide) to focus or split
+- Use [pr-small-cl](../../skills/pr-small-cl/SKILL.md#when-to-use-this-guide) to focus or split
   a change that exceeds a clear review boundary.

package/AGENTS.md

@@ -76,7 +76,7 @@ Use full capability names for files, modules, functions, variables, branches, an
 
   When planning work or opening a pull request, size the change first: one self-contained change, around 100 lines, with its tests. Read the small-changelists guide for the numbers, the allowed exceptions, and how to split.
 
-Use `~/.claude/skills/small-cl/SKILL.md` for change-size guidance and review-sized boundaries.
+Use `~/.claude/skills/pr-small-cl/SKILL.md` for change-size guidance and review-sized boundaries.
 
 ## Execution and delegation