claude-dev-env 8.36.4 → 8.37.1

package/rules/explore-thoroughly.md

@@ -1,25 +1,9 @@
-# Explore Thoroughly
+# Explore thoroughly
 
-Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#overthinking-and-excessive-thoroughness)
+**When:** Choosing an implementation approach or recommending an architectural direction.
 
-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.
+Read relevant files, map local patterns, and identify constraints before committing to an approach. Scale exploration to risk: inspect nearby files for a small change, broader examples for a new feature, and the full landscape for an architectural decision. Once the files, constraints, and success condition are known, act without repeating settled research.
 
-## Before committing to an approach
+**Enforcement:** none, the agent applies it.
 
-- Read the relevant files. Understand what exists before proposing what to change.
-- Map the existing patterns: naming conventions, file organization, architectural decisions.
-- Identify constraints that could invalidate an approach before investing effort in it.
-
-## Exploration scales with risk
-
-- Small change to a familiar file: a quick read of the file and its immediate neighbors is enough.
-- New feature or cross-cutting change: read broadly across the codebase to understand how similar things are done.
-- Architectural decision: explore the full landscape before recommending a direction.
-
-## Inside an autonomous run
-
-The depth budget shrinks once the evidence is in hand. When you can already name the files, the constraints, and what success looks like, further reading buys nothing — act. Re-reading a file to re-derive a fact the run already settled is the shape to cut. See [`long-horizon-autonomy.md`](long-horizon-autonomy.md).
-
-## Relationship to other rules
-
-- **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the codebase.
+**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it when setting exploration depth.

package/rules/filesystem-search.md

@@ -1,51 +1,9 @@
-# Filesystem Search
+# Filesystem search
 
-**When this applies:** Any search for files by name, path, extension, size, or date. That includes `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
+**When:** Searching for files by name, path, extension, size, or date.
 
-## The scope invariant
+Scope every search to a project, worktree, package, or narrowing filter. Never start at a filesystem root, drive root, bare home, or share root. Read a known path directly; use scoped `es.exe`, Glob, or Grep for discovery. After `es.exe` Error 8, retry twice before falling back within the same scope. Run one large shell walk at a time. Ask the user only after available search tools fail.
 
-Every filesystem search names a scope. A scope is a project, worktree, or package directory under the work in progress, or a filter that narrows the walk: an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern.
+**Enforcement:** none, the agent applies it.
 
-A search that starts at the filesystem root, a drive root, bare home, or a network share is out of bounds. Narrow it to what you need.
-
-## Choosing a tool
-
-Three tools are equally sanctioned; pick by what you know:
-
-| You know | Use |
-|---|---|
-| The exact path | `Read`. Do not search. |
-| A name, extension, or date, on Windows | `es.exe` with a path scope |
-| A name or path pattern | The harness `Glob` tool |
-| Text inside files | The harness `Grep` tool |
-
-When `es.exe` returns Error 8, retry the same search twice before any fallback. Error 8 is a missing IPC client window, not proof the index is down. After those retries fail, report that the Everything IPC client did not answer and that the service state was not probed, then fall back to `Glob` or `Grep` with the same scope. When `es.exe` is missing, or a later search returns no hits, fall back to `Glob` or `Grep`. Ask the user only after all three tools fail.
-
-`skills/everything-search/SKILL.md` holds the full `es.exe` operator reference: `ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT, output flags, and the junction and drive-mapping note.
-
-## Allowed and denied shapes
-
-| Allowed | Example |
-|---|---|
-| Cwd-relative | `find . -iname '*.py'` |
-| Project path | `find packages/claude-dev-env -name code_rules_gate.py` |
-| Git Bash scoped path | `find /c/Users/<you>/repo -iname SKILL.md` |
-| Recursive listing under a project | `Get-ChildItem -Path .\src -Recurse` |
-| Scoped Windows index search | `es.exe path:C:\dev\repo ext:py gate` |
-
-| Denied | Example |
-|---|---|
-| Filesystem root | `find / -iname code_rules_gate.py` |
-| Git Bash drive root | `find /c -name '*.py'` |
-| Windows drive root | `find C:\ -name foo` / `Get-ChildItem C:\ -Recurse` |
-| Bare home | `find ~ -name README.md` / `find $HOME -type f` |
-| Network share root | `find //server/share -name x`. A path under the share (`//server/share/project/src`) is allowed |
-
-## Shell batching
-
-Issue one shell search at a time when the walk is large. Parallel full-tree searches contend for the shell and can lock the host. Harness `Grep` and `Glob` calls carry no such cost and run in parallel freely.
-
-## Search controls
-
-- No hook denies a walk from an unscoped root. The scope invariant above is guidance a reader follows.
-- For Everything searches that use a project name, run `python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>`. An exact project name becomes its path from `~/.claude/project-paths.json`. The command then starts `es.exe` without a shell. `scripts/setup_project_paths.py` writes the registry.
+**Full text:** [`docs/rule-guides/filesystem-search.md`](../docs/rule-guides/filesystem-search.md). Read it for tool selection and search examples.

