@dalzoubi/dev-agents-sync 2.0.15 → 2.0.17

package/tests/e2e/steering-hooks-flow.test.mjs

@@ -0,0 +1,654 @@
+/**
+ * tests/e2e/steering-hooks-flow.test.mjs
+ *
+ * Slice S5 — Docs + e2e + back-compat.
+ * Spec: docs/specs/260616-agent-steering-and-hooks/
+ *
+ * Approach: node:test file in tests/e2e/ — matches the established pattern for
+ * this project (claudeMd-injection.test.mjs, readme-coverage.test.mjs, etc.).
+ * The e2e suite is `node --test tests/e2e/*.test.mjs` per `npm run test:e2e`.
+ *
+ * What these tests prove (cross-slice integration, NOT re-testing S1–S4 units):
+ *
+ *  E1. INTEGRATED FLOW — init → update → check in sequence:
+ *    E1a. .claude/steering/{decisions,glossary,architecture}.md present after init.
+ *    E1b. Steering files have no managed-by marker after init (consumer-owned).
+ *    E1c. Steering files are not referenced in the lockfile after init.
+ *    E1d. .claude/hooks/{steering-injector,managed-file-guard,uncommitted-check}.sh
+ *         present, executable, and lockfile-tracked after update.
+ *    E1e. .claude/settings.json contains a registration for each of the three hooks
+ *         after update.
+ *    E1f. A SECOND update call produces byte-identical hooks and settings.json
+ *         (idempotent no-op across the whole integrated path).
+ *    E1g. check exits 0 on the fully-synced tree (steering + hooks + settings in place).
+ *
+ *  E2. OLD-LOCKFILE UPGRADE (§8 back-compat e2e):
+ *    E2a. update against a pre-hooks lockfile (no `hooks` field) does not throw.
+ *    E2b. After the upgrade, hook scripts are installed.
+ *    E2c. After the upgrade, settings.json is wired with the three hooks.
+ *    E2d. After the upgrade, the lockfile references the installed hooks.
+ *    E2e. check exits 0 on the upgraded tree.
+ *
+ *  E3. README covers steering+hooks (cross-cutting doc criterion):
+ *    E3a. README mentions "steering" in the context of the init/update flow.
+ *    E3b. README mentions "hooks" and "settings.json" together.
+ *    E3c. README documents "--no-hooks-wiring".
+ *
+ * These tests are RED until the implement agent wires the behaviors described in
+ * S1 (steering seed), S3 (hook scripts in fetcher), and S4 (CLI install + settings
+ * merge) into the e2e integrated path.
+ *
+ * Test runner: `node --test packages/dev-agents-sync/tests/e2e/steering-hooks-flow.test.mjs`
+ * No third-party dependencies. All stateful tests use isolated tmp dirs.
+ *
+ * i18n/accessibility: N/A — CLI-only, no translated strings, no UI surface.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  statSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../../src/commands/init.mjs';
+import { runUpdate } from '../../src/commands/update.mjs';
+import { runCheck } from '../../src/commands/check.mjs';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, '..', 'fixtures', 'release-v1.0.0');
+const README_PATH = path.join(__dirname, '..', '..', 'README.md');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md'];
+
+const HOOK_FILES = [
+  'steering-injector.sh',
+  'managed-file-guard.sh',
+  'uncommitted-check.sh',
+];
+
+/**
+ * Events paired with the hook script that handles each one. Used to assert
+ * that settings.json wiring is complete without hard-coding the internal
+ * shape (the implement agent owns that).
+ */
+const HOOK_EVENT_PAIRS = [
+  { event: 'SessionStart', script: 'steering-injector.sh' },
+  { event: 'PostToolUse', script: 'managed-file-guard.sh' },
+  { event: 'Stop', script: 'uncommitted-check.sh' },
+];
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+const LOCKFILE_NAME = '.dev-agents-sync.json';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers — same pattern as claudeMd-injection.test.mjs
+// ---------------------------------------------------------------------------
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/**
+ * Builds a fixture file map from the release-v1.0.0 fixture directory,
+ * extended with the three hook scripts that S3's build.mjs would emit.
+ * These use the shell-comment marker format for .sh files.
+ */
+function buildFixtureFileMap(targets = ['claude']) {
+  const map = {};
+  for (const target of targets) {
+    const targetDir = path.join(FIXTURE_DIR, target);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, target);
+  }
+
+  // Hook scripts injected as if emitted by S3's build pipeline.
+  // They carry the shell-comment marker (POSIX-sh format, not HTML).
+  map['claude/hooks/steering-injector.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# SessionStart: surface steering context.\n[ -d .claude/steering ] && cat .claude/steering/*.md 2>/dev/null >&2\nexit 0\n';
+  map['claude/hooks/managed-file-guard.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# PostToolUse: warn on managed-file edits.\nexit 0\n';
+  map['claude/hooks/uncommitted-check.sh'] =
+    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# Stop: remind about uncommitted work.\nexit 0\n';
+
+  return map;
+}
+
+function makeFixtureFetcher() {
+  return async (_repo, _tag, _token) => buildFixtureFileMap(['claude']);
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-e2e-steering-hooks-'));
+}
+
+// ---------------------------------------------------------------------------
+// Assertions helpers (readable error messages)
+// ---------------------------------------------------------------------------
+
+/**
+ * Asserts that settings.json at .claude/settings.json under consumerDir
+ * contains at least one hook registration referencing scriptName under eventName.
+ * Does NOT assert the exact shape — the implement agent owns that.
+ */
+function assertSettingsWired(consumerDir, eventName, scriptName) {
+  const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+  assert.ok(
+    existsSync(settingsPath),
+    `.claude/settings.json must exist after update (required by settings wiring for ${scriptName})`,
+  );
+
+  const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  const hooks = settings.hooks ?? {};
+
+  // Walk the hooks object and collect all commands.
+  const allCommands = [];
+  for (const entries of Object.values(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+      for (const h of hookList) {
+        if (typeof h.command === 'string') allCommands.push(h.command);
+      }
+    }
+  }
+
+  assert.ok(
+    allCommands.some((cmd) => cmd.includes(scriptName)),
+    `settings.json must contain a hook command referencing "${scriptName}" ` +
+    `(expected under event "${eventName}").\n` +
+    `All wired commands: ${JSON.stringify(allCommands, null, 2)}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Shared setup: write a minimal pre-initialized lockfile (no hooks section).
+// Mirrors the approach in hooks-cli-install.test.mjs's setupInitializedRepo.
+// ---------------------------------------------------------------------------
+
+function writePreHooksLockfile(consumerDir) {
+  const raw =
+    JSON.stringify(
+      {
+        $schema:
+          'https://raw.githubusercontent.com/dalzoubi/dev-agents/v1/schema/lockfile.schema.json',
+        source: 'github:dalzoubi/dev-agents',
+        range: '^1',
+        resolvedVersion: '1.0.0',
+        targets: ['claude'],
+        lastUpdated: '2026-01-01T00:00:00Z',
+        // Intentionally omits the `hooks` field — this is the pre-S4 format.
+      },
+      null,
+      2,
+    ) + '\n';
+  writeFileSync(path.join(consumerDir, LOCKFILE_NAME), raw, 'utf8');
+}
+
+/** Seeds the minimum managed-file that update needs to find in the consumer tree. */
+function seedManagedFile(consumerDir) {
+  const agentsDir = path.join(consumerDir, '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    path.join(agentsDir, 'define.md'),
+    readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+    'utf8',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// E1 — integrated init → update → check flow
+// ---------------------------------------------------------------------------
+
+describe('S5 E1 — integrated init → update → check flow', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // E1a — steering files present after init
+  it('E1a: init writes .claude/steering/{decisions,glossary,architecture}.md when absent', async () => {
+    // This is the INTEGRATED assertion: init as the first step of the full
+    // init → update → check sequence must produce the steering scaffold.
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    assert.ok(
+      existsSync(steeringDir),
+      '.claude/steering/ must exist after init in the integrated flow',
+    );
+
+    for (const file of STEERING_FILES) {
+      assert.ok(
+        existsSync(path.join(steeringDir, file)),
+        `init must write .claude/steering/${file} as the first step of the integrated flow`,
+      );
+    }
+  });
+
+  // E1b — steering files have no managed-by marker
+  it('E1b: init-seeded steering files carry no managed-by marker (consumer-owned)', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    for (const file of STEERING_FILES) {
+      const content = readFileSync(path.join(steeringDir, file), 'utf8');
+      assert.ok(
+        !content.includes('managed-by'),
+        `steering/${file} must NOT carry the managed-by marker — it is consumer-owned`,
+      );
+    }
+  });
+
+  // E1c — steering files not in lockfile after init
+  it('E1c: steering files are not referenced in the lockfile after init', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const raw = readFileSync(path.join(consumerDir, LOCKFILE_NAME), 'utf8');
+    assert.ok(
+      !raw.includes('steering/'),
+      `lockfile must not reference any steering/* path after init.\nLockfile content:\n${raw}`,
+    );
+  });
+
+  // E1d — hooks present, executable, lockfile-tracked after update
+  it('E1d: update installs executable, lockfile-tracked .claude/hooks/*.sh scripts', async () => {
+    // Run init first (step 1 of the integrated sequence).
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // Run update (step 2).
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      const absPath = path.join(hooksDir, file);
+
+      assert.ok(existsSync(absPath), `update must install .claude/hooks/${file}`);
+
+      const st = statSync(absPath);
+      assert.ok(
+        (st.mode & 0o111) !== 0,
+        `${file} must be executable after install (mode: 0o${st.mode.toString(8)})`,
+      );
+    }
+
+    // Lockfile must reference each installed hook script.
+    const raw = readFileSync(path.join(consumerDir, LOCKFILE_NAME), 'utf8');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        raw.includes(file),
+        `lockfile must reference ${file} (it is a lockfile-tracked managed file).\nLockfile:\n${raw}`,
+      );
+    }
+  });
+
+  // E1e — settings.json wired with all three hooks after update
+  it('E1e: .claude/settings.json is wired with registrations for all three hooks after update', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const { event, script } of HOOK_EVENT_PAIRS) {
+      assertSettingsWired(consumerDir, event, script);
+    }
+  });
+
+  // E1f — second update is a no-op (byte-identical hooks + settings)
+  it('E1f: a second update call is a byte-identical no-op (hooks + settings unchanged)', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const updateOpts = {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    };
+
+    // First update.
+    await runUpdate(consumerDir, updateOpts);
+
+    // Capture state after first update.
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    const hookSnapshots = {};
+    for (const file of HOOK_FILES) {
+      hookSnapshots[file] = readFileSync(path.join(hooksDir, file), 'utf8');
+    }
+    const settingsPath = path.join(consumerDir, '.claude', 'settings.json');
+    const settingsSnapshot = readFileSync(settingsPath, 'utf8');
+
+    // Second update — must be a no-op.
+    await runUpdate(consumerDir, updateOpts);
+
+    // Hooks must be byte-identical.
+    for (const file of HOOK_FILES) {
+      const after = readFileSync(path.join(hooksDir, file), 'utf8');
+      assert.equal(
+        after,
+        hookSnapshots[file],
+        `${file} must be byte-identical after a second update (integrated idempotency)`,
+      );
+    }
+
+    // settings.json must be byte-identical.
+    const settingsAfter = readFileSync(settingsPath, 'utf8');
+    assert.equal(
+      settingsAfter,
+      settingsSnapshot,
+      'settings.json must be byte-identical after a second update (idempotent merge)',
+    );
+  });
+
+  // E1g — check exits 0 after init → update
+  it('E1g: check exits 0 on the fully-synced tree (steering + hooks + settings in place)', async () => {
+    // Run the full init → update sequence.
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // check must exit 0 — all managed files (hooks) in sync.
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v2.0.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'check must exit 0 when init → update has been run and all managed files are in sync ' +
+      '(steering seeded, hooks installed, settings wired)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// E2 — old-lockfile upgrade (§8 back-compat) e2e
+// ---------------------------------------------------------------------------
+
+describe('S5 E2 — old-lockfile-without-hooks upgrade (§8 back-compat) e2e', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Sets up a consumer repo that looks like it was initialized with a pre-S4
+   * version of the CLI: lockfile present but with no `hooks` field, one
+   * managed agent file present on disk.
+   */
+  function setupPreHooksConsumer() {
+    writePreHooksLockfile(consumerDir);
+    seedManagedFile(consumerDir);
+  }
+
+  // E2a — update does not throw on a pre-hooks lockfile
+  it('E2a: update against a pre-hooks lockfile (no hooks field) does not throw', async () => {
+    setupPreHooksConsumer();
+
+    await assert.doesNotReject(
+      runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+      }),
+      'update must not throw when the lockfile has no hooks section (additive §8 upgrade)',
+    );
+  });
+
+  // E2b — hook scripts are installed after the upgrade
+  it('E2b: hook scripts are installed after upgrading a pre-hooks lockfile', async () => {
+    setupPreHooksConsumer();
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        existsSync(path.join(hooksDir, file)),
+        `${file} must be installed after upgrading a pre-hooks lockfile`,
+      );
+    }
+  });
+
+  // E2c — settings.json is wired after the upgrade
+  it('E2c: settings.json is wired with hook registrations after upgrading a pre-hooks lockfile', async () => {
+    setupPreHooksConsumer();
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    for (const { event, script } of HOOK_EVENT_PAIRS) {
+      assertSettingsWired(consumerDir, event, script);
+    }
+  });
+
+  // E2d — lockfile references installed hooks after upgrade
+  it('E2d: upgraded lockfile references the installed hook scripts (additive §8 upgrade)', async () => {
+    setupPreHooksConsumer();
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const raw = readFileSync(path.join(consumerDir, LOCKFILE_NAME), 'utf8');
+    for (const file of HOOK_FILES) {
+      assert.ok(
+        raw.includes(file),
+        `upgraded lockfile must reference ${file} (additive hooks section).\nLockfile:\n${raw}`,
+      );
+    }
+  });
+
+  // E2e — check exits 0 after upgrade
+  it('E2e: check exits 0 after upgrading a pre-hooks lockfile (upgrade is clean)', async () => {
+    setupPreHooksConsumer();
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcher(),
+        availableTags: ['v2.0.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'check must exit 0 after upgrading a pre-hooks lockfile — the upgrade must leave a ' +
+      'fully-synced tree with no drift',
+    );
+  });
+
+  // E2f — old-lockfile steering also seeded during upgrade
+  it('E2f: update on a pre-hooks lockfile also seeds steering scaffold when absent', async () => {
+    // This verifies cross-slice interaction: S1 (steering seed) + §8 (old lockfile)
+    // work together — the upgrade path also runs the seed-if-absent logic.
+    setupPreHooksConsumer();
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'],
+    });
+
+    const steeringDir = path.join(consumerDir, '.claude', 'steering');
+    assert.ok(
+      existsSync(steeringDir),
+      '.claude/steering/ must be seeded during upgrade from a pre-hooks lockfile',
+    );
+    for (const file of STEERING_FILES) {
+      assert.ok(
+        existsSync(path.join(steeringDir, file)),
+        `steering/${file} must be seeded during the pre-hooks upgrade`,
+      );
+    }
+
+    // And steering still must not land in the lockfile.
+    const raw = readFileSync(path.join(consumerDir, LOCKFILE_NAME), 'utf8');
+    assert.ok(
+      !raw.includes('steering/'),
+      `lockfile must not reference steering/* even after pre-hooks upgrade.\nLockfile:\n${raw}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// E3 — README documents steering and hooks
+// ---------------------------------------------------------------------------
+
+describe('S5 E3 — README documents steering layer and hooks', () => {
+  function readReadme() {
+    assert.ok(
+      existsSync(README_PATH),
+      `README.md must exist at ${README_PATH}`,
+    );
+    return readFileSync(README_PATH, 'utf8');
+  }
+
+  // E3a — README mentions "steering" near init/update
+  it('E3a: README mentions "steering" in the context of the init/update flow', () => {
+    const content = readReadme();
+
+    // Must mention steering (the scaffold) somewhere.
+    assert.ok(
+      content.includes('steering'),
+      'README.md must mention "steering" to document the steering scaffold feature',
+    );
+
+    // Must also mention the three file names or "decisions", "glossary", "architecture"
+    // so consumers know what files will be seeded.
+    const mentionsSteeringFiles =
+      content.includes('decisions.md') ||
+      content.includes('glossary.md') ||
+      content.includes('architecture.md') ||
+      (content.includes('decisions') && content.includes('glossary'));
+
+    assert.ok(
+      mentionsSteeringFiles,
+      'README.md must document at least one steering file name ' +
+      '(decisions.md, glossary.md, or architecture.md) ' +
+      'so consumers understand what the scaffold contains',
+    );
+  });
+
+  // E3b — README mentions "hooks" and "settings.json" together
+  it('E3b: README mentions both "hooks" and "settings.json" as part of the wiring documentation', () => {
+    const content = readReadme();
+
+    assert.ok(
+      content.includes('hooks'),
+      'README.md must mention "hooks" to document the event-driven hook scripts',
+    );
+
+    assert.ok(
+      content.includes('settings.json'),
+      'README.md must mention "settings.json" to document the auto-wiring feature',
+    );
+
+    // Both must appear in some proximity (within 1500 chars of each other).
+    const hooksIdx = content.indexOf('hooks');
+    const settingsIdx = content.indexOf('settings.json');
+    assert.ok(
+      Math.abs(hooksIdx - settingsIdx) < 1500,
+      'README.md must describe "hooks" and "settings.json" in proximity ' +
+      `(found hooks at ${hooksIdx}, settings.json at ${settingsIdx}, distance: ${Math.abs(hooksIdx - settingsIdx)})`,
+    );
+  });
+
+  // E3c — README documents "--no-hooks-wiring" opt-out
+  it('E3c: README documents the --no-hooks-wiring opt-out flag', () => {
+    const content = readReadme();
+
+    assert.ok(
+      content.includes('--no-hooks-wiring'),
+      'README.md must document the "--no-hooks-wiring" flag so consumers know how ' +
+      'to install hook scripts without auto-wiring settings.json',
+    );
+  });
+});