@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.10

package/dist/domains/skill/platform-install.js

@@ -1,13 +1,30 @@
 import path from 'path';
 import { existsSync } from 'fs';
-import { readFile, writeFile, lstat, unlink, symlink, rm } from 'fs/promises';
+import { readFile, writeFile, lstat, unlink, symlink, rm, readdir } from 'fs/promises';
 import { fileURLToPath } from 'url';
-import { parseDocument } from 'yaml';
 import { fileExists, readJson, copyFile, ensureDir } from '../../platform/fs/file-system.js';
-import { getPlatformSkillsDir } from '../../platform/install/platforms.js';
-import { formatSupportedArtifactLanguages, resolveArtifactLanguage } from './languages.js';
+import { getPlatformConfigDir, getPlatformSkillsDir, } from '../../platform/install/platforms.js';
+import { resolveArtifactLanguage } from './languages.js';
+import { installCometProjectInstructions } from './project-instructions.js';
+import { readJsonObjectFile } from './json-object.js';
+import { assertClassicLayoutInitializationSafe, checkpointClassicLayoutInitialization, } from '../comet-classic/classic-layout-initialization.js';
+import { parseWorkflowProjectConfigDocument, projectConfigComment, renderStructuredProjectConfig, } from '../workflow-contract/project-config.js';
+import { readWorkflowProjectConfigSnapshot } from '../workflow-contract/project-config-reader.js';
+import { writeWorkflowProjectConfigSource } from '../workflow-contract/project-config-writer.js';
+import { ensureProtectedProjectDirectory } from '../workflow-contract/protected-project-path.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const HOOK_ROUTER_SCRIPT = 'comet/scripts/comet-hook-router.mjs';
+const LEGACY_HOOK_SCRIPTS = [
+    'comet/scripts/comet-hook-guard.mjs',
+    'comet-native/scripts/comet-native-hook-guard.mjs',
+];
+const LEGACY_RULE_FILES = ['comet-phase-guard.md', 'comet-native-phase-guard.md'];
+const NATIVE_SHARED_SKILL_PATHS = new Set([
+    'comet/SKILL.md',
+    'comet/scripts/comet-entry-runtime.mjs',
+    'comet/scripts/comet-hook-router.mjs',
+]);
 function planSkillDirectoryCopy(files, destinationRoot) {
     return files
         .map((file) => ({
@@ -19,9 +36,75 @@ function planSkillDirectoryCopy(files, destinationRoot) {
 function getManagedSkillPaths(manifest) {
     return [...new Set([...manifest.skills, ...(manifest.internalSkills ?? [])])];
 }
+function isManagedSkillPathForSelection(skillPath, workflowSelection) {
+    if (workflowSelection === 'both')
+        return true;
+    if (workflowSelection === 'classic')
+        return !skillPath.startsWith('comet-native/');
+    return (NATIVE_SHARED_SKILL_PATHS.has(skillPath) ||
+        skillPath.startsWith('comet-native/') ||
+        skillPath.startsWith('comet-any/'));
+}
+function getManagedSkillPathsForSelection(manifest, workflowSelection) {
+    return getManagedSkillPaths(manifest).filter((skillPath) => isManagedSkillPathForSelection(skillPath, workflowSelection));
+}
+function getUserFacingSkillPathsForSelection(manifest, workflowSelection) {
+    return manifest.skills.filter((skillPath) => isManagedSkillPathForSelection(skillPath, workflowSelection));
+}
 function getUserFacingSkillNames(manifest) {
     return getTopLevelSkillNames(manifest.skills);
 }
+function getManagedSkillReplacementPaths(manifest, workflowSelection = 'both') {
+    const allowed = new Set();
+    for (const skillPath of getManagedSkillPathsForSelection(manifest, workflowSelection)) {
+        const parts = skillPath.split('/').filter(Boolean);
+        for (let depth = 1; depth <= parts.length; depth++) {
+            allowed.add(parts.slice(0, depth).join('/'));
+        }
+    }
+    return allowed;
+}
+function getManagedSkillTopLevelEntries(manifest, workflowSelection = 'both') {
+    const entries = new Set();
+    for (const skillPath of getManagedSkillPathsForSelection(manifest, workflowSelection)) {
+        const [topLevel] = skillPath.split('/').filter(Boolean);
+        if (topLevel)
+            entries.add(topLevel);
+    }
+    return [...entries].sort();
+}
+function getManagedEntriesForTopLevel(managedEntries, topLevelEntry) {
+    const scopedEntries = new Set();
+    const prefix = `${topLevelEntry}/`;
+    for (const entry of managedEntries) {
+        if (entry.startsWith(prefix)) {
+            scopedEntries.add(entry.slice(prefix.length));
+        }
+    }
+    return scopedEntries;
+}
+async function collectDirectoryEntryPaths(root, current = root) {
+    const entries = await readdir(current, { withFileTypes: true });
+    const paths = [];
+    for (const entry of entries) {
+        const fullPath = path.join(current, entry.name);
+        const relativePath = path.relative(root, fullPath).split(path.sep).join('/');
+        paths.push(relativePath);
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            paths.push(...(await collectDirectoryEntryPaths(root, fullPath)));
+        }
+    }
+    return paths;
+}
+async function assertDirectoryContainsOnlyManagedEntries(dirPath, managedEntries) {
+    const entries = await collectDirectoryEntryPaths(dirPath);
+    const unmanagedEntries = entries.filter((entry) => !managedEntries.has(entry));
+    if (unmanagedEntries.length === 0)
+        return;
+    const preview = unmanagedEntries.slice(0, 5).join(', ');
+    const suffix = unmanagedEntries.length > 5 ? `, and ${unmanagedEntries.length - 5} more` : '';
+    throw new Error(`Refusing to replace ${dirPath} with a symlink because it contains unmanaged entries: ${preview}${suffix}. Move them aside or use copy install mode.`);
+}
 const OPENCODE_COMMAND_HEADER = `---
 description: Run the {skillName} Comet workflow
 ---
@@ -51,37 +134,150 @@ function getCentralSkillsDir(baseDir, _scope) {
  * Create a symlink from linkPath pointing to target.
  * On Windows, uses 'junction' type for directory symlinks (no admin required).
  */
-async function createSymlink(target, linkPath) {
+async function createSymlink(target, linkPath, managedEntries) {
     await ensureDir(path.dirname(linkPath));
     // Remove existing link/directory if present
+    let stat = null;
     try {
-        const stat = await lstat(linkPath);
-        if (stat.isSymbolicLink()) {
+        stat = await lstat(linkPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    if (stat?.isSymbolicLink()) {
+        await unlink(linkPath);
+    }
+    else if (stat?.isDirectory()) {
+        // For directories, try unlink first (handles Windows junctions)
+        try {
             await unlink(linkPath);
         }
-        else if (stat.isDirectory()) {
-            // For directories, try unlink first (handles Windows junctions)
-            try {
-                await unlink(linkPath);
-            }
-            catch {
-                await rm(linkPath, { recursive: true, force: true });
-            }
+        catch {
+            await assertDirectoryContainsOnlyManagedEntries(linkPath, managedEntries);
+            await rm(linkPath, { recursive: true, force: true });
         }
     }
-    catch {
-        // Path doesn't exist, continue
-    }
     // Windows uses 'junction' for directory symlinks (no admin privileges required)
     const type = process.platform === 'win32' ? 'junction' : 'dir';
     await symlink(target, linkPath, type);
 }
+async function lstatOrNull(filePath) {
+    try {
+        return await lstat(filePath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        throw err;
+    }
+}
+async function prepareManagedSkillCopyTarget(baseDir, platform, scope = 'project', workflowSelection = 'both') {
+    const manifest = await readManifest();
+    const managedEntries = new Set(getManagedSkillTopLevelEntries(manifest, workflowSelection));
+    const skillsRoot = path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills');
+    const rootStat = await lstatOrNull(skillsRoot);
+    if (!rootStat)
+        return;
+    if (rootStat.isSymbolicLink()) {
+        let linkedEntries = [];
+        try {
+            linkedEntries = await readdir(skillsRoot);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const unmanagedEntries = linkedEntries.filter((entry) => !managedEntries.has(entry));
+        if (unmanagedEntries.length > 0) {
+            throw new Error(`Refusing to replace ${skillsRoot} with managed copies because the linked directory contains unmanaged entries: ${unmanagedEntries.join(', ')}`);
+        }
+        await unlink(skillsRoot);
+        await ensureDir(skillsRoot);
+        return;
+    }
+    if (!rootStat.isDirectory())
+        return;
+    for (const entry of managedEntries) {
+        const entryPath = path.join(skillsRoot, entry);
+        const entryStat = await lstatOrNull(entryPath);
+        if (entryStat?.isSymbolicLink()) {
+            await unlink(entryPath);
+        }
+    }
+}
+async function prepareNativeSkillInstallTarget(baseDir, platform, scope, languageSkillsDir, action) {
+    if (action !== 'skip') {
+        await prepareManagedSkillCopyTarget(baseDir, platform, scope, 'native');
+    }
+    if (action === 'overwrite')
+        return;
+    const skillsRoot = path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills');
+    const assetsDir = getAssetsDir();
+    const manifest = await readManifest();
+    const requiredFiles = getManagedSkillPaths(manifest)
+        .filter((relativePath) => relativePath === 'comet/SKILL.md' ||
+        relativePath === 'comet/scripts/comet-entry-runtime.mjs' ||
+        relativePath === 'comet/scripts/comet-hook-router.mjs' ||
+        relativePath.startsWith('comet-any/') ||
+        relativePath.startsWith('comet-native/'))
+        .map((relativePath) => {
+        const pathParts = relativePath.split('/');
+        const sourceDir = relativePath.includes('/scripts/') ? 'skills' : languageSkillsDir;
+        return {
+            label: `the required Native asset ${relativePath}`,
+            destination: path.join(skillsRoot, ...pathParts),
+            source: path.join(assetsDir, sourceDir, ...pathParts),
+        };
+    });
+    for (const required of requiredFiles) {
+        const destinationStat = await lstatOrNull(required.destination);
+        if (!destinationStat) {
+            if (action === 'fill')
+                continue;
+            throw new Error(`Cannot activate Native while skipping existing Comet files because ${required.label} is missing at ${required.destination}`);
+        }
+        if (!destinationStat.isFile()) {
+            throw new Error(`Cannot activate Native because ${required.label} is not a regular file at ${required.destination}; rerun with --overwrite after preserving any custom content`);
+        }
+        const [installed, bundled] = await Promise.all([
+            readFile(required.destination),
+            readFile(required.source),
+        ]);
+        if (!installed.equals(bundled)) {
+            throw new Error(`Cannot activate Native because ${required.label} differs from the bundled routing contract at ${required.destination}; rerun with --overwrite after preserving any custom content`);
+        }
+    }
+}
+async function createSkillsSymlinks(targetRoot, linkRoot, managedEntries, topLevelEntries) {
+    const rootStat = await lstatOrNull(linkRoot);
+    if (!rootStat || rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        await createSymlink(targetRoot, linkRoot, managedEntries);
+        return 0;
+    }
+    let failed = 0;
+    for (const topLevelEntry of topLevelEntries) {
+        const targetEntry = path.join(targetRoot, topLevelEntry);
+        const linkEntry = path.join(linkRoot, topLevelEntry);
+        const managedEntryScope = getManagedEntriesForTopLevel(managedEntries, topLevelEntry);
+        try {
+            await createSymlink(targetEntry, linkEntry, managedEntryScope);
+        }
+        catch (err) {
+            failed++;
+            console.error(`    Failed to create symlink ${linkEntry} -> ${targetEntry}: ${err.message}`);
+        }
+    }
+    return failed;
+}
 /**
  * Install skills using symlink mode:
  * 1. Copy skills to central store (.comet/skills/)
- * 2. Create symlink from platform dir to central store
+ * 2. Create symlinks from the platform skills dir to central store
  */
-async function installSkillsAsSymlink(baseDir, platform, overwrite, languageSkillsDir = 'skills', scope = 'project') {
+async function installSkillsAsSymlink(baseDir, platform, overwrite, languageSkillsDir = 'skills', scope = 'project', workflowSelection = 'both') {
     const centralDir = getCentralSkillsDir(baseDir, scope);
     const assetsDir = getAssetsDir();
     const manifestPath = path.join(assetsDir, 'manifest.json');
@@ -92,20 +288,24 @@ async function installSkillsAsSymlink(baseDir, platform, overwrite, languageSkil
     if (!manifest || !Array.isArray(manifest.skills)) {
         throw new Error(`Invalid manifest at ${manifestPath}: "skills" must be an array`);
     }
+    const managedSkillPaths = getManagedSkillPathsForSelection(manifest, workflowSelection);
+    const userFacingSkillPaths = getUserFacingSkillPathsForSelection(manifest, workflowSelection);
+    const managedSkillReplacementPaths = getManagedSkillReplacementPaths(manifest, workflowSelection);
+    const managedSkillTopLevelEntries = getManagedSkillTopLevelEntries(manifest, workflowSelection);
     // Step 1: Copy skills to central store
     let copied = 0;
     let skippedCount = 0;
     let failedCount = 0;
-    for (const skillRelPath of getManagedSkillPaths(manifest)) {
+    for (const skillRelPath of managedSkillPaths) {
         const isScript = skillRelPath.includes('/scripts/');
         const sourceDir = isScript ? 'skills' : languageSkillsDir;
         const src = path.join(assetsDir, sourceDir, skillRelPath);
         const centralDest = path.join(centralDir, 'skills', skillRelPath);
-        if (!overwrite && (await fileExists(centralDest))) {
-            skippedCount++;
-            continue;
-        }
         try {
+            if (!overwrite && (await fileExists(centralDest))) {
+                skippedCount++;
+                continue;
+            }
             await copyFile(src, centralDest);
             copied++;
         }
@@ -114,11 +314,11 @@ async function installSkillsAsSymlink(baseDir, platform, overwrite, languageSkil
             console.error(`    Failed to copy ${skillRelPath} to central store: ${err.message}`);
         }
     }
-    // Step 2: Create symlink from platform dir to central store
+    // Step 2: Create symlinks from platform dir to central store
     const platformSkillsDir = path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills');
     const centralSkillsDir = path.join(centralDir, 'skills');
     try {
-        await createSymlink(centralSkillsDir, platformSkillsDir);
+        failedCount += await createSkillsSymlinks(centralSkillsDir, platformSkillsDir, managedSkillReplacementPaths, managedSkillTopLevelEntries);
     }
     catch (err) {
         failedCount++;
@@ -126,21 +326,23 @@ async function installSkillsAsSymlink(baseDir, platform, overwrite, languageSkil
     }
     // Handle OpenCode-style platform commands (still need copy, as command content may differ)
     if (OPENCODE_STYLE_PLATFORM_IDS.has(platform.id)) {
-        const result = await createOpenCodeCommands(baseDir, platform, manifest.skills, overwrite, scope, languageSkillsDir);
+        const result = await createOpenCodeCommands(baseDir, platform, userFacingSkillPaths, overwrite, scope, languageSkillsDir);
         copied += result.copied;
         skippedCount += result.skipped;
+        failedCount += result.failed;
     }
     // Handle Pi platform command extension
     if (platform.id === 'pi') {
-        const result = await createPiCommandExtension(baseDir, platform, manifest.skills, overwrite, scope);
+        const result = await createPiCommandExtension(baseDir, platform, userFacingSkillPaths, overwrite, scope);
         copied += result.copied;
         skippedCount += result.skipped;
+        failedCount += result.failed;
     }
     return { copied, skipped: skippedCount, failed: failedCount };
 }
-async function copyCometSkillsForPlatform(baseDir, platform, overwrite, languageSkillsDir = 'skills', scope = 'project', installMode = 'copy') {
+async function copyCometSkillsForPlatform(baseDir, platform, overwrite, languageSkillsDir = 'skills', scope = 'project', installMode = 'copy', workflowSelection = 'both') {
     if (installMode === 'symlink') {
-        return installSkillsAsSymlink(baseDir, platform, overwrite, languageSkillsDir, scope);
+        return installSkillsAsSymlink(baseDir, platform, overwrite, languageSkillsDir, scope, workflowSelection);
     }
     const assetsDir = getAssetsDir();
     const manifestPath = path.join(assetsDir, 'manifest.json');
@@ -154,16 +356,18 @@ async function copyCometSkillsForPlatform(baseDir, platform, overwrite, language
     let copied = 0;
     let skippedCount = 0;
     let failedCount = 0;
-    for (const skillRelPath of getManagedSkillPaths(manifest)) {
+    const managedSkillPaths = getManagedSkillPathsForSelection(manifest, workflowSelection);
+    const userFacingSkillPaths = getUserFacingSkillPathsForSelection(manifest, workflowSelection);
+    for (const skillRelPath of managedSkillPaths) {
         const isScript = skillRelPath.includes('/scripts/');
         const sourceDir = isScript ? 'skills' : languageSkillsDir;
         const src = path.join(assetsDir, sourceDir, skillRelPath);
         const dest = path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills', skillRelPath);
-        if (!overwrite && (await fileExists(dest))) {
-            skippedCount++;
-            continue;
-        }
         try {
+            if (!overwrite && (await fileExists(dest))) {
+                skippedCount++;
+                continue;
+            }
             await copyFile(src, dest);
             copied++;
         }
@@ -177,14 +381,16 @@ async function copyCometSkillsForPlatform(baseDir, platform, overwrite, language
         }
     }
     if (OPENCODE_STYLE_PLATFORM_IDS.has(platform.id)) {
-        const result = await createOpenCodeCommands(baseDir, platform, manifest.skills, overwrite, scope, languageSkillsDir);
+        const result = await createOpenCodeCommands(baseDir, platform, userFacingSkillPaths, overwrite, scope, languageSkillsDir);
         copied += result.copied;
         skippedCount += result.skipped;
+        failedCount += result.failed;
     }
     if (platform.id === 'pi') {
-        const result = await createPiCommandExtension(baseDir, platform, manifest.skills, overwrite, scope);
+        const result = await createPiCommandExtension(baseDir, platform, userFacingSkillPaths, overwrite, scope);
         copied += result.copied;
         skippedCount += result.skipped;
+        failedCount += result.failed;
     }
     return { copied, skipped: skippedCount, failed: failedCount };
 }
@@ -215,37 +421,46 @@ async function createPiCommandExtension(baseDir, platform, skillPaths, overwrite
     const platformBase = path.join(baseDir, getPlatformSkillsDir(platform, scope));
     const settingsPath = path.join(platformBase, 'settings.json');
     const extensionPath = path.join(platformBase, 'extensions', PI_COMMAND_EXTENSION_FILE);
-    let settings = {};
-    if (await fileExists(settingsPath)) {
-        try {
+    let copied = 0;
+    let skipped = 0;
+    let failed = 0;
+    try {
+        let settings = {};
+        if (await fileExists(settingsPath)) {
             const parsed = JSON.parse(await readFile(settingsPath, 'utf-8'));
             if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
                 throw new Error('expected a JSON object');
             }
             settings = parsed;
         }
-        catch (err) {
-            throw new Error(`Invalid Pi settings at ${settingsPath}: ${err.message}`, {
-                cause: err,
-            });
+        if (settings.enableSkillCommands !== true) {
+            settings.enableSkillCommands = true;
+            await ensureDir(path.dirname(settingsPath));
+            await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            copied++;
         }
     }
-    let copied = 0;
-    let skipped = 0;
-    if (settings.enableSkillCommands !== true) {
-        settings.enableSkillCommands = true;
-        await ensureDir(path.dirname(settingsPath));
-        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-        copied++;
+    catch (err) {
+        failed++;
+        console.error(`    Failed to update Pi settings at ${settingsPath}: ${err.message}`);
     }
-    if (!overwrite && (await fileExists(extensionPath))) {
-        skipped++;
-        return { copied, skipped };
+    if (failed > 0)
+        return { copied, skipped, failed };
+    try {
+        if (!overwrite && (await fileExists(extensionPath))) {
+            skipped++;
+        }
+        else {
+            await ensureDir(path.dirname(extensionPath));
+            await writeFile(extensionPath, renderPiCommandExtension(getTopLevelSkillNames(skillPaths)), 'utf-8');
+            copied++;
+        }
     }
-    await ensureDir(path.dirname(extensionPath));
-    await writeFile(extensionPath, renderPiCommandExtension(getTopLevelSkillNames(skillPaths)), 'utf-8');
-    copied++;
-    return { copied, skipped };
+    catch (err) {
+        failed++;
+        console.error(`    Failed to write Pi command extension at ${extensionPath}: ${err.message}`);
+    }
+    return { copied, skipped, failed };
 }
 function stripFrontmatter(content) {
     if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
@@ -260,6 +475,7 @@ function stripFrontmatter(content) {
 async function createOpenCodeCommands(baseDir, platform, skillPaths, overwrite, scope, languageSkillsDir) {
     let copied = 0;
     let skipped = 0;
+    let failed = 0;
     const assetsDir = getAssetsDir();
     const commandsDir = path.join(baseDir, getPlatformSkillsDir(platform, scope), 'commands');
     for (const skillPath of skillPaths) {
@@ -268,17 +484,18 @@ async function createOpenCodeCommands(baseDir, platform, skillPaths, overwrite,
             continue;
         const skillName = parts[0];
         const dest = path.join(commandsDir, `${skillName}.md`);
-        if (!overwrite && (await fileExists(dest))) {
-            skipped++;
-            continue;
-        }
-        await ensureDir(path.dirname(dest));
-        let skillSourcePath = path.join(assetsDir, languageSkillsDir, skillPath);
-        if (!(await fileExists(skillSourcePath))) {
-            skillSourcePath = path.join(assetsDir, 'skills', skillPath);
-        }
-        const skillBody = stripFrontmatter(await readFile(skillSourcePath, 'utf-8'));
-        const content = `${OPENCODE_COMMAND_HEADER.replace('{skillName}', skillName)}
+        try {
+            if (!overwrite && (await fileExists(dest))) {
+                skipped++;
+                continue;
+            }
+            await ensureDir(path.dirname(dest));
+            let skillSourcePath = path.join(assetsDir, languageSkillsDir, skillPath);
+            if (!(await fileExists(skillSourcePath))) {
+                skillSourcePath = path.join(assetsDir, 'skills', skillPath);
+            }
+            const skillBody = stripFrontmatter(await readFile(skillSourcePath, 'utf-8'));
+            const content = `${OPENCODE_COMMAND_HEADER.replace('{skillName}', skillName)}
 Equivalent Comet skill: \`${skillName}\`
 Command name: \`/${skillName}\`
 
@@ -290,19 +507,24 @@ $ARGUMENTS
 
 ${skillBody}
 `;
-        await writeFile(dest, content, 'utf-8');
-        copied++;
+            await writeFile(dest, content, 'utf-8');
+            copied++;
+        }
+        catch (err) {
+            failed++;
+            console.error(`    Failed to create OpenCode command ${dest}: ${err.message}`);
+        }
     }
-    return { copied, skipped };
+    return { copied, skipped, failed };
 }
 async function readManifest() {
     const assetsDir = getAssetsDir();
     const manifestPath = path.join(assetsDir, 'manifest.json');
     return readJson(manifestPath);
 }
-async function getManifestSkills() {
+async function getManifestSkills(workflowSelection = 'both') {
     const manifest = await readManifest();
-    return getManagedSkillPaths(manifest);
+    return getManagedSkillPathsForSelection(manifest, workflowSelection);
 }
 /**
  * Copy Comet rule files to a platform's rules directory.
@@ -312,14 +534,49 @@ async function getManifestSkills() {
  *   'copilot' = GitHub Copilot .instructions.md with applyTo frontmatter
  * Skips platforms without rulesDir.
  */
-async function copyCometRulesForPlatform(baseDir, platform, overwrite, scope = 'project') {
+// Rule variants share a base name and differ only by a `.en.md` suffix
+// (e.g. `comet-phase-guard.md` = zh default, `comet-phase-guard.en.md` = en).
+// Centralized here so the naming convention only needs to change in one place.
+const EN_RULE_SUFFIX = /\.en\.md$/;
+function isEnglishRuleVariant(ruleRelPath) {
+    return EN_RULE_SUFFIX.test(ruleRelPath);
+}
+function toRuleBaseName(ruleRelPath) {
+    return ruleRelPath.replace(EN_RULE_SUFFIX, '.md');
+}
+// Pick exactly one variant per base name for the requested language, falling
+// back to whichever variant exists if there's no per-language pair.
+function selectRulePathsForLanguage(rulePaths, languageId) {
+    const wantEnglish = languageId === 'en';
+    const selected = new Map();
+    for (const rulePath of rulePaths) {
+        const isEnglishVariant = isEnglishRuleVariant(rulePath);
+        const baseKey = toRuleBaseName(rulePath);
+        const matched = isEnglishVariant === wantEnglish;
+        const existing = selected.get(baseKey);
+        if (!existing || (matched && !existing.matched)) {
+            selected.set(baseKey, { rulePath, matched });
+        }
+    }
+    return [...selected.values()].map((entry) => entry.rulePath);
+}
+function managedRulesForSelection(manifest, _selection) {
+    return manifest.rules ?? [];
+}
+function managedHooksForSelection(manifest, _selection) {
+    return manifest.hooks ?? {};
+}
+function managedHookScriptPaths(hooksConfig) {
+    return [...new Set([...Object.keys(hooksConfig), ...LEGACY_HOOK_SCRIPTS])];
+}
+async function copyCometRulesForPlatform(baseDir, platform, overwrite, languageId, scope = 'project', workflowSelection = 'classic') {
     if (!platform.rulesDir || !platform.rulesFormat) {
-        return { copied: 0, skipped: 0 };
+        return { copied: 0, skipped: 0, failed: 0 };
     }
     const manifest = await readManifest();
-    const rulePaths = manifest.rules;
+    const rulePaths = selectRulePathsForLanguage(managedRulesForSelection(manifest, workflowSelection), languageId);
     if (!rulePaths || rulePaths.length === 0) {
-        return { copied: 0, skipped: 0 };
+        return { copied: 0, skipped: 0, failed: 0 };
     }
     const assetsDir = getAssetsDir();
     // Support platforms whose rules live outside the skills config dir
@@ -331,20 +588,24 @@ async function copyCometRulesForPlatform(baseDir, platform, overwrite, scope = '
         : path.join(baseDir, getPlatformSkillsDir(platform, scope));
     let copied = 0;
     let skippedCount = 0;
+    let failed = 0;
     for (const ruleRelPath of rulePaths) {
         const src = path.join(assetsDir, 'skills', ruleRelPath);
-        if (!(await fileExists(src))) {
-            console.error(`    Rule source not found: ${ruleRelPath}`);
-            continue;
-        }
-        const ruleFileName = path.basename(ruleRelPath);
-        const rulesDestDir = path.join(rulesBase, platform.rulesDir);
-        const dest = computeRuleDestPath(rulesDestDir, ruleFileName, platform.rulesFormat);
-        if (!overwrite && (await fileExists(dest))) {
-            skippedCount++;
-            continue;
-        }
         try {
+            if (!(await fileExists(src))) {
+                console.error(`    Rule source not found: ${ruleRelPath}`);
+                failed++;
+                continue;
+            }
+            // Normalize the `.en` infix away so the installed file name is the same
+            // regardless of which language variant was selected.
+            const ruleFileName = toRuleBaseName(path.basename(ruleRelPath));
+            const rulesDestDir = path.join(rulesBase, platform.rulesDir);
+            const dest = computeRuleDestPath(rulesDestDir, ruleFileName, platform.rulesFormat);
+            if (!overwrite && (await fileExists(dest))) {
+                skippedCount++;
+                continue;
+            }
             const content = await readFile(src, 'utf-8');
             await ensureDir(path.dirname(dest));
             const formatted = formatRuleContent(content, ruleFileName, platform.rulesFormat);
@@ -353,9 +614,24 @@ async function copyCometRulesForPlatform(baseDir, platform, overwrite, scope = '
         }
         catch (err) {
             console.error(`    Failed to copy rule ${ruleRelPath}: ${err.message}`);
+            failed++;
         }
     }
-    return { copied, skipped: skippedCount };
+    const rulesDestDir = path.join(rulesBase, platform.rulesDir);
+    for (const legacyFile of LEGACY_RULE_FILES) {
+        const legacyPath = computeRuleDestPath(rulesDestDir, legacyFile, platform.rulesFormat);
+        try {
+            await rm(legacyPath, { force: true });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                continue;
+            console.error(`    Failed to remove legacy Rule ${legacyPath}: ${error.message}`);
+            failed++;
+        }
+    }
+    return { copied, skipped: skippedCount, failed };
 }
 function computeRuleDestPath(rulesDestDir, ruleFileName, rulesFormat) {
     if (rulesFormat === 'mdc') {
@@ -392,57 +668,154 @@ ${content}`;
 /**
  * Install Comet hooks for platforms that support them.
  * Supports multiple hook formats:
- *   'claude-code' — settings.local.json with PreToolUse array (Claude Code, Codex, Amazon Q)
+ *   'claude-code' — Claude-shaped JSON with PreToolUse array; defaults to settings.local.json,
+ *                   with platform metadata able to override the filename
  *   'qwen' — settings.json with PreToolUse/hooks array (Qwen Code)
  *   'qoder' — settings.json with PreToolUse/hooks array (Qoder)
+ *   'codebuddy' — settings.json with PreToolUse/hooks array (CodeBuddy Code)
  *   'gemini' — settings.json with hooks.BeforeTool array (Gemini CLI)
  *   'windsurf' — hooks.json with pre_write_code array
  *   'copilot' — hooks/*.json with preToolUse
  *   'kiro' — hooks/*.kiro.hook JSON files
  */
-async function installCometHooksForPlatform(baseDir, platform, scope = 'project') {
-    if (!platform.supportsHooks || !platform.hookFormat) {
-        return { installed: false, reason: 'platform does not support hooks' };
+async function installCometHooksForPlatform(baseDir, platform, scope = 'project', workflowSelection = 'classic') {
+    if (!platform.supportsHooks) {
+        return { status: 'skipped', reason: 'platform does not support hooks' };
     }
-    const manifest = await readManifest();
-    const hooksConfig = manifest.hooks;
-    if (!hooksConfig || Object.keys(hooksConfig).length === 0) {
-        return { installed: false, reason: 'no hooks defined in manifest' };
+    if (!platform.hookFormat) {
+        return {
+            status: 'failed',
+            reason: 'hook-capable platform does not declare a hook format',
+        };
     }
-    const hookFormat = platform.hookFormat;
-    const skillsDir = getPlatformSkillsDir(platform, scope);
-    const platformBase = path.join(baseDir, skillsDir);
     try {
+        const manifest = await readManifest();
+        const hooksConfig = managedHooksForSelection(manifest, workflowSelection);
+        if (!hooksConfig || Object.keys(hooksConfig).length === 0) {
+            return { status: 'skipped', reason: 'no hooks defined in manifest' };
+        }
+        const hookFormat = platform.hookFormat;
+        const skillsDir = getPlatformSkillsDir(platform, scope);
+        const platformBase = path.join(baseDir, getPlatformConfigDir(platform, scope));
         switch (hookFormat) {
-            case 'claude-code':
-                return installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksConfig);
+            case 'claude-code': {
+                const result = await installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.hookConfigFile ?? 'settings.local.json', platform.name, { platformId: platform.id, scope });
+                if (result.status === 'installed') {
+                    const failedLegacyFiles = [];
+                    for (const legacyFile of platform.legacyHookConfigFiles ?? []) {
+                        try {
+                            const cleanup = await removeManagedHooksFromJsonFile(path.join(platformBase, legacyFile), managedHookScriptPaths(hooksConfig));
+                            if (cleanup.failed > 0)
+                                failedLegacyFiles.push(legacyFile);
+                        }
+                        catch {
+                            failedLegacyFiles.push(legacyFile);
+                        }
+                    }
+                    if (failedLegacyFiles.length > 0) {
+                        return {
+                            status: 'installed',
+                            reason: `legacy Hook cleanup failed for ${failedLegacyFiles.join(', ')}`,
+                            cleanupFailed: failedLegacyFiles.length,
+                        };
+                    }
+                }
+                return result;
+            }
             case 'qwen':
             case 'qoder':
-                return installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, hookFormat);
+            case 'codebuddy':
+                return await installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'gemini':
-                return installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'windsurf':
-                return installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'copilot':
-                return installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig, {
+                    platformId: platform.id,
+                    scope,
+                });
             case 'kiro':
-                return installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig, {
+                    platformId: platform.id,
+                    scope,
+                });
             default:
-                return { installed: false, reason: `unsupported hook format: ${hookFormat}` };
+                return { status: 'failed', reason: `unsupported hook format: ${hookFormat}` };
         }
     }
     catch (err) {
-        return { installed: false, reason: err.message };
+        return { status: 'failed', reason: err.message };
     }
 }
 function quoteCommandArg(value) {
     return `"${value.replaceAll('\\', '/').replaceAll('"', '\\"')}"`;
 }
 /** Build a hook command that is stable even when the hook runner executes from a subdirectory. */
-function buildHookCommand(baseDir, skillsDir, scriptRelPath) {
+function buildHookCommand(baseDir, skillsDir, scriptRelPath, context) {
     const projectRoot = path.resolve(baseDir);
     const scriptPath = path.join(projectRoot, skillsDir, 'skills', ...scriptRelPath.split('/'));
-    return `node ${quoteCommandArg(scriptPath)} --project-root ${quoteCommandArg(projectRoot)}`;
+    let command = `node ${quoteCommandArg(scriptPath)}`;
+    if (scriptRelPath === HOOK_ROUTER_SCRIPT && context) {
+        command += ` --platform ${quoteCommandArg(context.platformId)}`;
+        if (context.scope === 'project') {
+            command += ` --project-root ${quoteCommandArg(projectRoot)}`;
+        }
+        return command;
+    }
+    return `${command} --project-root ${quoteCommandArg(projectRoot)}`;
+}
+function parseCommandTokens(command) {
+    const tokens = [];
+    let current = '';
+    let quote;
+    let tokenStarted = false;
+    let quoteClosed = false;
+    for (let index = 0; index < command.length; index++) {
+        const character = command[index];
+        if (quote) {
+            if (character === quote) {
+                quote = undefined;
+                quoteClosed = true;
+            }
+            else if (character === '\\' && command[index + 1] === quote) {
+                current += quote;
+                index++;
+            }
+            else {
+                current += character;
+            }
+            continue;
+        }
+        if (character === '\r' || character === '\n' || ';|&<>`'.includes(character)) {
+            return undefined;
+        }
+        if (/\s/u.test(character)) {
+            if (tokenStarted) {
+                tokens.push(current);
+                current = '';
+                tokenStarted = false;
+                quoteClosed = false;
+            }
+            continue;
+        }
+        if (quoteClosed)
+            return undefined;
+        if (character === '"' || character === "'") {
+            if (tokenStarted)
+                return undefined;
+            quote = character;
+            tokenStarted = true;
+            continue;
+        }
+        current += character;
+        tokenStarted = true;
+    }
+    if (quote)
+        return undefined;
+    if (tokenStarted)
+        tokens.push(current);
+    return tokens;
 }
 function isManagedHookCommand(command, scriptRelPaths) {
     if (typeof command !== 'string')
@@ -450,28 +823,38 @@ function isManagedHookCommand(command, scriptRelPaths) {
     // Match both the current `node .../comet-hook-guard.mjs` form and the legacy
     // `bash .../comet-hook-guard.sh` form so uninstall also cleans up hooks
     // written by older Comet releases. Compare basenames without extension.
-    const commandPath = command
-        .trim()
-        .match(/^(?:node|bash|sh)\s+["']?([^"'\s]+)["']?(?:\s|$)/)?.[1]
-        ?.replace(/\\/g, '/');
-    if (!commandPath)
+    const tokens = parseCommandTokens(command.trim());
+    if (!tokens || tokens.length < 2 || !['node', 'bash', 'sh'].includes(tokens[0]))
         return false;
+    const commandPath = tokens[1].replace(/\\/g, '/');
     const normalize = (value) => value.replace(/\.(?:sh|mjs)$/u, '');
     return scriptRelPaths.some((scriptRelPath) => normalize(commandPath).endsWith(`/skills/${normalize(scriptRelPath.replace(/\\/g, '/'))}`));
 }
 function mergeHookGroups(existingGroups, newGroups, scriptRelPaths) {
-    const mergedGroups = existingGroups.flatMap((group) => {
-        if (!Array.isArray(group.hooks))
-            return [group];
-        const hooks = group.hooks.filter((hook) => !isManagedHookCommand(hook.command, scriptRelPaths));
-        if (hooks.length === 0 && group.hooks.length > 0)
-            return [];
-        return [{ ...group, hooks }];
+    const mergedGroups = existingGroups.map((group) => {
+        if (!group || typeof group !== 'object' || Array.isArray(group))
+            return group;
+        const record = group;
+        if (!Array.isArray(record.hooks))
+            return record;
+        const hooks = record.hooks.filter((hook) => {
+            const command = hook && typeof hook === 'object' ? hook.command : undefined;
+            return !isManagedHookCommand(command, scriptRelPaths);
+        });
+        return { ...record, hooks };
     });
     for (const newGroup of newGroups) {
-        const existingGroup = mergedGroups.find((group) => group.matcher === newGroup.matcher && Array.isArray(group.hooks));
-        if (existingGroup) {
-            existingGroup.hooks = [...existingGroup.hooks, ...newGroup.hooks];
+        const existingGroupIndex = mergedGroups.findIndex((group) => Boolean(group) &&
+            typeof group === 'object' &&
+            !Array.isArray(group) &&
+            group.matcher === newGroup.matcher &&
+            Array.isArray(group.hooks));
+        if (existingGroupIndex >= 0) {
+            const existingGroup = mergedGroups[existingGroupIndex];
+            mergedGroups[existingGroupIndex] = {
+                ...existingGroup,
+                hooks: [...existingGroup.hooks, ...newGroup.hooks],
+            };
         }
         else {
             mergedGroups.push(newGroup);
@@ -487,44 +870,101 @@ function mergeHookGroups(existingGroups, newGroups, scriptRelPaths) {
 function asHookGroup(value) {
     return Array.isArray(value) ? value : [];
 }
+async function removeManagedHooksFromJsonFile(settingsPath, scriptRelPaths) {
+    if (!(await fileExists(settingsPath)))
+        return { removed: 0, failed: 0 };
+    let source;
+    try {
+        source = await readFile(settingsPath, 'utf-8');
+    }
+    catch {
+        return { removed: 0, failed: 1 };
+    }
+    let settings;
+    try {
+        const parsed = JSON.parse(source);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { removed: 0, failed: 1 };
+        }
+        settings = parsed;
+    }
+    catch {
+        return { removed: 0, failed: 1 };
+    }
+    const existingHooks = settings.hooks;
+    const existingPreToolUse = existingHooks?.PreToolUse;
+    if (!existingHooks || !Array.isArray(existingPreToolUse)) {
+        return { removed: 0, failed: 0 };
+    }
+    let removed = 0;
+    const filtered = existingPreToolUse.map((group) => {
+        if (!group || typeof group !== 'object')
+            return group;
+        const record = group;
+        if (!Array.isArray(record.hooks))
+            return record;
+        const handlers = record.hooks.filter((handler) => {
+            const command = handler && typeof handler === 'object'
+                ? handler.command
+                : undefined;
+            const managed = isManagedHookCommand(command, scriptRelPaths);
+            if (managed)
+                removed++;
+            return !managed;
+        });
+        return { ...record, hooks: handlers };
+    });
+    if (removed === 0)
+        return { removed: 0, failed: 0 };
+    existingHooks.PreToolUse = filtered;
+    try {
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    }
+    catch {
+        return { removed: 0, failed: 1 };
+    }
+    return { removed, failed: 0 };
+}
+async function readSettingsJsonObject(settingsPath, platformName) {
+    const result = await readJsonObjectFile(settingsPath);
+    if (result.status === 'missing')
+        return {};
+    if (result.status === 'present')
+        return result.value;
+    throw new Error(`Invalid ${platformName} settings at ${settingsPath}: ${result.error.message}`, {
+        cause: result.error,
+    });
+}
 /**
- * Claude Code, Codex, Amazon Q format:
- * Writes to settings.local.json with { hooks: { PreToolUse: [...] } }
+ * Claude-shaped JSON format used by Claude Code, Codex, and Amazon Q.
+ * Defaults to settings.local.json; platform metadata may override the filename.
  */
-async function installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksConfig) {
-    const settingsPath = path.join(platformBase, 'settings.local.json');
+async function installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksConfig, configFile, platformName, context) {
+    const settingsPath = path.join(platformBase, configFile);
     // Group by matcher so hooks sharing the same matcher are merged
     const matcherGroups = {};
     for (const [scriptRelPath, config] of Object.entries(hooksConfig)) {
-        const command = buildHookCommand(baseDir, skillsDir, scriptRelPath);
+        const command = buildHookCommand(baseDir, skillsDir, scriptRelPath, context);
         if (!matcherGroups[config.matcher]) {
             matcherGroups[config.matcher] = [];
         }
         matcherGroups[config.matcher].push({ type: 'command', command });
     }
     const newEntries = Object.entries(matcherGroups).map(([matcher, hooks]) => ({ matcher, hooks }));
-    let settings = {};
-    if (await fileExists(settingsPath)) {
-        try {
-            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-        }
-        catch {
-            settings = {};
-        }
-    }
+    const settings = await readSettingsJsonObject(settingsPath, platformName);
     const existingHooks = settings.hooks ?? {};
     const existingPreToolUse = asHookGroup(existingHooks.PreToolUse);
-    const merged = mergeHookGroups(existingPreToolUse, newEntries, Object.keys(hooksConfig));
+    const merged = mergeHookGroups(existingPreToolUse, newEntries, managedHookScriptPaths(hooksConfig));
     settings.hooks = { ...existingHooks, PreToolUse: merged };
     await ensureDir(path.dirname(settingsPath));
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    return { installed: true };
+    return { status: 'installed' };
 }
 /**
- * Qwen Code / Qoder format:
+ * Qwen Code / Qoder / CodeBuddy format:
  * Writes to settings.json with { hooks: { PreToolUse: [{ matcher, hooks: [{ type, command }] }] } }
  */
-async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, _hookFormat) {
+async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName, context) {
     const settingsPath = path.join(platformBase, 'settings.json');
     // Group by matcher
     const matcherGroups = {};
@@ -534,7 +974,7 @@ async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConf
         }
         matcherGroups[config.matcher].push({
             type: 'command',
-            command: buildHookCommand(baseDir, skillsDir, scriptRelPath),
+            command: buildHookCommand(baseDir, skillsDir, scriptRelPath, context),
             description: config.description,
         });
     }
@@ -542,28 +982,20 @@ async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConf
         matcher,
         hooks,
     }));
-    let settings = {};
-    if (await fileExists(settingsPath)) {
-        try {
-            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-        }
-        catch {
-            settings = {};
-        }
-    }
+    const settings = await readSettingsJsonObject(settingsPath, platformName);
     const existingHooks = settings.hooks ?? {};
     const existingPreToolUse = asHookGroup(existingHooks.PreToolUse);
-    const merged = mergeHookGroups(existingPreToolUse, preToolUseEntries, Object.keys(hooksConfig));
+    const merged = mergeHookGroups(existingPreToolUse, preToolUseEntries, managedHookScriptPaths(hooksConfig));
     settings.hooks = { ...existingHooks, PreToolUse: merged };
     await ensureDir(path.dirname(settingsPath));
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    return { installed: true };
+    return { status: 'installed' };
 }
 /**
  * Gemini CLI format:
  * Writes to .gemini/settings.json with { hooks: { BeforeTool: [{ matcher, hooks: [{ type, command }] }] } }
  */
-async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig) {
+async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName, context) {
     const settingsPath = path.join(platformBase, 'settings.json');
     const entries = [];
     for (const [scriptRelPath, config] of Object.entries(hooksConfig)) {
@@ -572,72 +1004,62 @@ async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig)
             hooks: [
                 {
                     type: 'command',
-                    command: buildHookCommand(baseDir, skillsDir, scriptRelPath),
+                    command: buildHookCommand(baseDir, skillsDir, scriptRelPath, context),
                     name: config.description,
                 },
             ],
         });
     }
-    let settings = {};
-    if (await fileExists(settingsPath)) {
-        try {
-            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-        }
-        catch {
-            settings = {};
-        }
-    }
+    const settings = await readSettingsJsonObject(settingsPath, platformName);
     const existingHooks = settings.hooks ?? {};
     const existingBeforeTool = asHookGroup(existingHooks.BeforeTool);
-    const merged = mergeHookGroups(existingBeforeTool, entries, Object.keys(hooksConfig));
+    const merged = mergeHookGroups(existingBeforeTool, entries, managedHookScriptPaths(hooksConfig));
     settings.hooks = { ...existingHooks, BeforeTool: merged };
     await ensureDir(path.dirname(settingsPath));
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    return { installed: true };
+    return { status: 'installed' };
 }
 /**
  * Windsurf format:
  * Writes to .windsurf/hooks.json with { hooks: { pre_write_code: [{ command }] } }
  */
-async function installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig) {
+async function installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName, context) {
     const hooksPath = path.join(platformBase, 'hooks.json');
     const entries = [];
     for (const [scriptRelPath] of Object.entries(hooksConfig)) {
         entries.push({
-            command: buildHookCommand(baseDir, skillsDir, scriptRelPath),
+            command: buildHookCommand(baseDir, skillsDir, scriptRelPath, context),
             show_output: true,
         });
     }
-    let hooksFile = {};
-    if (await fileExists(hooksPath)) {
-        try {
-            hooksFile = JSON.parse(await readFile(hooksPath, 'utf-8'));
-        }
-        catch {
-            hooksFile = {};
-        }
-    }
+    const hooksFile = await readSettingsJsonObject(hooksPath, platformName);
     const existingHooks = hooksFile.hooks ?? {};
     const existingPreWrite = asHookGroup(existingHooks.pre_write_code);
-    const merged = existingPreWrite.filter((entry) => !isManagedHookCommand(entry.command, Object.keys(hooksConfig)));
+    const merged = existingPreWrite.filter((entry) => {
+        const command = entry && typeof entry === 'object' ? entry.command : undefined;
+        return !isManagedHookCommand(command, managedHookScriptPaths(hooksConfig));
+    });
     merged.push(...entries);
     hooksFile.hooks = { ...existingHooks, pre_write_code: merged };
     await ensureDir(path.dirname(hooksPath));
     await writeFile(hooksPath, JSON.stringify(hooksFile, null, 2) + '\n', 'utf-8');
-    return { installed: true };
+    return { status: 'installed' };
 }
 /**
  * GitHub Copilot format:
  * Writes to .github/hooks/comet-guard.json with preToolUse hooks config.
  */
