claude-dev-env 8.42.1 → 8.42.3

package/AGENTS.md

@@ -74,6 +74,8 @@ Banned word: real
 
 Never write real, really, or real-world. This ban has no exception. Emphasis and contrast are no exception. It covers chat, commits, pull requests, comments, documentation, headings, and variable names.
 
+`One real failure` is `one failure`. `The real cause` is `the cause`. `Really fast` is `fast`, or the measured number. `Real users` is `users`. `A real bug, not a flake` is `a bug`, followed by the evidence that rules out a flake.
+
 Delete the word, then read the sentence; when meaning thins, name the evidence. The failing check. The log line. The measured number. The file and the line.
 
-Swapping in actual, actually, genuine, or true is the same move, and each is banned with it.
+Swapping in actual, actually, genuine, or true is the same move, and each is banned with it. So is the invented contrast that invites the word back, such as `not a hypothetical problem but a problem`.

package/docs/rule-guides/anti-corollary-tests.md

@@ -0,0 +1,51 @@
+# Anti-corollary tests
+
+Full text behind [`rules/anti-corollary-tests.md`](../../rules/anti-corollary-tests.md).
+
+## The three questions
+
+### 1. Is this a corollary?
+
+When the code reduces each input to a canonical form and then compares the forms, every pairwise combination of input spellings follows once the reduction is proven canonical. Walking the full N-by-N matrix restates that fact. It adds cases and runtime, and it buries the few cases that carry information.
+
+### 2. Could this test pass if the mechanism were dead?
+
+The degenerate value may be an empty string, `None`, `False`, a blanket refusal, or an empty collection. A test expecting that value passes even when the mechanism stops.
+
+### 3. What single change to the code would make this test fail?
+
+The named mutation identifies the behavior a case observes. A case that survives it provides no evidence about that behavior.
+
+**The policy-surface case.** A test that asserts a policy's wording appears in its declaring file detects edits to that sentence. A suite of such tests counts repeated text. The declaring file can supply the policy while assertions inspect the surfaces it governs.
+
+## What a mechanism with a degenerate failure mode needs
+
+The audit record pairs a specific code mutation with the number of tests it fails. A reviewer or audit skill checks that record; no hook computes it.
+
+## Worked shape (sanitized)
+
+A write guard decides whether a write is about to hit a production database. It reduces each database URL to a canonical endpoint identity, then compares identities.
+
+Two independent mutations show the two halves of a useful suite:
+
+- Gut the reduction so it always returns the empty string. The guard fails **closed** and refuses everything. The *allow*-expecting cases die.
+- Abandon the reduction and compare raw hostnames. The guard fails **open** and allows a production write. The *refuse*-expecting cases die.
+
+The two breaks exercise opposite outcomes. A suite with both outcomes detects each break.
+
+## Why this requires judgment
+
+A structural hook cannot infer whether a case follows from canonicalization or passes against a dead implementation. Counting `parametrize` cases or assertions would also flag useful suites. The review and audit lanes judge changed tests using their intended behavior.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`code-standards.md`](../../rules/code-standards.md) | Points at CODE_RULES section 8 on a failing test before production code |
+| [`testing.md`](../../rules/testing.md) | Mocks and test infrastructure standards |
+| [`paired-test-coverage.md`](../../rules/paired-test-coverage.md) | Every public function in an established suite gets a behavioral test |
+| [`anti-corollary-tests.md`](../../rules/anti-corollary-tests.md) | Each test carries information |
+
+## Enforcement
+
+The AI review lane and audit skills inspect the test lines a pull request changes. No blocking hook evaluates the intent behind a corollary or dead-default case.

package/docs/rule-guides/archiving-agent-config.md

@@ -0,0 +1,34 @@
+# Archiving a rule, skill, agent, or command
+
+Full text behind [`rules/archiving-agent-config.md`](../../rules/archiving-agent-config.md), which loads in sessions as the short form.
+
+## Evidence of use
+
+Enforcement in this package often has a different name from the file that describes it. The script, lint identifier, and running check show whether a capability remains in service. A rule can have no mentions of its slug and still have a checker under another name.
+
+`CHANGELOG.md` records history. The `README.md` inventory table lists what ships. `bin/ever-shipped-skills.mjs` retains archived names on purpose. Mentions in these three files add no evidence of current use.
+
+This package installs into other repositories. A path absent from this tree can resolve in the host repository where the rule or skill runs. The path's intended location determines whether it is stale.
+
+## Archive layout
+
+`rules-archived/` sits beside `rules/`, and `.agents/skills-archived/` sits beside `.agents/skills/`. The installer copies a content directory whole, so an archive inside a live directory would ship. `CONTENT_DIRECTORIES` in `bin/install.mjs` omits archive siblings, and skill installation enumerates `.agents/skills` alone.
+
+The archive manifest records why each file left service, the `git mv` that restores it, and every companion edit a restore must undo. The sibling archive keeps the file available for a reverse move.
+
+## Exempt files
+
+The "Never archived" section of `rules-archived/ARCHIVE-MANIFEST.md` names files that stay in service. `rules/correction-lens.md` is listed there. Editing an exempt file to sharpen it remains ordinary work.
+
+## Skill names and tests
+
+The prune computes retired skill names as every name in `bin/ever-shipped-skills.mjs` minus the names installed now. The installer uses that set to move stale copies out of a host's agents home. `scripts/active_capability_references.py` uses the same registry to report leftover mentions of an archived name.
+
+The node test command globs `.agents/skills/**/*.test.mjs`. Tests under a renamed archived skill directory leave that run without failing, so the test count shows whether coverage still runs.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`retired-hook-prose.md`](../../rules/retired-hook-prose.md) | Hook prose names checks that still run |
+| [`doc-inventory-integrity.md`](../../rules/doc-inventory-integrity.md) | Inventory tables reflect what ships |

package/docs/rule-guides/build-needs-a-user.md

@@ -0,0 +1,27 @@
+# Build needs a user
+
+Full text behind [`rules/build-needs-a-user.md`](../../rules/build-needs-a-user.md), which loads in sessions as the short form.
+
+## First use and size
+
+A caller can be a hook entry, workflow step, skill, command, or module in the same change. First use can be a date or a named event. Prior manual use and frequency show whether the job recurs. An unanswered point leaves the owner a one-line statement of the intended build and the missing answer while the rest of the task continues.
+
+A correction starts as a row in a rule file. [`correction-lens.md`](../../rules/correction-lens.md) describes when repetition warrants a hook or lint. The first implementation needs only the behavior its first caller uses.
+
+## Where the check runs
+
+The staged policy lint's `uncalled-new-file` rule reads newly added code files under `scripts/`, `hooks/`, `bin/`, `ci/`, or `tools/`. It reports a file whose name appears only in its own tests, `CHANGELOG.md`, `README.md`, and `bin/ever-shipped-skills.mjs`. CI runs the lint against the merge base.
+
+The code checks caller references. The other decision points, including first use and prior manual work, depend on the author.
+
+## Why the caller matters
+
+The Codex compatibility watcher shipped 502 lines and 599 lines of tests in July. PR 1488 deleted it in September. Its own test was the only file that named it.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`prefer-existing-tools.md`](../../rules/prefer-existing-tools.md) | Search before building |
+| [`correction-lens.md`](../../rules/correction-lens.md) | A repeated correction moves up a layer |
+| [`archiving-agent-config.md`](../../rules/archiving-agent-config.md) | How an unused capability leaves service |

