update.test.ts

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { UpdateCommand, scanInstalledWorkflows } from '../../src/core/update.js';
import { InitCommand } from '../../src/core/init.js';
import { getConfiguredToolsForProfileSync } from '../../src/core/profile-sync-drift.js';
import { FileSystemUtils } from '../../src/utils/file-system.js';
import { OPENSPEC_MARKERS } from '../../src/core/config.js';
import type { GlobalConfig } from '../../src/core/global-config.js';
import { generateCopilotSetupSteps, persistCopilotCloudOptIn } from '../../src/core/github-copilot/cloud-agent.js';
import path from 'path';
import fs from 'fs/promises';
import os from 'os';

// Shared mutable mock config state
const mockState = {
  config: {
    featureFlags: {},
    profile: 'core' as const,
    delivery: 'both' as const,
  } as GlobalConfig,
};

// Mock global config module to isolate tests from the machine's actual config
vi.mock('../../src/core/global-config.js', async (importOriginal) => {
  const actual = await importOriginal<typeof import('../../src/core/global-config.js')>();

  return {
    ...actual,
    getGlobalConfig: () => ({ ...mockState.config }),
    saveGlobalConfig: vi.fn(),
  };
});

// Helper to set mock config for tests
function setMockConfig(config: GlobalConfig) {
  mockState.config = config;
}

function resetMockConfig() {
  mockState.config = { featureFlags: {}, profile: 'core', delivery: 'both' };
}

async function markCodexTarget(skillsDir: string): Promise<void> {
  await fs.mkdir(skillsDir, { recursive: true });
  await fs.writeFile(path.join(skillsDir, '.openspec-target'), 'codex\n');
}