-async function installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig) {
+async function installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig, context) {
     const hooksDir = path.join(platformBase, 'hooks');
     const hookFilePath = path.join(hooksDir, 'comet-guard.json');
     const scriptEntries = [];
-    for (const [scriptRelPath] of Object.entries(hooksConfig)) {
-        const cmd = buildHookCommand(baseDir, skillsDir, scriptRelPath);
+    for (const [scriptRelPath, config] of Object.entries(hooksConfig)) {
+        const cmd = buildHookCommand(baseDir, skillsDir, scriptRelPath, context);
+        const matcher = config.matcher === 'Write|Edit'
+            ? 'create|edit|str_replace_editor|apply_patch'
+            : config.matcher;
         // Hook runs through node on every platform; both fields use the same command
-        scriptEntries.push({ bash: cmd, powershell: cmd });
+        scriptEntries.push({ matcher, bash: cmd, powershell: cmd });
     }
     const hookConfig = {
         version: 1,
@@ -647,13 +1069,13 @@ async function installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig
     };
     await ensureDir(hooksDir);
     await writeFile(hookFilePath, JSON.stringify(hookConfig, null, 2) + '\n', 'utf-8');
-    return { installed: true };
+    return { status: 'installed' };
 }
 /**
  * Kiro format:
  * Writes to .kiro/hooks/comet-phase-guard.kiro.hook as a JSON file.
  */
-async function installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig) {
+async function installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig, context) {
     const hooksDir = path.join(platformBase, 'hooks');
     for (const [scriptRelPath, config] of Object.entries(hooksConfig)) {
         const hookFileName = path.basename(scriptRelPath).replace(/\.mjs$/, '.kiro.hook');
@@ -671,42 +1093,71 @@ async function installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig) {
             },
             then: {
                 type: 'runCommand',
-                command: buildHookCommand(baseDir, skillsDir, scriptRelPath),
+                command: buildHookCommand(baseDir, skillsDir, scriptRelPath, context),
             },
         };
         await ensureDir(hooksDir);
         await writeFile(hookFilePath, JSON.stringify(hookConfig, null, 2) + '\n', 'utf-8');
     }
