claude-dev-env 8.66.0 → 8.68.0

package/docs/rule-guides/proof-before-pull-request.md

@@ -12,7 +12,7 @@ What counts as proof:
 - You ran the changed thing the way its user runs it, and you saw the effect it exists to produce. A hook fires in a live Claude Code session and changes what that session does. A script runs from its launcher on inputs like the ones it will meet. A skill or rule changes what a fresh agent does with an ordinary request.
 - You saw the failure first. Run the same scenario without your change and record what goes wrong. The proof is the difference between the two runs.
 - You covered the conditions the change will meet. That includes the case it should leave alone, and for session behavior a fresh session, a resumed session, a later turn, and a session after compaction.
-- The session under test got an ordinary request, worded as a task the way Jon would ask for it.
+- The session under test got an ordinary request, worded as a task the way the owner would ask for it.
 
 Unit tests are welcome as extra evidence. The live run is the proof. A test you edited until it passed proves nothing.
 
@@ -28,10 +28,12 @@ For a change to Claude Code behavior, such as a hook, skill, rule, setting, prom
 
 Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, state the difference between the runs with and without the change, and name anything still unproven.
 
-When you cannot prove it, leave the pull request unopened. Tell Jon in three short sentences what you could not run and which tool would make it possible. A blocked proof is an acceptable result, because it shows where tooling is missing.
+When you cannot prove it, leave the pull request unopened. Tell the owner in three short sentences what you could not run and which tool would make it possible. A blocked proof is an acceptable result, because it shows where tooling is missing.
 
 ## Enforcement
 
 `hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
 
+When the checked-out branch changes a file people see (`.html`, `.htm`, `.css`, `.scss`, `.tsx`, `.jsx`, `.vue`, `.svelte`), the gate also denies a body whose proof section holds no picture: a markdown image, an image URL, or an Artifact page link that shows the screenshots. Render the change, read the screenshot, and put it in the section, so the reader sees what you looked at. When git in the session directory cannot list the branch's changed files, the gate asks for the picture as well.
+
 The gate checks that the section is there and names a command. Whether the run proves the change stays a judgment for the author and the reviewer.

package/docs/templates/artifact-page/README.md

@@ -1,5 +1,16 @@
 # Artifact page template
 
+Two templates live here. Pick the one that fits the ask before you write a line.
+
+| Ask | Template |
+|---|---|
+| A tracker, board, review page or dashboard that people read and click | `template.html` |
+| A picture of how things connect: a map, a flow, who calls what, old next to new. Also any ask for "only visuals" or "no words" | `diagram.html` |
+
+`diagram.html` draws the content in inline SVG: boxes for things, arrows for links, and color for state. Labels are a few words. Text in bordered cards is a tracker, so it never answers a visual-only ask.
+
+Render the page and look at the screenshot before you publish. Headless Chromium renders at least 500 pixels wide, so take the screenshot at 800 wide.
+
 `template.html` is the reference page for any artifact an agent builds: a tracker, a board, a review page, a dashboard. Start from it, keep its structure and house style, and replace the sample data and the parts the new page does not need.
 
 ## What it demonstrates

package/docs/templates/artifact-page/diagram.html

@@ -0,0 +1,50 @@
+<title>Flow Diagram</title>
+<style>
+:root {
+  --bg: #f4f5f7; --surface: #ffffff; --fg: #1b2230; --line: #6b7383;
+  --ok: #165737; --ok-soft: #e3f3ea; --bad: #8b2621; --bad-soft: #fbe5e3;
+  --font-body: system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
+  --bg: #12151b; --surface: #1a1f28; --fg: #e6e9ef; --line: #8a94a8;
+  --ok: #6fd3a0; --ok-soft: #173327; --bad: #ffa8a0; --bad-soft: #3a1c1a;
+  color-scheme: dark } }
+:root[data-theme="dark"] {
+  --bg: #12151b; --surface: #1a1f28; --fg: #e6e9ef; --line: #8a94a8;
+  --ok: #6fd3a0; --ok-soft: #173327; --bad: #ffa8a0; --bad-soft: #3a1c1a;
+  color-scheme: dark }
+* { box-sizing: border-box }
+body { background: var(--bg); color: var(--fg); font-family: var(--font-body); margin: 0; padding: 16px }
+svg { display: block; width: 100%; max-width: 960px; height: auto; margin: 0 auto }
+.node rect { stroke-width: 3 }
+.node.ok rect { fill: var(--ok-soft); stroke: var(--ok) }
+.node.bad rect { fill: var(--bad-soft); stroke: var(--bad) }
+.node.caller rect { fill: var(--surface); stroke: var(--line) }
+.node text { fill: var(--fg); font-size: 15px; font-weight: 700; text-anchor: middle; dominant-baseline: middle }
+.edge { fill: none; stroke-width: 3 }
+.edge.ok { stroke: var(--ok) }
+.edge.bad { stroke: var(--bad) }
+.key text { fill: var(--fg); font-size: 14px; font-weight: 700; dominant-baseline: middle }
+</style>
+<svg viewBox="0 0 720 360" role="img" aria-label="Callers on the left point at the source they use on the right">
+  <defs>
+    <marker id="arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z" fill="var(--ok)"/></marker>
+    <marker id="arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z" fill="var(--bad)"/></marker>
+  </defs>
+
+  <g class="key" transform="translate(20 24)">
+    <rect width="18" height="18" rx="4" fill="var(--ok)"/><text x="26" y="9">current</text>
+    <rect x="120" width="18" height="18" rx="4" fill="var(--bad)"/><text x="146" y="9">retire</text>
+  </g>
+
+  <g class="node caller"><rect x="20" y="80" width="200" height="56" rx="12"/><text x="120" y="108">Caller A</text></g>
+  <g class="node caller"><rect x="20" y="180" width="200" height="56" rx="12"/><text x="120" y="208">Caller B</text></g>
+  <g class="node caller"><rect x="20" y="280" width="200" height="56" rx="12"/><text x="120" y="308">Caller C</text></g>
+
+  <g class="node ok"><rect x="480" y="110" width="220" height="64" rx="12"/><text x="590" y="142">Source one</text></g>
+  <g class="node bad"><rect x="480" y="250" width="220" height="64" rx="12"/><text x="590" y="282">Source two</text></g>
+
+  <path class="edge ok" d="M220 108 C350 108 350 142 478 142" marker-end="url(#arrow-ok)"/>
+  <path class="edge bad" d="M220 208 C350 208 350 282 478 282" marker-end="url(#arrow-bad)"/>
+  <path class="edge bad" d="M220 308 C350 308 350 282 478 282" marker-end="url(#arrow-bad)"/>
+</svg>

package/hooks/blocking/artifact_look_gate.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: refuse to publish an artifact page nobody has looked at.
+
+An agent that writes a page and publishes it without rendering it cannot know
+the page matches the ask. The hook walks the session transcript and allows the
+publish only when a Read opened an image file whose modification time is at
+least the page file's::
+
+    Write page.html -> shoot shot.png -> Read shot.png -> publish -> allowed
+    Write page.html -> publish                                    -> refused
+    Read shot.png -> change page.html in any tool -> publish      -> refused
+    Read an image older than the page -> publish                  -> refused
+
+A Read that returned an error, or whose result came before the page's last
+change, does not count. A non-HTML file, an asset
+upload, a non-publish action and an unreadable transcript all pass, so the
+hook never fails closed.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.artifact_look_gate_constants import (
+    ALL_IMAGE_FILE_SUFFIXES,
+    ALL_PAGE_FILE_SUFFIXES,
+    ARTIFACT_ACTION_INPUT_KEY,
+    ARTIFACT_ASSET_INPUT_KEY,
+    ARTIFACT_PUBLISH_ACTION,
+    ARTIFACT_TOOL_NAME,
+    ASSISTANT_ENTRY_TYPE,
+    DENY_DECISION,
+    ENTRY_TIMESTAMP_KEY,
+    FILE_PATH_INPUT_KEY,
+    IMAGE_READING_TOOL_NAME,
+    PRE_TOOL_USE_EVENT_NAME,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    TOOL_RESULT_BLOCK_TYPE,
+    TOOL_USE_BLOCK_TYPE,
+    TRANSCRIPT_DECODE_ERRORS,
+    TRANSCRIPT_ENCODING,
+    TRANSCRIPT_PATH_KEY,
+    UNSEEN_PAGE_REASON_TEMPLATE,
+    USER_ENTRY_TYPE,
+)
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
+)
+from hooks_constants.pr_lifecycle_skill_gate_constants import (
+    PERMISSION_DECISION_REASON_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def _content_blocks(
+    all_entry_fields: dict[str, object], entry_type: str
+) -> list[dict[str, object]]:
+    if all_entry_fields.get("type") != entry_type:
+        return []
+    message = all_entry_fields.get("message")
+    content = message.get("content") if isinstance(message, dict) else None
+    if not isinstance(content, list):
+        return []
+    return [each_block for each_block in content if isinstance(each_block, dict)]
+
+
+def _parsed_entry(transcript_line: str) -> dict[str, object]:
+    try:
+        parsed_line = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return {}
+    return parsed_line if isinstance(parsed_line, dict) else {}
+
+
+def _entry_epoch(all_entry_fields: dict[str, object]) -> float | None:
+    timestamp_text = all_entry_fields.get(ENTRY_TIMESTAMP_KEY)
+    if not isinstance(timestamp_text, str):
+        return None
+    try:
+        return datetime.fromisoformat(timestamp_text.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None
+
+
+def _successful_result_epochs(all_entries: list[dict[str, object]]) -> dict[str, float]:
+    return {
+        str(each_block.get("tool_use_id")): result_epoch
+        for each_entry in all_entries
+        if (result_epoch := _entry_epoch(each_entry)) is not None
+        for each_block in _content_blocks(each_entry, USER_ENTRY_TYPE)
+        if each_block.get("type") == TOOL_RESULT_BLOCK_TYPE and not each_block.get("is_error")
+    }
+
+
+def _tool_calls(all_entries: list[dict[str, object]]) -> list[tuple[str, object, object]]:
+    return [
+        (str(each_block.get("id")), each_block.get("name"), tool_input.get(FILE_PATH_INPUT_KEY))
+        for each_entry in all_entries
+        for each_block in _content_blocks(each_entry, ASSISTANT_ENTRY_TYPE)
+        if each_block.get("type") == TOOL_USE_BLOCK_TYPE
+        and isinstance(tool_input := each_block.get("input"), dict)
+    ]
+
+
+def _is_image_read(tool_name: object, file_path: object) -> bool:
+    return (
+        tool_name == IMAGE_READING_TOOL_NAME
+        and isinstance(file_path, str)
+        and file_path.lower().endswith(ALL_IMAGE_FILE_SUFFIXES)
+    )
+
+
+def _modified_time(file_path: str) -> float | None:
+    try:
+        return Path(file_path).stat().st_mtime
+    except OSError:
+        return None
+
+
+def page_was_looked_at(all_transcript_lines: list[str], page_path: str) -> bool:
+    """Return True when a screenshot made after the page's last change was read.
+
+    The page's modification time covers every way it can change, including a
+    Bash command or a subagent. A Read counts only when it succeeded, its
+    result arrived after the page last changed, and its image file is at
+    least as new as the page.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON record per line.
+        page_path: The file the Artifact call publishes.
+    """
+    page_modified_time = _modified_time(page_path)
+    if page_modified_time is None:
+        return False
+    all_entries = [_parsed_entry(each_line) for each_line in all_transcript_lines]
+    result_epoch_by_id = _successful_result_epochs(all_entries)
+    for each_id, each_tool_name, each_file_path in _tool_calls(all_entries):
+        result_epoch = result_epoch_by_id.get(each_id)
+        if not _is_image_read(each_tool_name, each_file_path) or result_epoch is None:
+            continue
+        image_modified_time = _modified_time(str(each_file_path))
+        if (
+            image_modified_time is not None
+            and image_modified_time >= page_modified_time
+            and result_epoch >= page_modified_time
+        ):
+            return True
+    return False
+
+
+def _published_page_path(all_hook_fields: dict[str, object]) -> str | None:
+    tool_input = all_hook_fields.get(TOOL_INPUT_KEY)
+    if all_hook_fields.get(TOOL_NAME_KEY) != ARTIFACT_TOOL_NAME or not isinstance(tool_input, dict):
+        return None
+    page_path = tool_input.get(FILE_PATH_INPUT_KEY)
+    is_page_publish = (
+        tool_input.get(ARTIFACT_ACTION_INPUT_KEY, ARTIFACT_PUBLISH_ACTION) == ARTIFACT_PUBLISH_ACTION
+        and tool_input.get(ARTIFACT_ASSET_INPUT_KEY) is not True
+        and isinstance(page_path, str)
+        and page_path.lower().endswith(ALL_PAGE_FILE_SUFFIXES)
+    )
+    return page_path if is_page_publish else None
+
+
+def unseen_page_reason(all_hook_fields: dict[str, object]) -> str | None:
+    """Return the refusal for an unseen page publish, or None to allow it.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+    """
+    page_path = _published_page_path(all_hook_fields)
+    transcript_path = all_hook_fields.get(TRANSCRIPT_PATH_KEY)
+    if page_path is None or not isinstance(transcript_path, str):
+        return None
+    try:
+        all_transcript_lines = Path(transcript_path).read_text(
+            encoding=TRANSCRIPT_ENCODING, errors=TRANSCRIPT_DECODE_ERRORS
+        ).splitlines()
+    except OSError:
+        return None
+    if page_was_looked_at(all_transcript_lines, page_path):
+        return None
+    return UNSEEN_PAGE_REASON_TEMPLATE.format(page_path=page_path)
+
+
+def main() -> int:
+    """Read the PreToolUse payload and print a deny decision for an unseen page.
+
+    Returns:
+        0 in every case; the decision travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    refusal_reason = unseen_page_reason(hook_payload)
+    if refusal_reason is not None:
+        sys.stdout.write(
+            json.dumps(
+                {
+                    HOOK_SPECIFIC_OUTPUT_KEY: {
+                        HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+                        PERMISSION_DECISION_KEY: DENY_DECISION,
+                        PERMISSION_DECISION_REASON_KEY: refusal_reason,
+                    }
+                }
+            )
+        )
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -53,7 +53,11 @@ from hooks_constants.hook_specific_output_keys import (
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
 from blocking.followup_pr_dedupe import duplicate_followup_reason
-from blocking.pull_request_proof import missing_existing_work_reason, missing_proof_reason
+from blocking.pull_request_proof import (
+    missing_existing_work_reason,
+    missing_look_reason,
+    missing_proof_reason,
+)
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -214,6 +218,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     search_reason = missing_existing_work_reason(all_payload_fields)
     if search_reason is not None:
         return _deny(search_reason)
+    look_reason = missing_look_reason(all_payload_fields)
+    if look_reason is not None:
+        return _deny(look_reason)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)
 

package/hooks/blocking/pull_request_proof.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+import subprocess
 import sys
 from collections.abc import Mapping
 from pathlib import Path
@@ -16,15 +17,25 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
 from hooks_constants.pull_request_proof_constants import (
     ALL_GH_CREATE_WORDS,
     ALL_PYTHON_PROGRAM_NAMES,
+    ALL_VISIBLE_FILE_SUFFIXES,
+    CHANGED_FILES_SEPARATOR,
     COMMAND_MARKER,
     CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    ALL_DEFAULT_BRANCH_REFERENCES,
+    ALL_HEAD_FLAGS,
+    HEAD_FLAG_ASSIGNMENT_PREFIX,
+    REMOTE_BRANCH_PREFIX,
+    UNREADABLE_CHANGES_REASON,
     EXISTING_WORK_HEADING_PATTERN,
+    GIT_TIMEOUT_SECONDS,
     LINE_SEPARATOR,
     MISSING_BODY_REASON,
     MISSING_EXISTING_WORK_REASON,
+    MISSING_LOOK_REASON,
     MISSING_PROOF_REASON,
     NEXT_HEADING_PATTERN,
     PROOF_HEADING_PATTERN,
+    PROOF_IMAGE_PATTERN,
     PULL_REQUEST_SCRIPT_CREATE_WORD,
     PULL_REQUEST_SCRIPT_NAME,
 )
@@ -118,6 +129,34 @@ def _shell_create_bodies(command: str, working_directory: str) -> list[str | Non
     ]
 
 
+def _head_flag_value(all_create_arguments: list[str]) -> str | None:
+    for each_position, each_argument in enumerate(all_create_arguments):
+        if each_argument in ALL_HEAD_FLAGS and each_position + 1 < len(all_create_arguments):
+            return all_create_arguments[each_position + 1]
+        if each_argument.startswith(HEAD_FLAG_ASSIGNMENT_PREFIX):
+            return each_argument[len(HEAD_FLAG_ASSIGNMENT_PREFIX) :]
+    return None
+
+
+def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return None
+    head_branch = tool_input.get("head")
+    if isinstance(head_branch, str):
+        return head_branch
+    command = tool_input.get("command")
+    if all_payload_fields.get("tool_name") not in SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    all_head_flag_values = [
+        _head_flag_value(all_create_arguments)
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+        if (all_create_arguments := _create_arguments(each_segment)) is not None
+    ]
+    return next((each_value for each_value in all_head_flag_values if each_value), None)
+
+
 def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
     tool_name = all_payload_fields.get("tool_name")
     tool_input = all_payload_fields.get("tool_input")
@@ -181,3 +220,96 @@ def missing_existing_work_reason(all_payload_fields: Mapping[str, object]) -> st
         if each_body is not None and not section_under_existing_work(each_body):
             return MISSING_EXISTING_WORK_REASON
     return None
+
+
+def _git_lines(working_directory: str, *all_git_arguments: str) -> list[str] | None:
+    try:
+        completed = subprocess.run(
+            ["git", "-C", working_directory, *all_git_arguments],
+            capture_output=True,
+            text=True,
+            timeout=GIT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return completed.stdout.splitlines() if completed.returncode == 0 else None
+
+
+def _first_merge_base(working_directory: str, head_reference: str) -> str | None:
+    for each_base_reference in ALL_DEFAULT_BRANCH_REFERENCES:
+        all_merge_base_lines = _git_lines(working_directory, "merge-base", head_reference, each_base_reference)
+        if all_merge_base_lines:
+            return all_merge_base_lines[0]
+    return None
+
+
+def _head_reference(working_directory: str, head_branch: object) -> str | None:
+    if not isinstance(head_branch, str) or not head_branch:
+        return "HEAD"
+    if _git_lines(working_directory, "branch", "--show-current") == [head_branch]:
+        return "HEAD"
+    for each_candidate in (head_branch, REMOTE_BRANCH_PREFIX + head_branch):
+        if _git_lines(working_directory, "rev-parse", "--verify", "--quiet", each_candidate + "^{commit}"):
+            return each_candidate
+    return None
+
+
+def visible_changed_files(working_directory: str, head_branch: object) -> list[str] | None:
+    """Return the changed files people see on the head branch, or None when git cannot tell.
+
+    The head is the checked-out branch, or the named branch or its origin copy
+    when the checkout holds another branch. The base is the first of
+    origin/HEAD, origin/main and main that git can reach::
+
+        checkout on feature, page.html changed -> ["page.html"]
+        named head exists nowhere in the clone  -> None
+        no base reference reachable             -> None
+
+    Args:
+        working_directory: The session directory the hook payload names.
+        head_branch: The head branch a create call names, or None.
+    """
+    if not working_directory:
+        return None
+    head_reference = _head_reference(working_directory, head_branch)
+    if head_reference is None:
+        return None
+    merge_base = _first_merge_base(working_directory, head_reference)
+    if merge_base is None:
+        return None
+    all_changed_paths = _git_lines(working_directory, "diff", "--name-only", merge_base, head_reference)
+    if all_changed_paths is None:
+        return None
+    return [each_path for each_path in all_changed_paths if each_path.lower().endswith(ALL_VISIBLE_FILE_SUFFIXES)]
+
+
+def missing_look_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a pull request changing visible files shows no picture, else None.
+
+    ::
+
+        branch changes page.html, proof has ![after](https://x/after.png) -> None
+        branch changes page.html, proof quotes only command output        -> MISSING_LOOK_REASON
+        branch changes only .py files                                     -> None
+        git cannot read the branch, proof shows no picture                -> UNREADABLE_CHANGES_REASON
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    all_bodies = [each_body for each_body in _create_bodies(all_payload_fields) if each_body is not None]
+    if not all_bodies:
+        return None
+    working_directory = all_payload_fields.get("cwd")
+    all_visible_files = visible_changed_files(
+        str(working_directory or ""), _named_head_branch(all_payload_fields)
+    )
+    if all_visible_files == []:
+        return None
+    for each_body in all_bodies:
+        if re.search(PROOF_IMAGE_PATTERN, proof_section(each_body) or "", re.IGNORECASE):
+            continue
+        if all_visible_files is None:
+            return UNREADABLE_CHANGES_REASON
+        return MISSING_LOOK_REASON.format(changed_files=CHANGED_FILES_SEPARATOR.join(all_visible_files))
+    return None

package/hooks/blocking/reply_length_gate.py

@@ -17,6 +17,13 @@ It denies a colon that joins two clauses on one line, and an em dash::
     ok:   Two checks failed at 9:47, then the list follows:
           (each item on its own line below the colon)
 
+It denies a causal sentence ("so", "because", "caused", "due to",
+"therefore", "means") that carries no inline code, URL, or markdown link
+of its own. A command block in the same reply is no evidence::
+
+    flag: That window was Windows PowerShell without Administrator, so the write did not land.
+    ok:   The write did not land, because the next read printed `Right after write: 1`.
+
 It denies a banned word or phrase, matched whole and case-insensitive::
 
     flag: The cause is likely the cache.
@@ -58,6 +65,7 @@ from hooks_constants.reply_length_gate_constants import (
     ALL_DECISION_CARD_PROSE_KEYS,
     ALL_DECISION_OPTION_PROSE_KEYS,
     ALL_DEFAULT_BANNED_WORDS,
+    ALL_EVIDENCE_PATTERNS,
     ALLOW_EXIT_CODE,
     BANNED_WORD_MESSAGE,
     BANNED_WORD_PART_SEPARATOR,
@@ -66,6 +74,7 @@ from hooks_constants.reply_length_gate_constants import (
     BANNED_WORDS_JSON_KEY,
     BANNED_WORDS_PATH_ENV_VAR,
     BLOCK_EXIT_CODE,
+    CAUSAL_CLAIM_PATTERN,
     CARD_TEXT_SEPARATOR,
     CLAUDE_HOME_DIRECTORY_NAME,
     CONFIG_FILE_ENCODING,
@@ -94,6 +103,7 @@ from hooks_constants.reply_length_gate_constants import (
     TOOL_NAME_KEY,
     UNLINKED_PULL_REQUEST_MESSAGE,
     UNLINKED_PULL_REQUEST_PATTERN,
+    UNSOURCED_CAUSE_MESSAGE,
     URL_PATTERN,
     WORD_PATTERN,
     WORD_SEPARATOR,
@@ -151,6 +161,21 @@ def em_dash_violation(reply_text: str) -> str | None:
     return EM_DASH_MESSAGE
 
 
+def unsourced_cause_violation(reply_text: str) -> str | None:
+    """Return the deny reason for the first causal sentence that cites no evidence itself, or None."""
+    all_sentences = [
+        each_sentence
+        for each_line in LINE_BREAK_PATTERN.split(FENCED_BLOCK_PATTERN.sub(" ", reply_text))
+        for each_sentence in SENTENCE_END_PATTERN.split(each_line)
+    ]
+    for each_sentence in all_sentences:
+        is_causal = CAUSAL_CLAIM_PATTERN.search(INLINE_CODE_PATTERN.sub(" ", each_sentence))
+        has_evidence = any(each_pattern.search(each_sentence) for each_pattern in ALL_EVIDENCE_PATTERNS)
+        if is_causal and not has_evidence:
+            return UNSOURCED_CAUSE_MESSAGE.format(sentence=each_sentence.strip())
+    return None
+
+
 def unlinked_pull_request_violation(reply_text: str) -> str | None:
     """Return the deny reason for a pull request number outside a link, or None."""
     without_fences = FENCED_BLOCK_PATTERN.sub(" ", reply_text)
@@ -231,6 +256,7 @@ def tool_violation(tool_name: object, all_tool_input: dict[str, object]) -> tupl
         or mid_sentence_colon_violation(reply_text)
         or em_dash_violation(reply_text)
         or unlinked_pull_request_violation(reply_text)
+        or unsourced_cause_violation(reply_text)
         or banned_word_violation(reply_text, configured_banned_words())
     )
     return None if violation is None else (violation, reply_text)

package/hooks/blocking/test_artifact_look_gate.py

@@ -0,0 +1,152 @@
+"""Behavior tests for the artifact look gate.
+
+The refused case replays a session that wrote a page and published it with no
+render in between, the way a text-card page reached the person who asked for
+a diagram.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_BLOCKING_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _BLOCKING_DIR.parent
+for each_sys_path_entry in (str(_BLOCKING_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import artifact_look_gate
+
+HOOK_SCRIPT = _BLOCKING_DIR / "artifact_look_gate.py"
+
+
+def _tool_use(call_id: str, tool_name: str, file_path: str) -> dict[str, object]:
+    return {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "id": call_id,
+                    "name": tool_name,
+                    "input": {"file_path": file_path},
+                }
+            ]
+        },
+    }
+
+
+def _tool_result(
+    call_id: str, is_error: bool = False, timestamp: str = "2026-01-01T00:00:00Z"
+) -> dict[str, object]:
+    return {
+        "type": "user",
+        "timestamp": timestamp,
+        "message": {
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": call_id,
+                    "content": "ok",
+                    "is_error": is_error,
+                }
+            ]
+        },
+    }
+
+
+def _run_hook(tmp_path: Path, all_records: list[dict[str, object]], page_path: Path) -> str:
+    transcript_path = tmp_path / "transcript.jsonl"
+    transcript_path.write_text(
+        "".join(json.dumps(each_record) + "\n" for each_record in all_records), encoding="utf-8"
+    )
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(
+            {
+                "hook_event_name": "PreToolUse",
+                "tool_name": "Artifact",
+                "tool_input": {"file_path": str(page_path), "icon": "map"},
+                "transcript_path": str(transcript_path),
+            }
+        ),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return completed.stdout
+
+
+def _file_at(file_path: Path, modified_time: float) -> Path:
+    file_path.write_text("x", encoding="utf-8")
+    os.utime(file_path, (modified_time, modified_time))
+    return file_path
+
+
+def _read_records(
+    image_path: Path, is_error: bool = False, timestamp: str = "2026-01-01T00:00:00Z"
+) -> list[dict[str, object]]:
+    return [_tool_use("r1", "Read", str(image_path)), _tool_result("r1", is_error, timestamp)]
+
+
+def test_should_refuse_a_page_published_without_a_look(tmp_path: Path) -> None:
+    page_path = _file_at(tmp_path / "page.html", 1000)
+    hook_output = json.loads(
+        _run_hook(
+            tmp_path, [_tool_use("w1", "Write", str(page_path)), _tool_result("w1")], page_path
+        )
+    )
+    specific_output = hook_output["hookSpecificOutput"]
+    assert specific_output["permissionDecision"] == "deny"
+    assert "--screenshot" in specific_output["permissionDecisionReason"]
+
+
+def test_should_allow_a_page_whose_newer_screenshot_was_read(tmp_path: Path) -> None:
+    page_path = _file_at(tmp_path / "page.html", 1000)
+    image_path = _file_at(tmp_path / "page.png", 1001)
+    assert _run_hook(tmp_path, _read_records(image_path), page_path) == ""
+
+
+def test_should_refuse_when_the_page_changed_after_the_screenshot(tmp_path: Path) -> None:
+    image_path = _file_at(tmp_path / "page.png", 1000)
+    page_path = _file_at(tmp_path / "page.html", 1001)
+    assert "deny" in _run_hook(tmp_path, _read_records(image_path), page_path)
+
+
+def test_should_refuse_when_the_screenshot_read_failed(tmp_path: Path) -> None:
+    page_path = _file_at(tmp_path / "page.html", 1000)
+    image_path = _file_at(tmp_path / "page.png", 1001)
+    assert "deny" in _run_hook(tmp_path, _read_records(image_path, is_error=True), page_path)
+
+
+def test_should_refuse_a_screenshot_overwritten_after_its_read(tmp_path: Path) -> None:
+    page_path = _file_at(tmp_path / "page.html", 1000)
+    image_path = _file_at(tmp_path / "page.png", 1001)
+    read_before_the_page_changed = "1970-01-01T00:16:39Z"
+    assert "deny" in _run_hook(
+        tmp_path, _read_records(image_path, timestamp=read_before_the_page_changed), page_path
+    )
+
+
+def test_page_was_looked_at_ignores_reads_of_other_files(tmp_path: Path) -> None:
+    page_path = _file_at(tmp_path / "page.html", 1000)
+    notes_path = _file_at(tmp_path / "notes.md", 1001)
+    all_lines = [json.dumps(each_record) for each_record in _read_records(notes_path)]
+    assert not artifact_look_gate.page_was_looked_at(all_lines, str(page_path))
+
+
+def test_unseen_page_reason_passes_non_publish_calls() -> None:
+    assert (
+        artifact_look_gate.unseen_page_reason(
+            {"tool_name": "Artifact", "tool_input": {"action": "read", "url": "x"}}
+        )
+        is None
+    )
+    assert (
+        artifact_look_gate.unseen_page_reason(
+            {"tool_name": "Artifact", "tool_input": {"file_path": "image.png", "asset": True}}
+        )
+        is None
+    )

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -1,6 +1,7 @@
 """Behavior tests for the pull request lifecycle PreToolUse gate."""
 
 import json
+import subprocess
 import sys
 from io import BytesIO, StringIO, TextIOWrapper
 from pathlib import Path
@@ -240,11 +241,24 @@ def test_hook_has_its_own_pre_tool_use_registration() -> None:
     ]
 
 
+def _checkout_without_visible_changes(tmp_path: Path) -> str:
+    checkout_path = tmp_path / "checkout"
+    subprocess.run(["git", "init", "-q", "-b", "main", str(checkout_path)], check=True)
+    (checkout_path / "tool.py").write_text("x = 1\n", encoding="utf-8")
+    subprocess.run(["git", "-C", str(checkout_path), "add", "."], check=True)
+    subprocess.run(
+        ["git", "-C", str(checkout_path), "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "base"],
+        check=True,
+    )
+    return str(checkout_path)
+
+
 def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Path) -> None:
     payload = {
         "tool_name": "mcp__github__create_pull_request",
         "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
+        "cwd": _checkout_without_visible_changes(tmp_path),
     }
     open_followup = {"number": 1769, "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1769", "body": "Follow-up to #1731"}
     with patch.object(gate_dedupe, "read_open_pull_requests", return_value=[open_followup]):
@@ -259,6 +273,7 @@ def test_loaded_skill_allows_a_followup_when_the_read_fails(tmp_path: Path) -> N
         "tool_name": "mcp__github__create_pull_request",
         "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
+        "cwd": _checkout_without_visible_changes(tmp_path),
     }
     with patch.object(gate_dedupe, "read_open_pull_requests", side_effect=OSError("offline")):
         assert gate.decision_for(payload) is None

package/hooks/blocking/test_pull_request_proof.py

@@ -1,5 +1,6 @@
 """Behavior tests for the proof-in-practice and existing-work checks on a new pull request."""
 
+import subprocess
 import sys
 from pathlib import Path
 
@@ -12,6 +13,7 @@ from hooks_constants.pull_request_proof_constants import (
     MISSING_BODY_REASON,
     MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
+    UNREADABLE_CHANGES_REASON,
 )
 
 PROVEN_BODY = "## Summary\nAdds a gate.\n\n## Proof in practice\nRan `python run.py`.\n> denied\n"
@@ -133,3 +135,78 @@ def test_unreadable_body_should_leave_the_deny_to_the_proof_check() -> None:
 def test_other_pull_request_commands_should_pass_the_existing_work_check() -> None:
     for each_command in ("gh pr edit 3 --body x", "git push -u origin b", "gh pr view"):
         assert gate.missing_existing_work_reason(_shell(each_command)) is None
+
+
+def _repository_with_change(tmp_path: Path, changed_file_name: str) -> Path:
+    origin_path = tmp_path / "origin"
+    clone_path = tmp_path / "clone"
+    git_identity = ["-c", "user.name=t", "-c", "user.email=t@example.com"]
+    subprocess.run(["git", "init", "-q", "-b", "main", str(origin_path)], check=True)
+    (origin_path / "readme.md").write_text("base\n", encoding="utf-8")
+    subprocess.run(["git", "-C", str(origin_path), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(origin_path), *git_identity, "commit", "-q", "-m", "base"], check=True)
+    subprocess.run(["git", "clone", "-q", str(origin_path), str(clone_path)], check=True)
+    subprocess.run(["git", "-C", str(clone_path), "checkout", "-q", "-b", "feature"], check=True)
+    (clone_path / changed_file_name).write_text("<p>x</p>\n", encoding="utf-8")
+    subprocess.run(["git", "-C", str(clone_path), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(clone_path), *git_identity, "commit", "-q", "-m", "change"], check=True)
+    return clone_path
+
+
+def _mcp_create_on_branch(body: str, working_directory: Path) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"body": body, "head": "feature"},
+        "cwd": str(working_directory),
+    }
+
+
+def test_should_deny_a_page_change_whose_proof_shows_no_picture(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "page.html")
+    reason = gate.missing_look_reason(_mcp_create_on_branch(PROVEN_BODY, clone_path))
+    assert reason is not None
+    assert "page.html" in reason
+
+
+def test_should_allow_a_page_change_whose_proof_links_a_screenshot(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "page.html")
+    body = PROVEN_BODY + "![after](https://example.com/after.png)\n"
+    assert gate.missing_look_reason(_mcp_create_on_branch(body, clone_path)) is None
+
+
+def test_should_allow_a_python_only_change_without_a_picture(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "tool.py")
+    assert gate.missing_look_reason(_mcp_create_on_branch(PROVEN_BODY, clone_path)) is None
+
+
+def test_visible_changed_files_skips_a_different_head_branch(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "page.html")
+    assert gate.visible_changed_files(str(clone_path), "feature") == ["page.html"]
+    assert gate.visible_changed_files(str(clone_path), "other-branch") is None
+
+
+def test_should_deny_when_git_cannot_read_the_branch_and_proof_shows_no_picture(tmp_path: Path) -> None:
+    payload = _mcp_create_on_branch(PROVEN_BODY, tmp_path)
+    assert gate.missing_look_reason(payload) == UNREADABLE_CHANGES_REASON
+
+
+def test_visible_changed_files_falls_back_to_origin_main_without_origin_head(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "page.html")
+    subprocess.run(["git", "-C", str(clone_path), "remote", "set-head", "origin", "-d"], check=True)
+    subprocess.run(["git", "-C", str(clone_path), "checkout", "-q", "main"], check=True)
+    assert gate.visible_changed_files(str(clone_path), "feature") == ["page.html"]
+
+
+def test_should_read_the_head_flag_of_a_shell_create(tmp_path: Path) -> None:
+    clone_path = _repository_with_change(tmp_path, "page.html")
+    subprocess.run(["git", "-C", str(clone_path), "checkout", "-q", "main"], check=True)
+    body_path = clone_path / "body.md"
+    body_path.write_text(PROVEN_BODY, encoding="utf-8")
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": f"gh pr create --head feature --title t --body-file {body_path}"},
+        "cwd": str(clone_path),
+    }
+    reason = gate.missing_look_reason(payload)
+    assert reason is not None
+    assert "page.html" in reason

package/hooks/blocking/test_reply_length_gate.py

@@ -487,3 +487,55 @@ def test_should_deny_an_em_dash_and_allow_one_in_code(
     )
     assert (denied_code, allowed_code) == (2, 0)
     assert "em dash" in denied_text
+
+
+def test_should_deny_the_quoted_cause_with_no_source(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        POST_TOOL_NAME,
+        {"text": "That window was Windows PowerShell without Administrator, so the write did not land."},
+    )
+    assert exit_code == 2
+    assert "Cause with no source" in stderr_text
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    [
+        "The write did not land, because the next read printed `Right after write: 1`.",
+        "The job failed because of [run 12](https://github.com/owner/repo/actions/runs/12).",
+    ],
+)
+def test_should_allow_a_cause_that_cites_evidence(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text})
+    assert (exit_code, stderr_text) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    [
+        "That window lacked Administrator, so the write did not land.\n\n```powershell\nRestart-Service x\n```",
+        "The error shows the hook is the only line. So the filter wrote nothing.",
+        "One line survived because its start did not match my filter. Run this.",
+    ],
+)
+def test_should_deny_a_cause_whose_own_sentence_cites_nothing(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text})
+    assert exit_code == 2
+    assert "Cause with no source" in stderr_text
+
+
+def test_should_allow_a_reply_with_no_causal_claim(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "The runner restarted. Also, so far so good."}
+    )
+    assert exit_code == 0

package/hooks/features/conduct-gates.md

@@ -4,7 +4,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 ## Checks
 
-- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, and requires a readable link when the text names a pull request number.
+- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, and requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
 - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
@@ -12,6 +12,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
+- `blocking/artifact_look_gate.py` denies an Artifact publish of an HTML page until an image was opened with Read after the page file was last written, so the agent looks at its page before it ships.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 
 ## When it fires
@@ -24,6 +25,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)`, timeout `10` seconds in `hooks.json`.
+- `blocking/artifact_look_gate.py` runs on `PreToolUse`, matcher `Artifact|Skill`, timeout `10` seconds in `hooks.json`. It speaks only on an `Artifact` publish of a `.html` or `.htm` file.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 
 ## Proving it
