claude-dev-env 4.2.0 → 7.0.0

package/.agents/agents/pr-description-writer.md

@@ -6,7 +6,7 @@ tools: Read,Grep,Glob,Bash
 
 # PR Description Writer
 
-Write from the current pull request diff and task. Resolve the active managed root and active agents home before reading guides: `~/.claude` is the default root, `CLAUDE_CONFIG_DIR` selects another root, and `--target DIR` takes precedence; the default `.claude` root uses sibling `~/.agents`, while another root uses sibling `<root-name>.agents`. Use `<agents-home>/skills/pr-title-description/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-title-description/SKILL.md`) for required content and shape. Use the current review findings and task guidance for a review comment. Do not assume `~/.claude` or `~/.agents` for a named profile or explicit target.
+Write from the current pull request diff and task. Resolve the active managed root and active agents home before reading guides: `~/.claude` is the default root, `CLAUDE_CONFIG_DIR` selects another root, and `--target DIR` takes precedence; the default `.claude` root uses sibling `~/.agents`, while another root uses sibling `<root-name>.agents`. Use this agent's full-diff behavior standard and drafting steps. Use the current review findings and task guidance for a review comment. Do not assume `~/.claude` or `~/.agents` for a named profile or explicit target.
 
 ## Voice
 
@@ -24,7 +24,7 @@ Before drafting, inventory every independently observable behavior in the full d
 
 For each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.
 
-For a concrete voice sample only when needed, read `reference/pr-description-illustrative-voice.md` beside this agent. For a concrete verification sample only when needed, read `reference/pr-description-verification.md`. These samples guide the shape and voice; they are not content to copy into unrelated pull requests.
+For a voice sample only when needed, read `<agents-home>/agents/reference/pr-description-illustrative-voice.md` (source fallback: `packages/claude-dev-env/.agents/agents/reference/pr-description-illustrative-voice.md`). For a verification sample only when needed, read `reference/pr-description-verification.md` beside this agent. These samples guide the shape and voice; they are not content to copy into unrelated pull requests.
 
 ## Draft the body
 

package/.agents/agents/test_agent_frontmatter.py

