claude-dev-env 8.36.3 → 8.37.0

package/rules/failure-blast-radius.md

@@ -11,120 +11,10 @@ paths:
 
 **When this applies:** Batch code that processes assets, rows, accounts, messages, or files where one member can fail while the others are fine.
 
-## Rule
+Every raise reached through per-member work names what stops. A type ending in `RunFatal` stops the whole run. A type ending in `ItemBlocked` stops one member, and the batch carries on. Define `RunFatal` outside the `ItemBlocked` branch, and put the `try`/`except` inside the loop body with the `RunFatal` re-raise first.
 
-A check that raises decides two things at once: that a condition requires action, and what stops because of it. Name the second one.
+Four failures end a run: the source bytes changed, a provenance or digest mismatch, authentication is required, or a runtime crash such as `TypeError`. Work every other failure. Repair in place, take three attempts (three theories of the cause), then park the member and move on. The batch always reaches a deliverable. Three members parked with the same signature share one cause. The closing report gives every issue one line with how it ended, plus a recommended durable fix.
 
-An exception type ending in `RunFatal` says the whole run stops. An exception type ending in `ItemBlocked` says this one member stops and the batch carries on. Every raise reached through per-member work uses one or the other.
+**Enforcement:** `code_rules_blast_radius.py`, which the staged policy lint runs through `code_rules_enforcer.py` under its `code-rules` rule. CI runs it against the merge base.
 
