claude-dev-env 1.46.0 → 1.47.0

package/CLAUDE.md

@@ -1,5 +1,9 @@
 # Claude Development Assistant
 
+The user is short on time and tokens. 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.
+
+The user is short on tokens; whenever a task can be achieved cleanly and effectively, optimize to save the user $$ and token usage.
+
 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.
 
 ## Code Rules
@@ -18,7 +22,10 @@ Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md
 
 ## GOTCHAS
 When making code changes, make sure you are working in the proper worktree path for the task at hand.
-When writing to an existing file, you must either EDIT the file, or remove it and THEN re-write it if it's truly a full re-write.
+
+## Choosing Edit vs Write
+
+`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`.
 
 ## File-Global Constants
 

package/hooks/blocking/content_search_zoekt_redirect_guidance.py

@@ -32,6 +32,14 @@ def get_zoekt_redirect_guidance() -> str:
         "positively, e.g. mcp__zoekt__search(query=\"your pattern file:"
         + worktree_filter_fragment
         + "<branch>/\").\n\n"
+        "INDEX FRESHNESS: the index trails just-written code — recent or unpushed commits sync and reindex "
+        "on a short delay, so a symbol you just added can be missing from Zoekt for a few minutes even though "
+        "it is on disk. Worktrees are fully indexed and retrievable with the positive 'file:"
+        + worktree_filter_fragment
+        + "<branch>/' filter above, but that same lag applies to anything freshly edited. When a Zoekt search "
+        "returns nothing for code you know exists on disk, do not treat it as absent: Grep a specific file "
+        "(a path ending in a file extension is exempt from this redirect) or read the file directly to confirm "
+        "current contents.\n\n"
         "INDEX ROOTS (when Grep/Search in a tree is redirected): set ZOEKT_REDIRECT_INDEXED_ROOTS to a JSON array "
         "of absolute paths, or ~/.claude/zoekt-indexed-roots.json as {\"roots\": [\"/abs/path/to/repo/\", ...]}. "
         "Optional ZOEKT_REDIRECT_INDEXED_ROOTS_FILE points to a different JSON file. "

package/hooks/blocking/test_content_search_to_zoekt_redirector_unit.py

@@ -81,6 +81,12 @@ class RedirectGuidanceWorktreeTests(unittest.TestCase):
     def test_worktree_display_fragment_is_the_unescaped_path(self) -> None:
         self.assertEqual(worktree_path_display_fragment(), ".claude/worktrees/")
 
+    def test_guidance_documents_index_freshness_escape_hatch(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        self.assertIn("INDEX FRESHNESS:", guidance)
+        self.assertIn("exempt from this redirect", guidance)
+        self.assertIn("read the file directly", guidance)
+
 
 if __name__ == "__main__":
     unittest.main()

package/package.json

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

package/skills/pre-compact/SKILL.md

@@ -5,8 +5,10 @@ description: >-
   `/compact <directive>` string to the operator's clipboard so the next prompt
   is a single paste. The directive pins the session's load-bearing identifiers
   (branch, PR, HEAD, worktree, in-flight work, decisions, blockers, files in
-  play, follow-ups) and lists the redundant tool outputs the summarizer should
-  drop. Use when the user says `/pre-compact`, asks to prep for compaction, or
+  play, follow-ups) the next steps depend on, so the summarizer keeps them with
+  high fidelity. It confirms the operator's intent for the next chat through a
+  structured question first, then validates each identifier against its live
+  source before stating it. Use when the user says `/pre-compact`, asks to prep for compaction, or
   asks to compose a focus directive for `/compact`.
 disable-model-invocation: true
 ---
@@ -20,16 +22,35 @@ string to the operator's clipboard.
 
 **Announce at start:** "I'm composing your compact focus directive."
 