@@ -50,4 +52,5 @@ Preconditions:
 - The edit marker gate scans replacement cards as well as the message text.
 - The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.
+- **Looked-at page.** Input is a transcript that writes a page and publishes it with no screenshot read after the write. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_look_gate.py -q`. The adjacent test observes a denial that names the screenshot command; a Read of a PNG after the last write passes.
 - The dark mode gate denies a page publish when Node, Playwright or Chromium is missing, and its reason names the install command. It checks both dark signals, `prefers-color-scheme: dark` and `data-theme="dark"` on the root element.

package/hooks/features/session-context.md

@@ -10,7 +10,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
 - `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
-- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/artifact-page/template.html`.
+- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires

package/hooks/hooks.json

@@ -169,6 +169,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/artifact_template_pointer.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/artifact_look_gate.py",
+            "timeout": 10
           }
         ]
       },

package/hooks/hooks_constants/artifact_look_gate_constants.py

@@ -0,0 +1,33 @@
+"""Names and refusal text for the artifact_look_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+ARTIFACT_TOOL_NAME = "Artifact"
+ARTIFACT_ACTION_INPUT_KEY = "action"
+ARTIFACT_PUBLISH_ACTION = "publish"
+ARTIFACT_ASSET_INPUT_KEY = "asset"
+FILE_PATH_INPUT_KEY = "file_path"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+TRANSCRIPT_PATH_KEY = "transcript_path"
+IMAGE_READING_TOOL_NAME = "Read"
+ALL_IMAGE_FILE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp", ".gif")
+ALL_PAGE_FILE_SUFFIXES = (".html", ".htm")
+TRANSCRIPT_ENCODING = "utf-8"
+TRANSCRIPT_DECODE_ERRORS = "replace"
+ASSISTANT_ENTRY_TYPE = "assistant"
+USER_ENTRY_TYPE = "user"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+TOOL_RESULT_BLOCK_TYPE = "tool_result"
+ENTRY_TIMESTAMP_KEY = "timestamp"
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+DENY_DECISION = "deny"
+UNSEEN_PAGE_REASON_TEMPLATE = (
+    "This page has not been looked at since it was last written. Render it "
+    "and look at the picture before you publish: take a screenshot with a "
+    "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."
+)

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -22,6 +22,6 @@ SKILL_TOOL_NAME = "Skill"
 SKILL_NAME_INPUT_KEY = "skill"
 ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
 ARTIFACT_TEMPLATE_PATH = (
-    Path(__file__).resolve().parents[2] / "docs" / "templates" / "artifact-page" / "template.html"
+    Path(__file__).resolve().parents[2] / "docs" / "templates" / "artifact-page" / "README.md"
 )
-POINTER_TEXT_PREFIX = "Build this artifact page from the template at "
+POINTER_TEXT_PREFIX = "Pick the artifact page template that fits the ask from "

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -39,3 +39,28 @@ MISSING_EXISTING_WORK_REASON = (
     + EXISTING_WORK_GUIDE_PATH
     + " for the full rule."
 )
+ALL_VISIBLE_FILE_SUFFIXES = (".html", ".htm", ".css", ".scss", ".tsx", ".jsx", ".vue", ".svelte")
+PROOF_IMAGE_PATTERN = (
+    r"!\[[^\]]*\]\([^)]+\)|https?://\S+?\.(?:png|jpe?g|gif|webp)\b"
+    r"|https://claude\.ai/(?:code/)?artifact/[A-Za-z0-9-]+"
+)
+ALL_DEFAULT_BRANCH_REFERENCES = ("origin/HEAD", "origin/main", "main")
+REMOTE_BRANCH_PREFIX = "origin/"
+ALL_HEAD_FLAGS = frozenset({"--head", "-H"})
+HEAD_FLAG_ASSIGNMENT_PREFIX = "--head="
+GIT_TIMEOUT_SECONDS = 5
+MISSING_LOOK_REASON = (
+    "This pull request changes files people see ({changed_files}), and its 'Proof in"
+    " practice' section shows no picture. Render the change, open the screenshot with the"
+    " Read tool and check it against the ask, then put the screenshot in the section as an"
+    " image link, before and after when the change alters an existing view. Where the session"
+    " cannot upload an image, publish the screenshots as an Artifact page and link it. The person who"
+    " asked sees the same proof you looked at. Read " + PROOF_GUIDE_PATH + " for the full rule."
+)
+CHANGED_FILES_SEPARATOR = ", "
+UNREADABLE_CHANGES_REASON = (
+    "Git in this directory cannot list the files this pull request changes, so the"
+    " picture check cannot tell whether people see the change. Run the create call"
+    " 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."
+)

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -40,6 +40,15 @@ MID_SENTENCE_COLON_MESSAGE = (
     " and put the list on the lines below."
 )
 EM_DASH_MESSAGE = "An em dash is in the text. Use a period or a comma."
+CAUSAL_CLAIM_PATTERN = re.compile(
+    r"(?:^|,)\s*so\b(?!\s+far\b)|\b(?:because|caused|causes|due to|therefore|which means|that means)\b",
+    re.IGNORECASE,
+)
+ALL_EVIDENCE_PATTERNS = (INLINE_CODE_PATTERN, URL_PATTERN, MARKDOWN_LINK_PATTERN)
+UNSOURCED_CAUSE_MESSAGE = (
+    'Cause with no source: "{sentence}". Quote the log line or output in backticks,'
+    " or link the run or file and line that shows it."
+)
 ALL_DEFAULT_BANNED_WORDS = (
     "real",
     "really",

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -136,6 +136,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/session_title_format_gate.py      -> exempt
         hooks/blocking/session_title_stop_gate.py        -> exempt
         hooks/blocking/artifact_dark_mode_gate.py        -> exempt
+        hooks/blocking/artifact_look_gate.py             -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -160,6 +161,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     The verify-before-acting hook runs after a mutating call has finished. It
     asks the model to check a hedged claim, and the call it reads stays in place.
 
+    The artifact look gate denies an Artifact publish of a page until a
+    screenshot of it was read. It decides when a page ships and no code or
+    safety policy.
+
     The session title gates keep the session title in its status format. One
     denies a malformed title, and the other asks for a title before a turn
     ends. They decide the shape of a title and no code or safety policy.

package/scripts/policy_lint/config/constants.py

@@ -72,6 +72,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/session_title_format_gate.py",
     "blocking/session_title_stop_gate.py",
     "blocking/artifact_dark_mode_gate.py",
+    "blocking/artifact_look_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)