claude-dev-env 8.0.0 → 8.1.0

package/audit-rubrics/audit-categories.json

@@ -389,10 +389,6 @@
           "id": "J3",
           "axis_name": "Constants location"
         },
-        {
-          "id": "J4",
-          "axis_name": "File-global use-count"
-        },
         {
           "id": "J5",
           "axis_name": "Abbreviations"

package/audit-rubrics/category_rubrics/category-e-dead-code.md

@@ -26,7 +26,7 @@
 | E6 | Removed-but-not-deleted symbol references | Symbols renamed/removed elsewhere with stale import or call sites left behind. |
 | E7 | Test fixtures / helpers defined but never used | Pytest fixtures, test data builders, mock factories with no callers. |
 | E8 | Stub / placeholder code without tracking | Judge `pass`, `...`, and `raise NotImplementedError` directly; track follow-up work outside source code. |
-| E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. The file-global use-count gate exempts a constants module because every name it exports legitimately carries zero in-file references, so a genuinely dead export slips past the write-time gate. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
+| E9 | Constants-module exports with no importer | A module-level `UPPER_SNAKE` constant added to a `*_constants.py` / `config/` module that no module in the repo imports and that the constants file itself never references. No write-time check reads a constants module, and every name such a module exports carries zero in-file references by design, so a dead export reaches the audit untouched. Distinguish dead from live by grepping the whole repo for each constant name: a sibling such as `MEDIUM_TERMINAL` imported by a consumer module is live; a `MEDIUM_TEXT` that no `from ... import` line and no in-file reference names is dead (CODE_RULES 9.8). Remove the dead export. |
 
 ---
 

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -5,7 +5,7 @@
 **Examples of Category J findings:**
 - A literal `60` appears in a production function body (magic value rule).
 - A new `MAX_RETRIES = 3` declared at module scope outside `config/`.
-- A parameter named `ctx` instead of `context` (abbreviation rule).
+- A parameter named `ctx` where the name `context` belongs (abbreviation rule).
 - A function that returns a value with no return-type annotation.
 - A new `# explains the loop logic` comment added to production code.
 
@@ -20,7 +20,6 @@
 | J1 | Magic values in production function bodies | Literals other than `0`, `1`, `-1` inside production function bodies. Test files exempt. |
 | J2 | String-template magic | f-strings whose structural literal text (paths, URLs, patterns) belongs in `config/`. |
 | J3 | Constants location | Module-level `UPPER_SNAKE = ...` outside `config/` in production code. Exempt path families: `config/*`, `/migrations/`, `/workflow/`, `_tab.py`, `/states.py`, `/modules.py`, test files. |
-| J4 | File-global use-count | A file-global constant referenced by fewer than two methods/functions/classes in the same file. |
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -26,7 +26,7 @@ Inline the artifact under this section using the section types defined in the ch
 
 **E2. Functions / methods defined but never called**
 - For every function, method, or callable defined or modified by the artifact, enumerate call sites: direct calls, callback registrations (`onerror=`, `key=`, signal handlers), decorator applications, `__main__` guards, framework-driven discovery (pytest collection, Django URL resolution, FastAPI route decorators, Click groups), and string-form references resolved at runtime (`getattr`, dispatch tables).
-- Leading-underscore names: a single internal call site is sufficient; explicitly verify nothing outside the file imports the underscore-prefixed name.
+- Leading-underscore names: a single internal call site is enough; explicitly verify nothing outside the file imports the underscore-prefixed name.
 - Public names: confirm at least one call site inside or outside the file, or confirm the function is part of a documented public API.
 - Framework-discovered callables (test functions, route handlers, CLI commands): state which collector picks them up and confirm the artifact's path matches that collector's pattern.
 
@@ -71,7 +71,7 @@ Inline the artifact under this section using the section types defined in the ch
 
 **E9. Constants-module exports with no importer**
 - For every module-level `UPPER_SNAKE` constant the artifact adds to a `*_constants.py` or `config/` module, grep the whole repo for the constant name and locate at least one importer (`from <module> import <NAME>`) or in-file reference.
-- The file-global use-count gate exempts a constants module because every name it exports carries zero in-file references by design, so a genuinely dead export slips past the write-time gate; this sub-bucket is the audit-time backstop for that exemption.
+- Every name a constants module exports carries zero in-file references by design and no write-time check reads such a module, so a dead export reaches the audit untouched; this sub-bucket is the audit-time backstop.
 - A sibling that a consumer module imports is live; a constant that no `from ... import` line and no in-file reference names anywhere in the repo is dead and must be removed (CODE_RULES 9.8).
 - Constants reached only by string-form lookup (`getattr(config, name)`, settings registries) are live; name the dynamic consumer when you mark such a constant referenced.
 - Adversarial probes for proof-of-absence: (a) does the artifact add any constant to a `*_constants.py` / `config/` module whose name returns zero hits outside its own definition line? (b) is any newly added constant shadowed by a same-named constant in a sibling module so the importer resolves the other one? (c) does any constant exist only as an `__all__` re-export with no downstream importer of that re-export?

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -50,11 +50,6 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 - Distinguish *imports* (`from config.X import FOO`) from *declarations* — imports are not J3-scope.
 - Adversarial probes: (a) does any module-level constant masquerade as an "import" via a re-export pattern? (b) is there a `_PRIVATE_UPPER` declaration that escapes the visual UPPER_SNAKE filter but is still module-level? (c) does any test file declare a constant that *would* be flagged if it were in production, indicating the constant probably belongs in `config/` even if test-exempt?
 
-**J4. File-global use-count**
-- For every file-global constant outside `config/`, count references in the same file. Single ref → move to `config/`. Zero refs → delete.
-- The rule applies to *constants*, not functions, classes, or imports.
-- Adversarial probes: (a) is any imported constant referenced only once in the importing file (suggesting the import itself is gratuitous)? (b) is any helper function defined in a production file but never called from inside the same file (separate dead-code concern, surfaced here for completeness)? (c) does any constant in `config/` get imported from zero call sites across the repo?
-
 **J5. Abbreviations**
 - Walk every parameter, local, and attribute name across production, test, and JavaScript changed lines. Flag: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.
 - This audit walks changed test-file and `.mjs` / `.js` lines for this rule, even though the write-time hook skips them.
@@ -101,7 +96,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 
 ## Cross-bucket questions to answer at the end
 
-Q1: Are there literals or names that span two sub-buckets (e.g., a magic value in J1 that also appears inside an f-string scrutinized by J2; an UPPER_SNAKE in J3 that also fails the use-count test in J4)? Cite the literal/name and both sub-bucket IDs.
+Q1: Are there literals or names that span two sub-buckets (e.g., a magic value in J1 that also appears inside an f-string scrutinized by J2; an UPPER_SNAKE in J3 that is also an abbreviation under J5)? Cite the literal/name and both sub-bucket IDs.
 
 Q2: What is the worst CODE_RULES drift introduced by this artifact? Cite `<file>:<line>`. (Common candidates: cross-language duplicates, stale help text mirroring a config constant, abbreviations in a public API surface, bare `Any` annotations, hardcoded user paths in installer scripts.)
 
@@ -149,13 +144,6 @@ ID prefix: `find`.
 - `Install-SweepEmptyDirs.ps1` line 245 — `$TaskName = "SweepEmptyDirs"` is a PowerShell variable; J3 enforces Python module-level UPPER_SNAKE outside `config/`. PowerShell out of scope for J3.
 - Adversarial probes: (a) does any module-level constant in `sweep_empty_dirs.py` masquerade as an "import"? (b) is there any `_PRIVATE_UPPER` declaration that escapes the visual UPPER_SNAKE filter? (c) does the test file accidentally declare a constant that *would* be flagged if it were in production?
 
-**J4. File-global use-count**
-- For every file-global constant outside `config/`, count references in the same file. Single ref → move to `config/`. Zero refs → delete.
-- `sweep_empty_dirs.py` — no file-global constants declared (`DEFAULT_AGE_SECONDS` and `DEFAULT_POLL_INTERVAL` are imports). Imports follow standard import-usage rules, not the file-global use-count rule.
-- `config/sweep_config.py:142-143` — `DEFAULT_AGE_SECONDS` and `DEFAULT_POLL_INTERVAL` live in `config/`, exempt by location.
-- Test file `_SCRIPTS_DIR` — test files exempt.
-- Adversarial probes: (a) is any imported constant in `sweep_empty_dirs.py` referenced only once (line 104 for `DEFAULT_AGE_SECONDS`, line 108 for `DEFAULT_POLL_INTERVAL`) — wait, `DEFAULT_AGE_SECONDS` is referenced TWICE on line 104 (`default=DEFAULT_AGE_SECONDS`) and line 105 (`f"...default: {DEFAULT_AGE_SECONDS} = 2 minutes"`); `DEFAULT_POLL_INTERVAL` is referenced TWICE on line 108 and line 109. Both meet the ≥2-references threshold (note: file-global use-count technically applies to declarations, not imports — listed here for completeness). (b) is any helper function in `sweep_empty_dirs.py` defined but never called from inside the file? `_log_walk_error` (line 73) is referenced once at line 84; `_build_parser` (line 101) is referenced once at line 114. The use-count rule applies to *constants*, not functions, so neither is flagged. (c) does any constant in `config/sweep_config.py` get imported from zero call sites?
-
 **J5. Abbreviations**
 - Walk every parameter, local, and attribute name in `sweep_empty_dirs.py`.
 - `_log_walk_error(os_error: OSError)` — `os_error` is full word, not `e` (exception loop var allowed but not required). Verified clean.
@@ -247,11 +235,9 @@ import time
 from config.sweep_config import DEFAULT_AGE_SECONDS
 from config.sweep_config import DEFAULT_POLL_INTERVAL
 
-
 def _log_walk_error(os_error: OSError) -> None:
     print(f"warning: cannot scan {os_error.filename} — {os_error.strerror}", file=sys.stderr)
 
-
 def sweep(root: str, min_age_seconds: int) -> list[str]:
     """Remove empty directories under *root* older than *min_age_seconds*."""
 
@@ -275,7 +261,6 @@ def sweep(root: str, min_age_seconds: int) -> list[str]:
 
     return removed
 
-
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Delete empty directories older than a given age.")
     parser.add_argument("root", help="Root directory to scan")
@@ -287,7 +272,6 @@ def _build_parser() -> argparse.ArgumentParser:
                         help=f"Poll interval in seconds when looping (default: {DEFAULT_POLL_INTERVAL})")
     return parser
 