-Define `RunFatal` outside the `ItemBlocked` inheritance branch. The per-member boundary routes `ItemBlocked` to parking, while a `RunFatal` escalation passes straight through to the run-level branch.
-
-## What ends a run
-
-Four failures end a run, and they share one property: continuing compromises delivery integrity.
-
-Three of them are declared, and carry a `RunFatal` type:
-
-- The source bytes changed under the run.
-- A provenance or digest comparison failed.
-- Authentication is required.
-
-The fourth is a runtime crash, such as `TypeError` or `AttributeError`. Its runtime type reaches run-level handling because the per-member boundary recognizes the contract's named types.
-
-All remaining failures are member failures. A size mismatch, an optional input error, a path resolution error, or a manifest-field error each stops one member while the batch continues with its other members.
-
-## The boundary
-
-Put the `try`/`except` inside the loop body, around the per-member work:
-
-```python
-for each_member in all_members:
-    try:
-        remaster(each_member)
-    except AssetRunFatal:
-        raise
-    except AssetItemBlocked as failure:
-        park(each_member, failure)
-```
-
-The re-raise comes first, sending an escalation directly through the boundary.
-
-**The boundary recognizes declared types.** A runtime crash inside member work — a `TypeError`, an `AttributeError` — ends the run because its type identifies a code defect. `except Exception` triggers the rule (`CODE_RULES.md` §31).
-
-## Repair, park, and the deliverable
-
-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 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
-
-When three or more members park with the same failure signature — same exception type, same `file:line` — one shared defect affects all three members. Route repair to the shared cause.
-
-The run report groups parked members by that signature and names every group of three or more as a suspected shared cause. The raise site provides a reliable grouping key and removes message-text normalization.
-
-## 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 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 and names the fix the run recommends for each one. The report is a statement, not a gate: the current run completes its deliverable and ends. A later run builds whichever fixes the owner selects, and the recommendation stands as the default for any the owner does not rule on.
-
-## Enforcement
-
-`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so CI is where it reports. CI runs the same lint against the merge base.
-
-The check requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
-
-Findings compare each changed file against its baseline. A raise already present in the baseline stays accepted, so the check reports only newly written raises.
-
-## Excerpt for repository-instruction sessions
-
-Codex reads its repository `AGENTS.md`; this excerpt supplies the standalone failure-handling contract.
-
-```
-Failure handling for this run — from rules/failure-blast-radius.md.
-
-Keep solving problems. You own the fix. Each blast radius sets the repair
-scope, and the deliverable remains the run priority.
-
-Repair in place and preserve every completed asset in the current run.
-
-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;
-the third attempt sets the stopping point. After the third theory fails, park
-the asset with its reason and continue. Parked assets return after the batch.
-
-The batch always reaches a deliverable. Finish every asset you can, produce
-the packaged artifact, then work the parked list.
-
-When three or more assets fail the same way, one shared defect affects all
-three assets. Route repair to the shared cause.
-
-Four things end a run outright: the source bytes changed, a provenance or
-digest mismatch, authentication is required, or the code crashed with a
-runtime failure that requires run-level handling. Work every other failure. The
-named-type boundary defines the accepted exception handling; broad `except`
-handling triggers the rule.
-
-When you add a check that raises, name what it stops. End the type in
-RunFatal when the whole run stops, or ItemBlocked when a single asset
-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 defect in the list, because the closing report becomes
-its durable record.
-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
-durable fix.
-```
+**Full text:** [`docs/rule-guides/failure-blast-radius.md`](../docs/rule-guides/failure-blast-radius.md), with the boundary example and the Codex excerpt.

package/rules/orphan-css-class.md

@@ -5,24 +5,10 @@ paths:
 
 # Orphan CSS Class in Generated Markup
 
-**When this applies:** Any Write or Edit to a production `.py` file that builds HTML by emitting `class="..."` attributes inside string literals and pairs them with a `<style>` block — in the same file or in a companion module beside it.
+**When this applies:** Production `.py` that emits `class="..."` attributes in string literals beside a `<style>` block.
 
-## Rule
+Every class the markup references has a `.<class>` selector in a nearby `<style>` block. Add the selector in the change that adds the class, and drop the class in the change that drops its selector.
 
-Every class name a markup string references has a matching `.<class>` selector in the `<style>` block. A class that appears in the markup but carries no selector anywhere is a dead attribute (or a missing rule): the markup names a style that the stylesheet never defines, so a reader who trusts the class to be styled is misled, and the attribute adds noise without effect.
+**Enforcement:** `check_orphan_css_classes` in `code_rules_orphan_css_class.py`, which the staged policy lint runs through `code_rules_enforcer.py`.
 
-When you add a `class="..."` attribute, add its `.<class>` selector to the `<style>` block in the same change. When you drop a selector, drop the class attribute it styled.
-
-## What the check covers
-
-The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. CI runs that lint against the merge base. It:
-
-1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
-2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.
-3. Flags each referenced class with no matching selector in that whole set.
-
-The check stays quiet for a file that emits no `class="..."` markup, and for a file whose markup has no `<style>` source nearby (its stylesheet lives outside the scan, so the check cannot judge it). Test files are exempt, since a fixture may carry intentional orphan markup.
-
-## Why this check is mechanical
-
-A class attribute with no matching selector reads as styled but renders unstyled. Native elements such as `<details>` stay functional without CSS, so the gap survives review as a cosmetic defect rather than a crash. That is the class of issue a manual pass slips past, and it lands later as a deferred code-standard finding. Running the lint on every staged change keeps the markup and the stylesheet in step.
+**Full text:** [`docs/rule-guides/orphan-css-class.md`](../docs/rule-guides/orphan-css-class.md).

package/rules/paired-test-coverage.md

@@ -5,38 +5,10 @@ paths:
 
 # Public-Function Paired-Test Coverage
 
-**When this applies:** Either side of a paired module/test pair, so the check fires whichever file the write touches:
+**When this applies:** Writing a production Python module whose stem-matched test file (`test_<stem>.py` or `<stem>_test.py`) already exercises it, or writing that test file.
 
-- A Write or Edit to a production Python module that already has a dedicated stem-matched test file — `test_<stem>.py` beside the module or under an ancestor `tests/` directory — whose paired suite already exercises the module, either by covering at least one of its public functions or by referencing one of its private helpers by name.
-- A Write or Edit to a stem-matched test file (`test_<stem>.py` or `<stem>_test.py`) whose paired production module exists on disk and whose post-edit suite already exercises at least one of that module's public functions.
+Every public function such a module defines gets a behavioral test in its paired suite. When you add a public function there, add a test that calls it and asserts on its return value or side effect in the same change. `main` and underscore-prefixed functions need none.
 
-## Rule
+**Enforcement:** `check_public_function_missing_paired_test` and `check_test_file_omits_module_public_function` in `code_rules_paired_test.py`, which the staged policy lint runs through `code_rules_enforcer.py`. Both record smells per [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md).
 
-Every public function a production module defines is exercised by a test in the module's paired test suite. The suite proves the module is unit-tested function by function, so a public entry point the suite omits is a forgotten test: a reader who trusts the suite to cover the module's public surface misses that gap.
-
-When you add a public function to a module whose test suite already exercises that module — covering a sibling public function, or testing one of its private helpers — add a behavioral test that calls the new function and asserts on its return value or side effect — in the same change that adds the function. A suite that exercises only a private helper (such as a color-conversion helper) while leaving the module's public renderers untested is the exact gap this rule closes. This is the function-level half of the project rule "Every new production code path gets a paired behavioral test ... call the path and assert on what it does."
-
-## What the check covers
-
-Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
-
-Both checks record smells, per [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md). `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py` declares `code-rules/paired-test-missing-function` and `code-rules/paired-test-omitted-function` as smells. The lint prints each finding as a warning, records it in `.claude/followups/smells.jsonl`, and exits zero when every finding is a warning. A later pull request adds the missing tests.
-
-`check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
-
-1. The target is production code — not a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py`.
-2. A stem-matched test file exists for the module — `test_<stem>.py` or `<stem>_test.py` beside the module, or `test_<stem>.py` under an ancestor `tests/` directory.
-3. That suite already exercises the module — referencing at least one public function the module defines, or referencing one of its private (underscore-prefixed) helper functions by name — the signature of a maintained per-module suite rather than a placeholder or unrelated test file.
-4. The public function is referenced by no test file in the directory that holds the stem-matched test.
-
-`check_test_file_omits_module_public_function` runs on a stem-matched test-file write or edit and closes the reverse order, in which the production module is written before its test file exists. It resolves the production module the written `test_<stem>.py` or `<stem>_test.py` file pairs with — beside the test file, or in the parent of the `tests/` directory that holds it — reads that module from disk, and flags every public function the post-edit suite references nowhere, subject to the same established-suite precondition (the suite already covers at least one of the module's public functions). A production module that is itself exempt — a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py` — is skipped.
-
-A public function counts as covered when its name appears — imported, called, or named — in any `test_*.py` or `*_test.py` file in the suite directory, so a function exercised by a differently-named sibling test still counts. `main` and underscore-prefixed functions are never required to carry a test.
-
-## Relationship to the file-level TDD order
-
-No hook or lint checks the order in which a test and its module are written. Red-green-refactor is the default loop, and the TDD skill (`pstack:tdd`) carries it; a prototype may run ahead of its tests and adds them before the pull request goes ready. This check judges coverage one function at a time for a module that already carries a stem-matched test file, and reports any public function that file leaves uncovered.
-
-## Why this check is mechanical
-
-A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change records each gap in the follow-up ledger, where `cde followup list` names it until a pull request closes it.
+**Full text:** [`docs/rule-guides/paired-test-coverage.md`](../docs/rule-guides/paired-test-coverage.md).

