claude-dev-env 8.69.0 → 8.70.0

package/hooks/features/write-edit-blocking.md

@@ -1,18 +1,17 @@
 # Write and Edit blocking
 
-This family decides whether an agent's file mutation can run. It also warns about broad refactors and unsafe migration edits before the agent changes a file.
+This family decides whether an agent's file mutation can run. It also warns about unsafe migration edits before the agent changes a file.
 
 ## Checks
 
 - `blocking/pre_tool_use_dispatcher.py` combines hosted advisory output with its native description check and returns one permission decision.
-- `advisory/refactor_guard.py` warns when an Edit or MultiEdit appears to rename code beyond the current change.
 - `advisory/migration_safety_advisor.py` warns when an Edit or MultiEdit adds an unsafe Django migration operation.
 - `blocking/state_description_blocker.py` rejects historical or comparative prose in supported comments, docstrings, and Markdown.
 
 ## When it fires
 
 - `blocking/pre_tool_use_dispatcher.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds in `hooks.json`.
-- `advisory/refactor_guard.py` and `advisory/migration_safety_advisor.py` run inside that dispatcher on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. `ALL_HOSTED_HOOK_ENTRIES` selects `Edit` and `MultiEdit` for each.
+- `advisory/migration_safety_advisor.py` runs inside that dispatcher on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. `ALL_HOSTED_HOOK_ENTRIES` selects `Edit` and `MultiEdit` for it.
 - `blocking/state_description_blocker.py` runs through the dispatcher's native evaluator on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. Its evaluator checks `Write`, `Edit`, and `MultiEdit` payloads and skips `apply_patch`.
 
 ## Proving it
@@ -22,13 +21,12 @@ Preconditions:
 - Run each command from the repository root with Python and pytest available. The tests use disposable paths where they need files.
 
 - **Dispatcher decision.** Input is a clean Write payload. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pre_tool_use_dispatcher.py -q`. The adjacent test checks that the dispatcher allows clean writes and carries denials from its checks.
-- **Refactor warning.** Input is a MultiEdit whose second edit renames a function. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_refactor_guard.py -q`. The adjacent test reports both function names in the warning.
 - **Migration warning.** Input is an Edit containing `migrations.RemoveField`. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_migration_safety_advisor.py -q`. The adjacent test observes an allow decision with a migration warning.
 - **Description gate.** Input is a Write containing historical prose in a Python comment. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_state_description_blocker.py -q`. The adjacent test observes a denial reason.
 
 ## Gotchas
 
-- `ALL_HOSTED_HOOK_ENTRIES` lists only the two nonblocking advisors. The dispatcher calls the description evaluator through its native hook table.
+- `ALL_HOSTED_HOOK_ENTRIES` lists only the nonblocking migration advisor. The dispatcher calls the description evaluator through its native hook table.
 - The dispatcher runs hosted entries in roster order. A hosted advisory crash stays silent; a native blocking check can deny the write.
 - `scripts/policy_lint/adapter_detectors.py` also loads `blocking/state_description_blocker.py`. Check that adapter when changing its evaluator.
 - `bin/install.mjs` names folded and retired script paths so reinstall can remove stale registrations.

package/hooks/hooks.json

@@ -88,7 +88,7 @@
         ]
       },
       {
-        "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)",
+        "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)",
         "hooks": [
           {
             "type": "command",
@@ -97,6 +97,16 @@
           }
         ]
       },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/image_read_size_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "EnterWorktree",
         "hooks": [

package/hooks/hooks_constants/artifact_look_gate_constants.py

@@ -28,6 +28,5 @@ UNSEEN_PAGE_REASON_TEMPLATE = (
     "headless browser, for example `chromium --headless --screenshot=page.png "
     "--window-size=800,900 file://{page_path}`, then open page.png with the "
     "Read tool and check it against the ask. Fix what the picture shows, take "
-    "a new screenshot, and publish again. Attach that screenshot when you "
-    "report the page, so the person who asked sees the same proof."
+    "a new screenshot, and publish again."
 )

package/hooks/hooks_constants/followup_pr_dedupe_constants.py

@@ -17,3 +17,7 @@ DUPLICATE_FOLLOWUP_REASON_TEMPLATE = (
     " ({open_url}). Add this finding to the open follow-up pull request #{open_number}."
     " One combined follow-up pull request per parent pull request."
 )
