feat(set): validate autoMode structure + flag it in shared settings (CA-SET)

settings-validator now validates the autoMode block (auto-mode classifier
config). Structure (medium): autoMode must be an object whose only keys are
environment/allow/soft_deny/hard_deny, each a string array ("$defaults" is a
valid entry); flags not-an-object, unknown-subkey, not-string-array. Dead-config
(low): Claude Code does not read autoMode from shared project settings
(.claude/settings.json), so an autoMode block committed there has no effect —
keyed on file.scope === 'project'.

Both premises primary-source-verified (code.claude.com/docs/en/auto-mode-config).
The plan's "test per-file scope first" gate passed: ConfigFile already carries
scope. SET is in the orchestrator; SC-5 re-checked, byte-equal (snapshot fixture
has no autoMode). Fixtures force-added (.claude/ is gitignored).

Tests +5 (944->949). Scanner count unchanged (13). --json/--raw byte-stable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8

CLAUDE.md

@@ -221,6 +221,28 @@ claimed CC "suggests the parent directory when an entry points at a file"; that
 primary-source-verified conditions. `skills` is deliberately *not* in `SHADOWING_PATH_FIELDS`
 (it adds to the default scan, never shadows).
 
+### SET scanner — autoMode validation (`CA-SET`)
+
+Per-file check in `settings-validator.mjs` (`autoMode` was in `KNOWN_KEYS` but had no nested
+validation). Two sub-checks, both primary-source-verified against
+`code.claude.com/docs/en/auto-mode-config`:
+
+1. **Structure** (severity **MEDIUM**): `autoMode`, if present, must be an object whose only keys
+   are `environment`/`allow`/`soft_deny`/`hard_deny` (`AUTO_MODE_SUBKEYS`), each a **string
+   array** (the literal `"$defaults"` is a valid entry, so it passes the string check for free).
+   `problem` ∈ `not-an-object` / `unknown-subkey` / `not-string-array` in `details`.
+2. **Dead-config** (severity **LOW**): Claude Code does **not** read `autoMode` from *shared*
+   project settings — verbatim: *"The classifier does not read `autoMode` from shared project
+   settings in `.claude/settings.json`, so a checked-in repo cannot inject its own allow rules."*
+   The check keys on **`file.scope === 'project'`** (file-discovery's `classifyScope` returns
+   `'project'` for a committed `.claude/settings.json`; `'local'`/`'user'`/`'managed'` are read and
+   not flagged). `problem: 'shared-project-scope'`. This is why the plan's "test per-file scope
+   first" gate passed — `ConfigFile` already carries `scope`.
+
+The two sub-checks are independent (a malformed autoMode in shared scope yields both). SET is in the
+orchestrator, so SC-5 was re-checked after this change — byte-equal (the snapshot fixture has no
+`autoMode`, so the block never fires there).
+
 ## Gotchas
 
 - Session directories accumulate — use `/config-audit cleanup` to manage

README.md