package/rules/memory-stores-durable-facts.md

@@ -1,57 +1,9 @@
-# Memory Stores Durable Facts
+# Memory stores durable facts
 
-**When this applies:** Before you write or update a file in an auto-memory
-directory, and before you add its line to `MEMORY.md`.
+**When:** Writing auto-memory or adding a `MEMORY.md` entry.
 
-## Rule
+Keep only a fact that helps a fresh session weeks later. Remove dates, task identifiers, commits, and paths from a draft; if the remainder is empty or false, put it in the task tracker or handoff instead. Store standing user preferences, stable setup traps, and useful resource pointers. Delete stale memory and its index line in the same run.
 
-A memory must still help a fresh session, with no context, weeks later.
+**Enforcement:** none, the agent applies it.
 
-Run one test on the draft. Strip every date, pull request number, issue number,
-commit, job path, session ID, and task number. When what remains is empty or
-false, the draft is run state. Put it in the task tracker, the pull request, or
-a handoff file beside the work, and save no memory.
-
-## What never becomes a memory
-
-| Shape | Example | Where it belongs |
-|---|---|---|
-| Run or program state | "paused at", "resume from", "4 of 11 merged", a pointer to a handoff file | The task tracker or the handoff file |
-| A pull request, issue, stack, or commit map | "#583, #605, #610 merged" | The epic issue or the pull request |
-| A temporary condition | A concurrency schedule, credits out, a fleet that works this week, a fix "until X lands" | The current conversation |
-| One session's topology | A session ID, a parallel session's worktree, a second-account dispatch setup | The current conversation |
-| A workaround for a hook, gate, or verifier as it behaved one day | "the minter never fires, so skip the check" | A fix to the hook, per [`correction-lens.md`](correction-lens.md) |
-| The story of one incident or bug fix | "the fold checkbox took five tries" | Git history and the pull request body |
-| Where code lives, or a design recipe for one build phase | A module layout, a prompt recipe for one engine version | The repository and its inventories |
-| A restatement of a rule file | "CI owns the gate" | The rule file already loaded |
-
-## What a memory holds
-
-- A preference or standing order the user stated, with the date the user set it.
-- A trap in the local setup or the platform that stays true, such as a shared
-  `rr-cache` that replays one-sided resolutions without a marker.
-- A pointer to an external resource: a dashboard, a repository, a tracker.
-
-Write the fact first. A date belongs only on a rule the user set on that date.
-
-## Keeping the folder current
-
-When a memory goes stale, delete it and its `MEMORY.md` line in the same run.
-A "superseded" note on a stale memory keeps a false fact loading into every
-session.
-
-## Why
-
-One project's memory folder held 104 index entries. A cleanup pass removed 57
-of them, and each one failed the test above. Handoffs outlived their work,
-pull request maps named merged branches, and a capacity schedule and a
-dispatch topology contradicted newer standing orders. Every stale memory loads
-into each session and reads as current.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`correction-lens.md`](correction-lens.md) | A memory records a decision, and the control holds the behavior |
-| [`verify-before-asking.md`](verify-before-asking.md) | A recalled fact is a claim to re-check |
-| [`cleanup-temp-files.md`](cleanup-temp-files.md) | Scratch output leaves with the task |
+**Full text:** [`docs/rule-guides/memory-stores-durable-facts.md`](../docs/rule-guides/memory-stores-durable-facts.md). Read it when deciding whether a fact belongs in memory.

package/rules/no-contrast-framing.md

