claude-dev-env 7.7.1 → 8.1.0

package/hooks/validators/test_code_quality_checks.py

@@ -127,3 +127,25 @@ class TestFileLength:
             assert "400" in violations[0].message or "lines" in violations[0].message.lower()
         finally:
             temp_path.unlink()
+
+
+class TestTestFileExemption:
+    def test_long_function_in_a_test_file_passes(self) -> None:
+        tree = ast.parse(BAD_LONG_FUNCTION)
+        violations = check_function_length(tree, "packages/app/test_widget.py")
+        assert violations == []
+
+    def test_long_function_outside_a_test_file_still_fails(self) -> None:
+        tree = ast.parse(BAD_LONG_FUNCTION)
+        violations = check_function_length(tree, "packages/app/widget.py")
+        assert len(violations) == 1
+
+    def test_long_test_file_passes(self, tmp_path: Path) -> None:
+        temp_path = tmp_path / "test_widget.py"
+        temp_path.write_text("x = 1\n" * 450, encoding="utf-8")
+        assert check_file_length(temp_path) == []
+
+    def test_long_conftest_passes(self, tmp_path: Path) -> None:
+        temp_path = tmp_path / "conftest.py"
+        temp_path.write_text("x = 1\n" * 450, encoding="utf-8")
+        assert check_file_length(temp_path) == []

package/package.json

@@ -1,11 +1,10 @@
 {
     "name": "claude-dev-env",
-    "version": "7.7.1",
+    "version": "8.1.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs",
-        "cde-pstack": "bin/pstack.mjs",
         "codex-compat": "bin/codex-compat.mjs",
         "cde": "bin/cde.mjs"
     },

package/rules/anti-corollary-tests.md

@@ -28,12 +28,14 @@ When the code reduces each input to a canonical form and then compares the forms
 
 Name the degenerate value a dead implementation would return — empty string, `None`, `False`, a blanket refusal, an empty collection. When the test's expected value equals that default, the test passes whether the mechanism works or not. On its own it proves nothing.
 
-**Do this:** keep at least one case that expects the **non-default** answer, and drive the real code path — not a mock that only records that a call happened.
+**Do this:** keep at least one case that expects the **non-default** answer, and drive the production code path — not a mock that only records that a call happened.
 
 ### 3. What single change to the code would make this test fail?
 
 When the honest answer is "none," or "only a change that also breaks everything else," the test is decoration. Drop it or rewrite it so one named mutation kills it.
 
+**The policy-surface case.** A test that asserts a policy's own wording appears in the file that declares the policy has one mutation available: editing that sentence. It cannot report whether anything obeys the policy, so a suite full of such tests measures how many files repeat a rule, which is the duplication the reader was already complaining about. Assert instead that the surfaces the policy governs comply with it, and let the declaring file be the input rather than the subject.
+
 ## What a mechanism with a degenerate failure mode needs
 
 1. **At least one non-default case** that exercises the live path and expects the non-default answer.

package/rules/archiving-agent-config.md

