claude-dev-env 8.62.1 → 8.64.0

package/.agents/skills/context-audit/scripts/context_sources.py

@@ -0,0 +1,252 @@
+"""Read checkout files and measure them as context rows.
+
+A row records one loaded file: its size, its links out, and its depth mode.
+The helpers here read text, parse frontmatter, and follow links and imports.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from context_audit_constants.config import constants
+from context_audit_constants.config.constants import DepthMode, RowKind, Trigger
+
+
+@dataclass(frozen=True)
+class ContextRow:
+    """One file an agent loads, with its size and how it loads."""
+
+    path: str
+    kind: RowKind
+    loader: str
+    trigger: Trigger
+    bytes: int
+    lines: int
+    est_tokens: int
+    links_out: int
+    depth_mode: DepthMode
+    cap: int | None
+    note: str
+
+
+@dataclass(frozen=True)
+class RowSource:
+    """Where a row's file sits and how the agent reaches it."""
+
+    path: str
+    kind: RowKind
+    loader: str
+    trigger: Trigger
+    note: str
+
+
+def list_tracked_files(root: Path) -> list[Path]:
+    """Return the tracked files under *root*, minus caches and vendored folders.
+
+    Args:
+        root: A git checkout.
+
+    Returns:
+        Absolute paths of tracked files that exist on disk.
+    """
+    listing = subprocess.run(
+        constants.ALL_GIT_LIST_FILES_ARGUMENTS,
+        cwd=root,
+        capture_output=True,
+        check=True,
+    ).stdout
+    all_paths = [
+        root / os.fsdecode(each_entry)
+        for each_entry in listing.split(constants.GIT_LIST_FILES_SEPARATOR)
+        if each_entry
+    ]
+    return [
+        each_path
+        for each_path in all_paths
+        if not constants.ALL_SKIPPED_PATH_PARTS.intersection(each_path.parts)
+        and each_path.is_file()
+    ]
+
+
+def read_text(path: Path) -> str:
+    """Return the file text, or an empty string when it cannot be read.
+
+    Args:
+        path: The file to read.
+
+    Returns:
+        The decoded text.
+    """
+    try:
+        return path.read_text(
+            encoding=constants.TEXT_ENCODING, errors=constants.TEXT_DECODE_ERRORS
+        )
+    except OSError:
+        return ""
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Return the frontmatter fields of a markdown file as flat strings.
+
+    ::
+
+        ---
+        name: demo
+        paths:
+          - src/**
+        ---
+        -> {"name": "demo", "paths": "- src/**"}
+
+    Args:
+        text: The file text.
+
+    Returns:
+        Field text by field name; empty when the file has no frontmatter.
+    """
+    fence_length = len(constants.FRONTMATTER_FENCE)
+    closing_index = text.find(constants.FRONTMATTER_CLOSING_FENCE, fence_length)
+    if not text.startswith(constants.FRONTMATTER_FENCE) or closing_index == -1:
+        return {}
+    field_by_name: dict[str, str] = {}
+    current_name = ""
+    for each_line in text[fence_length:closing_index].splitlines():
+        current_name = _merge_frontmatter_line(field_by_name, current_name, each_line)
+    return field_by_name
+
+
+def _merge_frontmatter_line(
+    field_by_name: dict[str, str], current_name: str, line: str
+) -> str:
+    field_match = re.match(constants.FRONTMATTER_FIELD_PATTERN, line)
+    if field_match:
+        field_by_name[field_match.group(1)] = field_match.group(2).strip()
+        return field_match.group(1)
+    if current_name and line.startswith(
+        constants.ALL_FRONTMATTER_CONTINUATION_PREFIXES
+    ):
+        field_by_name[current_name] = (
+            f"{field_by_name[current_name]} {line.strip()}".strip()
+        )
+    return current_name
+
+
+def find_relative_links(source: Path, text: str, root: Path) -> list[Path]:
+    """Return the files inside *root* that markdown links in *text* point to.
+
+    Args:
+        source: The file the text came from.
+        text: Markdown text.
+        root: The checkout root.
+
+    Returns:
+        Resolved link targets that exist inside the checkout.
+    """
+    all_targets = [
+        each_target
+        for each_target in re.findall(constants.LINK_PATTERN, text)
+        if not re.match(constants.URL_SCHEME_PATTERN, each_target)
+    ]
+    return _existing_inside(source, all_targets, root)
+
+
+def find_import_targets(source: Path, text: str, root: Path) -> list[Path]:
+    """Return the files inside *root* that ``@path`` import lines name.
+
+    Args:
+        source: The instruction file the text came from.
+        text: The instruction text.
+        root: The checkout root.
+
+    Returns:
+        Resolved import targets that exist inside the checkout.
+    """
+    return _existing_inside(source, re.findall(constants.IMPORT_PATTERN, text), root)
+
+
+def _existing_inside(source: Path, all_targets: list[str], root: Path) -> list[Path]:
+    all_candidates = [
+        (source.parent / each_target).resolve() for each_target in all_targets
+    ]
+    return [
+        each_candidate
+        for each_candidate in all_candidates
+        if each_candidate.is_file() and root in each_candidate.parents
+    ]
+
+
+def classify_depth(
+    cap: int | None, byte_count: int, line_count: int, link_count: int
+) -> DepthMode:
+    """Return how much depth a file carries against its cap.
+
+    ::
+
+        classify_depth(20, 0, 0, 0)       -> empty
+        classify_depth(None, 900, 30, 0)  -> reference
+        classify_depth(20, 4000, 64, 2)   -> carries
+        classify_depth(20, 600, 12, 3)    -> points
+
+    Args:
+        cap: The line cap, or None for on-link depth.
+        byte_count: File size in bytes.
+        line_count: File length in lines.
+        link_count: Relative links out of the file.
+
+    Returns:
+        The depth mode; a file over cap lines, or over cap times 120 bytes, carries.
+    """
+    if byte_count <= constants.EMPTY_FILE_BYTE_LIMIT:
+        return DepthMode.EMPTY
+    if cap is None:
+        return DepthMode.REFERENCE
+    if line_count > cap or byte_count > cap * constants.CHARACTERS_PER_CAPPED_LINE:
+        return DepthMode.CARRIES
+    return DepthMode.POINTS if link_count else DepthMode.LEAN
+
+
+def count_lines(text: str) -> int:
+    """Return the line count of *text*, counting a final unterminated line.
+
+    Args:
+        text: Any text.
+
+    Returns:
+        The number of lines.
+    """
+    has_unterminated_tail = bool(text) and not text.endswith(constants.LINE_BREAK)
+    return text.count(constants.LINE_BREAK) + int(has_unterminated_tail)
+
+
+def measure_row(
+    source: RowSource, text: str, cap: int | None, link_count: int
+) -> ContextRow:
+    """Return the row for *text* loaded from *source*.
+
+    Args:
+        source: Where the file sits and how it loads.
+        text: The text the agent receives.
+        cap: The line cap, or None for on-link depth.
+        link_count: Relative links out of the text.
+
+    Returns:
+        The measured row.
+    """
+    byte_count = len(text.encode(constants.TEXT_ENCODING))
+    line_count = count_lines(text)
+    return ContextRow(
+        path=source.path,
+        kind=source.kind,
+        loader=source.loader,
+        trigger=source.trigger,
+        bytes=byte_count,
+        lines=line_count,
+        est_tokens=round(byte_count / constants.BYTES_PER_ESTIMATED_TOKEN),
+        links_out=link_count,
+        depth_mode=classify_depth(cap, byte_count, line_count, link_count),
+        cap=cap,
+        note=source.note,
+    )

package/.agents/skills/context-audit/scripts/test_context_audit.py

@@ -0,0 +1,217 @@
+"""Behavior tests for the context audit, run as a command on a temporary git checkout."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = Path(__file__).resolve().parent / "context_audit.py"
+
+
+def write_file(root: Path, relative_path: str, text: str) -> None:
+    target = root / relative_path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+
+
+def numbered_lines(count: int) -> str:
+    return "".join(f"line {each_index}\n" for each_index in range(count))
+
+
+@pytest.fixture
+def checkout(tmp_path: Path) -> Path:
+    root = tmp_path / "sample-repo"
+    write_file(root, "CLAUDE.md", "@AGENTS.md\n@docs/shared.md\n")
+    write_file(root, "AGENTS.md", numbered_lines(30))
+    write_file(root, "docs/shared.md", "Shared steps. See [deep](deep.md).\n")
+    write_file(root, "docs/deep.md", "Deep notes. See [deeper](deeper.md).\n")
+    write_file(root, "docs/deeper.md", "Deeper notes.\n")
+    write_file(root, "nested/CLAUDE.md", "")
+    write_file(
+        root,
+        ".claude/rules/api.md",
+        "---\npaths:\n  - src/api/**\n---\nUse the client.\n",
+    )
+    write_file(root, ".claude/rules/general.md", "Keep diffs small.\n")
+    write_file(
+        root,
+        ".claude/skills/demo/SKILL.md",
+        "---\nname: demo\ndescription: Run the demo. Use when asked to demo.\n---\n"
+        + numbered_lines(250),
+    )
+    write_file(root, ".claude/skills/demo/references/guide.md", "Guide body.\n")
+    write_file(
+        root,
+        ".claude/skills/quiet/SKILL.md",
+        "---\nname: quiet\ndescription: Hidden.\ndisable-model-invocation: true\n---\nBody.\n",
+    )
+    write_file(
+        root, "tests/fixture/.claude/skills/ghost/SKILL.md", "---\nname: ghost\n---\n"
+    )
+    write_file(root, "tool.py", '"""' + numbered_lines(20) + '"""\n')
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    return root
+
+
+def run_audit(*all_arguments: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH), *all_arguments],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def audit_rows(
+    checkout: Path, tmp_path: Path, *all_extra_arguments: str
+) -> dict[tuple[str, str], dict]:
+    rows_path = tmp_path / "rows.jsonl"
+    completed = run_audit(str(checkout), "--rows", str(rows_path), *all_extra_arguments)
+    assert completed.returncode == 0, completed.stderr
+    all_rows = [
+        json.loads(each_line) for each_line in rows_path.read_text().splitlines()
+    ]
+    return {(each_row["path"], each_row["kind"]): each_row for each_row in all_rows}
+
+
+def test_root_instructions_load_at_session_start_and_carry_when_over_cap(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    agents_row = row_by_key[("AGENTS.md", "instructions")]
+    assert agents_row["trigger"] == "session-start"
+    assert agents_row["loader"] == "@import from CLAUDE.md"
+    assert agents_row["lines"] == 30
+    assert agents_row["depth_mode"] == "carries"
+    assert row_by_key[("CLAUDE.md", "instructions")]["depth_mode"] == "lean"
+
+
+def test_nested_empty_instructions_load_on_folder_enter_as_empty(
+    checkout: Path, tmp_path: Path
+) -> None:
+    nested_row = audit_rows(checkout, tmp_path)[("nested/CLAUDE.md", "instructions")]
+    assert nested_row["trigger"] == "folder-enter"
+    assert nested_row["depth_mode"] == "empty"
+
+
+def test_import_loads_with_importer_and_its_links_follow_on_demand(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert row_by_key[("docs/shared.md", "import")]["trigger"] == "session-start"
+    assert row_by_key[("docs/shared.md", "import")]["depth_mode"] == "points"
+    deep_row = row_by_key[("docs/deep.md", "linked-doc")]
+    deeper_row = row_by_key[("docs/deeper.md", "linked-doc")]
+    assert (deep_row["trigger"], deep_row["depth_mode"], deep_row["note"]) == (
+        "on-link",
+        "reference",
+        "link depth 1",
+    )
+    assert deeper_row["note"] == "link depth 2"
+
+
+def test_rule_with_paths_loads_on_path_match_and_plain_rule_at_session_start(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert row_by_key[(".claude/rules/api.md", "rule")]["trigger"] == "path-match"
+    assert (
+        row_by_key[(".claude/rules/general.md", "rule")]["trigger"] == "session-start"
+    )
+
+
+def test_skill_yields_listing_body_and_reference_rows(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    description_row = row_by_key[(".claude/skills/demo/SKILL.md", "skill-description")]
+    body_row = row_by_key[(".claude/skills/demo/SKILL.md", "skill-body")]
+    reference_row = row_by_key[
+        (".claude/skills/demo/references/guide.md", "skill-reference")
+    ]
+    assert (description_row["trigger"], description_row["depth_mode"]) == (
+        "session-start",
+        "points",
+    )
+    assert (body_row["trigger"], body_row["depth_mode"]) == ("skill-invoke", "carries")
+    assert reference_row["trigger"] == "on-link"
+
+
+def test_disabled_skill_has_no_listing_and_fixture_skill_is_skipped(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert (".claude/skills/quiet/SKILL.md", "skill-description") not in row_by_key
+    assert (".claude/skills/quiet/SKILL.md", "skill-body") in row_by_key
+    assert not any(
+        each_path.startswith("tests/") and each_kind.startswith("skill")
+        for each_path, each_kind in row_by_key
+    )
+
+
+def test_module_docstring_loads_on_file_open_and_carries_over_cap(
+    checkout: Path, tmp_path: Path
+) -> None:
+    docstring_row = audit_rows(checkout, tmp_path)[("tool.py", "docstring")]
+    assert (
+        docstring_row["trigger"],
+        docstring_row["depth_mode"],
+        docstring_row["cap"],
+    ) == ("file-open", "carries", 15)
+
+
+def test_saved_hook_text_counts_at_session_start(
+    checkout: Path, tmp_path: Path
+) -> None:
+    hook_text_file = tmp_path / "hook-banner.txt"
+    hook_text_file.write_text(numbered_lines(3), encoding="utf-8")
+    row_by_key = audit_rows(
+        checkout, tmp_path, "--session-start-text", str(hook_text_file)
+    )
+    hook_row = row_by_key[("hook-banner.txt", "hook-text")]
+    assert (hook_row["trigger"], hook_row["lines"], hook_row["depth_mode"]) == (
+        "session-start",
+        3,
+        "lean",
+    )
+
+
+def test_report_lists_each_cleanup_section(checkout: Path) -> None:
+    completed = run_audit(str(checkout))
+    assert completed.returncode == 0, completed.stderr
+    carries_section, _, after_carries = completed.stdout.partition(
+        "## Empty instruction stubs"
+    )
+    stubs_section, _, split_section = after_carries.partition("## Long skills to split")
+    assert "| AGENTS.md | instructions | session-start | 30 | 20 |" in carries_section
+    assert "| tool.py | docstring | file-open | 20 | 15 |" in carries_section
+    assert "SKILL.md" not in carries_section
+    assert stubs_section.strip() == "- nested/CLAUDE.md (instructions)"
+    assert (
+        "| .claude/skills/demo/SKILL.md | 254 | 200 |"
+        in split_section.split("\n", 3)[3]
+    )
+
+
+def test_command_option_is_gone_and_text_file_must_exist(
+    checkout: Path, tmp_path: Path
+) -> None:
+    rejected = run_audit(str(checkout), "--session-start-command", "echo hi")
+    assert rejected.returncode == 2
+    assert "unrecognized arguments" in rejected.stderr
+    missing = run_audit(
+        str(checkout), "--session-start-text", str(tmp_path / "absent.txt")
+    )
+    assert missing.returncode == 2
+    assert "file not found" in missing.stderr
+
+
+def test_folder_outside_git_is_refused(tmp_path: Path) -> None:
+    completed = run_audit(str(tmp_path))
+    assert completed.returncode == 2
+    assert "not a git checkout" in completed.stderr

package/.agents/skills/search-before-acting/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: search-before-acting
+description: >-
+  Search for what already does an ask before logging, planning, delegating,
+  or building it, then report what exists in four points and wait for the
+  user. Use when a user asks for new or changed behavior, a tool, a check,
+  a workflow, a report, a tracker entry, or a plan, and before writing a
+  brief for a worker.
+---
+
+# Search before acting
+
+The user should hear about work that already does their ask before anyone duplicates it. Search first, report what you find, and let the user decide what to add.
+
+## Steps
+
+1. Restate the ask as the outcome the user wants, in their words.
+2. Search every place in [`references/search-places.md`](references/search-places.md) that this session can reach. Note each place you could not reach.
+3. Sort each hit as full, partial, or related. A hit is full when it already produces the outcome from step 1.
+4. When any hit is full or partial, stop. Send the four-point report from [`references/report-shape.md`](references/report-shape.md) and wait for the user. When a hit is full, tell the user they already have it.
+5. When nothing is found, say where you looked in one line, then continue with the playbook below.
+
+## Playbooks
+
+Open the playbook that matches the next move.
+
+| Next move | Playbook |
+|---|---|
+| Build or change code, a hook, a skill, a rule, a workflow, or config | [`playbooks/build.md`](playbooks/build.md) |
+| Log the ask in a tracker, or write a plan for it | [`playbooks/plan-or-log.md`](playbooks/plan-or-log.md) |
+| Hand the ask to a worker, a thread, or another session | [`playbooks/delegate.md`](playbooks/delegate.md) |
+
+## Layout
+
+| File | What it holds |
+|---|---|
+| `SKILL.md` | The steps and the playbook index |
+| `references/search-places.md` | Where to search, with the query to run in each place |
+| `references/report-shape.md` | The four-point report and the "you already have it" answer |
+| `playbooks/build.md` | The search and report before a build, and the pull request section |
+| `playbooks/plan-or-log.md` | The search and report before a tracker entry or plan |
+| `playbooks/delegate.md` | The search before a brief, and what the brief carries |

package/.agents/skills/search-before-acting/playbooks/build.md

@@ -0,0 +1,18 @@
+# Build
+
+Use this playbook before you build or change code, a hook, a skill, a rule, a workflow, or config for an ask.
+
+1. Run the skill steps. Search the places in [`../references/search-places.md`](../references/search-places.md), with production config and launcher options first when the ask names a running system.
+2. When a hit is full or partial, send the [report](../references/report-shape.md) and wait for the user's answer.
+3. When the user says go, build only the missing part from point 3 of the report. Extend the existing piece where it lives. Start a new piece only when the existing one cannot hold the addition, and say why in the pull request.
+4. When nothing exists, follow `prefer-existing-tools.md` to check open-source options, then build.
+5. Add an "Existing work" section to the pull request body. List each hit with its link or `file:line` and what the pull request adds on top of it. When nothing was found, say so and name the places searched. The pull request gate denies a body without this section.
+
+Example section:
+
+```markdown
+## Existing work
+
+- `scripts/run_batch.py:40` already runs jobs in parallel with `--workers`. This pull request adds a per-job timeout on top of it.
+- Searched open and merged pull requests for "timeout" and "workers"; none add a timeout.
+```

package/.agents/skills/search-before-acting/playbooks/delegate.md

@@ -0,0 +1,9 @@
+# Delegate
+
+Use this playbook before you hand an ask to a worker, a thread, or another session.
+
+1. Run the skill steps yourself before you write the brief. The worker starts from your search.
+2. When a hit is full or partial, send the user the [report](../references/report-shape.md) and wait. Delegate only after the user says go.
+3. Put the search result in the brief. Name each existing piece with its link or `file:line`, what it covers, and the missing part the worker builds.
+4. When nothing exists, put the places searched in the brief, so the worker skips them and searches what you could not reach.
+5. Ask the worker to report any existing piece it finds that the brief missed, and to stop on it before it builds.

package/.agents/skills/search-before-acting/playbooks/plan-or-log.md

@@ -0,0 +1,9 @@
+# Plan or log
+
+Use this playbook before you add an ask to a tracker, open an issue or card for it, or write a plan for it.
+
+1. Run the skill steps. Search open and closed tracker entries for the ask first, then the rest of [`../references/search-places.md`](../references/search-places.md).
+2. When a tracker entry already names the ask, update that entry and link it. Skip the new entry.
+3. When code, config, or a merged pull request already does the ask in full or in part, send the [report](../references/report-shape.md) and wait for the user before you log or plan.
+4. When the user says go, log or plan only the missing part. Link each existing piece in the entry or plan, so the reader starts from what is live.
+5. When nothing exists, write the entry or plan with one line that names the places searched.

package/.agents/skills/search-before-acting/references/report-shape.md

@@ -0,0 +1,14 @@
+# Report shape
+
+Send this report when the search finds something that does the ask in full or in part. Send it before any log entry, plan, brief, or edit, and wait for the user.
+
+1. **What exists and where.** Each hit with a link or `file:line`, and whether it is live.
+2. **What it covers of the ask.** The parts of the outcome it already produces.
+3. **What is missing.** The parts of the outcome nothing produces yet.
+4. **What the addition would add.** What the new work gives on top of what exists, and the smallest change that closes the gap.
+
+When nothing is missing, the report is one line: the user already has it, with the link and how to use it.
+
+When a place in [`search-places.md`](search-places.md) was out of reach, add one line naming it and the check that would reach it.
+
+Keep the report as short as the user's channel asks for. When the channel limits length, put the four points in a linked file and send a short message that says what exists, what is missing, and what the user decides.

package/.agents/skills/search-before-acting/references/search-places.md

@@ -0,0 +1,26 @@
+# Search places
+
+Search each place this session can reach. Start from the outcome words in the ask and from the names of the systems it touches. Try two or three phrasings, since an existing feature often uses different words than the ask, such as "workers" for "parallel" or "queue" for "batch".
+
+| Place | What to run |
+|---|---|
+| Repository code | `rg -i "<outcome words>"` across each repository the work touches, and a search for the system's entry points and their flags, such as `--help` output and argument parsers |
+| Open pull requests | `gh pr list --state open --search "<words>"`, or the GitHub search tool with `is:pr is:open` |
+| Merged pull requests | `gh pr list --state merged --search "<words>"`, and `git log --oneline -i --grep "<words>"` on the default branch |
+| Hooks | the hook registry, such as `hooks.json` or `settings.json`, and the hook directories, for a gate or reminder that already does the step |
+| Rules and instructions | `rules/`, `AGENTS.md`, `CLAUDE.md`, project instructions, and memory notes |
+| Skills and commands | the installed skills list, `skills/`, `.agents/skills/`, and `commands/` |
+| Workflows and schedules | `.github/workflows/`, scheduled routines, cron entries, and task schedulers |
+| Trackers | open and closed issues, project boards, and task cards that name the ask |
+| Production config | config files, environment settings, feature flags, and launcher options that the running system reads, including values that turn on a mode the ask describes |
+| Run logs and dashboards | recent run output that shows the behavior already happening |
+
+## What to record for each hit
+
+- The place and a link or `file:line`.
+- One sentence on what it does now.
+- Whether it is live: merged and running, merged and unused, or still open.
+
+## When a place is out of reach
+
+Name the place and the check that would reach it, such as "the production config on the build machine, read through a remote session". The report states the gap. The user may know the answer at once.

package/bin/ever-shipped-skills.mjs

@@ -18,6 +18,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'condensing-instructions',
     'codex-review',
     'codex-cleanse',
+    'context-audit',
     'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',
@@ -94,6 +95,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'reviewer-gates',
     'reviews',
     'run-claude-dev-env',
+    'search-before-acting',
     'second-account-workers',
     'session-continuity',
     'session-log',

package/bin/ever-shipped-skills.test.mjs

@@ -45,6 +45,10 @@ test('EVER_SHIPPED_SKILL_NAMES includes the correction skill', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('correction'), true);
 });
 
+test('EVER_SHIPPED_SKILL_NAMES includes the search before acting skill', () => {
+    assert.equal(EVER_SHIPPED_SKILL_NAMES.has('search-before-acting'), true);
+});
+
 test('EVER_SHIPPED_SKILL_NAMES includes the windows scheduled task skill', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('windows-scheduled-task'), true);
 });

package/docs/rule-guides/explore-thoroughly.md

@@ -6,6 +6,16 @@ Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.c
 
 Note: This deliberately chooses exploration depth over the "commit and execute quickly" pattern from the same source. Thorough upfront exploration is preferred for the intended workflow.
 
+## Search for existing work first
+
+Before you log, plan, delegate, or build an ask, search for what already does it in full or in part. An ask is any request for new or changed behavior, a tool, a check, a workflow, a report, a tracker entry, or a plan. The `search-before-acting` skill holds the search places, the four-point report, and a playbook for each next move.
+
+When the search finds something, stop before you act and report what exists and where, what it covers of the ask, what is missing, and what the addition would add. When it covers the whole ask, tell the user they already have it. When the search finds nothing, say where you looked and continue.
+
+[`prefer-existing-tools.md`](../../rules/prefer-existing-tools.md) and [`build-needs-a-user.md`](../../rules/build-needs-a-user.md) load only when a session touches a script, hook, or manifest path. This rule loads in every session, so the search comes before the plan is set.
+
+The pull request gate reads the body of each new pull request for an "Existing work" heading. Under it, list what the search found with a link or `file:line` and what the pull request adds on top of it, or state that nothing was found and name the places searched.
+
 ## Before committing to an approach
 
 - Read the relevant files. Understand what exists before proposing what to change.

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -53,7 +53,7 @@ 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_proof_reason
+from blocking.pull_request_proof import missing_existing_work_reason, missing_proof_reason
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -199,7 +199,7 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for an unloaded skill, a new pull request with no proof, or a second follow-up.
+    """Return a deny for an unloaded skill, a new pull request with no proof or existing-work section, or a second follow-up.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -211,6 +211,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     proof_reason = missing_proof_reason(all_payload_fields)
     if proof_reason is not None:
         return _deny(proof_reason)
+    search_reason = missing_existing_work_reason(all_payload_fields)
+    if search_reason is not None:
+        return _deny(search_reason)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)