@@ -1,68 +1,9 @@
-# No Contrast Framing
+# No contrast framing
 
-**When this applies:** Every sentence a person reads. A chat reply, a commit
-message, a pull request title or body, a review comment, an issue, a rule file,
-a document, a plan, a memory file.
+**When:** Writing any sentence a person reads.
 
-## Rule
+State the chosen point directly and leave out the discarded reading. Remove these six forms: `trailing-comma-not`, `corrective-it-is-not`, `substitution-rather-than`, `additive-not-just`, `comparative-ranking`, `substitution-as-opposed-to`. Keep quantity comparisons. If a sentence loses substance, add the failing check, log line, measured number, or file and line.
 
-State what is true. Leave the rejected reading out.
+**Enforcement:** staged policy lint and `scripts/durable_post_lint.py` check authored text; the agent checks chat.
 
-A contrast defines its subject against something the writer already decided
-against, so the reader carries two readings where one would do, and the second
-one is the writer's own discarded draft. The sentence says more and shows less.
-
-Six forms carry the whole ban. Each row names the form the check reports.
-
-| Form | Shape | Write this |
-|---|---|---|
-| `trailing-comma-not` | `a diff regression, not shared infrastructure` | `a diff regression` |
-| `corrective-it-is-not` | `it is not a flake, it is a bug` | `a bug`, then the evidence that shows it |
-| `substitution-rather-than` | `park it rather than fix it` | `park it` |
-| `additive-not-just` | `not just for today` | the point the sentence was building toward |
-| `comparative-ranking` | `being precise matters more than trying to cover them` | `be precise about these three` |
-| `substitution-as-opposed-to` | `a warning as opposed to a failure` | `a warning` |
-
-A comparison of quantities stays. "The function runs more than 30 lines" counts
-lines. The ban covers the comparison that ranks one course of action over
-another the writer is turning down.
-
-Three shapes stay quiet by design. A backticked span or a fenced block carries
-an example, so the check blanks it first. A line opening with `>` quotes
-someone else, whose words are theirs to write. A `, not` clause reports only
-when no bare `not` already sits earlier in the line, so a list of clauses
-reports its first `, not` and stays quiet on the rest, as in
-`a diff regression, not shared code, not a workaround`. A list whose own
-opening word is a bare `not`, as in "not in chat, not in a commit message, not
-in a body", keeps even its first `, not` quiet. A release automation body
-passes the post linter untouched, since the bot builds it from commit
-subjects and reads it back as machine input.
-
-When the sentence thins after the contrast comes out, the missing piece is
-evidence. Name it: the failing check, the log line, the measured number, the
-file and the line.
-
-## Where it is enforced
-
-| Surface | What runs |
-|---|---|
-| Authored Markdown in the repository | The staged policy lint's `contrast-framing` rule, on every changed file, graded against the file's prior text |
-| A pull request or issue title and body, and a comment | `scripts/durable_post_lint.py`, which every post passes through before it reaches GitHub |
-| A chat reply | The writer, reading the sentence back before sending |
-
-The pattern list lives in
-`scripts/dev_env_scripts_constants/contrast_framing_constants.py`, and both
-lints read that one list. A synchronization test requires a row in the table
-above for every form the list carries.
-
-A chat reply reaches no check, so the same list is what the writer reads the
-sentence against: a comma followed by `not`, a `rather than`, a `not just`, a
-ranking of one thing over another.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`asd-ste100-language.md`](asd-ste100-language.md) | Plain word choice, sentence style, and tone |
-| [`correction-lens.md`](correction-lens.md) | Every correction becomes a control at the highest layer that can hold it |
-| [`research-mode.md`](research-mode.md) | A claim carries its source |
+**Full text:** [`docs/rule-guides/no-contrast-framing.md`](../docs/rule-guides/no-contrast-framing.md). Read it for examples and checker exceptions.

package/rules/research-mode.md

@@ -1,29 +1,9 @@
-# Research Mode (Global)
+# Research mode
 
-Three anti-hallucination constraints are always active.
+**When:** Making a factual claim, recommendation, or piece of advice.
 
-Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
+Say when you lack a credible source; do not guess or infer. Cite a project file, web source, named expert or paper, or official documentation for each claim. Retract claims a source cannot support. Extract document text before analysis and ground the answer in word-for-word quotes. In chat, cite compactly with a link or `file:line`; put full quotes and citation lists in artifacts or replies that request them. Ground synthesis in sourced inputs. Creative ideas need no citation.
 
-## 1. Say "I don't know"
-If you don't have a credible source for a claim, say so. Don't guess. Don't infer. "I don't have data on this" is always a valid answer.
+**Enforcement:** none, the agent applies it.
 
-## 2. Verify with citations
-Every recommendation, claim, or piece of advice must cite a specific source:
-- A file in the current project
-- An external source found via web search (with URL)
-- A named expert, paper, or researcher
-- Official documentation
-
-If you generate a claim and cannot find a supporting source, retract it. Do not present it.
-
-A citation is checked against what the source says, not against whether the source exists. A named authority attached to a claim the authority does not make is weaker than no citation at all, because it stops the reader from asking. This bites hardest on numbers: a threshold that runs stricter or looser than its source is a house call, so label it as one and leave the attribution to the direction the source does support.
-
-## 3. Direct quotes for factual grounding
-When working from documents, extract the text first before analyzing. Ground your response in word-for-word quotes, not paraphrased summaries. Reference the quote when making your point.
-
-## How citations appear in a chat reply
-
-The grounding requirement above never relaxes: state no claim you cannot source. What changes with the channel is how much of the source you print. A chat reply carries the source in compact form — a linked source name, or a `file:line` reference. Word-for-word quotes and full citation lists belong in artifacts, PR bodies, and issue bodies, or in a reply when the user asks for them.
-
-## Exceptions
-Creative thinking, brainstorming, and novel ideas don't require citation. You can synthesize across sources to reach new conclusions, but the inputs must be grounded.
+**Full text:** [`docs/rule-guides/research-mode.md`](../docs/rule-guides/research-mode.md). Read it when checking a source or citation.

package/rules/verify-before-asking.md

@@ -1,52 +1,9 @@
-# Verify Before Asking
+# Verify before asking
 
-**When this applies:** Before asking the user any clarifying question during discovery, scoping, or implementation planning.
+**When:** Before asking the user a clarifying question.
 
-## Rule
+Inspect files, directories, configuration, environment, databases, and available tools for the answer. Recheck facts recalled from earlier sessions. Apply any criterion the user already supplied and state the decision. Ask only for a judgment, preference, or inaccessible fact; use the session's question tool when available.
 
-If a question can be answered by inspecting files, running a command, querying a database, reading a config, or using any available tool, answer it yourself. Only ask the user questions that require their judgment, preference, or knowledge that is not accessible to automated inspection.
+**Enforcement:** none, the agent applies it.
 
-## Decision Checklist
-
-Before using the current session's native question tool or asking a clarifying question in chat, evaluate:
-
-| Check | Action |
-|---|---|
-| Does the answer live in a file on disk? | Read the file. |
-| Does the answer live in a directory structure? | List the directory. |
-| Does the answer live in a database? | Query the database. |
-| Does the answer live in git history? | Run `git log` or `git blame`. |
-| Is the answer determined by file naming patterns or contents? | Glob a sample and inspect. |
-| Is the answer a value in a config or environment variable? | Read the config or check the env. |
-| Is the answer retrievable from any available MCP tool? | Use the tool. |
-| Did the user already state a criterion, standard, or line that decides this? | Apply it, state the call and the reason, and keep going. |
-
-Only after confirming the answer cannot be obtained through any available tool, ask the user. Present the question using [Present questions clearly](question-presentation.md).
-
-## Prior-session facts expire
-
-A path, port, branch name, or config value you recall from an earlier session counts as unanswered until a tool re-checks it this session. Memory records what was true when it was written; the file may have moved, the port may be down, the branch may have merged. Treat every recalled fact as a claim to re-ground, not an answer to reuse.
-
-- When a tool can settle it, re-check in silence and act on the fresh result — no question to the user.
-- When no tool can settle it and the user has a stake in the answer, use the current session's native question tool when available.
-
-## Questions That Belong to the User
-
-Reserve user questions for:
-- **Preferences** — "Do you want approach A or B?" when both are viable and the user has a stake.
-- **Missing context the user holds** — passwords, account names, intent, future plans.
-- **Judgment calls** — tradeoffs the user needs to evaluate.
-- **Scope decisions** — what to include or exclude from a piece of work.
-
-A preference question is one where the user has not yet given the line. Once they have, every case under that line is yours to decide. Handing back each application of a stated criterion turns one decision into many and stalls the work, because the person who set the standard does not hold the individual answers. Apply the criterion, name the call and the reason it went that way, and escalate only what the criterion cannot settle: a new axis it never covered, or a step nobody can undo. [`long-horizon-autonomy.md`](long-horizon-autonomy.md) carries the same duty for authority the task already granted.
-
-## Examples
-
-**Wrong:** "Are there multiple images per folder, or just one image + one mp4?"
-**Right:** List the folder contents directly, then state what was found.
-
-**Wrong:** "What columns does the themes table have?"
-**Right:** Query `information_schema.columns` and report the schema.
-
-**Wrong:** "Is there a Prisma schema in this project?"
-**Right:** Glob for `schema.prisma` and check.
+**Full text:** [`docs/rule-guides/verify-before-asking.md`](../docs/rule-guides/verify-before-asking.md). Read it when the source of an answer is uncertain.

