claude-dev-env 2.3.0 → 2.5.0

package/CLAUDE.md

@@ -1,83 +1,88 @@
-# Claude Development Assistant
+# Development Assistant
 
-The user is short on time and appreciates brevity in replies. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
+## Advisor consultation
 
-The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
+When the `advisor()` tool is available, reference `~/.claude/docs/references/advisor-tool.md`. For complex tasks, reference `~/.claude/docs/references/team-advisor-skill.md` and use the `/team-advisor` skill.
 
-## Timeless Documentation (all `.md` files)
+## Communication
 
-Docs describe the current state only. Full rule set and enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
+Use direct affirmative framing that states the desired action clearly and positively. Contrastive negation is banned.
 
-## Private values stay out of the committed tree
+Write concise, ADHD-friendly responses.
 
-A value the code needs at run time that is itself private — a host, ssh user or port, owner scope, or id — lives in git-ignored local config with a committed placeholder, not in the source.
+- Always say what is, rather than what is not.
+- Lead with the outcome.
+- Use short, active sentences with one idea each.
+- Put meaning before mechanism.
+- Explain jargon on first use.
+- Use plain-claim headings and bold leads.
+- Limit bullets to two sentences and paragraphs to three.
+- Omit repetition, narration, unnecessary options, and trailing notes.
+- End with what the reader must know or decide.
 
-## Choosing Edit vs Write
+## Execution and security
 