+ALL_TITLE_OPTIONS = frozenset({"-t", "--title"})
+WORKFLOW_DISPATCH_TOOL_SUFFIX = "__actions_run_trigger"
+RUN_WORKFLOW_METHOD = "run_workflow"
+ALL_PULL_REQUEST_DISPATCH_INPUT_KEYS = ("head", "title")

package/hooks/hooks_constants/image_read_size_gate_constants.py

@@ -0,0 +1,41 @@
+"""Names, limits and refusal text for the image_read_size_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+READ_TOOL_NAME = "Read"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+FILE_PATH_INPUT_KEY = "file_path"
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+DENY_DECISION = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+MAXIMUM_LONG_EDGE_PIXELS = 512
+HEADER_BYTE_COUNT = 64 * 1024
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+PNG_SIZE_START = 16
+PNG_SIZE_END = 24
+GIF_SIZE_START = 6
+GIF_SIZE_END = 10
+ALL_GIF_SIGNATURES = (b"GIF87a", b"GIF89a")
+JPEG_SIGNATURE = b"\xff\xd8"
+JPEG_MARKER_PREFIX = 0xFF
+JPEG_MARKER_LENGTH = 2
+JPEG_FRAME_SIZE_START = 5
+JPEG_FRAME_SIZE_END = 9
+ALL_JPEG_FRAME_MARKERS = frozenset(
+    {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
+)
+ALL_JPEG_STANDALONE_MARKERS = frozenset(
+    {0x01, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8}
+)
+AGENT_COPY_SCRIPT_PATH = Path(__file__).resolve().parents[2] / "scripts" / "agent_image_copy.py"
+OVERSIZED_IMAGE_REASON_TEMPLATE = (
+    "This image is {width}x{height} pixels. Agents read images at {maximum_edge} pixels or less"
+    " on the long edge, because a full-size image fills the context: a 1440x2560 screenshot costs"
+    " about 4,784 tokens, and a 288x512 copy costs about 209. Write a capped copy and read that"
+    ' copy: `python3 "{script_path}" "{image_path}"` prints the path of the copy, which keeps'
+    " the aspect ratio. Crop the region you need with `--crop LEFT,TOP,RIGHT,BOTTOM` when a"
+    " detail is too small at that size. Send the full-size file to a person, never to an agent."
+)

package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py

@@ -39,3 +39,6 @@ ALL_PYTHON_EXECUTABLES = frozenset({"python", "python3", "python.exe", "python3.
 PULL_REQUEST_SCRIPT_NAME = "pull_request.py"
 PATH_SEPARATOR_PATTERN = r"[\\/]"
 PYTHON_OPTIONS_WITH_VALUE = frozenset({"-X", "-W"})
+ALL_BUILD_EVAL_SKILL_NAMES = ("claude-api",)
+BUILD_EVAL_ARGUMENT_WORD = "build-eval"
+BUILD_EVAL_COMMAND_MARKER = "<command-name>/claude-api</command-name>"

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -83,11 +83,6 @@ class HostedHookEntry:
 
 
 ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
-    HostedHookEntry(
-        script_relative_path="advisory/refactor_guard.py",
-        applicable_tool_names=frozenset({EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}),
-        is_blocking=False,
-    ),
     HostedHookEntry(
         script_relative_path="advisory/migration_safety_advisor.py",
         applicable_tool_names=frozenset({EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}),

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -8,7 +8,6 @@ ALL_GH_CREATE_WORDS = ["pr", "create"]
 PULL_REQUEST_SCRIPT_NAME = "pull_request.py"
 PULL_REQUEST_SCRIPT_CREATE_WORD = "create"
 ALL_PYTHON_PROGRAM_NAMES = frozenset({"python", "python3", "py"})
-CREATE_PULL_REQUEST_TOOL_SUFFIX = "__create_pull_request"
 PROOF_GUIDE_PATH = "~/.claude/docs/rule-guides/proof-before-pull-request.md"
 MISSING_BODY_REASON = (
     "Pass the pull request body with --body or --body-file so this gate can read its"
@@ -64,3 +63,23 @@ UNREADABLE_CHANGES_REASON = (
     " from a checkout of the head branch with origin fetched, or put a screenshot"
     " link in the 'Proof in practice' section. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
+FEATURE_TITLE_PATTERN = r"^\s*feat(\([^)]*\))?!?:"
+EVAL_HEADING_PATTERN = r"^(#{1,6})[ \t]+evals?[ \t]*#*[ \t]*$"
+EVAL_GUIDE_PATH = "~/.claude/docs/rule-guides/features-start-with-an-eval.md"
+MISSING_EVAL_SECTION_REASON = (
+    "This feature pull request has no 'Eval' section naming its eval. A new feature is"
+    " built against an eval. Invoke the Skill tool with skill 'claude-api' and args"
+    " 'build-eval', build or reuse the eval it leads you to, and run it. Then add an"
+    " 'Eval' heading to the body that names the eval's cases and grader, gives the"
+    " command that runs it in backticks, and quotes its result. Read "
+    + EVAL_GUIDE_PATH
+    + " for the full rule."
+)
+MISSING_BUILD_EVAL_REASON = (
+    "This feature pull request comes from a session that never invoked /claude-api"
+    " build-eval. A new feature starts with that command. Invoke the Skill tool with"
+    " skill 'claude-api' and args 'build-eval', check the eval named in the 'Eval'"
+    " section with it, then run the same command again. Read "
+    + EVAL_GUIDE_PATH
+    + " for the full rule."
+)

package/hooks/hooks_constants/test_pre_tool_use_dispatcher_constants.py

@@ -37,21 +37,14 @@ def test_roster_keeps_only_nonblocking_edit_advisors() -> None:
     all_script_paths = tuple(
         each_entry.script_relative_path for each_entry in ALL_HOSTED_HOOK_ENTRIES
     )
-    assert all_script_paths == (
-        "advisory/refactor_guard.py",
-        "advisory/migration_safety_advisor.py",
-    )
+    assert all_script_paths == ("advisory/migration_safety_advisor.py",)
     assert all(not each_entry.is_blocking for each_entry in ALL_HOSTED_HOOK_ENTRIES)
 
 
 def test_advisors_apply_to_edit_and_multi_edit() -> None:
-    for each_script_path in (
-        "advisory/refactor_guard.py",
-        "advisory/migration_safety_advisor.py",
-    ):
-        entry = _entry_for(each_script_path)
-        assert entry is not None
-        assert entry.applicable_tool_names == frozenset({EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME})
+    entry = _entry_for("advisory/migration_safety_advisor.py")
+    assert entry is not None
+    assert entry.applicable_tool_names == frozenset({EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME})
 
 
 def test_every_hosted_script_path_exists_under_the_hooks_root() -> None:

package/hooks/hooks_constants/transcript_skill_scan_constants.py

@@ -5,3 +5,4 @@ COMPACT_BOUNDARY_SUBTYPE = "compact_boundary"
 SKILL_TOOL_NAME = "Skill"
 TOOL_USE_BLOCK_TYPE = "tool_use"
 USER_ENTRY_TYPE = "user"
+COMMAND_ARGUMENTS_PATTERN = r"<command-args>(.*?)</command-args>"

package/hooks/test_transcript_skill_scan.py

@@ -8,7 +8,11 @@ HOOKS_DIRECTORY = Path(__file__).resolve().parent
 if str(HOOKS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIRECTORY))
 
-from transcript_skill_scan import is_skill_loaded_after_last_compaction, skill_invocation_status
+from transcript_skill_scan import (
+    invokes_skill_with_argument,
+    is_skill_loaded_after_last_compaction,
+    skill_invocation_status,
+)
 
 
 def _skill_entry(name: str) -> str:
@@ -56,3 +60,73 @@ def test_invocation_status_separates_ever_invoked_from_loaded_now() -> None:
     assert skill_invocation_status([_skill_entry("pr-lifecycle")], ("pr-lifecycle",), ()) == (True, True)
     assert skill_invocation_status([_skill_entry("pr-lifecycle"), compaction], ("pr-lifecycle",), ()) == (True, False)
     assert skill_invocation_status([compaction, _skill_entry("other")], ("pr-lifecycle",), ()) == (False, False)
+
+
+BUILD_EVAL_MARKER = "<command-name>/claude-api</command-name>"
+
+
+def _skill_entry_with_arguments(name: str, arguments: object) -> str:
+    return json.dumps(
+        {
+            "type": "assistant",
+            "message": {
+                "content": [{"type": "tool_use", "name": "Skill", "input": {"skill": name, "args": arguments}}]
+            },
+        }
+    )
+
+
+def _invokes_build_eval(lines: list[str]) -> bool:
+    return invokes_skill_with_argument(lines, ("claude-api",), "build-eval", BUILD_EVAL_MARKER)
+
+
+def test_claude_api_skill_with_build_eval_argument_should_count() -> None:
+    assert _invokes_build_eval([_skill_entry_with_arguments("claude-api", "build-eval")])
+
+
+def test_build_eval_argument_followed_by_more_words_should_count() -> None:
+    assert _invokes_build_eval([_skill_entry_with_arguments("claude-api", "build-eval   extra words")])
+
+
+def test_plugin_prefixed_claude_api_with_build_eval_should_count() -> None:
+    assert _invokes_build_eval([_skill_entry_with_arguments("plugin:claude-api", "build-eval")])
+
+
+def test_claude_api_with_another_argument_should_not_count() -> None:
+    assert not _invokes_build_eval([_skill_entry_with_arguments("claude-api", "migrate")])
+    assert not _invokes_build_eval([_skill_entry_with_arguments("claude-api", "migrate build-eval")])
+    assert not _invokes_build_eval([_skill_entry_with_arguments("claude-api", None)])
+    assert not _invokes_build_eval([_skill_entry("claude-api")])
+
+
+def test_build_eval_skill_alone_should_not_count() -> None:
+    assert not _invokes_build_eval([_skill_entry("build-eval")])
+    assert not _invokes_build_eval([_skill_entry_with_arguments("build-eval", "build-eval")])
+
+
+def test_user_claude_api_build_eval_command_should_count() -> None:
+    command_text = BUILD_EVAL_MARKER + "<command-args>build-eval for the gate</command-args>"
+    assert _invokes_build_eval([json.dumps({"type": "user", "message": {"content": command_text}})])
+
+
+def test_user_claude_api_command_with_another_argument_should_not_count() -> None:
+    command_text = BUILD_EVAL_MARKER + "<command-args>migrate</command-args>"
+    assert not _invokes_build_eval([json.dumps({"type": "user", "message": {"content": command_text}})])
+    assert not _invokes_build_eval([json.dumps({"type": "user", "message": {"content": BUILD_EVAL_MARKER}})])
+
+
+def test_quoted_build_eval_command_in_a_tool_result_should_not_count() -> None:
+    command_text = BUILD_EVAL_MARKER + "<command-args>build-eval</command-args>"
+    quoted_result = json.dumps(
+        {"type": "user", "message": {"content": [{"type": "tool_result", "content": command_text}]}}
+    )
+    assert not _invokes_build_eval([quoted_result])
+
+
+def test_build_eval_invocation_before_a_compact_boundary_should_still_count() -> None:
+    lines = [
+        _skill_entry_with_arguments("claude-api", "build-eval"),
+        json.dumps({"type": "system", "subtype": "compact_boundary"}),
+        _skill_entry("other"),
+    ]
+    assert _invokes_build_eval(lines)

package/hooks/transcript_skill_scan.py

@@ -1,12 +1,14 @@
-"""Find a skill invocation after the last transcript compaction."""
+"""Find a skill invocation after the last transcript compaction, or one with a given first argument anywhere."""
 
 from __future__ import annotations
 
 import json
-from collections.abc import Collection, Iterable
+import re
+from collections.abc import Collection, Iterable, Iterator
 
 from hooks_constants.transcript_skill_scan_constants import (
     ASSISTANT_ENTRY_TYPE,
+    COMMAND_ARGUMENTS_PATTERN,
     COMPACT_BOUNDARY_SUBTYPE,
     SKILL_TOOL_NAME,
     TOOL_USE_BLOCK_TYPE,
@@ -14,19 +16,23 @@ from hooks_constants.transcript_skill_scan_constants import (
 )
 
 
-def _invokes_skill(
-    all_entry_fields: dict[str, object],
-    skill_names: Collection[str],
-    slash_command_markers: Collection[str],
-) -> bool:
+def _user_command_text(all_entry_fields: dict[str, object]) -> str | None:
     message = all_entry_fields.get("message")
-    if not isinstance(message, dict):
-        return False
+    if all_entry_fields.get("type") != USER_ENTRY_TYPE or not isinstance(message, dict):
+        return None
     content = message.get("content")
-    if all_entry_fields.get("type") == USER_ENTRY_TYPE and isinstance(content, str):
-        return any(marker in content for marker in slash_command_markers)
-    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(content, list):
-        return False
+    return content if isinstance(content, str) else None
+
+
+def _named_skill_inputs(
+    all_entry_fields: dict[str, object], skill_names: Collection[str]
+) -> Iterator[dict[str, object]]:
+    message = all_entry_fields.get("message")
+    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(message, dict):
+        return
+    content = message.get("content")
+    if not isinstance(content, list):
+        return
     for each_block in content:
         if not isinstance(each_block, dict) or each_block.get("type") != TOOL_USE_BLOCK_TYPE:
             continue
@@ -36,8 +42,42 @@ def _invokes_skill(
         if isinstance(invoked_name, str) and any(
             invoked_name == name or invoked_name.endswith(":" + name) for name in skill_names
         ):
-            return True
-    return False
+            yield each_block["input"]
+
+
+def _invokes_skill(
+    all_entry_fields: dict[str, object],
+    skill_names: Collection[str],
+    slash_command_markers: Collection[str],
+) -> bool:
+    command_text = _user_command_text(all_entry_fields)
+    if command_text is not None:
+        return any(marker in command_text for marker in slash_command_markers)
+    return next(_named_skill_inputs(all_entry_fields, skill_names), None) is not None
+
+
+def _first_word_is(text: object, argument_word: str) -> bool:
+    return isinstance(text, str) and text.split()[:1] == [argument_word]
+
+
+def _invokes_skill_with_argument(
+    all_entry_fields: dict[str, object],
+    skill_names: Collection[str],
+    argument_word: str,
+    command_marker: str,
+) -> bool:
+    command_text = _user_command_text(all_entry_fields)
+    if command_text is not None:
+        command_arguments = re.search(COMMAND_ARGUMENTS_PATTERN, command_text, re.DOTALL)
+        return (
+            command_marker in command_text
+            and command_arguments is not None
+            and _first_word_is(command_arguments.group(1), argument_word)
+        )
+    return any(
+        _first_word_is(each_input.get("args"), argument_word)
+        for each_input in _named_skill_inputs(all_entry_fields, skill_names)
+    )
 
 
 def _relevant_entry(each_line: str, skill_names: Collection[str]) -> dict[str, object] | None:
@@ -91,3 +131,35 @@ def is_skill_loaded_after_last_compaction(
         slash_command_markers: Accepted user command tags.
     """
     return skill_invocation_status(all_transcript_lines, skill_names, slash_command_markers)[1]