-    return { installed: true };
+    for (const legacyScript of LEGACY_HOOK_SCRIPTS) {
+        const legacyFile = path.join(hooksDir, path.basename(legacyScript).replace(/\.mjs$/u, '.kiro.hook'));
+        await rm(legacyFile, { force: true });
+    }
+    return { status: 'installed' };
 }
 function managedConfigFields(language = 'en') {
     const artifactLanguage = resolveArtifactLanguage(language);
-    return [
+    const commentLanguage = artifactLanguage.id === 'zh-CN' ? 'zh-CN' : 'en';
+    const top = [
+        {
+            key: 'ambient_resume',
+            def: 'true',
+            comment: projectConfigComment('ambient_resume', commentLanguage),
+        },
+    ];
+    const classic = [
+        {
+            key: 'artifact_layout',
+            def: 'legacy',
+            comment: projectConfigComment('classic.artifact_layout', commentLanguage),
+        },
         {
             key: 'language',
             def: artifactLanguage.id,
-            comment: `# language: ${formatSupportedArtifactLanguages()}`,
+            comment: projectConfigComment('classic.language', commentLanguage),
+        },
+        {
+            key: 'context_compression',
+            def: 'off',
+            comment: projectConfigComment('classic.context_compression', commentLanguage),
+        },
+        {
+            key: 'review_mode',
+            def: 'standard',
+            comment: projectConfigComment('classic.review_mode', commentLanguage),
+        },
+        {
+            key: 'auto_transition',
+            def: 'true',
+            comment: projectConfigComment('classic.auto_transition', commentLanguage),
+        },
+    ];
+    const native = [
+        {
+            key: 'clarification_mode',
+            def: 'sequential',
+            comment: projectConfigComment('native.clarification_mode', commentLanguage),
         },
-        { key: 'context_compression', def: 'off', comment: '# context_compression: off | beta' },
-        { key: 'review_mode', def: 'standard', comment: '# review_mode: off | standard | thorough' },
-        { key: 'auto_transition', def: 'true', comment: '# auto_transition: true | false' },
     ];
+    return { top, native, classic };
 }
 const MANAGED_CONFIG_FIELDS = managedConfigFields();
 function getManagedConfigFields(language = 'en') {
     return language === 'en' ? MANAGED_CONFIG_FIELDS : managedConfigFields(language);
 }
-function parseProjectConfigOverrides(content) {
-    if (!content.trim())
-        return {};
-    const doc = parseDocument(content, { uniqueKeys: false });
-    if (doc.errors.length > 0)
-        return {};
-    const js = doc.toJS();
-    if (!js || typeof js !== 'object' || Array.isArray(js))
-        return {};
+function projectConfigOverrides(value) {
     const out = {};
-    for (const [k, v] of Object.entries(js)) {
+    for (const [k, v] of Object.entries(value)) {
         if (v === null || v === undefined)
             continue;
         if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
@@ -715,40 +1166,168 @@ function parseProjectConfigOverrides(content) {
     }
     return out;
 }
-function renderProjectConfig(existing, language = 'en') {
-    const lines = [];
-    const fields = getManagedConfigFields(language);
-    const managed = new Set(fields.map((f) => f.key));
-    for (const f of fields) {
-        lines.push(f.comment);
-        lines.push(`${f.key}: ${existing[f.key] ?? f.def}`);
+function parseProjectConfigOverrides(content) {
+    if (!content.trim())
+        return {};
+    return projectConfigOverrides(parseWorkflowProjectConfigDocument(content, { allowPartialProject: true }).value);
+}
+// Coerce the string forms captured by `parseProjectConfigOverrides` back into YAML scalars
+// so booleans render as bare true/false rather than quoted strings.
+function coerceConfigScalar(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return raw;
+}
+// `language` is null when the caller has no definitive language selection to assert (e.g.
+// multiple platforms in the same scope disagree and no --language flag was given) — in that
+// case the existing config's language is preserved, falling back to 'en' only when absent.
+// A non-null language always overwrites the managed `classic.language` field: init/update
+// pass it specifically to persist the language the user just selected/installed.
+function renderProjectConfig(existing, language = null) {
+    const resolvedLanguage = language ?? existing.language ?? 'en';
+    const fields = getManagedConfigFields(resolvedLanguage);
+    const managedKeys = new Set([
+        ...fields.top.map((f) => f.key),
+        ...fields.classic.map((f) => f.key),
+    ]);
+    const root = {};
+    for (const f of fields.top) {
+        root[f.key] = coerceConfigScalar(existing[f.key] ?? f.def);
     }
     for (const [k, v] of Object.entries(existing)) {
-        if (!managed.has(k))
-            lines.push(`${k}: ${v}`);
+        if (!managedKeys.has(k))
+            root[k] = coerceConfigScalar(v);
     }
-    lines.push('');
-    return lines.join('\n');
+    const classicBlock = {};
+    for (const f of fields.classic) {
+        const value = f.key === 'language' ? resolvedLanguage : (existing[f.key] ?? f.def);
+        classicBlock[f.key] = coerceConfigScalar(value);
+    }
+    root.classic = classicBlock;
+    return renderStructuredProjectConfig(root, resolvedLanguage === 'zh-CN' ? 'zh-CN' : 'en');
 }
-async function mergeProjectConfig(projectPath, language = 'en') {
-    const configPath = path.join(projectPath, '.comet', 'config.yaml');
+async function mergeProjectConfig(projectPath, language = null, artifactLayoutDefault = 'legacy', completeProjectConfig = false, enableClassicWorkflow = completeProjectConfig) {
     let existing = {};
-    if (await fileExists(configPath)) {
-        existing = parseProjectConfigOverrides(await readFile(configPath, 'utf-8'));
+    let parsedRoot = {};
+    const snapshot = await readWorkflowProjectConfigSnapshot(projectPath, {
+        allowPartialProject: true,
+    });
+    const parsed = snapshot.document;
+    if (parsed) {
+        parsedRoot = parsed.value;
+        existing = projectConfigOverrides(parsedRoot);
+    }
+    // Preserve the full shared-parser value (including unknown extensions) plus
+    // legacy top-level Classic fields pending migration.
+    const root = { ...parsedRoot };
+    if (completeProjectConfig) {
+        root.schema = 'comet.project.v1';
+        const inferredDefault = root.default_workflow === 'native' || root.default_workflow === 'classic'
+            ? root.default_workflow
+            : root.native && typeof root.native === 'object' && !Array.isArray(root.native)
+                ? 'native'
+                : 'classic';
+        root.default_workflow = inferredDefault;
+        const workflows = Array.isArray(root.workflows)
+            ? root.workflows.filter((workflow) => workflow === 'native' || workflow === 'classic')
+            : [inferredDefault];
+        if (enableClassicWorkflow && !workflows.includes('classic'))
+            workflows.push('classic');
+        root.workflows = workflows;
     }
-    await ensureDir(path.dirname(configPath));
-    await writeFile(configPath, renderProjectConfig(existing, language), 'utf-8');
+    const prevClassic = root.classic && typeof root.classic === 'object' && !Array.isArray(root.classic)
+        ? { ...root.classic }
+        : {};
+    const prevNative = root.native && typeof root.native === 'object' && !Array.isArray(root.native)
+        ? { ...root.native }
+        : null;
+    const existingClassicLanguage = typeof prevClassic.language === 'string' ? prevClassic.language : undefined;
+    const resolvedLanguage = language ?? existingClassicLanguage ?? existing.language ?? 'en';
+    const fields = getManagedConfigFields(resolvedLanguage);
+    // Top-level managed field (ambient_resume).
+    for (const f of fields.top) {
+        root[f.key] = coerceConfigScalar(existing[f.key] ?? f.def);
+    }
+    // Native settings are managed only when the project already has a Native block. This lets
+    // update add new Native defaults without activating Native in Classic-only installations.
+    if (prevNative) {
+        const nativeBlock = { ...prevNative };
+        for (const f of fields.native) {
+            const value = nativeBlock[f.key] ?? f.def;
+            if (f.key === 'clarification_mode' && value !== 'sequential' && value !== 'batch') {
+                throw new Error('native.clarification_mode must be sequential or batch');
+            }
+            nativeBlock[f.key] = coerceConfigScalar(value);
+        }
+        if (nativeBlock.snapshot === undefined) {
+            nativeBlock.snapshot = {
+                include: ['**/*'],
+                exclude: [],
+                max_files: 10_000,
+                max_total_bytes: 256 * 1024 * 1024,
+                max_duration_ms: 60_000,
+            };
+        }
+        root.native = nativeBlock;
+    }
+    // Classic block: preserve explicit new-format values and unknown extension fields, then migrate legacy top-level values,
+    // then apply defaults. An explicit language argument still represents the caller's requested
+    // install/update language and therefore overrides both stored forms.
+    const shouldMergeClassic = !completeProjectConfig || enableClassicWorkflow || root.classic;
+    if (shouldMergeClassic) {
+        const classicBlock = { ...prevClassic };
+        for (const f of fields.classic) {
+            let value;
+            if (f.key === 'language') {
+                value = resolvedLanguage;
+            }
+            else if (f.key === 'artifact_layout') {
+                value = prevClassic[f.key] ?? artifactLayoutDefault;
+            }
+            else {
+                const legacyTop = root[f.key];
+                if (prevClassic[f.key] !== undefined)
+                    value = prevClassic[f.key];
+                else if (legacyTop !== undefined)
+                    value = legacyTop;
+                else
+                    value = f.def;
+            }
+            classicBlock[f.key] = coerceConfigScalar(value);
+        }
+        root.classic = classicBlock;
+        // Remove migrated legacy top-level Classic fields so they don't linger at the root.
+        for (const f of fields.classic) {
+            delete root[f.key];
+        }
+    }
+    const output = renderStructuredProjectConfig(root, resolvedLanguage === 'zh-CN' ? 'zh-CN' : 'en');
+    parseWorkflowProjectConfigDocument(output, { allowPartialProject: true });
+    await writeWorkflowProjectConfigSource(projectPath, output, {
+        allowPartialProject: !completeProjectConfig,
+        expectedIdentity: snapshot.identity,
+    });
 }
-async function createWorkingDirs(projectPath, language = 'en') {
+async function createWorkingDirs(projectPath, language = 'en', artifactLayout = 'docs', initializationPermit) {
+    const layout = await assertClassicLayoutInitializationSafe(projectPath, artifactLayout, initializationPermit);
     const dirs = [
-        path.join(projectPath, 'docs', 'superpowers', 'specs'),
-        path.join(projectPath, 'docs', 'superpowers', 'plans'),
+        layout.archiveDir,
+        layout.specsDir,
+        layout.superpowersSpecsDir,
+        layout.superpowersPlansDir,
+        layout.superpowersReportsDir,
         path.join(projectPath, '.comet'),
     ];
     for (const dir of dirs) {
-        await ensureDir(dir);
+        const relative = path.relative(layout.projectRoot, dir).replaceAll('\\', '/');
+        await ensureProtectedProjectDirectory(layout.projectRoot, relative, {
+            label: `Classic working directory ${relative}`,
+        });
     }
-    await mergeProjectConfig(projectPath, language);
+    await checkpointClassicLayoutInitialization(projectPath, layout.initializationPermit);
+    await installCometProjectInstructions(projectPath, language === 'zh-CN' ? 'zh' : 'en');
 }
-export { copyCometSkillsForPlatform, copyCometRulesForPlatform, installCometHooksForPlatform, readManifest, getManagedSkillPaths, getManifestSkills, getUserFacingSkillNames, createWorkingDirs, getAssetsDir, computeRuleDestPath, formatRuleContent, isManagedHookCommand, planSkillDirectoryCopy, mergeProjectConfig, parseProjectConfigOverrides, renderProjectConfig, getCentralSkillsDir, installSkillsAsSymlink, };
+export { copyCometSkillsForPlatform, copyCometRulesForPlatform, installCometHooksForPlatform, readManifest, getManagedSkillPaths, getManagedSkillPathsForSelection, getManifestSkills, getUserFacingSkillNames, createWorkingDirs, getAssetsDir, computeRuleDestPath, formatRuleContent, isManagedHookCommand, buildHookCommand, removeManagedHooksFromJsonFile, planSkillDirectoryCopy, mergeProjectConfig, parseProjectConfigOverrides, renderProjectConfig, getCentralSkillsDir, installSkillsAsSymlink, prepareManagedSkillCopyTarget, prepareNativeSkillInstallTarget, };
 //# sourceMappingURL=platform-install.js.map