package/docs/rule-guides/falsify-before-green.md

@@ -0,0 +1,43 @@
+# Falsify before green
+
+Full text behind [`rules/falsify-before-green.md`](../../rules/falsify-before-green.md).
+
+## The four shapes this stops
+
+### 1. A probe whose trigger condition never fires
+
+The probe reports zero while its counter stays at the start value. The trip input exposes whether it observes an event.
+
+**Break to apply:** feed it one input that must trip it. A probe still at zero on that input measures nothing.
+
+### 2. A sweep that reads a subset of the files it claims to cover
+
+The sweep may compare against the wrong base or walk a slice of the tree while claiming the full set.
+
+**Break to apply:** plant one violation in a file the sweep's coverage claim names. A sweep that misses the plant walks a smaller file set than the one it reports.
+
+### 3. A mutation that survives
+
+The test may miss the mutated code because a mock stands in for the call, a guard returns early, or the test drives a neighboring branch.
+
+**Break to apply:** hold the mutation in place and run the test. A green test names a line nothing covers.
+
+### 4. An assertion that counts an artifact the harness seeded
+
+The harness writes the row, file, or event the assertion counts. Stubbing the production writer exposes that source.
+
+**Break to apply:** stub the production writer to a no-op. A green assertion counts the seed.
+
+## What a shown-red record holds
+
+| Part | What it names |
+|---|---|
+| The break | The mutation, stub, or trip input, named by file and line or by the exact input text |
+| The red | The failing output the check printed under that break |
+| The control | The case that passes beside the red, run on the same command |
+
+The red and control distinguish a selective check from one that always fails or always passes.
+
+## Enforcement
+
+A reviewer reads the shown-red record beside each new check a pull request adds. A regex cannot tell which code a green check reached at run time.

package/docs/rule-guides/flag-non-breaking-findings.md