describe('UpdateCommand', () => {
  let testDir: string;
  let updateCommand: UpdateCommand;
  let originalEnv: NodeJS.ProcessEnv;

  beforeEach(async () => {
    originalEnv = { ...process.env };
    // Create a temporary test directory
    testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-test-'));
    process.env.CODEX_HOME = path.join(testDir, 'codex-home');
    process.env.HOME = path.join(testDir, 'home');
    process.env.USERPROFILE = path.join(testDir, 'home');

    // Create openspec directory
    const openspecDir = path.join(testDir, 'openspec');
    await fs.mkdir(openspecDir, { recursive: true });

    updateCommand = new UpdateCommand();

    // Reset mock config to defaults
    resetMockConfig();

    // Clear all mocks before each test
    vi.restoreAllMocks();
  });

  afterEach(async () => {
    process.env = originalEnv;
    // Restore all mocks after each test
    vi.restoreAllMocks();

    // Clean up test directory
    await fs.rm(testDir, { recursive: true, force: true });
  });

  describe('basic validation', () => {
    it('should throw error if openspec directory does not exist', async () => {
      // Remove openspec directory
      await fs.rm(path.join(testDir, 'openspec'), {
        recursive: true,
        force: true,
      });

      await expect(updateCommand.execute(testDir)).rejects.toThrow(
        "No OpenSpec directory found. Run 'openspec init' first."
      );
    });

    it('should report no configured tools when none exist', async () => {
      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('No configured tools found')
      );

      consoleSpy.mockRestore();
    });

    it('should remove generated Copilot cloud files when no tools are configured', async () => {
      const initCommand = new InitCommand({
        tools: 'github-copilot',
        force: true,
        copilotCloud: true,
      });
      await initCommand.execute(testDir);
      await fs.rm(path.join(testDir, '.github', 'skills'), { recursive: true, force: true });
      await fs.rm(path.join(testDir, '.github', 'prompts'), { recursive: true, force: true });

      await updateCommand.execute(testDir);

      await expect(fs.stat(path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml')))
        .rejects.toMatchObject({ code: 'ENOENT' });
      await expect(fs.stat(path.join(testDir, '.github', 'agents', 'openspec.agent.md')))
        .rejects.toMatchObject({ code: 'ENOENT' });
    });
  });

  describe('skill updates', () => {
    it('should update skill files for configured Claude tool', async () => {
      // Set up a configured Claude tool by creating skill directories
      const skillsDir = path.join(testDir, '.claude', 'skills');
      const exploreSkillDir = path.join(skillsDir, 'openspec-explore');
      await fs.mkdir(exploreSkillDir, { recursive: true });

      // Create an existing skill file
      const oldSkillContent = `---
name: openspec-explore (old)
description: Old description
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "0.9"
---

Old instructions content
`;
      await fs.writeFile(
        path.join(exploreSkillDir, 'SKILL.md'),
        oldSkillContent
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Check skill file was updated
      const updatedSkill = await fs.readFile(
        path.join(exploreSkillDir, 'SKILL.md'),
        'utf-8'
      );
      expect(updatedSkill).toContain('name: openspec-explore');
      expect(updatedSkill).not.toContain('Old instructions content');
      expect(updatedSkill).toContain('license: MIT');

      // Check console output
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updating 1 tool(s): claude')
      );

      consoleSpy.mockRestore();
    });

    it('should update MiniMax Code skills without touching unrelated global skills', async () => {
      const skillsDir = path.join(testDir, 'home', '.minimax', 'skills');
      const exploreSkill = path.join(skillsDir, 'openspec-explore', 'SKILL.md');
      const customSkill = path.join(skillsDir, 'my-custom-skill', 'SKILL.md');
      await fs.mkdir(path.dirname(exploreSkill), { recursive: true });
      await fs.writeFile(exploreSkill, 'old content');
      await fs.mkdir(path.dirname(customSkill), { recursive: true });
      await fs.writeFile(customSkill, 'custom content');

      await updateCommand.execute(testDir);

      expect(await fs.readFile(exploreSkill, 'utf-8')).toContain('name: openspec-explore');
      expect(await fs.readFile(customSkill, 'utf-8')).toBe('custom content');
      expect(await FileSystemUtils.directoryExists(path.join(testDir, '.minimax'))).toBe(false);
      expect(await FileSystemUtils.directoryExists(path.join(testDir, '.mavis'))).toBe(false);
    });

    it('should not update MiniMax skills through a linked directory outside the global skills root', async () => {
      const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-minimax-outside-'));
      const skillsRoot = path.join(testDir, 'home', '.minimax', 'skills');
      const linkedSkillDir = path.join(skillsRoot, 'openspec-explore');
      const skillFile = path.join(outsideDir, 'SKILL.md');
      const oldSkillContent = `---
name: openspec-explore
metadata:
  author: openspec
  version: "0.9"
---

Outside content
`;
      await fs.mkdir(skillsRoot, { recursive: true });
      await fs.writeFile(skillFile, oldSkillContent);

      try {
        await fs.symlink(
          outsideDir,
          linkedSkillDir,
          process.platform === 'win32' ? 'junction' : 'dir'
        );

        await expect(updateCommand.execute(testDir)).rejects.toThrow(
          'OpenSpec update failed for: MiniMax Code'
        );

        expect(await fs.readFile(skillFile, 'utf-8')).toBe(oldSkillContent);
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should not delete MiniMax skills through a linked directory outside the global skills root', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        workflows: ['propose'],
        delivery: 'skills',
      });
      const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-minimax-outside-'));
      const skillsRoot = path.join(testDir, 'home', '.minimax', 'skills');
      const linkedSkillDir = path.join(skillsRoot, 'openspec-explore');
      const skillFile = path.join(outsideDir, 'SKILL.md');
      const oldSkillContent = `---
name: openspec-explore
metadata:
  author: openspec
  version: "0.9"
---

Outside content
`;
      await fs.mkdir(skillsRoot, { recursive: true });
      await fs.writeFile(skillFile, oldSkillContent);

      try {
        await fs.symlink(
          outsideDir,
          linkedSkillDir,
          process.platform === 'win32' ? 'junction' : 'dir'
        );

        await expect(updateCommand.execute(testDir)).rejects.toThrow(
          'OpenSpec update failed for: MiniMax Code'
        );

        expect(await fs.readFile(skillFile, 'utf-8')).toBe(oldSkillContent);
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should not update generated artifacts through a linked tool directory outside the project', async () => {
      const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-update-outside-'));
      const skillFile = path.join(
        outsideDir,
        'skills',
        'openspec-explore',
        'SKILL.md'
      );
      const oldSkillContent = `---
name: openspec-explore
metadata:
  author: openspec
  version: "0.9"
---

Outside content
`;
      await fs.mkdir(path.dirname(skillFile), { recursive: true });
      await fs.writeFile(skillFile, oldSkillContent);

      try {
        await fs.symlink(
          outsideDir,
          path.join(testDir, '.claude'),
          process.platform === 'win32' ? 'junction' : 'dir'
        );

        await expect(updateCommand.execute(testDir)).rejects.toThrow(
          'OpenSpec update failed for: Claude Code'
        );

        expect(await fs.readFile(skillFile, 'utf-8')).toBe(oldSkillContent);
        expect(await fs.readdir(path.join(outsideDir, 'skills'))).toEqual([
          'openspec-explore',
        ]);
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should not delete generated artifacts through a linked tool directory outside the project', async () => {
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });
      const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-update-outside-'));
      const skillFile = path.join(
        outsideDir,
        'skills',
        'openspec-explore',
        'SKILL.md'
      );
      await fs.mkdir(path.dirname(skillFile), { recursive: true });
      await fs.writeFile(
        skillFile,
        `---
name: openspec-explore
metadata:
  author: openspec
  version: "0.9"
---
`
      );

      try {
        await fs.symlink(
          outsideDir,
          path.join(testDir, '.claude'),
          process.platform === 'win32' ? 'junction' : 'dir'
        );

        await expect(updateCommand.execute(testDir)).rejects.toThrow(
          'OpenSpec update failed for: Claude Code'
        );

        await expect(fs.stat(skillFile)).resolves.toBeDefined();
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should show the Hermes setup note when updating a configured Hermes tool', async () => {
      const exploreSkillDir = path.join(testDir, '.hermes', 'skills', 'openspec-explore');
      await fs.mkdir(exploreSkillDir, { recursive: true });
      await fs.writeFile(
        path.join(exploreSkillDir, 'SKILL.md'),
        `---\nname: openspec-explore\nmetadata:\n  author: openspec\n  version: "0.9"\n---\n\nOld instructions content\n`
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(
        logCalls.some(
          (entry) => entry.includes('Setup required for Hermes Agent') && entry.includes('skills.external_dirs'),
        ),
      ).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should show the Hermes setup note even when Hermes is already up to date', async () => {
      const initCommand = new InitCommand({ tools: 'hermes', force: true });
      await initCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(logCalls.some((entry) => entry.includes('up to date'))).toBe(true);
      expect(
        logCalls.some(
          (entry) => entry.includes('Setup required for Hermes Agent') && entry.includes('skills.external_dirs'),
        ),
      ).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should migrate OpenSpec skills from legacy .kimi to .kimi-code, preserving user files', async () => {
      // Managed skill in the legacy Kimi CLI location
      const legacySkillDir = path.join(testDir, '.kimi', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkillDir, { recursive: true });
      await fs.writeFile(
        path.join(legacySkillDir, 'SKILL.md'),
        `---\nname: openspec-explore\nmetadata:\n  author: openspec\n  version: "0.9"\n---\n\nOld instructions content\n`
      );

      // User-owned files in the legacy location that must be preserved
      const userSkillDir = path.join(testDir, '.kimi', 'skills', 'my-custom-skill');
      await fs.mkdir(userSkillDir, { recursive: true });
      await fs.writeFile(path.join(userSkillDir, 'SKILL.md'), 'user skill');
      await fs.writeFile(path.join(testDir, '.kimi', 'config.toml'), 'user config');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Managed skill migrated to .kimi-code and refreshed by the update
      const migratedSkill = await fs.readFile(
        path.join(testDir, '.kimi-code', 'skills', 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(migratedSkill).toContain('name: openspec-explore');
      expect(migratedSkill).not.toContain('Old instructions content');
      // Kimi Code has no command adapter, so the refreshed skill must use
      // its documented /skill:<name> invocations, never /opsx:* commands
      // that were not generated
      expect(migratedSkill).not.toContain('/opsx:');
      expect(migratedSkill).not.toContain('/opsx-');
      expect(migratedSkill).toContain('/skill:openspec-');

      // Legacy managed skill is gone; user files stay where they were
      await expect(fs.access(legacySkillDir)).rejects.toThrow();
      expect(await fs.readFile(path.join(userSkillDir, 'SKILL.md'), 'utf-8')).toBe('user skill');
      expect(await fs.readFile(path.join(testDir, '.kimi', 'config.toml'), 'utf-8')).toBe('user config');

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(logCalls.some((entry) => entry.includes('.kimi → .kimi-code'))).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should remove the legacy .kimi directory entirely when it only held OpenSpec skills', async () => {
      const legacySkillDir = path.join(testDir, '.kimi', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkillDir, { recursive: true });
      await fs.writeFile(
        path.join(legacySkillDir, 'SKILL.md'),
        `---\nname: openspec-explore\nmetadata:\n  author: openspec\n  version: "0.9"\n---\n\nOld instructions content\n`
      );

      await updateCommand.execute(testDir);

      await expect(fs.access(path.join(testDir, '.kimi'))).rejects.toThrow();
      const migratedSkill = path.join(testDir, '.kimi-code', 'skills', 'openspec-explore', 'SKILL.md');
      await expect(fs.access(migratedSkill)).resolves.toBeUndefined();
    });

    it('should migrate legacy Codex skills after writing replacements and preserve user files', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));

      const userSkill = path.join(testDir, '.codex', 'skills', 'my-custom-skill', 'SKILL.md');
      await fs.mkdir(path.dirname(userSkill), { recursive: true });
      await fs.writeFile(userSkill, 'user skill');
      await fs.writeFile(path.join(testDir, '.codex', 'config.toml'), 'user config');

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);

      const currentSkill = path.join(
        testDir,
        '.agents',
        'skills',
        'openspec-propose',
        'SKILL.md'
      );
      expect(await fs.readFile(currentSkill, 'utf-8')).toContain('$openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.codex', 'skills', 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
      expect(await fs.readFile(userSkill, 'utf-8')).toBe('user skill');
      expect(await fs.readFile(path.join(testDir, '.codex', 'config.toml'), 'utf-8')).toBe(
        'user config'
      );
      expect(
        consoleSpy.mock.calls.flat().map(String).some((entry) =>
          entry.includes('.codex → .agents')
        )
      ).toBe(true);
    });

    it('should retry interrupted equivalent Codex cleanup without force', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      const canonicalSkills = path.join(testDir, '.agents', 'skills');
      const legacySkills = path.join(testDir, '.codex', 'skills');
      await fs.cp(canonicalSkills, legacySkills, { recursive: true });
      await fs.rm(path.join(legacySkills, '.openspec-target'));

      for (const entry of await fs.readdir(legacySkills, { withFileTypes: true })) {
        if (!entry.isDirectory() || !entry.name.startsWith('openspec-')) continue;
        const skillFile = path.join(legacySkills, entry.name, 'SKILL.md');
        const legacyContent = (await fs.readFile(skillFile, 'utf-8'))
          .replace(
            /\$openspec-([a-z0-9-]+) \(Codex\) or \/openspec-\1 \(other agents\)/g,
            '$openspec-$1'
          )
          .replace(/generatedBy:\s*"[^"]+"/, 'generatedBy: "0.1.0"')
          .replace(/\n/g, '\r\n');
        await fs.writeFile(skillFile, `\uFEFF${legacyContent}`);
      }

      await updateCommand.execute(testDir);

      await expect(
        fs.access(path.join(legacySkills, 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
      expect(await fs.readFile(
        path.join(canonicalSkills, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      )).toContain('$openspec-apply-change');
    });

    it('should preserve and report a divergent legacy Codex skill', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));
      const legacySkill = path.join(
        testDir,
        '.codex',
        'skills',
        'openspec-propose',
        'SKILL.md'
      );
      await fs.appendFile(legacySkill, '\nUser edit\n');

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);

      expect(await fs.readFile(legacySkill, 'utf-8')).toContain('User edit');
      expect(
        consoleSpy.mock.calls.flat().map(String).some((entry) =>
          entry.includes('Left 1 file in .codex/')
        )
      ).toBe(true);

      consoleSpy.mockClear();
      await updateCommand.execute(testDir);
      const secondRunLogs = consoleSpy.mock.calls.flat().map(String);
      expect(secondRunLogs.some((entry) => entry.includes('up to date'))).toBe(true);
      expect(secondRunLogs.some((entry) => entry.includes('Left 1 file in .codex/'))).toBe(false);
    });

    it('should not restore legacy Codex workflows excluded by the active profile', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'skills',
        workflows: ['explore'],
      });

      await updateCommand.execute(testDir);

      expect(
        await FileSystemUtils.fileExists(
          path.join(testDir, '.agents', 'skills', 'openspec-explore', 'SKILL.md')
        )
      ).toBe(true);
      expect(
        await FileSystemUtils.fileExists(
          path.join(testDir, '.agents', 'skills', 'openspec-apply-change', 'SKILL.md')
        )
      ).toBe(false);
      expect(
        await FileSystemUtils.fileExists(
          path.join(testDir, '.codex', 'skills', 'openspec-apply-change', 'SKILL.md')
        )
      ).toBe(true);

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);
      expect(
        consoleSpy.mock.calls.flat().map(String).some((entry) => entry.includes('up to date'))
      ).toBe(true);
    });

    it('should keep Codex as the sole writer of its marked shared skill tree', async () => {
      await new InitCommand({ tools: 'codex,agents', force: true }).execute(testDir);
      const consoleSpy = vi.spyOn(console, 'log');

      await new UpdateCommand({ force: true }).execute(testDir);

      const proposeSkill = await fs.readFile(
        path.join(testDir, '.agents', 'skills', 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
      expect(
        consoleSpy.mock.calls.flat().map(String).some((entry) =>
          entry.includes('Force updating 1 tool(s): codex')
        )
      ).toBe(true);
    });

    it('should refresh Antigravity workflows without rewriting Codex-owned shared skills', async () => {
      await new InitCommand({ tools: 'antigravity,codex', force: true }).execute(testDir);

      await new UpdateCommand({ force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.agents', 'workflows', 'opsx-propose.md'))
      ).resolves.toBeUndefined();
      expect(getConfiguredToolsForProfileSync(testDir)).toEqual([
        'antigravity',
        'codex',
      ]);
    });

    it('should upgrade legacy Antigravity workflows beside Codex-owned shared skills', async () => {
      await new InitCommand({ tools: 'antigravity', force: true }).execute(testDir);
      const legacyWorkflow = path.join(testDir, '.agent', 'workflows', 'opsx-propose.md');
      await fs.mkdir(path.dirname(legacyWorkflow), { recursive: true });
      await fs.copyFile(
        path.join(testDir, '.agents', 'workflows', 'opsx-propose.md'),
        legacyWorkflow
      );
      await fs.cp(
        path.join(testDir, '.agents', 'skills'),
        path.join(testDir, '.agent', 'skills'),
        { recursive: true }
      );
      await fs.rm(path.join(testDir, '.agents', 'workflows'), { recursive: true });
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);

      await new UpdateCommand().execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      expect(
        await fs.readFile(path.join(skillsDir, 'openspec-propose', 'SKILL.md'), 'utf-8')
      ).toContain('$openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.agents', 'workflows', 'opsx-propose.md'))
      ).resolves.toBeUndefined();
      await expect(fs.access(legacyWorkflow)).rejects.toThrow();
    });

    it('should keep an explicit agents target despite preserved legacy Codex skills', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));
      await fs.appendFile(
        path.join(testDir, '.codex', 'skills', 'openspec-propose', 'SKILL.md'),
        '\nUser edit\n'
      );
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);

      await updateCommand.execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('agents\n');
      expect(
        await fs.readFile(path.join(skillsDir, 'openspec-propose', 'SKILL.md'), 'utf-8')
      ).toContain('/openspec-apply-change');
      expect(
        await fs.readFile(
          path.join(testDir, '.codex', 'skills', 'openspec-propose', 'SKILL.md'),
          'utf-8'
        )
      ).toContain('User edit');
    });

    it('does not let a legacy Codex global prompt hijack an established agents target', async () => {
      // Regression for the hijack this PR fixes: the guard must actually be
      // invoked by the update flow, not merely be correct in isolation.
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'skills' });
      // The vendor-neutral `agents` target owns `.agents` (marker + generic skills).
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);
      // A leftover global Codex install, detected only from `~/.codex/prompts`.
      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const globalPrompt = path.join(promptDir, 'opsx-explore.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(globalPrompt, 'legacy explore prompt');

      // The skip message is emitted via an ora spinner, which writes to the
      // process streams rather than through console.log. Restore the spies in a
      // finally so a throw can never swallow stdout for the rest of the suite.
      let streamOutput = '';
      const capture = (chunk: unknown) => {
        streamOutput += String(chunk);
        return true;
      };
      const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(capture as never);
      const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(capture as never);
      try {
        await new UpdateCommand({ force: true }).execute(testDir);
      } finally {
        stdoutSpy.mockRestore();
        stderrSpy.mockRestore();
      }

      const skillsDir = path.join(testDir, '.agents', 'skills');
      // Ownership marker is not flipped to codex...
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('agents\n');
      // ...and the tree keeps generic `/openspec-` syntax, never Codex `$openspec-`.
      const propose = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(propose).not.toContain('$openspec-');
      expect(propose).toContain('/openspec-');
      // Generation AND configuration are skipped: Codex is never recorded as a
      // configured tool, so a stray global prompt cannot flip ownership later.
      const configured = getConfiguredToolsForProfileSync(testDir);
      expect(configured).toContain('agents');
      expect(configured).not.toContain('codex');
      // The skip names the established owner so the user understands why.
      expect(streamOutput).toMatch(/Skipped Codex/);
      expect(streamOutput).toMatch(/managed by another tool \(Shared \.agents skills\)/);
      // The legacy signal must survive: because Codex was skipped, no
      // replacement skill exists, so the deferred global-prompt cleanup must
      // preserve `~/.codex/prompts` untouched (byte-for-byte) rather than
      // delete it — otherwise the skip could never re-offer Codex later.
      expect(await FileSystemUtils.fileExists(globalPrompt)).toBe(true);
      expect(await fs.readFile(globalPrompt, 'utf-8')).toBe('legacy explore prompt');
    });

    it('lets a first-time legacy Codex upgrade claim an unowned agents root', async () => {
      // Inverse of the hijack guard: with no `.agents` tree yet, nothing is
      // owned, so the real update path must still generate Codex skills and
      // stamp the `codex` marker — proving the guard is not over-broad.
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'skills' });
      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(path.join(promptDir, 'opsx-explore.md'), 'legacy explore prompt');

      await new UpdateCommand({ force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      // The codex marker is written (writeSharedSkillTarget on the non-owned path).
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      // A single opsx-explore prompt infers only the `explore` workflow, and the
      // generated skill carries Codex `$openspec-` syntax.
      const explore = await fs.readFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(explore).toContain('$openspec-');
      // Codex is now recorded as configured (mirrors the negative check above).
      expect(getConfiguredToolsForProfileSync(testDir)).toContain('codex');
    });

    it('preserves a skipped tool\'s repo-local legacy prompts instead of deleting them', async () => {
      // When the guard skips Codex (agents owns `.agents`), no replacement skill
      // is written — so Codex's repo-local `.codex/prompts` must NOT be cleaned
      // up. Deleting them would strip the legacy signal with nothing in its place.
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'skills' });
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);
      const legacyPrompts = path.join(testDir, '.codex', 'prompts');
      await fs.mkdir(legacyPrompts, { recursive: true });
      await fs.writeFile(path.join(legacyPrompts, 'openspec-explore.md'), 'legacy repo-local prompt');

      await new UpdateCommand({ force: true }).execute(testDir);

      // agents tree preserved, and the repo-local legacy prompt survives
      // byte-for-byte — asserting content, not mere existence, distinguishes
      // "left untouched" from "deleted then rewritten".
      expect(
        await fs.readFile(path.join(testDir, '.agents', 'skills', '.openspec-target'), 'utf-8')
      ).toBe('agents\n');
      const preservedPrompt = path.join(legacyPrompts, 'openspec-explore.md');
      expect(await FileSystemUtils.fileExists(preservedPrompt)).toBe(true);
      expect(await fs.readFile(preservedPrompt, 'utf-8')).toBe('legacy repo-local prompt');
    });

    it('should let an explicit Codex init take ownership of an agents tree', async () => {
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);

      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
    });

    it('should consolidate an existing unmarked agents tree with legacy Codex skills', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);
      await fs.rm(path.join(testDir, '.agents', 'skills', '.openspec-target'));
      const legacyPropose = path.join(
        testDir,
        '.codex',
        'skills',
        'openspec-propose',
        'SKILL.md'
      );
      await fs.writeFile(
        legacyPropose,
        (await fs.readFile(legacyPropose, 'utf-8')).replace(
          /generatedBy:\s*"[^"]+"/,
          'generatedBy: "0.1.0"'
        )
      );

      await new UpdateCommand({ force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.codex', 'skills', 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
    });

    it('should infer an unmarked canonical Codex tree that was moved manually', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      const skillsDir = path.join(testDir, '.agents', 'skills');
      await fs.rm(path.join(skillsDir, '.openspec-target'));

      await new UpdateCommand({ force: true }).execute(testDir);

      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
    });

    it('should preserve agents ownership when it switches to commands-only', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });

      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('agents\n');
      await expect(
        fs.access(path.join(skillsDir, 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
    });

    it('should not resurrect divergent legacy Codex skills after agents switches to commands-only', async () => {
      await new InitCommand({ tools: 'agents', force: true }).execute(testDir);
      const canonicalSkills = path.join(testDir, '.agents', 'skills');
      const legacySkills = path.join(testDir, '.codex', 'skills');
      await fs.cp(canonicalSkills, legacySkills, { recursive: true });
      await fs.writeFile(
        path.join(legacySkills, 'openspec-propose', 'SKILL.md'),
        'divergent legacy Codex skill\n'
      );
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });

      await updateCommand.execute(testDir);
      await updateCommand.execute(testDir);

      expect(await fs.readFile(path.join(canonicalSkills, '.openspec-target'), 'utf-8')).toBe(
        'agents\n'
      );
      await expect(
        fs.access(path.join(canonicalSkills, 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
      expect(
        await fs.readFile(path.join(legacySkills, 'openspec-propose', 'SKILL.md'), 'utf-8')
      ).toBe('divergent legacy Codex skill\n');
    });

    it('should migrate legacy Codex skills under commands-only delivery', async () => {
      await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
      await fs.rename(path.join(testDir, '.agents'), path.join(testDir, '.codex'));
      await fs.rm(path.join(testDir, '.codex', 'skills', '.openspec-target'));
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });

      await updateCommand.execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.codex', 'skills', 'openspec-propose', 'SKILL.md'))
      ).rejects.toThrow();
    });

    it('should not migrate legacy Codex skills through a symlink outside the project', async () => {
      const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openspec-codex-outside-'));
      try {
        await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
        const outsideSkill = path.join(
          outsideDir,
          'skills',
          'openspec-propose',
          'SKILL.md'
        );
        await fs.mkdir(path.dirname(outsideSkill), { recursive: true });
        await fs.copyFile(
          path.join(testDir, '.agents', 'skills', 'openspec-propose', 'SKILL.md'),
          outsideSkill
        );
        await fs.symlink(
          outsideDir,
          path.join(testDir, '.codex'),
          process.platform === 'win32' ? 'junction' : 'dir'
        );
        const warningSpy = vi.spyOn(console, 'warn');

        await new UpdateCommand({ force: true }).execute(testDir);

        await expect(fs.readFile(outsideSkill, 'utf-8')).resolves.toContain(
          'name: openspec-propose'
        );
        expect(
          warningSpy.mock.calls.flat().map(String).some((entry) =>
            entry.includes('resolves outside this project')
          )
        ).toBe(true);
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should not migrate a nested legacy Codex skill symlink outside the project', async () => {
      const outsideDir = await fs.mkdtemp(
        path.join(os.tmpdir(), 'openspec-codex-skill-outside-')
      );
      try {
        await new InitCommand({ tools: 'codex', force: true }).execute(testDir);
        const outsideSkill = path.join(outsideDir, 'SKILL.md');
        await fs.copyFile(
          path.join(testDir, '.agents', 'skills', 'openspec-propose', 'SKILL.md'),
          outsideSkill
        );
        const legacySkillsDir = path.join(testDir, '.codex', 'skills');
        await fs.mkdir(legacySkillsDir, { recursive: true });
        await fs.symlink(
          outsideDir,
          path.join(legacySkillsDir, 'openspec-propose'),
          process.platform === 'win32' ? 'junction' : 'dir'
        );
        const warningSpy = vi.spyOn(console, 'warn');

        await new UpdateCommand({ force: true }).execute(testDir);

        await expect(fs.readFile(outsideSkill, 'utf-8')).resolves.toContain(
          'name: openspec-propose'
        );
        expect(
          warningSpy.mock.calls.flat().map(String).some((entry) =>
            entry.includes('resolves outside this project')
          )
        ).toBe(true);
      } finally {
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });

    it('should update core profile skill files when tool is configured', async () => {
      // Set up a configured tool with one skill directory
      const skillsDir = path.join(testDir, '.claude', 'skills');

      // Create at least one skill to mark tool as configured
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old content'
      );

      await updateCommand.execute(testDir);

      // Verify core profile skill files were created/updated (propose, explore, apply, update, sync, archive)
      const coreSkillNames = [
        'openspec-explore',
        'openspec-apply-change',
        'openspec-update-change',
        'openspec-sync-specs',
        'openspec-archive-change',
        'openspec-propose',
      ];

      for (const skillName of coreSkillNames) {
        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
        const exists = await FileSystemUtils.fileExists(skillFile);
        expect(exists).toBe(true);

        const content = await fs.readFile(skillFile, 'utf-8');
        expect(content).toContain('---');
        expect(content).toContain('name:');
        expect(content).toContain('description:');
      }

      // Verify non-core skills are NOT created
      const nonCoreSkillNames = [
        'openspec-new-change',
        'openspec-continue-change',
        'openspec-ff-change',
        'openspec-bulk-archive-change',
        'openspec-verify-change',
      ];

      for (const skillName of nonCoreSkillNames) {
        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
        const exists = await FileSystemUtils.fileExists(skillFile);
        expect(exists).toBe(false);
      }
    });

    it('should update skill files for configured shared agents target', async () => {
      const skillsDir = path.join(testDir, '.agents', 'skills');
      const exploreSkillDir = path.join(skillsDir, 'openspec-explore');
      await fs.mkdir(exploreSkillDir, { recursive: true });
      await fs.writeFile(path.join(exploreSkillDir, 'SKILL.md'), 'old content');

      await updateCommand.execute(testDir);

      const updatedSkill = await fs.readFile(
        path.join(exploreSkillDir, 'SKILL.md'),
        'utf-8'
      );
      expect(updatedSkill).toContain('name: openspec-explore');
    });
  });

  describe('command updates', () => {
    it('heals stale colon references for a filename-invoked tool (cursor)', async () => {
      // The headline upgrade path for #1307: a project generated before the
      // fix carries /opsx: references that Cursor's palette never registers.
      // `openspec update` must rewrite both the command bodies and the skills.
      const initCommand = new InitCommand({ tools: 'cursor', force: true });
      await initCommand.execute(testDir);

      const commandFile = path.join(testDir, '.cursor', 'commands', 'opsx-apply.md');
      const skillFile = path.join(
        testDir,
        '.cursor',
        'skills',
        'openspec-apply-change',
        'SKILL.md'
      );
      for (const file of [commandFile, skillFile]) {
        const stale = (await fs.readFile(file, 'utf-8')).replace(/\/opsx-/g, '/opsx:');
        await fs.writeFile(file, stale);
      }
      expect(await fs.readFile(commandFile, 'utf-8')).toContain('/opsx:apply');
      expect(await fs.readFile(skillFile, 'utf-8')).toContain('/opsx:apply');

      await new UpdateCommand({ force: true }).execute(testDir);

      const command = await fs.readFile(commandFile, 'utf-8');
      expect(command).toContain('/opsx-archive');
      expect(command).not.toContain('/opsx:');

      const skill = await fs.readFile(skillFile, 'utf-8');
      // Positive assertion too: a skill that simply dropped every reference
      // would satisfy the negative one.
      expect(skill).toContain('/opsx-apply');
      expect(skill).not.toContain('/opsx:');
    });

    it('keeps namespaced references for claude while hyphenating qwen in one run', async () => {
      const initCommand = new InitCommand({ tools: 'claude,qwen', force: true });
      await initCommand.execute(testDir);

      await new UpdateCommand({ force: true }).execute(testDir);

      const claudeCommand = await fs.readFile(
        path.join(testDir, '.claude', 'commands', 'opsx', 'apply.md'),
        'utf-8'
      );
      expect(claudeCommand).toContain('/opsx:archive');
      expect(claudeCommand).not.toContain('/opsx-archive');

      const qwenCommand = await fs.readFile(
        path.join(testDir, '.qwen', 'commands', 'opsx-apply.md'),
        'utf-8'
      );
      expect(qwenCommand).toContain('/opsx-archive');
      expect(qwenCommand).not.toContain('/opsx:');

      const qwenSkill = await fs.readFile(
        path.join(testDir, '.qwen', 'skills', 'openspec-apply-change', 'SKILL.md'),
        'utf-8'
      );
      expect(qwenSkill).toContain('/opsx-apply');
      expect(qwenSkill).not.toContain('/opsx:');

      const claudeSkill = await fs.readFile(
        path.join(testDir, '.claude', 'skills', 'openspec-apply-change', 'SKILL.md'),
        'utf-8'
      );
      expect(claudeSkill).toContain('/opsx:apply');
      expect(claudeSkill).not.toContain('/opsx-');
    });

    it('heals stale slash references for a prompt-library tool (amazon-q)', async () => {
      // Amazon Q registers no slash command at all: .amazonq/prompts files are
      // its prompt library, invoked with @. A project generated before this fix
      // carries /opsx: references that Amazon Q answers to under no spelling.
      const initCommand = new InitCommand({ tools: 'amazon-q', force: true });
      await initCommand.execute(testDir);

      const promptFile = path.join(testDir, '.amazonq', 'prompts', 'opsx-apply.md');
      const skillFile = path.join(
        testDir,
        '.amazonq',
        'skills',
        'openspec-apply-change',
        'SKILL.md'
      );
      for (const file of [promptFile, skillFile]) {
        const stale = (await fs.readFile(file, 'utf-8')).replace(/@opsx-/g, '/opsx:');
        await fs.writeFile(file, stale);
      }
      expect(await fs.readFile(promptFile, 'utf-8')).toContain('/opsx:apply');

      await new UpdateCommand({ force: true }).execute(testDir);

      for (const file of [promptFile, skillFile]) {
        const refreshed = await fs.readFile(file, 'utf-8');
        // Positive assertion too: dropping every reference would satisfy the
        // negative ones. And no stray slash may survive the rewrite.
        expect(refreshed).toContain('@opsx-apply');
        expect(refreshed).not.toContain('/opsx:');
        expect(refreshed).not.toContain('/opsx-');
      }
      // The prompt body cross-references other prompts; those move too.
      expect(await fs.readFile(promptFile, 'utf-8')).toContain('@opsx-archive');
    });

    it('should update opsx commands for configured Claude tool', async () => {
      // Set up a configured Claude tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old content'
      );

      await updateCommand.execute(testDir);

      // Check opsx command files were created
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      const exploreCmd = path.join(commandsDir, 'explore.md');
      const exists = await FileSystemUtils.fileExists(exploreCmd);
      expect(exists).toBe(true);

      const content = await fs.readFile(exploreCmd, 'utf-8');
      expect(content).toContain('---');
      expect(content).toContain('name:');
      expect(content).toContain('description:');
      expect(content).toContain('category:');
      expect(content).toContain('tags:');
    });

    it('should generate ZCode commands under .zcode without creating .agents', async () => {
      // Mark ZCode as configured with an outdated generatedBy so update picks it up
      const skillsDir = path.join(testDir, '.zcode', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        '---\nmetadata:\n  generatedBy: "0.0.1"\n---\nold content\n'
      );

      await updateCommand.execute(testDir);

      // Commands regenerated under .zcode/commands/opsx
      const exploreCmd = path.join(testDir, '.zcode', 'commands', 'opsx', 'explore.md');
      expect(await FileSystemUtils.fileExists(exploreCmd)).toBe(true);

      const cmdContent = await fs.readFile(exploreCmd, 'utf-8');
      expect(cmdContent).toContain('---');
      expect(cmdContent).toContain('name:');
      expect(cmdContent).toContain('description:');
      expect(cmdContent).toContain('category:');
      expect(cmdContent).toContain('tags:');

      // Skill refreshed under .zcode
      const refreshedSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(refreshedSkill).not.toContain('old content');

      // .agents must never be created during update
      await expect(fs.access(path.join(testDir, '.agents'))).rejects.toThrow();
    });

    it('should update core profile opsx commands when tool is configured', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old content'
      );

      await updateCommand.execute(testDir);

      // Verify core profile commands were created (propose, explore, apply, update, sync, archive)
      const coreCommandIds = ['explore', 'apply', 'update', 'sync', 'archive', 'propose'];
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      for (const cmdId of coreCommandIds) {
        const cmdFile = path.join(commandsDir, `${cmdId}.md`);
        const exists = await FileSystemUtils.fileExists(cmdFile);
        expect(exists).toBe(true);
      }

      // Verify non-core commands are NOT created
      const nonCoreCommandIds = ['new', 'continue', 'ff', 'bulk-archive', 'verify'];
      for (const cmdId of nonCoreCommandIds) {
        const cmdFile = path.join(commandsDir, `${cmdId}.md`);
        const exists = await FileSystemUtils.fileExists(cmdFile);
        expect(exists).toBe(false);
      }
    });

    it('should refresh both Devin Desktop surfaces with the right invocation syntax', async () => {
      // Set up Devin Desktop directory with a skill to indicate it's configured
      const skillsDir = path.join(testDir, '.devin', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-apply-change'), {
        recursive: true,
      });
      const skillFile = path.join(skillsDir, 'openspec-apply-change', 'SKILL.md');
      await fs.writeFile(skillFile, 'old content');

      await updateCommand.execute(testDir);

      // Workflows are invoked by filename, so their bodies use `/opsx-*`.
      const workflow = path.join(testDir, '.devin', 'workflows', 'opsx-apply.md');
      expect(await FileSystemUtils.fileExists(workflow)).toBe(true);

      const workflowContent = await fs.readFile(workflow, 'utf-8');
      expect(workflowContent).toMatch(/^---\nname: "/);
      expect(workflowContent).toContain('/opsx-');
      expect(workflowContent).not.toContain('/opsx:');

      // Skills are refreshed too, and point at skills — the Devin Local agent
      // has no workflows to point at.
      const skillContent = await fs.readFile(skillFile, 'utf-8');
      expect(skillContent).not.toContain('old content');
      expect(skillContent).toContain('/openspec-apply-change');
      expect(skillContent).not.toContain('/opsx:');
      expect(skillContent).not.toContain('/opsx-');
    });

    it.each(['both', 'commands'] as const)(
      'should discover and refresh SourceCraft Code Assistant commands with delivery=%s',
      async (delivery) => {
        setMockConfig({ featureFlags: {}, profile: 'core', delivery });
        const commandsDir = path.join(testDir, '.codeassistant', 'commands');
        await fs.mkdir(commandsDir, { recursive: true });
        await fs.writeFile(path.join(commandsDir, 'opsx-apply.md'), 'old command content');
        const skillFile = path.join(testDir, '.codeassistant', 'skills', 'openspec-apply-change', 'SKILL.md');
        if (delivery === 'both') {
          await fs.mkdir(path.dirname(skillFile), { recursive: true });
          await fs.writeFile(skillFile, 'old skill content');
        }

        await updateCommand.execute(testDir);

        const commandContent = await fs.readFile(path.join(commandsDir, 'opsx-apply.md'), 'utf-8');
        expect(commandContent).toMatch(/^---\ndescription: /);
        expect(commandContent).toContain('/opsx-archive');
        expect(commandContent).not.toContain('/opsx:');
        expect(await FileSystemUtils.fileExists(path.join(commandsDir, 'opsx-propose.md'))).toBe(true);

        expect(await FileSystemUtils.fileExists(skillFile)).toBe(delivery === 'both');
        if (delivery === 'both') {
          const skillContent = await fs.readFile(skillFile, 'utf-8');
          expect(skillContent).toContain('/opsx-archive');
          expect(skillContent).not.toContain('/opsx:');
        }

        const consoleSpy = vi.spyOn(console, 'log');
        await updateCommand.execute(testDir);
        expect(consoleSpy.mock.calls.flat().map(String).some((entry) => entry.includes('up to date'))).toBe(true);
      }
    );

    it('should update command files when tool is configured via commands-only delivery without skills', async () => {
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      await fs.mkdir(commandsDir, { recursive: true });
      const coreCommandIds = ['explore', 'apply', 'update', 'sync', 'archive', 'propose'];
      for (const cmdId of coreCommandIds) {
        await fs.writeFile(path.join(commandsDir, `${cmdId}.md`), 'old command content');
      }

      await updateCommand.execute(testDir);

      for (const cmdId of coreCommandIds) {
        const updatedContent = await fs.readFile(path.join(commandsDir, `${cmdId}.md`), 'utf-8');
        expect(updatedContent).not.toBe('old command content');
        expect(updatedContent).toContain('---');
      }
    });
  });

  describe('multi-tool support', () => {
    it('should update multiple configured tools', async () => {
      // Set up Claude
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Set up Cursor
      const cursorSkillsDir = path.join(testDir, '.cursor', 'skills');
      await fs.mkdir(path.join(cursorSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(cursorSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Both tools should be updated
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updating 2 tool(s)')
      );

      // Verify Claude skills updated
      const claudeSkill = await fs.readFile(
        path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(claudeSkill).toContain('name: openspec-explore');

      // Verify Cursor skills updated
      const cursorSkill = await fs.readFile(
        path.join(cursorSkillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(cursorSkill).toContain('name: openspec-explore');

      consoleSpy.mockRestore();
    });

    it('should update Qwen tool with correct command format', async () => {
      // Set up Qwen
      const qwenSkillsDir = path.join(testDir, '.qwen', 'skills');
      await fs.mkdir(path.join(qwenSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(qwenSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      await updateCommand.execute(testDir);

      // Check Qwen command format (Markdown) - Qwen uses flat path structure: opsx-<id>.md
      const qwenCmd = path.join(
        testDir,
        '.qwen',
        'commands',
        'opsx-explore.md'
      );
      const exists = await FileSystemUtils.fileExists(qwenCmd);
      expect(exists).toBe(true);

      const content = await fs.readFile(qwenCmd, 'utf-8');
      expect(content).toContain('---');
      expect(content).toContain('description:');
    });

    it('should update Command Code tool and regenerate its flat command', async () => {
      // A configured Command Code install is detected by its skills dir
      const commandCodeSkillsDir = path.join(testDir, '.commandcode', 'skills');
      await fs.mkdir(path.join(commandCodeSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(commandCodeSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      await updateCommand.execute(testDir);

      // Adapter-backed: update regenerates .commandcode/commands/opsx-<id>.md
      const commandCodeCmd = path.join(
        testDir,
        '.commandcode',
        'commands',
        'opsx-explore.md'
      );
      expect(await FileSystemUtils.fileExists(commandCodeCmd)).toBe(true);

      // Plain Markdown (no frontmatter) with the argument placeholder injected
      const content = await fs.readFile(commandCodeCmd, 'utf-8');
      expect(content).not.toMatch(/^---\n/);
      expect(content).toContain('**Provided arguments**: $ARGUMENTS');
    });

    it('should repair stale OpenCode commands-only installs once', async () => {
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });
      const commandsDir = path.join(testDir, '.opencode', 'commands');
      const coreCommandIds = [
        'explore',
        'apply',
        'update',
        'sync',
        'archive',
        'propose',
      ];
      await fs.mkdir(commandsDir, { recursive: true });
      for (const commandId of coreCommandIds) {
        await fs.writeFile(
          path.join(commandsDir, `opsx-${commandId}.md`),
          'old command without arguments'
        );
      }

      await updateCommand.execute(testDir);

      for (const commandId of coreCommandIds) {
        const content = await fs.readFile(
          path.join(commandsDir, `opsx-${commandId}.md`),
          'utf-8'
        );
        expect(content.match(/\$ARGUMENTS/g)).toHaveLength(1);
        expect(content).toContain('**Provided arguments**: $ARGUMENTS');
        expect(content).not.toContain('old command without arguments');
      }

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(logCalls.some((entry) => entry.includes('up to date'))).toBe(true);
      expect(logCalls.some((entry) => entry.includes('Updating 1 tool(s)'))).toBe(false);
      consoleSpy.mockRestore();
    });

    it('should migrate a legacy .windsurf install to .devin, preserving user files', async () => {
      // A project set up before the Devin Desktop rebrand: OpenSpec skills and
      // workflows under .windsurf/, alongside files the user wrote themselves.
      const legacySkillDir = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkillDir, { recursive: true });
      await fs.writeFile(path.join(legacySkillDir, 'SKILL.md'), 'old skill content');

      const legacyWorkflows = path.join(testDir, '.windsurf', 'workflows');
      await fs.mkdir(legacyWorkflows, { recursive: true });
      await fs.writeFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'old workflow content');

      // User-owned content that must survive untouched
      const userSkillDir = path.join(testDir, '.windsurf', 'skills', 'my-custom-skill');
      await fs.mkdir(userSkillDir, { recursive: true });
      await fs.writeFile(path.join(userSkillDir, 'SKILL.md'), 'user skill');
      await fs.writeFile(path.join(legacyWorkflows, 'my-workflow.md'), 'user workflow');

      // Tests run non-interactively, so the consent-gated move is taken.
      await updateCommand.execute(testDir);

      // Both surfaces now live under .devin and were refreshed
      const migratedSkill = await fs.readFile(
        path.join(testDir, '.devin', 'skills', 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(migratedSkill).not.toContain('old skill content');
      const migratedWorkflow = await fs.readFile(
        path.join(testDir, '.devin', 'workflows', 'opsx-explore.md'),
        'utf-8'
      );
      expect(migratedWorkflow).not.toContain('old workflow content');
      expect(migratedWorkflow).toContain('---');

      // The OpenSpec-managed originals are gone; the user's files are not
      await expect(fs.access(legacySkillDir)).rejects.toThrow();
      await expect(
        fs.access(path.join(legacyWorkflows, 'opsx-explore.md'))
      ).rejects.toThrow();
      expect(await fs.readFile(path.join(userSkillDir, 'SKILL.md'), 'utf-8')).toBe('user skill');
      expect(
        await fs.readFile(path.join(legacyWorkflows, 'my-workflow.md'), 'utf-8')
      ).toBe('user workflow');
    });

    it('should not delete the install when the legacy root is a symlink to the current one', async () => {
      // Symlinking the two roots is a realistic way to straddle the rebrand.
      // Source and destination are then the same file, so a naive
      // "destination exists, drop the legacy copy" would delete the original.
      await updateCommand.execute(testDir);
      const devinSkill = path.join(testDir, '.devin', 'skills', 'openspec-explore');
      await fs.mkdir(devinSkill, { recursive: true });
      await fs.writeFile(path.join(devinSkill, 'SKILL.md'), 'real content');
      await fs.symlink('.devin', path.join(testDir, '.windsurf'));

      await updateCommand.execute(testDir);

      // The real file is still there, through either path
      expect(await FileSystemUtils.fileExists(path.join(devinSkill, 'SKILL.md'))).toBe(true);
    });

    it('should keep user files that live inside an OpenSpec-managed skill directory', async () => {
      // Both roots holding the same skill is the normal state after a rebrand.
      // A reference the user wrote beside SKILL.md is theirs and never moves.
      const devinSkill = path.join(testDir, '.devin', 'skills', 'openspec-explore');
      await fs.mkdir(devinSkill, { recursive: true });
      await fs.writeFile(path.join(devinSkill, 'SKILL.md'), 'current');

      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'current');
      await fs.writeFile(path.join(legacySkill, 'reference.md'), 'my notes');

      await updateCommand.execute(testDir);

      // Byte-identical to the survivor, so the redundant copy goes
      await expect(fs.access(path.join(legacySkill, 'SKILL.md'))).rejects.toThrow();
      expect(await fs.readFile(path.join(legacySkill, 'reference.md'), 'utf-8')).toBe('my notes');
    });

    it('should report divergent files even when nothing is movable', async () => {
      // Every legacy file differs from its counterpart, so there is no move to
      // make. Staying silent would leave two divergent copies the user never
      // hears about, so the result is reported rather than dropped.
      const devinSkill = path.join(testDir, '.devin', 'skills', 'openspec-explore');
      await fs.mkdir(devinSkill, { recursive: true });
      await fs.writeFile(path.join(devinSkill, 'SKILL.md'), 'current');
      const devinWorkflows = path.join(testDir, '.devin', 'workflows');
      await fs.mkdir(devinWorkflows, { recursive: true });
      await fs.writeFile(path.join(devinWorkflows, 'opsx-explore.md'), 'current');

      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'mine');
      const legacyWorkflows = path.join(testDir, '.windsurf', 'workflows');
      await fs.mkdir(legacyWorkflows, { recursive: true });
      await fs.writeFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'mine');

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);
      const logCalls = consoleSpy.mock.calls.flat().map(String);
      consoleSpy.mockRestore();

      // The divergence is surfaced...
      expect(logCalls.some((entry) => entry.includes('Left 2 files in .windsurf/'))).toBe(true);
      // ...without claiming a migration that did not happen. Matched on the
      // directory arrow rather than the word "Migrated", which also begins the
      // unrelated profile-migration line ("Migrated: custom profile with N
      // workflows") that fires only under some config states.
      expect(logCalls.some((entry) => entry.includes('.windsurf → .devin'))).toBe(false);
      expect(logCalls.some((entry) => entry.includes('Migrated 0'))).toBe(false);
      // ...and nothing was touched
      expect(await fs.readFile(path.join(legacySkill, 'SKILL.md'), 'utf-8')).toBe('mine');
      expect(await fs.readFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'utf-8')).toBe('mine');
    });

    it('should keep a legacy SKILL.md the user edited, matching how command files are treated', async () => {
      // Skills and commands must follow one rule. An earlier draft compared
      // content for commands and not for skills, so the same situation
      // destroyed a user's edited skill while preserving their edited command.
      const devinSkill = path.join(testDir, '.devin', 'skills', 'openspec-explore');
      await fs.mkdir(devinSkill, { recursive: true });
      await fs.writeFile(path.join(devinSkill, 'SKILL.md'), 'current');
      const devinWorkflows = path.join(testDir, '.devin', 'workflows');
      await fs.mkdir(devinWorkflows, { recursive: true });
      await fs.writeFile(path.join(devinWorkflows, 'opsx-explore.md'), 'current');

      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'my edited skill');
      const legacyWorkflows = path.join(testDir, '.windsurf', 'workflows');
      await fs.mkdir(legacyWorkflows, { recursive: true });
      await fs.writeFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'my edited command');

      await updateCommand.execute(testDir);

      expect(await fs.readFile(path.join(legacySkill, 'SKILL.md'), 'utf-8')).toBe(
        'my edited skill'
      );
      expect(await fs.readFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'utf-8')).toBe(
        'my edited command'
      );
    });

    it('should not carry a user file into a skill directory that commands-only delivery deletes', async () => {
      // Only SKILL.md may cross. The destination is a directory OpenSpec owns
      // and removes on its own under commands-only delivery, so moving the
      // whole legacy directory would hand the user's file to that removal.
      setMockConfig({ featureFlags: {}, profile: 'core', delivery: 'commands' });
      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'stale');
      await fs.writeFile(path.join(legacySkill, 'reference.md'), 'my notes');

      await updateCommand.execute(testDir);

      expect(await fs.readFile(path.join(legacySkill, 'reference.md'), 'utf-8')).toBe('my notes');
      await expect(fs.access(path.join(legacySkill, 'SKILL.md'))).rejects.toThrow();
    });

    it('should not carry a user file into a skill directory a deselected workflow deletes', async () => {
      // openspec-new-change is outside the core profile, so the skill
      // directory it would land in is one OpenSpec prunes.
      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-new-change');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'stale');
      await fs.writeFile(path.join(legacySkill, 'reference.md'), 'my notes');

      await updateCommand.execute(testDir);

      expect(await fs.readFile(path.join(legacySkill, 'reference.md'), 'utf-8')).toBe('my notes');
    });

    it('should still fully vacate a legacy skill directory that holds only SKILL.md', async () => {
      // The safety rule must not leave empty scaffolding behind in the
      // ordinary case, where there is nothing of the user's to preserve.
      const legacySkill = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkill, { recursive: true });
      await fs.writeFile(path.join(legacySkill, 'SKILL.md'), 'stale');

      await updateCommand.execute(testDir);

      expect(
        await FileSystemUtils.fileExists(
          path.join(testDir, '.devin', 'skills', 'openspec-explore', 'SKILL.md')
        )
      ).toBe(true);
      await expect(fs.access(path.join(testDir, '.windsurf'))).rejects.toThrow();
    });

    it('should keep a legacy command file the user edited, and drop an identical one', async () => {
      const devinWorkflows = path.join(testDir, '.devin', 'workflows');
      await fs.mkdir(devinWorkflows, { recursive: true });
      await fs.writeFile(path.join(devinWorkflows, 'opsx-explore.md'), 'generated');
      await fs.writeFile(path.join(devinWorkflows, 'opsx-apply.md'), 'generated');

      const legacyWorkflows = path.join(testDir, '.windsurf', 'workflows');
      await fs.mkdir(legacyWorkflows, { recursive: true });
      // Edited by the user — deleting it would throw the edit away
      await fs.writeFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'my edits');
      // Byte-identical — nothing is lost by dropping it
      await fs.writeFile(path.join(legacyWorkflows, 'opsx-apply.md'), 'generated');

      await updateCommand.execute(testDir);

      expect(await fs.readFile(path.join(legacyWorkflows, 'opsx-explore.md'), 'utf-8')).toBe(
        'my edits'
      );
      await expect(fs.access(path.join(legacyWorkflows, 'opsx-apply.md'))).rejects.toThrow();
    });

    it('should leave a migrated project alone on the next run', async () => {
      // The move must be idempotent: once .windsurf/ holds nothing of ours,
      // a second update has nothing to migrate and nothing to announce.
      const legacySkillDir = path.join(testDir, '.windsurf', 'skills', 'openspec-explore');
      await fs.mkdir(legacySkillDir, { recursive: true });
      await fs.writeFile(path.join(legacySkillDir, 'SKILL.md'), 'old');

      await updateCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');
      await updateCommand.execute(testDir);
      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(logCalls.some((entry) => entry.includes('.windsurf → .devin'))).toBe(false);
      consoleSpy.mockRestore();
    });
  });

  describe('error handling', () => {
    it('should preserve legacy Codex skills and prompts when canonical generation fails', async () => {
      const legacySkill = path.join(
        testDir,
        '.codex',
        'skills',
        'openspec-explore',
        'SKILL.md'
      );
      const legacyContent = 'legacy Codex skill';
      await fs.mkdir(path.dirname(legacySkill), { recursive: true });
      await fs.writeFile(legacySkill, legacyContent);

      const prompt = path.join(process.env.CODEX_HOME!, 'prompts', 'opsx-explore.md');
      await fs.mkdir(path.dirname(prompt), { recursive: true });
      await fs.writeFile(prompt, 'legacy prompt');

      const originalWriteFile = FileSystemUtils.writeFile.bind(FileSystemUtils);
      vi.spyOn(FileSystemUtils, 'writeFile').mockImplementation(async (filePath, content) => {
        if (filePath.includes(`${path.sep}.agents${path.sep}`) && filePath.endsWith('SKILL.md')) {
          throw new Error('EACCES: permission denied');
        }
        return originalWriteFile(filePath, content);
      });

      await expect(new UpdateCommand({ force: true }).execute(testDir)).rejects.toThrow(
        'OpenSpec update failed for: Codex'
      );
      expect(await fs.readFile(legacySkill, 'utf-8')).toBe(legacyContent);
      expect(await FileSystemUtils.fileExists(prompt)).toBe(true);
    });

    it('should report tool update failures to automation', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Mock writeFile to fail for skills
      const originalWriteFile = FileSystemUtils.writeFile.bind(FileSystemUtils);
      const writeSpy = vi
        .spyOn(FileSystemUtils, 'writeFile')
        .mockImplementation(async (filePath, content) => {
          if (filePath.includes('SKILL.md')) {
            throw new Error('EACCES: permission denied');
          }
          return originalWriteFile(filePath, content);
        });

      const consoleSpy = vi.spyOn(console, 'log');

      await expect(updateCommand.execute(testDir)).rejects.toThrow(
        'OpenSpec update failed for: Claude Code'
      );

      // Should report failure
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Failed')
      );

      writeSpy.mockRestore();
      consoleSpy.mockRestore();
    });

    it('should continue updating other tools when one fails', async () => {
      // Set up Claude and Cursor
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const cursorSkillsDir = path.join(testDir, '.cursor', 'skills');
      await fs.mkdir(path.join(cursorSkillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(cursorSkillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Mock writeFile to fail only for Claude
      const originalWriteFile = FileSystemUtils.writeFile.bind(FileSystemUtils);
      const writeSpy = vi
        .spyOn(FileSystemUtils, 'writeFile')
        .mockImplementation(async (filePath, content) => {
          if (filePath.includes('.claude') && filePath.includes('SKILL.md')) {
            throw new Error('EACCES: permission denied');
          }
          return originalWriteFile(filePath, content);
        });

      const consoleSpy = vi.spyOn(console, 'log');

      await expect(updateCommand.execute(testDir)).rejects.toThrow(
        'OpenSpec update failed for: Claude Code'
      );

      // Cursor should still be updated - check the actual format from ora spinner
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Cursor')
      );

      // Claude should be reported as failed
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Failed')
      );

      // Cursor succeeded, so its IDE process still needs to reload the changes.
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Restart your IDE')
      );

      writeSpy.mockRestore();
      consoleSpy.mockRestore();
    });

    it('should not suggest an IDE restart when only the IDE tool fails', async () => {
      const claudeSkill = path.join(testDir, '.claude', 'skills', 'openspec-explore', 'SKILL.md');
      const cursorSkill = path.join(testDir, '.cursor', 'skills', 'openspec-explore', 'SKILL.md');
      await fs.mkdir(path.dirname(claudeSkill), { recursive: true });
      await fs.mkdir(path.dirname(cursorSkill), { recursive: true });
      await fs.writeFile(claudeSkill, 'old');
      await fs.writeFile(cursorSkill, 'old');

      const originalWriteFile = FileSystemUtils.writeFile.bind(FileSystemUtils);
      vi.spyOn(FileSystemUtils, 'writeFile').mockImplementation(async (filePath, content) => {
        if (filePath.includes('.cursor') && filePath.includes('SKILL.md')) {
          throw new Error('EACCES: permission denied');
        }
        return originalWriteFile(filePath, content);
      });

      const consoleSpy = vi.spyOn(console, 'log');

      await expect(updateCommand.execute(testDir)).rejects.toThrow(
        'OpenSpec update failed for: Cursor'
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Claude Code')
      );
      expect(consoleSpy).not.toHaveBeenCalledWith(
        expect.stringContaining('Restart your IDE')
      );
    });
  });

  describe('tool detection', () => {
    it('should detect tool as configured only when skill file exists', async () => {
      // Create skills directory but no skill files
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(skillsDir, { recursive: true });

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should report no configured tools
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('No configured tools found')
      );

      consoleSpy.mockRestore();
    });

    it('should detect tool when any single skill exists', async () => {
      // Create only one skill file
      const skillDir = path.join(
        testDir,
        '.claude',
        'skills',
        'openspec-archive-change'
      );
      await fs.mkdir(skillDir, { recursive: true });
      await fs.writeFile(path.join(skillDir, 'SKILL.md'), 'old');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should detect and update Claude
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updating 1 tool(s): claude')
      );

      consoleSpy.mockRestore();
    });
  });

  describe('skill content validation', () => {
    it('should generate valid YAML frontmatter in skill files', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      await updateCommand.execute(testDir);

      const skillContent = await fs.readFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );

      // Validate frontmatter structure
      expect(skillContent).toMatch(/^---\n/);
      expect(skillContent).toContain('name:');
      expect(skillContent).toContain('description:');
      expect(skillContent).toContain('license:');
      expect(skillContent).toContain('compatibility:');
      expect(skillContent).toContain('metadata:');
      expect(skillContent).toContain('author:');
      expect(skillContent).toContain('version:');
      expect(skillContent).toMatch(/---\n\n/);
    });

    it('should include proper instructions in skill files', async () => {
      // Set up a configured tool with apply-change skill (which is in core profile)
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-apply-change'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-apply-change', 'SKILL.md'),
        'old'
      );

      await updateCommand.execute(testDir);

      const skillContent = await fs.readFile(
        path.join(skillsDir, 'openspec-apply-change', 'SKILL.md'),
        'utf-8'
      );

      // Apply skill should contain implementation instructions
      expect(skillContent.toLowerCase()).toContain('task');
    });
  });

  describe('success output', () => {
    it('should display success message with tool name', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // The success output uses "✓ Updated: <name>"
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Claude Code')
      );

      consoleSpy.mockRestore();
    });

    it('should not suggest an IDE restart for CLI-only tools', async () => {
      // Set up a configured CLI tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      expect(consoleSpy).not.toHaveBeenCalledWith(
        expect.stringContaining('Restart your IDE')
      );

      consoleSpy.mockRestore();
    });

    it('should suggest an IDE restart for IDE-resident tools', async () => {
      const skillsDir = path.join(testDir, '.cursor', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Restart your IDE')
      );

      consoleSpy.mockRestore();
    });
  });

  describe('smart update detection', () => {
    it('should show "up to date" message when skills have current version', async () => {
      // Initialize full core profile output so there is no profile/delivery drift.
      const initCommand = new InitCommand({ tools: 'claude', force: true });
      await initCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('up to date')
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('--force')
      );

      consoleSpy.mockRestore();
    });

    it('should create GitHub Copilot cloud files when github-copilot is up to date', async () => {
      const initCommand = new InitCommand({ tools: 'github-copilot', force: true, copilotCloud: true });
      await initCommand.execute(testDir);

      const setupStepsPath = path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml');
      const agentPath = path.join(testDir, '.github', 'agents', 'openspec.agent.md');
      await fs.rm(setupStepsPath, { force: true });
      await fs.rm(agentPath, { force: true });

      await updateCommand.execute(testDir);

      await expect(fs.readFile(setupStepsPath, 'utf8')).resolves.toContain('copilot-setup-steps:');
      await expect(fs.readFile(agentPath, 'utf8')).resolves.toContain('# OpenSpec Agent');
    });

    it('should refresh managed legacy Copilot files and preserve custom files during force update', async () => {
      const initCommand = new InitCommand({ tools: 'github-copilot', force: true, copilotCloud: true });
      await initCommand.execute(testDir);

      const setupStepsPath = path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml');
      const agentPath = path.join(testDir, '.github', 'agents', 'openspec.agent.md');
      const legacySetupSteps = generateCopilotSetupSteps().replace(
        /^# Generated by OpenSpec for GitHub Copilot coding agent support\.\n\n/,
        ''
      );
      const customAgent = 'custom Copilot agent';
      await fs.writeFile(setupStepsPath, legacySetupSteps);
      await fs.writeFile(agentPath, customAgent);

      await new UpdateCommand({ force: true }).execute(testDir);

      await expect(fs.readFile(setupStepsPath, 'utf8')).resolves.toBe(
        generateCopilotSetupSteps()
      );
      await expect(fs.readFile(agentPath, 'utf8')).resolves.toBe(customAgent);
    });

    it('should not create cloud files on update when Copilot is configured but not opted in', async () => {
      // Seed a configured github-copilot WITHOUT opting into cloud files.
      const initCommand = new InitCommand({ tools: 'github-copilot', force: true });
      await initCommand.execute(testDir);

      await updateCommand.execute(testDir);

      await expect(
        fs.stat(path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml'))
      ).rejects.toMatchObject({ code: 'ENOENT' });
      await expect(
        fs.stat(path.join(testDir, '.github', 'agents', 'openspec.agent.md'))
      ).rejects.toMatchObject({ code: 'ENOENT' });
    });

    it('should refresh pre-existing managed cloud files even without a config opt-in (migration)', async () => {
      // A project created before the opt-in existed: managed files are present
      // but config carries no githubCopilot key. Update must keep them current.
      const initCommand = new InitCommand({ tools: 'github-copilot', force: true });
      await initCommand.execute(testDir);

      const setupStepsPath = path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml');
      const legacySetupSteps = generateCopilotSetupSteps().replace(
        /^# Generated by OpenSpec for GitHub Copilot coding agent support\.\n\n/,
        ''
      );
      await fs.mkdir(path.dirname(setupStepsPath), { recursive: true });
      await fs.writeFile(setupStepsPath, legacySetupSteps);

      await new UpdateCommand({ force: true }).execute(testDir);

      await expect(fs.readFile(setupStepsPath, 'utf8')).resolves.toBe(generateCopilotSetupSteps());
    });

    it('should remove managed cloud files on update when the user has opted out', async () => {
      await new InitCommand({ tools: 'github-copilot', force: true, copilotCloud: true }).execute(testDir);
      const setupStepsPath = path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml');
      const agentPath = path.join(testDir, '.github', 'agents', 'openspec.agent.md');
      expect(await fs.stat(setupStepsPath)).toBeTruthy();

      await persistCopilotCloudOptIn(testDir, false); // explicit opt-out

      await new UpdateCommand({ force: true }).execute(testDir);

      await expect(fs.stat(setupStepsPath)).rejects.toMatchObject({ code: 'ENOENT' });
      await expect(fs.stat(agentPath)).rejects.toMatchObject({ code: 'ENOENT' });
    });

    it('should preserve a customized cloud file on update even when opted out', async () => {
      await new InitCommand({ tools: 'github-copilot', force: true, copilotCloud: true }).execute(testDir);
      const setupStepsPath = path.join(testDir, '.github', 'workflows', 'copilot-setup-steps.yml');
      await fs.writeFile(setupStepsPath, 'name: my own workflow\n');

      await persistCopilotCloudOptIn(testDir, false); // explicit opt-out

      await new UpdateCommand({ force: true }).execute(testDir);

      // A user-customized file is never removed, even on opt-out.
      await expect(fs.readFile(setupStepsPath, 'utf8')).resolves.toBe('name: my own workflow\n');
    });

    it('should warn when GitHub Copilot cloud files cannot be synchronized', async () => {
      const initCommand = new InitCommand({ tools: 'github-copilot', force: true, copilotCloud: true });
      await initCommand.execute(testDir);

      const agentsPath = path.join(testDir, '.github', 'agents');
      await fs.rm(agentsPath, { recursive: true, force: true });
      await fs.writeFile(agentsPath, 'blocks the generated agent directory');
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});

      await updateCommand.execute(testDir);

      expect(warnSpy).toHaveBeenCalledWith(
        expect.stringContaining('failed to sync Copilot cloud agent files')
      );
    });

    it('should detect update needed when generatedBy is missing', async () => {
      // Set up a configured tool without generatedBy
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        `---
name: openspec-explore
metadata:
  author: openspec
  version: "1.0"
---

Legacy content without generatedBy
`
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should show "unknown → version" in the update message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('unknown')
      );

      consoleSpy.mockRestore();
    });

    it('should detect update needed when version differs', async () => {
      // Set up a configured tool with old version
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        `---
name: openspec-explore
metadata:
  generatedBy: "0.1.0"
---

Old version content
`
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should show version transition
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('0.1.0')
      );

      consoleSpy.mockRestore();
    });

    it('should embed generatedBy in updated skill files', async () => {
      // Set up a configured tool without generatedBy
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old content without version'
      );

      await updateCommand.execute(testDir);

      const updatedContent = await fs.readFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );

      // Should contain generatedBy field
      expect(updatedContent).toMatch(/generatedBy:\s*["']\d+\.\d+\.\d+["']/);
    });
  });

  describe('--force flag', () => {
    it('should update when force is true even if up to date', async () => {
      // Set up a configured tool with current version
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });

      const { version } = await import('../../package.json');
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        `---
metadata:
  generatedBy: "${version}"
---
Content
`
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show "Force updating" message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Force updating')
      );

      // Should show updated message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Claude Code')
      );

      consoleSpy.mockRestore();
    });

    it('should not show --force hint when force is used', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Get all console.log calls as strings
      const allCalls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );

      // Should not show "Use --force" since force was used
      const hasForceHint = allCalls.some(call => call.includes('Use --force'));
      expect(hasForceHint).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should update all tools when force is used with mixed versions', async () => {
      // Set up Claude with current version
      const { version } = await import('../../package.json');
      const claudeSkillDir = path.join(testDir, '.claude', 'skills', 'openspec-explore');
      await fs.mkdir(claudeSkillDir, { recursive: true });
      await fs.writeFile(
        path.join(claudeSkillDir, 'SKILL.md'),
        `---
metadata:
  generatedBy: "${version}"
---
`
      );

      // Set up Cursor with old version
      const cursorSkillDir = path.join(testDir, '.cursor', 'skills', 'openspec-explore');
      await fs.mkdir(cursorSkillDir, { recursive: true });
      await fs.writeFile(
        path.join(cursorSkillDir, 'SKILL.md'),
        `---
metadata:
  generatedBy: "0.1.0"
---
`
      );

      const consoleSpy = vi.spyOn(console, 'log');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show both tools being force updated
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Force updating 2 tool(s)')
      );

      consoleSpy.mockRestore();
    });
  });

  describe('version tracking', () => {
    it('should show version in success message', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should show version in success message
      const { version } = await import('../../package.json');
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining(`(v${version})`)
      );

      consoleSpy.mockRestore();
    });

    it('should only update tools that need updating', async () => {
      // Initialize both tools so Cursor is fully synced with profile/delivery.
      const initCommand = new InitCommand({ tools: 'claude,cursor', force: true });
      await initCommand.execute(testDir);

      // Make Claude stale to force a version update.
      const claudeSkillFile = path.join(testDir, '.claude', 'skills', 'openspec-explore', 'SKILL.md');
      const claudeContent = await fs.readFile(claudeSkillFile, 'utf-8');
      await fs.writeFile(
        claudeSkillFile,
        claudeContent.replace(/generatedBy:\s*["'][^"']+["']/, 'generatedBy: "0.1.0"')
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should show only Claude being updated
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updating 1 tool(s)')
      );

      // Should mention Cursor is already up to date
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Already up to date: cursor')
      );

      // A configured IDE tool that was not affected must not cause the hint.
      expect(consoleSpy).not.toHaveBeenCalledWith(
        expect.stringContaining('Restart your IDE')
      );

      consoleSpy.mockRestore();
    });
  });

  describe('legacy cleanup', () => {
    it('should detect and auto-cleanup legacy files with --force flag', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Create legacy CLAUDE.md with OpenSpec markers
      const legacyContent = `${OPENSPEC_MARKERS.start}
# OpenSpec Instructions

These instructions are for AI assistants.
${OPENSPEC_MARKERS.end}
`;
      await fs.writeFile(path.join(testDir, 'CLAUDE.md'), legacyContent);

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show v1 upgrade message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Upgrading to the new OpenSpec')
      );

      // Should show marker removal message (config files are never deleted, only have markers removed)
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Removed OpenSpec markers from CLAUDE.md')
      );

      // Config file should still exist (never deleted)
      const legacyExists = await FileSystemUtils.fileExists(
        path.join(testDir, 'CLAUDE.md')
      );
      expect(legacyExists).toBe(true);

      // File should have markers removed
      const content = await fs.readFile(path.join(testDir, 'CLAUDE.md'), 'utf-8');
      expect(content).not.toContain(OPENSPEC_MARKERS.start);
      expect(content).not.toContain(OPENSPEC_MARKERS.end);

      consoleSpy.mockRestore();
    });

    it('should remove managed global Codex opsx prompts with --force and preserve unmanaged prompts', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const skillsDir = path.join(testDir, '.agents', 'skills');
      await markCodexTarget(skillsDir);
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, 'opsx-explore.md');
      const legacyPrompt = path.join(promptDir, 'openspec-proposal.md');
      const unmanagedPrompt = path.join(promptDir, 'personal-notes.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'legacy explore prompt');
      await fs.writeFile(legacyPrompt, 'managed');
      await fs.writeFile(unmanagedPrompt, 'user');

      const consoleSpy = vi.spyOn(console, 'log');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Deferred global prompts cleanup')
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining(`codex: ${managedPrompt}`)
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining(`Removed ${managedPrompt} (replaced by Codex skills)`)
      );
      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(false);
      expect(await FileSystemUtils.fileExists(legacyPrompt)).toBe(true);
      expect(await FileSystemUtils.fileExists(unmanagedPrompt)).toBe(true);

      const skillFile = path.join(skillsDir, 'openspec-explore', 'SKILL.md');
      expect(await FileSystemUtils.fileExists(skillFile)).toBe(true);
      const skillContent = await fs.readFile(skillFile, 'utf-8');
      expect(skillContent).toContain('name: openspec-explore');

      consoleSpy.mockRestore();
    });

    it('should infer Codex replacement workflows from legacy prompt filenames during forced update', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, 'opsx-explore.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'legacy explore prompt');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(false);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', 'openspec-explore', 'SKILL.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', 'openspec-apply-change', 'SKILL.md')
      )).toBe(false);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', 'openspec-archive-change', 'SKILL.md')
      )).toBe(false);
    });

    it.each([
      ['opsx-archive.md', 'openspec-archive-change'],
      ['opsx-bulk-archive.md', 'openspec-bulk-archive-change'],
    ])('should include sync when replacing legacy Codex %s', async (promptName, archiveSkill) => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, promptName);
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'legacy archive prompt');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(false);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', archiveSkill, 'SKILL.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', 'openspec-sync-specs', 'SKILL.md')
      )).toBe(true);
    });

    it('should print a skill-based getting-started menu when a legacy upgrade newly configures codex', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      // Legacy managed Codex prompt with codex not yet configured: the
      // upgrade newly configures codex, whose onboarding menu must not
      // advertise /opsx:* commands (codex has no slash surface).
      // The prompt is opsx-new.md so the inferred workflow ('new') is one the
      // onboarding menu actually lists — the menu is now filtered to the
      // workflows the upgrade installed.
      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(path.join(promptDir, 'opsx-new.md'), 'legacy new prompt');

      const consoleSpy = vi.spyOn(console, 'log');
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      consoleSpy.mockRestore();

      expect(logCalls.some((entry) => entry.includes('Getting started'))).toBe(true);
      const menuLines = logCalls.filter((entry) => entry.includes('Scaffold a change'));
      expect(menuLines).toHaveLength(1);
      expect(menuLines[0]).toContain('$openspec-new-change');
      expect(logCalls.some((entry) => entry.includes('/opsx:new'))).toBe(false);
      expect(logCalls.some((entry) => entry.includes('/opsx:continue'))).toBe(false);
      expect(logCalls.some((entry) => entry.includes('/opsx:apply'))).toBe(false);
      // Only the inferred workflow is advertised, not the rest of the profile
      expect(logCalls.some((entry) => entry.includes('Next artifact'))).toBe(false);
      expect(logCalls.some((entry) => entry.includes('Implement tasks'))).toBe(false);
    });

    it('should print the hyphen getting-started menu when a legacy upgrade newly configures cursor', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'both',
      });

      // A pre-opsx Cursor project: legacy .cursor/commands/openspec-*.md files
      // make the upgrade newly configure cursor, whose menu must name the
      // commands its palette registers (/opsx-propose), not /opsx:propose.
      const legacyDir = path.join(testDir, '.cursor', 'commands');
      await fs.mkdir(legacyDir, { recursive: true });
      await fs.writeFile(path.join(legacyDir, 'openspec-proposal.md'), 'legacy proposal command');

      const consoleSpy = vi.spyOn(console, 'log');
      await new UpdateCommand({ force: true }).execute(testDir);
      const logCalls = consoleSpy.mock.calls.flat().map(String);
      consoleSpy.mockRestore();

      const menuLines = logCalls.filter((entry) => entry.includes('Start a change'));
      expect(menuLines).toHaveLength(1);
      expect(menuLines[0]).toContain('/opsx-propose');
      expect(logCalls.some((entry) => entry.includes('/opsx:propose'))).toBe(false);
      expect(logCalls.some((entry) => entry.includes('Restart your IDE'))).toBe(true);
    });

    it('should preserve legacy Codex prompts when a configured Codex tool lacks the replacement workflow', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const skillsDir = path.join(testDir, '.agents', 'skills');
      await markCodexTarget(skillsDir);
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, 'opsx-onboard.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'legacy onboard prompt');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(testDir, '.agents', 'skills', 'openspec-onboard', 'SKILL.md')
      )).toBe(false);
    });

    it('should install a missing Codex update skill before removing its prompt in the same forced run', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const skillsDir = path.join(testDir, '.agents', 'skills');
      await markCodexTarget(skillsDir);
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, 'opsx-update.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'prompt generated by OpenSpec v1.6.0');

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-update-change', 'SKILL.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(false);
    });

    it('should warn but continue with update when legacy files found in non-interactive mode', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Create legacy CLAUDE.md with OpenSpec markers
      const legacyContent = `${OPENSPEC_MARKERS.start}
# OpenSpec Instructions
${OPENSPEC_MARKERS.end}
`;
      await fs.writeFile(path.join(testDir, 'CLAUDE.md'), legacyContent);

      const consoleSpy = vi.spyOn(console, 'log');

      // Run without --force in non-interactive mode (CI environment)
      await updateCommand.execute(testDir);

      // Should show v1 upgrade message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Upgrading to the new OpenSpec')
      );

      // Should show warning about --force
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Run with --force to auto-cleanup')
      );

      // Should continue with update
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Claude Code')
      );

      // Legacy file should still exist (not cleaned up)
      const legacyExists = await FileSystemUtils.fileExists(
        path.join(testDir, 'CLAUDE.md')
      );
      expect(legacyExists).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should cleanup legacy slash command directories with --force', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Create legacy slash command directory
      const legacyCommandDir = path.join(testDir, '.claude', 'commands', 'openspec');
      await fs.mkdir(legacyCommandDir, { recursive: true });
      await fs.writeFile(
        path.join(legacyCommandDir, 'old-command.md'),
        'old command'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show cleanup message for directory
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Removed .claude/commands/openspec/')
      );

      // Legacy directory should be deleted
      const legacyDirExists = await FileSystemUtils.directoryExists(legacyCommandDir);
      expect(legacyDirExists).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should cleanup legacy openspec/AGENTS.md with --force', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Create legacy openspec/AGENTS.md
      await fs.writeFile(
        path.join(testDir, 'openspec', 'AGENTS.md'),
        '# Old AGENTS.md content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show cleanup message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Removed openspec/AGENTS.md')
      );

      // Legacy file should be deleted
      const legacyExists = await FileSystemUtils.fileExists(
        path.join(testDir, 'openspec', 'AGENTS.md')
      );
      expect(legacyExists).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should not show legacy cleanup messages when no legacy files exist', async () => {
      // Set up a configured tool with no legacy files
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should not show v1 upgrade message (no legacy files)
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasLegacyMessage = calls.some(call =>
        call.includes('Upgrading to the new OpenSpec')
      );
      expect(hasLegacyMessage).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should remove OpenSpec marker block from mixed content files', async () => {
      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), {
        recursive: true,
      });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old'
      );

      // Create CLAUDE.md with mixed content (user content + OpenSpec markers)
      const mixedContent = `# My Project

Some user-defined instructions here.

${OPENSPEC_MARKERS.start}
# OpenSpec Instructions

These instructions are for AI assistants.
${OPENSPEC_MARKERS.end}

More user content after markers.
`;
      await fs.writeFile(path.join(testDir, 'CLAUDE.md'), mixedContent);

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show marker removal message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Removed OpenSpec markers from CLAUDE.md')
      );

      // File should still exist
      const fileExists = await FileSystemUtils.fileExists(
        path.join(testDir, 'CLAUDE.md')
      );
      expect(fileExists).toBe(true);

      // File should have markers removed but preserve user content
      const updatedContent = await fs.readFile(
        path.join(testDir, 'CLAUDE.md'),
        'utf-8'
      );
      expect(updatedContent).toContain('# My Project');
      expect(updatedContent).toContain('Some user-defined instructions here');
      expect(updatedContent).toContain('More user content after markers');
      expect(updatedContent).not.toContain(OPENSPEC_MARKERS.start);
      expect(updatedContent).not.toContain(OPENSPEC_MARKERS.end);

      consoleSpy.mockRestore();
    });
  });

  describe('legacy tool upgrade', () => {
    it('should upgrade legacy tools to new skills with --force', async () => {
      // Create legacy slash command directory (no skills exist yet)
      const legacyCommandDir = path.join(testDir, '.claude', 'commands', 'openspec');
      await fs.mkdir(legacyCommandDir, { recursive: true });
      await fs.writeFile(
        path.join(legacyCommandDir, 'proposal.md'),
        'old command content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should show detected tools message
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Tools detected from legacy artifacts')
      );

      // Should show Claude Code being set up
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Claude Code')
      );

      // Should show getting started message for newly configured tools,
      // limited to the commands the core profile installs (not new/continue)
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Getting started')
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('/opsx:propose')
      );
      const gettingStartedCalls = consoleSpy.mock.calls
        .map((call) => call.map((arg) => String(arg)).join(' '))
        .join('\n');
      expect(gettingStartedCalls).not.toContain('/opsx:new');
      expect(gettingStartedCalls).not.toContain('/opsx:continue');
      expect(gettingStartedCalls).not.toContain('Restart your IDE');

      // Skills should be created
      const skillFile = path.join(testDir, '.claude', 'skills', 'openspec-explore', 'SKILL.md');
      const skillExists = await FileSystemUtils.fileExists(skillFile);
      expect(skillExists).toBe(true);

      // Legacy directory should be deleted
      const legacyDirExists = await FileSystemUtils.directoryExists(legacyCommandDir);
      expect(legacyDirExists).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should upgrade multiple legacy tools with --force', async () => {
      // Create legacy command directories for Claude and Cursor
      await fs.mkdir(path.join(testDir, '.claude', 'commands', 'openspec'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.claude', 'commands', 'openspec', 'proposal.md'),
        'content'
      );

      await fs.mkdir(path.join(testDir, '.cursor', 'commands'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.cursor', 'commands', 'openspec-proposal.md'),
        'content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should detect both tools
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Tools detected from legacy artifacts')
      );

      // Both tools should have skills created
      const claudeSkillFile = path.join(testDir, '.claude', 'skills', 'openspec-explore', 'SKILL.md');
      const cursorSkillFile = path.join(testDir, '.cursor', 'skills', 'openspec-explore', 'SKILL.md');

      expect(await FileSystemUtils.fileExists(claudeSkillFile)).toBe(true);
      expect(await FileSystemUtils.fileExists(cursorSkillFile)).toBe(true);

      consoleSpy.mockRestore();
    });

    it('arbitrates legacy Antigravity and Codex before writing the shared tree', async () => {
      const antigravityLegacy = path.join(
        testDir,
        '.agent',
        'workflows',
        'openspec-propose.md'
      );
      const codexLegacy = path.join(testDir, '.codex', 'prompts', 'openspec-propose.md');
      await fs.mkdir(path.dirname(antigravityLegacy), { recursive: true });
      await fs.mkdir(path.dirname(codexLegacy), { recursive: true });
      await fs.writeFile(antigravityLegacy, 'legacy Antigravity command');
      await fs.writeFile(codexLegacy, 'legacy Codex prompt');

      await new UpdateCommand({ force: true }).execute(testDir);

      const skillsDir = path.join(testDir, '.agents', 'skills');
      expect(await fs.readFile(path.join(skillsDir, '.openspec-target'), 'utf-8')).toBe('codex\n');
      const proposeSkill = await fs.readFile(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md'),
        'utf-8'
      );
      expect(proposeSkill).toContain('$openspec-apply-change');
      expect(proposeSkill).toContain('/openspec-apply-change');
      await expect(
        fs.access(path.join(testDir, '.agents', 'workflows', 'opsx-propose.md'))
      ).resolves.toBeUndefined();
    });

    it('should not upgrade legacy tools already configured', async () => {
      // Set up a configured Claude tool with skills
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'existing skill'
      );

      // Also create legacy directory (simulating partial upgrade)
      const legacyCommandDir = path.join(testDir, '.claude', 'commands', 'openspec');
      await fs.mkdir(legacyCommandDir, { recursive: true });
      await fs.writeFile(
        path.join(legacyCommandDir, 'proposal.md'),
        'old command'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Legacy cleanup should happen
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Removed .claude/commands/openspec/')
      );

      // Should NOT show "Tools detected from legacy artifacts" because claude is already configured
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasDetectedMessage = calls.some(call =>
        call.includes('Tools detected from legacy artifacts')
      );
      expect(hasDetectedMessage).toBe(false);

      // Should update existing skills (not "Getting started" for newly configured)
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Claude Code')
      );

      consoleSpy.mockRestore();
    });

    it('should upgrade only unconfigured legacy tools when mixed', async () => {
      // Set up configured Claude tool with skills
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(
        path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'),
        'existing skill'
      );

      // Create legacy commands for both Claude (configured) and Cursor (not configured)
      await fs.mkdir(path.join(testDir, '.claude', 'commands', 'openspec'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.claude', 'commands', 'openspec', 'proposal.md'),
        'content'
      );

      await fs.mkdir(path.join(testDir, '.cursor', 'commands'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.cursor', 'commands', 'openspec-proposal.md'),
        'content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Should detect Cursor as a legacy tool to upgrade (but not Claude)
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Tools detected from legacy artifacts')
      );

      // Cursor skills should be created
      const cursorSkillFile = path.join(testDir, '.cursor', 'skills', 'openspec-explore', 'SKILL.md');
      expect(await FileSystemUtils.fileExists(cursorSkillFile)).toBe(true);

      // Should show "Getting started" for newly configured Cursor
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Getting started')
      );

      consoleSpy.mockRestore();
    });

    it('should list the expanded commands a custom profile installs', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'both',
        workflows: ['new', 'continue', 'apply'],
      });

      const legacyCommandDir = path.join(testDir, '.claude', 'commands', 'openspec');
      await fs.mkdir(legacyCommandDir, { recursive: true });
      await fs.writeFile(
        path.join(legacyCommandDir, 'proposal.md'),
        'old command content'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await new UpdateCommand({ force: true }).execute(testDir);

      const output = consoleSpy.mock.calls
        .map((call) => call.map((arg) => String(arg)).join(' '))
        .join('\n');
      expect(output).toContain('/opsx:new');
      expect(output).toContain('/opsx:continue');
      expect(output).not.toContain('/opsx:propose');

      consoleSpy.mockRestore();
    });

    it('should not show getting started message when no new tools configured', async () => {
      // Set up a configured tool (no legacy artifacts)
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'old skill'
      );

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should NOT show "Getting started" message
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasGettingStarted = calls.some(call =>
        call.includes('Getting started')
      );
      expect(hasGettingStarted).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should create only effective profile skills when upgrading legacy tools', async () => {
      // Create legacy command directory
      await fs.mkdir(path.join(testDir, '.claude', 'commands', 'openspec'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.claude', 'commands', 'openspec', 'proposal.md'),
        'content'
      );

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // Default profile is core, so only core workflows should be generated.
      const skillNames = [
        'openspec-propose',
        'openspec-explore',
        'openspec-apply-change',
        'openspec-sync-specs',
        'openspec-archive-change',
      ];

      const skillsDir = path.join(testDir, '.claude', 'skills');
      for (const skillName of skillNames) {
        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
        const exists = await FileSystemUtils.fileExists(skillFile);
        expect(exists).toBe(true);
      }

      const nonCoreSkill = path.join(skillsDir, 'openspec-new-change', 'SKILL.md');
      expect(await FileSystemUtils.fileExists(nonCoreSkill)).toBe(false);
    });

    it('should create commands when upgrading legacy tools', async () => {
      // Create legacy command directory
      await fs.mkdir(path.join(testDir, '.claude', 'commands', 'openspec'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.claude', 'commands', 'openspec', 'proposal.md'),
        'content'
      );

      // Create update command with force option
      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      // New opsx commands should be created
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      const exploreCmd = path.join(commandsDir, 'explore.md');
      const exists = await FileSystemUtils.fileExists(exploreCmd);
      expect(exists).toBe(true);
    });

    it('should not inject non-profile workflows when upgrading legacy tools', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'both',
        workflows: ['explore'],
      });

      await fs.mkdir(path.join(testDir, '.claude', 'commands', 'openspec'), { recursive: true });
      await fs.writeFile(
        path.join(testDir, '.claude', 'commands', 'openspec', 'proposal.md'),
        'content'
      );

      const forceUpdateCommand = new UpdateCommand({ force: true });
      await forceUpdateCommand.execute(testDir);

      const skillsDir = path.join(testDir, '.claude', 'skills');
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md')
      )).toBe(false);

      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'explore.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'propose.md')
      )).toBe(false);
    });
  });

  describe('profile-aware updates', () => {
    it('should generate only profile workflows when custom profile is set', async () => {
      // Set custom profile with only explore and new
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'both',
        workflows: ['explore', 'new'],
      });

      // Set up a configured tool
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      await updateCommand.execute(testDir);

      // Should create explore and new skills
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-new-change', 'SKILL.md')
      )).toBe(true);

      // Should NOT create non-profile skills
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-apply-change', 'SKILL.md')
      )).toBe(false);
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-propose', 'SKILL.md')
      )).toBe(false);
    });

    it.each(['skills', 'commands', 'both'] as const)(
      'should repair an archive profile missing sync with %s delivery',
      async (delivery) => {
        setMockConfig({
          featureFlags: {},
          profile: 'custom',
          delivery,
          workflows: ['propose', 'explore', 'apply', 'archive'],
        });

        const archiveSkill = path.join(
          testDir,
          '.claude',
          'skills',
          'openspec-archive-change',
          'SKILL.md'
        );
        const archiveCommand = path.join(
          testDir,
          '.claude',
          'commands',
          'opsx',
          'archive.md'
        );
        if (delivery !== 'commands') {
          await fs.mkdir(path.dirname(archiveSkill), { recursive: true });
          await fs.writeFile(archiveSkill, 'old archive skill');
        }
        if (delivery !== 'skills') {
          await fs.mkdir(path.dirname(archiveCommand), { recursive: true });
          await fs.writeFile(archiveCommand, 'old archive command');
        }

        const consoleSpy = vi.spyOn(console, 'log');

        await updateCommand.execute(testDir);

        const calls = consoleSpy.mock.calls.map(call =>
          call.map(arg => String(arg)).join(' ')
        );
        expect(calls.some(call =>
          call.includes('Your custom profile is missing 1 core workflow: update')
        )).toBe(true);
        expect(calls.some(call =>
          call.includes('openspec config profile core')
        )).toBe(true);

        expect(await FileSystemUtils.fileExists(
          path.join(testDir, '.claude', 'skills', 'openspec-sync-specs', 'SKILL.md')
        )).toBe(delivery !== 'commands');
        expect(await FileSystemUtils.fileExists(
          path.join(testDir, '.claude', 'commands', 'opsx', 'sync.md')
        )).toBe(delivery !== 'skills');

        consoleSpy.mockRestore();
      }
    );

    it('should list a single missing core workflow when custom profile lacks only update', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'both',
        workflows: ['propose', 'explore', 'apply', 'sync', 'archive'],
      });

      const initCommand = new InitCommand({ tools: 'claude', force: true });
      await initCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      expect(calls.some(call =>
        call.includes('Your custom profile is missing 1 core workflow: update')
      )).toBe(true);
      expect(calls.some(call =>
        call.includes('to add it, or')
      )).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should not display a missing-core note when custom profile covers core workflows', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'custom',
        delivery: 'both',
        workflows: ['propose', 'explore', 'apply', 'update', 'sync', 'archive', 'verify'],
      });

      const initCommand = new InitCommand({ tools: 'claude', force: true });
      await initCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      expect(calls.some(call =>
        call.includes('Your custom profile is missing')
      )).toBe(false);

      consoleSpy.mockRestore();
    });

    it('should respect skills-only delivery setting', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      await updateCommand.execute(testDir);

      // Skills should be created
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(true);

      // Commands should NOT be created
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'explore.md')
      )).toBe(false);

      // Skill content should reference skills, not commands that were never generated
      const skillContent = await fs.readFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        'utf-8'
      );
      expect(skillContent).not.toContain('/opsx:');
      expect(skillContent).not.toContain('/opsx-');
      expect(skillContent).toContain('/openspec-');

      // update-change references several other workflows; a command missing
      // from the reference map would leave a raw /opsx: reference behind
      const updateSkillContent = await fs.readFile(
        path.join(skillsDir, 'openspec-update-change', 'SKILL.md'),
        'utf-8'
      );
      expect(updateSkillContent).not.toContain('/opsx:');
      expect(updateSkillContent).not.toContain('/opsx-');
      expect(updateSkillContent).toContain('/openspec-');
    });

    it.each(['skills', 'commands'] as const)(
      'should switch SourceCraft Code Assistant to delivery=%s without deleting custom files',
      async (delivery) => {
        await new InitCommand({ tools: 'codeassistant', force: true }).execute(testDir);
        const toolDir = path.join(testDir, '.codeassistant');
        const customCommand = path.join(toolDir, 'commands', 'opsx-custom.md');
        const customSkill = path.join(toolDir, 'skills', 'custom-review', 'SKILL.md');
        await fs.mkdir(path.dirname(customSkill), { recursive: true });
        await fs.writeFile(customCommand, 'custom command');
        await fs.writeFile(customSkill, 'custom skill');

        setMockConfig({ featureFlags: {}, profile: 'core', delivery });
        await updateCommand.execute(testDir);

        expect(await FileSystemUtils.fileExists(path.join(toolDir, 'commands', 'opsx-apply.md'))).toBe(delivery === 'commands');
        const skillFile = path.join(toolDir, 'skills', 'openspec-apply-change', 'SKILL.md');
        expect(await FileSystemUtils.fileExists(skillFile)).toBe(delivery === 'skills');
        if (delivery === 'skills') {
          const skillContent = await fs.readFile(skillFile, 'utf-8');
          expect(skillContent).toContain('the openspec-archive-change skill');
          expect(skillContent).not.toContain('/openspec-');
          expect(skillContent).not.toContain('/opsx-');
        }
        expect(await fs.readFile(customCommand, 'utf-8')).toBe('custom command');
        expect(await fs.readFile(customSkill, 'utf-8')).toBe('custom skill');
      }
    );

    it('should respect commands-only delivery setting', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      await updateCommand.execute(testDir);

      // Commands should be created
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'explore.md')
      )).toBe(true);

      // Skills should be removed for commands-only delivery
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(false);
    });

    it('should be a no-op on second update run for commands-only delivery', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      // First run updates commands and removes skills
      await updateCommand.execute(testDir);

      const consoleSpy = vi.spyOn(console, 'log');

      // Second run should report all tools up to date without updating
      await updateCommand.execute(testDir);

      const logCalls = consoleSpy.mock.calls.flat().map(String);
      expect(logCalls.some((entry) => entry.includes('up to date'))).toBe(true);
      expect(logCalls.some((entry) => entry.includes('Updating 1 tool(s)'))).toBe(false);

      consoleSpy.mockRestore();
    });

    it.each(['both', 'skills', 'commands'] as const)(
      'should refresh Codex skills and not create global prompts when delivery=%s',
      async (delivery) => {
        setMockConfig({
          featureFlags: {},
          profile: 'core',
          delivery,
        });

        const skillsDir = path.join(testDir, '.agents', 'skills');
        await markCodexTarget(skillsDir);
        await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
        await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

        await updateCommand.execute(testDir);

        const skillFile = path.join(skillsDir, 'openspec-explore', 'SKILL.md');
        expect(await FileSystemUtils.fileExists(skillFile)).toBe(true);
        const skillContent = await fs.readFile(skillFile, 'utf-8');
        expect(skillContent).toContain('name: openspec-explore');

        const promptFile = path.join(process.env.CODEX_HOME!, 'prompts', 'opsx-explore.md');
        expect(await FileSystemUtils.fileExists(promptFile)).toBe(false);
      }
    );

    it('should report Codex command generation as skipped because it uses skills', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'both',
      });

      const skillsDir = path.join(testDir, '.agents', 'skills');
      await markCodexTarget(skillsDir);
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Updated: Codex')
      );
      expect(consoleSpy).toHaveBeenCalledWith(
        expect.stringContaining('Commands skipped for: codex (uses skills)')
      );

      consoleSpy.mockRestore();
    });

    it('should preserve managed global Codex prompts during non-interactive update without force', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const skillsDir = path.join(testDir, '.agents', 'skills');
      await markCodexTarget(skillsDir);
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const promptDir = path.join(process.env.CODEX_HOME!, 'prompts');
      const managedPrompt = path.join(promptDir, 'opsx-explore.md');
      await fs.mkdir(promptDir, { recursive: true });
      await fs.writeFile(managedPrompt, 'legacy explore prompt');

      await updateCommand.execute(testDir);

      expect(await FileSystemUtils.fileExists(managedPrompt)).toBe(true);
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(true);
    });

    it('should preserve global MiniMax Code skills in commands-only delivery', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const skillFile = path.join(
        testDir,
        'home',
        '.minimax',
        'skills',
        'openspec-explore',
        'SKILL.md'
      );
      await fs.mkdir(path.dirname(skillFile), { recursive: true });
      await fs.writeFile(skillFile, 'existing global skill');

      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      await updateCommand.execute(testDir);

      expect(await fs.readFile(skillFile, 'utf-8')).toBe('existing global skill');
      expect(await FileSystemUtils.directoryExists(path.join(testDir, '.minimax'))).toBe(false);
      const output = consoleSpy.mock.calls.flat().join('\n');
      expect(output).toContain('up to date');
      expect(output).not.toContain('Updated: MiniMax Code');
      consoleSpy.mockRestore();
    });

    it('should remove skills for configured tools without command adapters in commands-only delivery', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const { AI_TOOLS } = await import('../../src/core/config.js');
      const { resolveCommandSurfaceCapability } = await import('../../src/core/command-surface.js');
      const adapterlessTool = AI_TOOLS.find((tool) =>
        tool.skillsDir && resolveCommandSurfaceCapability(tool.value) === 'none'
      );
      expect(adapterlessTool).toBeDefined();
      if (!adapterlessTool?.skillsDir) {
        return;
      }

      const skillsDir = path.join(testDir, adapterlessTool.skillsDir, 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const consoleSpy = vi.spyOn(console, 'log');
      await expect(updateCommand.execute(testDir)).resolves.toBeUndefined();

      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md')
      )).toBe(false);

      // The tool now has zero OpenSpec artifacts; the removal must not be
      // silent — update prints the same configuration correction init does.
      const logCalls = consoleSpy.mock.calls.flat().map(String);
      const correction = logCalls.find((entry) => entry.includes('No skills or commands remain'));
      expect(correction).toBeTruthy();
      expect(correction).toContain("openspec config set delivery both");
    });

    it('should apply config sync when templates are up to date', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'skills',
      });

      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      const packageJsonPath = path.join(process.cwd(), 'package.json');
      const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8')) as { version: string };
      await fs.writeFile(
        path.join(skillsDir, 'openspec-explore', 'SKILL.md'),
        `---
name: openspec-explore
metadata:
  generatedBy: "${packageJson.version}"
---
content
`
      );

      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      await fs.mkdir(commandsDir, { recursive: true });
      await fs.writeFile(path.join(commandsDir, 'explore.md'), 'old command');

      await updateCommand.execute(testDir);

      // Command files should be removed due to delivery change, even though skill version is current
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'explore.md')
      )).toBe(false);
    });

    it('should detect commands-only tool configuration', async () => {
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'commands',
      });

      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      await fs.mkdir(commandsDir, { recursive: true });
      await fs.writeFile(path.join(commandsDir, 'explore.md'), 'existing command');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should not short-circuit with "No configured tools found"
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasNoConfiguredMessage = calls.some(call =>
        call.includes('No configured tools found')
      );
      expect(hasNoConfiguredMessage).toBe(false);

      // Commands should be updated/generated for the core profile
      expect(await FileSystemUtils.fileExists(
        path.join(commandsDir, 'propose.md')
      )).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should remove workflows outside profile during update sync', async () => {
      // Set core profile (propose, explore, apply, sync, archive)
      setMockConfig({
        featureFlags: {},
        profile: 'core',
        delivery: 'both',
      });

      // Set up tool with extra workflows beyond core profile
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      // Add a non-core workflow
      await fs.mkdir(path.join(skillsDir, 'openspec-new-change'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-new-change', 'SKILL.md'), 'old');
      const extraCommandFile = path.join(testDir, '.claude', 'commands', 'opsx', 'new.md');
      await fs.mkdir(path.dirname(extraCommandFile), { recursive: true });
      await fs.writeFile(extraCommandFile, 'old');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Deselected workflow artifacts should be removed for both delivery surfaces.
      expect(await FileSystemUtils.fileExists(
        path.join(skillsDir, 'openspec-new-change', 'SKILL.md')
      )).toBe(false);
      expect(await FileSystemUtils.fileExists(extraCommandFile)).toBe(false);

      // Should report deselected workflow cleanup.
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasDeselectedRemovalNote = calls.some(call =>
        call.includes('deselected workflows')
      );
      expect(hasDeselectedRemovalNote).toBe(true);

      consoleSpy.mockRestore();
    });
  });

  describe('new tool detection', () => {
    it('should detect new tool directories not currently configured', async () => {
      // Set up a configured Claude tool
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      // Create a Cursor directory (not configured — no skills)
      await fs.mkdir(path.join(testDir, '.cursor'), { recursive: true });

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      // Should detect Cursor as a new tool
      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasNewToolMessage = calls.some(call =>
        call.includes("Detected new tool: Cursor. Run 'openspec init' to add it.")
      );
      expect(hasNewToolMessage).toBe(true);

      consoleSpy.mockRestore();
    });

    it('should consolidate multiple new tools into one message', async () => {
      // Set up a configured Claude tool
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      // Create two unconfigured tool directories
      await fs.mkdir(path.join(testDir, '.github'), { recursive: true });
      await fs.writeFile(path.join(testDir, '.github', 'copilot-instructions.md'), '');
      await fs.mkdir(path.join(testDir, '.windsurf'), { recursive: true });

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );

      const consolidatedCalls = calls.filter(call =>
        call.includes('Detected new tools:')
      );
      expect(consolidatedCalls).toHaveLength(1);
      expect(consolidatedCalls[0]).toContain('GitHub Copilot');
      expect(consolidatedCalls[0]).toContain('Windsurf');
      expect(consolidatedCalls[0]).toContain("Run 'openspec init' to add them.");

      const repeatedSingularCalls = calls.filter(call =>
        call.includes('Detected new tool:')
      );
      expect(repeatedSingularCalls).toHaveLength(0);

      consoleSpy.mockRestore();
    });

    it('should not show new tool message when no new tools detected', async () => {
      // Set up a configured tool (only Claude, no other tool directories)
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasNewToolMessage = calls.some(call =>
        call.includes('Detected new tool')
      );
      expect(hasNewToolMessage).toBe(false);

      consoleSpy.mockRestore();
    });
  });

  describe('scanInstalledWorkflows', () => {
    it('should detect installed workflows across tools', async () => {
      // Create skills for Claude
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'), 'content');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-apply-change'), { recursive: true });
      await fs.writeFile(path.join(claudeSkillsDir, 'openspec-apply-change', 'SKILL.md'), 'content');

      const workflows = scanInstalledWorkflows(testDir, ['claude']);
      expect(workflows).toContain('explore');
      expect(workflows).toContain('apply');
      expect(workflows).not.toContain('propose');
    });

    it('should return union of workflows across multiple tools', async () => {
      // Claude has explore
      const claudeSkillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(claudeSkillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(claudeSkillsDir, 'openspec-explore', 'SKILL.md'), 'content');

      // Cursor has apply
      const cursorSkillsDir = path.join(testDir, '.cursor', 'skills');
      await fs.mkdir(path.join(cursorSkillsDir, 'openspec-apply-change'), { recursive: true });
      await fs.writeFile(path.join(cursorSkillsDir, 'openspec-apply-change', 'SKILL.md'), 'content');

      const workflows = scanInstalledWorkflows(testDir, ['claude', 'cursor']);
      expect(workflows).toContain('explore');
      expect(workflows).toContain('apply');
    });

    it('should only match workflows in ALL_WORKFLOWS', async () => {
      // Create a custom skill directory that doesn't match any workflow
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'my-custom-skill'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'my-custom-skill', 'SKILL.md'), 'content');

      const workflows = scanInstalledWorkflows(testDir, ['claude']);
      expect(workflows).toHaveLength(0);
    });

    it('should return empty array when no tools have skills', async () => {
      const workflows = scanInstalledWorkflows(testDir, ['claude']);
      expect(workflows).toHaveLength(0);
    });

    it('should detect installed workflows from managed command files', async () => {
      const commandsDir = path.join(testDir, '.claude', 'commands', 'opsx');
      await fs.mkdir(commandsDir, { recursive: true });
      await fs.writeFile(path.join(commandsDir, 'explore.md'), 'content');

      const workflows = scanInstalledWorkflows(testDir, ['claude']);
      expect(workflows).toContain('explore');
    });
  });

  describe('tools output', () => {
    it('should list affected tools in output', async () => {
      const skillsDir = path.join(testDir, '.claude', 'skills');
      await fs.mkdir(path.join(skillsDir, 'openspec-explore'), { recursive: true });
      await fs.writeFile(path.join(skillsDir, 'openspec-explore', 'SKILL.md'), 'old');

      const consoleSpy = vi.spyOn(console, 'log');

      await updateCommand.execute(testDir);

      const calls = consoleSpy.mock.calls.map(call =>
        call.map(arg => String(arg)).join(' ')
      );
      const hasToolsList = calls.some(call =>
        call.includes('Tools:') && call.includes('Claude Code')
      );
      expect(hasToolsList).toBe(true);

      consoleSpy.mockRestore();
    });
  });
});