feat(config-audit): self-audit --check-readme flag (v5 F6) [skip-docs]

Filesystem counts are the source of truth; README badges parsed via
line-anchored substring (badge/<kind>-<N>-...). Emits readmeCheck object
with counts/badges/mismatches.

CLI: node scanners/self-audit.mjs --check-readme [--json]
API: runSelfAudit({ checkReadme: true }) → result.readmeCheck
Helper: checkReadmeBadges(pluginDir) for per-fixture testing

New fixture: readme-desynced/ (commands/foo + bar, README claims 1).

Note: alpha phase does NOT require result.readmeCheck.passed === true.
Self-test of real plugin currently fails (scanners 10 vs 9, tests 31 vs 543);
will be reconciled in Session 5 Step 28 (README sync).

582 → 586 tests, all green.

plugins/config-audit/tests/fixtures/readme-desynced/README.md

@@ -0,0 +1,7 @@
+# readme-desynced fixture
+
+Fixture for v5 F6 self-audit --check-readme. The badge below claims 1 command,
+but `commands/` actually contains 2 (foo, bar). The check should flag this as
+a low-severity mismatch.
+
+![Commands](https://img.shields.io/badge/commands-1-green)

plugins/config-audit/tests/fixtures/readme-desynced/commands/bar.md

@@ -0,0 +1,6 @@
+---
+name: bar
+description: Bar command for the readme-desynced fixture
+---
+
+# Bar command body

plugins/config-audit/tests/fixtures/readme-desynced/commands/foo.md

@@ -0,0 +1,6 @@
+---
+name: foo
+description: Foo command for the readme-desynced fixture
+---
+
+# Foo command body

plugins/config-audit/tests/scanners/self-audit.test.mjs

@@ -1,6 +1,11 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { runSelfAudit, formatSelfAudit } from '../../scanners/self-audit.mjs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runSelfAudit, formatSelfAudit, checkReadmeBadges } from '../../scanners/self-audit.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const FIXTURES = resolve(__dirname, '../fixtures');
 
 // ========================================
 // runSelfAudit
@@ -69,6 +74,45 @@ describe('runSelfAudit — fixture filtering', () => {
   });
 });
 
+// ========================================
+// --check-readme (v5 F6)
+// ========================================
+describe('checkReadmeBadges (v5 F6)', () => {
+  it('detects mismatch in readme-desynced fixture', async () => {
+    const path = resolve(FIXTURES, 'readme-desynced');
+    const result = await checkReadmeBadges(path);
+    assert.equal(typeof result.passed, 'boolean');
+    assert.equal(result.passed, false, 'expected mismatch');
+    const cmd = result.mismatches.find(m => m.kind === 'commands');
+    assert.ok(cmd, `expected commands mismatch; got: ${JSON.stringify(result.mismatches)}`);
+    assert.equal(cmd.expected, 2, `filesystem count should be 2`);
+    assert.equal(cmd.foundInReadme, 1, `README badge claims 1`);
+  });
+
+  it('returns counts and badges objects', async () => {
+    const path = resolve(FIXTURES, 'readme-desynced');
+    const result = await checkReadmeBadges(path);
+    assert.equal(typeof result.counts, 'object');
+    assert.equal(typeof result.badges, 'object');
+    assert.equal(result.counts.commands, 2);
+    assert.equal(result.badges.commands, 1);
+  });
+});
+
+describe('runSelfAudit({ checkReadme: true }) (v5 F6)', () => {
+  it('attaches readmeCheck object to the result', async () => {
+    const result = await runSelfAudit({ checkReadme: true });
+    assert.ok(result.readmeCheck, 'expected result.readmeCheck');
+    assert.equal(typeof result.readmeCheck.passed, 'boolean');
+    // Do NOT assert passed === true during alpha/beta phases — see plan Step 16.
+  });
+
+  it('omits readmeCheck when flag not set', async () => {
+    const result = await runSelfAudit();
+    assert.equal(result.readmeCheck, undefined);
+  });
+});
+
 // ========================================
 // formatSelfAudit
 // ========================================