claude-dev-env 2.0.1 → 2.1.0

package/CLAUDE.md

@@ -43,7 +43,7 @@ Run every multi-step code task in two phases:
 1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
 2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
-Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
+Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
 
 ## Sub-agent Output Validation
 

package/agents/clean-coder.md

@@ -2,7 +2,7 @@
 name: clean-coder
 description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
 model: opus
-tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill
+tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---
 
@@ -389,6 +389,36 @@ BEFORE writing:
 [12] One abstraction level throughout?
 ```
 
+## Pre-Check Loop — Validate Candidate Content Before Each Write
+
+The write gate reports every violation in one denial, so a blocked write is a poor place to find a rule. Run the checker on the candidate content first, read the verdict, fix each line, and re-run until the verdict is clean. Then call Write or Edit, and the write lands on the first try.
+
+### The two local surfaces
+
+- **`code_rules_enforcer.py --check <candidate> [--as <target>]`** — the full CODE_RULES verdict on one complete candidate file. Stage the candidate at any path and point `--as` at the real destination. The `--as` target drives every path-based decision (test-file detection, `config/` exemption, hook-infrastructure exemption), so a candidate staged in a temp folder is judged as if it sat at its destination. Exit `0` is clean or an exempt target; `1` is one or more violations, each on its own line, or an unreadable candidate; `2` is a malformed flag sequence.
+- **`run_all_validators.py`** — the validator suite over the git-changed files: Ruff, Mypy, type safety, magic values, abbreviations, and more. `--pre-tool-use` runs the same suite as a gate on one proposed write from stdin. `--health` reports whether the suite runs.
+
+Point `--as` at the file's real production path. When `--as` names an exempt path, the check returns `0` for a candidate that carries violations, so a wrong target hides the verdict you want.
+
+### The loop
+
+1. Build the full candidate content.
+2. Stage it at a temp path with the Write tool or the PowerShell tool.
+3. Run `code_rules_enforcer.py --check <staged path> --as <real destination>`.
+4. Read every reported line and fix each one in the candidate.
+5. Re-run step 3. A fix can raise a fresh violation: a magic number pulled to a module constant needs the `ALL_` collection prefix, and that rename can leave the source constant with no reader; a long function split to meet the length target can push the file past the length advisory. Loop steps 3 through 5 until the verdict is clean.
+6. Call Write or Edit with the clean content.
+
+Re-running the checker after each fix catches the rework a single pass misses, so the write clears the gate one time.
+
+### Windows shell shape
+
+Create every multi-line script with the PowerShell tool or the Write tool. A bash heredoc on Windows strips backslashes from paths and garbles multi-line Python, so a heredoc-built script fails in ways its source text hides. For a wait-for-condition step, drive a Monitor until-loop; a `sleep && tail` poll chain blocks the turn and misses the moment the condition flips.
+
+### Mining session transcripts
+
+When reading transcripts under the user projects directory, pass explicit file paths to the reader, or search through Python or `Select-String`. A `.gitignore` holding `*` in that tree makes ripgrep and Grep directory recursion return zero matches with no error, so a recursive pattern reads as a clean miss even when files match.
+
 ## Constants Protocol
 
 Decision tree before writing any constant:

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -66,7 +66,7 @@ Inline the artifact under this section using the section types defined in the ch
 **E8. Stub / placeholder code without TODO**
 - Distinguish real-behavior `pass` / `continue` / empty-handler bodies (intentional swallowing of expected exceptions, no-op branches that exist to satisfy a contract) from scaffolding stubs.
 - Real-behavior bodies do NOT require a TODO; the audit must state the rationale (e.g., "rmdir race with concurrent writer is intentionally swallowed").
-- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's "Document Temporary Code" rule.
+- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's `CODE_RULES.md` → "COMMENT PRESERVATION" rule.
 - Adversarial probes for proof-of-absence: (a) any empty brace block in PowerShell / TypeScript / Go (`{ }` with no statements)? (b) any function whose entire body is `pass` / `return` / `return None`? (c) any branch that exits cleanly only because the surrounding loop is no-op for an empty input — is the no-op intentional or a placeholder?
 
 **E9. Constants-module exports with no importer**
@@ -165,7 +165,7 @@ ID prefix: `find`.
 - `sweep_empty_dirs.py` line 28: the second `except OSError: continue` similarly is intended behavior (skip the directory whose ctime is unreadable), not a stub.
 - No `...` literal anywhere in the four files.
 - No `raise NotImplementedError` anywhere.
-- No `# TODO` markers in the diff — the project's own rule (`code-standards.md` → "Document Temporary Code") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
+- No `# TODO` markers in the diff — the project's own rule (`CODE_RULES.md` → "COMMENT PRESERVATION") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
 - Adversarial probes for proof-of-absence: (a) does the PowerShell script have an empty `else { }` or empty branch body? — scan lines 14-71 for any `{ }` with no statements between the braces. (b) does any function body consist of a single `pass` or `return` with no work done? — every function body in this PR performs at least one statement. (c) does the `Status` branch (lines 14-31) exit cleanly even when `$task.Triggers` is empty? — the `foreach` loop at line 26 is a no-op for an empty collection, which is correct behavior, not a stub.
 
 **E9. Constants-module exports with no importer**