@@ -602,8 +602,8 @@ EXPECTED_SOURCE_LINK_PAIRS = {
     }),
     "pr-description-writer.md": frozenset({
         (
-            "<agents-home>/skills/pr-title-description/SKILL.md",
-            "packages/claude-dev-env/.agents/skills/pr-title-description/SKILL.md",
+            "<agents-home>/agents/reference/pr-description-illustrative-voice.md",
+            "packages/claude-dev-env/.agents/agents/reference/pr-description-illustrative-voice.md",
         ),
         (
             "<managed-root>/rules/gh-cli-conventions.md#body-content-goes-in-a-file",

package/.agents/agents/test_pr_description_writer_style.py

@@ -17,6 +17,7 @@ def test_pr_description_writer_uses_repo_owned_progressive_samples() -> None:
     assert "only when needed" in agent_text
     assert "PR #2562" not in agent_text
     assert "PR #1150" not in agent_text
+    assert "skills/pr-title-description" not in agent_text
 
 
 def test_voice_reference_keeps_the_plain_illustrative_shape() -> None:
@@ -48,9 +49,6 @@ def test_verification_leads_with_a_human_visible_check() -> None:
 
 def test_full_diff_behavior_standard_is_explicit_in_writer_sources() -> None:
     all_writer_source_texts = [
-        (AGENT_DIRECTORY.parent / "skills" / "pr-title-description" / "SKILL.md").read_text(
-            encoding="utf-8"
-        ),
         AGENT_PATH.read_text(encoding="utf-8"),
         VOICE_REFERENCE_PATH.read_text(encoding="utf-8"),
     ]

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

@@ -16,10 +16,10 @@ description: >-
 
 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.
+1. `preflight-proposal` requires `<pr_number>`, `--level <low|medium|xhigh>`, `--base-sha <immutable SHA>`, `--head-sha <immutable SHA>`, and `--worktree <isolated path>`. Default level is `low`. Follow [reference/preflight-proposal.md](reference/preflight-proposal.md). 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.
+Proposal mode selects the review level and records finding outcomes. The downstream owner records selected proposal IDs before reapplication. Each new finding gets a new ID.
 
 ## Gotchas
 
@@ -27,7 +27,7 @@ The proposal mode applies the canonical proposal contract at `@~/.claude/_shared
 - **Collection reports every real finding.** Keep every CONFIRMED or PLAUSIBLE finding at its assigned severity (`blocker`, `high`, `medium`, `low`, `nit`). Do not drop low or nit findings during collection. Severity or action filtering is a separate consumer stage after the collection record is complete (`scripts/finding_pipeline.py`).
 - **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) assign severity carefully so a later filter can pick maintainer-action findings. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
 - **Every retained finding carries `severity` and `verdict`.** Severity is one of `blocker`, `high`, `medium`, `low`, `nit`. Verdict is `CONFIRMED` or `PLAUSIBLE`. Drop REFUTED candidates only; never emit an unclassified retained finding.
-- **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the code-rules gate, skip logging, and outcome reporting. Commits are lead-owned; fix agents never commit or push.
+- **`--fix` applies findings once.** Load `reference/fix.md` and follow it. That file owns the fix agent, the code-rules gate, skip logging, and outcome reporting. Commits are lead-owned; fix agents never commit or push.
 - **`loop` never asks.** A round with bug findings validates them with an advisor, fixes, and re-reviews. Terminals are exactly `clean`, `nits_fixed`, and `advisor_blocked`. There is no reviewed-head count limit; a new head increments the count once, a re-review of the same head does not. Load `reference/loop.md` and follow it.
 - **`--fix` and `loop` combine.** With both, each loop round runs the level file, and the round's fixing happens inside `reference/loop.md`'s gate sequence, which loads `reference/fix.md` for the mechanics. There is no separate fix pass around the round.
 
@@ -35,13 +35,13 @@ The proposal mode applies the canonical proposal contract at `@~/.claude/_shared
 
 Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`, or `xhigh`. `--fix` and `loop` are each optional and may be used together.
 
-**Refusal — first match wins:**
+**Refusal. First match wins:**
 
 - **No level, or an unknown level.** Respond exactly: `Which effort level — low, medium, or xhigh?`
 
 ## Evaluation-backed defaults (e-code-review family)
 
-When the caller asks which level to pick for a known fixture band (easy / medium / demanding scope), use the committed OP-02B evaluation evidence — not an inherited hard-coded preference. Thinking stays on; **effort** is the only cost/latency lever.
+When the caller asks which level to pick for a known fixture band (easy / medium / demanding scope), use the committed OP-02B evaluation evidence. Thinking stays on; **effort** is the only cost/latency lever.
 
 | Fixture band | Skill effort | Source |
 |---|---|---|
@@ -58,7 +58,7 @@ Detail: `reference/effort-evaluation.md`.
 1. Read `<level>` and the optional `--fix` and `loop` flags. Apply the refusal first.
 2. Load `reference/low.md`, `reference/medium.md`, or `reference/xhigh.md`. Run that file as one review cycle, ending in its structured findings report.
 3. If `--fix` is set and `loop` is not set, load `reference/fix.md` and apply it to that cycle's findings. This path has no commit step: the fixes stay uncommitted in the working tree for the user to review and commit.
-4. If `loop` is set, load `reference/loop.md` and follow it with that cycle's findings still unfixed. Round 1's findings are the ones step 2 already produced; from the second round on, the round re-runs that same level file end to end. End to end means the level file's review phases, up to and including its findings report — not its *Looping* section, which hands control to `loop.md` and would re-enter the loop the round is already inside. `loop.md`'s gate sequence owns when the round fixes.
+4. If `loop` is set, load `reference/loop.md` and follow it with that cycle's findings still unfixed. Round 1's findings are the ones step 2 already produced; from the second round on, the round re-runs that same level file end to end. End to end means the level file's review phases, up to and including its findings report. Skip that file's *Looping* section, which hands control to `loop.md` and would re-enter the loop the round is already inside. `loop.md`'s gate sequence owns when the round fixes.
 5. Without `--fix` or `loop`, return the cycle findings and stop.
 
 ## File index
@@ -66,9 +66,9 @@ Detail: `reference/effort-evaluation.md`.
 | File | Purpose |
 |---|---|
 | `SKILL.md` | Route by level; dispatch `--fix` and `loop` |
-| `reference/low.md` | low review procedure — 1 diff pass per target item, no verify |
-| `reference/medium.md` | medium review procedure — 8 angles, 1-vote verify |
-| `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
+| `reference/low.md` | low review procedure: 1 diff pass per target item, no verify |
+| `reference/medium.md` | medium review procedure: 8 angles, 1-vote verify |
+| `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 |
@@ -85,6 +85,6 @@ Detail: `reference/effort-evaluation.md`.
 
 ## Folder map
 
-- `SKILL.md` — route and dispatch.
-- `reference/` — level procedures, fix/loop, effort evaluation, runner selection.
-- `scripts/` — collect-then-filter finding pipeline, effort evaluation, Grok medium-review module, tests, and `e_code_review_scripts_constants/`.
+- `SKILL.md`: route and dispatch.
+- `reference/`: level procedures, fix/loop, effort evaluation, runner selection.
+- `scripts/`: collect-then-filter finding pipeline, effort evaluation, Grok medium-review module, tests, and `e_code_review_scripts_constants/`.

package/.agents/skills/e-code-review/preflight-proposal.contract.test.mjs

@@ -0,0 +1,20 @@
+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 here = dirname(fileURLToPath(import.meta.url))
+const skill = readFileSync(resolve(here, 'SKILL.md'), 'utf8')
+const contract = readFileSync(resolve(here, 'reference/preflight-proposal.md'), 'utf8')
+
+test('e-code-review owns its preflight proposal contract', () => {
+  assert.match(skill, /reference\/preflight-proposal\.md/)
+  assert.doesNotMatch(skill, /_shared\/pr-loop/)
+  assert.match(contract, /caller-supplied isolated worktree/)
+  assert.match(contract, /exact `base_sha\.\.\.head_sha` range/)
+  assert.match(contract, /immutable proposal identity/)
+  assert.match(contract, /selected or dispositioned proposal collection/)
+  assert.match(contract, /review_level: low \| medium \| xhigh/)
+  assert.match(contract, /outcome: fixed \| no_change_needed \| skipped/)
+})

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

@@ -12,7 +12,7 @@ For each finding, resume the same Agent-tool agent instance that originally
 surfaced it. That agent applies all relevant fixes, which you provide guidance
 on in your resume prompt.
 
-At `low` — and any time the Agent tool is unavailable — no finder agent exists
+At `low`, and any time the Agent tool is unavailable, no finder agent exists
 to resume. Apply the fixes yourself, sequentially, in this context, holding to
 every rule below.
 
@@ -26,7 +26,7 @@ call every other surface in this skill uses:
 2. If the gate reports violations **on lines this fix already owns** (the files
    and added lines the fix changed), fix them and re-run the exact same command.
 3. A violation on a path or added line outside this fix's own work is reported
-   or skipped — it is not force-fixed into unrelated files. Log each skip with
+   or skipped. It is not force-fixed into unrelated files. Log each skip with
    the path and reason, then continue.
 4. Repeat until every violation on this fix's own work is clean (or skipped with
    a logged reason for out-of-scope hits).
@@ -39,15 +39,14 @@ This gate commits nothing. The fix lands in the working tree and stays
 uncommitted. **Commit ownership is lead-only:** a fix agent, patch worker, or
 resumed finding agent never runs `git commit` or `git push`. The lead that owns
 the branch creates the commit after gates pass. The bare code-rules call covers
-the merge-base surface and staged added lines only — working-tree-only lines
+the merge-base surface and staged added lines only. Working-tree-only lines
 enter that scope after the lead stages or commits them.
 
-Under a bare `--fix` — this document invoked without `loop` — nothing
-downstream commits either, and that is the intended outcome: a one-shot fix
-pass leaves its fixes uncommitted in the working tree for the lead to review
-and commit (stage first if you re-run the gate on those lines). Under `loop`,
-the round tail in `reference\loop.md` stages and runs required checks; the lead
-still owns the commit and push.
+Under a bare `--fix` (this document invoked without `loop`), nothing
+downstream commits either. A one-shot fix pass leaves its fixes uncommitted in
+the working tree for the lead to review and commit (stage first if you re-run
+the gate on those lines). Under `loop`, the round tail in `reference\loop.md`
+stages and runs required checks; the lead still owns the commit and push.
 
 ## Skip candidates
 
@@ -55,16 +54,15 @@ Skip a finding when fixing it would change intended behavior, require changes
 well outside the reviewed diff, or the finding itself is judged a false
 positive.
 
-Every logged skip surfaces exactly once, batched together, in a single 
-consolidated list presented to the user at the very end of the fix pass 
-— after every other finding has been fixed, marked not-needed, or skipped, 
-and never before.
+Every logged skip surfaces exactly once, batched together, in a single
+list presented to the user at the end of the fix pass, after every other
+finding has been fixed, marked not-needed, or skipped, and never before.
 
 ## Reporting outcomes
 
 After fixes land, report the same findings list again through the structured
-findings-report call — the mechanism that renders this review's results as a
-typed list in the host UI — with each finding now carrying an `outcome`:
+findings-report call, the call that renders this review's results as a typed
+list in the host UI, with each finding now carrying an `outcome`:
 `fixed`, `no_change_needed` (the finding was wrong or already handled), or
 `skipped` (real but not applied). Do not repeat the findings as text in the
 response body; the structured call is the record the host UI reads, and the
@@ -72,8 +70,8 @@ batched skip list from above goes in the prose that follows it.
 
 ## If findings are fixed later
 
-Whenever a reported finding is fixed later in the session — the user asks for
-the fix, or later work fixes it incidentally — call the structured
+Whenever a reported finding is fixed later in the session, because the user
+asks for 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

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

@@ -14,18 +14,14 @@ Report progress while you work. Stop for the user only on a terminal outcome bel
 
 ## Where fixes come from
 
-A round fixes whether or not `--fix` is set. Gate 2 below applies the round's
-fixes on every run, and its three cases read the same way with the flag and
-without it. What `--fix` adds is `fix.md`'s mechanics, not permission to fix:
-the flag decides where the mechanics come from, never whether a round fixes at
-all.
-
-When `--fix` is also set, the round's fixing happens inside the gate sequence
-below. Gate 2 is the only place a round applies a fix, and there is no separate
-fix pass sitting around the round. Gate 2 loads `reference\fix.md` (relative to
-this skill's folder) for the mechanics — which agent applies each fix, agent
-resume, the code-rules gate, skip logging, and outcome reporting — while the
-gate sequence decides whether a round fixes, commits, pushes, and re-reviews.
+A round always applies fixes. Gate 2 below is the only place a round applies a
+fix. `--fix` chooses the mechanics. With the flag, Gate 2 loads
+`reference\fix.md` (relative to this skill's folder) for which agent applies
+each fix, agent resume, the code-rules gate, skip logging, and outcome
+reporting. Without the flag, this session applies each fix itself.
+
+The gate sequence still decides whether a round fixes, commits, pushes, and
+re-reviews.
 
 ## Scope stays narrow
 
@@ -55,8 +51,8 @@ no advisor call reopens that.
 `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo root>`
 with no file paths and no `--only-under` prefix. On a violation on lines this
 round already owns, fix it and re-run the exact same command until clean. A
-violation outside the review target is reported or skipped — not force-fixed into
-unrelated files — and the skip is logged with path and reason.
+violation outside the review target is reported or skipped, not force-fixed into
+unrelated files, and the skip is logged with path and reason.
 
 That bare call gates the git diff since the merge-base (and any staged added
 lines the gate already includes). Working-tree lines that are neither staged
@@ -76,20 +72,20 @@ A repair diff is new code. From the second round on, the round runs the level
 file end to end at the new head. End to end means that file's review phases, up
 to and including its findings report; the round stops there and brings those
 findings back to the gate sequence below. It does not run the level file's
-*Looping* section — that section hands control to this document, and the round
+*Looping* section. That section hands control to this document, and the round
 is already inside it. The round's scope is the level's own review
-target — the diff or path the level gathers up front, called Phase 0 in
-`medium.md` and `xhigh.md` — taken against that target's base. A repair edit
+target, the diff or path the level gathers up front, called Phase 0 in
+`medium.md` and `xhigh.md`, taken against that target's base. A repair edit
 landing outside that target widens the next round's scope to cover it: the next
 round's review target is the original target **plus** that path, and the round
 reviews both. A later widening adds to that target the same way.
 
 The widened target is what the round hands the level file. When a round runs the
-level file end to end, it passes the current review target — the original target
-plus every path a widening has since added — as that run's target argument, in
+level file end to end, it passes the current review target (the original target
+plus every path a widening has since added) as that run's target argument, in
 place of the argument the first round was given. When the first round was given
-no target argument, the original target is the item `default-range` — the level
-file's own default gather — so the widened target is `default-range` plus every
+no target argument, the original target is the item `default-range`, the level
+file's own default gather, so the widened target is `default-range` plus every
 added path, and the range the first round reviewed stays in scope. The level
 file gathers what the round hands it, so a widened path is gathered and reviewed
 like any other part of the target.
@@ -134,11 +130,11 @@ A broken reader outside the review target does not block the loop and does not
 widen scope. Hand it off as a reported finding. Two separate things are owed for
 that hand-off, and they land at different times:
 
-- **The round-scoped record** — what a round produces. Check the reader, record
+- **The round-scoped record.** What a round produces. Check the reader, record
   its result, and name it in that round's progress report. All three are done
   inside the round that checks the reader, and nothing outside that round is
   needed to complete them. This is the record gate 2 reads.
-- **The termination-time disclosure** — what terminating requires. The
+- **The termination-time disclosure.** What terminating requires. The
   ready-for-review message names every broken off-target reader and every
   skipped finding that still exists, and the pull request body carries the same
   names when the target is a pull request. A target with no pull request owes
@@ -158,15 +154,15 @@ The loop emits exactly one of these terminals when it stops:
 Every round does this round's own work first, then runs the three gates below,
 in order: gate 1, then gate 2, then gate 3.
 
-**This round's work — before the gates.** Record this round's dangerous
+**This round's work, before the gates.** Record this round's dangerous
 classification and the dangerous-round count as `N of M`; and when a shape-change
 list is open, check each reader on that list and name each reader with its
 result, adding any on-target reader that reads the new shape wrong to this
 round's findings as *A shape change names its readers* directs. Then run the
 gates.
 
-**Gate 1 — obligations.** Gate 1 is evaluated first in the sequence, and its
-answer turns on the round's open obligations alone — the findings are in hand by
+**Gate 1, obligations.** Gate 1 is evaluated first in the sequence, and its
+answer turns on the round's open obligations alone. The findings are in hand by
 now, and no content they carry changes it. Ask only: does any obligation remain
 open? Two kinds exist.
 
@@ -175,17 +171,17 @@ open? Two kinds exist.
 
 Gate 1 states its answer and stops there: an obligation remains open, or none
 does. It states no re-entry, no continuation, and no routing. Gate 3 is the sole
-router — every path out of a round passes through it.
+router. Every path out of a round passes through it.
 
-**Gate 2 — findings.** When `--fix` is set, load `reference\fix.md` here and
-follow it for the mechanics of every fix this gate applies — the fix agent,
+**Gate 2, findings.** When `--fix` is set, load `reference\fix.md` here and
+follow it for the mechanics of every fix this gate applies: the fix agent,
 agent resume, the code-rules gate, skip logging, and outcome reporting. When `--fix` is
 absent, apply each fix in this session yourself, and log each skip in this
 round's progress report. Then take the one case that matches the round's
 findings.
 
 - Any bug-severity finding: validate each bug with an advisor before touching
-  code — confirm it's real and confirm the intended fix — then fix every
+  code. Confirm it's real and confirm the intended fix, then fix every
   validated bug and every nit on the review target. A refuted bug removes only
   itself from the round's work; the nits are fixed either way.
 - Nits only, with at least one nit present: fix all of them on the review
@@ -196,13 +192,13 @@ Gate 2 then ends by stating one of exactly two outcomes: unresolved findings
 remain, or none remain. A refuted bug is resolved. A fixed nit is resolved. A
 fixed validated bug is resolved. A handed-off off-target finding is resolved once
 this round has made its round-scoped record as *A shape change names its readers*
-defines that record — checked, result recorded, named in this round's progress
-report — whether or not the problem behind it is solved. Gate 2 reads the record
+defines that record (checked, result recorded, named in this round's progress
+report), whether or not the problem behind it is solved. Gate 2 reads the record
 and nothing else; the termination-time disclosure belongs to gate 3.
 
-A skipped finding — a finding deliberately not applied, because fixing it would
+A skipped finding, a finding deliberately not applied because fixing it would
 change intended behavior, would reach beyond the review target, or the finding
-itself is judged a false positive — is resolved once its skip is logged in this
+itself is judged a false positive, is resolved once its skip is logged in this
 round's progress report, naming the finding and the reason it was skipped. That
 report is the sink every run has, with or without `--fix`. When `--fix` is set,
 the skip handling `fix.md` carries runs inside this gate and adds to this log
@@ -210,7 +206,7 @@ rather than replacing it.
 
 Gate 3 reads that stated outcome, never a case label.
 
-**Gate 3 — exit test.** Resolve the terminal from the table above, then stop or
+**Gate 3, exit test.** Resolve the terminal from the table above, then stop or
 continue:
 
 - zero retained findings and required checks pass → `clean`;
@@ -226,13 +222,13 @@ Also require, for `clean` and `nits_fixed`:
 
 Any other combination runs the round tail and re-enters the loop.
 
-Terminating with `clean` or `nits_fixed` carries one further condition — the
+Terminating with `clean` or `nits_fixed` carries one further condition, the
 termination-time disclosure: the ready-for-review message names every broken
 off-target reader and every skipped finding that still exists. When the target
 is a pull request, the pull request body carries the same names; a target with
 no pull request owes the ready message alone. Every surface this condition
-names is written at termination — the ready message always, the pull request
-body too when the target is a pull request — so each one is available to the
+names is written at termination, the ready message always, the pull request
+body too when the target is a pull request, so each one is available to the
 terminating round. A round that cannot name them does not terminate; it runs
 the round tail and re-enters the loop, the same as any other non-terminating
 round. With that condition met, post the proof-of-work PR comment when the
@@ -250,7 +246,7 @@ own section above.
 *Required checks* gives: the bare command, no file paths. When this round
 produced edits, stage those edits first so they enter the bare gate's scope,
 then run the checks. When this round produced no edits, run the same checks.
-Should those checks produce repairs, this round has produced edits — stage
+Should those checks produce repairs, this round has produced edits. Stage
 them and re-run the checks.
 
 **Commit and push are lead-owned.** Gate 2 and the round tail leave every fix

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

@@ -33,7 +33,8 @@ function assertReviewLevelExtension() {
 }
 
 function assertProposalHandoffs() {
-  assert.match(proposalSource, /canonical contract owns the immutable range/)
+  assert.match(proposalSource, /This file owns the proposal contract for `e-code-review`/)
+  assert.match(proposalSource, /exact `base_sha\.\.\.head_sha` range/)
   const fixModeSource = sourceBetweenHeadings(
     fixSource,
     '## Preflight-proposal mode',

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

@@ -1,17 +1,37 @@
 # Review preflight proposal mode
 
-Apply the canonical proposal contract at:
+This file owns the proposal contract for `e-code-review`.
 
-```text
-@~/.claude/_shared/pr-loop/preflight-proposal.md
-```
-
-Use this review extension when the caller selects `preflight-proposal`:
+Use this review mode 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>
 ```
 
+## Required inputs
+
+| Input | Contract |
+|---|---|
+| `pr_number` | Resolved open pull-request number |
+| `--level` | Resolved review level: `low`, `medium`, or `xhigh` |
+| `--base-sha` | Full immutable base commit SHA |
+| `--head-sha` | Full immutable head commit SHA |
+| `--worktree` | Caller-supplied isolated worktree path |
+
+## Proposal contract
+
+1. Validate every required input before the first review command.
+2. Run `git rev-parse HEAD` in the supplied worktree and require exact equality with the head SHA.
+3. Gather changed paths and review scope from the exact `base_sha...head_sha` range. Use the resolved pull-request number for pull-request metadata.
+4. Run the complete selected review and findings against the immutable range and worktree.
+5. Keep every review edit and test inside the caller-supplied isolated worktree.
+6. Create an immutable proposal identity. Use the existing commit SHA for committed proposals. For working-tree edits, use a deterministic diff hash over the baseline `HEAD` SHA, base SHA, head SHA, sorted normalized changed paths, status records, and file bytes.
+7. Record every changed path, including tracked, untracked, renamed, and deleted paths.
+8. Record exact tests and outcomes: each test command, exit code, and outcome.
+9. Return selected-candidate-ready proposal evidence with the proposal ID, isolated worktree path, changed paths, findings, tests, and outcomes.
+10. Keep commit, push, pull-request body, pull-request comment, pull-request review, pull-request update, merge, rebase, and Ready-state mutations disabled.
+11. Return the proposal for downstream disposition. The downstream owner adds the proposal ID to its selected or dispositioned proposal collection. Reapplication uses exactly the selected records and their changed paths. Give each later finding a new proposal ID and evidence record.
+
 ## Review extension
 
 The caller resolves the review level before invocation and always passes `--level`. Use this mapping:
@@ -27,14 +47,29 @@ 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:
+Keep Gate 1, Gate 2, the bare code-rules gate, and exact required tests.
+
+## Evidence record
 
 ```yaml
+mode: preflight-proposal
+pr_number: <resolved PR number>
 review_level: low | medium | xhigh
+base_sha: <immutable base SHA>
+head_sha: <immutable head SHA>
+proposal_id:
+  kind: commit-sha | diff-sha256
+  value: <immutable identity>
+isolated_worktree: <caller-supplied path>
+changed_paths:
+  - <normalized path>
 findings:
   - severity: blocker | high | medium | low | nit
     verdict: CONFIRMED | PLAUSIBLE
     outcome: fixed | no_change_needed | skipped
+tests:
+  - command: <exact command>
+    exit_code: <integer>
+    outcome: <exact outcome>
+downstream_selection: required
 ```
-
-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

@@ -1,16 +1,16 @@
 # Runner selection (medium review)
 
-How `/e-code-review medium` (and loop) should pick a **harness runner** for
-finder/verify work. This file is the map; `SKILL.md` only points here.
+How `/e-code-review medium` (and loop) picks a harness runner for finder and
+verify work. `SKILL.md` points here.
 
 ## What lives here
 
 | Topic | Content |
 |---|---|
-| Goal | One skill surface; many possible runners (Grok, Codex, Claude headless, …) |
+| Goal | One skill surface, many runners (Grok, Codex, Claude headless, and others) |
 | Today | `scripts/grok_code_review.py` is the Grok medium orchestration module |
 | Target | A thin selector chooses a runner by availability and task flags |
-| Non-goals | Reimplementing every harness inside this skill |
+| Out of scope | Reimplementing every harness inside this skill |
 
 ## Today
 
@@ -21,21 +21,20 @@ finder/verify work. This file is the map; `SKILL.md` only points here.
 
 ## Target shape (tracked separately)
 
-1. **Runner protocol** — shared inputs (diff base, head, angles) and outputs
+1. **Runner protocol.** Shared inputs (diff base, head, angles) and outputs
    (candidates, verdicts, severities).
-2. **Detection** — which runners are installed/configured (PATH, skills,
+2. **Detection.** Which runners are installed or configured (PATH, skills,
    account chain).
-3. **Selection** — pick one runner without baking a single vendor into
-   `SKILL.md` process steps.
-4. **Adapters** — thin wrappers: Grok (current module), Codex, Claude, …
+3. **Selection.** Pick one runner. Keep vendor choice out of `SKILL.md`
+   process steps.
+4. **Adapters.** Thin wrappers: Grok (current module), Codex, Claude, and
+   others.
 
-Open issue for implementation work should link this file and keep PRs small
-(Google small-CL practice: one concern per PR).
+Keep implementation pull requests small: one concern each. Link this file from
+the tracking issue.
 
 ## Related always-on docs
 
-- Skill hub: `../SKILL.md` (levels, fix, loop — not runner internals).
+- Skill hub: `../SKILL.md` (levels, fix, loop).
 - 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/issue-tracker/SKILL.md

@@ -60,6 +60,13 @@ Search open and closed issues on the target repo before create. Open twin -> upd
 
 Prefer GitHub MCP. Fall back to `gh` on the same REST endpoints. Full map and `.id` rule: [reference/operation-matrix.md](reference/operation-matrix.md).
 
+Before issue creation, a full issue body edit, or an issue comment, write the
+body to a UTF-8 file. Resolve the active managed root (`CLAUDE_CONFIG_DIR` when
+set, `~/.claude` otherwise), then run
+`<managed-root>/scripts/durable_post_lint.py`. Use `issue-create`, `issue-edit`,
+or `issue-comment` as the action. Send the server write only after exit code
+`0`.
+
 ## Handoff input
 
 Optional issue-candidate JSON from orchestrator or closeout. Full schema and consume path: [reference/handoff-schema.md](reference/handoff-schema.md).