package/rules/verify-runtime-state.md

@@ -1,42 +1,9 @@
-# Verify Runtime State
+# Verify runtime state
 
-**When this applies:** Before stating that a component is fine, healthy, not at fault, or working — during debugging, triage, or any judgment about whether something runs.
+**When:** Before saying a component works, is healthy, or is not the cause of a failure.
 
-## Rule
+Gather a live signal this session: process list, port probe, log, status code, or fresh reproduction. Read the user's terminal and named error log while a reported failure is still visible. Check the effect the work should produce, including each job result, loaded config, or deployed artifact; a success status alone does not establish the effect. When testing code, identify the loaded module path.
 
-A verdict that a component is fine or not the cause rests on live evidence gathered this session: a process list, a port probe, a log tail, an HTTP status code, or a fresh repro. Reading the code, recalling how the component behaved earlier, or trusting a prior session's finding does not settle whether it runs right now. Code shows what should happen; only a live probe shows what does.
+**Enforcement:** none, the agent applies it.
 
-Gather the probe before you write the verdict. When the probe contradicts the code (the code looks right but the port refuses the connection), report the live result and treat the component as suspect.
-
-A status field is a report, not the effect. An exit code, a green pipeline run, and a task result all say the work finished. They do not say the work happened. Read the thing the work was meant to make.
-
-Some evidence lasts only a moment. When a user shows you a failure, read the source they already hold: the terminal itself, and any log file the error names. A fresh probe minutes later measures a different moment, and a system that healed in between hides the failure you were asked about.
-
-## Grounding checklist
-
-Before stating a runtime claim, gather the matching live signal:
-
-| Claim | Grounding probe |
-|---|---|
-| The service is healthy | Hit its health endpoint and read the status code. |
-| The config is in effect | Print the loaded config at runtime and read the value. |
-| The server is up | Probe the port; a refused connection means it is down. |
-| The process is running | List processes and match the name or PID. |
-| The change took effect | Drive the flow and watch the new behavior. A script that proves a branch's behavior names the module file it loaded, as its first step, because an installed copy of the same package shadows the checkout you meant to test. |
-| The dependency is reachable | Send one request and read the response. |
-| The release or deploy shipped | Read what it makes: the tag, the published version, the file on disk. |
-| The pipeline did the work | Read each job's own result. A run reports success while a job inside it is skipped. |
-| The automation works | Drive the branch that matters. A green run of the do-nothing branch proves nothing. |
-
-Only after a live signal backs the claim do you state it.
-
-## Examples
-
-**Wrong:** "The search server code looks correct, so it is not the problem."
-**Right:** Probe port 54321; report "connection refused — the server is down."
-
-**Wrong:** "This function handles the retry, so the request must be going through."
-**Right:** Tail the request log and confirm the retry fired, or report that no retry line appears.
-
-**Wrong:** "The config sets the timeout to 30 seconds, so the timeout is fine."
-**Right:** Print the loaded config at runtime and report the value the process holds.
+**Full text:** [`docs/rule-guides/verify-runtime-state.md`](../docs/rule-guides/verify-runtime-state.md). Read it when choosing the probe for a claim.