-
 def main() -> None:
     parser = _build_parser()
     arguments = parser.parse_args()
@@ -309,7 +293,6 @@ def main() -> None:
         print("
 stopped.")
 
-
 if __name__ == "__main__":
     main()
 ```
@@ -342,7 +325,6 @@ if str(_SCRIPTS_DIR) not in sys.path:
 
 from sweep_empty_dirs import sweep  # noqa: E402
 
-
 def _set_creation_time_windows(path: str, timestamp: float) -> None:
     dt = datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
     date_str = dt.strftime("%Y-%m-%d %H:%M:%S")
@@ -352,7 +334,6 @@ def _set_creation_time_windows(path: str, timestamp: float) -> None:
         check=True, capture_output=True,
     )
 
-
 def test_deletes_empty_dir_older_than_threshold() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         empty_dir = os.path.join(tmp, "old_empty")
@@ -362,7 +343,6 @@ def test_deletes_empty_dir_older_than_threshold() -> None:
         assert empty_dir in removed
         assert not os.path.isdir(empty_dir)
 
-
 def test_skips_empty_dir_newer_than_threshold() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         fresh_dir = os.path.join(tmp, "fresh_empty")
@@ -371,7 +351,6 @@ def test_skips_empty_dir_newer_than_threshold() -> None:
         assert fresh_dir not in removed
         assert os.path.isdir(fresh_dir)
 
-
 def test_deletes_nested_empty_dirs() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         leaf = os.path.join(tmp, "parent", "child", "leaf")
@@ -384,13 +363,11 @@ def test_deletes_nested_empty_dirs() -> None:
         assert os.path.join(tmp, "parent", "child") in removed
         assert os.path.join(tmp, "parent") in removed
 
-
 def test_empty_root_does_not_crash() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         _set_creation_time_windows(tmp, time.time() - 300)
         sweep(tmp, min_age_seconds=120)
 
-
 def test_skips_nonempty_dir() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         nonempty_dir = os.path.join(tmp, "has_stuff")

package/package.json

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

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

@@ -37,6 +37,21 @@ 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

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

@@ -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.
 

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

@@ -36,7 +36,7 @@ A hook module is the sharpest case of the same rule: its docstring lead narrativ
 
 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,9 +58,9 @@ 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
 
@@ -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

@@ -64,10 +64,13 @@ 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 gate
-charges a change for the whole file it touches, so "pre-existing on main" is a
-blame note, not a pass. Fix the line in the next push or report the branch
-blocked. Read the gate's own report rather than a narrower substitute. A
+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.
 

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/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. CI runs that 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.
 
@@ -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/scripts/tests/test_codex_compat_materializer.py

@@ -826,7 +826,7 @@ def test_failure_blast_radius_projection_uses_the_canonical_excerpt() -> None:
     projected_instruction = materializer.render_codex_failure_blast_radius(canonical_rule)
 
     assert projected_instruction.startswith("Failure handling for this run")
-    assert "Three real attempts, then park." in projected_instruction
+    assert "Three attempts, then park." in projected_instruction
     assert "Report as: N of M complete" in projected_instruction
 
 
@@ -851,7 +851,7 @@ def test_build_plan_publishes_owned_agents_projection_and_tracks_drift(
     assert manifest_record["source"] == "rules/failure-blast-radius.md"
 
     rule_path.write_text(
-        rule_path.read_text(encoding="utf-8").replace("Three real attempts, then park.", "Three tested attempts, then park."),
+        rule_path.read_text(encoding="utf-8").replace("Three attempts, then park.", "Three tested attempts, then park."),
         encoding="utf-8",
     )
     drifted_plan, _ = build_plan(config, all_agents=[])
@@ -1021,7 +1021,7 @@ def _assert_projection_and_manifest(
 ) -> None:
     assert not retired_owned_path.exists()
     projected_instruction = (target / "AGENTS.md").read_text(encoding="utf-8")
-    assert "Three real attempts, then park." in projected_instruction
+    assert "Three attempts, then park." in projected_instruction
     manifest = json.loads((target / "hooks.json").read_text(encoding="utf-8"))
     assert manifest["hooks"]["PreToolUse"][0]["matcher"] == "apply_patch"
     assert manifest["hooks"]["PreToolUse"][1] == existing_hooks["hooks"]["PreToolUse"][1]