-`Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
+For code tasks, execute available steps directly and minimize manual work.
 
-## Showing Files: Open Them, Don't Print the Path
+Always execute as many parallel workers as you can, when tasks do not overlap or conflict.
 
-When I ask you to "show me", "open", "display", "let me see", or "pull up" a file — an image, PDF, HTML page, document, anything — open it on my screen. Launch the viewer so each image window matches the asset's size:
+Ask when ambiguity materially changes scope or implementation. Collect credentials through secure UI only; never request secrets in chat.
 
-`Start-Process pwsh -WindowStyle Hidden -ArgumentList '-NoProfile','-File',"$HOME\.claude\scripts\Show-Asset.ps1",'<path 1>','<path 2>'`
+A runtime value that is itself private — a host, an SSH user or port, an owner scope, an account ID — lives in git-ignored local configuration with a committed placeholder in its place. Source files never carry the real value.
 
-## Test Philosophy
+## Documentation
 
-When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.
+Describe only the current system state. Keep documentation self-contained and free of historical, transitional, conversational, or version-transition language. Never use negative prose or antipatterns. Always state what to do, specifically.
 
-When writing tests, always ensure you utilize the production code paths instead of duplicating explicitly for the test.
+Follow:
 
-## Research via Subagents
+- `~/.claude/rules/no-historical-clutter.md`
+- `~/.claude/rules/self-contained-docs.md`
+- `~/.claude/skills/condensing-instructions/SKILL.md`
 
-Delegate exploration whose raw content you won't directly edit or reuse. If you'd `Read` more than one file or `Grep` more than one pattern just to extract a fact, dispatch an `Explore` subagent.
+## File edits
 
-Ask the subagent for a specific answer: "return the file:line where X is defined." For multiple unrelated questions, fan out parallel subagents — issue several `Agent` calls in a single response.
+`Edit` changes an existing file. `Write` creates a new file. Default to `Edit`; reach for `Write` only when the path is genuinely new.
 
-Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compose subagent prompts via the protocol in `agent-spawn-protocol`.
+## Files and workspaces
 
-## Target Execution Workflow for Code Tasks
+Put all work in an isolated git worktree, created outside the primary checkout.
 
-Run every multi-step code task in two phases:
+### Code and tests
 
-1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
-2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
+Tests exercise real behavior, real data, and production paths.
 
-Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code (docs, images), a pytest test file by name (`test_*.py`, `*_test.py`, or `conftest.py`), or a Python file whose docstring-stripped AST is unchanged (docstring, comment, or formatting-only edits). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
+For multi-step code tasks:
 
-## Sub-agent Output Validation
+- Assign each scope to its own coder agent.
+- A coder consults a tool-less advisor agent when blocked.
+- A fresh-context verifier agent runs named gates, baseline checks, and a two-way task-to-diff review.
+- Repair only reported findings, then re-verify after every repair.
 
-After any sub-agent returns a PR description, file list, or counts, verify each claim against the actual diff and repo state before using it. Flag and correct any invented paths, fabricated counts, or out-of-scope changes before they land in commits or PR bodies.
+Do not commit, push, or open a PR until verification is clean and the verified-commit gate covers the current diff. The verification requirement is waived only for a non-code diff, or when the Python AST is unchanged after removing docstrings.
 
-## Task Tracking
+Keep changes within scope. Prefer durable systemic fixes for reusable behavior. Do not rewrite entire files or rename public parameters without need.
 
-Track every task with the task tool, always — for all sessions and all tasks. Capture each task with `TaskCreate` as it arrives, mark it `in_progress` with `TaskUpdate` when you start, and `completed` when it is done. Run `/task-build` to gather any open tasks and add them to the list in one pass.
+### Reviews and convergence
 
-## Working in the claude-dev-env Repo
+Report only findings verified against the code. Verify every sub-agent file list, count, description, and finding against the repository and the diff before using it.
 
-When changing how skills, rules, or hooks install or sync in this repo (for example adding a skill), read `docs/references/skill-install-system.md` — it maps the install pipeline in `packages/claude-dev-env/bin/install.mjs`.
+Do not commit untracked files unless explicitly instructed.
 
-## Additional Non-overlapping Rules
+### Research and delegation
 
-- **disambiguate_overloaded_terms:** When a word in the request has two different technical meanings — "conflict" (git-merge versus functional/behavioral), "sync" (fast-forward versus commit), and the like — confirm which one is meant via AskUserQuestion before analyzing or acting.
+Delegate fact extraction when multiple files or search patterns are required. Request precise file-and-line answers.
 
-## Serena (Code Intelligence MCP)
+Use fresh parallel subagents, each named for its task, for unrelated questions at whatever effort level the task needs.
 
-The `mcp__serena__*` tools expose LSP-level code intelligence for any activated project.
+Read or search directly only in files you will actually modify this turn. Delegate broader fact-finding to a subagent instead of reading widely yourself.
 
-### CRITICAL: Call `initial_instructions` first
-Before any coding task, call the `initial_instructions` tool to load the Serena Instructions Manual.
+For code navigation, prefer a semantic code-navigation tool (an MCP server such as Serena, when available) or a fast file-search tool (such as Everything's `es.exe` on Windows, when available), then fall back to content search or globbing. Scope every search to a project directory. Never scan an entire drive or network share.
 
-### When to use Serena
-- **Symbol declaration** → `mcp__serena__find_declaration`
-- **All references to a symbol** → `mcp__serena__find_referencing_symbols`
-- **Implementations of an interface/class** → `mcp__serena__find_implementations`
-- **Rename across codebase** → `mcp__serena__rename_symbol`
-- **Targeted body replacement / insertion** → `replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol`
-- **Safe symbol removal (no references)** → `mcp__serena__safe_delete_symbol`
-- **File diagnostics** → `mcp__serena__get_diagnostics_for_file`
+### Task tracking
 
-### Tool hierarchy for code navigation
-1. **Serena** — symbol-level navigation (declarations, references, implementations, rename)
-2. **es.exe** — file-system search by name/path/extension/size/date (Everything CLI)
-3. **Grep/Glob** — content and pattern matching
+Track every task with the harness's task tool (TaskCreate/TaskUpdate) or the `task-build` skill: `~/.claude/skills/task-build/SKILL.md`.
+
+## Definitions
+
+Warm agent: any agent who has acted within the past 30 minutes.

package/_shared/pr-loop/scripts/_claude_permissions_common.py

@@ -18,9 +18,11 @@ from pathlib import Path
 from typing import NoReturn
 
 from pr_loop_shared_constants.claude_permissions_constants import (
+    ALL_INERT_FILE_PERMISSION_TOOLS,
     ALL_TRUST_ENTRY_PROJECT_PATH_BOUNDARY_QUOTE_CHARACTERS,
     CLAUDE_SETTINGS_DIRECTORY_NAME,
     GIT_DIRECTORY_NAME,
+    HOME_PROJECT_PATH_ALIAS,
     TEXT_FILE_ENCODING as TEXT_FILE_ENCODING,
     UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH,
 )
@@ -80,6 +82,88 @@ def get_current_project_path() -> str:
     return normalized_project_path
 
 
+def permission_rule_tool_name(permission_rule: object) -> str | None:
+    """Return the tool name prefix of a Claude permission rule, or None.
+
+    ::
+
+        permission_rule_tool_name("Edit(/repo/.claude/**)")  # ok: "Edit"
+        permission_rule_tool_name(42)  # ok: None
+
+    Args:
+        permission_rule: A Claude settings allow/deny rule value.
+
+    Returns:
+        The tool name before the first ``(``, or None when the value is not a
+        well-formed rule string.
+    """
+    if not isinstance(permission_rule, str):
+        return None
+    opening_parenthesis_index = permission_rule.find("(")
+    if opening_parenthesis_index <= 0:
+        return None
+    return permission_rule[:opening_parenthesis_index]
+
+
+def is_inert_file_permission_rule(permission_rule: object) -> bool:
+    """Return True when a rule uses Write/Glob/NotebookEdit (ignored for files).
+
+    ::
+
+        is_inert_file_permission_rule("Write(/wt/.claude/**)")  # ok: True
+        is_inert_file_permission_rule("Edit(/repo/.claude/**)")  # ok: False
+
+    Args:
+        permission_rule: A Claude settings allow/deny rule value.
+
+    Returns:
+        True when the rule's tool is in ALL_INERT_FILE_PERMISSION_TOOLS.
+    """
+    tool_name = permission_rule_tool_name(permission_rule)
+    if tool_name is None:
+        return False
+    return tool_name in ALL_INERT_FILE_PERMISSION_TOOLS
+
+
+def all_project_path_aliases_for_reap(
+    project_path: str,
+    home_directory_path: str | None = None,
+) -> tuple[str, ...]:
+    """Return project path forms a revoke run should match when removing rules.
+
+    ::
+
+        all_project_path_aliases_for_reap("/repo")  # ok: ("/repo",)
+        all_project_path_aliases_for_reap("/home/u", home_directory_path="/home/u")
+            # ok: ("/home/u", "$HOME")
+
+    Always includes the absolute POSIX project path. When that path is the
+    user home directory, also includes ``$HOME`` so grant shapes like
+    ``Edit($HOME/.claude/**)`` are reaped from home cwd.
+
+    Args:
+        project_path: POSIX-style project root path from get_current_project_path.
+        home_directory_path: Optional home path for tests; defaults to Path.home().
+
+    Returns:
+        Ordered unique path aliases used when building project-scoped remove rules.
+    """
+    normalized_project_path = project_path.replace("\\", "/").rstrip("/")
+    resolved_home_directory_path = (
+        home_directory_path
+        if home_directory_path is not None
+        else str(Path.home())
+    ).replace("\\", "/").rstrip("/")
+    all_path_aliases: list[str] = [normalized_project_path]
+    if normalized_project_path.lower() == resolved_home_directory_path.lower():
+        all_path_aliases.append(HOME_PROJECT_PATH_ALIAS)
+    all_unique_path_aliases: list[str] = []
+    for each_path_alias in all_path_aliases:
+        if each_path_alias not in all_unique_path_aliases:
+            all_unique_path_aliases.append(each_path_alias)
+    return tuple(all_unique_path_aliases)
+
+
 def build_permission_rule(tool_name: str, project_path: str) -> str:
     return f"{tool_name}({project_path}/.claude/**)"
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -296,8 +296,9 @@ def _run_diff_mode(
     """Validate the merge-base diff joined with the untracked files.
 
     Zero candidates means nothing was inspected (bad wiring looks the same),
-    so that run refuses loudly. A set emptied only by the ``--only-under``
-    scope flows through ``run_gate`` over zero files and exits clean.
+    so that run refuses loudly. A set emptied by the ``--only-under`` scope or
+    left with no code files after the code-path filter flows through
+    ``run_gate`` over zero files and exits clean.
     """
     all_candidate_paths = _deduplicate_paths(
         paths_from_git_diff(repository_root, arguments.base)
@@ -308,6 +309,7 @@ def _run_diff_mode(
     file_paths = filter_paths_under_prefixes(
         all_candidate_paths, repository_root, arguments.only_under
     )
+    file_paths = [each_path for each_path in file_paths if is_code_path(each_path)]
     scoped_added_lines = (
         added_lines_by_file(repository_root, arguments.base, file_paths) if file_paths else {}
     )