claude-dev-env 2.2.1 → 2.4.0

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

@@ -31,7 +31,7 @@ def _load_revoke_module() -> ModuleType:
 
 def test_module_imports_constants_from_config_modules() -> None:
     revoke_module = _load_revoke_module()
-    assert revoke_module.ALL_PERMISSION_ALLOW_TOOLS == ("Edit", "Write", "Read")
+    assert revoke_module.ALL_PERMISSION_ALLOW_TOOLS == ("Edit", "Read")
     assert revoke_module.AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX == (
         "Trusted local workspace:"
     )
@@ -49,3 +49,90 @@ def test_revoke_module_guards_sys_path_insert_against_duplicates() -> None:
         "revoke_project_claude_permissions.py must guard sys.path.insert against "
         "duplicate entries on reload (consistent with sibling modules)"
     )
+
+
+def _section_of(settings: dict[str, object], section_key: str) -> dict[str, object]:
+    section = settings[section_key]
+    assert isinstance(section, dict)
+    return section
+
+
+def test_remove_values_from_list_removes_matching_strings() -> None:
+    revoke_module = _load_revoke_module()
+    target_list: list[object] = ["keep", "drop", 7, "drop"]
+    removed_count = revoke_module.remove_values_from_list(target_list, {"drop"})
+    assert removed_count == 2
+    assert target_list == ["keep", 7]
+
+
+def test_remove_rules_from_allow_list_removes_named_rules() -> None:
+    revoke_module = _load_revoke_module()
+    settings: dict[str, object] = {
+        "permissions": {
+            "allow": ["Edit(/proj/.claude/**)", "Read(/proj/.claude/**)"],
+        },
+    }
+    removed_count = revoke_module.remove_rules_from_allow_list(
+        settings, ["Edit(/proj/.claude/**)"]
+    )
+    assert removed_count == 1
+    assert _section_of(settings, "permissions")["allow"] == ["Read(/proj/.claude/**)"]
+
+
+def test_remove_rules_from_deny_list_removes_named_rules() -> None:
+    revoke_module = _load_revoke_module()
+    settings: dict[str, object] = {
+        "permissions": {
+            "deny": ["Edit(/proj/.claude/hooks/**)", "Read(/proj/.claude/hooks/**)"],
+        },
+    }
+    removed_count = revoke_module.remove_rules_from_deny_list(
+        settings, ["Edit(/proj/.claude/hooks/**)"]
+    )
+    assert removed_count == 1
+    assert _section_of(settings, "permissions")["deny"] == [
+        "Read(/proj/.claude/hooks/**)"
+    ]
+
+
+def test_remove_directory_from_additional_directories_removes_entry() -> None:
+    revoke_module = _load_revoke_module()
+    settings: dict[str, object] = {
+        "permissions": {
+            "additionalDirectories": ["/proj", "/other"],
+        },
+    }
+    removed_count = revoke_module.remove_directory_from_additional_directories(
+        settings, "/proj"
+    )
+    assert removed_count == 1
+    assert _section_of(settings, "permissions")["additionalDirectories"] == ["/other"]
+
+
+def test_remove_trust_entries_for_project_removes_every_project_entry() -> None:
+    revoke_module = _load_revoke_module()
+    trust_prefix = revoke_module.AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX
+    project_entry_a = "Trusted local workspace: /proj/.claude/** wording A"
+    project_entry_b = "Trusted local workspace: /proj/.claude/** wording B"
+    other_project_entry = "Trusted local workspace: /other/.claude/** unrelated"
+    settings: dict[str, object] = {
+        "autoMode": {
+            "environment": [project_entry_a, project_entry_b, other_project_entry],
+        },
+    }
+    removed_count = revoke_module.remove_trust_entries_for_project(
+        settings, "/proj", trust_prefix
+    )
+    assert removed_count == 2
+    assert _section_of(settings, "autoMode")["environment"] == [other_project_entry]
+
+
+def test_prune_settings_after_revoke_drops_empty_sections() -> None:
+    revoke_module = _load_revoke_module()
+    settings: dict[str, object] = {
+        "permissions": {"allow": [], "deny": []},
+        "autoMode": {"environment": []},
+    }
+    revoke_module.prune_settings_after_revoke(settings)
+    assert "permissions" not in settings
+    assert "autoMode" not in settings

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