@@ -0,0 +1,59 @@
+# Flag non-breaking findings
+
+Full text behind [`rules/flag-non-breaking-findings.md`](../../rules/flag-non-breaking-findings.md), which loads in sessions as the short form.
+
+## Why severity matters
+
+A breaking finding means the change is wrong: a bug, a secret in the tree, a broken test, a syntax error, or an instruction file that fails to load. A smell means the change reads poorly: a length limit, a naming convention, a prose term, a comment rule, or a structural preference.
+
+A smell that blocks a commit stops delivery for something the reader could fix in the next pass. The writer then reaches for a bypass flag, which disables the breaking checks beside it. Recording the smell keeps the blocking checks useful and gives later work a record to clear.
+
+## The ledger
+
+Recorded findings land in `.claude/followups/smells.jsonl` at the repository root, one JSON object per line. `hooks/followup_ledger.py` writes and reads it. Ledger writes are fail-safe, so a ledger failure leaves the gate's decision unchanged.
+
+| Field | What it carries |
+|---|---|
+| `rule_id` | The rule that raised the finding |
+| `check_id` | The single check behind it, which a severity table keys on |
+| `file_path` | The repository-relative path the finding names |
+| `message` | The text a reader acts on |
+| `severity` | The class the gate put it in |
+| `origin_commit` | The revision checked out when it was recorded |
+
+The origin commit groups a follow-up pull request by the change that raised the findings. A smell seen again under a later revision keeps the revision that first raised it, so one smell stays one record. The ledger is per-checkout state and stays out of the repository.
+
+## The check identifier
+
+Most lint rules run one check, so their rule identifier already names it. The `code-rules` and `validators` rules bundle many checks behind one identifier. `scripts/policy_lint/check_catalog.py` resolves those to a `<rule>/<check>` identifier, which `cde lint --format json` emits as `check_id` on every diagnostic. Consumers partition findings by that identifier.
+
+A message with no catalog entry resolves to `<rule>/unclassified`, which a partition treats as blocking. When check wording changes, the catalog synchronization tests expose a missing mapping.
+
+## Reading and clearing the ledger
+
+| Command | What it does |
+|---|---|
+| `cde followup list` | Names every recorded follow-up |
+| `cde followup ingest REPORT` | Records the diagnostics a policy-lint JSON report carries |
+| `cde followup brief` | Writes the task an agent fixes them from |
+| `cde followup clear` | Empties the ledger |
+| `cde followup count` | Reports the backlog against the threshold |
+
+`count` exits non-zero once the backlog passes `FOLLOWUP_BACKLOG_THRESHOLD` in `scripts/dev_env_scripts_constants/followup_constants.py`, so a scheduled job escalates. The number is the repository's setting.
+
+The `/fix-followups` command reads the brief, fixes each rule group, opens a pull request, and clears the ledger.
+
+## Worked example
+
+`scripts/validate_instruction_pairs.py` raises five findings. A missing governing `AGENTS.md`, mismatched import text, and an instruction path that is not a regular file each stop instructions loading. A non-canonical filename and a Git mode other than 100644 leave instructions loading, so the gate records them and passes.
+
+`SEVERITY_BY_RULE_ID` in that module declares the split. `scripts/repository_policy.py` uses `SEVERITY_BY_CHECK_ID` in `repository_checks/config/constants.py`. Its `package-inventory` check is a smell because the production file still imports and runs when an inventory row is missing. The check prints an `advisory:` prefix and records the finding. A `CLAUDE.md` naming a missing file, an env-var row naming a file that never reads the variable, a test outside the testpaths allowlist, and a tracked secret each block.
+
+`scripts/cde_lint.py` uses `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py`. `test-pairing` and the two paired-test coverage checks are smells there. The lint prints warnings, records them, and exits zero when no error remains.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [CI Owns the Gate](../../.agents/skills/pr-lifecycle/SKILL.md#ci-owns-the-gate) | The full check suite runs once, on CI |
+| [Git workflow](../../.agents/skills/pr-lifecycle/SKILL.md#git-workflow) | A red required check blocks the branch |

package/docs/rule-guides/long-horizon-autonomy.md

@@ -0,0 +1,40 @@
+# Long-horizon autonomy
+
+Full text behind [`rules/long-horizon-autonomy.md`](../../rules/long-horizon-autonomy.md).
+
+Source: [Anthropic prompting guidance for Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5).
+
+## Act on what you have
+
+Facts already settled in the conversation remain settled. A recommendation gives the user one course to evaluate. A list of discarded options adds reading without changing that course. This governs user-facing messages and leaves private reasoning free to examine alternatives.
+
+Unclear intent calls for research and a recommendation before action. Clear intent and available evidence allow the run to proceed.
+
+## Pause and resume
+
+A pause asks for one missing input in the channel the user reads. It names what resumes when the answer arrives. `AskUserQuestion` is the Claude tool for that request. A status line, checklist, working document, or side thread leaves the request unseen by the user.
+
+Independent work continues while an answer is outstanding. Authority granted earlier in the task remains in force. A later preference about tone or report length changes the message. The task's earlier authorization stays in force.
+
+Before ending a turn, inspect its last paragraph. These endings leave work owed to the user:
+
+- A summary that names the next step without starting it.
+- An offer to continue unless the user objects.
+- A list of decisions that does not block remaining work.
+- A pause because the turn ran long or reached a milestone.
+
+A harness reads a turn ending in text as a report. When checklist items remain and the report names no blocker, it sends a short continuation prompt. The harness stops after two or three continuations on one task. [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#unattended-agentic-runs) describes this loop.
+
+In an autonomous pipeline, the user cannot answer during the run. Reversible actions already authorized by the task continue, and follow-up offers wait until completion.
+
+## Delegate and keep working
+
+A large independent track can run in a subagent while the lead handles other work. A few reads, a handful of edits, or a simple check fit in the lead's turn. Reusing a long-lived subagent across related tasks preserves its context. The lead steps in when that agent drifts or lacks context.
+
+For a task that spawned workers, the completion condition and checklist live in the [workers-done-before-complete guide](workers-done-before-complete.md).
+
+## Ground progress and the closing report
+
+Progress claims come from tool results in the current session. Failed tests carry their output. Skipped steps are named. The [ASD-STE100 language rule](../../rules/asd-ste100-language.md) governs the wording. The first progress update uses one sentence. Later updates cover important discoveries or a change in direction.
+
+Terse notes between tool calls can support the run. The final message briefs a reader who saw none of them. It opens with the outcome, then explains any input needed using plain names for each file, commit, or flag. A remaining context or token count does not end an unfinished run. Content the user must see word for word goes through the channel the harness provides for it.

package/docs/rule-guides/no-cross-skill-duplicate-helpers.md

@@ -0,0 +1,24 @@
+# Cross-skill duplicate helpers
+
+Full text behind [`rules/no-cross-skill-duplicate-helpers.md`](../../rules/no-cross-skill-duplicate-helpers.md).
+
+## The two duplication cases differ
+
+CODE_RULES "Reuse before create" / DRY gives one helper one home within a skill. Two `.py` modules in the same skill's `scripts/` directory with the same top-level function body fail the `code_rules_duplicate_body` check. The staged policy lint runs it through `code_rules_enforcer.py`.
+
+Each skill folder installs on its own. A shared module that lives in one skill would break the other skill after removal or reinstall. A small launch helper, such as one that reads the browser registry entry and starts `chrome.exe`, can live in each skill.
+
+## Dependency choices
+
+A large helper may hold business logic or drift in ways that change behavior. The user chooses between two arrangements:
+
+- Copy the helper into each skill and accept the drift risk.
+- Declare a shared dependency in both skills. A published package in both `requirements` files or a `_shared` module installed into each skill can survive independent installation.
+
+## What the advisory tells you
+
+The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr when a changed top-level function matches a helper in another skill's `scripts/` directory. It leaves the lint passing. The message names the source skill and function for review. The advisory covers copies across skill folders; the blocking check covers copies within one skill.
+
+## Why the checks have different scopes
+
+The cross-skill advisory preserves the small-copy option that keeps skills independently installable. Its source-skill name gives the writer enough context to judge the copy. The blocking check handles duplication inside one skill.

package/docs/rule-guides/prefer-existing-tools.md

@@ -0,0 +1,22 @@
+# Prefer existing tools
+
+Full text behind [`rules/prefer-existing-tools.md`](../../rules/prefer-existing-tools.md), which loads in sessions as the short form.
+
+## What a candidate must cover
+
+Internal code includes the repository and its shared packages. An established external option has a security process, a field reputation, broad use measured by stars, downloads, or dependents, and maintenance shown by a release or commit within the last year. An open critical advisory rules it out.
+
+Custom rules belong in the chosen tool's configuration format. A wrapper adds code that this package must maintain.
+
+The choice report identifies the tool by name and link, gives its license, and cites one adoption count. A custom build's report records the candidates and the missing capability that ruled out each one.
+
+## Why this rule exists
+
+Code written here needs local maintenance. A widely used tool draws fixes and new patterns from its maintainers and users.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`explore-thoroughly.md`](../../rules/explore-thoroughly.md) | Read existing code before proposing a change |
+| [`verify-before-asking.md`](../../rules/verify-before-asking.md) | Check a question with a tool before asking it |

package/docs/rule-guides/retired-hook-prose.md

@@ -0,0 +1,27 @@
+# Rules prose names only hooks that run
+
+Full text behind [`rules/retired-hook-prose.md`](../../rules/retired-hook-prose.md), which loads in sessions as the short form.
+
+## How a hook reaches a tool call
+
+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. The installer writes an inert stand-in at a retired hook path when stale `settings.json` still names it. A missing registered path makes the interpreter exit 2, which a PreToolUse harness reads as a block.
+
+A retired hook's logic can move into a `*_parts/` package imported by a live module. The old hook name then stops while its check still fires. A present-tense claim about the old module sends the reader to a gate they will never encounter.
+
+The staged policy lint registers `retired-hook-prose` in `scripts/policy_lint/registry.py`. `accepts_instruction_markdown` covers Markdown under `.agents/`, `commands/`, `docs/`, `output-styles/`, `rules/`, and `system-prompts/`. The detector reads backticked hook module names, checks registration and dispatcher rosters, and reports a present-tense action attributed to a module with no live registration. The lint does not find a forced detour that names only an agent, step, or token.
+
+A module name counts as a hook when it ends in a hook family suffix such as `_blocker`, `_enforcer`, `_gate`, `_tracker`, or `_dispatcher`, and either sits under `hooks/` or appears in `RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS` in `bin/install.mjs`. A support module without a hook suffix stays outside that check.
+
+Past-tense history makes no live claim. A sentence naming the staged policy lint, `cde_lint`, or a repository check identifies where the work runs now.
+
+## Why gate detours matter
+
+A gate and the standing orders written to satisfy it form one unit. A required agent spawn, token, or extra step can remain after the gate ends because those orders often omit the module name the lint searches for. The stale order costs every later session an unnecessary action.
+
+A withdrawn threshold can also remain in an audit rubric, an agent instruction table, or a review prompt. Removing only the mechanical check leaves a judgment lane enforcing the same threshold. The archive entry records each lane so a restore can recover the complete decision.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`archiving-agent-config.md`](../../rules/archiving-agent-config.md) | Archive a retired rule or capability with a restore record |

package/docs/rule-guides/testing.md

@@ -0,0 +1,21 @@
+# Testing standards
+
+Full text behind [`rules/testing.md`](../../rules/testing.md).
+
+> **Reference:** [`TEST_QUALITY.md`](../TEST_QUALITY.md) for test review.
+
+## Complete mocks for testability
+
+If a component renders field X, a mock with a valid X value lets the test reach rendering behavior. An omitted field can make a failing render ambiguous.
+
+## Tests exercise production behavior
+
+A stand-in can satisfy an assertion while the production path stays untested. The behavior under review is the result of the production call.
+
+## Test order
+
+The TDD skill (`pstack:tdd`) carries the red, green, refactor procedure. No hook or lint checks the order. Review reads the reproducing test on the diff.
+
+## Fix proof job
+
+The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on pull requests whose title starts with `fix`. Node proof tests end in `.test.mjs`, `.test.js`, or `.test.cjs`, and the job runs them with `node --test`. A docs-only or CI-only fix passes. A fix proven by a PowerShell test also needs Python or Node proof.

package/docs/rule-guides/workers-done-before-complete.md

@@ -0,0 +1,30 @@
+# Workers done before complete
+
+Full text behind [`rules/workers-done-before-complete.md`](../../rules/workers-done-before-complete.md).
+
+## The completion gate
+
+The gate applies to subagents, workflow agents, and background shells spawned by a task. The run state can be `state.json`, `pr-converge-state.json`, a task list, or another record the task keeps. A finished worker with an unmerged result leaves the task open.
+
+The gate controls task status. Work that can proceed while a worker runs continues. A worker that dies or hangs becomes a finding to record and report. A wakeup returns the run to the outstanding workers.
+
+## Checklist before marking complete
+
+| Check | Action |
+|---|---|
+| Are any spawned workers still running? | List them. If any run, stay `in_progress` and schedule a wakeup. |
+| Did every finished worker return a result? | Read each result. Report a dead or hung worker as a finding. |
+| Is each result merged into run state? | Write it to the run record before closing. |
+| Does the task's goal hold? | Check the merged state and the repository or diff behind worker claims. |
+
+The file list, count, description, and finding in each worker report need repository and diff evidence before they enter run state or a user report.
+
+## Examples
+
+An audit task has two workers still running. The lead lists them, keeps the task `in_progress`, and schedules a wakeup to collect their results.
+
+A worker crashes while the others finish. The lead records the crash as a finding, reports it, and keeps the task open until the missing work is covered.
+
+## Relationship to other rules
+
+The [long-horizon-autonomy guide](long-horizon-autonomy.md) covers acting on available evidence and finishing owed work before ending a turn. This gate defines the completion condition for tasks with workers.

package/docs/rule-guides/workflow-substitution-slots.md

@@ -0,0 +1,13 @@
+# Workflow substitution slots
+
+Full text behind [`rules/workflow-substitution-slots.md`](../../rules/workflow-substitution-slots.md).
+
+## Values in agent-prompt templates
+
+An agent fills angle-bracket slots such as `<plate.svg>`, `<object.svg>`, and `<glow_hex>` for each call. The same convention applies to an iteration index in a path or output key. `cand_<i>` names a changing path segment. `cand_i` names one literal directory, so repeated iterations can overwrite the same output and collapse an N-iteration gate into one run.
+
+For a looped path or key, use `cand_<i>`. Step text can instead say `replace <i> with the iteration index 0, 1, 2`. Each call then gets its own value.
+
+## Enforcement
+
+The staged policy lint runs `workflow-substitution` on `.workflow.js` files. It reports a bare `<word>_<i|j|k>` token used as a path segment in looped content. CI runs the lint against the merge base. A write-time hook does not report this case, so the token remains on disk until lint runs.

package/package.json

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

package/rules/anti-corollary-tests.md

@@ -8,64 +8,12 @@ paths:
   - "**/tests/**"
 ---
 
-# Anti-Corollary Tests
+# Anti-corollary tests
 
-**When this applies:** Any Write or Edit that adds or changes tests.
+**When:** Add or change a test.
 
-## Rule
+Before keeping a test, name one code change it would catch; replace a case that catches none. Skip spelling cross products after proving canonicalization once; compare a few discriminating cases. Exercise the production path with a non-default expected result so a dead implementation cannot pass. Test policy compliance on governed surfaces; in an audit, name a mutation and record how many tests it fails.
 
-A large green suite can prove almost nothing. Before you keep a case, answer three questions. If any answer fails, cut the case or replace it with one that carries information.
+**Enforcement:** none, the agent applies it.
 
-## The three questions
-
-### 1. Is this a corollary?
-
-When the code reduces each input to a canonical form and then compares the forms, every pairwise combination of input spellings follows once the reduction is proven canonical. Walking the full N×N matrix restates that fact. It adds cases and runtime, and it buries the few cases that carry information.
-
-**Do this:** test the reduction once. Test the comparison with a few discriminating cases. Do not walk the cross product of spellings.
-
-### 2. Could this test pass if the mechanism were dead?
-
-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 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.
-2. **A stated mutation (audit lane):** name one specific change to the code and record how many tests it kills. A mutation that kills zero tests means the suite proves nothing. A reviewer or an audit skill checks this; a hook does not compute it.
-3. **A few discriminating cases** in place of a large matrix.
-
-## Worked shape (sanitized)
-
-A write guard decides whether a write is about to hit a production database. It reduces each database URL to a canonical endpoint identity, then compares identities.
-
-Two independent mutations show the two halves of a useful suite:
-
-- Gut the reduction so it always returns the empty string: the guard fails **closed** and refuses everything. Only the *allow*-expecting cases die.
-- Abandon the reduction and compare raw hostnames: the guard fails **open** and allows a production write. Only the *refuse*-expecting cases die.
-
-Opposite breaks kill opposite halves. A suite with only one half cannot see one of those breaks. Build both halves; skip the spelling matrix once the reduction is covered.
-
-## What this is not
-
-A structural hook is the wrong tool here. "Is this a corollary?" and "would this pass against a dead implementation?" need the intent of the code under test. A hook that pattern-matches `parametrize` breadth or counts assertions fires on correct suites and trains people to ignore it. A false-positive gate on a judgment call is worse than no gate. This rule stays judgment-only, with the stated-mutation check in the audit lane — the same pattern as other judgment rules in this package that have no Write/Edit blocker.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| `code-standards.md` | Points at CODE_RULES §8: write a failing test before production code |
-| `testing.md` | Mocks and test infrastructure standards |
-| `paired-test-coverage.md` | Every public function in an established suite gets a behavioral test |
-| `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |
-
-## Enforcement
-
-The AI review lane and audit skills carry this rule: an agent applies it to the test lines a PR changes. No blocking hook backs it, because corollary and dead-default judgments need meaning a regex cannot read.
+**Full text:** [`docs/rule-guides/anti-corollary-tests.md`](../docs/rule-guides/anti-corollary-tests.md). Read it when choosing cases or auditing mutation evidence.

package/rules/archiving-agent-config.md

@@ -2,87 +2,19 @@
 paths:
   - "**/rules/**"
   - "**/rules-archived/**"
-  - "**/skills/**"
+  - "**/.agents/skills/**"
   - "**/skills-archived/**"
   - "**/agents/**"
   - "**/commands/**"
   - "**/ever-shipped-skills.mjs"
 ---
 
-# Archiving a Rule, Skill, Agent, or Command
+# 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.
+**When:** Before archiving configuration.
 
-## Prove disuse before you remove
+Trace checks and callers; `CHANGELOG.md`, `README.md`, shipped-skills registry, and host paths prove neither use nor disuse. Read `rules-archived/ARCHIVE-MANIFEST.md`; skip and report exemptions, then continue. Move unused files with `git mv` into sibling archives; record the reason, restore command, and companion edits. Retain skill names in `bin/ever-shipped-skills.mjs` and check tests lost when a skill directory moves.
 
-A prune is only as good as the usage evidence behind it, and three habits give
-confident wrong answers here.
+**Enforcement:** none, the agent applies it.
 
-**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.
-
-## Exempt files
-
-The "Never archived" section of `rules-archived/ARCHIVE-MANIFEST.md` names the
-files this procedure leaves alone. Read that section before a prune moves
-anything. A pass that reaches an exempt file stops there and reports which file
-it was, so the prune's other moves still land.
-
-`rules/correction-lens.md` is on that list today. Editing an exempt file to
-sharpen it is ordinary work.
-
-## Make the archive stick
-
-Two 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. The reference checker in
-`scripts/active_capability_references.py` derives its retired set the same way,
-so the registry entry is also what makes a leftover mention of the archived
-name report. No second list needs the name.
-
-**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 |
+**Full text:** [`docs/rule-guides/archiving-agent-config.md`](../docs/rule-guides/archiving-agent-config.md). Read it before moving or restoring.

package/rules/build-needs-a-user.md

@@ -5,60 +5,16 @@ paths:
   - "**/bin/**"
   - "**/ci/**"
   - "**/tools/**"
-  - "**/skills/**"
+  - "**/skills/*/scripts/**"
   - "**/commands/**"
 ---
 
-# Build Needs a User
+# Build needs a user
 
-**When this applies:** Before you build a new tool, script, hook, gate, skill,
-command, or workflow step. That includes a hook or check built to answer a
-correction.
+**When:** Before building a tool, script, hook, gate, skill, command, or workflow step.
 
-## Rule
+Name its caller in this change, first-use date or event, and last manual use with frequency. Build only with all three answers; otherwise tell the owner in one line what the build is for and which answer is missing, then continue unaffected work. Search for an existing tool, size the build to first use, and turn a correction into a hook or lint only after it recurs.
 
-Answer three questions before the first line of the build:
+**Enforcement:** `uncalled-new-file` checks new code under `scripts/`, `hooks/`, `bin/`, `ci/`, and `tools/` for a caller.
 
-1. **Who calls it?** Name the hook entry, workflow step, skill, command, or
-   module that will run it in this same change.
-2. **When does it first run?** Name the date or the event of first use.
-3. **When was this job last done by hand?** Name the last time, and how often it
-   comes up.
-
-Build when all three have a concrete answer. When the only answer is "it might
-help" or "we could use it later", stop and send the owner one line: what the
-build is for and which question has no answer. Keep the rest of the task moving
-while that line waits.
-
-Search first, per [`prefer-existing-tools.md`](prefer-existing-tools.md). A
-tool that already exists answers the need, and the build is the glue.
-
-## Size the first build to the first use
-
-Build the smallest version that serves the first caller. A correction starts
-as a row in a rule file. It becomes a hook or a lint only when the same
-correction arrives a second time, per
-[`correction-lens.md`](correction-lens.md).
-
-## Where it is enforced
-
-The staged policy lint's `uncalled-new-file` rule reads each code file a change
-adds under `scripts/`, `hooks/`, `bin/`, `ci/`, or `tools/`. It reports the file when its name
-appears only in its own tests, `CHANGELOG.md`, `README.md`, and
-`bin/ever-shipped-skills.mjs`. CI runs that lint against the merge base, so a
-file with no caller turns the pull request red.
-
-## Why
-
-The history of this package holds files that lived weeks and ran never. The
-Codex compatibility watcher shipped 502 lines and 599 lines of tests in July,
-and PR 1488 deleted it in September. Its own test was the only file that named
-it.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`prefer-existing-tools.md`](prefer-existing-tools.md) | Search before you build |
-| [`correction-lens.md`](correction-lens.md) | A repeated correction moves up a layer |
-| [`archiving-agent-config.md`](archiving-agent-config.md) | How an unused capability leaves service |
+**Full text:** [`docs/rule-guides/build-needs-a-user.md`](../docs/rule-guides/build-needs-a-user.md). Read it when sizing a new check.

package/rules/falsify-before-green.md

@@ -9,52 +9,12 @@ paths:
   - "**/scripts/**"
 ---
 
-# Falsify Before Green
+# Falsify before green
 
-**When this applies:** Any new test, probe, concurrency harness, sweep, mutation check, or measurement script, before its green counts as evidence.
+**When:** A new test, probe, sweep, mutation check, or measurement script first reports green.
 
-## Rule
+Apply a named break that the same check must catch, and run a passing control beside it on the same command. Record the break, its failing output, and the control before counting the restored green as evidence. If the check stays green under its break, fix its reach; a probe needs a trip input, a sweep needs a planted violation in its claimed file set, and a writer assertion needs a disabled production writer.
 
-A check's green counts as evidence only after that same check ran red on a deliberate break, with a paired control that passes beside it. The break is named: a mutation applied to the code, a stubbed-out target, or a trip input built to fire the check.
+**Enforcement:** none, the agent applies it.
 
-A green with no shown red is an unmeasured result, not a pass. Apply the break, watch the check fail, then trust the green. A check that stays green under its own break reads nothing about the code, and its number carries no weight.
-
-## The four shapes this stops
-
-### 1. A probe whose trigger condition never fires
-
-The probe reports zero because it measured zero events, not because the code is clean. Its counter sits at its start value for the whole run.
-
-**Break to apply:** feed it one input that must trip it. A probe still at zero on that input measures nothing.
-
-### 2. A sweep that reads a subset of the files it claims to cover
-
-The sweep compares against the wrong base, walks a slice of the tree, and reports its finding count over the full set.
-
-**Break to apply:** plant one violation in a file the sweep's coverage claim names. A sweep that misses the plant walks a smaller file set than the one it reports.
-
-### 3. A mutation that survives
-
-The test meant to kill the mutation never reaches the mutated code — a mock stands in for the call, a guard returns early, or the test drives a neighboring branch.
-
-**Break to apply:** hold the mutation in place and run the test. A green test names a line nothing covers.
-
-### 4. An assertion that counts an artifact the harness seeded
-
-The harness writes the row, file, or event the assertion counts, so the assertion tracks the harness rather than the code under test.
-
-**Break to apply:** stub the production writer to a no-op. A green assertion counts the seed.
-
-## What a shown-red record holds
-
-| Part | What it names |
-|---|---|
-| The break | The mutation, stub, or trip input applied, named by file and line or by the exact input text |
-| The red | The failing output the check printed under that break |
-| The control | The case that passes beside the red, run on the same command |
-
-All three land together. A record carrying the red alone shows a check that fails on everything; a record carrying the control alone shows a check that passes on everything.
-
-## Enforcement
-
-This rule binds as prose discipline: a reviewer reads the shown-red record beside each new check a PR adds. No hook backs it, because a green that measured the code and a green that measured nothing look the same to a regex — the difference sits in what the check reached at run time.
+**Full text:** [`docs/rule-guides/falsify-before-green.md`](../docs/rule-guides/falsify-before-green.md). Read it when designing a break or reviewing a red record.

package/rules/flag-non-breaking-findings.md

@@ -9,126 +9,12 @@ paths:
   - "**/.github/workflows/**"
 ---
 
-# Flag Non-Breaking Findings
+# Flag non-breaking findings
 
-**When this applies:** Writing or changing a local gate — a git hook, a
-pre-commit entry, a Claude tool-use hook — and deciding what one of its checks
-does when it finds something.
+**When:** When writing a local gate or changing a check's severity.
 
-## Rule
+Give every check ID a breaking or smell severity row; style and structure findings are smells. Fail the gate and stop for a bug, secret, broken test, syntax error, or instruction file that cannot load. Record a smell in `.claude/followups/smells.jsonl`, proceed, and fix it in a later pull request; ledger failure leaves the gate decision unchanged. Treat an unclassified check as breaking.
 
-A gate blocks on a breaking finding and records a non-breaking one.
+**Enforcement:** none, the agent applies it.
 
-A **breaking** finding means the change is wrong: a bug, a secret in the
-tree, a broken test, a syntax error, an instruction file that fails to
-load. The gate fails and the work stops there.
-
-A **smell** finding means the change reads poorly: a length limit, a naming
-convention, a prose term, a comment rule, a structural preference. The gate
-records it and lets the commit, the push, or the tool call proceed. A later
-pull request carries the fix.
-
-Every check a gate runs declares which of the two it is. A check that cannot
-say which one it raises is a breaking check until someone decides otherwise.
-
-## Why
-
-A smell that blocks a commit stops delivery for something the reader would
-have fixed in the next pass anyway. The writer then reaches for the bypass
-flag, and the bypass turns off the breaking checks beside it. The gate that
-blocks on everything ends up enforcing nothing.
-
-Recording the smell keeps both halves working. The breaking checks stay
-sharp because nobody routes around them, and the smells still get fixed
-because the ledger holds them until a pull request does.
-
-## The ledger
-
-A recorded finding lands in `.claude/followups/smells.jsonl` at the
-repository root, one JSON object per line. `hooks/followup_ledger.py` writes
-and reads it. Every write there is fail-safe, so a ledger failure leaves the
-gate's decision unchanged.
-
-| Field | What it carries |
-|---|---|
-| `rule_id` | The rule that raised the finding |
-| `check_id` | The single check behind it, which a severity table keys on |
-| `file_path` | The repository-relative path the finding names |
-| `message` | The text a reader acts on |
-| `severity` | The class the gate put it in |
-| `origin_commit` | The revision checked out when it was recorded |
-
-The origin commit groups a follow-up pull request by the change that raised
-the findings. A smell seen again under a later revision keeps the revision
-that first raised it, so one smell stays one record.
-
-The ledger is per-checkout state and stays out of the repository.
-
-## The check identifier
-
-Most lint rules run one check, so their rule identifier already names it. The
-`code-rules` and `validators` rules bundle many checks behind one identifier.
-`scripts/policy_lint/check_catalog.py` resolves those to a `<rule>/<check>`
-identifier, which `cde lint --format json` emits as `check_id` on every
-diagnostic. A consumer partitions findings by that identifier rather than by
-message text.
-
-A message no catalog entry names resolves to `<rule>/unclassified`, which a
-partition treats as blocking. A check whose wording moves reports louder
-rather than going quiet, and the catalog's synchronization tests fail on the
-same change.
-
-## Reading and clearing it
-
-| Command | What it does |
-|---|---|
-| `cde followup list` | Names every recorded follow-up |
-| `cde followup ingest REPORT` | Records the diagnostics a policy-lint JSON report carries |
-| `cde followup brief` | Writes the task an agent fixes them from |
-| `cde followup clear` | Empties the ledger |
-| `cde followup count` | Reports the backlog against the threshold |
-
-`count` exits non-zero once the backlog passes
-`FOLLOWUP_BACKLOG_THRESHOLD` in
-`scripts/dev_env_scripts_constants/followup_constants.py`, so a scheduled job
-escalates rather than opening one more quiet pull request. The number is the
-repository's setting, and raising or lowering it is one edit there.
-
-The `/fix-followups` command drives the whole pass: it reads the brief, fixes
-each rule group, opens a pull request, and clears the ledger.
-
-## Worked example
-
-`scripts/validate_instruction_pairs.py` raises five findings and splits them
-on this line. A missing governing `AGENTS.md`, an import text that differs,
-and an instruction path that is not a regular file each stop the instructions
-loading, so the gate fails. A non-canonical filename and a Git mode other than
-100644 leave the instructions loading, so the gate records them and passes.
-
-`SEVERITY_BY_RULE_ID` in that module is the whole declaration. Add a check,
-add its row.
-
-`scripts/repository_policy.py` splits the committed-tree checks the same way.
-`SEVERITY_BY_CHECK_ID` in `repository_checks/config/constants.py` carries one
-row per check id, and a check id with no row reads as breaking. The
-`package-inventory` check is the one smell there. A production file whose
-package inventory omits its row still imports and still runs, so the check
-prints its finding with an `advisory:` prefix, records it in the ledger, and
-leaves the tree passing. Every other committed-tree check blocks: a `CLAUDE.md`
-naming a file that does not exist, an env-var row naming a file that never
-reads the variable, a test outside the testpaths allowlist, and a tracked
-secret.
-
-`scripts/cde_lint.py` splits the policy-lint findings the same way.
-`SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py`
-carries one row per smell, and a check id with no row reads as breaking. Three
-checks are smells there: `test-pairing` and the two paired-test coverage
-checks. The lint prints each as a warning, records it in the ledger, and exits
-zero when no error remains.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [CI Owns the Gate](../.agents/skills/pr-lifecycle/SKILL.md#ci-owns-the-gate) | The full check suite runs once, on CI |
-| [Git workflow](../.agents/skills/pr-lifecycle/SKILL.md#git-workflow) | A red required check blocks the branch |
+**Full text:** [`docs/rule-guides/flag-non-breaking-findings.md`](../docs/rule-guides/flag-non-breaking-findings.md). Read it when adding a check.

package/rules/long-horizon-autonomy.md

@@ -4,55 +4,12 @@ paths:
   - "**/skills/orchestrator-refresh/**"
 ---
 
-# Long-Horizon Autonomy
+# Long-horizon autonomy
 
-Source: [Anthropic - Prompting Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)
+**When:** Run a long or unattended task.
 
-**When this applies:** Long, multi-step, or unwatched runs — autonomous pipelines, background jobs, convergence loops, and any task that spans many tool calls or a long stretch where the user is away. The behaviors below carry a run to completion rather than letting it stall, drift, or stop early.
+Act on settled facts and authority, and recommend after researching unclear intent. When protected or irreversible actions, scope changes, or user-only input block the task, ask for one answer in the user-facing channel, name what resumes, and keep other work moving. Finish owed work without ending a turn on a promise, milestone, or context limit. Delegate independent tracks while working, ground claims in tool output, name skipped checks, make the first update one sentence, reserve later updates for discoveries, and close with the outcome and input.
 
-## Act on what you have
+**Enforcement:** none, the agent applies it.
 
-When you have enough to act, act. Do not re-derive facts already settled in the conversation, re-open a decision the user already made, or narrate options you will not pursue in user-facing text. When you weigh a choice, give a recommendation, not a full survey. This shapes user-facing messages, not your private reasoning.
-
-This is the autonomous-run partner to the ambiguous case: research and recommend first when intent is unclear; this rule covers the clear case, where the evidence is already in hand.
-
-## Do not end a turn on a promise
-
-Pause for the user only when the work 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.
-
-Four turn endings leave owed work unstarted. Each one is a stop to remove:
-
-- A summary of the work so far that closes by naming the next step, with no tool call to start it.
-- An offer to continue unless the user objects.
-- A list of decisions for the user when none of them blocks the remaining work.
-- A pause chosen because the turn ran long or a milestone finished.
-
-A status note or a recommendation on an open decision rides in the same message as the next tool call. The stops that stay are the two where nothing can move: the next step needs the user, or the blocker is a control that is protected from you on purpose. Confirmation before a risky or destructive action still applies.
-
-A harness or routine that drives an unattended run reads a turn that ends in text as a report. When open checklist items remain and the turn names no blocker, it sends one short message naming those items. It stops after two or three such continuations on one task, so a stuck run ends where a reader can review it. [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#unattended-agentic-runs) is the source for this list and this loop.
-
-In an autonomous pipeline the user cannot answer mid-task. For reversible actions that follow from the original request, act without asking; save any follow-up offers for after the task is done.
-
-Authority the task already granted stays granted. A later preference about tone, brevity, or reply format changes how you report, never what you are allowed to do. Re-asking for permission the task already gave hands the work back to the user, who then does it by hand.
-
-## Delegate and keep working
-
-Delegate a large, independent track to a subagent, and keep working while it runs in the background. Do work you can finish in a few tool calls yourself: a few reads, a handful of edits, or a simple check. Reuse a long-lived subagent across related subtasks so its context carries forward and saves repeated reads. Step in when a subagent drifts off track or is missing context.
-
-## Ground every progress claim
-
-Before you report progress, check each claim against a tool result from this session. State only what the evidence backs; name anything unverified as unverified. If tests fail, say so with the output; if a step was skipped, say that.
-
-Visible progress follows the [ASD-STE100 language policy](asd-ste100-language.md) and this rule's run-completion contract: the **first progress update is one sentence**; later updates mark only **important discoveries or a direction change**.
-
-## Re-ground the final message
-
-Terse shorthand between tool calls is fine — that is you thinking. The final message is for a reader who saw none of it. After a long or unwatched run, write it as a fresh briefing: the **outcome in one sentence first**, then the one or two things you need from the reader, each explained as if new. Drop the working vocabulary, arrow chains, and stacked-hyphen compounds; give each file, commit, or flag its own plain clause. When short and clear pull apart, choose clear.
-
-## Keep going on context
-
-A remaining-context or token count is not a reason to stop. Do not pause, summarize, or float a fresh session on account of context limits; keep working. When the user must see content word-for-word (a partial deliverable, a direct answer to a mid-run question), surface it through the channel the harness gives for that, not by ending the turn.
+**Full text:** [`docs/rule-guides/long-horizon-autonomy.md`](../docs/rule-guides/long-horizon-autonomy.md). Read it when preparing the run.

package/rules/no-cross-skill-duplicate-helpers.md

@@ -2,28 +2,12 @@
 paths: "**/skills/*/scripts/**/*.py"
 ---
 
-# Cross-Skill Duplicate Helpers
+# Cross-skill duplicate helpers
 
-**When this applies:** Any Write or Edit to a `.py` file under a skill's `scripts/` directory (`**/skills/<skill-name>/scripts/**/*.py`) that copies a top-level helper from another skill's `scripts/` directory.
+**When:** Write a top-level Python helper in a skill `scripts/` directory.
 
-## The two duplication cases differ
+Within one skill, extract a shared module and import it at both call sites. Across skill folders, copy a small self-contained helper when independent installation needs it, then confirm the advisory names the source. For a large or behavior-bearing body, ask the user to choose an intentional copy with drift risk or a dependency that survives independent install.
 
-CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is enforced **within one skill**. Two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` check, which the staged policy lint runs through `code_rules_enforcer.py`. The fix is a shared module both import.
+**Enforcement:** `code_rules_duplicate_body.py` blocks sibling-module copies and emits cross-skill advisories through `code_rules_enforcer.py`; the agent judges copy size.
 
-Across **two skill folders** the same copy is a different call. Each skill folder installs on its own, so a shared module would couple two skills the install model keeps separate: deleting or reinstalling one skill would break a helper the other depends on. A small launch helper copied into each skill (for example a Chrome-open helper that reads the registry and runs `chrome.exe`) is a defensible skill-isolation tradeoff, not a regression.
-
-## Decision
-
-Before you copy a top-level helper from one skill's `scripts/` directory into another:
-
-- **Same skill, two modules.** Extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` check reports the copy.
-- **Two skill folders, a small self-contained helper.** Copy it, and the skill-isolation tradeoff stands. An advisory `[CODE_RULES advisory]` line names the source skill when the lint runs, so the copy is a deliberate choice on record, not an oversight.
-- **Two skill folders, a large or behavior-bearing body** — when the copied body is large, holds business logic, or would drift in a way that changes behavior, raise the choice through `AskUserQuestion`: copy and accept drift, or stand up a shared dependency both skills declare (for example a published package both `requirements` files name, or a `_shared` module the install step writes into each skill). A shared dependency that survives independent install is the only shared-home path that does not break the install model.
-
-## What the advisory tells you
-
-The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never fails the lint) when a top-level function in a changed file has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders. Within one skill the reporting check already covers the copy.
-
-## Why this is a rule, not a wider check
-
-Extending the duplicate-body check to span skill folders would report the exact skill-isolation copy that keeps skills independently installable, a false positive on a sanctioned pattern. The boundary between "same skill, report" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment, and the `[CODE_RULES advisory]` line surfaces the signal. Neither one fails the defensible copy.
+**Full text:** [`docs/rule-guides/no-cross-skill-duplicate-helpers.md`](../docs/rule-guides/no-cross-skill-duplicate-helpers.md). Read it when judging copy size or dependency ownership.

package/rules/prefer-existing-tools.md

@@ -5,44 +5,18 @@ paths:
   - "**/bin/**"
   - "**/ci/**"
   - "**/tools/**"
-  - "**/skills/**"
+  - "**/skills/*/scripts/**"
   - "**/package.json"
   - "**/pyproject.toml"
   - "**/requirements*.txt"
 ---
 
-# Prefer Existing Tools
+# Prefer existing tools
 
-**When this applies:** Before you build a tool, check, scanner, script, or library of your own.
+**When:** Before building a tool, check, script, or library.
 
-## Rule
+Search local and shared code, then open-source options. Stop at first fit; build if neither fits. Choose an external option with an active security process, no open critical advisory, field reputation, broad use, and a release or commit within a year; add missing rules in its configuration without a wrapper. Report its name, link, license, and one use count; for custom code, name rejected candidates and reasons.
 
-Search in this order, and stop at the first fit:
+**Enforcement:** none, the agent applies it.
 
-1. **Internal code.** Search the repository and its shared packages for a tool that already does the job. Reuse or extend it.
-2. **An established open-source option.** Search for a plugin, package, or tool that already does the job.
-3. **Your own code.** Build it only when steps 1 and 2 find nothing that fits.
-
-Use an open-source option only when it meets all four conditions:
-
-- It is secure: it has an active security process and no open critical advisory.
-- It is well known in its field.
-- It is widely used: many stars, downloads, or dependents.
-- It is maintained: it had a release or commit in the last year.
-
-Add only what the option lacks. Put custom rules in its own configuration format. Do not wrap it in a new layer of your own code.
-
-## Report the choice
-
-Tell the user which tool you chose before the work is marked ready. Give its name, link, license, and one number that shows how widely it is used. When you build your own code, name what you searched and why each candidate did not fit.
-
-## Why
-
-Code of your own is code you maintain alone. A trusted tool carries fixes and new patterns from its community, and its users find its defects first.
-
-## Sibling rules
-
-| Rule | Role |
-|---|---|
-| [`explore-thoroughly.md`](explore-thoroughly.md) | Read what exists before you propose a change |
-| [`verify-before-asking.md`](verify-before-asking.md) | Answer a question with a tool before you ask it |
+**Full text:** [`docs/rule-guides/prefer-existing-tools.md`](../docs/rule-guides/prefer-existing-tools.md). Read it when comparing candidates.

package/rules/retired-hook-prose.md

@@ -3,22 +3,12 @@ paths:
   - "**/rules/*.md"
 ---
 
-# Rules Prose Names Only Hooks That Run
+# 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. 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.
+**When:** When describing a hook or retiring a gate.
 
-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.
+Verify the module and its hook registration or dispatcher roster before claiming it runs; describe a retired hook in past tense or name the check that carries its work now. When retiring a gate, remove the forced agent calls, tokens, extra steps, thresholds, audit rubrics, and review prompts it required across every instruction lane. Add a retired hook path to the installer roster when deleting its module.
 
-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.
+**Enforcement:** `retired-hook-prose` in `scripts/policy_lint/registry.py` checks instruction Markdown, including `rules/` and `docs/`; the detour sweep is manual.
 
-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.
+**Full text:** [`docs/rule-guides/retired-hook-prose.md`](../docs/rule-guides/retired-hook-prose.md). Read it when tracing a hook's current path or removing its gate.

package/rules/testing.md

@@ -8,25 +8,12 @@ paths:
   - "**/tests/**"
 ---
 
-# Testing Standards
+# Testing standards
 
-> **Reference:** TEST_QUALITY.md - Load when writing or reviewing tests.
+**When:** Write or review behavior tests.
 
-## Complete Mocks for Testability
+Read [`TEST_QUALITY.md`](../docs/TEST_QUALITY.md) and give mocks every field the component reads, with valid values. Assert results from production data and code paths. Use red, green, refactor for fixes and new behavior; add prototype tests before a pull request goes ready, and ship a reproducing test with each fix. A production fix titled `fix` needs a changed Python or Node test that fails on base and passes on head.
 
-**Mocks must include all fields the component uses.**
+**Enforcement:** `useless_test_checks.py` and `code_rules_test_assertions.py` catch weak assertions; `Fix test proof` checks fix tests.
 
-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 Production Behavior
-
-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
-
-Red, green, refactor is the default loop for a bug fix and for new behavior. The TDD skill (`pstack:tdd`) carries the procedure, and no hook or lint checks the order. A prototype may run ahead of its tests and adds them before the pull request goes ready. A bug fix ships with a test that reproduces the bug. Review reads the tests on the diff.
-
-## A Fix Carries Its Proof Test
-
-The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on every pull request whose title starts with `fix`. A fix that changes production code must change at least one Python or Node test that fails on the base and passes on the head. Node tests are files ending in `.test.mjs`, `.test.js`, or `.test.cjs`, and the job runs them with `node --test`. A fix that changes only docs or CI config passes. A fix proven by a PowerShell test needs a Python or Node test beside it.
+**Full text:** [`docs/rule-guides/testing.md`](../docs/rule-guides/testing.md). Read it for mock fields, test order, and fix proof details.

package/rules/workers-done-before-complete.md

@@ -4,12 +4,12 @@ paths:
   - "**/skills/orchestrator-refresh/**"
 ---
 
-# Workers Done Before Complete
+# Workers done before complete
 
-Before marking a task `completed` that spawned workers — subagents, workflow agents, or background shells — confirm both: every worker has finished, and each worker's result is merged into run state (`state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps). A worker still running, or one whose output never landed in run state, keeps the task `in_progress`: list the live workers, report any dead or hung one as a finding rather than dropping it in silence, and schedule a wakeup so the run picks the workers back up before the task closes.
+**When:** Mark a task `completed` after spawning subagents, workflow agents, or background shells.
 