+
+
+def invokes_skill_with_argument(
+    all_transcript_lines: Iterable[str],
+    skill_names: Collection[str],
+    argument_word: str,
+    command_marker: str,
+) -> bool:
+    """Return whether any entry invoked the skill with ``argument_word`` as its first argument.
+
+    ::
+
+        Skill claude-api, args "build-eval extra"            -> True
+        Skill plugin:claude-api, args "build-eval"            -> True
+        Skill claude-api, args "migrate"                      -> False
+        user "/claude-api" command, command-args "build-eval" -> True
+
+    An invocation stays counted after a later compact boundary.
+
+    Args:
+        all_transcript_lines: JSON transcript entries, one per line.
+        skill_names: Accepted skill names, with plugin prefixes accepted.
+        argument_word: The first whitespace-separated word the arguments must carry.
+        command_marker: The user command tag that names the skill.
+    """
+    for each_line in all_transcript_lines:
+        if not any(name in each_line for name in skill_names):
+            continue
+        all_entry_fields = _relevant_entry(each_line, skill_names)
+        if all_entry_fields and _invokes_skill_with_argument(all_entry_fields, skill_names, argument_word, command_marker):
+            return True
+    return False

package/package.json

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

package/rules/anti-corollary-tests.md

@@ -14,6 +14,6 @@ paths:
 
 Before keeping a test, name one code change it would catch; replace a case that catches none. Skip spelling cross products after proving canonicalization once; compare a few discriminating cases. Exercise the production path with a non-default expected result so a dead implementation cannot pass. Test policy compliance on governed surfaces; in an audit, name a mutation and record how many tests it fails.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/anti-corollary-tests.md`](../docs/rule-guides/anti-corollary-tests.md). Read it when choosing cases or auditing mutation evidence.
+**Full text:** [guide](../docs/rule-guides/anti-corollary-tests.md). Read it when choosing cases or auditing mutation evidence.

package/rules/archiving-agent-config.md

@@ -15,6 +15,6 @@ paths:
 
 Trace checks and callers; `CHANGELOG.md`, `README.md`, shipped-skills registry, and host paths prove neither use nor disuse. Read `rules-archived/ARCHIVE-MANIFEST.md`; skip and report exemptions, then continue. Move unused files with `git mv` into sibling archives; record the reason, restore command, and companion edits. Retain skill names in `bin/ever-shipped-skills.mjs` and check tests lost when a skill directory moves.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/archiving-agent-config.md`](../docs/rule-guides/archiving-agent-config.md). Read it before moving or restoring.
