@dalzoubi/dev-agents-sync 2.0.6 → 2.0.8

package/tests/codex-init-check.test.mjs

@@ -0,0 +1,823 @@
+/**
+ * tests/codex-init-check.test.mjs
+ *
+ * Regression guards (slice: codex-init-check) for the init + check behavior of
+ * the codex target. The behavior is delivered by the build emitter (S1) and the
+ * writer/lockfile wiring (S2): `init.mjs` passes explicit `--targets` through
+ * without an ALL_TARGETS gate, and `codex` resolves via TARGET_PREFIX +
+ * filterFileMapByTargets — so this slice required no production change and these
+ * tests lock the contract against future regressions.
+ *
+ * Contract:
+ *  - `--targets codex` is an accepted, selectable value (not auto-detected).
+ *  - init writes <root>/.agents/skills/<agent>/SKILL.md and <root>/AGENTS.md
+ *    for all six agents, each carrying the managed marker.
+ *  - init records `codex` in the lockfile targets array.
+ *  - init scopes correctly: only files whose FileMap key prefix matches a
+ *    selected target are written. `--targets claude` must NOT write codex files
+ *    and vice versa.
+ *  - init leaves a pre-existing unmanaged sibling .agents/ file untouched.
+ *  - Collision: a pre-existing UNMANAGED <root>/AGENTS.md (no marker) causes
+ *    refusal (exit 1); --force allows the overwrite. Same for SKILL.md.
+ *  - check drift: deleting or modifying a codex file reports drift (exit 1);
+ *    a clean tree is in-sync (exit 0); a non-codex sibling .agents/ file is
+ *    NEVER reported as drift.
+ *  - autoDetectTargets does NOT include `codex` — it is opt-in only.
+ *    No filesystem signal (not even .agents/ existing) triggers codex selection.
+ *
+ * The six agent names used by the build emitter (verified from .agents/agents/):
+ *   analyze, define, implement, supervise, test, validate
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { runInit } from '../src/commands/init.mjs';
+import { runCheck } from '../src/commands/check.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+import { hasMarker } from '../src/marker.mjs';
+
+// ---------------------------------------------------------------------------
+// Fixture FileMap
+//
+// A minimal FileMap that includes codex keys for all six agents + AGENTS.md,
+// plus a couple of claude keys — so prefix-scoping is actually exercised.
+//
+// Key shape mirrors what the build emitter (S1) produces and what the writer
+// (S2) normalizes:
+//   "codex/.agents/skills/<agent>/SKILL.md"  — consumer path: .agents/skills/<agent>/SKILL.md
+//   "codex/AGENTS.md"                         — consumer path: AGENTS.md
+//   "claude/agents/define.md"                 — consumer path: .claude/agents/define.md
+// ---------------------------------------------------------------------------
+
+const SIX_AGENTS = ['analyze', 'define', 'implement', 'supervise', 'test', 'validate'];
+
+const MANAGED_MARKER = '<!-- managed-by: dev-agents-sync v1.0.0 -->';
+
+function makeCodexSkillContent(agent) {
+  return `${MANAGED_MARKER}\n# ${agent} Skill\n\nYou are the ${agent} agent.\n`;
+}
+
+function makeCodexAgentsMd() {
+  return `${MANAGED_MARKER}\n# Agent Skills\n\nThis repo contains the following agent skills.\n`;
+}
+
+function makeClaudeAgentContent(agent) {
+  return `---\nname: "${agent}"\n---\n${MANAGED_MARKER}\nYou are the ${agent} agent for Claude.\n`;
+}
+
+/**
+ * Builds a fixture FileMap containing:
+ *   - codex keys for all six agents + AGENTS.md
+ *   - claude keys for define + test agents
+ *
+ * This is the canonical "full" FileMap used as the fetcher response for most tests.
+ */
+function buildFullFixtureFileMap() {
+  const map = {};
+  for (const agent of SIX_AGENTS) {
+    map[`codex/.agents/skills/${agent}/SKILL.md`] = makeCodexSkillContent(agent);
+  }
+  map['codex/AGENTS.md'] = makeCodexAgentsMd();
+  map['claude/agents/define.md'] = makeClaudeAgentContent('define');
+  map['claude/agents/test.md'] = makeClaudeAgentContent('test');
+  return map;
+}
+
+function makeFullFetcher() {
+  return async (_repo, _tag, _token) => buildFullFixtureFileMap();
+}
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-codex-ic-test-'));
+}
+
+// ---------------------------------------------------------------------------
+// 1. init --targets codex writes the codex file set
+// ---------------------------------------------------------------------------
+
+describe('init --targets codex — writes codex file set', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // RED: `codex` is not in ALL_TARGETS in init.mjs — normalizeTargets passes it
+  // through for explicit arrays, but runInit would still call filterFileMapByTargets
+  // which looks at the prefix. Once S2 wired writer, this may partially work.
+  // However the key gate is that init accepts 'codex' as a valid target string
+  // without throwing "unknown target" — currently it passes through because
+  // normalizeTargets does NOT validate against ALL_TARGETS for explicit arrays.
+  // The actual RED will appear at writeLockfile (VALID_TARGETS) if codex is absent
+  // there — but S2 already added it. So let's verify the actual behavior.
+  it('writes SKILL.md for all six agents under <root>/.agents/skills/', async () => {
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const agent of SIX_AGENTS) {
+      const skillPath = path.join(consumerDir, '.agents', 'skills', agent, 'SKILL.md');
+      assert.ok(
+        existsSync(skillPath),
+        `SKILL.md for agent "${agent}" must be written at .agents/skills/${agent}/SKILL.md`,
+      );
+    }
+  });
+
+  it('writes AGENTS.md at <root>/AGENTS.md (not nested in a subdir)', async () => {
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    assert.ok(existsSync(agentsMdPath), 'AGENTS.md must be written at the consumer root');
+    // Must not be nested under a subdir like .codex/ or .agents/
+    const relative = path.relative(consumerDir, agentsMdPath);
+    assert.equal(relative, 'AGENTS.md', 'AGENTS.md must be directly under consumer root');
+  });
+
+  it('each written codex file contains the managed-by marker', async () => {
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const agent of SIX_AGENTS) {
+      const skillPath = path.join(consumerDir, '.agents', 'skills', agent, 'SKILL.md');
+      const content = readFileSync(skillPath, 'utf8');
+      assert.ok(
+        hasMarker(content),
+        `SKILL.md for agent "${agent}" must contain the managed-by marker`,
+      );
+    }
+
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    const content = readFileSync(agentsMdPath, 'utf8');
+    assert.ok(hasMarker(content), 'AGENTS.md must contain the managed-by marker');
+  });
+
+  it('records codex in the lockfile targets', async () => {
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+    const lockfile = JSON.parse(readFileSync(lockfilePath, 'utf8'));
+    assert.ok(
+      Array.isArray(lockfile.targets) && lockfile.targets.includes('codex'),
+      `lockfile.targets must include "codex", got: ${JSON.stringify(lockfile.targets)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. init scoping — codex and claude are independent targets
+// ---------------------------------------------------------------------------
+
+describe('init --targets scoping — codex and claude are independent', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // GREEN (expected to pass already, since filterFileMapByTargets in init.mjs
+  // scopes by prefix and `claude` prefix won't match codex keys).
+  it('--targets claude does NOT write .agents/skills/ (codex files excluded)', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const agentsSkillsDir = path.join(consumerDir, '.agents', 'skills');
+    assert.ok(
+      !existsSync(agentsSkillsDir),
+      '.agents/skills/ must NOT exist when only claude target is selected',
+    );
+  });
+
+  // GREEN: same for AGENTS.md — it has prefix "codex", not "claude"
+  it('--targets claude does NOT write AGENTS.md at consumer root', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    assert.ok(
+      !existsSync(agentsMdPath),
+      'AGENTS.md must NOT be written when only claude target is selected',
+    );
+  });
+
+  // RED: `codex` key is blocked from filterFileMapByTargets unless 'codex' ∈ resolvedTargets.
+  // When --targets codex, claude prefix keys must be excluded.
+  it('--targets codex does NOT write .claude/ (claude files excluded)', async () => {
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.claude')),
+      '.claude/ must NOT exist when only codex target is selected',
+    );
+  });
+
+  // RED: both targets together write both sets of files
+  it('--targets claude,codex writes both .claude/ and codex files', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude', 'codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude')),
+      '.claude/ must exist when claude target is included',
+    );
+    assert.ok(
+      existsSync(path.join(consumerDir, '.agents', 'skills', 'define', 'SKILL.md')),
+      '.agents/skills/define/SKILL.md must exist when codex target is included',
+    );
+    assert.ok(
+      existsSync(path.join(consumerDir, 'AGENTS.md')),
+      'AGENTS.md must exist when codex target is included',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. init leaves pre-existing unmanaged sibling .agents/ files untouched
+// ---------------------------------------------------------------------------
+
+describe('init --targets codex — unmanaged sibling .agents/ file untouched', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // GREEN: writeManagedFile only writes paths in the FileMap; it never deletes.
+  // There is no cleanup/uninstall logic. This test locks that no-cleanup contract.
+  it('a pre-existing .agents/skills/my-own-skill.md (no marker) remains untouched after init', async () => {
+    // Seed a custom skill file that init must never manage or delete
+    const customSkillDir = path.join(consumerDir, '.agents', 'skills');
+    mkdirSync(customSkillDir, { recursive: true });
+    const customSkillPath = path.join(customSkillDir, 'my-own-skill.md');
+    const customContent = '# My Custom Skill\nNo managed-by marker here.';
+    writeFileSync(customSkillPath, customContent, 'utf8');
+
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(customSkillPath), 'custom skill file must still exist after init');
+    const afterContent = readFileSync(customSkillPath, 'utf8');
+    assert.equal(
+      afterContent,
+      customContent,
+      'custom skill file content must be byte-identical after init (init must not touch it)',
+    );
+  });
+
+  // GREEN: no cleanup on re-init either — the file stays if init is run twice
+  it('a pre-existing .agents/ custom file survives a second init run (no cleanup on overwrite)', async () => {
+    const customSkillDir = path.join(consumerDir, '.agents', 'skills');
+    mkdirSync(customSkillDir, { recursive: true });
+    const customSkillPath = path.join(customSkillDir, 'my-own-skill.md');
+    const customContent = '# My Custom Skill\nNo managed-by marker here.';
+    writeFileSync(customSkillPath, customContent, 'utf8');
+
+    // Run init twice
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+    await runInit(consumerDir, {
+      targets: ['codex'],
+      force: true,
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(existsSync(customSkillPath), 'custom skill file must survive a second init run');
+    const afterContent = readFileSync(customSkillPath, 'utf8');
+    assert.equal(afterContent, customContent, 'content must be unchanged after second init run');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Collision refusal — pre-existing unmanaged codex target files
+// ---------------------------------------------------------------------------
+
+describe('init --targets codex — collision refusal for unmanaged files', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // GREEN: writeManagedFile already refuses unmarked files at any path.
+  // The collision check in init.mjs does the same. These tests pin the
+  // codex-specific collision paths are respected — not new logic, but a
+  // regression guard that the codex path flows through the existing collision
+  // code (which it will once codex files are writable after S3 init change).
+  it('refuses to overwrite an unmanaged AGENTS.md (no marker) with exit code 1', async () => {
+    // Pre-seed an unmanaged AGENTS.md at the consumer root
+    writeFileSync(path.join(consumerDir, 'AGENTS.md'), '# My custom AGENTS.md\nNo marker.', 'utf8');
+
+    let caughtError;
+    try {
+      await runInit(consumerDir, {
+        targets: ['codex'],
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      caughtError = err;
+    }
+
+    assert.ok(caughtError, 'init must throw when an unmanaged AGENTS.md collision exists');
+    assert.equal(
+      caughtError.exitCode,
+      1,
+      `collision must produce exit code 1, got: ${caughtError.exitCode}`,
+    );
+    assert.ok(
+      caughtError.message.toLowerCase().includes('unmanaged') ||
+        caughtError.message.toLowerCase().includes('marker') ||
+        caughtError.message.toLowerCase().includes('force'),
+      `collision error must mention unmanaged/marker/force, got: ${caughtError.message}`,
+    );
+  });
+
+  it('collision error for AGENTS.md names the conflicting file path', async () => {
+    writeFileSync(path.join(consumerDir, 'AGENTS.md'), '# Unmanaged', 'utf8');
+
+    let errorMessage = '';
+    try {
+      await runInit(consumerDir, {
+        targets: ['codex'],
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      errorMessage = err.message;
+    }
+
+    assert.ok(
+      errorMessage.includes('AGENTS.md') || errorMessage.includes('codex/AGENTS.md'),
+      `collision error must name the conflicting path, got: ${errorMessage}`,
+    );
+  });
+
+  it('refuses to overwrite an unmanaged SKILL.md with exit code 1', async () => {
+    // Pre-seed an unmanaged SKILL.md at the define skill path
+    const skillDir = path.join(consumerDir, '.agents', 'skills', 'define');
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(path.join(skillDir, 'SKILL.md'), '# My custom define skill\nNo marker.', 'utf8');
+
+    let caughtError;
+    try {
+      await runInit(consumerDir, {
+        targets: ['codex'],
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      caughtError = err;
+    }
+
+    assert.ok(caughtError, 'init must throw when an unmanaged SKILL.md collision exists');
+    assert.equal(
+      caughtError.exitCode,
+      1,
+      `collision must produce exit code 1, got: ${caughtError.exitCode}`,
+    );
+  });
+
+  it('--force overwrites an unmanaged AGENTS.md', async () => {
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    writeFileSync(agentsMdPath, '# Unmanaged AGENTS.md\nNo marker.', 'utf8');
+
+    await assert.doesNotReject(
+      runInit(consumerDir, {
+        targets: ['codex'],
+        force: true,
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+      'init with --force must succeed even when an unmanaged AGENTS.md exists',
+    );
+
+    const written = readFileSync(agentsMdPath, 'utf8');
+    assert.ok(
+      hasMarker(written),
+      'AGENTS.md written with --force must now contain the managed-by marker',
+    );
+  });
+
+  it('--force overwrites an unmanaged SKILL.md', async () => {
+    const skillDir = path.join(consumerDir, '.agents', 'skills', 'define');
+    mkdirSync(skillDir, { recursive: true });
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    writeFileSync(skillPath, '# Unmanaged define skill\nNo marker.', 'utf8');
+
+    await assert.doesNotReject(
+      runInit(consumerDir, {
+        targets: ['codex'],
+        force: true,
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    const written = readFileSync(skillPath, 'utf8');
+    assert.ok(hasMarker(written), 'SKILL.md written with --force must contain the managed-by marker');
+  });
+
+  it('overwrites a previously managed codex file (already has marker) without --force', async () => {
+    // A file that already carries the managed marker is safe to overwrite — no --force needed.
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    writeFileSync(agentsMdPath, `${MANAGED_MARKER}\n# Old AGENTS.md\n`, 'utf8');
+
+    await assert.doesNotReject(
+      runInit(consumerDir, {
+        targets: ['codex'],
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+      'init must not throw when an already-managed AGENTS.md exists',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. check drift for codex target
+// ---------------------------------------------------------------------------
+
+describe('check — codex target drift detection', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Sets up a consumer dir that has previously run init with the codex target.
+   * Writes the lockfile and materializes all codex files to the expected paths.
+   */
+  function setupCodexConsumer(dir, opts = {}) {
+    const { resolvedVersion = '1.2.0' } = opts;
+
+    writeLockfile(dir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion,
+      targets: ['codex'],
+      lastUpdated: '2026-06-07T00:00:00Z',
+    });
+
+    // Write the expected codex files so the initial state is in-sync
+    for (const agent of SIX_AGENTS) {
+      const skillDir = path.join(dir, '.agents', 'skills', agent);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(
+        path.join(skillDir, 'SKILL.md'),
+        makeCodexSkillContent(agent),
+        'utf8',
+      );
+    }
+    writeFileSync(path.join(dir, 'AGENTS.md'), makeCodexAgentsMd(), 'utf8');
+  }
+
+  // GREEN: check uses filterFileMapByTargets which already scopes by prefix.
+  // With `codex` in lockfile targets, codex keys from the fetcher will be
+  // included in the check. A clean tree is in-sync.
+  it('exits 0 (in-sync) when all codex files match expected content', async () => {
+    setupCodexConsumer(consumerDir);
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(exitCode, 0, 'check must exit 0 when all codex files are in sync');
+  });
+
+  // GREEN: deletion drift is detected for any target once it's in the lockfile.
+  it('exits 1 and reports <missing> when a SKILL.md is deleted', async () => {
+    setupCodexConsumer(consumerDir);
+
+    // Delete one SKILL.md to simulate deletion drift
+    const defineSkillPath = path.join(consumerDir, '.agents', 'skills', 'define', 'SKILL.md');
+    rmSync(defineSkillPath);
+
+    let exitCode;
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+      errorMessage = err.message;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when a codex SKILL.md is missing');
+    assert.ok(
+      errorMessage.includes('<missing>'),
+      `drift message must mark the file as missing, got: ${errorMessage}`,
+    );
+    assert.ok(
+      errorMessage.includes('define') || errorMessage.includes('SKILL.md'),
+      `drift message must name the offending path, got: ${errorMessage}`,
+    );
+  });
+
+  // GREEN: content drift — file exists but content differs from expected
+  it('exits 1 when a SKILL.md has been locally modified (content drift)', async () => {
+    setupCodexConsumer(consumerDir);
+
+    const defineSkillPath = path.join(consumerDir, '.agents', 'skills', 'define', 'SKILL.md');
+    const original = readFileSync(defineSkillPath, 'utf8');
+    writeFileSync(defineSkillPath, original + '\n\n# Someone added this locally.', 'utf8');
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when a codex SKILL.md has drifted content');
+  });
+
+  // GREEN: drift detected when AGENTS.md is deleted
+  it('exits 1 and reports <missing> when AGENTS.md is deleted', async () => {
+    setupCodexConsumer(consumerDir);
+
+    rmSync(path.join(consumerDir, 'AGENTS.md'));
+
+    let exitCode;
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+      errorMessage = err.message;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when AGENTS.md is missing');
+    assert.ok(
+      errorMessage.includes('<missing>'),
+      `drift message must mark AGENTS.md as missing, got: ${errorMessage}`,
+    );
+  });
+
+  // GREEN: content drift for AGENTS.md
+  it('exits 1 when AGENTS.md has been locally modified (content drift)', async () => {
+    setupCodexConsumer(consumerDir);
+
+    const agentsMdPath = path.join(consumerDir, 'AGENTS.md');
+    const original = readFileSync(agentsMdPath, 'utf8');
+    writeFileSync(agentsMdPath, original + '\n\n# Extra section added locally.', 'utf8');
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'check must exit 1 when AGENTS.md content has drifted');
+  });
+
+  // GREEN (critical contract): a non-codex sibling .agents/ file is NEVER reported
+  // as drift. check only looks at paths in the scoped FileMap — unmanaged siblings
+  // are invisible to it.
+  it('does NOT report drift for an unmanaged .agents/ sibling file', async () => {
+    setupCodexConsumer(consumerDir);
+
+    // Seed a sibling file that is not in the codex FileMap
+    const siblingPath = path.join(consumerDir, '.agents', 'skills', 'my-custom-skill.md');
+    writeFileSync(siblingPath, '# My own custom skill — not in FileMap', 'utf8');
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'check must exit 0 and must NOT report an unmanaged .agents/ sibling as drift',
+    );
+  });
+
+  // GREEN: check only checks the targets recorded in the lockfile.
+  // With targets: ['codex'], claude files are invisible to check.
+  it('does NOT report drift for unwritten .claude/ files when lockfile targets is only codex', async () => {
+    setupCodexConsumer(consumerDir);
+    // .claude/ does not exist — and it shouldn't be flagged as drift
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'check must NOT report missing .claude/ files when targets is only ["codex"]',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Opt-in only — autoDetectTargets must never include codex
+// ---------------------------------------------------------------------------
+
+describe('autoDetectTargets — codex is never auto-selected', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  // GREEN: .agents/ is a shared directory (consumer may own it for their own skills).
+  // Its presence must NOT be interpreted as a codex opt-in signal.
+  it('auto-detect does NOT select codex even when .agents/ exists in the consumer repo', async () => {
+    // Pre-create a .agents/ directory — this must NOT trigger codex selection
+    mkdirSync(path.join(consumerDir, '.agents', 'skills'), { recursive: true });
+    writeFileSync(
+      path.join(consumerDir, '.agents', 'skills', 'my-skill.md'),
+      '# My skill',
+      'utf8',
+    );
+
+    // Run init in auto mode (targets: 'auto') — should not select codex
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+    const lockfile = JSON.parse(readFileSync(lockfilePath, 'utf8'));
+    assert.ok(
+      !lockfile.targets.includes('codex'),
+      `auto-detect must not include "codex" when only .agents/ exists, got: ${JSON.stringify(lockfile.targets)}`,
+    );
+  });
+
+  // GREEN: neither .claude nor .cursor, neither .codex — auto falls back to ALL_TARGETS
+  // (currently ['claude','cursor']). Codex must not be in ALL_TARGETS either.
+  it('auto-detect fallback (no .claude/ or .cursor/) does NOT include codex', async () => {
+    // Empty consumer dir — no IDE dirs at all
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+    const lockfile = JSON.parse(readFileSync(lockfilePath, 'utf8'));
+    assert.ok(
+      !lockfile.targets.includes('codex'),
+      `auto-detect fallback must not include "codex", got: ${JSON.stringify(lockfile.targets)}`,
+    );
+  });
+
+  // GREEN: .claude/ exists → auto picks claude only; still no codex
+  it('auto-detect picks only claude when .claude/ exists — still no codex', async () => {
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+    mkdirSync(path.join(consumerDir, '.agents', 'skills'), { recursive: true });
+
+    await runInit(consumerDir, {
+      targets: 'auto',
+      fetcher: makeFullFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const lockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+    const lockfile = JSON.parse(readFileSync(lockfilePath, 'utf8'));
+    assert.deepEqual(
+      lockfile.targets,
+      ['claude'],
+      `auto-detect must pick only claude when .claude/ exists, got: ${JSON.stringify(lockfile.targets)}`,
+    );
+    assert.ok(
+      !lockfile.targets.includes('codex'),
+      'auto-detect must not include codex even when .agents/ also exists',
+    );
+  });
+
+  // GREEN: explicit --targets codex works (user opted in) — different from auto
+  it('explicit --targets codex is accepted (opt-in path, not auto)', async () => {
+    let caughtError;
+    try {
+      await runInit(consumerDir, {
+        targets: ['codex'],
+        fetcher: makeFullFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    } catch (err) {
+      caughtError = err;
+    }
+
+    // Must not throw a "no targets" or "unknown target" error
+    assert.equal(
+      caughtError,
+      undefined,
+      `--targets codex (explicit opt-in) must not throw, got: ${caughtError?.message}`,
+    );
+
+    const lockfilePath = path.join(consumerDir, '.dev-agents-sync.json');
+    assert.ok(existsSync(lockfilePath), 'lockfile must be created for explicit --targets codex');
+  });
+});