package/rules/plain-illustrative-docstrings.md

@@ -5,87 +5,10 @@ paths:
 
 # Plain, Illustrative Docstrings
 
-**When this applies:** Any Write or Edit to a public function, method, class, or module docstring whose narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — says what the code is for or how it behaves. The standard governs the prose a reader meets first, not the structured `Args:` / `Returns:` entries below it.
+**When this applies:** Writing or editing the narrative prose of a public function, method, class, or module docstring, the text before its first `Args:` section.
 
-## Rule
+Write the narrative so a general developer follows it on the first read. Paint a concrete scene in short sentences, one idea each. Name what the reader sees and why it matters. Say what a thing is. Once the explanation grows past two or three lines, use one summary line, then a `::` literal block or a doctest that shows the input and the outcome, then two or three short lines, then the Google `Args:` and `Returns:` sections.
 
-A docstring's narrative reads plainly enough that a general developer follows it on the first read. Two things make that true:
+**Enforcement:** `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` in `code_rules_docstrings.py`, which the staged policy lint runs through `code_rules_enforcer.py`. Category O sub-bucket O9 of the audit rubric carries the judgment.
 
-- **Illustrative.** The prose paints a concrete scene — the reader pictures the moment the code matters, the input it sees, the outcome it produces. A reader who finishes the narrative can say what breaks without it.
-- **Brief.** The narrative makes its point in few words. Short sentences, each carrying one idea.
-
-Two shapes break the standard. Hold the prose clear of both:
-
-- **No machinery nouns stacked into a wall.** A sentence that chains abstract machinery terms (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`) names parts without painting a scene. Name what the reader sees and why it matters.
-- **No defining by negation.** Prose that explains a thing by what it is not (`the non-promoter-specific machinery`) leaves the reader without a picture. Say what the thing is.
-
-## Shape: a summary line, then a diagram
-
-The clearest way to be illustrative is to show a worked example, not describe one. A docstring that lands well reads in four parts:
-
-1. **One summary line** that says what the code does.
-2. **A diagram block** that carries the explanation by sight — a reStructuredText literal block (a line ending in `::`, then an indented example) or a doctest (`>>>`). Give the concrete input, mark the outcome, and add `ok:` / `flag:` contrast lines where a pass-and-fail pair makes the point. Keep the diagram clear of a bare number or an ALL-CAPS `NAME = value` line, which read as a magic value or a stray constant to a line-based lint pass.
-3. **A couple of short narrative lines** after the block — two or three at most.
-4. **The Google `Args:` / `Returns:` sections.**
-
-Keep the wording neutral in the diagram and the prose: two names "contradict" or "clash", two names "agree". Skip words that pass judgment.
-
-Canonical example:
-
-```
-Flag a boolean assignment whose target and callee assert opposite polarity.
-
-::
-
-    is_inside_allowed = _point_hits_any_forbidden(...)
-             ^^^^^^^                    ^^^^^^^^^
-             allowed         vs.        forbidden      ⚠ the two names clash
-    ok:   is_inside_allowed = _point_inside_allowed_region(...)
-    flag: is_inside_allowed = _point_hits_any_forbidden(...)
-
-The target token and the callee token contradict each other, so the reader
-cannot tell which name states the truth. Rename the callee to a neutral form
-the two names agree on at every call site.
-```
-
-The live version of this docstring sits on `check_polarity_name_contradiction` in `~/.claude/hooks/blocking/code_rules_naming_collection.py`.
-
-A short narrative with no diagram is fine when a couple of plain sentences carry the whole picture. The diagram earns its place once the explanation grows past what two or three lines hold — the moment a wall of prose starts to form.
-
-## What to check before you write the docstring
-
-Read the narrative back as a stranger would:
-
-- Does one sentence run long while joining clauses with an em-dash or a semicolon? That is the wall mark — break it into short sentences.
-- Does the prose name a concrete moment, input, and outcome, or only abstract parts?
-- Does any sentence define the thing by what it is not? Rewrite it to say what the thing is.
-
-## Worked example
-
-A dense wall — one long sentence, machinery nouns, a term defined by negation:
-
-```
-Owns the SIGINT install/restore/installability check, the atexit terminal-record
-registration, and the interrupted-run finalizer — the non-promoter-specific
-machinery that brackets a run so the JSONL artifact always carries a terminal
-record and an in-flight theme record on interrupt.
-```
-
-The same contract, plain and illustrative:
-
-```
-Make sure a run's log always records how it ended.
-
-So when you reopen the report, the last line tells you the truth: the run
-finished cleanly, or you hit Ctrl-C while theme 42 was processing, or it died
-on an unexpected error. Without this, a killed run looks identical to a clean
-one — and you're debugging blind.
-```
-
-## Enforcement
-
-Two surfaces carry this standard:
-
-- **Lint (the run-on backstop).** `check_docstring_runon_sentence` in `code_rules_docstrings.py` flags the one mechanical mark of a wall, a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. The staged policy lint reaches it through `code_rules_enforcer.py`, and no write-time hook runs it. A mechanical check cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
-- **Lint (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well, and that stays with the audit lane.
-- **Audit (the judgment lane).** Category O sub-bucket O9 in `~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the lint cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.
+**Full text:** [`docs/rule-guides/plain-illustrative-docstrings.md`](../docs/rule-guides/plain-illustrative-docstrings.md), with the canonical example.

package/rules/windows-filesystem-safe.md

@@ -8,10 +8,8 @@ paths:
 
 # Windows Filesystem Safety
 
-Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` files (e.g. `.git/objects/pack/`) raise `PermissionError`, the flag swallows it, and the tree silently stays on disk. Use an `onexc` (Python >= 3.12) / `onerror` handler that runs `os.chmod(target_path, stat.S_IWRITE)` then retries the removal function the failure interrupted.
+Call `shutil.rmtree` with an `onexc` (Python 3.12 and later) or `onerror` handler that runs `os.chmod(target_path, stat.S_IWRITE)` and retries. `ignore_errors=True` leaves read-only trees on disk. In Node, call `mkdirSync(targetPath, { recursive: true })` on a path that may exist. Import the shared `force_rmtree` handler trio from its one shared Windows-filesystem module.
 
-In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing paths — `ReadOnly` directories break the non-recursive form. When the call must be non-recursive, strip the attribute first (`(Get-Item $path -Force).Attributes = "Directory"` / `os.chmod(path, stat.S_IWRITE)`).
+**Enforcement:** the staged policy lint's `rmtree-safety` rule, which returns the full `force_rmtree` code. CI runs it against the merge base.
 
-The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. CI runs that lint against the merge base.
-
-Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first, so a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES, "Reuse before create"). The same `rmtree-safety` lint rule reports a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` check, which a copy between two distant packages slips past.
+**Full text:** [`docs/rule-guides/windows-filesystem-safe.md`](../docs/rule-guides/windows-filesystem-safe.md).

package/scripts/codex_compat_materializer.py

@@ -27,7 +27,10 @@ publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
 frontmatter_unsupported_fields = ("tools", "model", "color", "disable-model-invocation")
 instruction_alias_filenames = frozenset({"AGENTS.md", "CLAUDE.md"})
-codex_instruction_rule_relative_paths = ("rules/failure-blast-radius.md", "rules/correction-lens.md")
+codex_instruction_rule_relative_paths = (
+    "docs/rule-guides/failure-blast-radius.md",
+    "docs/rule-guides/correction-lens-excerpt.md",
+)
 codex_instruction_source_separator = ", "
 codex_instruction_target_path = "AGENTS.md"
 codex_instruction_section_heading = "## Excerpt for repository-instruction sessions"

package/scripts/tests/test_codex_compat_materializer.py

@@ -174,8 +174,8 @@ def test_public_legacy_call_forms_validate_collection_entries(tmp_path: Path) ->
 
 
 def test_render_codex_instruction_excerpt_requires_the_excerpt_heading() -> None:
-    with pytest.raises(MaterializerError, match="rules/correction-lens.md requires a Codex excerpt"):
-        materializer.render_codex_instruction_excerpt("# No excerpt\n", "rules/correction-lens.md")
+    with pytest.raises(MaterializerError, match="docs/rule-guides/correction-lens-excerpt.md requires a Codex excerpt"):
+        materializer.render_codex_instruction_excerpt("# No excerpt\n", "docs/rule-guides/correction-lens-excerpt.md")
 
 
 def test_validation_rejects_reparse_point_from_portable_attribute_seam(
@@ -820,11 +820,11 @@ def test_frontmatter_rejects_non_string_name() -> None:
 
 
 def test_failure_blast_radius_projection_uses_the_canonical_excerpt() -> None:
-    canonical_rule_path = Path(__file__).parents[2] / "rules" / "failure-blast-radius.md"
+    canonical_rule_path = Path(__file__).parents[2] / "docs" / "rule-guides" / "failure-blast-radius.md"
     canonical_rule = canonical_rule_path.read_text(encoding="utf-8")
 
     projected_instruction = materializer.render_codex_instruction_excerpt(
-        canonical_rule, "rules/failure-blast-radius.md"
+        canonical_rule, "docs/rule-guides/failure-blast-radius.md"
     )
 
     assert projected_instruction.startswith("Failure handling for this run")
@@ -833,12 +833,12 @@ def test_failure_blast_radius_projection_uses_the_canonical_excerpt() -> None:
 
 
 def test_codex_instruction_projection_carries_every_listed_rule(tmp_path: Path) -> None:
-    rules_root = Path(__file__).parents[2] / "rules"
+    package_root = Path(__file__).parents[2]
     source = tmp_path / "source"
     target = tmp_path / "target"
-    (source / "rules").mkdir(parents=True)
     for each_relative_path in materializer.codex_instruction_rule_relative_paths:
-        canonical_path = rules_root / Path(each_relative_path).name
+        canonical_path = package_root / each_relative_path
+        (source / each_relative_path).parent.mkdir(parents=True, exist_ok=True)
         (source / each_relative_path).write_text(
             canonical_path.read_text(encoding="utf-8"), encoding="utf-8"
         )
@@ -851,17 +851,17 @@ def test_codex_instruction_projection_carries_every_listed_rule(tmp_path: Path)
     assert "Failure handling for this run" in projected_instruction
     assert "Correction handling for this run" in projected_instruction
     manifest_record = _manifest_files(_required_manifest_path(config))["AGENTS.md"]
-    assert manifest_record["source"] == "rules/failure-blast-radius.md, rules/correction-lens.md"
+    assert manifest_record["source"] == "docs/rule-guides/failure-blast-radius.md, docs/rule-guides/correction-lens-excerpt.md"
 
 
 def test_codex_instruction_projection_skips_an_absent_listed_rule(
     tmp_path: Path,
 ) -> None:
-    rules_root = Path(__file__).parents[2] / "rules"
+    guides_root = Path(__file__).parents[2] / "docs" / "rule-guides"
     source = tmp_path / "source"
-    (source / "rules").mkdir(parents=True)
-    (source / "rules" / "correction-lens.md").write_text(
-        (rules_root / "correction-lens.md").read_text(encoding="utf-8"),
+    (source / "docs" / "rule-guides").mkdir(parents=True)
+    (source / "docs" / "rule-guides" / "correction-lens-excerpt.md").write_text(
+        (guides_root / "correction-lens-excerpt.md").read_text(encoding="utf-8"),
         encoding="utf-8",
     )
     config = MaterializerConfig(source, tmp_path / "target", should_apply=False)
@@ -869,7 +869,7 @@ def test_codex_instruction_projection_skips_an_absent_listed_rule(
     projection = materializer._build_codex_instruction_projection(config)
 
     assert projection is not None
-    assert projection.source_identity == "rules/correction-lens.md"
+    assert projection.source_identity == "docs/rule-guides/correction-lens-excerpt.md"
     assert "Correction handling for this run" in projection.content
     assert "Failure handling for this run" not in projection.content
 
@@ -877,10 +877,10 @@ def test_codex_instruction_projection_skips_an_absent_listed_rule(
 def test_build_plan_publishes_owned_agents_projection_and_tracks_drift(
     tmp_path: Path,
 ) -> None:
-    canonical_rule_path = Path(__file__).parents[2] / "rules" / "failure-blast-radius.md"
+    canonical_rule_path = Path(__file__).parents[2] / "docs" / "rule-guides" / "failure-blast-radius.md"
     source = tmp_path / "source"
     target = tmp_path / "target"
-    rule_path = source / "rules" / "failure-blast-radius.md"
+    rule_path = source / "docs" / "rule-guides" / "failure-blast-radius.md"
     rule_path.parent.mkdir(parents=True)
     rule_path.write_text(canonical_rule_path.read_text(encoding="utf-8"), encoding="utf-8")
     config = MaterializerConfig(source, target, should_apply=True)
@@ -892,7 +892,7 @@ def test_build_plan_publishes_owned_agents_projection_and_tracks_drift(
     first_projection = projected_path.read_text(encoding="utf-8")
     manifest_record = _manifest_files(_required_manifest_path(config))["AGENTS.md"]
     assert manifest_record["ownership"] == "codex-compat"
-    assert manifest_record["source"] == "rules/failure-blast-radius.md"
+    assert manifest_record["source"] == "docs/rule-guides/failure-blast-radius.md"
 
     rule_path.write_text(
         rule_path.read_text(encoding="utf-8").replace("Three attempts, then park.", "Three tested attempts, then park."),
@@ -944,12 +944,12 @@ def _prepare_projection_fixture(
 ) -> tuple[Path, Path, dict[str, Any], Path]:
     source = tmp_path / "source"
     target = tmp_path.parent / "codex-prod-target"
-    source_rule = source / "rules" / "failure-blast-radius.md"
+    source_rule = source / "docs" / "rule-guides" / "failure-blast-radius.md"
     source_hooks = source / "hooks" / "hooks.json"
     source_rule.parent.mkdir(parents=True)
     source_hooks.parent.mkdir(parents=True)
     source_rule.write_text(
-        (Path(__file__).parents[2] / "rules" / "failure-blast-radius.md").read_text(
+        (Path(__file__).parents[2] / "docs" / "rule-guides" / "failure-blast-radius.md").read_text(
             encoding="utf-8"
         ),
         encoding="utf-8",