@@ -12,7 +12,7 @@
 ![Commands](https://img.shields.io/badge/commands-18-green)
 ![Agents](https://img.shields.io/badge/agents-6-orange)
 ![Hooks](https://img.shields.io/badge/hooks-4-red)
-![Tests](https://img.shields.io/badge/tests-944+-brightgreen)
+![Tests](https://img.shields.io/badge/tests-949+-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
 A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 13 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
@@ -393,6 +393,17 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
 > `claude plugin validate`. Note `skills` *adds to* the default `skills/` scan, so a custom path
 > here is never a shadow — it just has to resolve to a real folder.
 
+> **`autoMode` validation — structure and the shared-settings blind spot.** The SET scanner
+> checks the auto-mode classifier config two ways. **Structure:** `autoMode` must be an object
+> whose only keys are `environment`, `allow`, `soft_deny`, and `hard_deny`, each a list of
+> plain-text rule strings (the literal `"$defaults"` is allowed). An unknown sub-key (e.g. a
+> typo'd `hard_denies`), a non-object value, or a sub-key that isn't a string array is flagged
+> **medium** — a typo'd key silently drops those rules. **Scope:** Claude Code does **not** read
+> `autoMode` from *shared* project settings (`.claude/settings.json`) — "a checked-in repo cannot
+> inject its own allow rules" — so an `autoMode` block committed there is dead config (**low**);
+> it only takes effect in user (`~/.claude/settings.json`), local (`.claude/settings.local.json`),
+> or managed settings.
+
 ### CLI Tools
 
 All tools work standalone — no Claude Code session needed:

scanners/lib/humanizer-data.mjs

@@ -142,7 +142,27 @@ export const TRANSLATIONS = {
         recommendation: 'Open the file and fix the JSON syntax shown in the details (often a missing comma or quote).',
       },
     },
-    patterns: [],
+    patterns: [
+      {
+        // Specific case first: well-formed autoMode placed in the wrong scope.
+        regex: /^autoMode in shared project settings/,
+        translation: {
+          title: 'Your auto-mode rules are in a file Claude Code ignores',
+          description: 'Claude Code doesn\'t read `autoMode` from shared project settings (`.claude/settings.json`), so a checked-in repo can\'t grant itself auto-approval rules. The block has no effect where it is.',
+          recommendation: 'Move `autoMode` to your user settings (`~/.claude/settings.json`), the local (gitignored) project settings (`.claude/settings.local.json`), or managed settings.',
+        },
+      },
+      {
+        // Catch-all for autoMode structure problems (not-an-object, unknown
+        // sub-key, sub-key not a string array).
+        regex: /^autoMode/,
+        translation: {
+          title: 'Your `autoMode` block is malformed',
+          description: '`autoMode` must be an object with `environment`, `allow`, `soft_deny`, and `hard_deny`, each a list of plain-text rules. Part of it doesn\'t match that shape, so those rules may not apply.',
+          recommendation: 'Fix the `autoMode` entry shown in the details — use only the four known keys, each set to a list of strings.',
+        },
+      },
+    ],
     _default: {
       title: 'Your settings file has an issue',
       description: 'A check on your settings file flagged something worth a look.',

scanners/settings-validator.mjs

@@ -75,6 +75,11 @@ const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
  * a project root to walks/discovery, inflating per-turn cost and confusing scope. */
 const ADDITIONAL_DIRS_THRESHOLD = 2;
 
+/** The only valid sub-keys of `autoMode`, each a prose-rule string array
+ * (the literal "$defaults" is a valid entry). Verified against
+ * code.claude.com/docs/en/auto-mode-config. */
+const AUTO_MODE_SUBKEYS = new Set(['environment', 'allow', 'soft_deny', 'hard_deny']);
+
 /**
  * Scan all settings.json files discovered.
  * @param {string} targetPath
@@ -234,6 +239,75 @@ export async function scan(targetPath, discovery) {
       }));
     }
 
+    // autoMode validation (auto-mode classifier config).
+    // Structure: must be an object whose only keys are the four documented
+    // prose-rule arrays (each an array of strings; "$defaults" is a valid entry).
+    // Dead-config: Claude Code does NOT read autoMode from SHARED project settings
+    // (.claude/settings.json) — "a checked-in repo cannot inject its own allow
+    // rules" — so it is only honored in user/local/managed scopes.
+    if (parsed.autoMode !== undefined) {
+      const am = parsed.autoMode;
+      if (typeof am !== 'object' || am === null || Array.isArray(am)) {
+        findings.push(finding({
+          scanner: SCANNER,
+          severity: SEVERITY.medium,
+          title: 'autoMode must be an object',
+          description: `${file.relPath}: "autoMode" must be an object with environment/allow/soft_deny/hard_deny arrays, got ${Array.isArray(am) ? 'array' : typeof am}.`,
+          file: file.absPath,
+          evidence: `autoMode: ${JSON.stringify(am)}`,
+          recommendation: 'Set autoMode to an object, e.g. { "environment": ["$defaults"] }.',
+          autoFixable: false,
+          details: { key: 'autoMode', problem: 'not-an-object' },
+        }));
+      } else {
+        for (const subKey of Object.keys(am)) {
+          if (!AUTO_MODE_SUBKEYS.has(subKey)) {
+            findings.push(finding({
+              scanner: SCANNER,
+              severity: SEVERITY.medium,
+              title: `autoMode has an unknown sub-key: ${subKey}`,
+              description: `${file.relPath}: "autoMode.${subKey}" is not a recognized sub-key. Valid keys are environment, allow, soft_deny, hard_deny. It is silently ignored — a typo of a real key (e.g. "hard_denies") means those rules never apply.`,
+              file: file.absPath,
+              evidence: `autoMode.${subKey}`,
+              recommendation: 'Use only environment, allow, soft_deny, hard_deny. Check for typos.',
+              autoFixable: false,
+              details: { key: 'autoMode', subKey, problem: 'unknown-subkey' },
+            }));
+            continue;
+          }
+          const val = am[subKey];
+          const isStringArray = Array.isArray(val) && val.every(e => typeof e === 'string');
+          if (!isStringArray) {
+            findings.push(finding({
+              scanner: SCANNER,
+              severity: SEVERITY.medium,
+              title: `autoMode.${subKey} must be an array of strings`,
+              description: `${file.relPath}: "autoMode.${subKey}" must be an array of prose-rule strings (the literal "$defaults" is allowed), got ${Array.isArray(val) ? 'an array with a non-string entry' : typeof val}.`,
+              file: file.absPath,
+              evidence: `autoMode.${subKey}: ${JSON.stringify(val)}`,
+              recommendation: `Set "autoMode.${subKey}" to an array of strings, e.g. ["$defaults"].`,
+              autoFixable: false,
+              details: { key: 'autoMode', subKey, problem: 'not-string-array' },
+            }));
+          }
+        }
+      }
+      // Dead-config: shared project settings (.claude/settings.json) is not read.
+      if (file.scope === 'project') {
+        findings.push(finding({
+          scanner: SCANNER,
+          severity: SEVERITY.low,
+          title: 'autoMode in shared project settings is ignored by Claude Code',
+          description: `${file.relPath}: Claude Code does not read "autoMode" from shared project settings (.claude/settings.json), so a checked-in repo cannot inject its own rules. This autoMode block has no effect where it is.`,
+          file: file.absPath,
+          evidence: 'autoMode in shared .claude/settings.json (project scope)',
+          recommendation: 'Move autoMode to user settings (~/.claude/settings.json), local settings (.claude/settings.local.json), or managed settings.',
+          autoFixable: false,
+          details: { key: 'autoMode', problem: 'shared-project-scope' },
+        }));
+      }
+    }
+
     // hooks checks (basic — detailed in hook-validator)
     if (parsed.hooks) {
       if (Array.isArray(parsed.hooks)) {

tests/fixtures/automode-nonobject/.claude/settings.local.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "autoMode": "on"
+}

tests/fixtures/automode-shared/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "autoMode": {
+    "environment": ["$defaults", "Org: acme"],
+    "hard_deny": ["$defaults"]
+  }
+}

tests/fixtures/automode-structure/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "autoMode": {
+    "environment": ["$defaults"],
+    "allow": "oops-not-an-array",
+    "soft_deny": ["ok", 7],
+    "bogus": ["x"]
+  }
+}

tests/scanners/settings-validator.test.mjs

@@ -208,3 +208,79 @@ describe('SET scanner — empty project', () => {
     assert.strictEqual(result.findings.length, 0);
   });
 });
+
+describe('SET scanner — autoMode validation (CA-SET-NNN)', () => {
+  // All autoMode findings have a title starting with "autoMode".
+  const AM_RE = /^autoMode/;
+  const amFindings = (result) => result.findings.filter(f => f.scanner === 'SET' && AM_RE.test(f.title || ''));
+
+  it('flags structural problems: wrong sub-key type, non-string array entry, unknown sub-key', async () => {
+    resetCounter();
+    // automode-structure/.claude/settings.local.json (scope=local → no dead-config):
+    // environment valid; allow not-array; soft_deny ["ok",7]; bogus unknown sub-key.
+    const path = resolve(FIXTURES, 'automode-structure');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    const am = amFindings(result);
+    const problems = am.map(f => f.details && f.details.problem).sort();
+    assert.deepEqual(
+      problems,
+      ['not-string-array', 'not-string-array', 'unknown-subkey'],
+      `Expected 2 not-string-array + 1 unknown-subkey, got ${am.map(f => f.title).join(' | ')}`
+    );
+    for (const f of am) {
+      assert.equal(f.severity, 'medium', `structure problem is medium: ${f.title}`);
+      assert.ok(/settings\.local\.json$/.test(f.file || ''), `points at the settings file: ${f.file}`);
+      assert.ok(f.details && f.details.key === 'autoMode', 'details.key === autoMode');
+    }
+  });
+
+  it('does NOT flag a valid string-array sub-key (incl. "$defaults")', async () => {
+    resetCounter();
+    const path = resolve(FIXTURES, 'automode-structure');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    // environment: ["$defaults"] is valid → must not appear.
+    const envFlagged = amFindings(result).some(f => /environment/.test(f.title || ''));
+    assert.equal(envFlagged, false, 'a valid string array (with $defaults) is not flagged');
+  });
+
+  it('flags autoMode that is not an object', async () => {
+    resetCounter();
+    const path = resolve(FIXTURES, 'automode-nonobject');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    const am = amFindings(result);
+    assert.equal(am.length, 1, `Expected one not-an-object finding, got ${am.map(f => f.title).join(' | ')}`);
+    assert.equal(am[0].details.problem, 'not-an-object');
+    assert.equal(am[0].severity, 'medium');
+  });
+
+  it('flags autoMode in shared project settings as dead config (and not in local scope)', async () => {
+    resetCounter();
+    // automode-shared/.claude/settings.json → scope=project → dead-config.
+    const sharedPath = resolve(FIXTURES, 'automode-shared');
+    const sharedResult = await scan(sharedPath, await discoverConfigFiles(sharedPath));
+    const dead = amFindings(sharedResult).filter(f => f.details && f.details.problem === 'shared-project-scope');
+    assert.equal(dead.length, 1, 'autoMode in shared .claude/settings.json is dead config');
+    assert.equal(dead[0].severity, 'low', 'dead-config is low severity');
+    // valid structure → no structure findings, only the dead-config one.
+    assert.equal(amFindings(sharedResult).length, 1, 'valid structure in shared scope yields only the dead-config finding');
+
+    // The same-shaped autoMode in LOCAL scope (automode-structure) must NOT be dead config.
+    resetCounter();
+    const localPath = resolve(FIXTURES, 'automode-structure');
+    const localResult = await scan(localPath, await discoverConfigFiles(localPath));
+    const localDead = amFindings(localResult).filter(f => f.details && f.details.problem === 'shared-project-scope');
+    assert.equal(localDead.length, 0, 'autoMode in settings.local.json is read by CC → not dead config');
+  });
+
+  it('does NOT flag a settings file without autoMode', async () => {
+    resetCounter();
+    // healthy-project has .claude/settings.json but no autoMode.
+    const path = resolve(FIXTURES, 'healthy-project');
+    const discovery = await discoverConfigFiles(path);
+    const result = await scan(path, discovery);
+    assert.equal(amFindings(result).length, 0, 'no autoMode key → no autoMode findings');
+  });
+});