claude-dev-env 2.18.0 → 2.20.0

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
 

package/_shared/pr-loop/AGENTS.md

@@ -11,6 +11,7 @@ Runtime documents and scripts shared by every PR-loop skill. Changes here affect
 | `post-audit-thread-contract.md` | Single source of truth for the `post_audit_thread.py` invocation string, exit-code table, and per-caller policy (bugteam exit 2 = hard blocker; autoconverge clean-audit failed post = recorded bypass) |
 | `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
 | `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
+| `preflight-proposal.md` | Shared immutable proposal evidence and mutation-boundary contract for audit preflight worktrees |
 | `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |
 | `code-rules-gate.md` | Reference for the CODE_RULES pre-commit gate check; describes what the gate blocks and when it runs |
 | `precatch-rubric.md` | Shared pre-catch lane checklist — deterministic sweep, doc-vs-code parity, test-assertion completeness, PR-description parity, adversarial audit — that autoconverge's lenses and pr-converge's CODE_REVIEW step read on demand |
@@ -24,4 +25,4 @@ Runtime documents and scripts shared by every PR-loop skill. Changes here affect
 
 ## Breaking-change rule
 
-Any shape change in `audit-contract.md` or `audit-reply-template.md` requires updating every consuming skill in the same commit.
+Any shape change in a canonical contract listed under **Key documents** requires updating every consuming skill in the same commit.

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

@@ -0,0 +1,56 @@
+# Preflight proposal contract
+
+Audit skills use this contract when the caller selects `preflight-proposal`. The mode prepares a local candidate and returns evidence for downstream selection.
+
+Each skill hub defines its command name and finding classification. Commands use this shape:
+
+```text
+<audit-skill> preflight-proposal <pr_number> --base-sha <base_sha> --head-sha <head_sha> --worktree <isolated_worktree>
+```
+
+## Required inputs
+
+| Input | Contract |
+|---|---|
+| `pr_number` | Resolved open pull-request number |
+| `--base-sha` | Full immutable base commit SHA |
+| `--head-sha` | Full immutable head commit SHA |
+| `--worktree` | Caller-supplied isolated worktree path |
+
+## Contract
+
+1. Validate every required input before the first audit command.
+2. Run `git rev-parse HEAD` in the supplied worktree and require exact equality with the head SHA.
+3. Gather changed paths and audit scope from the exact `base_sha...head_sha` range. Use the resolved PR number for PR metadata.
+4. Run the complete audit and findings against the immutable range and worktree.
+5. Keep every audit 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.
+
+## Evidence record
+
+Use this record shape:
+
+```yaml
+mode: preflight-proposal
+pr_number: <resolved PR number>
+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:
+  - <audit-classified finding>
+tests:
+  - command: <exact command>
+    exit_code: <integer>
+    outcome: <exact outcome>
+downstream_selection: required
+```

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/code_rules_gate_parts/tests/test_gate_running.py

@@ -3,14 +3,23 @@
 from pathlib import Path
 
 import pytest
-from code_rules_gate_parts import gate_running
 
+from code_rules_gate_parts import enforcer_loading, gate_running
+from code_rules_gate_parts.tests._repo_test_helpers import (
+    init_repository,
+    write_commit_and_stage_change,
+)
 
-def _clean_validate(_content: str, _path: str, _prior: str = "", **_kwargs: object) -> list[str]:
+
+def _clean_validate(
+    _content: str, _path: str, _prior: str = "", **_kwargs: object
+) -> list[str]:
     return []
 
 
-def _dirty_validate(_content: str, _path: str, _prior: str = "", **_kwargs: object) -> list[str]:
+def _dirty_validate(
+    _content: str, _path: str, _prior: str = "", **_kwargs: object
+) -> list[str]:
     return ["Line 1: bad"]
 
 
@@ -92,8 +101,42 @@ def test_print_violation_section_groups_by_relative_path(
 ) -> None:
     module_path = (tmp_path / "module.py").resolve()
 
-    gate_running.print_violation_section("HEADER", {module_path: ["Line 1: issue"]}, tmp_path)
+    gate_running.print_violation_section(
+        "HEADER", {module_path: ["Line 1: issue"]}, tmp_path
+    )
 
     captured = capsys.readouterr()
     assert "HEADER" in captured.err
     assert "Line 1: issue" in captured.err
+
+
+def test_gate_caller_scans_staged_content_with_commit_stage_scope(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    repository_root = tmp_path / "repository"
+    repository_root.mkdir()
+    init_repository(repository_root)
+    committed_source = "def calculate_total() -> int:\n    return 0\n"
+    staged_source = (
+        "def calculate_total() -> int:\n    total = 9999\n    return total\n"
+    )
+    file_path = write_commit_and_stage_change(
+        repository_root,
+        "service.py",
+        committed_source,
+        staged_source,
+    )
+
+    resolved_file_path = file_path.resolve()
+    exit_code = gate_running.run_gate(
+        validate_content=enforcer_loading.load_validate_content(),
+        all_file_paths=[resolved_file_path],
+        repository_root=repository_root,
+        all_added_lines_by_path={resolved_file_path: {2, 3}},
+        should_read_staged_content=True,
+    )
+
+    captured = capsys.readouterr()
+    assert exit_code == 1
+    assert "9999" in captured.err

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")