claude-dev-env 8.37.0 → 8.37.1

package/docs/rule-guides/asd-ste100-language.md

@@ -0,0 +1,42 @@
+Back to the [rule entry](../../rules/asd-ste100-language.md).
+
+# ASD-STE100 language policy
+
+Use this rule as the sole general language authority for user-facing text in this repository.
+It defines ordinary word choice, sentence style, tone, punctuation, and prose form.
+
+This text is an **ASD-STE100 Issue 9 conversational adaptation**. It applies the standard's
+clear-writing principles to assistant messages. The official standard remains the authority for
+definitions and dictionary decisions.
+
+## Official sources
+
+- [ASD-STE100 Simplified Technical English, Issue 9 (2025-01-15)](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
+- [ASD-STE100 FAQ](https://www.asd-ste100.org/STE_faq.html)
+- [ASD-STE100 About page](https://www.asd-ste100.org/about_STE.html)
+- [ASD-STE100 tools guidance](https://www.asd-ste100.org/STEsoftware.html)
+- [STEMG white paper on ASD-STE100 and artificial intelligence](https://www.asd-ste100.org/assets/files/WhitePaper-ASD-STE100_and_AI.pdf)
+
+## Writing policy
+
+- Write short, complete sentences. Keep one topic in each explanatory sentence.
+- Use active voice. Put the condition first when an instruction has a prerequisite.
+- Write imperative procedure steps. Give one action in each sentence.
+- Prefer familiar, precise words. Use one stable term for one item or action.
+- Write full words and explicit references. Expand abbreviations and contractions when they first appear.
+- Replace ambiguous pronouns with the noun they name.
+- Use inclusive, neutral language.
+- Use periods, commas, colons, and bullets to show structure.
+- Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
+- Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
+- Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
+- Aim for 20 words or fewer in a procedure sentence when the technical content allows.
+- Aim for 25 words or fewer in a descriptive sentence when the technical content allows.
+
+Use this policy for chat, tool narration, questions, plans, documentation, code-adjacent prose,
+and durable repository text. Named contracts can add behavior-specific structure, evidence,
+question routing, current-state documentation, completion, docstring, or publication rules.
+Those contracts use this policy for their language.
+
+Treat automated output and language checks as drafting aids. A responsible human verifies
+technical accuracy, terminology, safety, confidentiality, and intended meaning.

package/docs/rule-guides/cleanup-temp-files.md

@@ -0,0 +1,35 @@
+Back to the [rule entry](../../rules/cleanup-temp-files.md).
+
+# Clean up temporary files
+
+**When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
+
+Source: [Anthropic: Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
+
+## During a task
+
+- Prefer working in memory over creating scratchpad files. Keep intermediate data in variables and tool results.
+- When a temporary file is needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
+
+## When a task is complete
+
+- Remove every temporary file, script, or helper file you created during the task.
+- Leave the working directory cleaner than you found it.
+- If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
+
+## Exceptions to the removal duty
+
+Three kinds of file are already ephemeral and need no explicit removal:
+
+- A file under the OS temporary root.
+- A file under `$CLAUDE_JOB_DIR`, which the harness clears with the job.
+- A child agent's scratch file, which the parent removes at teardown.
+
+Use an allowed removal form for everything else: [`destructive-commands.md`](../../rules/destructive-commands.md) names them.
+
+## What counts as temporary
+
+- Scripts written to test a hypothesis or run a one-off check
+- Debug output files, log dumps, or intermediate data exports
+- Helper files created to work around tool limitations
+- Any file the user did not ask for and would not expect to find after the task

package/docs/rule-guides/correction-lens.md

@@ -0,0 +1,112 @@
+Back to the [rule entry](../../rules/correction-lens.md).
+
+# Correction lens
+
+**Standing rule. This file is never archived and never removed.** The permanence
+clause at the end of this document states what that binds.
+
+**When this applies:** Every correction the user gives. A "no, do it this way", a
+"stop writing that word", a repeated review comment, a fix the user makes by hand
+after an agent hands work back. Each one is evidence that a control is missing,
+and the correction is handled by building that control.
+
+## Rule
+
+A correction runs through five layers, in this order, and the lesson lands at the
+highest layer that can hold it. The change opens in the same run as the
+correction.
+
+| Priority | Layer | What holds the lesson | The lesson lands as |
+|---|---|---|---|
+| 1 | Codebase | The mistake is impossible by how the code is written | A type, a signature, a data structure, an API shape, a deleted branch |
+| 2 | Static analysis | A program reads the tree and decides | A lint rule, an enforcer check, a paired test, a CI gate |
+| 3 | Review tooling | A reviewer or a review bot reads the criterion | A `CODE_RULES.md` row, a `.cursor/BUGBOT.md` pointer, a Graphite or BugBot rule |
+| 4 | Skill | An agent follows a procedure | A skill under the agents home |
+| 5 | Style guide | Word choice and prose shape | A row in a `rules/*.md` file or a style document |
+
+Layer 1 is the goal every time. A lesson encoded there needs no reader, no run,
+and no agent to remember it. The wrong call has nowhere to live.
+
+## Choosing the layer
+
+Three sentences close every correction:
+
+1. The layer chosen.
+2. Why each higher layer cannot hold this lesson.
+3. The change opened at the chosen layer, by pull request.
+
+A layer holds a lesson when its own test passes:
+
+- **Layer 1 holds it** when a type, a signature, or a data structure can make the
+  wrong call fail to compile, fail to construct, or fail to exist.
+- **Layer 2 holds it** when a program reading the tree can separate right from
+  wrong with no judgment call.
+- **Layer 3 holds it** when a reader needs the criterion in front of them and a
+  program cannot decide it.
+- **Layer 4 holds it** when the lesson is a procedure with steps an agent runs.
+- **Layer 5 holds it** when the lesson is word choice or the shape of prose.
+
+Effort rules out no layer. A layer is ruled out when it lacks the capability to
+hold the lesson, and the sentence that rules it out says which capability is
+missing. "A lint for this would take a day" leaves layer 2 in play.
+
+Two layers often hold one correction. Take both: the shape at layer 1 and the
+check at layer 2 cost one run together and each covers what the other misses.
+
+## A repeated correction moves up a layer
+
+The same correction arriving a second time is the measurement. The layer chosen
+the first time was too low. Move the lesson one layer up and say so in the same
+run.
+
+A review comment that repeats across pull requests reads the same way. Each
+repetition names the layer below the reviewer as the one that needs the control.
+Count the repetitions.
+
+## Where the control lands
+
+A control lands in the repository whose code, CI, or pipeline it guards. A
+control for one repository's workflows, review bots, pipelines, or agents lands
+in that repository. This package takes only repo-agnostic controls, the
+environment and development pieces any repository could use, so every session
+that loads this environment carries them. A control written into one project's
+instructions reaches that project alone, and a control written into a chat reply
+reaches that conversation alone.
+
+Memory holds the decision. The control holds the behavior. A correction that
+produced a memory file and nothing else has been recorded and never encoded, so
+the rule still binds. Open the control.
+
+## Trust grows as the controls catch the common mistakes
+
+Add agents after the controls catch what agents get wrong, and start from a
+workflow small enough to watch. Each repeated correction becomes a stronger
+control, and the number of agents rises behind it.
+[`docs/high-trust-agent-delivery.md`](../high-trust-agent-delivery.md)
+carries the model this comes from, including the layered-controls picture and
+the inner and outer delivery loops.
+
+## Permanence
+
+This file stays in `rules/`. A prune pass, an archive sweep, a consolidation, or
+a rewrite that would move it into `rules-archived/` stops at this line. The
+"Never archived" section of
+[`packages/claude-dev-env/rules-archived/ARCHIVE-MANIFEST.md`](../../rules-archived/ARCHIVE-MANIFEST.md)
+names it, and
+[`archiving-agent-config.md`](../../rules/archiving-agent-config.md) names the same
+exemption from the archiving procedure's side.
+
+An edit that sharpens this rule is welcome. The file stays.
+
+## Codex copy
+
+Codex reads its repository `AGENTS.md`. The standalone excerpt it receives lives in [`docs/rule-guides/correction-lens-excerpt.md`](correction-lens-excerpt.md).
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`flag-non-breaking-findings.md`](../../rules/flag-non-breaking-findings.md) | A gate blocks on a breaking finding and records a smell |
+| [`code-standards.md`](../../rules/code-standards.md) | The layer map of contract, pointer, enforcer, lint, session rules |
+| [`archiving-agent-config.md`](../../rules/archiving-agent-config.md) | How a rule leaves service, and which files are exempt |
+| [`falsify-before-green.md`](../../rules/falsify-before-green.md) | A new layer-2 check counts once it has run red on a named break |

package/docs/rule-guides/destructive-commands.md

@@ -0,0 +1,49 @@
+Back to the [rule entry](../../rules/destructive-commands.md).
+
+# Destructive commands in Bash
+
+No hook watches Bash commands for destructive patterns. What you face is the harness permission prompt. The harness raises it from the session permission mode and the permission rules in effect on your host. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+
+Two consequences follow. Use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
+
+## Removal forms to prefer
+
+- **Scratch and probe files.** Use the PowerShell tool with `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`.
+- **Worktrees.** Use `git worktree remove --force <path>`.
+- **Tracked files.** Use `git rm <path>`, which records the deletion in the index.
+- **Bash `rm` when unavoidable.** Write one standalone `rm` with absolute literal paths, no chaining, and no globs. Keep every target inside the ephemeral namespace below.
+
+## The ephemeral namespace
+
+Keep a Bash `rm` to targets that resolve inside one of these:
+
+- The OS temporary root.
+- A path rooted at `/tmp` or `/temp`, drive-letter tolerant.
+- A path holding a `/worktrees/` or `/worktree/` segment, or a directory git reports inside a worktree admin directory.
+- `~/.claude`.
+
+Never pass a bare ephemeral root, such as `/tmp`, the OS temp root itself, or a bare directory named `worktrees` or `worktree`. A single stray argument then wipes the whole namespace.
+
+Write each target as a literal path. A variable, a `$(...)` or backtick expansion, or a brace glob hides what the command will delete from the reader and from the permission matcher.
+
+A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md).
+
+## Keep destructive literals out of the command string
+
+The permission matcher reads the raw command string. A destructive literal carried only as data still sits in that string, so it can push the command out of an allowed shape and into a prompt even though the shell never executes it. This covers a commit message, a PR or issue body, an echoed string, a `python -c` or `node -e` or `awk` argument, and a heredoc.
+
+- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [`gh-cli-conventions.md`](../../rules/gh-cli-conventions.md). Never `git commit -m` or `gh … -b`.
+- To exercise or verify a hook, run the committed test suite with `python -m pytest <test_file>`, which passes the command strings as in-language data. Never an inline `python -c` harness.
+
+## Every subagent prompt carries the rule
+
+A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers, such as review lenses, fix agents, or verifiers, copies this line into every subagent prompt it issues. A grandchild cleaning up its own probe file then uses an allowed form:
+
+> Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
+
+Prefer that a child leaves its scratch files for the parent to remove at teardown.
+
+## Sibling rules
+
+- [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
+- [`windows-filesystem-safe.md`](../../rules/windows-filesystem-safe.md) holds the safe `rmtree` and `force_rmtree` patterns for read-only Windows files.

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

@@ -0,0 +1,27 @@
+Back to the [rule entry](../../rules/explore-thoroughly.md).
+
+# 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)
+
+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.
+
+## Before committing to an approach
+
+- 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`](../../rules/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.

package/docs/rule-guides/filesystem-search.md

@@ -0,0 +1,53 @@
+Back to the [rule entry](../../rules/filesystem-search.md).
+
+# 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.
+
+## The scope invariant
+
+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.
+
+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 reports a missing IPC client window, which leaves the index state unknown. 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.

package/docs/rule-guides/memory-stores-durable-facts.md

@@ -0,0 +1,59 @@
+Back to the [rule entry](../../rules/memory-stores-durable-facts.md).
+
+# 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`.
+
+## Rule
+
+A memory must still help a fresh session, with no context, weeks later.
+
+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`](../../rules/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 persists, 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`](../../rules/correction-lens.md) | A memory records a decision, and the control holds the behavior |
+| [`verify-before-asking.md`](../../rules/verify-before-asking.md) | A recalled fact is a claim to re-check |
+| [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md) | Scratch output leaves with the task |

package/docs/rule-guides/no-contrast-framing.md

@@ -0,0 +1,70 @@
+Back to the [rule entry](../../rules/no-contrast-framing.md).
+
+# 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.
+
+## Rule
+
+State the chosen point. Leave the rejected reading out.
+
+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`](../../rules/asd-ste100-language.md) | Plain word choice, sentence style, and tone |
+| [`correction-lens.md`](../../rules/correction-lens.md) | Every correction becomes a control at the highest layer that can hold it |
+| [`research-mode.md`](../../rules/research-mode.md) | A claim carries its source |

package/docs/rule-guides/research-mode.md

@@ -0,0 +1,31 @@
+Back to the [rule entry](../../rules/research-mode.md).
+
+# Research mode (global)
+
+Three anti-hallucination constraints are always active.
+
+Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
+
+## 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.
+
+## 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.
+
+Check a citation against what the source says. 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. 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.

package/docs/rule-guides/verify-before-asking.md

@@ -0,0 +1,54 @@
+Back to the [rule entry](../../rules/verify-before-asking.md).
+
+# Verify before asking
+
+**When this applies:** Before asking the user any clarifying question during discovery, scoping, or implementation planning.
+
+## Rule
+
+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.
+
+## 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](../../rules/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 past state; 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.
+
+- 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`](../../rules/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.

package/docs/rule-guides/verify-runtime-state.md

@@ -0,0 +1,44 @@
+Back to the [rule entry](../../rules/verify-runtime-state.md).
+
+# Verify runtime state
+
+**When this applies:** Before stating that a component is fine, healthy, innocent, or working: during debugging, triage, or any judgment about whether something runs.
+
+## Rule
+
+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.
+
+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. 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.

package/package.json

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

package/rules/asd-ste100-language.md

@@ -1,40 +1,9 @@
-# ASD-STE100 Language Policy
+# ASD-STE100 language policy
 
-Use this rule as the sole general language authority for user-facing text in this repository.
-It defines ordinary word choice, sentence style, tone, punctuation, and prose form.
+**When:** Writing chat, tool narration, or repository prose.
 
-This text is an **ASD-STE100 Issue 9 conversational adaptation**. It applies the standard's
-clear-writing principles to assistant messages. The official standard remains the authority for
-definitions and dictionary decisions.
+Use the sole general language rule. Write short, complete sentences on one topic. Use active voice; lead with conditions; give one action per step. Use plain, precise words and stable terms. Expand abbreviations and contractions first; name unclear pronouns. Be inclusive; punctuate clearly. Preserve exact labels, identifiers, formulas, titles, and interface text. Send a result, blocker, or question. Mark injury or death `WARNING`, equipment damage `CAUTION`; state condition then result. Aim for 20 words per step, 25 per description. Treat checks as aids; have a human verify accuracy, terms, safety, confidentiality, and meaning.
 
-## Official sources
+**Enforcement:** none, the agent applies it.
 
-- [ASD-STE100 Simplified Technical English, Issue 9 (2025-01-15)](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
-- [ASD-STE100 FAQ](https://www.asd-ste100.org/STE_faq.html)
-- [ASD-STE100 About page](https://www.asd-ste100.org/about_STE.html)
-- [ASD-STE100 tools guidance](https://www.asd-ste100.org/STEsoftware.html)
-- [STEMG white paper on ASD-STE100 and artificial intelligence](https://www.asd-ste100.org/assets/files/WhitePaper-ASD-STE100_and_AI.pdf)
-
-## Writing policy
-
-- Write short, complete sentences. Keep one topic in each explanatory sentence.
-- Use active voice. Put the condition first when an instruction has a prerequisite.
-- Write imperative procedure steps. Give one action in each sentence.
-- Prefer familiar, precise words. Use one stable term for one item or action.
-- Write full words and explicit references. Expand abbreviations and contractions when they first appear.
-- Replace ambiguous pronouns with the noun they name.
-- Use inclusive, neutral language.
-- Use periods, commas, colons, and bullets to show structure.
-- Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
-- Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
-- Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
-- Aim for 20 words or fewer in a procedure sentence when the technical content allows.
-- Aim for 25 words or fewer in a descriptive sentence when the technical content allows.
-
-Use this policy for chat, tool narration, questions, plans, documentation, code-adjacent prose,
-and durable repository text. Named contracts can add behavior-specific structure, evidence,
-question routing, current-state documentation, completion, docstring, or publication rules.
-Those contracts use this policy for their language.
-
-Treat automated output and language checks as drafting aids. A responsible human verifies
-technical accuracy, terminology, safety, confidentiality, and intended meaning.
+**Full text:** [`docs/rule-guides/asd-ste100-language.md`](../docs/rule-guides/asd-ste100-language.md). Read it for sources.

package/rules/cleanup-temp-files.md

@@ -1,33 +1,9 @@
-# Clean Up Temporary Files
+# Clean up temporary files
 
-**When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
+**When:** Creating scratch files, debug dumps, or one-off helpers during a task.
 
-Source: [Anthropic — Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
+Prefer memory to scratch files and track any temporary files you create. At completion, remove those files and leave user-requested files in place. Files under the OS temporary root or `$CLAUDE_JOB_DIR` need no explicit removal; a parent handles child-agent scratch. Use the permitted removal form.
 
-## During a task
+**Enforcement:** none, the agent applies it.
 
-- Prefer working in memory over creating scratchpad files. Use variables and tool results instead of writing intermediate data to disk.
-- When a temporary file is needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
-
-## When a task is complete
-
-- Remove every temporary file, script, or helper file you created during the task.
-- Leave the working directory cleaner than you found it.
-- If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
-
-## Exceptions to the removal duty
-
-Three kinds of file are already ephemeral and need no explicit removal:
-
-- A file under the OS temporary root.
-- A file under `$CLAUDE_JOB_DIR`, which the harness clears with the job.
-- A child agent's scratch file, which the parent removes at teardown.
-
-Use an allowed removal form for everything else: [`destructive-commands.md`](destructive-commands.md) names them.
-
-## What counts as temporary
-
-- Scripts written to test a hypothesis or run a one-off check
-- Debug output files, log dumps, or intermediate data exports
-- Helper files created to work around tool limitations
-- Any file the user did not ask for and would not expect to find after the task
+**Full text:** [`docs/rule-guides/cleanup-temp-files.md`](../docs/rule-guides/cleanup-temp-files.md). Read it to classify a file or choose cleanup.

package/rules/correction-lens.md

@@ -1,110 +1,21 @@
-# Correction Lens
+# Correction lens
 
-**Standing rule. This file is never archived and never removed.** The permanence
-clause at the end of this document states what that binds.
+**When:** A user corrects you.
 
-**When this applies:** Every correction the user gives. A "no, do it this way", a
-"stop writing that word", a repeated review comment, a fix the user makes by hand
-after an agent hands work back. Each one is evidence that a control is missing,
-and the correction is handled by building that control.
+Open a control in the guarded repository, in the same run, at the highest capable layer. State the layer, why higher layers fail, and the change opened. Pair layers when both help. Move repeated corrections up a layer. Memory records the decision.
 
-## Rule
-
-A correction runs through five layers, in this order, and the lesson lands at the
-highest layer that can hold it. The change opens in the same run as the
-correction.
-
-| Priority | Layer | What holds the lesson | The lesson lands as |
-|---|---|---|---|
-| 1 | Codebase | The mistake is impossible by how the code is written | A type, a signature, a data structure, an API shape, a deleted branch |
-| 2 | Static analysis | A program reads the tree and decides | A lint rule, an enforcer check, a paired test, a CI gate |
-| 3 | Review tooling | A reviewer or a review bot reads the criterion | A `CODE_RULES.md` row, a `.cursor/BUGBOT.md` pointer, a Graphite or BugBot rule |
-| 4 | Skill | An agent follows a procedure | A skill under the agents home |
-| 5 | Style guide | Word choice and prose shape | A row in a `rules/*.md` file or a style document |
-
-Layer 1 is the goal every time. A lesson encoded there needs no reader, no run,
-and no agent to remember it. The wrong call has nowhere to live.
-
-## Choosing the layer
-
-Three sentences close every correction:
-
-1. The layer chosen.
-2. Why each higher layer cannot hold this lesson.
-3. The change opened at the chosen layer, by pull request.
-
-A layer holds a lesson when its own test passes:
-
-- **Layer 1 holds it** when a type, a signature, or a data structure can make the
-  wrong call fail to compile, fail to construct, or fail to exist.
-- **Layer 2 holds it** when a program reading the tree can separate right from
-  wrong with no judgment call.
-- **Layer 3 holds it** when a reader needs the criterion in front of them and a
-  program cannot decide it.
-- **Layer 4 holds it** when the lesson is a procedure with steps an agent runs.
-- **Layer 5 holds it** when the lesson is word choice or the shape of prose.
-
-Effort rules out no layer. A layer is ruled out when it lacks the capability to
-hold the lesson, and the sentence that rules it out says which capability is
-missing. "A lint for this would take a day" leaves layer 2 in play.
-
-Two layers often hold one correction. Take both: the shape at layer 1 and the
-check at layer 2 cost one run together and each covers what the other misses.
-
-## A repeated correction moves up a layer
-
-The same correction arriving a second time is the measurement. The layer chosen
-the first time was too low. Move the lesson one layer up and say so in the same
-run.
-
-A review comment that repeats across pull requests reads the same way. Each
-repetition names the layer below the reviewer as the one that needs the control.
-Count the repetitions.
-
-## Where the control lands
-
-A control lands in the repository whose code, CI, or pipeline it guards. A
-control for one repository's workflows, review bots, pipelines, or agents lands
-in that repository. This package takes only repo-agnostic controls, the
-environment and development pieces any repository could use, so every session
-that loads this environment carries them. A control written into one project's
-instructions reaches that project alone, and a control written into a chat reply
-reaches that conversation alone.
-
-Memory holds the decision. The control holds the behavior. A correction that
-produced a memory file and nothing else has been recorded and never encoded, so
-the rule still binds. Open the control.
-
-## Trust grows as the controls catch the common mistakes
-
-Add agents after the controls catch what agents get wrong, and start from a
-workflow small enough to watch. Each repeated correction becomes a stronger
-control, and the number of agents rises behind it.
-[`docs/high-trust-agent-delivery.md`](../docs/high-trust-agent-delivery.md)
-carries the model this comes from, including the layered-controls picture and
-the inner and outer delivery loops.
+| Priority | Layer | Control |
+|---|---|---|
+| 1 | Codebase | Prevent the mistake. |
+| 2 | Static analysis | Programmatic check. |
+| 3 | Review tooling | Reviewer criterion. |
+| 4 | Skill | Agent procedure. |
+| 5 | Style guide | Wording rule. |
 
 ## Permanence
 
-This file stays in `rules/`. A prune pass, an archive sweep, a consolidation, or
-a rewrite that would move it into `rules-archived/` stops at this line. The
-"Never archived" section of
-[`packages/claude-dev-env/rules-archived/ARCHIVE-MANIFEST.md`](../rules-archived/ARCHIVE-MANIFEST.md)
-names it, and
-[`archiving-agent-config.md`](archiving-agent-config.md) names the same
-exemption from the archiving procedure's side.
-
-An edit that sharpens this rule is welcome. The file stays.
-
-## Codex copy
-
-Codex reads its repository `AGENTS.md`. The standalone excerpt it receives lives in [`docs/rule-guides/correction-lens-excerpt.md`](../docs/rule-guides/correction-lens-excerpt.md).
+Keep this file in `rules/`. A prune, archive, consolidation, or rewrite that would move it stops here. Edits that sharpen it are welcome.
 
-## Sibling rules
+**Enforcement:** none, the agent applies it.
 
-| Rule | Role |
-|---|---|
-| [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md) | A gate blocks on a breaking finding and records a smell |
-| [`code-standards.md`](code-standards.md) | The layer map of contract, pointer, enforcer, lint, session rules |
-| [`archiving-agent-config.md`](archiving-agent-config.md) | How a rule leaves service, and which files are exempt |
-| [`falsify-before-green.md`](falsify-before-green.md) | A new layer-2 check counts once it has run red on a named break |
+**Full text:** [`docs/rule-guides/correction-lens.md`](../docs/rule-guides/correction-lens.md). Read it when choosing a layer or locating a control.

package/rules/destructive-commands.md

@@ -1,47 +1,11 @@
-# Destructive Commands in Bash
+# Destructive commands in Bash
 
-No hook watches Bash commands for destructive patterns. What you face is the harness permission prompt. The harness raises it from the session permission mode and the permission rules in effect on your host. In a background or auto-mode run no human can answer that prompt, so the call stalls.
+**When:** Removing files or writing a destructive command string.
 
-Two consequences follow. Use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
-
-## Removal forms to prefer
-
-- **Scratch and probe files.** Use the PowerShell tool with `Remove-Item -Recurse -Force -Confirm:$false <absolute path>`.
-- **Worktrees.** Use `git worktree remove --force <path>`.
-- **Tracked files.** Use `git rm <path>`, which records the deletion in the index.
-- **Bash `rm` when unavoidable.** Write one standalone `rm` with absolute literal paths, no chaining, and no globs. Keep every target inside the ephemeral namespace below.
-
-## The ephemeral namespace
-
-Keep a Bash `rm` to targets that resolve inside one of these:
-
-- The OS temporary root.
-- A path rooted at `/tmp` or `/temp`, drive-letter tolerant.
-- A path holding a `/worktrees/` or `/worktree/` segment, or a directory git reports inside a worktree admin directory.
-- `~/.claude`.
-
-Never pass a bare ephemeral root, such as `/tmp`, the OS temp root itself, or a bare directory named `worktrees` or `worktree`. A single stray argument then wipes the whole namespace.
-
-Write each target as a literal path. A variable, a `$(...)` or backtick expansion, or a brace glob hides what the command will delete from the reader and from the permission matcher.
-
-A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](cleanup-temp-files.md).
-
-## Keep destructive literals out of the command string
-
-The permission matcher reads the raw command string. A destructive literal carried only as data still sits in that string, so it can push the command out of an allowed shape and into a prompt even though the shell never executes it. This covers a commit message, a PR or issue body, an echoed string, a `python -c` or `node -e` or `awk` argument, and a heredoc.
-
-- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [`gh-cli-conventions.md`](gh-cli-conventions.md). Never `git commit -m` or `gh … -b`.
-- To exercise or verify a hook, run the committed test suite with `python -m pytest <test_file>`, which passes the command strings as in-language data. Never an inline `python -c` harness.
-
-## Every subagent prompt carries the rule
-
-A prompt-delivered directive reaches only the agent that gets it. An agent that spawns its own workers, such as review lenses, fix agents, or verifiers, copies this line into every subagent prompt it issues. A grandchild cleaning up its own probe file then uses an allowed form:
+No hook watches Bash commands; a permission prompt can stall unattended work. Keep destructive literals out of command strings, including data. Use literal absolute targets; never target a bare temporary root. Use `git rm` for tracked files. Pass bodies by file and test hooks through the test suite. Copy this line into every subagent prompt:
 
 > Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
 
-Prefer that a child leaves its scratch files for the parent to remove at teardown.
-
-## Sibling rules
+**Enforcement:** none, the agent applies it; the harness may prompt.
 
-- [`cleanup-temp-files.md`](cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
-- [`windows-filesystem-safe.md`](windows-filesystem-safe.md) holds the safe `rmtree` and `force_rmtree` patterns for read-only Windows files.
+**Full text:** [`docs/rule-guides/destructive-commands.md`](../docs/rule-guides/destructive-commands.md). Read it before any removal.

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.