claude-dev-env 8.73.0 → 8.73.2

package/.agents/agents/test_agent_frontmatter.py

@@ -474,20 +474,20 @@ EXPECTED_SOURCE_LINK_PAIRS = {
             "packages/claude-dev-env/rules/bdd.md",
         ),
         (
-            "<managed-root>/rules/verify-before-asking.md",
-            "packages/claude-dev-env/rules/verify-before-asking.md",
+            "<managed-root>/docs/rule-guides/verify-before-asking.md",
+            "packages/claude-dev-env/docs/rule-guides/verify-before-asking.md",
         ),
         (
-            "<managed-root>/rules/filesystem-search.md",
-            "packages/claude-dev-env/rules/filesystem-search.md",
+            "<managed-root>/docs/rule-guides/filesystem-search.md",
+            "packages/claude-dev-env/docs/rule-guides/filesystem-search.md",
         ),
         (
-            "<managed-root>/rules/shell-invocation.md",
-            "packages/claude-dev-env/rules/shell-invocation.md",
+            "<managed-root>/docs/rule-guides/shell-invocation.md",
+            "packages/claude-dev-env/docs/rule-guides/shell-invocation.md",
         ),
         (
-            "<managed-root>/rules/verify-runtime-state.md",
-            "packages/claude-dev-env/rules/verify-runtime-state.md",
+            "<managed-root>/docs/rule-guides/verify-runtime-state.md",
+            "packages/claude-dev-env/docs/rule-guides/verify-runtime-state.md",
         ),
         (
             "<managed-root>/rules/doc-inventory-integrity.md",
@@ -714,7 +714,7 @@ def test_clean_coder_links_canonical_policy_areas() -> None:
     required_links = (
         "<managed-root>/docs/CODE_RULES.md#5-no-abbreviations",
         "<managed-root>/rules/testing.md",
-        "<managed-root>/rules/verify-runtime-state.md",
+        "<managed-root>/docs/rule-guides/verify-runtime-state.md",
         "<managed-root>/rules/doc-inventory-integrity.md",
         "<managed-root>/rules/failure-blast-radius.md",
         "<agents-home>/skills/pr-lifecycle/SKILL.md",
@@ -950,24 +950,24 @@ def test_clean_coder_groups_session_policy_references() -> None:
     assert "AskUserQuestion" in body
     assert "do not ask in plain text or guess" in body
 
-    expected_session_policy_files = (
-        "testing.md",
-        "anti-corollary-tests.md",
-        "verify-before-asking.md",
-        "filesystem-search.md",
-        "shell-invocation.md",
-        "verify-runtime-state.md",
-        "doc-inventory-integrity.md",
-        "docstring-prose-matches-implementation.md",
-        "failure-blast-radius.md",
-        "workers-done-before-complete.md",
+    expected_session_policy_paths = (
+        "rules/testing.md",
+        "rules/anti-corollary-tests.md",
+        "docs/rule-guides/verify-before-asking.md",
+        "docs/rule-guides/filesystem-search.md",
+        "docs/rule-guides/shell-invocation.md",
+        "docs/rule-guides/verify-runtime-state.md",
+        "rules/doc-inventory-integrity.md",
+        "rules/docstring-prose-matches-implementation.md",
+        "rules/failure-blast-radius.md",
+        "rules/workers-done-before-complete.md",
     )
     session_policy_map = body[body.index("## Session policy map") :]
     session_policy_links = SOURCE_LINK_PATTERN.findall(session_policy_map)
-    for each_policy_file_name in expected_session_policy_files:
+    for each_policy_path in expected_session_policy_paths:
         assert (
-            f"<managed-root>/rules/{each_policy_file_name}",
-            f"packages/claude-dev-env/rules/{each_policy_file_name}",
+            f"<managed-root>/{each_policy_path}",
+            f"packages/claude-dev-env/{each_policy_path}",
         ) in session_policy_links
     assert (
         "<agents-home>/skills/pr-lifecycle/SKILL.md",

package/.agents/agents-archived/clean-coder.md

@@ -54,8 +54,8 @@ Installed paths use the active managed root and agents home resolved above; sour
 | `gh` body files | `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`) |
 | Plain illustrative docstrings | `<managed-root>/rules/plain-illustrative-docstrings.md` (source fallback: `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`) |
 | Tests / TDD | `<managed-root>/rules/testing.md` (source fallback: `packages/claude-dev-env/rules/testing.md`), `<managed-root>/rules/paired-test-coverage.md` (source fallback: `packages/claude-dev-env/rules/paired-test-coverage.md`), `<managed-root>/rules/bdd.md` (source fallback: `packages/claude-dev-env/rules/bdd.md`) |
-| Questions / task tracking | `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
-| Runtime evidence | `<managed-root>/rules/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/rules/verify-runtime-state.md`) |
+| Questions / task tracking | `<managed-root>/docs/rule-guides/verify-before-asking.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/verify-before-asking.md`) |
+| Runtime evidence | `<managed-root>/docs/rule-guides/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/verify-runtime-state.md`) |
 | Documentation / durable artifacts | `<managed-root>/rules/doc-inventory-integrity.md` (source fallback: `packages/claude-dev-env/rules/doc-inventory-integrity.md`), `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`) |
 | Batch / failure blast radius | `<managed-root>/rules/failure-blast-radius.md` (source fallback: `packages/claude-dev-env/rules/failure-blast-radius.md`) |
 | Git / GitHub | `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`), `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`), `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`) |
@@ -69,9 +69,9 @@ Load only the group that matches the task. Keep session policy details in these
 | Group | Canonical refs |
 |---|---|
 | Tests | `<managed-root>/rules/testing.md` (source fallback: `packages/claude-dev-env/rules/testing.md`); `<managed-root>/rules/anti-corollary-tests.md` (source fallback: `packages/claude-dev-env/rules/anti-corollary-tests.md`) |
-| Questions | `<managed-root>/rules/verify-before-asking.md` (source fallback: `packages/claude-dev-env/rules/verify-before-asking.md`) |
-| Search and shell | `<managed-root>/rules/filesystem-search.md` (source fallback: `packages/claude-dev-env/rules/filesystem-search.md`); `<managed-root>/rules/shell-invocation.md` (source fallback: `packages/claude-dev-env/rules/shell-invocation.md`) |
-| Runtime checks | `<managed-root>/rules/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/rules/verify-runtime-state.md`) |
+| Questions | `<managed-root>/docs/rule-guides/verify-before-asking.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/verify-before-asking.md`) |
+| Search and shell | `<managed-root>/docs/rule-guides/filesystem-search.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/filesystem-search.md`); `<managed-root>/docs/rule-guides/shell-invocation.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/shell-invocation.md`) |
+| Runtime checks | `<managed-root>/docs/rule-guides/verify-runtime-state.md` (source fallback: `packages/claude-dev-env/docs/rule-guides/verify-runtime-state.md`) |
 | Documentation | `<managed-root>/rules/doc-inventory-integrity.md` (source fallback: `packages/claude-dev-env/rules/doc-inventory-integrity.md`); `<managed-root>/rules/docstring-prose-matches-implementation.md` (source fallback: `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`) |
 | Batch failures | `<managed-root>/rules/failure-blast-radius.md` (source fallback: `packages/claude-dev-env/rules/failure-blast-radius.md`) |
 | Git | `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`); `<agents-home>/skills/pr-lifecycle/SKILL.md` (source fallback: `packages/claude-dev-env/.agents/skills/pr-lifecycle/SKILL.md`) |

package/.agents/skills/correction/playbooks/fix.md

@@ -8,7 +8,7 @@ Use this playbook when this session lands the fix for the correction itself. One
 4. Search for an existing control: a rule, hook, lint, test, or skill that already names this mistake. A control that exists and still let the mistake through makes this a repeat.
 5. Choose the layer with [`correction-lens.md`](../../../../docs/rule-guides/correction-lens.md). When `Repeat` is `yes`, or step 4 found a control, go one layer above the one that failed.
 6. Land the control in the repository whose code, CI, or agents it guards, per the guide's "Where the control lands" section. When that repository is not in this session, add it. When it cannot be added, print the brief, name the missing repository, and stop.
-7. Prove the control. Show it fail on the mistake from the brief's `Evidence` line, then pass with the change, per [`falsify-before-green.md`](../../../../rules/falsify-before-green.md) and [`proof-before-pull-request.md`](../../../../rules/proof-before-pull-request.md). Without that proof, open no pull request.
+7. Prove the control. Show it fail on the mistake from the brief's `Evidence` line, then pass with the change, per [`falsify-before-green.md`](../../../../rules/falsify-before-green.md) and [`proof-before-pull-request.md`](../../../../docs/rule-guides/proof-before-pull-request.md). Without that proof, open no pull request.
 8. Open the pull request through `pr-lifecycle`. Put the brief, the layer, and both proof results in the body.
 
 **Reply:** the layer chosen, why each higher layer cannot hold the lesson, and the pull request link.

package/.agents/skills/eli5/SKILL.md

@@ -52,7 +52,7 @@ presentation capability local.
 | Owner | Owns | ELI5 action |
 |---|---|---|
 | ELI5 | Beginner framing, visual expectation, minimal content, HTML continuity, and sharing | Keep the response in one useful, stable artifact. |
-| `~/.claude/rules/asd-ste100-language.md` | Word choice, sentence structure, terminology, punctuation, procedural instructions, and safety text | Read and apply it before writing or updating any page or response prose. |
+| `~/.claude/docs/rule-guides/asd-ste100-language.md` | Word choice, sentence structure, terminology, punctuation, procedural instructions, and safety text | Read and apply it before writing or updating any page or response prose. |
 | The named capability skill | Native data, evidence, workflow, and file-format requirements | Preserve its contract inside the HTML presentation envelope. |
 | User instructions and safety requirements | Task boundary, audience, confidentiality, and permitted result | Treat them as the controlling scope for the page. |
 | Human review | Technical accuracy, terminology, safety, confidentiality, intended meaning, and rendered usefulness | Review the completed artifact before delivery. |
@@ -67,7 +67,7 @@ keep ownership of their native artifact rules while ELI5 supplies the global
 ## Gotchas
 
 - Keep the HTML presentation envelope active when another capability skill creates the page.
-- Keep sentence-level prose under `~/.claude/rules/asd-ste100-language.md`.
+- Keep sentence-level prose under `~/.claude/docs/rule-guides/asd-ste100-language.md`.
 - Preserve an explicit user-supplied output path and an existing artifact path.
 - Keep one artifact path across all updates in the active task or conversation.
 - Keep every page self-contained and browser-ready.
@@ -95,7 +95,7 @@ Process steps in order.
    such as 3a and 3b for a case that holds a draft and a ready variant. Give
    each case its own card and its own visual.
 3. **Borderline — add the current explanation to that artifact.** Read and apply
-   `~/.claude/rules/asd-ste100-language.md` to every sentence. Frame the topic
+   `~/.claude/docs/rule-guides/asd-ste100-language.md` to every sentence. Frame the topic
    for a beginner, use a large useful visual, keep the text minimal, and update
    the same artifact in place.
 4. **Deterministic — run the digest check on a summary of many changes.** A

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -226,7 +226,7 @@ behind, so each new head runs the gate again.
 | Rule | Role |
 |---|---|
 | [`git-workflow.md`](#git-workflow) | Confirm each required context fired after the push |
-| [`verify-runtime-state.md`](~/.claude/rules/verify-runtime-state.md) | A status field is a report; read the thing the work was meant to make |
+| [`verify-runtime-state.md`](~/.claude/docs/rule-guides/verify-runtime-state.md) | A status field is a report; read the thing the work was meant to make |
 | [`falsify-before-green.md`](~/.claude/rules/falsify-before-green.md) | A green counts as evidence once the check has run red on a deliberate break |
 
 ## Review Closure Is a Check

package/.agents/skills/recovering-codex-startup/SKILL.md

@@ -29,7 +29,7 @@ For a non-Windows run, return exactly:
 ## Process
 
 1. When the session exposes a task tool, register the tasks in `reference/task-seeds.md`.
-2. Read `../../../rules/verify-runtime-state.md`.
+2. Read `../../../docs/rule-guides/verify-runtime-state.md`.
 3. Confirm Windows and collect a fresh timestamp.
 4. Use read-only Windows tools to inspect Codex processes only.
 5. Record process name, executable path, start time, and owner.

package/.agents/skills/recovering-codex-startup/reference/task-seeds.md

@@ -1,5 +1,5 @@
 1. Confirm Windows and use the exact refusal on another host.
-2. Read `../../../rules/verify-runtime-state.md`.
+2. Read `../../../docs/rule-guides/verify-runtime-state.md`.
 3. Collect fresh, read-only Codex process evidence and a timestamp.
 4. Record the exact path, name, start time, and owner.
 5. Report observation separately from diagnosis.

package/_shared/advisor/reference/third-party-bind.md

@@ -26,7 +26,7 @@ When the Astra flag is off, follow the Claude-chain steps below.
    ```
 
    Use `--model opus --effort` with the value of `ADVISOR_EFFORT` (default `xhigh`) on Opus.
-   User-facing wording follows [`rules/asd-ste100-language.md`](../../../rules/asd-ste100-language.md).
+   User-facing wording follows [`docs/rule-guides/asd-ste100-language.md`](../../../docs/rule-guides/asd-ste100-language.md).
    Account choice, failover, and the `advisor_blocked` status are in [`cli-chain.md`](cli-chain.md).
 4. Stop at the first successful bind.
    Record `{tier, result: "cli"}` for Opus or `{tier: "Astra", result: "codex"}` for the Astra helper, and set `selected_tier` to that tier.

package/bin/install.mjs

@@ -1254,6 +1254,7 @@ export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
     'blocking/send_user_file_open_locally_blocker.py',
     'blocking/question_to_user_enforcer.py',
     'blocking/session_handoff_blocker.py',
+    'blocking/artifact_look_gate.py',
     'session/issue_tracker_session_starter.py',
 ]);
 

package/bin/install.policy-lint.test.mjs

@@ -45,6 +45,7 @@ const allRetiredPolicyRegistrations = [
     'blocking/send_user_file_open_locally_blocker.py',
     'blocking/question_to_user_enforcer.py',
     'blocking/session_handoff_blocker.py',
+    'blocking/artifact_look_gate.py',
 ];
 const sourceHooks = JSON.parse(readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8'));
 const installedRoot = '/fixture-home/.claude';

package/bin/install.profile-root.test.mjs

@@ -82,7 +82,7 @@ test('explicit target has precedence over CLAUDE_CONFIG_DIR and the home default
 
 test('isPathWithinManagedRoot requires a separator boundary', () => {
     const managedRoot = resolve(join(tmpdir(), 'containment-root', '.claude'));
-    const insideFile = join(managedRoot, 'rules', 'asd-ste100-language.md');
+    const insideFile = join(managedRoot, 'rules', 'index.md');
     const evilSibling = `${managedRoot}-evil`;
     const evilChild = join(`${managedRoot}-evil`, 'rules', 'x.md');
 

package/bin/install.test.mjs

@@ -1230,6 +1230,7 @@ test('retired hook registrations stay managed so reinstall removes them', () =>
         'blocking/send_user_file_open_locally_blocker.py',
         'blocking/question_to_user_enforcer.py',
         'blocking/session_handoff_blocker.py',
+        'blocking/artifact_look_gate.py',
         'session/issue_tracker_session_starter.py',
     ]);
     const shippedHooks = JSON.parse(

package/commands/fix-followups.md

@@ -9,7 +9,7 @@ and deliver them as one pull request.
 The repository root is `$ARGUMENTS`, or the current repository when that is
 blank.
 
-Use `rules/asd-ste100-language.md` for user-facing wording.
+Use `docs/rule-guides/asd-ste100-language.md` for user-facing wording.
 
 ## 1. Read the ledger
 

package/commands/sr-loop.md

@@ -7,7 +7,7 @@ Run the converging cleanup loop on the target: `$ARGUMENTS` (blank means the
 current branch's diff). Each phase invokes an existing skill with the Skill
 tool and repeats it until a pass returns zero new findings.
 
-Use `rules/asd-ste100-language.md` for user-facing wording. Keep the loop's
+Use `docs/rule-guides/asd-ste100-language.md` for user-facing wording. Keep the loop's
 cleanup, verification, commit, push, and finish-report fields.
 
 ### Nit-only terminal

package/docs/references/prose-style-enforcement.md

@@ -10,7 +10,7 @@ The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_st
 
 ## Always on
 
-Historical and comparative language detection lives in `state_description_blocker.py`, which the staged policy lint applies under its state-description rule whatever this flag holds. Apply `rules/asd-ste100-language.md` for user-facing word choice and sentence style. Code-rules and security blockers are out of scope for this switch.
+Historical and comparative language detection lives in `state_description_blocker.py`, which the staged policy lint applies under its state-description rule whatever this flag holds. Apply `docs/rule-guides/asd-ste100-language.md` for user-facing word choice and sentence style. Code-rules and security blockers are out of scope for this switch.
 
 ## Hedging claims
 

package/docs/references/working-style.md

@@ -10,7 +10,7 @@ The SessionStart hook `hooks/session/working_style_prompt.py` points every sessi
 ## Presentation
 
 - Use ELI5 for beginner framing, large visuals, minimal text, one stable self-contained HTML artifact, update-in-place continuity, and sharing when a user-facing response needs that presentation.
-- Apply `~/.claude/rules/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form.
+- Apply `~/.claude/docs/rule-guides/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form.
 - Keep responses focused, brief, and concise. Keep disclaimers and caveats short while giving the main answer most of the response.
 - Give a high-level explanation by default and provide depth when the request calls for it.
 - Match written-document length to the task. Cover the substance and keep every section, summary, and phrase useful.

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

@@ -1,7 +1,15 @@
-Back to the [rule entry](../../rules/asd-ste100-language.md).
+Back to the [rules index](../../rules/index.md).
 
 # ASD-STE100 language policy
 
+## In brief
+
+**When:** Writing chat, tool narration, or repository prose.
+
+Use the sole general language rule. Write short, complete sentences on one topic. Use active voice; lead with conditions; one action per step. Use plain, precise words, stable terms. Expand abbreviations and contractions; name unclear pronouns. Be inclusive; punctuate clearly. Preserve exact labels, identifiers, formulas, titles, interface text. Say each fact once. Send a result, blocker, or question. Mark injury or death `WARNING`, equipment damage `CAUTION`; state condition then result. Aim for 20 words per step, 25 per description. Treat checks as aids; have a human verify accuracy, terms, safety, confidentiality, meaning.
+
+**Enforcement:** none.
+
 Use this rule as the sole general language authority for user-facing text in this repository.
 It defines ordinary word choice, sentence style, tone, punctuation, and prose form.
 

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

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/cleanup-temp-files.md).
+Back to the [rules index](../../rules/index.md).
 
 # Clean up temporary files
 
+## In brief
+
+Prefer memory to scratch files and track any temporary files you create. At completion, remove those files and leave user-requested files in place. Files under the OS temporary root or `$CLAUDE_JOB_DIR` need no explicit removal; a parent handles child-agent scratch.
+
+**Enforcement:** none.
+
 **When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
 
 Source: [Anthropic: Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
@@ -25,7 +31,7 @@ Three kinds of file are already ephemeral and need no explicit removal:
 - A file under `$CLAUDE_JOB_DIR`, which the harness clears with the job.
 - A child agent's scratch file, which the parent removes at teardown.
 
-Use an allowed removal form for everything else: [`destructive-commands.md`](../../rules/destructive-commands.md) names them.
+Use an allowed removal form for everything else: [`destructive-commands.md`](destructive-commands.md) names them.
 
 ## What counts as temporary
 

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

@@ -1,7 +1,17 @@
-Back to the [rule entry](../../rules/destructive-commands.md).
+Back to the [rules index](../../rules/index.md).
 
 # Destructive commands in Bash
 
+## In brief
+
+**When:** Removing files or writing a destructive command string.
+
+Keep destructive literals out of command strings, including data. Use literal absolute targets; never target a bare temporary root. Use `git rm` for tracked files. Pass bodies by file and test hooks through the test suite. Copy this line into every subagent prompt:
+
+> Never use bash rm in any form. Delete scratch/probe files with the PowerShell tool (Remove-Item -Recurse -Force -Confirm:$false <absolute path>), or leave them in the OS temp dir; remove worktrees only via git worktree remove --force.
+
+**Enforcement:** none; a harness permission prompt can stall unattended work.
+
 No hook watches Bash commands for destructive patterns. What you face is the harness permission prompt. The harness raises it from the session permission mode and the permission rules in effect on your host. In a background or auto-mode run no human can answer that prompt, so the call stalls.
 
 Two consequences follow. Use an allowed removal form, and keep a destructive literal out of the command string even when it rides only as data.
@@ -26,7 +36,7 @@ Never pass a bare ephemeral root, such as `/tmp`, the OS temp root itself, or a
 
 Write each target as a literal path. A variable, a `$(...)` or backtick expansion, or a brace glob hides what the command will delete from the reader and from the permission matcher.
 
-A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md).
+A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by the harness and needs no explicit removal. See the exception clause in [`cleanup-temp-files.md`](cleanup-temp-files.md).
 
 ## Keep destructive literals out of the command string
 
@@ -45,5 +55,5 @@ Prefer that a child leaves its scratch files for the parent to remove at teardow
 
 ## Sibling rules
 
-- [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
+- [`cleanup-temp-files.md`](cleanup-temp-files.md) names which scratch files a task removes, and which it leaves.
 - [`windows-filesystem-safe.md`](../../rules/windows-filesystem-safe.md) holds the safe `rmtree` and `force_rmtree` patterns for read-only Windows files.

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

@@ -1,7 +1,15 @@
-Back to the [rule entry](../../rules/explore-thoroughly.md).
+Back to the [rules index](../../rules/index.md).
 
 # Explore thoroughly
 
+## In brief
+
+**When:** Before you log, plan, delegate, or build an ask, or choose an approach.
+
+Search for what already does the ask, in full or in part. When something exists, stop and report it to the user in four points; run the `search-before-acting` skill. Then read files, patterns, and constraints, scaled to risk. Once the files, constraints, and success condition are known, act without repeating settled research.
+
+**Enforcement:** the pull request gate denies a body with no "Existing work" section.
+
 Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#overthinking-and-excessive-thoroughness)
 
 Note: This deliberately chooses exploration depth over the "commit and execute quickly" pattern from the same source. Thorough upfront exploration is preferred for the intended workflow.

package/docs/rule-guides/features-start-with-an-eval.md

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/features-start-with-an-eval.md).
+Back to the [rules index](../../rules/index.md).
 
 # Features start with an eval
 
+## In brief
+
+Your first action is the Skill tool with skill `claude-api` and args `build-eval`. Build the feature against that eval. When the work touches an existing feature with no eval, start a separate session to build that eval in parallel. An Agent-tool subagent does not count. You own its result.
+
+**Enforcement:** `hooks/blocking/pr_lifecycle_skill_gate.py` denies a `feat` pull request with no "Eval" section or no build-eval call.
+
 **When this applies:** A user asks for a new feature or a change in behavior, in any project.
 
 ## What counts
@@ -13,7 +19,7 @@ An eval is three things for one feature: a set of input cases with their expecte
 ## Rule
 
 1. Make the Skill tool call with skill `claude-api` and args `build-eval` your first action on the ask. A user who types `/claude-api build-eval` has made the same call.
-2. Run the existing-work search from [`explore-thoroughly.md`](../../rules/explore-thoroughly.md) next. The guide's own first step also looks for cases, graders, and runners that exist.
+2. Run the existing-work search from [`explore-thoroughly.md`](explore-thoroughly.md) next. The guide's own first step also looks for cases, graders, and runners that exist.
 3. Follow the guide the skill loads. It asks the user to approve the inputs and the grading method, and to approve the cost before the first paid run. Ask through the session's question tool. Where the host says to keep working while a question waits, continue on the option you recommended and change course if the answer differs.
 4. Run the eval before the change to get a baseline, build the feature, and run it again.
 5. Give the pull request an "Eval" section. Name the cases and the grader, give the command that runs the eval in backticks, and quote the baseline and the result.

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

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/filesystem-search.md).
+Back to the [rules index](../../rules/index.md).
 
 # Filesystem search
 
+## In brief
+
+Scope every search to a project, worktree, package, or narrowing filter. Never start at a filesystem root, drive root, bare home, or share root. Read a known path directly; use scoped `es.exe`, Glob, or Grep for discovery. After `es.exe` Error 8, retry twice before falling back within the same scope. Run one large shell walk at a time.
+
+**Enforcement:** none.
+
 **When this applies:** Any search for files by name, path, extension, size, or date. That includes `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
 
 ## The scope invariant

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

@@ -35,6 +35,6 @@ For a task that spawned workers, the completion condition and checklist live in
 
 ## 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.
+Progress claims come from tool results in the current session. Failed tests carry their output. Skipped steps are named. The [ASD-STE100 language rule](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/memory-stores-durable-facts.md

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/memory-stores-durable-facts.md).
+Back to the [rules index](../../rules/index.md).
 
 # Memory stores durable facts
 
+## In brief
+
+Keep only a fact that helps a fresh session weeks later. Remove dates, task identifiers, commits, and paths from a draft; if the remainder is empty or false, put it in the task tracker or handoff instead. Store standing user preferences, stable setup traps, and useful resource pointers. Delete stale memory and its index line in the same run.
+
+**Enforcement:** none.
+
 **When this applies:** Before you write or update a file in an auto-memory
 directory, and before you add its line to `MEMORY.md`.
 
@@ -55,5 +61,5 @@ into each session and reads as current.
 | Rule | Role |
 |---|---|
 | [`correction-lens.md`](../../rules/correction-lens.md) | A memory records a decision, and the control holds the behavior |
-| [`verify-before-asking.md`](../../rules/verify-before-asking.md) | A recalled fact is a claim to re-check |
-| [`cleanup-temp-files.md`](../../rules/cleanup-temp-files.md) | Scratch output leaves with the task |
+| [`verify-before-asking.md`](verify-before-asking.md) | A recalled fact is a claim to re-check |
+| [`cleanup-temp-files.md`](cleanup-temp-files.md) | Scratch output leaves with the task |

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

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/no-contrast-framing.md).
+Back to the [rules index](../../rules/index.md).
 
 # No contrast framing
 
+## In brief
+
+State the chosen point directly and leave out the discarded reading. Remove these six forms: `trailing-comma-not`, `corrective-it-is-not`, `substitution-rather-than`, `additive-not-just`, `comparative-ranking`, `substitution-as-opposed-to`. Keep quantity comparisons. If a sentence loses substance, add the failing check, log line, measured number, or file and line.
+
+**Enforcement:** staged policy lint and `scripts/durable_post_lint.py` check authored text; the agent checks chat.
+
 **When this applies:** Every sentence a person reads. A chat reply, a commit
 message, a pull request title or body, a review comment, an issue, a rule file,
 a document, a plan, a memory file.
@@ -55,7 +61,7 @@ file and the line.
 The pattern list lives in
 `scripts/dev_env_scripts_constants/contrast_framing_constants.py`, and both
 lints read that one list. A synchronization test requires the rule file
-`rules/no-contrast-framing.md` to name every form the list carries.
+`docs/rule-guides/no-contrast-framing.md` to name every form the list carries.
 
 A chat reply reaches no check, so the same list is what the writer reads the
 sentence against: a comma followed by `not`, a `rather than`, a `not just`, a
@@ -65,6 +71,6 @@ ranking of one thing over another.
 
 | Rule | Role |
 |---|---|
-| [`asd-ste100-language.md`](../../rules/asd-ste100-language.md) | Plain word choice, sentence style, and tone |
+| [`asd-ste100-language.md`](asd-ste100-language.md) | Plain word choice, sentence style, and tone |
 | [`correction-lens.md`](../../rules/correction-lens.md) | Every correction becomes a control at the highest layer that can hold it |
-| [`research-mode.md`](../../rules/research-mode.md) | A claim carries its source |
+| [`research-mode.md`](research-mode.md) | A claim carries its source |

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

@@ -18,5 +18,5 @@ Code written here needs local maintenance. A widely used tool draws fixes and ne
 
 | 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 |
+| [`explore-thoroughly.md`](explore-thoroughly.md) | Read existing code before proposing a change |
+| [`verify-before-asking.md`](verify-before-asking.md) | Check a question with a tool before asking it |

package/docs/rule-guides/proof-before-pull-request.md

@@ -1,7 +1,11 @@
-Back to the [rule entry](../../rules/proof-before-pull-request.md).
+Back to the [rules index](../../rules/index.md).
 
 # Proof before a pull request
 
+## In brief
+
+Run the change where it runs, with and without it, and quote both results under "Proof in practice" in the body. A hook denies a body without one. Unproven: leave it unopened and tell the user.
+
 **When this applies:** Every session that builds a change and opens a pull request, in every project.
 
 ## Rule

package/docs/rule-guides/request-scope.md

@@ -1,7 +1,11 @@
-Back to the [rule entry](../../rules/request-scope.md).
+Back to the [rules index](../../rules/index.md).
 
 # Request scope
 
+## In brief
+
+A shipped gate makes each block line restating what it enforces dead text. Propose removing all of them, past the part asked about, and give each kept line's reason. Read the output back before reporting done.
+
 **When this applies:** The user asks whether part of a prompt, rule, card, or check is still needed, or asks you to change one.
 
 ## Rule

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

@@ -1,7 +1,15 @@
-Back to the [rule entry](../../rules/research-mode.md).
+Back to the [rules index](../../rules/index.md).
 
 # Research mode (global)
 
+## In brief
+
+**When:** Making a factual claim, recommendation, or piece of advice.
+
+State no claim without a credible source; do not guess or infer. Before an answer depends on an unsettled fact, run each tool that could settle it and that reads state or that permissions already allow, and stop at the first one that settles it. When none can, name the exact check and who can run or approve it. Cite a project file, web source, named expert or paper, or official documentation for each claim. Retract claims a source cannot support. Extract document text before analysis and ground the answer in word-for-word quotes. In chat, cite compactly with a link or `file:line`; put full quotes and citation lists in artifacts or replies that request them. Ground synthesis in sourced inputs. Creative ideas need no citation.
+
+**Enforcement:** none.
+
 Three anti-hallucination constraints are always active.
 
 Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)

package/docs/rule-guides/session-title.md

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/session-title.md).
+Back to the [rules index](../../rules/index.md).
 
 # Status in the session title
 
+## In brief
+
+Before each turn ends, set the title to `<emoji> <name>`. Use the red flag when the user must act, the check mark when the work is done, and the hourglass while work, CI, or a merge queue runs. The name has 25 characters or fewer, in sentence case, with concrete nouns and no IDs, dates, or branch names.
+
+**Enforcement:** `hooks/blocking/session_title_format_gate.py` denies a malformed title; `hooks/blocking/session_title_stop_gate.py` blocks a turn end with no title.
+
 **When this applies:** The session has a tool whose name ends in `__set_session_title`, such as `mcp__claude-code-remote__set_session_title` in a cloud session or `mcp__ccd_session_mgmt__set_session_title` in the desktop app.
 
 ## Rule

package/docs/rule-guides/shell-invocation.md

@@ -1,7 +1,15 @@
-Back to the [rule entry](../../rules/shell-invocation.md).
+Back to the [rules index](../../rules/index.md).
 
 # Shell Invocation
 
+## In brief
+
+**When:** Issuing a Bash-tool shell command, or writing a `settings.json` permission rule.
+
+On Windows, run shell work through `pwsh`: `pwsh -NoProfile -File '<script>.ps1' <args>` for a script, and `pwsh -NoProfile -Command "..."` or the `PowerShell` tool for inline work. A direct interpreter call such as `python script.py` conforms as written. Keep `powershell`, `cmd /c`, and `bash -c` out of permission rules. Keep `$(...)`, unescaped backticks, and `<(...)` or `>(...)` out of Bash commands; split the call or use a flag form such as `git -C "<path>"`. Arithmetic `$((...))` passes.
+
+**Enforcement:** none; a permission prompt on a wrapped command is the signal. `blocking/msys_rev_path_rewriter.py` only rewrites a `<rev>:<path>` argument.
+
 Two constraints govern every shell command an agent issues: which shell runs it, and what the command string may contain.
 
 ## Use pwsh

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

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/verify-before-asking.md).
+Back to the [rules index](../../rules/index.md).
 
 # Verify before asking
 
+## In brief
+
+Inspect files, directories, configuration, environment, databases, and available tools for the answer. Recheck facts recalled from earlier sessions. Apply any criterion the user already supplied and state the decision. Ask only for a judgment, preference, or inaccessible fact.
+
+**Enforcement:** none.
+
 **When this applies:** Before asking the user any clarifying question during discovery, scoping, or implementation planning.
 
 ## Rule

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

@@ -1,7 +1,13 @@
-Back to the [rule entry](../../rules/verify-runtime-state.md).
+Back to the [rules index](../../rules/index.md).
 
 # Verify runtime state
 
+## In brief
+
+Gather a live signal this session: process list, port probe, log, status code, or fresh reproduction. Read the user's terminal and named error log while a reported failure is still visible. Check the effect the work should produce, including each job result, loaded config, or deployed artifact; a success status alone does not establish the effect. When testing code, identify the loaded module path.
+
+**Enforcement:** none.
+
 **When this applies:** Before stating that a component is fine, healthy, innocent, or working: during debugging, triage, or any judgment about whether something runs.
 
 ## Rule