claude-dev-env 1.62.1 → 1.63.0

package/agents/code-advisor.md

@@ -0,0 +1,22 @@
+---
+name: code-advisor
+description: Mid-run advisor for executor agents. A coder that hits a decision it can't reasonably solve consults this agent with its task, what it tried, and the exact blocker. Returns a plan, a correction, or a stop signal — guidance only. Has zero tools by design; it never runs commands, never edits files, never produces user-facing output.
+tools: []
+model: inherit
+color: purple
+---
+
+You are the advisor in an executor/advisor pair (Anthropic's advisor strategy: https://claude.com/blog/the-advisor-strategy). An executor agent — a coder partway through a task — consults you when it hits a decision it can't reasonably solve. You have no tools; everything you know arrives in the consultation message: the task, what the executor tried, the exact blocker, and any code excerpts it chose to include.
+
+Reply with exactly one of three signals, named on the first line:
+
+- **PLAN** — the blocker needs a different approach. Give concrete ordered steps the executor can run with its own tools. Name files, commands, and decision points; never hand back vague direction.
+- **CORRECTION** — the executor's approach is right but one thing is wrong. Name the wrong assumption or step and the precise fix.
+- **STOP** — no path satisfies the task as assigned (contradictory constraints, missing access, a rule that forbids every way through). Say why in one or two sentences so the executor can report it upward.
+
+Rules:
+
+- Guidance only. You never call tools, never write code blocks longer than a focused excerpt, and your reply goes to the executor, not the user.
+- Reason from what the executor sent. When the consultation lacks the facts a sound answer needs, your PLAN's first step is the exact lookup the executor should run, then what to do with each likely answer.
+- Keep replies short. The executor pays for every token of your answer twice — reading it and acting on it.
+- Never invent repository facts. Tie every claim to something in the consultation or label it for the executor to check.

package/agents/code-verifier.md

@@ -0,0 +1,42 @@
+---
+name: code-verifier
+description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
+tools: Read, Grep, Glob, Bash
+model: inherit
+color: orange
+---
+
+You are the verifier in a two-phase code workflow: coder agents wrote changes, and you grade the result on its own terms (Claude Code best practices, fresh-context review: https://code.claude.com/docs/en/best-practices). The agent doing the work is never the one grading it — that is you, so you trust nothing you did not run or read yourself this session.
+
+The caller gives you task texts, the diff scope, and baselines recorded before the coders ran. Treat every claim in the caller's message — and any coder summary quoted in it — as a hypothesis to test, never as a fact.
+
+Run all three layers, in this order:
+
+1. **Runnable gates.** Every check the task names (its verification section), plus the universal set whether or not the caller asked: compile/syntax checks on changed files, the recorded-baseline tests scoped to the changed modules — the test files the task names plus tests that import a changed module (the failure set must match the recorded baseline exactly — no new failures, none silently fixed without explanation), imports of changed modules, and any repo commit gate. Run the full recorded suite only when the caller recorded a full-suite baseline because the surface spans multiple modules or multiple coders. Run each command yourself and keep its output.
+2. **Two-way diff-vs-task reading.** Read each coder's diff against that coder's task text. Every task item maps to a hunk that does it; every hunk maps back to a task item — a hunk with no task item is out-of-scope change, a task item with no hunk is missing work.
+3. **Negative space.** Walk the task's item list asking "where is this one?": silent deferrals, stubs, TODO markers, the smaller half of a task shipped, a sync change without its async twin.
+
+Findings discipline:
+
+- A finding must cite a failing command (with its output) or a named task item. No citation, no finding.
+- Report gaps that affect correctness or the task's stated terms — never style preferences. Sound work produces zero findings; do not invent gaps to look thorough.
+- Never edit a file. You verify; repair agents repair.
+- Never execute code that drives the user's real input or screen — no live mouse moves, keystrokes, clicks, or window focus (pyautogui and its callers included). Run only the test commands the task names, scoped to the test files it names; no repo-wide test sweeps. Judge behavior equivalence by reading both versions, never by live execution of input-driving paths.
+
+Before you write the verdict, learn the surface hash of the work tree you verified. Use the branch mode — it resolves the work tree that holds the branch automatically, so it is immune to your own cwd:
+
+    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash-for-branch <branch under review>
+
+On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verification_verdict_store.py; invoke it with the python on your PATH. If the caller named an explicit work-tree path rather than a branch, use the explicit-directory mode instead:
+
+    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash <explicit-work-tree-dir>
+
+The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
+
+End your final message with exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
+
+```verdict
+{"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
+```
+
+Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Any file change after you finish moves that hash and invalidates the verdict, so you are the last step before the commit.

package/bin/install.mjs

@@ -149,7 +149,7 @@ const INSTALL_GROUPS = {
         skills: [
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
-            'recall', 'remember', 'task-build'
+            'recall', 'remember', 'task-build', 'verified-build'
         ],
         includeDirectories: ['rules', 'docs', 'commands', 'agents', 'audit-rubrics'],
         includeAllHooks: true,

package/hooks/blocking/config/verified_commit_constants.py

@@ -48,6 +48,7 @@ WRITE_CALL_REGION_PATTERN = (
 VERDICT_KEY_ALL_PASS = "all_pass"
 VERDICT_KEY_MANIFEST_SHA256 = "manifest_sha256"
 VERDICT_KEY_FINDINGS = "findings"
+VERDICT_FILE_GLOB = "*.json"
 SUBAGENTS_DIRECTORY_NAME = "subagents"
 AGENT_TRANSCRIPT_GLOB = "agent-*.jsonl"
 AGENT_META_SIDECAR_SUFFIX = ".meta.json"
@@ -61,6 +62,21 @@ TRANSCRIPT_TEXT_CONTENT_TYPE = "text"
 TRANSCRIPT_TEXT_KEY = "text"
 VERDICT_FENCE_PATTERN = r"```verdict\s*\n(.*?)```"
 MANIFEST_HASH_CLI_FLAG = "--manifest-hash"
+MANIFEST_HASH_FOR_BRANCH_CLI_FLAG = "--manifest-hash-for-branch"
+WORKTREE_LIST_PATH_PREFIX = "worktree "
+WORKTREE_LIST_BRANCH_PREFIX = "branch "
+BRANCH_REFERENCE_PREFIX = "refs/heads/"
+EMPTY_SURFACE_GUARD_MESSAGE = (
+    "ERROR: The work tree at {repo_root} has no changed or untracked files "
+    "versus origin/main (empty change surface). This work tree holds nothing "
+    "to verify — you are pointed at the wrong work tree. Run `git worktree list` "
+    "to see all checked-out work trees and target the one on the branch under review."
+)
+BRANCH_WORKTREE_ABSENT_MESSAGE = (
+    "ERROR: No work tree has branch '{branch}' checked out. "
+    "Check it out in a work tree first: "
+    "`git worktree add <path> <branch>` or `git checkout <branch>`."
+)
 DOCS_ONLY_EXTENSIONS = frozenset(
     {".md", ".txt", ".rst", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"}
 )

package/hooks/blocking/test_verification_verdict_store.py

@@ -11,6 +11,8 @@ import pathlib
 import subprocess
 import sys
 
+import pytest
+
 _HOOK_DIR = pathlib.Path(__file__).parent
 if str(_HOOK_DIR) not in sys.path:
     sys.path.insert(0, str(_HOOK_DIR))
@@ -28,6 +30,10 @@ resolve_merge_base = store_module.resolve_merge_base
 branch_surface_manifest = store_module.branch_surface_manifest
 manifest_sha256 = store_module.manifest_sha256
 workflow_verdict_covers_surface = store_module.workflow_verdict_covers_surface
+minted_verdict_covers_surface = store_module.minted_verdict_covers_surface
+write_verdict = store_module.write_verdict
+worktree_path_for_branch = store_module.worktree_path_for_branch
+empty_surface_hash = store_module.empty_surface_hash
 
 constants_spec = importlib.util.spec_from_file_location(
     "verified_commit_constants",
@@ -38,6 +44,8 @@ assert constants_spec.loader is not None
 constants_module = importlib.util.module_from_spec(constants_spec)
 constants_spec.loader.exec_module(constants_module)
 CORRECTIVE_MESSAGE = constants_module.CORRECTIVE_MESSAGE
+EMPTY_SURFACE_GUARD_MESSAGE = constants_module.EMPTY_SURFACE_GUARD_MESSAGE
+BRANCH_WORKTREE_ABSENT_MESSAGE = constants_module.BRANCH_WORKTREE_ABSENT_MESSAGE
 
 PRODUCTION_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
 TEST_SOURCE = "def test_add() -> None:\n    assert 1 + 1 == 2\n"
@@ -488,3 +496,227 @@ def test_manifest_hash_cli_prints_live_surface_hash(tmp_path: pathlib.Path) -> N
         text=True,
     )
     assert completed_process.stdout.strip() == expected_hash
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: pathlib.Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def test_minted_verdict_covers_surface_matches_other_worktree_by_hash(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    write_verdict(
+        str(tmp_path / "other" / "worktree"),
+        MATCHING_MANIFEST_SHA256,
+        True,
+        [],
+        "agent-x",
+    )
+    assert minted_verdict_covers_surface(MATCHING_MANIFEST_SHA256) is True
+
+
+def test_minted_verdict_covers_surface_false_for_other_hash(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    write_verdict(
+        str(tmp_path / "other" / "worktree"),
+        OTHER_MANIFEST_SHA256,
+        True,
+        [],
+        "agent-x",
+    )
+    assert minted_verdict_covers_surface(MATCHING_MANIFEST_SHA256) is False
+
+
+def test_minted_verdict_covers_surface_false_for_failing_verdict(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    write_verdict(
+        str(tmp_path / "other" / "worktree"),
+        MATCHING_MANIFEST_SHA256,
+        False,
+        [{"severity": "P0", "summary": "boom"}],
+        "agent-x",
+    )
+    assert minted_verdict_covers_surface(MATCHING_MANIFEST_SHA256) is False
+
+
+def test_minted_verdict_covers_surface_false_when_directory_absent(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    assert minted_verdict_covers_surface(MATCHING_MANIFEST_SHA256) is False
+
+
+def _make_repo_with_branch_worktree(
+    tmp_path: pathlib.Path, branch_name: str
+) -> tuple[pathlib.Path, pathlib.Path]:
+    """Create a repo with a branch checked out in a separate worktree.
+
+    Returns:
+        A tuple of (main worktree path, branch worktree path).
+    """
+    empty_hooks_dir = tmp_path / "nohooks"
+    empty_hooks_dir.mkdir()
+
+    main_dir = tmp_path / "main"
+    main_dir.mkdir()
+    _run_git(main_dir, "init", "--initial-branch=main")
+    _run_git(main_dir, "config", "user.email", "tests@example.com")
+    _run_git(main_dir, "config", "user.name", "Worktree Tests")
+    _run_git(main_dir, "config", "core.hooksPath", str(empty_hooks_dir))
+    (main_dir / "app.py").write_text(PRODUCTION_SOURCE, encoding="utf-8")
+    _run_git(main_dir, "add", "-A")
+    _run_git(main_dir, "commit", "-m", "base")
+
+    origin_dir = tmp_path / "origin.git"
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    _run_git(main_dir, "remote", "add", "origin", str(origin_dir))
+    _run_git(main_dir, "push", "-u", "origin", "main")
+
+    _run_git(main_dir, "branch", branch_name)
+
+    branch_worktree_dir = tmp_path / "branch-worktree"
+    _run_git(main_dir, "worktree", "add", str(branch_worktree_dir), branch_name)
+
+    return main_dir, branch_worktree_dir
+
+
+def test_worktree_path_for_branch_returns_path_when_branch_present(
+    tmp_path: pathlib.Path,
+) -> None:
+    _main_dir, branch_worktree_dir = _make_repo_with_branch_worktree(
+        tmp_path, "feature-x"
+    )
+    resolved_path = worktree_path_for_branch(str(branch_worktree_dir), "feature-x")
+    assert resolved_path is not None
+    assert pathlib.Path(resolved_path).resolve() == branch_worktree_dir.resolve()
+
+
+def test_worktree_path_for_branch_returns_none_when_branch_absent(
+    tmp_path: pathlib.Path,
+) -> None:
+    main_dir, _branch_worktree_dir = _make_repo_with_branch_worktree(
+        tmp_path, "feature-x"
+    )
+    resolved_path = worktree_path_for_branch(str(main_dir), "branch-never-checked-out")
+    assert resolved_path is None
+
+
+def test_empty_surface_hash_equals_hash_of_empty_string() -> None:
+    assert empty_surface_hash() == manifest_sha256("")
+
+
+def test_manifest_hash_cli_empty_surface_writes_guard_message_to_stderr(
+    tmp_path: pathlib.Path,
+) -> None:
+    work_dir = _make_repo_with_origin(tmp_path)
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(_HOOK_DIR / "verification_verdict_store.py"),
+            "--manifest-hash",
+            str(work_dir),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.returncode != 0
+    assert completed_process.stdout.strip() == ""
+    lowered_stderr = completed_process.stderr.lower()
+    assert "wrong work tree" in lowered_stderr or "empty" in lowered_stderr
+
+
+def test_manifest_hash_cli_empty_surface_prints_nothing_on_stdout(
+    tmp_path: pathlib.Path,
+) -> None:
+    work_dir = _make_repo_with_origin(tmp_path)
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(_HOOK_DIR / "verification_verdict_store.py"),
+            "--manifest-hash",
+            str(work_dir),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert completed_process.stdout.strip() == ""
+
+
+def test_manifest_hash_for_branch_cli_prints_same_hash_as_explicit_dir(
+    tmp_path: pathlib.Path,
+) -> None:
+    _main_dir, branch_worktree_dir = _make_repo_with_branch_worktree(
+        tmp_path, "feature-branch"
+    )
+    (branch_worktree_dir / "app.py").write_text(
+        "def add(left: int, right: int) -> int:\n    return left - right\n",
+        encoding="utf-8",
+    )
+    direct_process = subprocess.run(
+        [
+            sys.executable,
+            str(_HOOK_DIR / "verification_verdict_store.py"),
+            "--manifest-hash",
+            str(branch_worktree_dir),
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    branch_process = subprocess.run(
+        [
+            sys.executable,
+            str(_HOOK_DIR / "verification_verdict_store.py"),
+            "--manifest-hash-for-branch",
+            "feature-branch",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+        cwd=str(branch_worktree_dir),
+    )
+    assert direct_process.stdout.strip() == branch_process.stdout.strip()
+    assert direct_process.stdout.strip() != ""
+
+
+def test_manifest_hash_for_branch_cli_returns_nonzero_when_branch_absent(
+    tmp_path: pathlib.Path,
+) -> None:
+    main_dir, _branch_worktree_dir = _make_repo_with_branch_worktree(
+        tmp_path, "feature-branch"
+    )
+    completed_process = subprocess.run(
+        [
+            sys.executable,
+            str(_HOOK_DIR / "verification_verdict_store.py"),
+            "--manifest-hash-for-branch",
+            "branch-never-checked-out",
+        ],
+        capture_output=True,
+        text=True,
+        cwd=str(main_dir),
+    )
+    assert completed_process.returncode != 0
+    assert completed_process.stdout.strip() == ""

package/hooks/blocking/test_verified_commit_gate.py

@@ -525,3 +525,46 @@ def test_verification_bypass_marker_allows_an_otherwise_gated_commit(
     assert "VERIFIED_COMMIT_GATE" in capsys.readouterr().out
     _run_gate_main(monkeypatch, "git commit -m x # verify-skip", work_dir)
     assert capsys.readouterr().out == ""
+
+
+def test_minted_verdict_from_other_worktree_allows_commit_by_hash(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    live_surface_hash = _live_surface_hash(work_dir)
+    store_module.write_verdict(
+        str(tmp_path / "sibling" / "worktree"),
+        live_surface_hash,
+        True,
+        [],
+        "agent-x",
+    )
+    transcript_path = tmp_path / "projects" / "demo" / "sess1.jsonl"
+    transcript_path.parent.mkdir(parents=True)
+    transcript_path.write_text("", encoding="utf-8")
+    assert deny_reason_for_directory(str(work_dir), str(transcript_path)) is None
+
+
+def test_minted_verdict_from_other_worktree_with_wrong_hash_denies(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    store_module.write_verdict(
+        str(tmp_path / "sibling" / "worktree"),
+        "d" * 64,
+        True,
+        [],
+        "agent-x",
+    )
+    transcript_path = tmp_path / "projects" / "demo" / "sess1.jsonl"
+    transcript_path.parent.mkdir(parents=True)
+    transcript_path.write_text("", encoding="utf-8")
+    deny_reason = deny_reason_for_directory(str(work_dir), str(transcript_path))
+    assert deny_reason is not None
+    assert "VERIFIED_COMMIT_GATE" in deny_reason

package/hooks/blocking/test_verifier_verdict_minter.py

@@ -37,6 +37,16 @@ minter_spec.loader.exec_module(minter_module)
 mint_for_payload = minter_module.mint_for_payload
 resolved_subagent_type = minter_module.resolved_subagent_type
 
+store_spec = importlib.util.spec_from_file_location(
+    "verification_verdict_store",
+    _HOOK_DIR / "verification_verdict_store.py",
+)
+assert store_spec is not None
+assert store_spec.loader is not None
+store_module = importlib.util.module_from_spec(store_spec)
+store_spec.loader.exec_module(store_module)
+empty_surface_hash = store_module.empty_surface_hash
+
 constants_spec = importlib.util.spec_from_file_location(
     "verified_commit_constants",
     _HOOK_DIR / "config" / "verified_commit_constants.py",
@@ -191,3 +201,132 @@ def test_settings_deny_verdict_directory_write() -> None:
 
 def test_settings_deny_verdict_directory_edit() -> None:
     assert "Edit($HOME/.claude/verification/**)" in _deny_rules()
+
+
+def test_minter_refuses_when_attested_hash_equals_empty_surface_hash(
+    tmp_path: pathlib.Path,
+) -> None:
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    _init_repo_with_upstream_and_edit(repo_root)
+    attested_empty = empty_surface_hash()
+    verdict_fence = json.dumps(
+        {"all_pass": True, "findings": [], "manifest_sha256": attested_empty}
+    )
+    agent_transcript = tmp_path / "agent-7.jsonl"
+    agent_transcript.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
+                        }
+                    ]
+                },
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
+    payload = {
+        "agent_transcript_path": str(agent_transcript),
+        "cwd": str(repo_root),
+        "agent_id": "empty-surface-1",
+    }
+    assert mint_for_payload(payload) is None
+
+
+def test_minter_refuses_when_recomputed_surface_is_empty(
+    tmp_path: pathlib.Path,
+) -> None:
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    subprocess.run(["git", "-C", str(repo_root), "init", "-q"], check=True)
+    subprocess.run(
+        ["git", "-C", str(repo_root), "config", "user.email", "verifier@test"],
+        check=True,
+    )
+    subprocess.run(
+        ["git", "-C", str(repo_root), "config", "user.name", "verifier"],
+        check=True,
+    )
+    (repo_root / "module.py").write_text("answer = 1\n", encoding="utf-8")
+    subprocess.run(["git", "-C", str(repo_root), "add", "-A"], check=True)
+    subprocess.run(
+        ["git", "-C", str(repo_root), "commit", "-qm", "init"], check=True
+    )
+    subprocess.run(
+        ["git", "-C", str(repo_root), "branch", "-f", "origin/main", "HEAD"],
+        check=True,
+    )
+    agent_transcript = tmp_path / "agent-7.jsonl"
+    agent_transcript.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
+                        }
+                    ]
+                },
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
+    payload = {
+        "agent_transcript_path": str(agent_transcript),
+        "cwd": str(repo_root),
+        "agent_id": "empty-recompute-1",
+    }
+    assert mint_for_payload(payload) is None
+
+
+def test_attested_manifest_hash_binds_over_cwd_surface(tmp_path: pathlib.Path) -> None:
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    _init_repo_with_upstream_and_edit(repo_root)
+    attested_hash = "c" * 64
+    agent_transcript = tmp_path / "agent-7.jsonl"
+    verdict_fence = json.dumps(
+        {"all_pass": True, "findings": [], "manifest_sha256": attested_hash}
+    )
+    agent_transcript.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
+                        }
+                    ]
+                },
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
+    payload = {
+        "agent_transcript_path": str(agent_transcript),
+        "cwd": str(repo_root),
+        "agent_id": "attest-1",
+    }
+    verdict_path = mint_for_payload(payload)
+    try:
+        assert verdict_path is not None
+        verdict_record = json.loads(verdict_path.read_text(encoding="utf-8"))
+        assert verdict_record["manifest_sha256"] == attested_hash
+    finally:
+        if verdict_path is not None and verdict_path.exists():
+            verdict_path.unlink()

package/hooks/blocking/verification_verdict_store.py

@@ -29,12 +29,16 @@ from config.verified_commit_constants import (
     AGENT_META_SIDECAR_SUFFIX,
     AGENT_META_TYPE_KEY,
     AGENT_TRANSCRIPT_GLOB,
+    BRANCH_REFERENCE_PREFIX,
+    BRANCH_WORKTREE_ABSENT_MESSAGE,
     CLAUDE_HOME_DIRECTORY_NAME,
     CONFTEST_FILE_NAME,
     DOCS_ONLY_EXTENSIONS,
     ALL_FALLBACK_BASE_REFERENCES,
+    EMPTY_SURFACE_GUARD_MESSAGE,
     GIT_TIMEOUT_SECONDS,
     MANIFEST_HASH_CLI_FLAG,
+    MANIFEST_HASH_FOR_BRANCH_CLI_FLAG,
     MINIMUM_STATUS_FIELD_COUNT,
     MINTING_AGENT_TYPE,
     PYTHON_EXTENSION,
@@ -52,10 +56,13 @@ from config.verified_commit_constants import (
     TRANSCRIPT_TEXT_KEY,
     VERDICT_DIRECTORY_NAME,
     VERDICT_FENCE_PATTERN,
+    VERDICT_FILE_GLOB,
     VERDICT_JSON_INDENT,
     VERDICT_KEY_ALL_PASS,
     VERDICT_KEY_FINDINGS,
     VERDICT_KEY_MANIFEST_SHA256,
+    WORKTREE_LIST_BRANCH_PREFIX,
+    WORKTREE_LIST_PATH_PREFIX,
 )
 
 
@@ -243,6 +250,65 @@ def manifest_sha256(surface_manifest_text: str) -> str:
     return hashlib.sha256(surface_manifest_text.encode("utf-8")).hexdigest()
 
 
+def empty_surface_hash() -> str:
+    """Return the manifest hash that represents an empty change surface.
+
+    A work tree whose HEAD equals the merge base has no changed or untracked
+    files, so ``branch_surface_manifest`` returns ``""`` and this hash is what
+    the minter or store CLI would produce for it. Comparing an attested hash
+    against this value lets the minter refuse to mint for a verifier that ran
+    in the wrong work tree.
+
+    Returns:
+        The hex sha256 digest of the empty surface manifest (the empty string).
+    """
+    return manifest_sha256("")
+
+
+def worktree_path_for_branch(repo_directory: str, branch_name: str) -> str | None:
+    """Find the work-tree directory that has a given branch checked out.
+
+    Parses the porcelain output of ``git worktree list --porcelain`` and
+    returns the ``worktree <path>`` line whose block carries a
+    ``branch refs/heads/<branch_name>`` line. Returns None when git fails
+    or no work tree holds the branch.
+
+    Args:
+        repo_directory: Any directory inside the repository.
+        branch_name: The short branch name to locate (without ``refs/heads/``).
+
+    Returns:
+        The absolute path of the work tree that has the branch checked out,
+        or None when no work tree holds the branch or git fails.
+    """
+    porcelain_output = run_git(repo_directory, "worktree", "list", "--porcelain")
+    if porcelain_output is None:
+        return None
+    target_branch_reference = f"{BRANCH_REFERENCE_PREFIX}{branch_name}"
+    current_worktree_path: str | None = None
+    for each_line in porcelain_output.splitlines():
+        if each_line.startswith(WORKTREE_LIST_PATH_PREFIX):
+            current_worktree_path = each_line[len(WORKTREE_LIST_PATH_PREFIX):]
+        elif each_line.startswith(WORKTREE_LIST_BRANCH_PREFIX):
+            branch_reference = each_line[len(WORKTREE_LIST_BRANCH_PREFIX):]
+            if branch_reference == target_branch_reference and current_worktree_path:
+                return current_worktree_path
+    return None
+
+
+def verdict_directory() -> Path:
+    """Return the shared directory holding every work tree's verdict file.
+
+    Verdicts live outside any repository (under the user's Claude home) so no
+    repo accumulates untracked verdict files; every work tree's verdict shares
+    this one directory, distinguished by file name.
+
+    Returns:
+        The verdict directory under the user's Claude home.
+    """
+    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME / VERDICT_DIRECTORY_NAME
+
+
 def verdict_path_for_repo(repo_root: str) -> Path:
     """Derive the verdict file path for a repository work tree.
 
@@ -258,9 +324,7 @@ def verdict_path_for_repo(repo_root: str) -> Path:
     """
     normalized_root = str(Path(repo_root).resolve()).replace("\\", "/").lower()
     root_key = hashlib.sha256(normalized_root.encode("utf-8")).hexdigest()[:ROOT_KEY_HEX_LENGTH]
-    return (
-        Path.home() / CLAUDE_HOME_DIRECTORY_NAME / VERDICT_DIRECTORY_NAME / f"{root_key}.json"
-    )
+    return verdict_directory() / f"{root_key}.json"
 
 
 def load_valid_verdict(repo_root: str, expected_manifest_sha256: str) -> dict | None:
@@ -289,6 +353,44 @@ def load_valid_verdict(repo_root: str, expected_manifest_sha256: str) -> dict |
     return verdict_record
 
 
+def minted_verdict_covers_surface(expected_manifest_sha256: str) -> bool:
+    """Decide whether any minted verdict covers the live surface, keyed by hash.
+
+    A verdict's bound ``manifest_sha256`` commits to the exact set of surface
+    file paths and their byte contents; the work tree's location never enters
+    the hash. A clean verdict minted while verifying one work tree therefore
+    proves the same change surface in a sibling work tree of the same branch,
+    even though each work tree files its verdict under its own path-keyed name.
+    Scanning every verdict file by bound hash lets that verdict clear the
+    sibling's commit, while a verdict bound to a different hash — different
+    code — never matches. The path-keyed ``load_valid_verdict`` stays the fast
+    same-work-tree lookup; this is the cross-work-tree fallback.
+
+    Args:
+        expected_manifest_sha256: Hash of the live surface manifest the verdict
+            must match exactly.
+
+    Returns:
+        True as soon as one verdict file reports ``all_pass`` true and binds to
+        the expected hash; False when none match or the directory is absent.
+    """
+    verdict_dir = verdict_directory()
+    if not verdict_dir.is_dir():
+        return False
+    for each_verdict_file in sorted(verdict_dir.glob(VERDICT_FILE_GLOB)):
+        try:
+            verdict_record = json.loads(each_verdict_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(verdict_record, dict):
+            continue
+        if verdict_record.get(VERDICT_KEY_ALL_PASS) is not True:
+            continue
+        if verdict_record.get(VERDICT_KEY_MANIFEST_SHA256) == expected_manifest_sha256:
+            return True
+    return False
+
+
 def _subagents_directory_for_transcript(transcript_path: str) -> Path | None:
     """Locate the live session's subagents directory from a transcript path.
 
@@ -647,14 +749,18 @@ def _print_live_manifest_hash(repo_directory: str) -> int:
     """Print the live surface manifest hash for a repo, for a workflow verifier.
 
     A workflow code-verifier runs this to learn the exact hash to bind its
-    verdict to, so stdout carries only the hash and nothing else.
+    verdict to, so stdout carries only the hash and nothing else. When the
+    work tree has no changed or untracked files (empty change surface), this
+    prints the empty-surface guard message to stderr and returns nonzero —
+    an empty surface means the verifier is pointed at the wrong work tree.
 
     Args:
         repo_directory: A directory inside the work tree to bind the verdict to.
 
     Returns:
-        0 after printing the hash; nonzero with no stdout when the repo root or
-        merge base cannot be resolved.
+        0 after printing the hash; nonzero with no stdout when the repo root,
+        merge base, or manifest cannot be resolved, or when the change surface
+        is empty (wrong work tree).
     """
     repo_root = resolve_repo_root(repo_directory)
     if repo_root is None:
@@ -665,20 +771,69 @@ def _print_live_manifest_hash(repo_directory: str) -> int:
     surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
     if surface_manifest_text is None:
         return 1
+    if surface_manifest_text == "":
+        print(EMPTY_SURFACE_GUARD_MESSAGE.format(repo_root=repo_root), file=sys.stderr)
+        return 1
     print(manifest_sha256(surface_manifest_text))
     return 0
 
 
+def _print_branch_manifest_hash(branch_name: str) -> int:
+    """Print the manifest hash for the work tree that holds a given branch.
+
+    Resolves the repository root from the current working directory, then
+    finds the work tree that has ``branch_name`` checked out, and delegates
+    to ``_print_live_manifest_hash`` for that work tree. This mode is immune
+    to the verifier's own cwd: it always hashes the work tree that holds the
+    branch under review, regardless of where the verifier itself is running.
+
+    Args:
+        branch_name: The short branch name to locate (without ``refs/heads/``).
+
+    Returns:
+        0 after printing the hash; nonzero with a stderr message when the
+        repo root cannot be resolved, no work tree holds the branch, or the
+        located work tree has an empty change surface.
+    """
+    repo_root = resolve_repo_root(str(Path.cwd()))
+    if repo_root is None:
+        print("ERROR: Current directory is not inside a git repository.", file=sys.stderr)
+        return 1
+    branch_worktree_path = worktree_path_for_branch(repo_root, branch_name)
+    if branch_worktree_path is None:
+        print(
+            BRANCH_WORKTREE_ABSENT_MESSAGE.format(branch=branch_name),
+            file=sys.stderr,
+        )
+        return 1
+    return _print_live_manifest_hash(branch_worktree_path)
+
+
 def main() -> None:
     """Run the verdict-store CLI: compute the live surface-manifest hash.
 
-    Reads ``--manifest-hash <repo_root>`` from argv and prints the live
-    ``manifest_sha256`` so a workflow code-verifier can bind its verdict to the
-    exact surface the gate checks. Exits nonzero with no stdout on any other
-    argument shape or when the surface cannot be resolved.
+    Two modes:
+
+    ``--manifest-hash <work-tree-dir>``
+        Print the live ``manifest_sha256`` for the given work tree directory
+        so a workflow code-verifier can bind its verdict to the exact surface
+        the gate checks. Fails with a stderr message when the change surface
+        is empty (wrong work tree).
+
+    ``--manifest-hash-for-branch <branch>``
+        Resolve the work tree that has ``<branch>`` checked out (via
+        ``git worktree list --porcelain``) and print its manifest hash.
+        Immune to the verifier's own cwd — always targets the branch's own
+        work tree. Fails when no work tree holds the branch or the surface
+        is empty.
+
+    Exits nonzero with no stdout on any other argument shape or when the
+    surface cannot be resolved.
     """
     if len(sys.argv) == 3 and sys.argv[1] == MANIFEST_HASH_CLI_FLAG:
         sys.exit(_print_live_manifest_hash(sys.argv[2]))
+    if len(sys.argv) == 3 and sys.argv[1] == MANIFEST_HASH_FOR_BRANCH_CLI_FLAG:
+        sys.exit(_print_branch_manifest_hash(sys.argv[2]))
     sys.exit(1)
 
 

package/hooks/blocking/verified_commit_gate.py

@@ -13,8 +13,11 @@ and allows the command only when one of these holds:
 - the surface is mechanically exempt (docs/images by extension, pytest
   test files by name convention, Python files whose docstring-stripped
   AST is unchanged), or
-- a verdict minted by ``verifier_verdict_minter.py`` reports ``all_pass``
-  and binds to the exact live manifest hash.
+- a passing verifier verdict binds to the exact live manifest hash —
+  matched by content hash, not by work-tree location, so a verdict
+  ``verifier_verdict_minter.py`` minted while verifying any work tree of
+  the surface clears the commit, as does one a workflow ``code-verifier``
+  emitted in its own transcript.
 
 The surface binds every changed and untracked file's content, so slicing
 work into small commits or staging files cannot move the hash, while any
@@ -57,6 +60,7 @@ from verification_verdict_store import (
     is_verification_exempt_diff,
     load_valid_verdict,
     manifest_sha256,
+    minted_verdict_covers_surface,
     resolve_merge_base,
     resolve_repo_root,
     workflow_verdict_covers_surface,
@@ -500,6 +504,8 @@ def deny_reason_for_directory(target_directory: str, transcript_path: str) -> st
     live_manifest_sha256 = manifest_sha256(surface_manifest_text)
     if load_valid_verdict(repo_root, live_manifest_sha256) is not None:
         return None
+    if minted_verdict_covers_surface(live_manifest_sha256):
+        return None
     if workflow_verdict_covers_surface(transcript_path, live_manifest_sha256):
         return None
     hash_preview = live_manifest_sha256[:HASH_PREVIEW_LENGTH]

package/hooks/blocking/verifier_verdict_minter.py

@@ -35,9 +35,13 @@ blocking_directory = str(Path(__file__).resolve().parent)
 if blocking_directory not in sys.path:
     sys.path.insert(0, blocking_directory)
 
-from config.verified_commit_constants import MINTING_AGENT_TYPE
+from config.verified_commit_constants import (
+    MINTING_AGENT_TYPE,
+    VERDICT_KEY_MANIFEST_SHA256,
+)
 from verification_verdict_store import (
     branch_surface_manifest,
+    empty_surface_hash,
     manifest_sha256,
     resolve_merge_base,
     resolve_repo_root,
@@ -169,6 +173,53 @@ def resolved_subagent_type(subagent_stop_payload: dict) -> str | None:
     )
 
 
+def _attested_or_recomputed_hash(verdict_record: dict, repo_root: str) -> str | None:
+    """Choose the surface hash the minted verdict binds to.
+
+    A code-verifier that verifies a work tree other than the stop event's cwd
+    attests the surface it checked by emitting ``manifest_sha256`` in its
+    verdict fence (computed against the verified work tree via the
+    ``--manifest-hash`` CLI). Binding the minted verdict to that attested hash
+    keeps the verdict tied to the code actually verified rather than the
+    subagent's cwd, so a verdict earned for one work tree clears a commit in a
+    sibling work tree of the same surface. When the fence attests no hash, the
+    minter recomputes one from the cwd work tree, which is correct whenever the
+    verifier ran in the work tree it verified.
+
+    Returns None (mints nothing) in two empty-surface cases:
+
+    - The attested hash equals ``empty_surface_hash()`` — the verifier called
+      the store CLI on a wrong (empty) work tree and the hash it got back
+      represents nothing.
+    - The recompute branch produces an empty manifest — the cwd work tree also
+      has no changed or untracked files versus the merge base.
+
+    Args:
+        verdict_record: The parsed verdict fence from the verifier transcript.
+        repo_root: The work-tree root resolved from the stop event's cwd, used
+            for the recompute fallback.
+
+    Returns:
+        The attested ``manifest_sha256`` when the fence carries a non-empty
+        string one that is not the empty-surface sentinel; the cwd work tree's
+        recomputed surface hash when the fence attests nothing and the surface
+        is non-empty; or None when the attested hash is the empty-surface
+        sentinel, the surface manifest is empty, or no upstream base resolves.
+    """
+    attested_manifest_sha256 = verdict_record.get(VERDICT_KEY_MANIFEST_SHA256)
+    if isinstance(attested_manifest_sha256, str) and attested_manifest_sha256:
+        if attested_manifest_sha256 == empty_surface_hash():
+            return None
+        return attested_manifest_sha256
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if not surface_manifest_text:
+        return None
+    return manifest_sha256(surface_manifest_text)
+
+
 def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
     """Mint a verdict file for a code-verifier stop event.
 
@@ -177,8 +228,10 @@ def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
 
     Returns:
         The verdict file path when minted; None when the payload is not a
-        code-verifier stop, the transcript holds no verdict, or the
-        session directory is not a work tree with an upstream base.
+        code-verifier stop, the transcript holds no verdict, the cwd is not a
+        work tree, or — for a verdict that attests no ``manifest_sha256`` of
+        its own — that work tree has no upstream base to recompute the surface
+        hash from.
     """
     if resolved_subagent_type(subagent_stop_payload) != MINTING_AGENT_TYPE:
         return None
@@ -191,15 +244,12 @@ def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
     repo_root = resolve_repo_root(subagent_stop_payload.get("cwd", "."))
     if repo_root is None:
         return None
-    merge_base_sha = resolve_merge_base(repo_root)
-    if merge_base_sha is None:
-        return None
-    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
-    if surface_manifest_text is None:
+    bound_manifest_sha256 = _attested_or_recomputed_hash(verdict_record, repo_root)
+    if bound_manifest_sha256 is None:
         return None
     return write_verdict(
         repo_root,
-        manifest_sha256(surface_manifest_text),
+        bound_manifest_sha256,
         verdict_record["all_pass"],
         verdict_record["findings"],
         str(subagent_stop_payload.get("agent_id", "")),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.62.1",
+    "version": "1.63.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/autoconverge/SKILL.md

@@ -34,7 +34,9 @@ PR's owner.
 
 1. **Enter a worktree.** Call `EnterWorktree` with no arguments before any
    `gh`, `git`, file read, or edit. `gh`/`git` Bash calls do not auto-isolate,
-   so this is mandatory. If it fails, report and stop.
+   so this is mandatory. If it fails, report and stop. A bare `EnterWorktree`
+   branches from `origin/main`; step 2 positions the worktree on the PR's head
+   ref, which the workflow needs.
 
 2. **Resolve PR scope.** When the user passed a PR URL or number, parse owner,
    repo, and number from it. Otherwise read the current branch's PR:
@@ -43,6 +45,18 @@ PR's owner.
    ready, mark it draft first (`gh pr ready <n> --repo <o>/<r> --undo`) so the
    loop owns the ready transition.
 
+   **Position the worktree on the PR branch.** The workflow reviews
+   `git diff origin/main...HEAD` against this worktree's local `HEAD` and pushes
+   each fix to the PR branch, so the worktree sits on the PR's head ref at the PR
+   HEAD before the workflow launches. A worktree fresh off `origin/main` has
+   `HEAD == origin/main`, shows an empty diff, and reports a false convergence
+   with zero findings. When a local worktree already tracks the PR branch, enter
+   that one by passing its path to `EnterWorktree`; otherwise put the entered
+   worktree on the branch with `gh pr checkout <number> --repo <owner>/<repo>`
+   (or `git fetch origin <headRefName>` then `git switch <headRefName>`). Confirm
+   before launching: `git rev-parse --abbrev-ref HEAD` equals the PR's head ref
+   and local `HEAD` equals the PR head SHA.
+
 3. **Verify the worktree is the PR's repo (strict pre-flight).** Run
    `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`.
    It confirms the working directory is a checkout of the PR's own repo and
@@ -56,6 +70,17 @@ PR's owner.
 4. **Grant project permissions.**
    `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
 
+   In auto-mode the classifier blocks this grant as an unrequested change to the
+   permission allowlist: the `/autoconverge` invocation alone does not meet its
+   bar for an explicitly requested permission change. When it is blocked, keep
+   the run alive — surface the grant to the user through `AskUserQuestion` with
+   the exact command and ask them to approve it or run it themselves with the `!`
+   prefix:
+   `! python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`.
+   Continue once the grant lands. A user who wants future runs to skip this
+   prompt can add a standing Bash permission allow-rule for that script in their
+   settings.
+
 ## Run the workflow
 
 Call the `Workflow` tool against the colocated script:

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -220,37 +220,61 @@ test('the fix flow spawns a code-verifier step between the edit step and the com
   );
 });
 
-function constantBody(constantName) {
-  const constantStart = convergeSource.indexOf(`const ${constantName} =`);
-  assert.notEqual(constantStart, -1, `expected ${constantName} to exist`);
-  const nextConstantStart = convergeSource.indexOf('\nconst ', constantStart + 1);
-  const constantEnd = nextConstantStart === -1 ? convergeSource.length : nextConstantStart;
-  return convergeSource.slice(constantStart, constantEnd);
-}
-
-test('the shared verdict-fence steps name the binding-hash command and the verdict fence', () => {
-  const fenceSteps = constantBody('VERDICT_FENCE_STEPS');
-  assert.match(fenceSteps, /--manifest-hash/, 'expected the binding-hash command to be named');
+test('the shared verdict-fence builder names the binding-hash command and the verdict fence', () => {
+  const fenceBuilder = lensPromptBody('buildVerdictFenceSteps');
   assert.match(
-    fenceSteps,
+    fenceBuilder,
+    /--manifest-hash-for-branch/,
+    'expected the binding-hash command to use --manifest-hash-for-branch (cwd-immune)',
+  );
+  assert.doesNotMatch(
+    fenceBuilder,
+    /--manifest-hash(?!-for-branch)/,
+    'expected the old --manifest-hash <REPO> form to be removed in favour of --manifest-hash-for-branch',
+  );
+  assert.match(
+    fenceBuilder,
     /verification_verdict_store\.py/,
     'expected the verdict-store script that computes the binding hash to be named',
   );
-  assert.match(fenceSteps, /```verdict/, 'expected the verdict fence to be specified');
-  assert.match(fenceSteps, /manifest_sha256/, 'expected the verdict fence to carry manifest_sha256');
+  assert.match(fenceBuilder, /```verdict/, 'expected the verdict fence to be specified');
+  assert.match(fenceBuilder, /manifest_sha256/, 'expected the verdict fence to carry manifest_sha256');
+  assert.match(
+    fenceBuilder,
+    /gh pr view/,
+    'expected buildVerdictFenceSteps to resolve the head branch via gh pr view (cwd-immune)',
+  );
+  assert.match(
+    fenceBuilder,
+    /headRefName/,
+    'expected buildVerdictFenceSteps to extract the headRefName from gh pr view output',
+  );
+});
+
+test('the verdict-fence binding does not self-resolve a cwd via git rev-parse for the manifest hash', () => {
+  const fenceBuilder = lensPromptBody('buildVerdictFenceSteps');
+  assert.doesNotMatch(
+    fenceBuilder,
+    /git rev-parse --show-toplevel/,
+    'expected the binding hash to be cwd-immune (no git rev-parse in the binding step)',
+  );
 });
 
-test('every verify step reuses the shared verdict-fence steps, uses code-verifier, and forbids edits', () => {
+test('every verify step calls buildVerdictFenceSteps, uses code-verifier, and forbids edits', () => {
   for (const verifyFunctionName of [
     'verifyFixesInWorkingTree',
     'verifyRepairChanges',
-    'verifyHardeningChanges',
   ]) {
     const verifyBody = lensPromptBody(verifyFunctionName);
     assert.match(
       verifyBody,
-      /VERDICT_FENCE_STEPS/,
-      `expected ${verifyFunctionName} to reuse the shared VERDICT_FENCE_STEPS`,
+      /buildVerdictFenceSteps\(/,
+      `expected ${verifyFunctionName} to call buildVerdictFenceSteps (cwd-immune branch binding)`,
+    );
+    assert.doesNotMatch(
+      verifyBody,
+      /VERDICT_FENCE_STEPS(?!\s*\))/,
+      `expected ${verifyFunctionName} not to reference the removed VERDICT_FENCE_STEPS constant`,
     );
     assert.match(
       verifyBody,
@@ -270,6 +294,46 @@ test('every verify step reuses the shared verdict-fence steps, uses code-verifie
   }
 });
 
+test('verifyHardeningChanges uses --manifest-hash-for-branch with the hardening branch, uses code-verifier, and forbids edits', () => {
+  const verifyBody = lensPromptBody('verifyHardeningChanges');
+  assert.match(
+    verifyBody,
+    /--manifest-hash-for-branch/,
+    'expected verifyHardeningChanges to bind by hardening branch (cwd-immune)',
+  );
+  assert.doesNotMatch(
+    verifyBody,
+    /--manifest-hash(?!-for-branch)/,
+    'expected verifyHardeningChanges not to use the old --manifest-hash <REPO> form',
+  );
+  assert.match(
+    verifyBody,
+    /agentType:\s*'code-verifier'/,
+    'expected verifyHardeningChanges to spawn the code-verifier agent type',
+  );
+  assert.doesNotMatch(
+    verifyBody,
+    /schema:/,
+    'expected verifyHardeningChanges to pass no schema so its verdict fence stays as assistant text',
+  );
+  assert.match(
+    verifyBody,
+    /do no edits|make no edits|not edit|no file edits/i,
+    'expected verifyHardeningChanges to be told to make no edits',
+  );
+});
+
+test('verifyFixesInWorkingTree and verifyRepairChanges pass input.owner, input.repo, input.prNumber to buildVerdictFenceSteps', () => {
+  for (const verifyFunctionName of ['verifyFixesInWorkingTree', 'verifyRepairChanges']) {
+    const verifyBody = lensPromptBody(verifyFunctionName);
+    assert.match(
+      verifyBody,
+      /buildVerdictFenceSteps\(input\.owner,\s*input\.repo,\s*input\.prNumber\)/,
+      `expected ${verifyFunctionName} to pass PR coordinates to buildVerdictFenceSteps`,
+    );
+  }
+});
+
 test('the commit step is instructed to make no further file edits', () => {
   const commitBody = lensPromptBody('commitVerifiedFixes');
   assert.match(

package/skills/autoconverge/workflow/converge.mjs

@@ -141,15 +141,33 @@ const STANDARDS_EDIT_SCHEMA = {
   required: ['issueUrl', 'hardeningRepoPath', 'hardeningBranch', 'hardeningEdited', 'summary'],
 }
 
-const VERDICT_FENCE_STEPS =
-  `Compute the binding hash for the live surface by running exactly:\n` +
-  `   "C:\\Python313\\python.exe" "<REPO>/packages/claude-dev-env/hooks/blocking/verification_verdict_store.py" --manifest-hash "<REPO>"\n` +
-  `   (substitute the REPO path you resolved). That prints a single 64-char hex hash on stdout — capture it.\n` +
-  `Then END your message with a fenced verdict block exactly in this shape, on its own, carrying that hash:\n` +
-  "   ```verdict\n" +
-  `   {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
-  "   ```\n" +
-  `   When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`
+/**
+ * Build the verdict-fence step instructions for a verify agent, binding the
+ * surface hash by branch name rather than by a self-resolved cwd. Resolving
+ * the branch via `gh pr view` is cwd-immune: it does not matter which worktree
+ * the verify agent runs in, so a launcher session whose cwd is a different
+ * worktree cannot poison the binding hash.
+ * @param {string} prOwner GitHub owner of the repo that holds the branch
+ * @param {string} prRepo GitHub repo name
+ * @param {number|string} prNumber PR number used to resolve the head branch
+ * @returns {string} binding-hash and verdict-fence instructions for a verify prompt
+ */
+function buildVerdictFenceSteps(prOwner, prRepo, prNumber) {
+  return (
+    `Compute the binding hash for the live surface:\n` +
+    `   a. Resolve the PR head branch (cwd-immune): run exactly\n` +
+    `         gh pr view ${prNumber} --repo ${prOwner}/${prRepo} --json headRefName -q .headRefName\n` +
+    `      Capture the branch name printed on stdout.\n` +
+    `   b. Run exactly:\n` +
+    `         "C:\\Python313\\python.exe" "<REPO>/packages/claude-dev-env/hooks/blocking/verification_verdict_store.py" --manifest-hash-for-branch "<that branch>"\n` +
+    `      (substitute the REPO path you resolved for the script path, and the branch name for <that branch>). That prints a single 64-char hex hash on stdout — capture it.\n` +
+    `Then END your message with a fenced verdict block exactly in this shape, on its own, carrying that hash:\n` +
+    "   ```verdict\n" +
+    `   {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
+    "   ```\n" +
+    `   When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`
+  )
+}
 
 const CONVERGENCE_SUMMARY_SCHEMA = {
   type: 'object',
@@ -713,9 +731,9 @@ function verifyFixesInWorkingTree(head, findings, sourceLabel) {
     `You are the VERIFY step for ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The edit step left fixes in the working tree, uncommitted. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
       `Findings the working-tree fixes must address:\n${findingsBlock}\n\n` +
       `Steps:\n` +
-      `1. Resolve the worktree repo root: REPO=$(git rev-parse --show-toplevel).\n` +
+      `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
       `2. Verify the uncommitted working-tree changes resolve every finding above: run the relevant tests and the named gates against the working tree. Read the diff (git diff) and confirm each finding is fixed test-first per CODE_RULES.\n` +
-      `3. ${VERDICT_FENCE_STEPS}`,
+      `3. ${buildVerdictFenceSteps(input.owner, input.repo, input.prNumber)}`,
     { label: `fix-verify:${sourceLabel}`, phase: 'Converge', agentType: 'code-verifier' },
   )
 }
@@ -935,9 +953,9 @@ function verifyRepairChanges(head, failures) {
     `You are the VERIFY step for the convergence repair on ${prCoordinates}, HEAD ${head}. The edit step left its repair in the working tree (a bot-thread fix uncommitted, and/or a rebase onto origin/main), unpushed. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
       `Concerns the working-tree repair must resolve (the gates the convergence check flagged):\n${failureBlock}\n\n` +
       `Steps:\n` +
-      `1. Resolve the worktree repo root: REPO=$(git rev-parse --show-toplevel).\n` +
+      `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
       `2. Verify the working tree against origin/main: any bot-thread code fix is correct test-first per CODE_RULES, and a rebase (if any) left a clean, conflict-free tree. Read the diff (git diff origin/main) and run the relevant tests and named gates.\n` +
-      `3. ${VERDICT_FENCE_STEPS}`,
+      `3. ${buildVerdictFenceSteps(input.owner, input.repo, input.prNumber)}`,
     { label: 'repair-verify', phase: 'Finalize', agentType: 'code-verifier' },
   )
 }
@@ -1044,22 +1062,32 @@ function standardsFollowUpEdit(head, findings, sourceLabel) {
 /**
  * Standards-hardening verify step: a code-verifier confirms the uncommitted
  * hooks/rules change staged in the hardening repo blocks the deferred violation
- * classes, computes the binding surface hash for that repo, and ends with a
- * verdict fence as plain assistant text (NO schema) — unlocking the
+ * classes, computes the binding surface hash for that repo by branch (cwd-immune),
+ * and ends with a verdict fence as plain assistant text (NO schema) — unlocking the
  * verified-commit gate for the cross-repo hardening commit. The verifier makes
  * no edits.
  * @param {string} hardeningRepoPath absolute path of the hardening repo checkout the edit staged
+ * @param {string} hardeningBranch the branch in the hardening repo that the edit staged the change on
  * @param {string} sourceLabel short description of where the findings came from
  * @returns {Promise<string>} the verifier transcript carrying the verdict fence
  */
-function verifyHardeningChanges(hardeningRepoPath, sourceLabel) {
+function verifyHardeningChanges(hardeningRepoPath, hardeningBranch, sourceLabel) {
   return convergeAgent(
     `You are the VERIFY step for an environment-hardening change (${sourceLabel}) staged in the working tree of ${hardeningRepoPath}. The edit step left the hooks/rules edits uncommitted there. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
       `Concern the working-tree change must resolve: the edited hooks/rules block the code-standard violation classes from the deferred round at Write/Edit time, and a hook change carries a passing test per CODE_RULES.\n\n` +
       `Steps:\n` +
       `1. cd into ${hardeningRepoPath}, then resolve its repo root: REPO=$(git rev-parse --show-toplevel).\n` +
       `2. Verify the uncommitted working-tree change in REPO: read the diff (git diff) and run the hook/rule tests in that repo, confirming each violation class is now blocked.\n` +
-      `3. ${VERDICT_FENCE_STEPS}`,
+      `3. Compute the binding hash for the live surface:\n` +
+      `   The hardening branch is: ${hardeningBranch}\n` +
+      `   Run exactly:\n` +
+      `      "C:\\Python313\\python.exe" "<REPO>/packages/claude-dev-env/hooks/blocking/verification_verdict_store.py" --manifest-hash-for-branch "${hardeningBranch}"\n` +
+      `   (substitute the REPO path you resolved for the script path). That prints a single 64-char hex hash on stdout — capture it.\n` +
+      `   Then END your message with a fenced verdict block exactly in this shape, on its own, carrying that hash:\n` +
+      "      ```verdict\n" +
+      `      {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
+      "      ```\n" +
+      `      When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`,
     { label: `standards-verify:${sourceLabel}`, phase: 'Converge', agentType: 'code-verifier' },
   )
 }
@@ -1123,7 +1151,7 @@ async function spawnStandardsFollowUp(head, findings, sourceLabel) {
   if (editResult?.hardeningEdited !== true || !editResult?.hardeningRepoPath) {
     return { hardeningPrOpened: false }
   }
-  const verifyTranscript = await verifyHardeningChanges(editResult.hardeningRepoPath, sourceLabel)
+  const verifyTranscript = await verifyHardeningChanges(editResult.hardeningRepoPath, editResult.hardeningBranch, sourceLabel)
   if (!verdictPassed(verifyTranscript)) {
     return { hardeningPrOpened: false }
   }

package/skills/verified-build/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: verified-build
+description: >-
+  Runs a code task through the two-phase verified workflow: scoped coder
+  agents write the changes (consulting the tool-less code-advisor when
+  stuck on a decision), then a fresh-context code-verifier agent re-derives
+  and runs every check itself. The verifier's fenced verdict is minted by
+  the verifier_verdict_minter hook and unlocks the verified_commit_gate for
+  git commit/push. Use for feature implementations, refactors, and bug
+  fixes that land behind verification. Triggers: 'verified build', 'run
+  this verified', 'two-phase build', 'build and verify', 'verified
+  implementation'.
+---
+
+# Verified Build
+
+Two phases, hook-enforced: coders write, a fresh-context verifier grades, and `git commit`/`git push` open only on a clean verdict bound to the live change surface.
+
+## Workflow
+
+Copy this checklist and check items off as you go:
+
+- [ ] **Record baselines.** Before any coder runs: the test command and its exact failure set, plus any other gates the repo names. Scope the test command to the modules the task touches (their test files plus tests importing the changed modules); record a full-suite baseline only when the assignments span multiple modules or multiple coders. The verifier compares against these.
+- [ ] **Scope assignments.** Split the task into file-disjoint assignments; write each as a task text with named checks.
+- [ ] **Spawn coders.** One agent per assignment (`clean-coder` or Sonnet). Tell each: on a decision it can't reasonably solve, consult the tool-less `code-advisor` agent — it returns a plan, a correction, or a stop signal — then resume.
+- [ ] **Settle the tree.** After coders finish: run formatters and any file-rewriting hooks, stage nothing, change nothing more.
+- [ ] **Spawn the verifier last.** Agent tool, `subagent_type: "code-verifier"`, with the task texts, the diff scope, and the recorded baselines. When it stops, the SubagentStop hook mints its verdict.
+- [ ] **Repair only reported findings.** On a failing verdict, spawn repair agents scoped to the findings, then re-spawn the verifier. Repeat until clean.
+- [ ] **Land right away.** One commit, push, draft PR — before anything else touches a file.
+
+## Gotchas
+
+- Any file change after the verifier stops moves the surface hash and re-locks the gate — formatter rewrites included. Settle the tree first; land right after the clean verdict.
+- The verdict covers the whole branch surface (merge base to work tree, untracked files included). There is no "verify just my part."
+- The verifier must end with a ```` ```verdict ```` fence. No fence means nothing is minted and the gate stays closed.
+- The minter keys on the agent type string `code-verifier` — spawning the same prompt under another agent type mints nothing.
+- A surface whose every change is a docs/image file (by extension), a Python file whose docstring-stripped AST is unchanged (docstring-, comment-, or formatting-only Python edits), or a pytest test file (`test_*.py`, `*_test.py`, `conftest.py`) is exempt automatically; skip the verifier for those. Comment-only edits in non-Python files are not exempt.
+- Record the test baseline before coders start. Without the exact pre-existing failure set, new breakage hides inside old noise.