package/bin/install.test.mjs

@@ -803,13 +803,13 @@ test('managedHookScriptRelativePathsFromSourceRoots unions managed scripts acros
             hooks: { Stop: [{ matcher: '', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py' }] }] },
         });
         writeHooksJsonAtRoot(dependencyRoot, {
-            hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pwsh_enforcer.py' }] }] },
+            hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/example_hook.py' }] }] },
         });
 
         const relativePaths = managedHookScriptRelativePathsFromSourceRoots([builtinRoot, dependencyRoot]);
 
         assert.ok(relativePaths.has('blocking/code_rules_enforcer.py'));
-        assert.ok(relativePaths.has('blocking/pwsh_enforcer.py'));
+        assert.ok(relativePaths.has('blocking/example_hook.py'));
         for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
             assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must always be in the managed set`);
         }

package/docs/CLAUDE.md

@@ -14,8 +14,9 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 | `PR_DESCRIPTION_GUIDE.md` | Authoritative reference for the `pr-description-writer` agent; PR body shapes derived from a 120-PR Anthropic corpus |
 | `DJANGO_PATTERNS.md` | Django-specific coding patterns |
 | `REACT_PATTERNS.md` | React-specific coding patterns |
-| `emotion-informed-prompt-design.md` | Guidance for emotionally-aware prompt authoring |
-| `agents-md-alignment-plan.md` | Alignment between `AGENTS.md` review-tool rules and the local hook enforcement layer |
+| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
+| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
+| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
 
 ## Subdirectory
 
@@ -25,4 +26,6 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 
 ## Load pattern
 
-Rules reference these docs with `@~/.claude/docs/<file>.md` to pull them into context only when needed, rather than loading every doc on every session start.
+A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
+
+The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.

package/docs/CODE_RULES.md

@@ -8,6 +8,8 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 **Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
 
+Scaffolding and placeholder code carry a `TODO:` comment naming the permanent implementation and why the code is temporary — the documented exception to the no-new-comments rule.
+
 ---
 
 ## CORE PRINCIPLES
@@ -16,6 +18,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 - **Centralized configuration** — every constant lives in ONE place (`config/`).
 - **Reuse before create** — search first, import second, create last.
 - **Encapsulation enables cleaner naming** — `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`.
+- **Construction logic lives in the model** — path/URL building, formatting, and transformations belong on the model or service that owns the data; a string pattern built at two or more call sites moves to a method there.
 
 ---
 
@@ -37,7 +40,7 @@ Before writing ANY constant: search `config/` for the exact value → semantic m
 
 ## 5. NO ABBREVIATIONS
 
-Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`.
+Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`. Name a component for what it IS — `Overlay`, `Validator`, `InvoicePreview`.
 
 ---
 
@@ -55,6 +58,7 @@ Advisory only, never blocking: soft advisory at >= 400 lines, strong nudge at >=
 
 **Simple > Clever. Functions > Classes. Concrete > Abstract.**
 Never: ABC for single impl, DI frameworks, factory for single type. Always: functions when no state, concrete classes, simple imports.
+Parameters follow YAGNI: add an optional parameter when a caller varies the value; when every call site passes the same value, make it required or inline the constant. Remove parameters no caller passes and no body reads.
 
 ## 7.5 SOLID PRINCIPLES
 

package/docs/agent-spawn-protocol.md

@@ -0,0 +1,39 @@
+# Agent Spawn Protocol
+
+Full protocol behind the always-on `rules/agent-spawn-protocol.md` kernel. It applies before any Agent or Task tool invocation — Explore, implementation, research, or team subagents.
+
+## Step 1: Context sufficiency check
+
+Before writing any agent prompt, confirm you can answer all of these:
+
+- What specific files, directories, or areas of the codebase are involved?
+- What constraints apply — patterns to follow, things to leave untouched, boundaries?
+- What does success look like — expected output, acceptance criteria?
+- Is the task unambiguous enough to delegate?
+
+When any answer is "I don't know", investigate first (read files, search code) or ask the user. Do not spawn with incomplete context.
+
+## Step 2: Craft the prompt with /prompt-generator
+
+Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
+
+- The task description and goal
+- Target files and directories found in Step 1
+- Constraints and boundaries
+- Expected output format
+- Acceptance criteria
+
+The skill asks one to three clarifying questions when information is missing — this is the built-in context verification. Use the skill's output as the agent's `prompt` parameter.
+
+## Step 3: Spawn the agent
+
+Pass the structured prompt from Step 2 to the Agent or Task tool.
+
+## Why
+
+An agent that receives a vague prompt wastes tokens exploring in circles, produces code that misses constraints, and needs a second pass. A small investment in prompt quality through `/prompt-generator` saves a long agent failure. This holds for Explore agents, which waste context on unfocused searches, and for execution agents, which write wrong code.
+
+## Relationship to other rules
+
+- `conservative-action.md` gates acting when intent is ambiguous. This protocol extends that: an ambiguous task goes to investigation or a user question first, never straight to a subagent.
+- Project-specific rules or `~/.claude/CLAUDE.md` may decide whether to use subagents at all; this protocol governs how to craft the prompt once you delegate.

package/docs/nas-ssh-invocation.md

@@ -0,0 +1,23 @@
+# NAS SSH Invocation Policy
+
+Full detail behind the always-on `rules/nas-ssh-invocation.md` kernel. It applies to any `ssh`, `scp`, or `sftp` command against the NAS.
+
+## Why the Windows OpenSSH binary
+
+Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
+
+## The form to use
+
+```
+"/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 22 operator@nas.example.local "<cmd>"
+```
+
+`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and the same port (`-P` for `scp`).
+
+The host, ssh user, and port come from the `CLAUDE_NAS_*` environment variables or `~/.claude/local-identity.json`; the committed examples show placeholders (`nas.example.local`, `operator`, `22`).
+
+`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
+
+## Enforcement
+
+`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at the NAS host and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.

package/docs/worker-completion-gate.md

@@ -0,0 +1,33 @@
+# Worker Completion Gate
+
+Full detail behind the always-on `rules/workers-done-before-complete.md` kernel. It applies before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+
+## The gate
+
+A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
+
+List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
+
+## Checklist before marking complete
+
+| Check | Action |
+|---|---|
+| Are any spawned workers still running? | List them; when yes, stay `in_progress` and schedule a wakeup. |
+| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
+| Is each result merged into run state? | Write it to `state.json` or the task list before closing. |
+| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
+
+Mark `completed` only when every row passes.
+
+## Examples
+
+**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
+**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
+
+**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
+**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
+
+## Relationship to other rules
+
+- `long-horizon-autonomy` covers acting on what you have and not ending a turn on a promise. This gate names the specific completion condition: workers finished and their results merged.
+- `skills/pr-converge/reference/state-schema.md` defines the run-state records a worker's result lands in before the task closes.

package/hooks/blocking/CLAUDE.md

@@ -8,6 +8,7 @@ PreToolUse hooks that deny (block) tool calls when a rule is violated. The main
 |---|---|
 | `config/` | Shared constants for the verified-commit gate family (`verified_commit_constants.py`) |
 | `tdd_enforcer_parts/` | Concern modules the `tdd_enforcer.py` entry hook wires together: path classification, content analysis, candidate-path resolution, freshness, git-tracking restore detection, decisions, and constants |
+| `verified_commit_gate_parts/` | Concern modules the `verified_commit_gate.py` entry hook wires together: command tokenization, directory-change resolution, gated git-invocation resolution, deny-reason resolution, and deny-payload assembly |
 | `claude_md_orphan_file_blocker_parts/` | Concern modules the `claude_md_orphan_file_blocker.py` entry hook wires together: reference extraction, subtree scan, scan plan, decision, and constants |
 | `package_inventory_stale_blocker_parts/` | Concern modules the `package_inventory_stale_blocker.py` entry hook wires together: inventory detection, decision, and constants |
 | `inventory_intent_records/` | The shared per-session pending-intent store both inventory blockers read to break the file/row add-order deadlock |

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -74,6 +74,7 @@ from hooks_constants.dead_module_constant_constants import (  # noqa: E402
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
     DEAD_MODULE_CONSTANT_GUIDANCE,
+    DEAD_MODULE_CONSTANT_RETRY_GUIDANCE,
     DUNDER_ALL_NAME,
     DUNDER_INIT_FILENAME,
     GIT_DIRECTORY_NAME,
@@ -204,9 +205,11 @@ def _referenced_names_in_source(
     """Return every name a module references — imported, read, or re-exported.
 
     Collects imported binding names, ``from`` import member names, name
-    references, attribute roots, and (when ``collect_string_literals`` is set)
-    string literals, so a name listed in an ``__all__`` literal or named in a
-    string annotation counts as a reference. A module that fails to parse
+    references, both the root and the member name of each attribute access (so
+    ``module.CONSTANT`` counts ``CONSTANT`` as read), and (when
+    ``collect_string_literals`` is set) string literals, so a name listed in an
+    ``__all__`` literal or named in a string annotation counts as a reference. A
+    module that fails to parse
     contributes no names. With ``load_only`` set, only ``Load``-context names
     count, so a constant's own assignment target in the module being judged does
     not count as a reference to itself.
@@ -234,6 +237,8 @@ def _referenced_names_in_source(
             if load_only and not isinstance(each_node.ctx, ast.Load):
                 continue
             referenced_names.add(each_node.id)
+        elif isinstance(each_node, ast.Attribute):
+            referenced_names.add(each_node.attr)
         elif isinstance(each_node, ast.Import | ast.ImportFrom):
             for each_alias in each_node.names:
                 referenced_names.add(each_alias.asname or each_alias.name)
@@ -631,8 +636,9 @@ def check_dead_module_constants(
         if each_name in all_referenced_names:
             continue
         issues.append(
-            f"Line {each_line}: module-level constant {each_name!r}"
-            f" - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+            f"Line {each_line}: module-level constant {each_name!r} in"
+            f" {written_path.name} - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+            f" {DEAD_MODULE_CONSTANT_RETRY_GUIDANCE}"
         )
         if len(issues) >= MAX_DEAD_MODULE_CONSTANT_ISSUES:
             break

package/hooks/blocking/code_rules_shared.py

@@ -31,11 +31,11 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
 from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME,
     HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
-    HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME,
     HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
     HOOK_PAYLOAD_SESSION_ID_KEY,
-    HOOK_PAYLOAD_WORKING_DIRECTORY_KEY,
 )
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
@@ -275,78 +275,157 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     return False
 
 
-def _resolve_session_scratchpad_root(hook_payload: dict) -> str | None:
-    """Rebuild the harness session scratchpad directory from a PreToolUse payload.
+def _session_id_for_scratchpad(hook_payload: dict) -> str:
+    """Return the session id from the payload, or the harness environment value.
+
+    Args:
+        hook_payload: The PreToolUse payload that may carry ``session_id``.
+
+    Returns:
+        The payload session id when present, otherwise the
+        ``CLAUDE_CODE_SESSION_ID`` environment value, or an empty string when
+        neither source carries one.
+    """
+    payload_session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
+    if isinstance(payload_session_id, str) and payload_session_id:
+        return payload_session_id
+    return os.environ.get(CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME, "")
 
-    ::
 
-        payload.cwd = /home/user/project    payload.session_id = 5f2c...
-                          |                            |
-        <tempdir>/claude-<uid>/-home-user-project/5f2c.../scratchpad
-                     |               |
-                  os.getuid()   cwd with each "/" turned to "-"
+def _is_harness_user_directory(directory_name: str) -> bool:
+    """Return whether a path component is the harness user directory.
 
-    No environment variable carries this path, so it is rebuilt from the three
-    signals a hook can read: the POSIX user id and the ``cwd`` and ``session_id``
-    fields the harness puts in every PreToolUse payload. The rebuilt directory
-    is returned only when it exists on disk, so a wrong guess or a non-POSIX
-    platform yields None and the gates keep full enforcement.
+    The harness names this directory ``claude`` on Windows and ``claude-<uid>``
+    on POSIX, so both the exact name and the prefixed form count.
 
     Args:
-        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+        directory_name: A single path component below the temp-directory root.
 
     Returns:
-        The scratchpad directory path when it exists on disk, else None.
+        True when the component is the harness user directory.
     """
-    get_user_id = getattr(os, "getuid", None)
-    if get_user_id is None:
-        return None
-    session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
-    working_directory = hook_payload.get(HOOK_PAYLOAD_WORKING_DIRECTORY_KEY, "")
-    if not isinstance(session_id, str) or not session_id:
-        return None
-    if not isinstance(working_directory, str) or not working_directory:
-        return None
-    mangled_working_directory = working_directory.replace("\\", "/").replace(
-        "/", HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT
-    )
-    user_directory_name = f"{HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX}{get_user_id()}"
-    scratchpad_root = os.path.join(
-        tempfile.gettempdir(),
-        user_directory_name,
-        mangled_working_directory,
-        session_id,
-        HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    return (
+        directory_name == HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME
+        or directory_name.startswith(HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX)
     )
-    if not os.path.isdir(scratchpad_root):
+
+
+def _relative_parts_under_temp_root(
+    real_target: str, real_temp_root: str
+) -> tuple[str, ...]:
+    """Return real_target's path components below real_temp_root, or empty when outside.
+
+    Args:
+        real_target: The resolved candidate path.
+        real_temp_root: The resolved temp-directory root.
+
+    Returns:
+        The path components between the temp root and the target, or an empty
+        tuple when the target sits outside the temp directory or on another
+        drive.
+    """
+    try:
+        relative_path = os.path.relpath(real_target, real_temp_root)
+    except ValueError:
+        return ()
+    all_relative_parts = Path(relative_path).parts
+    if all_relative_parts and all_relative_parts[0] == os.path.pardir:
+        return ()
+    return all_relative_parts
+
+
+def _existing_scratchpad_root(
+    all_relative_parts: tuple[str, ...], real_temp_root: str, session_id: str
+) -> str | None:
+    """Return the on-disk scratchpad root matching the harness shape, or None.
+
+    ::
+
+        <temp-root>/<user-dir>/<mangled-cwd>/<session-id>/scratchpad/<file>
+                        |                          |           |
+                  claude user dir            session id     leaf name
+
+    Args:
+        all_relative_parts: The target's path components below the temp root.
+        real_temp_root: The resolved temp-directory root.
+        session_id: The session id the scratchpad's parent segment must equal.
+
+    Returns:
+        The scratchpad directory path when the shape matches and that directory
+        exists on disk, otherwise None.
+    """
+    if not all_relative_parts or not _is_harness_user_directory(all_relative_parts[0]):
         return None
-    return scratchpad_root
+    for each_session_index in range(2, len(all_relative_parts) - 1):
+        leaf_index = each_session_index + 1
+        if all_relative_parts[each_session_index] != session_id:
+            continue
+        if all_relative_parts[leaf_index] != HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME:
+            continue
+        scratchpad_root = os.path.join(
+            real_temp_root, *all_relative_parts[: leaf_index + 1]
+        )
+        if os.path.isdir(scratchpad_root):
+            return scratchpad_root
+    return None
 
 
 def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
     """Return True when file_path resolves under the harness session scratchpad.
 
     One-off scripts written to the session scratchpad are throwaway tooling
-    outside every repo, so the TDD and CODE_RULES gates skip them. Both
-    file_path and the rebuilt scratchpad root are resolved through the real
-    filesystem (symlinks followed) before the containment test, so a symlink
-    into the scratchpad exempts and a symlink out of it does not.
+    outside every repo, so the TDD and CODE_RULES gates skip them.
+
+    The match keys on the session id — from the payload, or the
+    ``CLAUDE_CODE_SESSION_ID`` environment variable — and on the temp-directory
+    path shape ``<user-dir>/<mangled-cwd>/<session-id>/scratchpad``, so it holds
+    on Windows and POSIX alike. file_path resolves through the real filesystem
+    (symlinks followed) before the shape test, and the scratchpad directory must
+    exist on disk, so a crafted path that never existed keeps full enforcement.
 
     Args:
         file_path: The path the write targets.
-        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+        hook_payload: The PreToolUse payload carrying the session id.
 
     Returns:
         True when file_path's real path sits at or under the session scratchpad.
     """
     if not file_path:
         return False
-    scratchpad_root = _resolve_session_scratchpad_root(hook_payload)
-    if scratchpad_root is None:
+    session_id = _session_id_for_scratchpad(hook_payload)
+    if not session_id:
         return False
     real_target = os.path.realpath(file_path)
-    real_root = os.path.realpath(scratchpad_root)
-    return real_target == real_root or real_target.startswith(real_root + os.sep)
+    real_temp_root = os.path.realpath(tempfile.gettempdir())
+    all_relative_parts = _relative_parts_under_temp_root(real_target, real_temp_root)
+    return (
+        _existing_scratchpad_root(all_relative_parts, real_temp_root, session_id)
+        is not None
+    )
+
+
+def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
+    """Return True when file_path is a throwaway scratch path exempt from repo gates.
+
+    Combines the two throwaway-path families a repo gate skips: the root-anchored
+    ephemeral scratch directories (``/tmp`` and ``$CLAUDE_JOB_DIR/tmp``) and the
+    harness session scratchpad. The session scratchpad match reads the session id
+    from the payload when one is supplied, and from the harness environment
+    variable otherwise, so a caller that holds no payload still gets the match.
+    One call answers path exemption for both families, so a gate that skips
+    throwaway paths need not repeat the two checks itself.
+
+    Args:
+        file_path: The candidate path to classify.
+        hook_payload: The PreToolUse payload carrying the session id, or None to
+            read the session id from the environment alone.
+
+    Returns:
+        True when the path is ephemeral scratch or under the session scratchpad.
+    """
+    if is_ephemeral_script_path(file_path):
+        return True
+    return is_under_session_scratchpad(file_path, hook_payload or {})
 
 
 def is_migration_file(file_path: str) -> bool:

package/hooks/blocking/config/CLAUDE.md

@@ -12,6 +12,8 @@ A Python package that holds shared constants for the verified-commit gate family
 |---|---|
 | `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
 | `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
+| `verified_commit_context_constants.py` | `VERIFY_SKIP_ADDITIONAL_CONTEXT`, the ``# verify-skip`` usage rule the gate attaches to a deny payload's `additionalContext` |
+| `verified_commit_gate_output_constants.py` | `PRE_TOOL_USE_HOOK_EVENT_NAME` and `DENY_PERMISSION_DECISION` (the deny payload's event name and decision string), `GATE_HOOK_MODULE_NAME` (the gate's own module name for block logging), and `REGEX_ALTERNATION_SEPARATOR` (the `\|` join for the directory-change verb alternation in `gated_invocations.py`) |
 
 ## Key constants in `verified_commit_constants.py`
 

package/hooks/blocking/config/verified_commit_constants.py

@@ -131,7 +131,14 @@ CORRECTIVE_MESSAGE = (
     "and recorded baselines; when it finishes with a clean verdict the "
     "SubagentStop hook mints the verdict and this command will pass. Any "
     "file change after verification invalidates the verdict, so verify "
-    "last. Exempt automatically: docs/image files, pytest test files, and "
+    "last. The verdict binds to the exact surface content (every changed "
+    "and untracked file's bytes), not to a work-tree path, so a commit "
+    "from a different work tree passes only when its surface is "
+    "byte-identical; a work tree carrying any extra or later edit has a "
+    "surface no verdict covers. To land this change, run this command "
+    "from the work tree that holds the verified surface, or verify this "
+    "surface here. Exempt automatically: docs/image files, pytest test "
+    "files, and "
     "Python files whose docstring- and comment-stripped AST is unchanged "
     "(comment-only edits in non-Python files are not exempt)."
 )

package/hooks/blocking/config/verified_commit_context_constants.py

@@ -0,0 +1,21 @@
+"""The additionalContext text the verified-commit gate attaches to a deny.
+
+The gate injects this next to the blocked tool result so the agent learns,
+at the moment of the block, when the '# verify-skip' marker is legitimate
+and when a fresh verification is required instead.
+"""
+
+VERIFY_SKIP_ADDITIONAL_CONTEXT = (
+    "The verified-commit gate honors a one-command escape hatch: appending the "
+    "marker '# verify-skip' as a trailing shell comment (outside every quoted "
+    "region) to the blocked command bypasses the gate for that command only. "
+    "It is allowed only when the branch surface is the "
+    "same code a code-verifier already passed clean and the gate is "
+    "blocking on a verdict that does not cover it (an unminted verdict, "
+    "staging churn, or a reverted concurrent write) — confirm the verified "
+    "suite still passes and the diff holds nothing beyond the clean verdict "
+    "before using it. Any real code change since that clean verdict, a "
+    "first verification, or unrepaired findings all require a fresh "
+    "verification by the code-verifier agent instead. Full rule: "
+    "~/.claude/rules/verified-commit-gate-skip.md."
+)

package/hooks/blocking/config/verified_commit_gate_output_constants.py

@@ -0,0 +1,14 @@
+"""Output-shape constants for the verified-commit gate's deny payload.
+
+Shared by ``verified_commit_gate.py`` and its ``verified_commit_gate_parts``
+package so the PreToolUse event name, the deny decision string, the hook's
+own module name for block logging, and the regex-alternation join separator
+live in one place.
+"""
+
+from __future__ import annotations
+
+PRE_TOOL_USE_HOOK_EVENT_NAME = "PreToolUse"
+DENY_PERMISSION_DECISION = "deny"
+GATE_HOOK_MODULE_NAME = "verified_commit_gate.py"
+REGEX_ALTERNATION_SEPARATOR = "|"