@@ -0,0 +1,70 @@
+# Archiving a Rule, Skill, Agent, or Command
+
+**When this applies:** Pruning agent configuration in this package — moving a
+rule, skill, agent, or command out of service, and deciding whether one is
+still used at all.
+
+## Prove disuse before you remove
+
+A prune is only as good as the usage evidence behind it, and three habits give
+confident wrong answers here.
+
+**Grepping the file's own name measures documentation, not use.** Enforcement in
+this package is rarely named after the file that describes it. Resolve what the
+file names instead: does the script exist, does the lint rule id appear in the
+registry, does the check run. A rule with no mention of its slug anywhere can
+still have a live checker behind it under a different name.
+
+**Three files name every capability and prove nothing about any of them.**
+`CHANGELOG.md` records history. The `README.md` inventory table lists what
+ships. `bin/ever-shipped-skills.mjs` is a registry the prune reads, and it keeps
+archived names on purpose. Subtract all three before you read a referrer count.
+
+**A path this tree does not hold is not by itself a stale reference.** This
+package installs into other repositories, so a rule or skill naming a file that
+lives in the host repository is working as intended. Ask whether the specific
+script or id it names resolves where it would run, not whether the path exists
+here.
+
+## Archive rather than delete
+
+Move the file with `git mv` into the archive sibling: `rules-archived/` beside
+`rules/`, `.agents/skills-archived/` beside `.agents/skills/`. The archive is a
+sibling and never a child, because the installer copies a content directory
+whole.
+
+Archives ship nothing by omission. `CONTENT_DIRECTORIES` in `bin/install.mjs`
+names the directories the installer writes, and no archive sibling is on that
+list; skills are enumerated from `.agents/skills` alone. So an archived file
+leaves every install without any further step, and it comes back with the
+reverse `git mv`.
+
+Record a row in the archive manifest for each file: why it went, the `git mv`
+that restores it, and every other edit a restore has to undo. A restore that has
+to be reconstructed from the diff is not recoverable in any useful sense.
+
+## Make the archive stick
+
+Three things do not follow the file on their own.
+
+**A skill's name stays in `bin/ever-shipped-skills.mjs`.** The prune computes
+the retired set as every name ever shipped minus the names installed now, and
+that is how a stale copy is moved out of a host's agents home. Delete the name
+and the copy is stranded on every machine that has it.
+
+**Add the archived name to the banned active-capability list.** The reference
+checker in `scripts/active_capability_references.py` does not resolve a named
+capability against the shipped inventory; it reports a name only when that name
+sits on `ALL_BANNED_ACTIVE_CAPABILITY_NAMES`. Until the archived name is on that
+list, every leftover mention of it passes.
+
+**A renamed skill directory takes its tests out of the run.** The node test
+command globs `.agents/skills/**/*.test.mjs`, so a suite under an archived skill
+stops running without failing. Check that the count you expect still runs.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`retired-hook-prose.md`](retired-hook-prose.md) | Prose names only hooks that run, and retiring a gate drops the detours it required |
+| [`doc-inventory-integrity.md`](doc-inventory-integrity.md) | Inventory tables stay in step with what ships |

package/rules/asd-ste100-language.md

@@ -26,7 +26,7 @@ definitions and dictionary decisions.
 - Use inclusive, neutral language.
 - Use periods, commas, colons, and bullets to show structure.
 - Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
-- Use `WARNING` for a real risk of injury or death. Use `CAUTION` for a real risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
+- 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.
 

package/rules/ci-owns-the-gate.md

@@ -0,0 +1,73 @@
+# CI Owns the Gate
+
+**When this applies:** Before pushing a branch, and any time a repository's full
+check suite or policy gate is about to run on your own machine.
+
+## Rule
+
+The gate runs once, and it runs on CI. Push the branch, read the verdict, act on
+what it says.
+
+The inner development loop stays yours. Run the single test you are writing, as
+often as it helps. That is how the change gets built. This rule governs the
+second full pass, the one whose only product is a prediction of CI's answer.
+Push instead, and spend the wait on the next piece of work.
+
+## Why
+
+**A pinned gate answers only from its pinned revision.** The workflow names an
+exact revision of the policy package, and that revision decides which rules run.
+The copy under your home directory is a separate artifact at its own revision. A
+run against the home copy reports on those rules, which are a different question
+from the one CI asks. Treat its exit code as information about the home copy
+alone.
+
+**Self-hosted runners often share your machine.** Where the runners execute on
+the same host as your shell, a local suite run draws its processor time from the
+runners, and it does so while they work on the branch you just pushed. Read
+where the runners live, and count a local run against the same budget.
+
+**One authoritative answer beats two.** Where both runs agree, the second one
+restated the first. Where they differ, the environments differ, and CI is the
+environment that decides.
+
+## Running a gate locally
+
+Clone the revision the workflow pins, then point the gate at that clone. That
+run asks CI's question and its answer carries. Report a local result by naming
+the revision it used, so a reader can tell which question it answered.
+
+The selection flag decides which question the staged policy lint answers.
+`--staged` and `--base <revision>` carry each file's prior text, so the lint
+subtracts what the prior text already reported and only a breach the change
+introduced survives. `--files` and `--repository` carry no prior text, so every
+breach in the file reports and the command exits non-zero on debt the change
+never touched. CI runs the merge-base form, so reproduce a CI verdict with it:
+
+```
+git merge-base HEAD origin/main
+python packages/claude-dev-env/scripts/cde_lint.py --base <the revision that printed>
+```
+
+A `--files` run that comes back red on a file you touched has answered a
+different question. Read the reported line before you treat it as yours.
+
+## The verdict belongs to CI
+
+CI decides whether a change passed, from evidence CI gathered. Keep that loop
+closed. A flag, trailer, receipt, or environment variable through which the
+change under test announces its own result hands the verdict to the subject.
+Where the runner and the agent share one host, a signature names the same party
+twice, so it carries the claim no further.
+
+A cache stays available on one condition. CI derives the key itself from the
+tree it is about to test, looks for a previous run under that key, and
+republishes that result. CI computes, CI verifies, CI decides.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`git-workflow.md`](git-workflow.md) | Confirm each required context fired after the push |
+| [`verify-runtime-state.md`](verify-runtime-state.md) | A status field is a report; read the thing the work was meant to make |
+| [`falsify-before-green.md`](falsify-before-green.md) | A green counts as evidence once the check has run red on a deliberate break |