-## Step 1 — Read the live session
-
-Pull the load-bearing identifiers from the current conversation. Run
-`git status`, `git rev-parse --short HEAD`, or `gh pr view` when values are
-not already in context.
+## Step 1 — Confirm the next-session intent
+
+Before composing anything, ask the operator what they intend to work on in
+the next chat. Do not infer it silently from the conversation, and do not
+ask it raw — use `AskUserQuestion` with two to four options drawn from the
+session context (the threads left open, the obvious next actions, the task
+the operator last steered toward); the tool's free-text fallback covers
+anything unlisted. The selected intent is the directive's forward task:
+Step 2 scopes every field to what that intent needs, and the rendered
+`In-flight` line states it.
+
+## Step 2 — Read and validate the live session
+
+Validate every identifier directly before stating it. Conversation context
+goes stale within a session — a PR merges, HEAD advances, a worktree
+advances to a newer commit — so confirm each value against its live source
+at compose time rather than carrying it from memory. Run the command in
+each field's Source column; for a PR, capture its merge state
+(`gh pr view --json state,mergedAt`) and state `merged` or `open` from that
+result, never from recollection. A value that cannot be confirmed against a
+live source is not dropped silently — surface it to the operator via
+`AskUserQuestion` to clarify (offer the candidate values found plus the
+free-text fallback) and use the answer. Omit it only when the operator
+chooses to skip it.
 
 | Field | What to capture | Source |
 |---|---|---|
 | `branch` | Active branch name | `git branch --show-current` |
-| `pr` | Active PR number, when one exists | `gh pr view --json number` |
+| `pr` | Active PR number and its merge state (open / merged), when one exists | `gh pr view --json number,state,mergedAt` |
 | `head` | Short HEAD SHA (whatever `git rev-parse --short` outputs) | `git rev-parse --short HEAD` |
 | `worktree` | Absolute path to the working directory | `pwd` |
 | `in_flight` | One sentence describing what is being worked on right now | conversation |
@@ -41,7 +62,15 @@ not already in context.
 A field whose value cannot be stated as a concrete identifier is omitted
 from the directive.
 
-## Step 2 — Render the directive
+Scope every field to what the Step 1 intent needs next. Compaction carries
+forward the slice of session history the remaining work needs: capture a
+`decision`, `blocker`, or `in_flight` detail when a next step relies on
+it, and leave a detail the next steps do not touch (a settled question, a
+resolved blocker, a path not taken) out by simply not listing it. When a
+settled decision still constrains the next step, list its outcome as one
+line, not the deliberation behind it.
+
+## Step 3 — Render the directive
 
 Render this exact shape, populating only the fields with concrete values:
 
@@ -56,25 +85,21 @@ Preserve:
 - Blockers: <bullet per blocker>
 - Files: <path>, <path>, <path>
 - Follow-ups: <bullet per follow-up>
-
-Drop:
-- Tool outputs already applied to files
-- Per-tick progress narration
-- Resolved findings and superseded SHAs
-- Listing/grep output whose conclusion appears above
 ```
 
-The `Preserve:` block leads so the summarizer maximizes recall first. The
-`Drop:` block lists the lightest-touch removals — raw tool outputs are the
-safest content to drop because the work they produced lives in the files
-and commits.
+The directive lists only what the next steps consume, so the summarizer
+preserves that with high fidelity and compresses the rest of the trace on
+its own — naming what to keep is a clearer instruction than enumerating
+what to cut. Keep the list tight: a `Preserve:` block padded with finished
+or out-of-scope context dilutes the summarizer's focus on what happens
+next.
 
 Source: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
 — "start by maximizing recall to ensure your compaction prompt captures
 every relevant piece of information from the trace, then iterate to improve
 precision by eliminating superfluous content."
 
-## Step 3 — Copy `/compact <directive>` to the clipboard
+## Step 4 — Copy `/compact <directive>` to the clipboard
 
 Write the full `/compact <directive>` string to a temporary file via the
 Write tool, then copy the file contents to the clipboard with PowerShell:
@@ -91,7 +116,7 @@ unmodified regardless of which characters it contains.
 A reasonable temp path under `$env:TEMP` (Windows) or `$TMPDIR` (POSIX)
 works; clean it up after the `Set-Clipboard` call returns.
 
-## Step 4 — Hand off
+## Step 5 — Hand off
 
 Print this confirmation line to the operator:
 
@@ -99,8 +124,8 @@ Print this confirmation line to the operator:
 > compact this conversation with focus.
 
 Then list up to the first three `Preserve:` bullets (or fewer when the
-directive omits fields) and the first `Drop:` bullet inline so the
-operator can spot-check before pasting.
+directive omits fields) inline so the operator can spot-check before
+pasting.
 
 ---