claude-dev-env 8.73.1 → 8.74.0

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/cde.mjs

@@ -45,6 +45,7 @@ export function createHelpText() {
         "  cde followup brief        Write the task an agent fixes them from",
         "  cde followup count        Report the backlog against the threshold",
         "  cde followup clear        Empty the ledger",
+        "  cde followup dedupe       Remove exact repeated ledger lines",
         "",
         "Python may also be selected with CDE_PYTHON.",
     ].join("\n");

package/bin/cde.test.mjs

@@ -292,4 +292,5 @@ test("dispatches followup to the follow-up ledger command", async () => {
 test("help names the followup command", () => {
     assert.match(createHelpText(), /cde <lint\|verify\|followup>/);
     assert.match(createHelpText(), /cde followup count/);
+    assert.match(createHelpText(), /cde followup dedupe/);
 });

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.settings-defaults.test.mjs

@@ -263,10 +263,18 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
     }
 });
 
-test('package settings.json publishes the session agent, advisor model and auto mode defaults', () => {
+test('package settings.json publishes the session agent, advisor model, auto-compact and auto mode defaults', () => {
     const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
     const settingsDefaults = settingsDefaultsFromPackageSettings(packageSettings);
-    assert.deepEqual(Object.keys(settingsDefaults).sort(), ['advisorModel', 'agent', 'autoMode']);
+    assert.deepEqual(
+        Object.keys(settingsDefaults).sort(),
+        ['advisorModel', 'agent', 'autoCompactWindow', 'autoMode', 'modelSettings'],
+    );
+    assert.equal(settingsDefaults.autoCompactWindow, 350000);
+    assert.deepEqual(settingsDefaults.modelSettings, {
+        'claude-haiku-5-5': { autoCompactWindow: 100000 },
+        'claude-haiku-4-5': { autoCompactWindow: 100000 },
+    });
     assert.equal(settingsDefaults.agent, 'dev-env-session');
     assert.ok(
         existsSync(join(PACKAGE_ROOT, '.agents', 'agents', `${settingsDefaults.agent}.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/bin/merge_settings_defaults.mjs

@@ -4,9 +4,35 @@
  * Every top-level key in the package settings.json other than the managed
  * lists (`permissions`) is a default. Install adds a default only when the
  * user settings lack that key, so a value the user already set stays as is.
+ *
+ * A per-model key (`modelSettings`) merges one level deeper: install adds each
+ * model entry, and each field inside an entry, that the user settings lack.
  */
 
 export const MANAGED_LIST_SETTING_KEYS = Object.freeze(['permissions']);
+export const PER_MODEL_SETTING_KEYS = Object.freeze(['modelSettings']);
+
+function isPlainObject(candidate) {
+    return Boolean(candidate) && typeof candidate === 'object' && !Array.isArray(candidate);
+}
+
+function mergeMissingPerModelFields(targetPerModel, defaultPerModel, settingKey) {
+    const addedKeys = [];
+    for (const [modelName, defaultFields] of Object.entries(defaultPerModel)) {
+        if (!Object.hasOwn(targetPerModel, modelName)) {
+            targetPerModel[modelName] = { ...defaultFields };
+            addedKeys.push(`${settingKey}.${modelName}`);
+            continue;
+        }
+        if (!isPlainObject(targetPerModel[modelName])) continue;
+        for (const [fieldName, fieldDefault] of Object.entries(defaultFields)) {
+            if (Object.hasOwn(targetPerModel[modelName], fieldName)) continue;
+            targetPerModel[modelName][fieldName] = fieldDefault;
+            addedKeys.push(`${settingKey}.${modelName}.${fieldName}`);
+        }
+    }
+    return addedKeys;
+}
 
 /**
  * Read the setting defaults from a package settings source object.
@@ -35,8 +61,15 @@ export function settingsDefaultsFromPackageSettings(packageSettings) {
 export function mergeMissingSettingsDefaults(targetSettings, settingsDefaults) {
     const addedKeys = [];
     for (const [settingKey, defaultValue] of Object.entries(settingsDefaults)) {
+        const isPerModelMerge = PER_MODEL_SETTING_KEYS.includes(settingKey)
+            && isPlainObject(targetSettings[settingKey])
+            && isPlainObject(defaultValue);
+        if (isPerModelMerge) {
+            addedKeys.push(...mergeMissingPerModelFields(targetSettings[settingKey], defaultValue, settingKey));
+            continue;
+        }
         if (Object.hasOwn(targetSettings, settingKey)) continue;
-        targetSettings[settingKey] = defaultValue;
+        targetSettings[settingKey] = structuredClone(defaultValue);
         addedKeys.push(settingKey);
     }
     return { addedKeys };

package/bin/merge_settings_defaults.test.mjs

@@ -41,3 +41,56 @@ test('mergeMissingSettingsDefaults adds absent keys and keeps present values', (
         theme: 'dark',
     });
 });
+
+test('mergeMissingSettingsDefaults should add a missing model entry and a missing field inside a present one', () => {
+    const targetSettings = {
+        modelSettings: {
+            'claude-opus-5-5': { effortLevel: 'medium' },
+            'claude-haiku-4-5': { effortLevel: 'low' },
+        },
+    };
+
+    assert.deepEqual(
+        mergeMissingSettingsDefaults(targetSettings, {
+            modelSettings: {
+                'claude-haiku-5-5': { autoCompactWindow: 100000 },
+                'claude-haiku-4-5': { autoCompactWindow: 100000 },
+            },
+        }),
+        {
+            addedKeys: [
+                'modelSettings.claude-haiku-5-5',
+                'modelSettings.claude-haiku-4-5.autoCompactWindow',
+            ],
+        },
+    );
+    assert.deepEqual(targetSettings.modelSettings, {
+        'claude-opus-5-5': { effortLevel: 'medium' },
+        'claude-haiku-4-5': { effortLevel: 'low', autoCompactWindow: 100000 },
+        'claude-haiku-5-5': { autoCompactWindow: 100000 },
+    });
+});
+
+test('mergeMissingSettingsDefaults should give each target its own copy of an added default', () => {
+    const settingsDefaults = { modelSettings: { 'claude-haiku-5-5': { autoCompactWindow: 100000 } } };
+    const firstTarget = {};
+    const secondTarget = {};
+
+    mergeMissingSettingsDefaults(firstTarget, settingsDefaults);
+    firstTarget.modelSettings['claude-haiku-5-5'].autoCompactWindow = 200000;
+    mergeMissingSettingsDefaults(secondTarget, settingsDefaults);
+
+    assert.deepEqual(secondTarget.modelSettings, { 'claude-haiku-5-5': { autoCompactWindow: 100000 } });
+});
+
+test('mergeMissingSettingsDefaults should keep a per-model value the user already set', () => {
+    const targetSettings = { modelSettings: { 'claude-haiku-5-5': { autoCompactWindow: 150000 } } };
+
+    assert.deepEqual(
+        mergeMissingSettingsDefaults(targetSettings, {
+            modelSettings: { 'claude-haiku-5-5': { autoCompactWindow: 100000 } },
+        }),
+        { addedKeys: [] },
+    );
+    assert.deepEqual(targetSettings.modelSettings, { 'claude-haiku-5-5': { autoCompactWindow: 150000 } });
+});

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/flag-non-breaking-findings.md

@@ -38,9 +38,12 @@ A message with no catalog entry resolves to `<rule>/unclassified`, which a parti
 | `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 |
+| `cde followup dedupe` | Removes exact repeated lines and keeps the first of each |
 
 `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.
 
+`.gitattributes` marks the ledger `merge=union`, so a local `git merge` keeps both sides' appended lines without a conflict. GitHub's server-side merge ignores the attribute. Every ledger write drops exact repeated lines, and the `followup-ledger-duplicates` repository check fails a tree that still holds one.
+
 The `/fix-followups` command reads the brief, fixes each rule group, opens a pull request, and clears the ledger.
 
 ## Worked example

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 |