package/rules/cleanup-temp-files.md

@@ -7,7 +7,7 @@ Source: [Anthropic — Reduce file creation in agentic coding](https://platform.
 ## During a task
 
 - 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 genuinely needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
+- 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
 

package/rules/code-standards.md

@@ -2,7 +2,7 @@
 
 > **Canonical review contract:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — the human and AI review contract for code quality, loaded on demand.
 > **Checked-in pointer:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the file Cursor BugBot reads; it points at `CODE_RULES.md`.
-> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. Use `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit, and CI runs the same lint against the merge base. Each mechanical rule carries a synchronization test.
+> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. CI runs that lint against the merge base. Each mechanical rule carries a synchronization test.
 
 ## Policy surface map
 
@@ -11,7 +11,7 @@
 | Contract | `docs/CODE_RULES.md` | Full review criteria for PR agents, loaded on demand |
 | Pointer | `.cursor/BUGBOT.md` | Checked-in file Cursor BugBot reads; points at `CODE_RULES.md` |
 | Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained checks the staged policy lint runs; not generated from the docs |
-| Lint | `scripts/cde_lint.py` | Runs the enforcer and the other policy rules over staged or changed files |
+| Lint | `scripts/cde_lint.py` | Runs the enforcer and the other policy rules over staged or changed files, grading each against the file's prior text; see [`ci-owns-the-gate.md`](ci-owns-the-gate.md) for what each selection flag reports |
 | Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
 Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or generating code. Prefer linking this ref over restating rules.
@@ -19,7 +19,7 @@ Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or genera
 Two standards live in `CODE_RULES.md` in full:
 
 - **TDD** — CODE_RULES §8 / AGENTS Tests: red, green, refactor; no production code before a failing test.
-- **Right-sized engineering** — CODE_RULES §7 / AGENTS Design: functions over classes; concrete over abstract; add an abstraction at the commit that introduces its second concrete implementation.
+- **Right-sized engineering** — CODE_RULES §7 / AGENTS Design: functions over classes; concrete over abstract; add an abstraction at the commit that introduces its second concrete implementation. That count is a house call, one occurrence earlier than the rule of three Fowler credits to Don Roberts. The direction comes from the literature; the number does not, so read it as this package's setting rather than as a cited standard.
 
 BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the TDD cycle.
 
@@ -27,7 +27,6 @@ BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers
 
 | Concern | Rule file |
 |---|---|
-| Question routing | [`ask-user-question-required.md`](ask-user-question-required.md) |
 | Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
 | Multi-step task list | skill `task-build` (see agents catalog) |
 

package/rules/docstring-prose-matches-implementation.md

@@ -28,15 +28,15 @@ Read the body and the docstring side by side. Apply each check that matches the
 - **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
 - **Returns / Raises / Note claims** — each free-form claim matches the body.
 
-Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and no write-time hook runs them. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. Free-form rest is judgment.
+Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and CI runs it against the merge base. Free-form rest is judgment.
 
 ## Hook prose matches its detector
 
 A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
 
-The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit.
+The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so CI is where it reports.
 
-After writing a hook, ask: would a token matching every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
+After writing a hook, ask: would a token matching every word of this message trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
 
 ## Full standard
 

package/rules/explore-thoroughly.md

@@ -13,7 +13,7 @@ Note: This deliberately chooses exploration depth over the "commit and execute q
 
 ## Exploration scales with risk
 
-- Small change to a familiar file: a quick read of the file and its immediate neighbors is sufficient.
+- 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.
 
@@ -23,4 +23,4 @@ The depth budget shrinks once the evidence is in hand. When you can already name
 
 ## Relationship to other rules
 
-- **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the actual codebase.
+- **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the codebase.

package/rules/failure-blast-radius.md

@@ -47,7 +47,7 @@ The re-raise comes first, sending an escalation directly through the boundary.
 An agent that hits a member failure keeps working the problem. Three things bound how:
 
 - **Repair in place.** The current run preserves every completed member.
-- **Three real attempts, then park.** An attempt is a theory of the cause, acted on. Re-running the same code on the same input counts as one attempt. Three theories cover the obvious cause, the second guess, and the cause revealed by the first two attempts. Judgment selects each theory; the third attempt sets the stopping point. After the third theory fails, park the member with its reason and move to the next. Parked members return after the batch.
+- **Three attempts, then park.** An attempt is a theory of the cause, acted on. Re-running the same code on the same input counts as one attempt. Three theories cover the obvious cause, the second guess, and the cause revealed by the first two attempts. Judgment selects each theory; the third attempt sets the stopping point. After the third theory fails, park the member with its reason and move to the next. Parked members return after the batch.
 - **The batch always reaches a deliverable.** Complete every member that can complete, produce the packaged artifact, then work the parked list. A run with 34 of 37 members complete and 3 parked records progress and continues to delivery.
 
 ## Three alike means one cause
@@ -58,13 +58,13 @@ The run report groups parked members by that signature and names every group of
 
 ## Close the run with every outcome
 
-Every issue the run hit gets one line in the closing report: what failed, and how it ended — repaired, worked around, or parked. Members that finished after a repair belong in that list beside the parked ones. A workaround patched past mid-run is the likeliest real defect in the batch, because the closing report becomes its durable record.
+Every issue the run hit gets one line in the closing report: what failed, and how it ended — repaired, worked around, or parked. Members that finished after a repair belong in that list beside the parked ones. A workaround patched past mid-run is the likeliest defect in the batch, because the closing report becomes its durable record.
 
-The report then presents each candidate to the owner for a durable-fix decision, names the fixes the run recommends, and waits for the answer. The next run builds the selected fix; the current run completes its deliverable first.
+The report then presents each candidate to the owner for a durable-fix decision and names the fix the run recommends for each one. The report is a statement, not a gate: the current run completes its deliverable and ends. A later run builds whichever fixes the owner selects, and the recommendation stands as the default for any the owner does not rule on.
 
 ## Enforcement
 
-`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so CI is where it reports. CI runs the same lint against the merge base.
 
 The check requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
 
@@ -82,7 +82,7 @@ scope, and the deliverable remains the run priority.
 
 Repair in place and preserve every completed asset in the current run.
 
-Three real attempts, then park. An attempt is a theory of the cause, acted
+Three attempts, then park. An attempt is a theory of the cause, acted
 on. Repeated execution of one theory remains one attempt.
 Three theories cover the obvious cause, the second guess, and the cause
 revealed by the first two attempts. Use your judgment to select each theory;
@@ -108,11 +108,12 @@ stops. For an asset-level stop, put the handling inside the loop body.
 Close the run by reporting what broke and what you did about it. Every issue
 gets one line: what failed, and how it ended — repaired, worked around, or
 parked. Include the ones you solved; a workaround you patched past in attempt
-two is the likeliest real defect in the list, because the closing report becomes
+two is the likeliest defect in the list, because the closing report becomes
 its durable record.
-Present each candidate for the owner's durable-fix decision, state which fixes
-you recommend and why, and wait for the answer. The next run builds the
-selected durable fix after this run completes its deliverable.
+Present each candidate for the owner's durable-fix decision and state which
+fix you recommend for each and why. Do not wait on the answer. Complete this
+run's deliverable and end. A later run builds whichever fixes the owner
+selects, and your recommendation stands as the default for the rest.
 
 Report as: N of M complete, K parked, and what you are working now.
 Close with: what broke, how each one ended, and which of them deserve a

package/rules/git-workflow.md

@@ -29,9 +29,10 @@ opens with the bot's own marker line. The description rules in this file, the
 failure signature in the release job log reads
 `could not parse pull request body as a release PR`.
 
-Use the `pr-description-writer` agent before creating a pull request or
-rewriting its full description. Publish its title and body file through
-`.agents/skills/pull-request/scripts/pull_request.py`.
+The `pr-description-writer` agent writes a title and body from the diff when
+you want one. Publish the title and body file through
+`~/.agents/skills/pull-request/scripts/pull_request.py`. That path is under the
+agents home, not the repository. A worktree holds no `.agents/` copy.
 
 Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
 otherwise), then run `<managed-root>/scripts/durable_post_lint.py` before any