+**Full text:** [guide](../docs/rule-guides/archiving-agent-config.md). Read it before moving or restoring.

package/rules/asd-ste100-language.md

@@ -4,6 +4,6 @@
 
 Use the sole general language rule. Write short, complete sentences on one topic. Use active voice; lead with conditions; give one action per step. Use plain, precise words and stable terms. Expand abbreviations and contractions first; name unclear pronouns. Be inclusive; punctuate clearly. Preserve exact labels, identifiers, formulas, titles, and interface text. Send a result, blocker, or question. Mark injury or death `WARNING`, equipment damage `CAUTION`; state condition then result. Aim for 20 words per step, 25 per description. Treat checks as aids; have a human verify accuracy, terms, safety, confidentiality, and meaning.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/asd-ste100-language.md`](../docs/rule-guides/asd-ste100-language.md). Read it for sources.
+**Full text:** [guide](../docs/rule-guides/asd-ste100-language.md). Read it for sources.

package/rules/bdd.md

@@ -13,4 +13,4 @@ paths:
 
 For every non-trivial feature, discover what you do not know, illustrate it with concrete examples in chat, formulate each behavior as a narrow "should ..." specification, then build each one through the TDD loop (CODE_RULES §8). Name developer-facing specs and tests as should sentences.
 
-**Full text:** [`docs/rule-guides/bdd.md`](../docs/rule-guides/bdd.md), with the long-form BDD references.
+**Full text:** [guide](../docs/rule-guides/bdd.md), with the long-form BDD references.

package/rules/build-needs-a-user.md

@@ -17,4 +17,4 @@ Name its caller in this change, first-use date or event, and last manual use wit
 
 **Enforcement:** `uncalled-new-file` checks new code under `scripts/`, `hooks/`, `bin/`, `ci/`, and `tools/` for a caller.
 
-**Full text:** [`docs/rule-guides/build-needs-a-user.md`](../docs/rule-guides/build-needs-a-user.md). Read it when sizing a new check.
+**Full text:** [guide](../docs/rule-guides/build-needs-a-user.md). Read it when sizing a new check.

package/rules/cleanup-temp-files.md

@@ -2,8 +2,8 @@
 
 **When:** Creating scratch files, debug dumps, or one-off helpers during a task.
 
-Prefer memory to scratch files and track any temporary files you create. At completion, remove those files and leave user-requested files in place. Files under the OS temporary root or `$CLAUDE_JOB_DIR` need no explicit removal; a parent handles child-agent scratch. Use the permitted removal form.
+Prefer memory to scratch files and track any temporary files you create. At completion, remove those files and leave user-requested files in place. Files under the OS temporary root or `$CLAUDE_JOB_DIR` need no explicit removal; a parent handles child-agent scratch.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/cleanup-temp-files.md`](../docs/rule-guides/cleanup-temp-files.md). Read it to classify a file or choose cleanup.
+**Full text:** [guide](../docs/rule-guides/cleanup-temp-files.md). Read it to classify a file or choose cleanup.

