claude-dev-env 8.19.1 → 8.20.0

package/bin/install.mjs

@@ -25,6 +25,10 @@ import {
     pruneManagedPermissionsFromSettings,
     retiredManagedPermissions,
 } from './merge_managed_permissions.mjs';
+import {
+    mergeMissingSettingsDefaults,
+    settingsDefaultsFromPackageSettings,
+} from './merge_settings_defaults.mjs';
 import {
     SKIPPED_SOURCE_ENTRY_NAMES,
     SKIPPED_SOURCE_FILE_EXTENSIONS,
@@ -2176,6 +2180,26 @@ function mergeManagedPermissions() {
     return { ...mergeOutcome, removedCount: pruneOutcome.removedCount };
 }
 
+/**
+ * Add each package setting default that ~/.claude/settings.json lacks.
+ *
+ * @returns {{addedKeys: string[]}}
+ */
+function mergePackageSettingsDefaults() {
+    const packageSettingsPath = join(PACKAGE_ROOT, SETTINGS_FILE_NAME);
+    if (!existsSync(packageSettingsPath)) return { addedKeys: [] };
+    const settingsDefaults = settingsDefaultsFromPackageSettings(
+        JSON.parse(readFileSync(packageSettingsPath, 'utf8')),
+    );
+    const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
+    const settings = loadClaudeSettingsObject(settingsPath);
+    const mergeOutcome = mergeMissingSettingsDefaults(settings, settingsDefaults);
+    if (mergeOutcome.addedKeys.length > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+    }
+    return mergeOutcome;
+}
+
 /**
  * Merge two path lists into one, keyed on `comparisonKeyForPath`, with the
  * current run's spelling winning a collision.
@@ -2864,6 +2888,11 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         );
     }
 
+    const settingsDefaultsMerge = mergePackageSettingsDefaults();
+    if (settingsDefaultsMerge.addedKeys.length > 0) {
+        console.log(`  Settings: added ${settingsDefaultsMerge.addedKeys.join(', ')}`);
+    }
+
     const agentsHubSource = join(PACKAGE_ROOT, 'AGENTS.md');
     if (existsSync(agentsHubSource)) {
         const agentsHubDest = join(AGENTS_HOME, 'AGENTS.md');

package/bin/install.settings-defaults.test.mjs

@@ -21,6 +21,10 @@ import {
     mergeManagedPermissionsIntoSettings,
     pruneManagedPermissionsFromSettings,
 } from './merge_managed_permissions.mjs';
+import {
+    mergeMissingSettingsDefaults,
+    settingsDefaultsFromPackageSettings,
+} from './merge_settings_defaults.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PACKAGE_SETTINGS_PATH = join(PACKAGE_ROOT, 'settings.json');
@@ -251,3 +255,52 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
         rmSync(sandboxHome, { recursive: true, force: true });
     }
 });
+
+test('package settings.json publishes the advisor model default', () => {
+    const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
+    assert.deepEqual(settingsDefaultsFromPackageSettings(packageSettings), { advisorModel: 'opus' });
+});
+
+test('a missing default is added and a user-set value is kept', () => {
+    const emptySettings = {};
+    assert.deepEqual(mergeMissingSettingsDefaults(emptySettings, { advisorModel: 'opus' }), {
+        addedKeys: ['advisorModel'],
+    });
+    assert.equal(emptySettings.advisorModel, 'opus');
+    const userSettings = { advisorModel: 'sonnet' };
+    assert.deepEqual(mergeMissingSettingsDefaults(userSettings, { advisorModel: 'opus' }), {
+        addedKeys: [],
+    });
+    assert.equal(userSettings.advisorModel, 'sonnet');
+});
+
+test('a Fable main model gets no advisor default', () => {
+    for (const fableModel of ['fable', 'claude-fable-5-1']) {
+        const fableSettings = { model: fableModel };
+        assert.deepEqual(mergeMissingSettingsDefaults(fableSettings, { advisorModel: 'opus' }), {
+            addedKeys: [],
+        });
+        assert.equal(Object.hasOwn(fableSettings, 'advisorModel'), false);
+    }
+    const opusSettings = { model: 'opus' };
+    mergeMissingSettingsDefaults(opusSettings, { advisorModel: 'opus' });
+    assert.equal(opusSettings.advisorModel, 'opus');
+});
+
+test('install adds advisorModel when missing and keeps a user choice on rerun', () => {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
+    try {
+        const firstRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(firstRun.status, 0, firstRun.stderr);
+        const settingsPath = join(sandboxHome, '.claude', 'settings.json');
+        assert.equal(JSON.parse(readFileSync(settingsPath, 'utf8')).advisorModel, 'opus');
+        const userChoice = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        userChoice.advisorModel = 'sonnet';
+        writeFileSync(settingsPath, JSON.stringify(userChoice, null, 4) + '\n');
+        const secondRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(secondRun.status, 0, secondRun.stderr);
+        assert.equal(JSON.parse(readFileSync(settingsPath, 'utf8')).advisorModel, 'sonnet');
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+    }
+});

package/bin/merge_settings_defaults.mjs

@@ -0,0 +1,50 @@
+/**
+ * Merge package-owned scalar setting defaults into a settings object.
+ *
+ * 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 Fable main model accepts only a Fable advisor, so a user whose settings
+ * name a Fable model gets no package advisor default.
+ */
+
+export const MANAGED_LIST_SETTING_KEYS = Object.freeze(['permissions']);
+export const ADVISOR_MODEL_SETTING_KEY = 'advisorModel';
+const FABLE_MODEL_PATTERN = /fable/i;
+
+/**
+ * Read the setting defaults from a package settings source object.
+ *
+ * @param {Record<string, unknown> | null | undefined} packageSettings
+ * @returns {Record<string, unknown>}
+ */
+export function settingsDefaultsFromPackageSettings(packageSettings) {
+    if (!packageSettings || typeof packageSettings !== 'object' || Array.isArray(packageSettings)) {
+        return {};
+    }
+    return Object.fromEntries(
+        Object.entries(packageSettings).filter(
+            ([settingKey]) => !MANAGED_LIST_SETTING_KEYS.includes(settingKey),
+        ),
+    );
+}
+
+/**
+ * Add each default whose key the target settings lack.
+ *
+ * @param {Record<string, unknown>} targetSettings Mutated in place.
+ * @param {Record<string, unknown>} settingsDefaults
+ * @returns {{addedKeys: string[]}}
+ */
+export function mergeMissingSettingsDefaults(targetSettings, settingsDefaults) {
+    const addedKeys = [];
+    const mainModel = targetSettings.model;
+    const usesFableMainModel = typeof mainModel === 'string' && FABLE_MODEL_PATTERN.test(mainModel);
+    for (const [settingKey, defaultValue] of Object.entries(settingsDefaults)) {
+        if (Object.hasOwn(targetSettings, settingKey)) continue;
+        if (settingKey === ADVISOR_MODEL_SETTING_KEY && usesFableMainModel) continue;
+        targetSettings[settingKey] = defaultValue;
+        addedKeys.push(settingKey);
+    }
+    return { addedKeys };
+}

package/package.json

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

package/rules/agent-merges-its-own-green-pull-request.md

@@ -24,7 +24,7 @@ One command prints the verdict:
 python packages/claude-dev-env/scripts/agent_merge_check.py <owner>/<name> <number>
 ```
 
-It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, and for an open review thread. It exits 2 when the state could not be read.
+It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, for a head the merge queue ejected for failed checks, and for an open review thread. It exits 2 when the state could not be read.
 
 Each hold reason names its own repair, and each repair belongs to the agent:
 
@@ -35,6 +35,7 @@ Each hold reason names its own repair, and each repair belongs to the agent:
 | A required check is red | Read the failing check, fix it, push |
 | A check is red or still running | Fix it, or wait for it, then read the verdict again |
 | A review thread is open | Answer it, push the fix, resolve the thread |
+| Ejected from the merge queue for failed checks on this head | Read the merge_group run, fix the failure, push, then read the verdict again |
 | The pull request is a draft | Mark it ready once the checks pass |
 
 ## When a gate elsewhere holds the merge command

package/rules/review-closure-is-a-check.md

@@ -26,6 +26,8 @@ It prints `CLOSED` and exits 0 when every finding on the head is answered. It pr
 | A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
 | A top-level comment on the pull request | A later top-level comment from the driving account |
 
+A review bot rewrites its summary comment on each pass. Its edit leaves an answered summary closed, because each new finding it has arrives as a review thread or a new comment. An edit from a person reopens the comment.
+
 A red circle marks a finding a review states as blocking, so resolution in silence leaves it open. The reply says what changed or why the finding stands, and the reviewer reads it beside the diff.
 
 The driving account is the one that opened the pull request. Where the agent comments under a second login, `--driver-login <login>` names it, repeatably.