@@ -50,14 +51,28 @@ untouched.
    - Before push: `gh pr ready --undo`
    - After review approved: `gh pr ready`
 
-## Run the required checks locally before the first push
-
-Read the branch ruleset for the required check contexts before you push a branch,
-or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
-Then run that exact gate command locally against that level's own base, on every
-level. A required check that never fired is invisible debt at every level, and it
-surfaces only after the whole stack is pushed, when the repair costs a second pass
-over every branch.
+## Confirm the required checks fired, and let CI run them
+
+The gate runs once, and it runs on CI. Push the branch and read its verdict.
+[`ci-owns-the-gate.md`](ci-owns-the-gate.md) holds the reasoning and the shape
+a local run takes when one is warranted.
+
+Read the branch ruleset for the required check contexts before you push a
+branch, or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
+Read it to learn which checks must report. After the push, confirm each of those
+contexts appears on that level's head. A required check that never fired is
+invisible debt at every level, and it surfaces only after the whole stack is
+pushed, when the repair costs a second pass over every branch.
+
+A red required check blocks the branch, whoever owns the failing line. The
+staged policy lint grades a change against the file's prior text, so a finding
+that survives is one the change introduced or made worse. Fix that line in the
+next push or report the branch blocked. A finding the change did not introduce
+is a gate-scoping defect: report it against the lint and leave the file's shape
+alone. Restructuring a file to satisfy a mis-scoped check trades one finding for
+a set of new ones. Read the gate's own report rather than a narrower substitute. A
+single-file mypy call cannot see sibling modules and reports false import
+errors, so it neither clears nor convicts a change.
 
 A checks listing that reports nothing on the branch is a finding, not a neutral
 state. Find out whether the workflow's event filters exclude the branch, or whether