package/rules/code-standards.md

@@ -16,4 +16,4 @@ paths:
 
 **Enforcement:** the staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file, and CI runs it against the merge base.
 
-**Full text:** [`docs/rule-guides/code-standards.md`](../docs/rule-guides/code-standards.md), with the policy surface map.
+**Full text:** [guide](../docs/rule-guides/code-standards.md), with the policy surface map.

package/rules/correction-lens.md

@@ -5,7 +5,7 @@
 Open a control in the guarded repository, in the same run, at the highest capable layer. State the layer, why higher layers fail, and the change opened. Pair layers when both help. Move repeated corrections up a layer. Memory records the decision.
 
 | Priority | Layer | Control |
-|---|---|---|
+|-|-|-|
 | 1 | Codebase | Prevent the mistake. |
 | 2 | Static analysis | Programmatic check. |
 | 3 | Review tooling | Reviewer criterion. |
@@ -16,6 +16,6 @@ Open a control in the guarded repository, in the same run, at the highest capabl
 
 Keep this file in `rules/`. A prune, archive, consolidation, or rewrite that would move it stops here. Edits that sharpen it are welcome.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/correction-lens.md`](../docs/rule-guides/correction-lens.md). Read it when choosing a layer or locating a control.
+**Full text:** [guide](../docs/rule-guides/correction-lens.md). Read it when choosing a layer or locating a control.

package/rules/destructive-commands.md

@@ -2,10 +2,10 @@
 
 **When:** Removing files or writing a destructive command string.
 
-No hook watches Bash commands; a permission prompt can stall unattended work. Keep destructive literals out of command strings, including data. Use literal absolute targets; never target a bare temporary root. Use `git rm` for tracked files. Pass bodies by file and test hooks through the test suite. Copy this line into every subagent prompt:
+Keep destructive literals out of command strings, including data. Use literal absolute targets; never target a bare temporary root. Use `git rm` for tracked files. Pass bodies by file and test hooks through the test suite. Copy this line into every subagent prompt:
 
 > Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
 
-**Enforcement:** none, the agent applies it; the harness may prompt.
+**Enforcement:** none; a harness permission prompt can stall unattended work.
 
-**Full text:** [`docs/rule-guides/destructive-commands.md`](../docs/rule-guides/destructive-commands.md). Read it before any removal.
+**Full text:** [guide](../docs/rule-guides/destructive-commands.md). Read it before any removal.

package/rules/doc-inventory-integrity.md

@@ -21,4 +21,4 @@ A doc that inventories code stays in step with the code, in the same change:
 
 **Enforcement:** `repository_checks/claude_md.py`, `repository_checks/package_inventory.py`, and `repository_checks/env_var_documentation.py`. Run `python packages/claude-dev-env/scripts/repository_policy.py` before you commit. CI runs the same command.
 
-**Full text:** [`docs/rule-guides/doc-inventory-integrity.md`](../docs/rule-guides/doc-inventory-integrity.md).
+**Full text:** [guide](../docs/rule-guides/doc-inventory-integrity.md).

package/rules/docstring-prose-matches-implementation.md

@@ -12,4 +12,4 @@ The list covers every behavior the body applies, and the body accepts only what
 
 **Enforcement:** `code_rules_docstrings.py` and the JS slices in `code_rules_imports_logging.py`, which the staged policy lint runs through `code_rules_enforcer.py`, plus its `hook-prose-consistency` rule. CI runs it against the merge base.
 
-**Full text:** [`docs/rule-guides/docstring-prose-matches-implementation.md`](../docs/rule-guides/docstring-prose-matches-implementation.md), with the write-time checklist. The Category O audit rubric carries the full standard.
+**Full text:** [guide](../docs/rule-guides/docstring-prose-matches-implementation.md), with the write-time checklist. The Category O audit rubric carries the full standard.

package/rules/explore-thoroughly.md

@@ -6,4 +6,4 @@ Search for what already does the ask, in full or in part. When something exists,
 
 **Enforcement:** the pull request gate denies a body with no "Existing work" section.
 
-**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it for search scope and depth.
+**Full text:** [guide](../docs/rule-guides/explore-thoroughly.md). Read it for search scope and depth.

package/rules/failure-blast-radius.md

@@ -17,4 +17,4 @@ Four failures end a run: the source bytes changed, a provenance or digest mismat
 
 **Enforcement:** `code_rules_blast_radius.py`, which the staged policy lint runs through `code_rules_enforcer.py` under its `code-rules` rule. CI runs it against the merge base.
 
-**Full text:** [`docs/rule-guides/failure-blast-radius.md`](../docs/rule-guides/failure-blast-radius.md), with the boundary example and the Codex excerpt.
+**Full text:** [guide](../docs/rule-guides/failure-blast-radius.md), with the boundary example and the Codex excerpt.

package/rules/falsify-before-green.md

@@ -15,6 +15,6 @@ paths:
 
 Apply a named break that the same check must catch, and run a passing control beside it on the same command. Record the break, its failing output, and the control before counting the restored green as evidence. If the check stays green under its break, fix its reach; a probe needs a trip input, a sweep needs a planted violation in its claimed file set, and a writer assertion needs a disabled production writer.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/falsify-before-green.md`](../docs/rule-guides/falsify-before-green.md). Read it when designing a break or reviewing a red record.
