claude-dev-env 2.19.0 → 2.20.0

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

@@ -21,6 +21,14 @@ 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 = [
   {
@@ -77,13 +85,35 @@ function assertSharedProposalContract(contractSource) {
   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 both audit skills', () => {
+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/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,24 +1,114 @@
 ---
 name: pr-cleanup
-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.
+description: >-
+  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
+# PR cleanup
 
-Run `pr-refinement`, then run `sr-loop` on its resulting pull request or stack.
+## Contents
 
-## Workflow
+- [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)
 
-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.
+## Principle
+
+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.
+
+## When this applies
+
+Use this skill for a pull request that needs placement review, capability
+naming, cleanup convergence, and a focused delivery boundary.
+
+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.`
+
+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.
+
+## Composition
+
+| 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 |
+
+## Task seeding
+
+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 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 worktree.
+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`.
 
-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.
+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.
 
@@ -26,6 +116,14 @@ Use `reference/task-seeds.md` and `reference/process-inventory.md` to record pro
 
 - Pull request or stack URLs.
 - `pr-refinement` outcome.
-- `sr-loop` passes, commits, and validation results.
+- `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/_shared/pr-loop/scripts/code_rules_gate.py

@@ -4,6 +4,7 @@
 
     default mode: git diff since merge-base, joined with untracked files
     --staged:     validate the staged index; --paths: validate explicit files
+    --immediate:  validate staged rules and terminology at commit time
     every mode ends by naming how many files it inspected
 
 This entry module wires the ``code_rules_gate_parts`` submodules into one CLI
@@ -43,6 +44,7 @@ try:
         ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS,
         EMPTY_FILE_SET_EXIT_CODE,
         EMPTY_FILE_SET_MESSAGE,
+        IMMEDIATE_SCOPE_ARGUMENT,
         INSPECTED_COUNT_MESSAGE,
         MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS,
         MINIMUM_STAGED_PYTEST_PYTHON_MAJOR,
@@ -263,31 +265,50 @@ def _run_explicit_paths_mode(
     )
 
 
-def _run_staged_mode(
+def _run_staged_validation(
     validate_content: enforcer_loading.ValidateContentCallable,
     arguments: argparse.Namespace,
     repository_root: Path,
 ) -> int:
-    """Validate the staged changes, run staged tests, and sweep terminology."""
-    _report_terminology_findings(staged_terminology_findings(repository_root))
-    staged_test_exit_code = _staged_pytest_exit_code_for_current_python(repository_root)
+    """Validate staged file content and report scoped rule findings."""
     staged_file_paths = filter_paths_under_prefixes(
         paths_from_git_staged(repository_root), repository_root, arguments.only_under
     )
     if not staged_file_paths:
         sys.stderr.write(INSPECTED_COUNT_MESSAGE.format(inspected_count=0) + "\n")
-        return staged_test_exit_code
+        return 0
     staged_added_lines = added_lines_by_file_staged(repository_root, staged_file_paths)
-    gate_exit_code = run_gate(
+    return run_gate(
         validate_content,
         staged_file_paths,
         repository_root,
         all_added_lines_by_path=staged_added_lines,
         should_read_staged_content=True,
     )
+
+
+def _run_staged_mode(
+    validate_content: enforcer_loading.ValidateContentCallable,
+    arguments: argparse.Namespace,
+    repository_root: Path,
+) -> int:
+    """Validate staged rules, terminology, and staged-test behavior."""
+    _report_terminology_findings(staged_terminology_findings(repository_root))
+    staged_test_exit_code = _staged_pytest_exit_code_for_current_python(repository_root)
+    gate_exit_code = _run_staged_validation(validate_content, arguments, repository_root)
     return gate_exit_code or staged_test_exit_code
 
 
+def _run_immediate_mode(
+    validate_content: enforcer_loading.ValidateContentCallable,
+    arguments: argparse.Namespace,
+    repository_root: Path,
+) -> int:
+    """Validate staged rules and terminology at the native commit boundary."""
+    _report_terminology_findings(staged_terminology_findings(repository_root))
+    return _run_staged_validation(validate_content, arguments, repository_root)
+
+
 def _run_diff_mode(
     validate_content: enforcer_loading.ValidateContentCallable,
     arguments: argparse.Namespace,
@@ -339,6 +360,8 @@ def main(all_arguments: list[str]) -> int:
     validate_content = load_validate_content()
     if arguments.paths:
         return _run_explicit_paths_mode(validate_content, arguments, repository_root)
+    if arguments.immediate:
+        return _run_immediate_mode(validate_content, arguments, repository_root)
     if arguments.staged:
         return _run_staged_mode(validate_content, arguments, repository_root)
     return _run_diff_mode(validate_content, arguments, repository_root)

package/_shared/pr-loop/scripts/code_rules_gate_parts/gate_arguments.py

@@ -3,9 +3,14 @@
 import argparse
 from pathlib import Path
 
+from pr_loop_shared_constants.code_rules_gate_constants import (
+    IMMEDIATE_SCOPE_ARGUMENT,
+    IMMEDIATE_SCOPE_HELP,
+)
+
 
 def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
-    """Add the repo-root, base-ref, and staged-mode arguments to *parser*."""
+    """Add the repo-root, base-ref, and staged-scope arguments to *parser*."""
     parser.add_argument(
         "--repo-root",
         type=Path,
@@ -17,12 +22,19 @@ def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
         default="origin/main",
         help="Merge-base ref for git diff (default: origin/main).",
     )
-    parser.add_argument(
+    staged_scope_group = parser.add_mutually_exclusive_group()
+    staged_scope_group.add_argument(
         "--staged",
         action="store_true",
         default=False,
         help="Scope to staged changes only (git diff --cached).",
     )
+    staged_scope_group.add_argument(
+        IMMEDIATE_SCOPE_ARGUMENT,
+        action="store_true",
+        default=False,
+        help=IMMEDIATE_SCOPE_HELP,
+    )
 
 
 def _add_filter_arguments(parser: argparse.ArgumentParser) -> None:
@@ -65,6 +77,6 @@ def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
 
     Returns:
         The parsed namespace with ``repo_root``, ``base``, ``staged``,
-        ``only_under``, and ``paths`` attributes.
+        ``immediate``, ``only_under``, and ``paths`` attributes.
     """
     return _build_argument_parser().parse_args(all_arguments)

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -97,6 +97,10 @@ CODE_RULES_GATE_PYTHON_ENV_VAR: str = "CODE_RULES_GATE_PYTHON"
 
 CODE_RULES_GATE_PYTHONPATH_ENV_VAR: str = "CODE_RULES_GATE_PYTHONPATH"
 
+IMMEDIATE_SCOPE_ARGUMENT: str = "--immediate"
+
+IMMEDIATE_SCOPE_HELP: str = "Validate staged rules without running staged tests."
+
 PYTHONPATH_ENV_VAR: str = "PYTHONPATH"
 
 ALL_VENV_DIRECTORY_NAMES: tuple[str, ...] = (".venv", "venv")

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -300,6 +300,45 @@ def test_main_staged_mode_blocks_when_staged_lines_introduce_violations(
     assert exit_code == 1
 
 
+def test_main_immediate_mode_blocks_staged_rule_violations(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "module.py", "first_count = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        temporary_git_repository / "module.py",
+        "first_count = 1\n"
+        "def compute_total(operand):\n"
+        "    result = operand + 1\n"
+        "    return result\n",
+    )
+    stage_file(temporary_git_repository, "module.py")
+
+    monkeypatch.chdir(temporary_git_repository)
+    exit_code = gate_module.main(["--immediate"])
+
+    assert exit_code == 1
+
+
+def test_main_immediate_mode_skips_staged_test_execution(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "module.py", "first_count = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        temporary_git_repository / "test_staged_failure.py",
+        "def test_intentionally_fails() -> None:\n    assert False\n",
+    )
+    stage_file(temporary_git_repository, "test_staged_failure.py")
+
+    monkeypatch.chdir(temporary_git_repository)
+    exit_code = gate_module.main(["--immediate"])
+
+    assert exit_code == 0
+
+
 def test_main_staged_mode_passes_when_no_staged_violations(
     temporary_git_repository: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -2336,10 +2375,18 @@ def test_parse_arguments_reads_staged_base_and_prefix_flags() -> None:
     assert parsed_arguments.paths == [Path("explicit_file.py")]
 
 
+def test_parse_arguments_reads_immediate_scope_flag() -> None:
+    parsed_arguments = gate_module.parse_arguments(["--immediate"])
+
+    assert parsed_arguments.immediate is True
+    assert parsed_arguments.staged is False
+
+
 def test_parse_arguments_applies_documented_defaults() -> None:
     parsed_arguments = gate_module.parse_arguments([])
 
     assert parsed_arguments.staged is False
+    assert parsed_arguments.immediate is False
     assert parsed_arguments.base == "origin/main"
     assert parsed_arguments.repo_root is None
     assert parsed_arguments.only_under == []

package/docs/CODE_RULES.md

@@ -94,6 +94,8 @@ Removed code is removed: no renamed re-export aliases, no `_old_*` aliases, no k
 
 Never swallow a failure into a default unless the caller explicitly opted in at the boundary. Name the specific exception (`except KeyError:`) and propagate the rest — collapsing every error class to `None` masks programming errors and makes debugging impossible.
 
+**A per-member boundary records each member outcome.** In a batch loop, a `try`/`except` inside the loop body catches a declared `*ItemBlocked` type, records the failure with its reason, and continues to the next member — the failure reaches the run report by name. The boundary preserves the blast radius: escalations re-raise first so a `*RunFatal` passes through directly, while `except Exception` triggers the rule. Types, boundary shape, and the parked-member report: [`rules/failure-blast-radius.md`](../rules/failure-blast-radius.md).
+
 ## 9.8 REMOVE CODE YOU ORPHAN (Dead Code Elimination)
 
 An edit that deletes or rewrites code also removes everything it makes dead: unread variables, uncalled functions, unpassed parameters, dead branches, unused imports, helper files whose only consumer that edit deleted. Prove unreachability first: Serena `find_referencing_symbols` plus a text search for dynamic lookups (`getattr`, entry-point names). A symbol is live only when a reference chain reaches a live entry point (CLI command, route, public API, test); a self-referential dead cluster is removed together in the same commit. **When liveness is uncertain (public API, plugin hook, reflective dispatch), do NOT delete — surface the ambiguity via AskUserQuestion.** Source links: [`references/dead-code-elimination.md`](references/dead-code-elimination.md).

package/hooks/advisory/conftest.py

@@ -0,0 +1,10 @@
+"""Pytest registration for shared refactor guard test support."""
+
+import sys
+from pathlib import Path
+
+advisory_directory = str(Path(__file__).resolve().parent)
+if advisory_directory not in sys.path:
+    sys.path.insert(0, advisory_directory)
+
+from refactor_guard_test_support import git_repository  # noqa: E402, F401