@@ -82,7 +97,7 @@ what it calls.
 Force-with-lease protects the ref. It protects nobody's understanding of what the
 branch now holds. When a rewrite moves content between levels of a stack, or
 otherwise changes what a branch contains, refresh that pull request's description
-through the `pr-description-writer` agent before you ask anyone to read or merge it.
+before you ask anyone to read or merge it.
 
 ## Never commit working documents or images
 

package/rules/long-horizon-autonomy.md

@@ -12,7 +12,9 @@ This is the autonomous-run partner to the ambiguous case: research and recommend
 
 ## Do not end a turn on a promise
 
-Pause for the user only when the work truly needs them: a destructive or irreversible action, a real scope change, or input only they can give. When you hit one, ask through `AskUserQuestion` and end the turn. Do not end on a promise about work you have not done.
+Pause for the user only when the work truly needs them: a destructive or irreversible action, a scope change, or input only they can give. When you hit one, ask through `AskUserQuestion` and end the turn. Do not end on a promise about work you have not done.
+
+A pause is a request you deliver, not a state you enter. Put it in the channel the user reads, name the one input you need and what resumes the moment it arrives, and shape it so a single word answers it. A decision recorded in a status line, a checklist, a working document, or a side thread is a note; the user never learns they are the bottleneck, and the work sits. Keep everything that does not depend on the answer moving while it is outstanding.
 
 Before you end any turn, read your last paragraph. If it is a plan, an analysis, a list of next steps, or a statement of intent ("I'll run the tests", "next I'll wire it up"), do that work with tool calls before you stop. End the turn only when the task is done or you are blocked on input only the user can give.
 