+**Full text:** [guide](../docs/rule-guides/falsify-before-green.md). Read it when designing a break or reviewing a red record.

package/rules/features-start-with-an-eval.md

@@ -0,0 +1,9 @@
+# Features start with an eval
+
+**When:** A user asks for a new feature or a change in behavior.
+
+Your first action is the Skill tool with skill `claude-api` and args `build-eval`. Build the feature against that eval. When the work touches an existing feature with no eval, start a separate session to build that eval in parallel. An Agent-tool subagent does not count. You own its result.
+
+**Enforcement:** `hooks/blocking/pr_lifecycle_skill_gate.py` denies a `feat` pull request with no "Eval" section or no build-eval call.
+
+**Full text:** [guide](../docs/rule-guides/features-start-with-an-eval.md).

package/rules/filesystem-search.md

@@ -2,8 +2,8 @@
 
 **When:** Searching for files by name, path, extension, size, or date.
 
-Scope every search to a project, worktree, package, or narrowing filter. Never start at a filesystem root, drive root, bare home, or share root. Read a known path directly; use scoped `es.exe`, Glob, or Grep for discovery. After `es.exe` Error 8, retry twice before falling back within the same scope. Run one large shell walk at a time. Ask the user only after available search tools fail.
+Scope every search to a project, worktree, package, or narrowing filter. Never start at a filesystem root, drive root, bare home, or share root. Read a known path directly; use scoped `es.exe`, Glob, or Grep for discovery. After `es.exe` Error 8, retry twice before falling back within the same scope. Run one large shell walk at a time.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/filesystem-search.md`](../docs/rule-guides/filesystem-search.md). Read it for tool selection and search examples.
+**Full text:** [guide](../docs/rule-guides/filesystem-search.md). Read it for tool selection and search examples.

package/rules/flag-non-breaking-findings.md

@@ -15,6 +15,6 @@ paths:
 
 Give every check ID a breaking or smell severity row; style and structure findings are smells. Fail the gate and stop for a bug, secret, broken test, syntax error, or instruction file that cannot load. Record a smell in `.claude/followups/smells.jsonl`, proceed, and fix it later in one combined follow-up pull request per parent pull request, whose body names the parent as `Follow-up to #N`; ledger failure leaves the gate decision unchanged. Treat an unclassified check as breaking.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/flag-non-breaking-findings.md`](../docs/rule-guides/flag-non-breaking-findings.md). Read it when adding a check.
+**Full text:** [guide](../docs/rule-guides/flag-non-breaking-findings.md). Read it when adding a check.

package/rules/long-horizon-autonomy.md

@@ -10,6 +10,6 @@ paths:
 
 Act on settled facts and authority, and recommend after researching unclear intent. When protected or irreversible actions, scope changes, or user-only input block the task, ask for one answer in the user-facing channel, name what resumes, and keep other work moving. Finish owed work without ending a turn on a promise, milestone, or context limit. Delegate independent tracks while working, ground claims in tool output, name skipped checks, make the first update one sentence, reserve later updates for discoveries, and close with the outcome and input.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** none.
 
-**Full text:** [`docs/rule-guides/long-horizon-autonomy.md`](../docs/rule-guides/long-horizon-autonomy.md). Read it when preparing the run.
+**Full text:** [guide](../docs/rule-guides/long-horizon-autonomy.md). Read it when preparing the run.