@rpamis/comet 0.4.0-beta.6 → 0.4.0-beta.8

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

@@ -5,11 +5,23 @@ import { fileURLToPath } from 'url';
 import { parseDocument } from 'yaml';
 import { fileExists, readJson, copyFile, ensureDir } from '../../platform/fs/file-system.js';
 import { getPlatformConfigDir, getPlatformSkillsDir, } from '../../platform/install/platforms.js';
-import { formatSupportedArtifactLanguages, resolveArtifactLanguage } from './languages.js';
+import { resolveArtifactLanguage } from './languages.js';
 import { installCometProjectInstructions } from './project-instructions.js';
 import { readJsonObjectFile } from './json-object.js';
+import { projectConfigComment, renderStructuredProjectConfig, } from '../workflow-contract/project-config.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) => ({
@@ -21,12 +33,27 @@ 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) {
+function getManagedSkillReplacementPaths(manifest, workflowSelection = 'both') {
     const allowed = new Set();
-    for (const skillPath of getManagedSkillPaths(manifest)) {
+    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('/'));
@@ -34,9 +61,9 @@ function getManagedSkillReplacementPaths(manifest) {
     }
     return allowed;
 }
-function getManagedSkillTopLevelEntries(manifest) {
+function getManagedSkillTopLevelEntries(manifest, workflowSelection = 'both') {
     const entries = new Set();
-    for (const skillPath of getManagedSkillPaths(manifest)) {
+    for (const skillPath of getManagedSkillPathsForSelection(manifest, workflowSelection)) {
         const [topLevel] = skillPath.split('/').filter(Boolean);
         if (topLevel)
             entries.add(topLevel);
@@ -138,11 +165,89 @@ async function lstatOrNull(filePath) {
         return await lstat(filePath);
     }
     catch (err) {
-        if (err.code === 'ENOENT')
+        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()) {
@@ -169,7 +274,7 @@ async function createSkillsSymlinks(targetRoot, linkRoot, managedEntries, topLev
  * 1. Copy skills to central store (.comet/skills/)
  * 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');
@@ -180,13 +285,15 @@ 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 managedSkillReplacementPaths = getManagedSkillReplacementPaths(manifest);
-    const managedSkillTopLevelEntries = getManagedSkillTopLevelEntries(manifest);
+    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);
@@ -216,23 +323,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');
@@ -246,7 +353,9 @@ 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);
@@ -269,13 +378,13 @@ 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;
@@ -410,9 +519,9 @@ async function readManifest() {
     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.
@@ -448,12 +557,21 @@ function selectRulePathsForLanguage(rulePaths, languageId) {
     }
     return [...selected.values()].map((entry) => entry.rulePath);
 }
-async function copyCometRulesForPlatform(baseDir, platform, overwrite, languageId, scope = 'project') {
+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, failed: 0 };
     }
     const manifest = await readManifest();
-    const rulePaths = selectRulePathsForLanguage(manifest.rules ?? [], languageId);
+    const rulePaths = selectRulePathsForLanguage(managedRulesForSelection(manifest, workflowSelection), languageId);
     if (!rulePaths || rulePaths.length === 0) {
         return { copied: 0, skipped: 0, failed: 0 };
     }
@@ -496,6 +614,20 @@ async function copyCometRulesForPlatform(baseDir, platform, overwrite, languageI
             failed++;
         }
     }
+    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) {
@@ -543,7 +675,7 @@ ${content}`;
  *   'copilot' — hooks/*.json with preToolUse
  *   'kiro' — hooks/*.kiro.hook JSON files
  */
-async function installCometHooksForPlatform(baseDir, platform, scope = 'project') {
+async function installCometHooksForPlatform(baseDir, platform, scope = 'project', workflowSelection = 'classic') {
     if (!platform.supportsHooks) {
         return { status: 'skipped', reason: 'platform does not support hooks' };
     }
@@ -555,7 +687,7 @@ async function installCometHooksForPlatform(baseDir, platform, scope = 'project'
     }
     try {
         const manifest = await readManifest();
-        const hooksConfig = manifest.hooks;
+        const hooksConfig = managedHooksForSelection(manifest, workflowSelection);
         if (!hooksConfig || Object.keys(hooksConfig).length === 0) {
             return { status: 'skipped', reason: 'no hooks defined in manifest' };
         }
@@ -564,31 +696,47 @@ async function installCometHooksForPlatform(baseDir, platform, scope = 'project'
         const platformBase = path.join(baseDir, getPlatformConfigDir(platform, scope));
         switch (hookFormat) {
             case 'claude-code': {
-                const result = await installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.hookConfigFile ?? 'settings.local.json', platform.name);
+                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 {
-                            await removeManagedHooksFromJsonFile(path.join(platformBase, legacyFile), Object.keys(hooksConfig));
+                            const cleanup = await removeManagedHooksFromJsonFile(path.join(platformBase, legacyFile), managedHookScriptPaths(hooksConfig));
+                            if (cleanup.failed > 0)
+                                failedLegacyFiles.push(legacyFile);
                         }
                         catch {
-                            // Historical Hook cleanup is best-effort after canonical install succeeds.
+                            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':
             case 'codebuddy':
-                return await installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name);
+                return await installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'gemini':
-                return await installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name);
+                return await installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'windsurf':
-                return await installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name);
+                return await installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig, platform.name, { platformId: platform.id, scope });
             case 'copilot':
-                return await installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig, {
+                    platformId: platform.id,
+                    scope,
+                });
             case 'kiro':
-                return await installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig);
+                return await installKiroHooks(baseDir, platformBase, skillsDir, hooksConfig, {
+                    platformId: platform.id,
+                    scope,
+                });
             default:
                 return { status: 'failed', reason: `unsupported hook format: ${hookFormat}` };
         }
@@ -601,10 +749,18 @@ 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 = [];
@@ -780,12 +936,12 @@ async function readSettingsJsonObject(settingsPath, platformName) {
  * 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, configFile, platformName) {
+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] = [];
         }
@@ -795,7 +951,7 @@ async function installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksCon
     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');
@@ -805,7 +961,7 @@ async function installClaudeCodeHooks(baseDir, platformBase, skillsDir, hooksCon
  * Qwen Code / Qoder / CodeBuddy format:
  * Writes to settings.json with { hooks: { PreToolUse: [{ matcher, hooks: [{ type, command }] }] } }
  */
-async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName) {
+async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName, context) {
     const settingsPath = path.join(platformBase, 'settings.json');
     // Group by matcher
     const matcherGroups = {};
@@ -815,7 +971,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,
         });
     }
@@ -826,7 +982,7 @@ async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConf
     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');
@@ -836,7 +992,7 @@ async function installQwenStyleHooks(baseDir, platformBase, skillsDir, hooksConf
  * Gemini CLI format:
  * Writes to .gemini/settings.json with { hooks: { BeforeTool: [{ matcher, hooks: [{ type, command }] }] } }
  */
-async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName) {
+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)) {
@@ -845,7 +1001,7 @@ async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig,
             hooks: [
                 {
                     type: 'command',
-                    command: buildHookCommand(baseDir, skillsDir, scriptRelPath),
+                    command: buildHookCommand(baseDir, skillsDir, scriptRelPath, context),
                     name: config.description,
                 },
             ],
@@ -854,7 +1010,7 @@ async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig,
     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');
@@ -864,12 +1020,12 @@ async function installGeminiHooks(baseDir, platformBase, skillsDir, hooksConfig,
  * Windsurf format:
  * Writes to .windsurf/hooks.json with { hooks: { pre_write_code: [{ command }] } }
  */
-async function installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfig, platformName) {
+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,
         });
     }
@@ -878,7 +1034,7 @@ async function installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfi
     const existingPreWrite = asHookGroup(existingHooks.pre_write_code);
     const merged = existingPreWrite.filter((entry) => {
         const command = entry && typeof entry === 'object' ? entry.command : undefined;
-        return !isManagedHookCommand(command, Object.keys(hooksConfig));
+        return !isManagedHookCommand(command, managedHookScriptPaths(hooksConfig));
     });
     merged.push(...entries);
     hooksFile.hooks = { ...existingHooks, pre_write_code: merged };
@@ -890,14 +1046,17 @@ async function installWindsurfHooks(baseDir, platformBase, skillsDir, hooksConfi
  * 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,
@@ -913,7 +1072,7 @@ async function installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig
  * 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');
@@ -931,26 +1090,58 @@ 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');
     }
+    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: '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),
         },
-        { 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' },
     ];
+    const native = [
+        {
+            key: 'clarification_mode',
+            def: 'sequential',
+            comment: projectConfigComment('native.clarification_mode', commentLanguage),
+        },
+    ];
+    return { top, native, classic };
 }
 const MANAGED_CONFIG_FIELDS = managedConfigFields();
 function getManagedConfigFields(language = 'en') {
@@ -975,36 +1166,112 @@ function parseProjectConfigOverrides(content) {
     }
     return out;
 }
+// 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 `language` field: init/update pass it
-// specifically to persist the language the user just selected/installed.
+// 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 lines = [];
     const fields = getManagedConfigFields(resolvedLanguage);
-    const managed = new Set(fields.map((f) => f.key));
-    for (const f of fields) {
-        lines.push(f.comment);
-        const value = f.key === 'language' ? resolvedLanguage : (existing[f.key] ?? f.def);
-        lines.push(`${f.key}: ${value}`);
+    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);
+    }
+    const classicBlock = {};
+    for (const f of fields.classic) {
+        const value = f.key === 'language' ? resolvedLanguage : (existing[f.key] ?? f.def);
+        classicBlock[f.key] = coerceConfigScalar(value);
     }
-    lines.push('');
-    return lines.join('\n');
+    root.classic = classicBlock;
+    return renderStructuredProjectConfig(root, resolvedLanguage === 'zh-CN' ? 'zh-CN' : 'en');
 }
 async function mergeProjectConfig(projectPath, language = null) {
     const configPath = path.join(projectPath, '.comet', 'config.yaml');
     let existing = {};
+    let existingSource = '';
     if (await fileExists(configPath)) {
-        existing = parseProjectConfigOverrides(await readFile(configPath, 'utf-8'));
+        existingSource = await readFile(configPath, 'utf-8');
+        existing = parseProjectConfigOverrides(existingSource);
     }
     await ensureDir(path.dirname(configPath));
-    await writeFile(configPath, renderProjectConfig(existing, language), 'utf-8');
+    // Preserve the full parsed structure (e.g. the `native:` block) plus any legacy top-level
+    // Classic fields pending migration. Falling back to an empty mapping keeps this idempotent
+    // for a missing or unparseable config.
+    const document = parseDocument(existingSource, { uniqueKeys: false });
+    const parsedRoot = document.errors.length === 0 ? document.toJS() : null;
+    const root = parsedRoot && typeof parsedRoot === 'object' && !Array.isArray(parsedRoot)
+        ? { ...parsedRoot }
+        : {};
+    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);
+        }
+        root.native = nativeBlock;
+    }
+    // Classic block: preserve explicit new-format values, 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 classicBlock = {};
+    for (const f of fields.classic) {
+        let value;
+        if (f.key === 'language') {
+            value = resolvedLanguage;
+        }
+        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);
+    }
+    // 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];
+    }
+    root.classic = classicBlock;
+    await writeFile(configPath, renderStructuredProjectConfig(root, resolvedLanguage === 'zh-CN' ? 'zh-CN' : 'en'), 'utf-8');
 }
 async function createWorkingDirs(projectPath, language = 'en') {
     const dirs = [
@@ -1018,5 +1285,5 @@ async function createWorkingDirs(projectPath, language = 'en') {
     await mergeProjectConfig(projectPath, language);
     await installCometProjectInstructions(projectPath, language === 'zh-CN' ? 'zh' : 'en');
 }
-export { copyCometSkillsForPlatform, copyCometRulesForPlatform, installCometHooksForPlatform, readManifest, getManagedSkillPaths, getManifestSkills, getUserFacingSkillNames, createWorkingDirs, getAssetsDir, computeRuleDestPath, formatRuleContent, isManagedHookCommand, buildHookCommand, removeManagedHooksFromJsonFile, 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