package/rules/nas-ssh-invocation.md

@@ -25,5 +25,5 @@ Host, ssh port and ssh user are constants inside the runner and are also under t
 
 To copy a file, write it inside the script with a quoted heredoc rather than reaching for `scp`.
 
-The `/tmp` size limit, how to tell a real break from a platform-only one, and a failure-to-cause
+The `/tmp` size limit, how to tell a break in the code from a platform-only one, and a failure-to-cause
 table: `@~/.claude/docs/nas-ssh-invocation.md`.

package/rules/orphan-css-class.md

@@ -15,7 +15,7 @@ When you add a `class="..."` attribute, add its `.<class>` selector to the `<sty
 
 ## What the check covers
 
-The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. It:
+The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. CI runs that lint against the merge base. It:
 
 1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
 2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.

package/rules/paired-test-coverage.md

@@ -18,7 +18,7 @@ When you add a public function to a module whose test suite already exercises th
 
 ## What the check covers
 
-Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. The two checks cover the two write orders.
+Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
 
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 

package/rules/research-mode.md

@@ -16,8 +16,10 @@ Every recommendation, claim, or piece of advice must cite a specific source:
 
 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 actual text first before analyzing. Ground your response in word-for-word quotes, not paraphrased summaries. Reference the quote when making your point.
+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
 

package/rules/retired-hook-prose.md

@@ -5,12 +5,20 @@ paths:
 
 # Rules Prose Names Only Hooks That Run
 
-A hook module runs when `hooks/hooks.json` registers it or a dispatcher roster hosts it. A module can survive on disk while appearing in neither place, and it then reaches no tool call. Prose that gives such a module a present-tense action describes a gate the reader never faces, and a reader who trusts it skips the check they were meant to run by hand.
+A hook module runs when `hooks/hooks.json` registers it or a dispatcher roster hosts it. A module can survive on disk while appearing in neither place, and it then reaches no tool call. Presence on disk settles nothing in either direction. The installer writes an inert stand-in at a retired hook path when a host's stale `settings.json` still names it, because a registered path that resolves to nothing makes the interpreter exit 2 and the harness reads a PreToolUse exit 2 as a block. A retired hook can also keep working through a different door: its logic moves into a `*_parts/` package that a live module imports, so the hook name is dead while the check it carried still fires. Prose that gives such a module a present-tense action describes a gate the reader never faces, and a reader who trusts it skips the check they were meant to run by hand.
 
-The staged policy lint carries this check as its `retired-hook-prose` rule. It reads each Markdown file under a `rules/` directory, takes every backticked hook module name, and reports the ones that are registered nowhere and that carry a present-tense action verb in the rest of the sentence. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+The staged policy lint carries this check as its `retired-hook-prose` rule. It reads each Markdown file under a `rules/` directory, takes every backticked hook module name, and reports the ones that are registered nowhere and that carry a present-tense action verb in the rest of the sentence. CI runs that lint against the merge base. Its reach stops at that directory. Skill manifests, agent definitions, commands, `docs/` and `_shared/` all carry prose about hooks and none of it is read, so a stale claim there passes CI and reaches every reader. Sweep those trees by hand against the retired roster whenever you retire a hook.
 
 A module name counts as a hook when it ends in one of the hook families, such as `_blocker`, `_enforcer`, `_gate`, `_tracker`, or `_dispatcher`, and when it either sits under `hooks/` or appears in `RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS` in `bin/install.mjs`. A support module inside the hooks tree carries no such family suffix, so it stays out of the check. A hook deleted from disk without an entry in that roster resolves nowhere, so add the roster entry when you retire a hook.
 
 Two shapes pass. A past-tense sentence that records what a hook once did makes no live claim. A sentence that names the staged policy lint, `cde_lint`, or a repository check tells the reader where the work runs now, so the module name reads as a pointer to code.
 
+## Retiring a gate drops the detours it required
+
+A gate and the standing orders written to satisfy it are one unit. An order that says to spawn a named agent first, to carry a magic token into a spawn, or to route through an extra step exists because some check demanded it. When the check goes, that order is a toll every later session pays for nothing, and it costs more than a stale sentence does, because a reader obeys it.
+
+So retiring a hook is finished only when the detours it required are gone in the same change. Search for the order, not for the module: the module name is what the lint looks for, and a detour usually names the agent, the step, or the token instead, which is how these survive a lint that reads the same file. Drop the requirement and keep the agent, the skill, or the command itself; a capability nobody is forced to call costs nothing, while a forced call costs every run.
+
+The same duty covers every lane a withdrawn standard rode on. A threshold enforced by a hook is often also stated in an audit rubric, an agent's instruction table, or a review prompt. Withdraw all of them together, and name the lanes in the archive entry. Removing the fast mechanical lane and leaving the slow judgment lane keeps the standard in force while deleting the text that a reader could argue with.
+
 When the rule reports a line, say what the reader faces now. Name the harness permission prompt, the staged policy lint, or the repository check that carries the work, or drop the claim.

package/rules/testing.md

@@ -14,14 +14,14 @@ paths:
 
 ## Complete Mocks for Testability
 
-**Mocks must include all fields the component actually uses.**
+**Mocks must include all fields the component uses.**
 
 If a component renders field X, the mock must have field X with a valid value.
 Incomplete mocks make it impossible to distinguish "broken code" from "missing data".
 
-## Tests Exercise Real Behavior
+## Tests Exercise Production Behavior
 
-Tests exercise real behavior, real data, and production code paths. A test that asserts on a stand-in for the production path proves the stand-in works.
+Tests exercise production behavior, production data, and production code paths. A test that asserts on a stand-in for the production path proves the stand-in works.
 
 ## No Gate Holds the Test-First Order
 

package/rules/verify-before-asking.md

@@ -19,6 +19,7 @@ Before writing any AskUserQuestion or asking a clarifying question in chat, eval
 | 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.
 
@@ -27,7 +28,7 @@ Only after confirming the answer cannot be obtained through any available tool,
 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, ask through `AskUserQuestion` (see [`confirm-implementation-forks`](confirm-implementation-forks.md)).
+- When no tool can settle it and the user has a stake in the answer, ask through `AskUserQuestion`.
 
 ## Questions That Belong to the User
 
@@ -37,6 +38,8 @@ Reserve user questions for:
 - **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?"

package/rules/verify-runtime-state.md

@@ -23,7 +23,7 @@ Before stating a runtime claim, gather the matching live signal:
 | 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 real request and read the response. |
+| 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. |
@@ -39,4 +39,4 @@ Only after a live signal backs the claim do you state it.
 **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 actually holds.
+**Right:** Print the loaded config at runtime and report the value the process holds.

package/rules/windows-filesystem-safe.md

@@ -12,6 +12,6 @@ Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` file
 
 In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing paths — `ReadOnly` directories break the non-recursive form. When the call must be non-recursive, strip the attribute first (`(Get-Item $path -Force).Attributes = "Directory"` / `os.chmod(path, stat.S_IWRITE)`).
 
-The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. CI runs that lint against the merge base.
 
 Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first, so a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES, "Reuse before create"). The same `rmtree-safety` lint rule reports a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` check, which a copy between two distant packages slips past.

package/rules/workflow-substitution-slots.md

@@ -9,4 +9,4 @@ In a `.workflow.js` agent-prompt template, every per-call or per-iteration value
 
 When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
 
-The staged policy lint carries this check as its `workflow-substitution` rule. It reports a `.workflow.js` file whose looped content holds a bare `<word>_<i|j|k>` token as a per-iteration path segment. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. No write-time hook reports this, so a bare token stays on disk until the lint runs.
+The staged policy lint carries this check as its `workflow-substitution` rule. It reports a `.workflow.js` file whose looped content holds a bare `<word>_<i|j|k>` token as a per-iteration path segment. CI runs that lint against the merge base. No write-time hook reports this, so a bare token stays on disk until the lint runs.