@@ -0,0 +1,301 @@
+"""Behavioral tests for stale_worktree_rule_sweep.
+
+Drives the real sweep functions against real temp directories and a real
+temp settings file, and drives the real grant and revoke flows end to end.
+A live worktree directory exists on disk; a dead worktree path does not. The
+sweep keeps every rule whose worktree directory still exists and drops every
+rule whose worktree directory is gone, then removes exact duplicates from
+each rule array. The grant and revoke runs perform that sweep before they
+save, so a run whose only effect is the sweep still persists the cleanup.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_scripts_module(module_name: str) -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    parent_directory = str(scripts_directory.resolve())
+    if parent_directory not in sys.path:
+        sys.path.insert(0, parent_directory)
+    module_path = scripts_directory / f"{module_name}.py"
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def _load_sweep_module() -> ModuleType:
+    return _load_scripts_module("stale_worktree_rule_sweep")
+
+
+permissions_common = _load_scripts_module("_claude_permissions_common")
+
+
+def _make_live_worktree_directory(worktrees_root: Path) -> Path:
+    live_worktree_directory = worktrees_root / "repo" / "live-worktree"
+    live_worktree_directory.mkdir(parents=True)
+    return live_worktree_directory
+
+
+def _allow_rule_for(worktree_directory: Path) -> str:
+    return f"Edit({worktree_directory}/.claude/**)"
+
+
+def _deny_rule_for(worktree_directory: Path) -> str:
+    return f"Read({worktree_directory}/.claude/settings*.json)"
+
+
+def _permission_list(all_settings: dict[str, object], list_key: str) -> list[object]:
+    permissions_section = all_settings["permissions"]
+    assert isinstance(permissions_section, dict)
+    rule_list = permissions_section[list_key]
+    assert isinstance(rule_list, list)
+    return rule_list
+
+
+def test_sweep_keeps_live_worktree_rules_and_drops_dead_ones(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    live_worktree_directory = _make_live_worktree_directory(tmp_path)
+    dead_worktree_directory = tmp_path / "repo" / "dead-worktree"
+    live_allow_rule = _allow_rule_for(live_worktree_directory)
+    dead_allow_rule = _allow_rule_for(dead_worktree_directory)
+    live_deny_rule = _deny_rule_for(live_worktree_directory)
+    dead_deny_rule = _deny_rule_for(dead_worktree_directory)
+    all_settings: dict[str, object] = {
+        "permissions": {
+            "allow": [live_allow_rule, dead_allow_rule],
+            "deny": [live_deny_rule, dead_deny_rule],
+        },
+    }
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 2
+    assert _permission_list(all_settings, "allow") == [live_allow_rule]
+    assert _permission_list(all_settings, "deny") == [live_deny_rule]
+
+
+def test_sweep_keeps_live_flat_worktree_rules_and_drops_dead_ones(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    live_worktree_directory = tmp_path / "flat-live"
+    live_worktree_directory.mkdir(parents=True)
+    dead_worktree_directory = tmp_path / "flat-dead"
+    live_allow_rule = _allow_rule_for(live_worktree_directory)
+    dead_allow_rule = _allow_rule_for(dead_worktree_directory)
+    all_settings: dict[str, object] = {
+        "permissions": {
+            "allow": [live_allow_rule, dead_allow_rule],
+            "deny": [],
+        },
+    }
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 1
+    assert _permission_list(all_settings, "allow") == [live_allow_rule]
+
+
+def test_sweep_leaves_rules_for_projects_outside_the_worktrees_root(
+    tmp_path: Path,
+) -> None:
+    sweep_module = _load_sweep_module()
+    unrelated_project_rule = "Edit(/home/developer/project/.claude/**)"
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": [unrelated_project_rule]},
+    }
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 0
+    assert _permission_list(all_settings, "allow") == [unrelated_project_rule]
+
+
+def test_sweep_removes_exact_duplicate_rules(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    live_worktree_directory = _make_live_worktree_directory(tmp_path)
+    live_allow_rule = _allow_rule_for(live_worktree_directory)
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": [live_allow_rule, live_allow_rule]},
+    }
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 1
+    assert _permission_list(all_settings, "allow") == [live_allow_rule]
+
+
+def test_sweep_ignores_malformed_and_non_string_entries(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    malformed_entry = "not a rule at all"
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": [malformed_entry, 7, malformed_entry]},
+    }
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 1
+    assert _permission_list(all_settings, "allow") == [malformed_entry, 7]
+
+
+def test_sweep_tolerates_missing_permission_sections(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    all_settings: dict[str, object] = {}
+    removed_count = sweep_module.sweep_and_deduplicate_permission_lists(
+        all_settings, tmp_path
+    )
+    assert removed_count == 0
+    assert all_settings == {}
+
+
+def test_sweep_round_trips_through_a_real_temp_settings_file(tmp_path: Path) -> None:
+    sweep_module = _load_sweep_module()
+    worktrees_root = tmp_path / "worktrees"
+    live_worktree_directory = _make_live_worktree_directory(worktrees_root)
+    dead_worktree_directory = worktrees_root / "repo" / "dead-worktree"
+    live_allow_rule = _allow_rule_for(live_worktree_directory)
+    dead_allow_rule = _allow_rule_for(dead_worktree_directory)
+    settings_path = tmp_path / "settings.json"
+    permissions_common.save_settings(
+        settings_path,
+        {"permissions": {"allow": [live_allow_rule, dead_allow_rule]}},
+    )
+    loaded_settings = permissions_common.load_settings(settings_path)
+    sweep_module.sweep_and_deduplicate_permission_lists(loaded_settings, worktrees_root)
+    permissions_common.save_settings(settings_path, loaded_settings)
+    reloaded_settings = permissions_common.load_settings(settings_path)
+    assert _permission_list(reloaded_settings, "allow") == [live_allow_rule]
+
+
+def test_wrapper_resolves_worktrees_root_under_the_user_claude_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    sweep_module = _load_sweep_module()
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    worktrees_root = tmp_path / ".claude" / "worktrees"
+    live_worktree_directory = _make_live_worktree_directory(worktrees_root)
+    dead_worktree_directory = worktrees_root / "repo" / "dead-worktree"
+    live_allow_rule = _allow_rule_for(live_worktree_directory)
+    dead_allow_rule = _allow_rule_for(dead_worktree_directory)
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": [live_allow_rule, dead_allow_rule]},
+    }
+    removed_count = sweep_module.sweep_stale_worktree_rules_from_settings(all_settings)
+    assert removed_count == 1
+    assert _permission_list(all_settings, "allow") == [live_allow_rule]
+
+
+def _prepare_home_with_worktrees(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> tuple[Path, Path, Path]:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    worktrees_root = tmp_path / ".claude" / "worktrees"
+    live_worktree_directory = _make_live_worktree_directory(worktrees_root)
+    dead_worktree_directory = worktrees_root / "repo" / "dead-worktree"
+    settings_path = tmp_path / ".claude" / "settings.json"
+    return settings_path, live_worktree_directory, dead_worktree_directory
+
+
+def _make_fake_project(tmp_path: Path) -> Path:
+    fake_project_root = tmp_path / "fake_project"
+    (fake_project_root / ".claude").mkdir(parents=True)
+    return fake_project_root
+
+
+def _seed_allow_rules(settings_path: Path, all_rules: list[object]) -> None:
+    permissions_common.save_settings(
+        settings_path, {"permissions": {"allow": all_rules}}
+    )
+
+
+def _saved_allow_list(settings_path: Path) -> list[object]:
+    saved_settings = permissions_common.load_settings(settings_path)
+    permissions_section = saved_settings.get("permissions")
+    if not isinstance(permissions_section, dict):
+        return []
+    allow_list = permissions_section.get("allow")
+    return allow_list if isinstance(allow_list, list) else []
+
+
+def test_real_grant_run_sweeps_a_dead_worktree_rule_from_saved_settings(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    settings_path, live_directory, dead_directory = _prepare_home_with_worktrees(
+        tmp_path, monkeypatch
+    )
+    live_rule = _allow_rule_for(live_directory)
+    dead_rule = _allow_rule_for(dead_directory)
+    unrelated_rule = "Edit(/home/developer/project/.claude/**)"
+    _seed_allow_rules(settings_path, [live_rule, dead_rule, unrelated_rule])
+    monkeypatch.chdir(_make_fake_project(tmp_path))
+    grant_module = _load_scripts_module("grant_project_claude_permissions")
+    grant_module.grant_permissions_for_current_directory()
+    saved_allow = _saved_allow_list(settings_path)
+    assert dead_rule not in saved_allow
+    assert live_rule in saved_allow
+    assert unrelated_rule in saved_allow
+
+
+def test_real_grant_run_with_only_a_sweep_change_still_saves(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    settings_path, _live_directory, dead_directory = _prepare_home_with_worktrees(
+        tmp_path, monkeypatch
+    )
+    monkeypatch.chdir(_make_fake_project(tmp_path))
+    grant_module = _load_scripts_module("grant_project_claude_permissions")
+    grant_module.grant_permissions_for_current_directory()
+    dead_rule = _allow_rule_for(dead_directory)
+    granted_settings = permissions_common.load_settings(settings_path)
+    _permission_list(granted_settings, "allow").append(dead_rule)
+    permissions_common.save_settings(settings_path, granted_settings)
+    grant_module.grant_permissions_for_current_directory()
+    assert dead_rule not in _saved_allow_list(settings_path)
+
+
+def test_real_revoke_run_sweeps_a_dead_worktree_rule_from_saved_settings(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    settings_path, live_directory, dead_directory = _prepare_home_with_worktrees(
+        tmp_path, monkeypatch
+    )
+    fake_project_root = _make_fake_project(tmp_path)
+    monkeypatch.chdir(fake_project_root)
+    revoke_module = _load_scripts_module("revoke_project_claude_permissions")
+    project_path = str(fake_project_root).replace("\\", "/")
+    project_allow_rules = revoke_module.build_permission_rules(
+        project_path, revoke_module.ALL_PERMISSION_ALLOW_TOOLS
+    )
+    live_rule = _allow_rule_for(live_directory)
+    dead_rule = _allow_rule_for(dead_directory)
+    _seed_allow_rules(settings_path, [*project_allow_rules, live_rule, dead_rule])
+    revoke_module.revoke_permissions_for_current_directory()
+    saved_allow = _saved_allow_list(settings_path)
+    assert dead_rule not in saved_allow
+    assert live_rule in saved_allow
+    for each_project_rule in project_allow_rules:
+        assert each_project_rule not in saved_allow
+
+
+def test_real_revoke_run_with_only_a_sweep_change_still_saves(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    settings_path, _live_directory, dead_directory = _prepare_home_with_worktrees(
+        tmp_path, monkeypatch
+    )
+    dead_rule = _allow_rule_for(dead_directory)
+    _seed_allow_rules(settings_path, [dead_rule])
+    monkeypatch.chdir(_make_fake_project(tmp_path))
+    revoke_module = _load_scripts_module("revoke_project_claude_permissions")
+    revoke_module.revoke_permissions_for_current_directory()
+    assert dead_rule not in _saved_allow_list(settings_path)

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

@@ -0,0 +1,85 @@
+"""Behavioral tests for stale_worktree_rule_sweep_constants.
+
+Confirms get_claude_worktrees_root resolves the worktrees directory under
+the user's ~/.claude home, and that the rule-parsing constants carry the
+literal shapes the sweep relies on.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_constants_module() -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    parent_directory = str(scripts_directory.resolve())
+    if parent_directory not in sys.path:
+        sys.path.insert(0, parent_directory)
+    module_path = (
+        scripts_directory
+        / "pr_loop_shared_constants"
+        / "stale_worktree_rule_sweep_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "pr_loop_shared_constants.stale_worktree_rule_sweep_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def test_worktrees_root_resolves_under_the_user_claude_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    constants_module = _load_constants_module()
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    resolved_worktrees_root = constants_module.get_claude_worktrees_root()
+    assert resolved_worktrees_root == tmp_path / ".claude" / "worktrees"
+
+
+def test_extract_rule_target_path_reads_the_delimited_path() -> None:
+    constants_module = _load_constants_module()
+    extracted_path = constants_module.extract_rule_target_path(
+        "Edit(/repo/wt/.claude/**)"
+    )
+    assert extracted_path == "/repo/wt/.claude/**"
+
+
+def test_extract_rule_target_path_returns_none_for_a_non_rule() -> None:
+    constants_module = _load_constants_module()
+    assert constants_module.extract_rule_target_path("not a rule") is None
+
+
+def test_worktree_directory_for_rule_keeps_nested_segments_below_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/repo/feature/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "repo" / "feature"
+
+
+def test_worktree_directory_for_rule_keeps_one_segment_flat_layout() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/.claude/worktrees/flat-worktree/.claude/**)", worktrees_root
+    )
+    assert resolved_directory == worktrees_root / "flat-worktree"
+
+
+def test_worktree_directory_for_rule_returns_none_outside_the_root() -> None:
+    constants_module = _load_constants_module()
+    worktrees_root = Path("/home/dev/.claude/worktrees")
+    resolved_directory = constants_module.worktree_directory_for_rule(
+        "Edit(/home/dev/project/.claude/**)", worktrees_root
+    )
+    assert resolved_directory is None

package/_shared/pr-loop/worker-spawn.md

@@ -146,7 +146,7 @@ Mode decision:
 | `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
 
 The review always runs at effort **high** on model **opus**. Chain mode builds
-a single-turn prompt `/code-review high --fix`, pins `--model opus`, sets
+a single-turn prompt `/code-review xhigh --fix`, pins `--model opus`, sets
 subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
 so the spawn does not wait for input.
 

package/agents/CLAUDE.md

@@ -18,6 +18,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
 | `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
 | `session-advisor.md` | Session Advisor | Standing multi-consumer reviewer; SendMessage only; returns endorse/correction/plan/stop |
+| `skill-writer-agent.md` | Skill Writer Agent | Authors SKILL.md and companion files to skill-builder conventions; caller-agnostic authoring specialist |
 
 ## Format
 

package/agents/code-verifier.md

@@ -1,12 +1,12 @@
 ---
 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 — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then 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.
+description: Post-hoc verification agent for the three-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 — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then 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, Task
 model: sonnet
 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.
+You are the verifier in a three-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.
 
@@ -33,7 +33,7 @@ On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verificati
 
 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.
 
-As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
+As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
 
 This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then emit the fenced verdict block below — it stays the last thing in your message so the verifier_verdict_minter hook reads it.
 
@@ -43,4 +43,4 @@ End your final message with exactly one fenced verdict block — the verifier_ve
 {"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.
+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. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.

package/agents/skill-writer-agent.md

@@ -0,0 +1,84 @@
+---
+name: skill-writer-agent
+description: >-
+  Authors a skill package — SKILL.md plus companion files — to skill-builder conventions: hub layout, trigger-catalog description, deterministic work shipped as scripts and task-seed lists. Triggers: author a skill, write a SKILL.md, skill-writer-agent, delegate skill file authoring, produce skill package files.
+tools: Read, Write, Edit, Grep, Glob
+color: green
+---
+
+# Skill Writer Agent
+
+You author skill files. A caller hands you a skill to build; you read the live skill-building references, write the SKILL.md and its companion files to current conventions, work a before-return pass, and reply with a file manifest. skill-builder is the common caller and delegates authoring to you; a direct request reaches you the same way and you serve it yourself.
+
+## Input
+
+Callers reach you in one of two shapes.
+
+**Structured packet** (skill-builder sends this). A new-skill packet carries these fields, in order:
+
+- `Skill type` — one of the skill-builder skill types.
+- `Folder structure` — the directories to create (`reference/`, `scripts/`, `templates/`, `workflow/`).
+- `What it does` — one sentence naming the single job.
+- `Domain context` — what the authored skill needs Claude to know.
+- `Initial gotchas` — failure patterns to document from the start.
+- `Degree of freedom` — high, medium, or low, with reasoning.
+- `Constraints` — the non-negotiables.
+- `Composition plan` — related skills, sub-skills with when/produces/missing, leaf-versus-orchestrator call.
+- `Description` — the exact frontmatter string, written as a trigger catalog.
+- `Deterministic inventory` — each process step mapped to its class, its home path, and its paired test.
+
+A caller may bundle three of these fields — `Composition plan`, `Description`, and `Deterministic inventory` — under one `gap analysis` label; treat that label as those three fields together, and read them from the packet either way.
+
+A refine packet instead carries: the current SKILL.md, what was observed, what to change, new gotchas to add, what to preserve, a description rewrite, a composition change, and a deterministic fix.
+
+**Direct request.** A looser prompt names the skill to build or the file to edit. Fill the packet yourself from the references below, and ask the caller for any field only they hold, such as domain context or constraints.
+
+## Read first
+
+At the start of every job, read the live references at `~/.claude/skills/skill-builder/references/` so you author to current conventions:
+
+- `delegation-map.md` — the handoff packet and the Produce contract.
+- `deterministic-elements.md` — the rule that deterministic work ships as code, artifacts, or session tasks.
+- `description-field.md` — the trigger-catalog description shape.
+- `skill-modularity.md` — hub layout and compose-by-name.
+
+Read them fresh each run; they carry the rules you author to.
+
+## Standards every file meets
+
+1. SKILL.md follows the hub layout: principle, gotchas, when-applies, process, file index, folder map.
+2. The frontmatter description is the exact trigger-catalog string — a `capability stem` plus a `Triggers:` list.
+3. A sub-skills table appears whenever the composition plan lists peer skills.
+4. Companion files carry the detail: reference docs, workflow steps, templates, scripts.
+5. Every deterministic-inventory row gets a script or workflow; SKILL.md points to it and handles its exit codes.
+6. Skill scripts follow CODE_RULES: a `*_constants/` package, full type hints, specific errors, and a paired test.
+7. Every file stays under 500 lines, with a table of contents on any file over 100 lines.
+8. A file index lists every file and its purpose.
+9. Steps owned by a named sub-skill stay in that sub-skill; SKILL.md invokes it by name.
+
+## Deterministic elements
+
+Honor `deterministic-elements.md` in every skill you author. A step is deterministic when the same inputs give the same outputs, success is machine-checkable, and a human could write it as a pure function or a fixed sequence. Route each kind to its home:
+
+- Validators, transforms, detection, and mechanical sequences ship as `scripts/` or `workflow/*.mjs`, each with tests and a `*_constants/` package.
+- Verbatim templates ship in `templates/`.
+- Long fixed catalogs Claude reads word-for-word ship in `reference/`.
+- Ordered work the future skill-runner must finish ships as a task-seed list: plain bullets or numbered lines in a reference file, plus an instruction in SKILL.md to register one session task per item through the host task tool (`TaskCreate`, else `TodoWrite`). Judgment, routing, and refusal stay in markdown prose.
+
+Keep required step lists on the task list. Where a host task tool is present, the authored SKILL.md registers each item through it; where the host offers only prose, the SKILL.md states that limit and stops.
+
+## Before you return
+
+Work your before-return checks as one pass over the file set:
+
+- The SKILL.md hub layout is present and complete.
+- The description reads as a trigger catalog.
+- Every deterministic row carries its script and paired test.
+- Files stay under the line caps, with a table of contents wherever the cap calls for one.
+- The file index is present, and the sub-skills table is present whenever the skill composes others.
+
+On a direct call, this pass is your whole quality gate — work it in full. When skill-builder is the caller, it runs its 38-point audit next; hand it a coherent, complete file set so that audit starts clean.
+
+## Return
+
+Reply with a file manifest kept thin: each path you created or edited on its own line, then one line naming what the caller picks up next, such as the audit or the tests to run. Keep the reply light so the caller acts on it directly.