-This rule gates a task's status, not your own work. It never says wait before acting: keep working while a worker runs, and hold only the `completed` mark until the worker's result has landed.
+List every worker and confirm that each has finished and its result is merged into run state. Verify worker file lists, counts, descriptions, and findings against the repository and diff before repeating them. While a worker runs or output is missing, keep the task `in_progress`, report dead or hung workers, schedule a wakeup, and keep other work moving. Check the task goal against merged state before closing.
 
-Verify every sub-agent file list, count, description, and finding against the repository and the diff before you merge it into run state or repeat it to the user.
+**Enforcement:** none, the agent applies it.
 
-Checklist, examples, and run-state detail: `@~/.claude/docs/worker-completion-gate.md`.
+**Full text:** [`docs/rule-guides/workers-done-before-complete.md`](../docs/rule-guides/workers-done-before-complete.md). Read it before closing a task that spawned workers.

package/rules/workflow-substitution-slots.md

@@ -3,10 +3,12 @@ paths:
   - "**/*.workflow.js"
 ---
 
-# Workflow Substitution Slot Rule
+# Workflow substitution slots
 
-In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.
+**When:** Write a `.workflow.js` agent-prompt template with values filled per call or iteration.
 
-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.
+Mark each changing value with angle brackets, including loop indices in paths or output keys such as `cand_<i>`.
 
-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.
+**Enforcement:** `workflow-substitution` in the staged policy lint.
+
+**Full text:** [`docs/rule-guides/workflow-substitution-slots.md`](../docs/rule-guides/workflow-substitution-slots.md). Read it when a loop builds a path or output key.

package/docs/worker-completion-gate.md

@@ -1,32 +0,0 @@
-# Worker Completion Gate
-
-Full detail behind the always-on `rules/workers-done-before-complete.md` kernel. It applies before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
-
-## The gate
-
-A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
-
-List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
-
-## Checklist before marking complete
-
-| Check | Action |
-|---|---|
-| Are any spawned workers still running? | List them; when yes, stay `in_progress` and schedule a wakeup. |
-| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
-| Is each result merged into run state? | Write it to `state.json` or the task list before closing. |
-| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
-
-Mark `completed` only when every row passes.
-
-## Examples
-
-**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
-**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
-
-**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
-**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
-
-## Relationship to other rules
-
-- `long-horizon-autonomy` covers acting on what you have and not ending a turn on a promise. This gate names the specific completion condition: workers finished and their results merged.