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

package/dist/app/commands/update.js

@@ -4,33 +4,103 @@ import { promises as fs } from 'fs';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 import { select } from '@inquirer/prompts';
-import { fileExists, readDir, readJson } from '../../platform/fs/file-system.js';
-import { getBaseDir } from '../../platform/install/detect.js';
-import { copyCometSkillsForPlatform, copyCometRulesForPlatform, installCometHooksForPlatform, getManifestSkills, mergeProjectConfig, } from '../../domains/skill/platform-install.js';
-import { PLATFORMS, getPlatformSkillsDir, } from '../../platform/install/platforms.js';
+import { fileExists, readJson } from '../../platform/fs/file-system.js';
+import { getBaseDir, hasSkills } from '../../platform/install/detect.js';
+import { copyCometSkillsForPlatform, copyCometRulesForPlatform, installCometHooksForPlatform, getManifestSkills, mergeProjectConfig, prepareManagedSkillCopyTarget, } from '../../domains/skill/platform-install.js';
+import { removeLegacyCometSkillsForPlatform } from '../../domains/skill/uninstall.js';
+import { installCometProjectInstructions } from '../../domains/skill/project-instructions.js';
+import { artifactLanguageToSkillLanguage, LANGUAGES, } from '../../domains/skill/languages.js';
+import { getPlatformSkillsDir, getPlatformSkillsDirs, } from '../../platform/install/platforms.js';
+import { resolvePlatformTarget } from '../../platform/install/platform-targets.js';
+import { resolveCanonicalSkillRootOwners } from '../../platform/install/skill-root-owner.js';
+import { listProjectRegistryEntries, removeProjectInstallation, upsertProjectInstallation, } from '../../platform/install/project-registry.js';
 import { hasCodegraphProjectIndex, installCodegraph, } from '../../domains/integrations/codegraph.js';
-import { printVersionInfo } from '../../platform/version/version.js';
+import { installOpenSpec, isProjectMutationGuardError, } from '../../domains/integrations/openspec.js';
+import { assertClassicLayoutInitializationSafe, beginClassicLayoutInitialization, checkpointClassicLayoutInitialization, completeClassicLayoutInitialization, } from '../../domains/comet-classic/classic-layout-initialization.js';
+import { classicLayoutPaths } from '../../domains/comet-classic/classic-layout.js';
+import { assertClassicOpenSpecRootHealthy } from '../../domains/comet-classic/classic-openspec-root.js';
+import { discoverNativeProject } from '../../domains/comet-native/native-paths.js';
+import { readWorkflowProjectConfigSnapshot } from '../../domains/workflow-contract/project-config-reader.js';
+import { migrateLegacyClassicSelection } from '../../domains/comet-entry/current-selection.js';
+import { getLatestVersion, printVersionInfo } from '../../platform/version/version.js';
 import { t } from './i18n.js';
+import { assertProjectScopeOptions, resolveProjectScopeMode } from './project-scope-selection.js';
 const PACKAGE_NAME = '@rpamis/comet';
 const OFFICIAL_REGISTRY = 'https://registry.npmjs.org';
-function languageToSkillsDir(language, fallback) {
-    return (language ?? fallback) === 'zh' ? 'skills-zh' : 'skills';
+const CANDIDATE_COMMAND_LIMITS = {
+    timeoutMs: 15_000,
+    maxOutputBytes: 256 * 1024,
+};
+const NPM_INSPECTION_LIMITS = {
+    timeoutMs: 15_000,
+    maxOutputBytes: 64 * 1024,
+};
+const CANDIDATE_INSTALL_LIMITS = {
+    timeoutMs: 3 * 60_000,
+    maxOutputBytes: 4 * 1024 * 1024,
+};
+const NPM_MUTATION_LIMITS = {
+    timeoutMs: 10 * 60_000,
+    maxOutputBytes: 8 * 1024 * 1024,
+};
+function createNpmUpdateFailure(scope, reason) {
+    const detail = reason ? `: ${reason}` : '';
+    const error = new Error(`npm package update failed (${scope} scope)${detail}`);
+    error.npmScope = scope;
+    return error;
+}
+function isGlobalNpmUpdateFailure(error) {
+    return error?.npmScope === 'global';
+}
+function resolveTargetLanguage(language, fallback) {
+    return (language ?? fallback) === 'zh' ? 'zh' : 'en';
+}
+function languageToSkillsDir(languageId) {
+    return languageId === 'zh' ? 'skills-zh' : 'skills';
+}
+function languageToArtifactLanguage(languageId) {
+    return LANGUAGES.find((entry) => entry.id === languageId).artifactLanguage;
 }
 function getScopedBaseDir(scope, projectPath, globalBaseDir = os.homedir()) {
     return scope === 'global' ? globalBaseDir : projectPath;
 }
 function getInstalledCometSkillsDirs(baseDir, platform, scope = 'project') {
-    const dirs = [path.join(baseDir, getPlatformSkillsDir(platform, scope), 'skills')];
-    if (scope === 'global' && platform.id === 'pi') {
-        dirs.push(path.join(baseDir, platform.skillsDir, 'skills'));
+    const skillsDirs = [
+        ...getPlatformSkillsDirs(platform, scope),
+        ...(scope === 'global' && platform.id === 'pi' ? [platform.skillsDir] : []),
+    ];
+    return [...new Set(skillsDirs)].map((skillsDir) => path.join(baseDir, skillsDir, 'skills'));
+}
+function isMissingInspectionError(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+async function targetPathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch (error) {
+        if (isMissingInspectionError(error))
+            return false;
+        throw error;
+    }
+}
+async function readTargetDir(dirPath) {
+    try {
+        return await fs.readdir(dirPath);
+    }
+    catch (error) {
+        if (isMissingInspectionError(error))
+            return [];
+        throw error;
     }
-    return [...new Set(dirs)];
 }
 async function hasLocalCometSkills(baseDir, platform, scope) {
     for (const skillsDir of getInstalledCometSkillsDirs(baseDir, platform, scope)) {
-        if (!(await fileExists(skillsDir)))
+        if (!(await targetPathExists(skillsDir)))
             continue;
-        const entries = await readDir(skillsDir);
+        const entries = await readTargetDir(skillsDir);
         if (entries.some((entry) => entry.startsWith('comet')))
             return true;
     }
@@ -38,20 +108,21 @@ async function hasLocalCometSkills(baseDir, platform, scope) {
 }
 async function detectInstalledCometLanguage(baseDir, platform, scope = 'project') {
     for (const skillsDir of getInstalledCometSkillsDirs(baseDir, platform, scope)) {
-        if (!(await fileExists(skillsDir)))
+        if (!(await targetPathExists(skillsDir)))
             continue;
-        const entries = (await readDir(skillsDir)).filter((entry) => entry.startsWith('comet'));
+        const entries = (await readTargetDir(skillsDir)).filter((entry) => entry.startsWith('comet'));
         for (const entry of entries) {
             const skillPath = path.join(skillsDir, entry, 'SKILL.md');
-            if (!(await fileExists(skillPath)))
+            if (!(await targetPathExists(skillPath)))
                 continue;
             try {
                 const content = await fs.readFile(skillPath, 'utf-8');
                 if (/[㐀-鿿]/u.test(content))
                     return 'zh';
             }
-            catch {
-                // Fall through to the default English asset set if the file cannot be read.
+            catch (error) {
+                if (!isMissingInspectionError(error))
+                    throw error;
             }
         }
     }
@@ -62,7 +133,10 @@ async function detectInstalledCometTargets(projectPath, options = {}) {
     const targets = [];
     for (const scope of scopes) {
         const baseDir = getScopedBaseDir(scope, projectPath, options.globalBaseDir);
-        for (const platform of PLATFORMS) {
+        const owners = await resolveCanonicalSkillRootOwners(baseDir, scope, {
+            respectDetectionPaths: options.respectDetectionPaths,
+        });
+        for (const { platform } of owners) {
             if (!(await hasLocalCometSkills(baseDir, platform, scope)))
                 continue;
             targets.push({
@@ -93,18 +167,89 @@ async function detectCometPackageScope(projectPath, packageRoot = path.resolve(p
     }
     return 'global';
 }
-function buildNpmUpdateArgs(scope) {
+function buildNpmUpdateArgs(scope, version = 'latest') {
+    const packageSpec = `${PACKAGE_NAME}@${version}`;
     return scope === 'global'
-        ? ['install', '-g', `${PACKAGE_NAME}@latest`, '--registry', OFFICIAL_REGISTRY]
-        : ['install', `${PACKAGE_NAME}@latest`, '--registry', OFFICIAL_REGISTRY];
+        ? ['install', '-g', packageSpec, '--registry', OFFICIAL_REGISTRY]
+        : ['install', packageSpec, '--registry', OFFICIAL_REGISTRY];
+}
+function formatNpmUpdateCommand(scope, version = 'latest') {
+    return ['npm', ...buildNpmUpdateArgs(scope, version)].join(' ');
+}
+function parseSemver(version) {
+    const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.exec(version);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4]?.split('.') ?? [],
+    };
+}
+function comparePrereleaseIdentifiers(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        if (left.length === right.length)
+            return 0;
+        return left.length === 0 ? 1 : -1;
+    }
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const leftPart = left[index];
+        const rightPart = right[index];
+        if (leftPart === undefined)
+            return -1;
+        if (rightPart === undefined)
+            return 1;
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/u.test(leftPart);
+        const rightNumeric = /^\d+$/u.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return Number(leftPart) - Number(rightPart);
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+function compareSemverVersions(left, right) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (left[field] !== right[field])
+            return left[field] - right[field];
+    }
+    return comparePrereleaseIdentifiers(left.prerelease, right.prerelease);
 }
-function formatNpmUpdateCommand(scope) {
-    return ['npm', ...buildNpmUpdateArgs(scope)].join(' ');
+function resolveNpmSelfUpdatePlan(currentVersion, registryVersion) {
+    const current = parseSemver(currentVersion);
+    const registry = parseSemver(registryVersion);
+    if (!current) {
+        return {
+            action: 'fail',
+            reason: `current Comet version is not valid semver: ${currentVersion}`,
+        };
+    }
+    if (!registry) {
+        return {
+            action: 'fail',
+            reason: `registry Comet version is not valid semver: ${registryVersion}`,
+        };
+    }
+    const comparison = compareSemverVersions(registry, current);
+    if (comparison < 0) {
+        return {
+            action: 'skip',
+            reason: `registry version ${registryVersion} is older than current version ${currentVersion}`,
+        };
+    }
+    if (comparison === 0) {
+        return { action: 'skip', reason: `Comet ${currentVersion} is already installed` };
+    }
+    return { action: 'update', version: registryVersion };
 }
 function formatSkillUpdateCommand(scope, platform, languageSkillsDir, installMode = 'copy') {
     const destPrefix = scope === 'global' ? '~/' : '';
     if (installMode === 'symlink') {
-        return `symlink .comet/skills/ -> ${destPrefix}${getPlatformSkillsDir(platform, scope)}/skills/ (${scope})`;
+        return `symlink via .comet/skills/ in ${destPrefix}${getPlatformSkillsDir(platform, scope)}/skills/ (${scope})`;
     }
     return `copy assets/${languageSkillsDir} -> ${destPrefix}${getPlatformSkillsDir(platform, scope)}/skills/ (${scope})`;
 }
@@ -121,34 +266,397 @@ async function selectInstallMode(options, lang) {
         ],
     });
 }
-function getNpmExecutable() {
-    return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+async function resolveNpmCliPath() {
+    const candidates = new Set();
+    const addStandardCandidates = (baseDir) => {
+        candidates.add(path.join(baseDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+        candidates.add(path.resolve(baseDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+    };
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && path.basename(npmExecPath).toLowerCase() === 'npm-cli.js') {
+        candidates.add(path.resolve(npmExecPath));
+    }
+    addStandardCandidates(path.dirname(process.execPath));
+    const pathValue = process.env.PATH ?? process.env.Path ?? '';
+    for (const entry of pathValue.split(path.delimiter).filter(Boolean)) {
+        addStandardCandidates(entry);
+        const npmExecutable = path.join(entry, process.platform === 'win32' ? 'npm.cmd' : 'npm');
+        try {
+            const resolved = await fs.realpath(npmExecutable);
+            if (path.basename(resolved).toLowerCase() === 'npm-cli.js')
+                candidates.add(resolved);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    for (const candidate of candidates) {
+        try {
+            return await resolveRegularContainedFile(candidate, path.resolve(candidate, '..', '..'), 'npm CLI');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    throw new Error('Unable to locate npm CLI (npm-cli.js) without using a shell');
 }
-async function updateCometNpmPackage(scope, projectPath, log, jsonMode = false) {
-    const args = buildNpmUpdateArgs(scope);
-    const cwd = scope === 'global' ? process.cwd() : projectPath;
+function runCapturedProcess(command, args, cwd, limits) {
     return new Promise((resolve) => {
-        // In JSON mode, discard npm's stdout/stderr so it cannot corrupt the JSON
-        // document emitted on stdout. 'ignore' avoids the pipe backpressure a
-        // verbose npm install could otherwise cause.
-        const child = spawn(getNpmExecutable(), args, {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let capturedBytes = 0;
+        let spawnError = null;
+        let limitReason = null;
+        let forceKillTimer = null;
+        const child = spawn(command, args, {
             cwd,
-            stdio: jsonMode ? 'ignore' : 'inherit',
-            shell: true,
-        });
-        child.on('error', (err) => {
-            log(`  npm package: failed to launch npm — ${err.message}`);
-            resolve(false);
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
         });
-        child.on('exit', (code) => {
-            if (code !== 0) {
-                log(`  npm package: update failed (exit code ${code}). Unable to reach the official npm registry at ${OFFICIAL_REGISTRY}.`);
-                log(`  Check your network connection or firewall settings and try again.`);
+        const terminate = (reason) => {
+            if (limitReason !== null)
+                return;
+            limitReason = reason;
+            child.kill();
+            forceKillTimer = setTimeout(() => child.kill('SIGKILL'), 1_000);
+            forceKillTimer.unref?.();
+        };
+        const capture = (target, chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            if (!limits) {
+                target.push(bytes);
+                return;
             }
-            resolve(code === 0);
+            const remaining = Math.max(0, limits.maxOutputBytes - capturedBytes);
+            if (remaining > 0)
+                target.push(bytes.subarray(0, remaining));
+            capturedBytes += bytes.length;
+            if (capturedBytes > limits.maxOutputBytes) {
+                terminate(`process output exceeded ${limits.maxOutputBytes} bytes`);
+            }
+        };
+        child.stdout?.on('data', (chunk) => capture(stdoutChunks, chunk));
+        child.stderr?.on('data', (chunk) => capture(stderrChunks, chunk));
+        child.on('error', (error) => {
+            spawnError = error;
+        });
+        const timeout = limits
+            ? setTimeout(() => terminate(`process timed out after ${limits.timeoutMs}ms`), limits.timeoutMs)
+            : null;
+        timeout?.unref?.();
+        child.on('close', (exitCode) => {
+            if (timeout)
+                clearTimeout(timeout);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const success = spawnError === null && limitReason === null && exitCode === 0;
+            const captured = (stderr.trim() || stdout.trim()).slice(-4000);
+            resolve({
+                success,
+                exitCode,
+                stdout,
+                stderr,
+                reason: success
+                    ? undefined
+                    : (limitReason ??
+                        (spawnError
+                            ? `failed to launch ${command}: ${spawnError.message}`
+                            : captured || `${command} exited with code ${exitCode ?? 'unknown'}`)),
+            });
         });
     });
 }
+function runNpmCli(npmCliPath, args, cwd, limits = NPM_INSPECTION_LIMITS) {
+    return runCapturedProcess(process.execPath, [npmCliPath, ...args], cwd, limits);
+}
+async function removeDirectoryWithRetry(directory, attempts = 3) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            await fs.rm(directory, { recursive: true, force: true });
+            return null;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < attempts) {
+                await new Promise((resolve) => setTimeout(resolve, attempt * 25));
+            }
+        }
+    }
+    return lastError;
+}
+async function resolveRegularContainedFile(file, root, label) {
+    const [realRoot, realFile] = await Promise.all([fs.realpath(root), fs.realpath(file)]);
+    const stat = await fs.lstat(realFile);
+    if (!stat.isFile() || stat.isSymbolicLink() || !isSameOrInside(realFile, realRoot)) {
+        throw new Error(`${label} must be a regular file inside ${realRoot}`);
+    }
+    return realFile;
+}
+async function readCometPackage(packageRoot) {
+    const resolvedPackageRoot = path.resolve(packageRoot);
+    const realPackageRoot = await fs.realpath(resolvedPackageRoot);
+    const packageRootStat = await fs.lstat(realPackageRoot);
+    if (!packageRootStat.isDirectory() || packageRootStat.isSymbolicLink()) {
+        throw new Error(`Comet package root is not a real directory: ${packageRoot}`);
+    }
+    const packageJsonPath = await resolveRegularContainedFile(path.join(resolvedPackageRoot, 'package.json'), resolvedPackageRoot, 'Comet package.json');
+    const pkg = await readJson(packageJsonPath);
+    if (typeof pkg.version !== 'string') {
+        throw new Error(`Comet package has no valid version: ${packageJsonPath}`);
+    }
+    const binReference = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.comet;
+    if (!binReference)
+        throw new Error(`Comet package has no comet bin: ${packageJsonPath}`);
+    const binPath = path.resolve(resolvedPackageRoot, binReference);
+    if (!isSameOrInside(binPath, resolvedPackageRoot)) {
+        throw new Error(`Comet package bin is invalid: ${binReference}`);
+    }
+    let realBinPath;
+    try {
+        realBinPath = await resolveRegularContainedFile(binPath, resolvedPackageRoot, 'Comet package bin');
+    }
+    catch (error) {
+        throw new Error(`Comet package bin is invalid: ${binReference}`, { cause: error });
+    }
+    return { packageRoot: resolvedPackageRoot, version: pkg.version, binPath: realBinPath };
+}
+async function readInstalledCometPackage(scope, projectPath, npmCliPath) {
+    if (scope === 'project') {
+        const [rootResult, prefixResult] = await Promise.all([
+            runNpmCli(npmCliPath, ['root'], projectPath),
+            runNpmCli(npmCliPath, ['prefix'], projectPath),
+        ]);
+        const npmRoot = parseNpmAbsolutePath(rootResult, 'npm root');
+        const npmPrefix = parseNpmAbsolutePath(prefixResult, 'npm prefix');
+        const installedPackage = await readCometPackage(path.join(npmRoot, '@rpamis', 'comet'));
+        return {
+            ...installedPackage,
+            projectMetadataRoots: [...new Set([path.resolve(projectPath), npmPrefix])],
+        };
+    }
+    const rootResult = await runNpmCli(npmCliPath, ['root', '--global'], projectPath);
+    const npmRoot = parseNpmAbsolutePath(rootResult, 'npm root --global');
+    return readCometPackage(path.join(npmRoot, '@rpamis', 'comet'));
+}
+function parseNpmAbsolutePath(result, command) {
+    if (!result.success) {
+        throw new Error(`Unable to resolve ${command}: ${result.reason ?? 'unknown error'}`);
+    }
+    const outputPath = result.stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .at(-1);
+    if (!outputPath || !path.isAbsolute(outputPath)) {
+        throw new Error(`${command} returned an invalid path: ${outputPath ?? '<empty>'}`);
+    }
+    return path.resolve(outputPath);
+}
+async function validateCometPackageCommands(candidate, expectedVersion) {
+    const checks = [
+        {
+            args: ['--version'],
+            accepts: (stdout) => stdout.trim() === expectedVersion,
+            label: 'version command',
+        },
+        {
+            args: ['workflow', 'resolve', '--help'],
+            accepts: (stdout) => stdout.includes('Usage: comet workflow resolve'),
+            label: 'workflow resolve command',
+        },
+        {
+            args: ['native', '--help'],
+            accepts: (stdout) => stdout.includes('Usage: comet native'),
+            label: 'native command',
+        },
+    ];
+    for (const check of checks) {
+        const result = await runCapturedProcess(process.execPath, [candidate.binPath, ...check.args], candidate.packageRoot, CANDIDATE_COMMAND_LIMITS);
+        if (!result.success || !check.accepts(result.stdout)) {
+            return {
+                ...result,
+                success: false,
+                reason: `candidate ${check.label} failed: ${result.reason ?? 'unexpected command contract'}`,
+            };
+        }
+    }
+    return { success: true, exitCode: 0, stdout: '', stderr: '' };
+}
+async function validateRegistryCometPackage(version, npmCliPath) {
+    let validationDir;
+    try {
+        validationDir = await fs.mkdtemp(path.join(os.tmpdir(), 'comet-self-update-'));
+    }
+    catch (error) {
+        return {
+            success: false,
+            exitCode: null,
+            stdout: '',
+            stderr: '',
+            reason: `unable to create candidate prefix: ${error.message}`,
+        };
+    }
+    let result;
+    try {
+        const install = await runNpmCli(npmCliPath, [
+            'install',
+            '--prefix',
+            validationDir,
+            '--ignore-scripts',
+            '--no-save',
+            '--package-lock=false',
+            `${PACKAGE_NAME}@${version}`,
+            '--registry',
+            OFFICIAL_REGISTRY,
+        ], validationDir, CANDIDATE_INSTALL_LIMITS);
+        if (!install.success) {
+            result = {
+                ...install,
+                reason: `candidate package install failed: ${install.reason ?? 'unknown error'}`,
+            };
+        }
+        else {
+            const candidate = await readCometPackage(path.join(validationDir, 'node_modules', '@rpamis', 'comet'));
+            if (candidate.version !== version) {
+                result = {
+                    success: false,
+                    exitCode: null,
+                    stdout: '',
+                    stderr: '',
+                    reason: `candidate package version mismatch: expected ${version}, got ${candidate.version}`,
+                };
+            }
+            else {
+                result = await validateCometPackageCommands(candidate, version);
+            }
+        }
+    }
+    catch (error) {
+        result = {
+            success: false,
+            exitCode: null,
+            stdout: '',
+            stderr: '',
+            reason: `candidate package validation failed: ${error.message}`,
+        };
+    }
+    const cleanupError = await removeDirectoryWithRetry(validationDir);
+    if (!cleanupError)
+        return result;
+    return {
+        ...result,
+        success: false,
+        reason: result.reason
+            ? `${result.reason}; temporary cleanup failed: ${cleanupError.message}`
+            : `candidate validation temporary cleanup failed: ${cleanupError.message}`,
+    };
+}
+const PROJECT_INSTALL_METADATA = [
+    'package.json',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+];
+async function snapshotProjectInstallMetadata(metadataRoots) {
+    const filePaths = [
+        ...new Set(metadataRoots.flatMap((metadataRoot) => PROJECT_INSTALL_METADATA.map((relativePath) => path.join(metadataRoot, relativePath)))),
+    ];
+    return Promise.all(filePaths.map(async (filePath) => {
+        try {
+            return { filePath, content: await fs.readFile(filePath) };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { filePath, content: null };
+            throw error;
+        }
+    }));
+}
+async function restoreProjectInstallMetadata(snapshots) {
+    const failures = [];
+    for (const snapshot of snapshots) {
+        try {
+            if (snapshot.content === null) {
+                await fs.rm(snapshot.filePath, { force: true });
+            }
+            else {
+                await fs.writeFile(snapshot.filePath, snapshot.content);
+            }
+        }
+        catch (error) {
+            failures.push(`${path.basename(snapshot.filePath)}: ${error.message}`);
+        }
+    }
+    return failures.length > 0 ? failures.join('; ') : null;
+}
+async function installCometNpmVersion(npmCliPath, scope, projectPath, version) {
+    const cwd = scope === 'global' ? process.cwd() : projectPath;
+    return runNpmCli(npmCliPath, buildNpmUpdateArgs(scope, version), cwd, NPM_MUTATION_LIMITS);
+}
+async function updateCometNpmPackage(npmCliPath, scope, projectPath, targetVersion, installedPackage, log) {
+    const validation = await validateRegistryCometPackage(targetVersion, npmCliPath);
+    if (!validation.success) {
+        log(`  npm package: candidate validation failed: ${validation.reason}`);
+        return { success: false, exitCode: validation.exitCode, reason: validation.reason };
+    }
+    let metadata;
+    if (scope === 'project') {
+        try {
+            metadata = await snapshotProjectInstallMetadata(installedPackage.projectMetadataRoots ?? [projectPath]);
+        }
+        catch (error) {
+            return {
+                success: false,
+                exitCode: null,
+                reason: `unable to snapshot project package metadata: ${error.message}`,
+            };
+        }
+    }
+    const install = await installCometNpmVersion(npmCliPath, scope, projectPath, targetVersion);
+    let installReason = install.reason;
+    if (install.success) {
+        try {
+            const installedAfterUpdate = await readCometPackage(installedPackage.packageRoot);
+            if (installedAfterUpdate.version === targetVersion) {
+                return { success: true, exitCode: install.exitCode };
+            }
+            installReason = `installed package version mismatch: expected ${targetVersion}, got ${installedAfterUpdate.version}`;
+        }
+        catch (error) {
+            installReason = `unable to verify installed package: ${error.message}`;
+        }
+    }
+    const primaryReason = installReason ?? 'npm package installation failed';
+    log(`  npm package: update failed; restoring ${installedPackage.version}...`);
+    const rollback = await installCometNpmVersion(npmCliPath, scope, projectPath, installedPackage.version);
+    let rollbackReason = rollback.reason ?? null;
+    if (rollback.success) {
+        try {
+            const restored = await readCometPackage(installedPackage.packageRoot);
+            if (restored.version !== installedPackage.version) {
+                rollbackReason = `restored package version mismatch: expected ${installedPackage.version}, got ${restored.version}`;
+            }
+        }
+        catch (error) {
+            rollbackReason = `unable to verify restored package: ${error.message}`;
+        }
+    }
+    const metadataRestoreError = metadata ? await restoreProjectInstallMetadata(metadata) : null;
+    const details = [
+        primaryReason,
+        rollbackReason
+            ? `rollback to ${installedPackage.version} failed: ${rollbackReason}`
+            : `restored ${installedPackage.version}`,
+        metadataRestoreError ? `project metadata restore failed: ${metadataRestoreError}` : null,
+    ].filter((detail) => detail !== null);
+    return { success: false, exitCode: install.exitCode, reason: details.join('; ') };
+}
 async function promptCodegraphInstall(lang) {
     return select({
         message: t(lang, 'installCodegraph'),
@@ -158,116 +666,648 @@ async function promptCodegraphInstall(lang) {
         ],
     });
 }
-export async function updateCommand(targetPath, options = {}) {
-    const projectPath = path.resolve(targetPath);
-    const log = options.json ? () => undefined : console.log;
-    const lang = options.language ?? 'en';
-    log(`\n  ${t(lang, 'updateTitle')}`);
-    if (!options.json) {
-        await printVersionInfo(log);
+function currentProjectJson(result) {
+    return {
+        status: hasUpdateFailures(result) ? 'incomplete' : 'complete',
+        failures: collectCommandFailures(result),
+        npm: result.npm,
+        skills: {
+            totalCopied: result.skills.totalCopied,
+            totalFailed: result.skills.totalFailed,
+            cleanupFailed: result.skills.cleanupFailed,
+            installMode: result.skills.installMode,
+            targets: result.skills.targets,
+        },
+        rules: result.rules,
+        hooks: result.hooks,
+        projectInstructions: result.projectInstructions,
+        openspec: result.openspec,
+        codegraph: result.codegraph,
+    };
+}
+function hasComponentFailures(result) {
+    return (result.skills.totalFailed > 0 ||
+        result.skills.cleanupFailed > 0 ||
+        result.rules.totalFailed > 0 ||
+        result.hooks.totalFailed > 0);
+}
+function hasUpdateFailures(result) {
+    return (result.npm.status === 'failed' ||
+        result.openspec.status === 'failed' ||
+        result.codegraph === 'failed' ||
+        hasComponentFailures(result));
+}
+function collectComponentFailures(result) {
+    const skillFailures = result.skills.targets.flatMap((target) => {
+        const failed = target.failed + target.cleanupFailed;
+        if (failed === 0 || !target.reason)
+            return [];
+        return [
+            {
+                scope: target.scope,
+                platform: target.platform,
+                platformName: target.platformName,
+                component: 'Skill',
+                status: 'failed',
+                failed,
+                reason: target.reason,
+            },
+        ];
+    });
+    const ruleFailures = result.rules.targets.flatMap((target) => {
+        if (target.failed === 0 || !target.reason)
+            return [];
+        return [
+            {
+                scope: target.scope,
+                platform: target.platform,
+                platformName: target.platformName,
+                component: 'Rule',
+                status: 'failed',
+                failed: target.failed,
+                reason: target.reason,
+            },
+        ];
+    });
+    const hookFailures = result.hooks.targets.flatMap((target) => {
+        if (target.failed === 0 || !target.reason)
+            return [];
+        return [
+            {
+                scope: target.scope,
+                platform: target.platform,
+                platformName: target.platformName,
+                component: 'Hook',
+                status: 'failed',
+                failed: target.failed,
+                reason: target.reason,
+            },
+        ];
+    });
+    return [...skillFailures, ...ruleFailures, ...hookFailures];
+}
+function collectCommandFailures(result) {
+    const failures = [];
+    if (result.npm.status === 'failed') {
+        failures.push({
+            component: 'npm',
+            scope: result.npm.scope === 'skipped' ? undefined : result.npm.scope,
+            reason: result.npm.reason ?? 'npm package update failed',
+        });
     }
-    log('');
-    const packageScope = options.scope ?? (await detectCometPackageScope(projectPath));
+    if (result.openspec.status === 'failed') {
+        failures.push({
+            component: 'OpenSpec',
+            reason: result.openspec.reason ?? 'OpenSpec update failed',
+        });
+    }
+    failures.push(...collectComponentFailures(result));
+    if (result.codegraph === 'failed') {
+        failures.push({ component: 'CodeGraph', reason: 'CodeGraph installation failed' });
+    }
+    return failures;
+}
+function summarizeTargets(targets) {
+    return targets.map((target) => ({
+        scope: target.scope,
+        platform: target.platform.id,
+        platformName: target.platform.name,
+        language: target.language,
+    }));
+}
+function summarizeUpdatedTargets(targets) {
+    return targets.map((target) => ({
+        scope: target.scope,
+        platform: target.platform,
+        platformName: target.platformName,
+        language: target.language,
+    }));
+}
+async function upsertUpdatedProjectTargets(projectPath, result) {
+    const projectTargets = result.skills.targets.filter((target) => target.scope === 'project');
+    if (projectTargets.length === 0)
+        return;
+    await upsertProjectInstallation(projectPath, projectTargets.map((target) => ({
+        platform: target.platform,
+        language: target.language,
+    })), 'update');
+}
+async function updateSingleProject(startPath, options, log) {
+    const lang = options.language ?? 'en';
+    const includesProjectScope = options.targetScopes
+        ? options.targetScopes.includes('project')
+        : options.scope !== 'global';
+    const projectPath = includesProjectScope ? await discoverNativeProject(startPath) : startPath;
+    const projectConfigSnapshot = includesProjectScope
+        ? await readWorkflowProjectConfigSnapshot(projectPath, { allowPartialProject: true })
+        : null;
+    const projectConfigDocument = projectConfigSnapshot?.document ?? null;
+    const projectConfig = projectConfigDocument?.config ?? null;
+    const configuredWorkflows = projectConfig?.workflows ?? (projectConfig ? [projectConfig.default_workflow] : null);
+    const nativeProject = configuredWorkflows
+        ? configuredWorkflows.includes('native')
+        : projectConfigDocument?.native !== undefined;
+    const classicProject = configuredWorkflows ? configuredWorkflows.includes('classic') : true;
+    const projectWorkflowSelection = nativeProject && classicProject ? 'both' : nativeProject ? 'native' : 'classic';
+    const packageScope = options.scope && !options.targetScopes
+        ? options.scope
+        : await detectCometPackageScope(projectPath);
     let npmStatus = 'skipped';
-    if (!options.skipNpm) {
-        log(`  ${t(lang, 'updatingNpmPackage')} (${packageScope} scope)...`);
-        log(`    $ ${formatNpmUpdateCommand(packageScope)}`);
-        const npmUpdated = await updateCometNpmPackage(packageScope, projectPath, log, options.json === true);
-        if (npmUpdated) {
-            npmStatus = 'updated';
-            log(`  ${t(lang, 'npmPackageUpdated')} ${PACKAGE_NAME}`);
+    let npmExitCode = null;
+    let npmReason = options.npmSkipReason;
+    let npmCommand = null;
+    const skipPackageSelfUpdate = options.skipPackageSelfUpdate ?? options.skipNpm === true;
+    const skipRepeatedGlobalNpm = !skipPackageSelfUpdate && packageScope === 'global' && options.skipGlobalNpmUpdate === true;
+    if (skipRepeatedGlobalNpm) {
+        npmReason = 'global scope self-update already attempted';
+        log(`  ${t(lang, 'updatingNpmPackage')}: skipped (global scope already attempted)`);
+    }
+    else if (!skipPackageSelfUpdate) {
+        let npmCliPath = null;
+        let installedPackage = null;
+        try {
+            npmCliPath = await resolveNpmCliPath();
+            installedPackage = await readInstalledCometPackage(packageScope, projectPath, npmCliPath);
         }
-        else {
+        catch (error) {
+            npmStatus = 'failed';
+            npmReason = `unable to inspect installed Comet package: ${error.message}`;
+        }
+        const registryVersion = installedPackage ? await getLatestVersion() : null;
+        if (installedPackage && registryVersion === null) {
             npmStatus = 'failed';
-            log(`  ${t(lang, 'npmPackageFailed')}`);
+            npmReason = 'unable to resolve the latest Comet version from the npm registry';
+        }
+        else if (installedPackage && registryVersion && npmCliPath) {
+            const plan = resolveNpmSelfUpdatePlan(installedPackage.version, registryVersion);
+            if (plan.action === 'skip') {
+                npmStatus = 'skipped';
+                npmReason = plan.reason;
+                log(`  ${t(lang, 'updatingNpmPackage')}: skipped (${plan.reason})`);
+            }
+            else if (plan.action === 'fail') {
+                npmStatus = 'failed';
+                npmReason = plan.reason;
+            }
+            else {
+                npmCommand = formatNpmUpdateCommand(packageScope, plan.version);
+                log(`  ${t(lang, 'updatingNpmPackage')} (${packageScope} scope)...`);
+                log(`    $ ${npmCommand}`);
+                const npmResult = await updateCometNpmPackage(npmCliPath, packageScope, projectPath, plan.version, installedPackage, log);
+                npmExitCode = npmResult.exitCode;
+                npmReason = npmResult.reason;
+                if (npmResult.success) {
+                    npmStatus = 'updated';
+                    log(`  ${t(lang, 'npmPackageUpdated')} ${PACKAGE_NAME}@${plan.version}`);
+                }
+                else {
+                    npmStatus = 'failed';
+                }
+            }
+        }
+        if (npmStatus === 'failed') {
+            log(`  ${t(lang, options.failOnNpmFailure ? 'npmPackageFailedBlocking' : 'npmPackageFailed')}`);
+            if (options.failOnNpmFailure) {
+                throw createNpmUpdateFailure(packageScope, npmReason);
+            }
         }
     }
-    const installMode = await selectInstallMode(options, lang);
-    const targets = await detectInstalledCometTargets(projectPath, {
-        scopes: options.scope ? [options.scope] : undefined,
-    });
+    const targets = options.platform
+        ? await Promise.all((options.targetScopes ?? [options.scope ?? 'project']).map(async (scope) => {
+            const existing = options.language
+                ? null
+                : (await detectInstalledCometTargets(projectPath, {
+                    scopes: [scope],
+                    respectDetectionPaths: scope === 'project' && options.scope === undefined,
+                })).find((candidate) => candidate.platform.id === options.platform);
+            const fallbackLanguage = existing?.language ??
+                (scope === 'project'
+                    ? artifactLanguageToSkillLanguage(projectConfig?.native?.language ??
+                        projectConfig?.classic?.language ??
+                        projectConfigDocument?.native?.language ??
+                        projectConfigDocument?.classic?.language)
+                    : 'en');
+            const target = resolvePlatformTarget(options.platform, scope);
+            return {
+                scope,
+                platform: target.platform,
+                language: resolveTargetLanguage(options.language, fallbackLanguage),
+            };
+        }))
+        : await detectInstalledCometTargets(projectPath, {
+            scopes: options.targetScopes ?? (options.scope ? [options.scope] : undefined),
+            respectDetectionPaths: options.scope === undefined,
+        });
     if (targets.length === 0) {
-        if (options.json) {
-            console.log(JSON.stringify({
+        return {
+            projectPath,
+            npm: {
+                scope: skipPackageSelfUpdate ? 'skipped' : packageScope,
+                status: npmStatus,
+                command: npmCommand,
+                exitCode: npmExitCode,
+                reason: npmReason,
+            },
+            skills: { totalCopied: 0, totalFailed: 0, cleanupFailed: 0, targets: [] },
+            rules: { totalCopied: 0, totalFailed: 0, targets: [] },
+            hooks: { totalInstalled: 0, totalFailed: 0, targets: [] },
+            projectInstructions: { updated: 0 },
+            openspec: { status: 'skipped' },
+            codegraph: 'skipped',
+        };
+    }
+    const targetPlatforms = targets.map((target) => target.platform);
+    const openSpecTargets = [];
+    for (const target of targets) {
+        if (target.scope === 'project' && !classicProject)
+            continue;
+        const baseDir = getBaseDir(target.scope, projectPath);
+        if (await hasSkills(baseDir, target.platform, 'openspec', targetPlatforms, target.scope, {
+            includeGlobalFallback: false,
+        })) {
+            openSpecTargets.push(target);
+        }
+    }
+    const hasClassicCompatibleTarget = targets.some((target) => target.scope === 'global' || classicProject);
+    const selectedInstallMode = hasClassicCompatibleTarget
+        ? await selectInstallMode(options, lang)
+        : 'copy';
+    const installModeFor = (target) => nativeProject && target.scope === 'project' ? 'copy' : selectedInstallMode;
+    const reportedInstallMode = targets.every((target) => nativeProject && target.scope === 'project')
+        ? 'copy'
+        : selectedInstallMode;
+    const rawClassic = projectConfigDocument?.value.classic;
+    const explicitClassicArtifactLayout = rawClassic !== null &&
+        typeof rawClassic === 'object' &&
+        !Array.isArray(rawClassic) &&
+        (rawClassic.artifact_layout === 'legacy' ||
+            rawClassic.artifact_layout === 'docs')
+        ? rawClassic.artifact_layout
+        : null;
+    const classicArtifactLayout = explicitClassicArtifactLayout ??
+        ((await fileExists(path.join(projectPath, 'openspec'))) &&
+            !(await fileExists(path.join(projectPath, 'docs', 'openspec')))
+            ? 'legacy'
+            : 'docs');
+    const refreshClassicArtifactRoot = includesProjectScope && classicProject && targets.some((target) => target.scope === 'project');
+    let classicLayoutInitializationPermit;
+    if (refreshClassicArtifactRoot) {
+        try {
+            let initialization = await assertClassicLayoutInitializationSafe(projectPath, classicArtifactLayout, undefined, projectConfigSnapshot?.identity);
+            initialization = await beginClassicLayoutInitialization(projectPath, initialization);
+            classicLayoutInitializationPermit = initialization.initializationPermit;
+        }
+        catch (error) {
+            const reason = `Classic layout preflight failed: ${error.message}`;
+            return {
+                projectPath,
                 npm: {
-                    scope: options.skipNpm ? 'skipped' : packageScope,
+                    scope: skipPackageSelfUpdate ? 'skipped' : packageScope,
                     status: npmStatus,
-                    command: options.skipNpm ? null : formatNpmUpdateCommand(packageScope),
+                    command: npmCommand,
+                    exitCode: npmExitCode,
+                    reason: npmReason,
                 },
-                skills: { totalCopied: 0, targets: [] },
-                rules: { totalCopied: 0 },
-                hooks: { totalInstalled: 0 },
+                skills: {
+                    totalCopied: 0,
+                    totalFailed: 0,
+                    cleanupFailed: 0,
+                    installMode: reportedInstallMode,
+                    targets: targets.map((target) => {
+                        const languageId = resolveTargetLanguage(options.language, target.language);
+                        const languageSkillsDir = languageToSkillsDir(languageId);
+                        return {
+                            scope: target.scope,
+                            platform: target.platform.id,
+                            platformName: target.platform.name,
+                            language: languageId,
+                            source: languageSkillsDir,
+                            copied: 0,
+                            skipped: 0,
+                            failed: 0,
+                            reason: 'skipped because Classic layout preflight failed',
+                            cleanupFailed: 0,
+                            command: formatSkillUpdateCommand(target.scope, target.platform, languageSkillsDir, installModeFor(target)),
+                        };
+                    }),
+                },
+                rules: { totalCopied: 0, totalFailed: 0, targets: [] },
+                hooks: { totalInstalled: 0, totalFailed: 0, targets: [] },
+                projectInstructions: { updated: 0 },
+                openspec: { status: 'failed', reason },
                 codegraph: 'skipped',
-            }, null, 2));
-            return;
+            };
         }
-        log(`\n  ${t(lang, 'noInstallsFound')}\n`);
-        return;
     }
+    const assertClassicProjectMutationAllowed = classicLayoutInitializationPermit
+        ? async () => {
+            await assertClassicLayoutInitializationSafe(projectPath, classicArtifactLayout, classicLayoutInitializationPermit);
+        }
+        : undefined;
     log(`\n  ${t(lang, 'updatingSkillsOnTargets')} ${targets.length} target(s):`);
     for (const target of targets) {
         const language = options.language ?? target.language;
         const scopeLabel = target.scope === 'global' ? 'global' : `project (${projectPath})`;
-        const languageSkillsDir = languageToSkillsDir(options.language, target.language);
+        const languageId = resolveTargetLanguage(options.language, target.language);
+        const languageSkillsDir = languageToSkillsDir(languageId);
+        const targetInstallMode = installModeFor(target);
         log(`    - ${target.platform.name} (${scopeLabel}, ${language})`);
-        log(`      $ ${formatSkillUpdateCommand(target.scope, target.platform, languageSkillsDir, installMode)}`);
+        log(`      $ ${formatSkillUpdateCommand(target.scope, target.platform, languageSkillsDir, targetInstallMode)}`);
     }
-    log(`\n  ${t(lang, 'copyingSkillsFiles')} ${(await getManifestSkills()).length} skill files...\n`);
+    const targetWorkflowSelections = targets.map((target) => target.scope === 'global' ? 'classic' : projectWorkflowSelection);
+    const updateSkillPaths = new Set((await Promise.all([...new Set(targetWorkflowSelections)].map((selection) => getManifestSkills(selection)))).flat());
+    log(`\n  ${t(lang, 'copyingSkillsFiles')} ${updateSkillPaths.size} skill files...\n`);
     let totalCopied = 0;
+    let totalFailed = 0;
+    let totalCleanupFailed = 0;
     let totalRulesCopied = 0;
+    let totalRulesFailed = 0;
     let totalHooksInstalled = 0;
+    let totalHooksFailed = 0;
+    let projectInstructionsUpdated = 0;
     const targetResults = [];
+    const ruleTargetResults = [];
+    const hookTargetResults = [];
     for (const target of targets) {
         const baseDir = getBaseDir(target.scope, projectPath);
-        const languageSkillsDir = languageToSkillsDir(options.language, target.language);
-        const { copied, skipped } = await copyCometSkillsForPlatform(baseDir, target.platform, true, languageSkillsDir, target.scope, installMode);
+        const languageId = resolveTargetLanguage(options.language, target.language);
+        const languageSkillsDir = languageToSkillsDir(languageId);
+        const targetInstallMode = installModeFor(target);
+        const nativeProjectTarget = nativeProject && target.scope === 'project';
+        const targetWorkflowSelection = target.scope === 'global' ? 'classic' : projectWorkflowSelection;
+        if (target.scope === 'project') {
+            await assertClassicProjectMutationAllowed?.();
+        }
+        if (nativeProjectTarget) {
+            await prepareManagedSkillCopyTarget(baseDir, target.platform, target.scope, targetWorkflowSelection);
+        }
+        const { copied, skipped, failed } = await copyCometSkillsForPlatform(baseDir, target.platform, true, languageSkillsDir, target.scope, targetInstallMode, targetWorkflowSelection);
+        const cleanupResult = failed === 0
+            ? await removeLegacyCometSkillsForPlatform(baseDir, target.platform, target.scope)
+            : { removed: 0, failed: 0 };
+        totalCleanupFailed += cleanupResult.failed;
         totalCopied += copied;
+        totalFailed += failed;
         targetResults.push({
             scope: target.scope,
             platform: target.platform.id,
             platformName: target.platform.name,
-            language: options.language ?? target.language,
+            language: languageId,
             source: languageSkillsDir,
             copied,
             skipped,
-            command: formatSkillUpdateCommand(target.scope, target.platform, languageSkillsDir, installMode),
+            failed,
+            reason: failed > 0
+                ? `${failed} Skill file(s) failed to install`
+                : cleanupResult.failed > 0
+                    ? `legacy Skill cleanup failed (${cleanupResult.failed})`
+                    : undefined,
+            cleanupFailed: cleanupResult.failed,
+            command: formatSkillUpdateCommand(target.scope, target.platform, languageSkillsDir, targetInstallMode),
         });
         log(`  ${target.platform.name} (${target.scope}, ${languageSkillsDir}): ${copied} ${t(lang, 'skillsCopiedSkipped')} ${skipped} skipped`);
+        if (cleanupResult.failed > 0) {
+            log(`  ${target.platform.name} (${target.scope}): legacy Skill cleanup failed; update incomplete`);
+        }
+        if (failed > 0) {
+            const dependencyReason = 'skipped because Skill installation failed';
+            ruleTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                copied: 0,
+                skipped: 0,
+                failed: 0,
+                status: 'skipped',
+                reason: dependencyReason,
+            });
+            hookTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                failed: 0,
+                status: 'skipped',
+                reason: dependencyReason,
+            });
+            continue;
+        }
         try {
-            const { copied: ruleCopied } = await copyCometRulesForPlatform(baseDir, target.platform, true, target.scope);
-            totalRulesCopied += ruleCopied;
-            if (ruleCopied > 0) {
-                log(`  Comet rules -> ${target.platform.name}: ${ruleCopied} ${t(lang, 'rulesUpdated')}`);
+            const ruleResult = await copyCometRulesForPlatform(baseDir, target.platform, true, languageId, target.scope, target.scope === 'global' ? 'classic' : projectWorkflowSelection);
+            totalRulesCopied += ruleResult.copied;
+            totalRulesFailed += ruleResult.failed;
+            const ruleStatus = ruleResult.failed > 0 ? 'failed' : ruleResult.copied > 0 ? 'copied' : 'skipped';
+            const ruleReason = ruleResult.failed > 0
+                ? `${ruleResult.failed} Rule file(s) failed to install`
+                : !target.platform.rulesDir || !target.platform.rulesFormat
+                    ? 'platform does not support rules'
+                    : undefined;
+            ruleTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                ...ruleResult,
+                status: ruleStatus,
+                reason: ruleReason,
+            });
+            if (ruleResult.copied > 0) {
+                log(`  Comet rules -> ${target.platform.name}: ${ruleResult.copied} ${t(lang, 'rulesUpdated')}`);
+            }
+            if (ruleResult.failed > 0) {
+                log(`  Comet rules -> ${target.platform.name}: ${t(lang, 'rulesFailed')} (${ruleReason})`);
             }
         }
         catch (err) {
-            log(`  Comet rules -> ${target.platform.name}: ${t(lang, 'rulesFailed')} (${err.message})`);
+            totalRulesFailed++;
+            const reason = err.message;
+            ruleTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                copied: 0,
+                skipped: 0,
+                failed: 1,
+                status: 'failed',
+                reason,
+            });
+            log(`  Comet rules -> ${target.platform.name}: ${t(lang, 'rulesFailed')} (${reason})`);
         }
-        if (target.platform.supportsHooks) {
-            try {
-                const { installed, reason } = await installCometHooksForPlatform(baseDir, target.platform, target.scope);
-                if (installed) {
-                    totalHooksInstalled++;
-                    log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksUpdated')}`);
+        try {
+            const { status, reason, cleanupFailed = 0, } = await installCometHooksForPlatform(baseDir, target.platform, target.scope, target.scope === 'global' ? 'classic' : projectWorkflowSelection);
+            const hookFailed = status === 'failed' ? 1 : cleanupFailed;
+            totalHooksFailed += hookFailed;
+            hookTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                failed: hookFailed,
+                status,
+                reason,
+            });
+            if (status === 'installed') {
+                totalHooksInstalled++;
+                log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksUpdated')}`);
+                if (cleanupFailed > 0) {
+                    log(`  Comet hooks -> ${target.platform.name}: ${reason}`);
                 }
-                else if (reason) {
-                    log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksSkipped')} (${reason})`);
+            }
+            else if (status === 'failed') {
+                log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksFailed')} (${reason})`);
+            }
+            else if (reason && target.platform.supportsHooks) {
+                log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksSkipped')} (${reason})`);
+            }
+        }
+        catch (err) {
+            totalHooksFailed++;
+            const reason = err.message;
+            hookTargetResults.push({
+                scope: target.scope,
+                platform: target.platform.id,
+                platformName: target.platform.name,
+                failed: 1,
+                status: 'failed',
+                reason,
+            });
+            log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksFailed')} (${reason})`);
+        }
+    }
+    const projectRouterInstalled = hookTargetResults.some((target) => target.scope === 'project' && target.status === 'installed');
+    const projectHookFailed = hookTargetResults.some((target) => target.scope === 'project' && target.status === 'failed');
+    if (includesProjectScope &&
+        projectRouterInstalled &&
+        !projectHookFailed &&
+        (projectWorkflowSelection === 'classic' || projectWorkflowSelection === 'both')) {
+        if (await migrateLegacyClassicSelection(projectPath)) {
+            log('  Comet current selection -> migrated Classic v1 to shared v2');
+        }
+    }
+    let openSpecStatus = 'skipped';
+    let openSpecReason;
+    let projectMutationBlocked = false;
+    let projectConfigCommitBlocked = false;
+    for (const scope of ['project', 'global']) {
+        const scopeTargets = openSpecTargets.filter((target) => target.scope === scope);
+        const requiresArtifactOnlyRefresh = scope === 'project' && refreshClassicArtifactRoot && scopeTargets.length === 0;
+        if (scopeTargets.length === 0 && !requiresArtifactOnlyRefresh)
+            continue;
+        const toolIds = [...new Set(scopeTargets.map((target) => target.platform.openspecToolId))];
+        const mirrorOpenCodePlatformIds = scopeTargets
+            .map((target) => target.platform.id)
+            .filter((id) => id === 'zcode' || id === 'mimocode');
+        const artifactLayout = scope === 'project' ? classicArtifactLayout : 'legacy';
+        try {
+            if (scope === 'project') {
+                await assertClassicProjectMutationAllowed?.();
+            }
+            const status = await installOpenSpec(projectPath, toolIds, scope, !skipPackageSelfUpdate, mirrorOpenCodePlatformIds, artifactLayout, scope === 'project' ? assertClassicProjectMutationAllowed : undefined);
+            if (status === 'failed') {
+                openSpecStatus = 'failed';
+                openSpecReason = `OpenSpec ${scope} asset update failed`;
+                if (scope === 'project' && refreshClassicArtifactRoot) {
+                    projectConfigCommitBlocked = true;
+                }
+            }
+            else if (status === 'skipped') {
+                openSpecStatus = 'failed';
+                openSpecReason = `OpenSpec ${scope} asset update skipped because a compatible OpenSpec CLI is unavailable`;
+                if (scope === 'project' && refreshClassicArtifactRoot) {
+                    projectConfigCommitBlocked = true;
+                }
+            }
+            else if (status === 'installed' && openSpecStatus !== 'failed') {
+                if (scope === 'project') {
+                    try {
+                        await assertClassicProjectMutationAllowed?.();
+                        await assertClassicOpenSpecRootHealthy(projectPath, classicLayoutPaths(projectPath, classicArtifactLayout));
+                        await assertClassicProjectMutationAllowed?.();
+                        if (classicLayoutInitializationPermit) {
+                            await checkpointClassicLayoutInitialization(projectPath, classicLayoutInitializationPermit);
+                        }
+                    }
+                    catch (error) {
+                        projectConfigCommitBlocked = true;
+                        throw error;
+                    }
                 }
+                openSpecStatus = 'installed';
+            }
+            log(`  OpenSpec (${scope}): ${status}`);
+        }
+        catch (error) {
+            openSpecStatus = 'failed';
+            openSpecReason = `OpenSpec ${scope} asset update failed: ${error.message}`;
+            if (scope === 'project' && isProjectMutationGuardError(error)) {
+                projectMutationBlocked = true;
             }
-            catch (err) {
-                log(`  Comet hooks -> ${target.platform.name}: ${t(lang, 'hooksFailed')} (${err.message})`);
+            if (scope === 'project' && refreshClassicArtifactRoot) {
+                projectConfigCommitBlocked = true;
             }
+            log(`  ${openSpecReason}`);
         }
     }
-    const hasProjectTargets = targets.some((target) => target.scope === 'project');
-    if (hasProjectTargets) {
-        await mergeProjectConfig(projectPath);
+    const projectTarget = targets.find((target) => target.scope === 'project');
+    if (projectTarget && !projectMutationBlocked) {
+        try {
+            await assertClassicProjectMutationAllowed?.();
+            const projectLanguageId = resolveTargetLanguage(options.language, projectTarget.language);
+            const projectInstructionResult = await installCometProjectInstructions(projectPath, projectLanguageId);
+            projectInstructionsUpdated = projectInstructionResult.changed;
+            if (projectInstructionsUpdated > 0) {
+                log(`  Comet project instructions -> ${projectInstructionsUpdated} file(s) updated`);
+            }
+        }
+        catch (error) {
+            openSpecStatus = 'failed';
+            openSpecReason = `Classic layout update failed before project instruction mutation: ${error.message}`;
+            projectMutationBlocked = true;
+        }
+    }
+    for (const scope of ['project', 'global']) {
+        const scopeTargets = targets.filter((candidate) => candidate.scope === scope);
+        if (scopeTargets.length === 0)
+            continue;
+        if (scope === 'project' && (projectMutationBlocked || projectConfigCommitBlocked))
+            continue;
+        // An explicit --language always wins. Otherwise only force the persisted language when
+        // every platform installed at this scope agrees — if two platforms disagree (e.g. one
+        // installed with English skills, another with Chinese) and the user didn't say which one
+        // they mean, guessing from array order would silently override whatever language they
+        // (or a prior install) already configured. Pass null in that case so mergeProjectConfig
+        // preserves the existing config's language instead of guessing.
+        const agreedLanguage = scopeTargets.every((t) => t.language === scopeTargets[0].language)
+            ? scopeTargets[0].language
+            : undefined;
+        const languageId = options.language
+            ? resolveTargetLanguage(options.language, scopeTargets[0].language)
+            : agreedLanguage;
+        const configRoot = getBaseDir(scope, projectPath);
+        if (scope === 'project') {
+            try {
+                await assertClassicProjectMutationAllowed?.();
+            }
+            catch (error) {
+                openSpecStatus = 'failed';
+                openSpecReason = `Classic layout update failed before config mutation: ${error.message}`;
+                projectMutationBlocked = true;
+                continue;
+            }
+        }
+        await mergeProjectConfig(configRoot, languageId ? languageToArtifactLanguage(languageId) : null, scope === 'project' ? classicArtifactLayout : 'docs', scope === 'project', scope === 'project' && classicProject);
+        if (scope === 'project' && classicLayoutInitializationPermit) {
+            await completeClassicLayoutInitialization(projectPath, classicLayoutInitializationPermit);
+        }
         log(`  ${t(lang, 'configMerged')}`);
     }
     let codegraphStatus = 'skipped';
     const primaryScope = targets[0]?.scope ?? 'project';
     const codegraphAlreadyIndexed = hasCodegraphProjectIndex(projectPath);
-    if (options.json) {
+    if (projectMutationBlocked && primaryScope === 'project') {
+        codegraphStatus = 'skipped';
+    }
+    else if (options.json) {
+        codegraphStatus = 'skipped';
+    }
+    else if (nativeProject) {
         codegraphStatus = 'skipped';
     }
     else if (codegraphAlreadyIndexed) {
@@ -284,33 +1324,297 @@ export async function updateCommand(targetPath, options = {}) {
             log(`\n  CodeGraph: ${t(lang, 'cgSkippedByUser')}`);
         }
     }
+    return {
+        projectPath,
+        npm: {
+            scope: skipPackageSelfUpdate ? 'skipped' : packageScope,
+            status: npmStatus,
+            command: npmCommand,
+            exitCode: npmExitCode,
+            reason: npmReason,
+        },
+        skills: {
+            totalCopied,
+            totalFailed,
+            cleanupFailed: totalCleanupFailed,
+            installMode: reportedInstallMode,
+            targets: targetResults,
+        },
+        rules: {
+            totalCopied: totalRulesCopied,
+            totalFailed: totalRulesFailed,
+            targets: ruleTargetResults,
+        },
+        hooks: {
+            totalInstalled: totalHooksInstalled,
+            totalFailed: totalHooksFailed,
+            targets: hookTargetResults,
+        },
+        projectInstructions: { updated: projectInstructionsUpdated },
+        openspec: {
+            status: openSpecStatus,
+            ...(openSpecReason ? { reason: openSpecReason } : {}),
+        },
+        codegraph: codegraphStatus,
+    };
+}
+function logSingleProjectSummary(result, options, log) {
+    const lang = options.language ?? 'en';
+    const languages = [...new Set(result.skills.targets.map((target) => target.language))].join(', ');
+    const scopes = [...new Set(result.skills.targets.map((target) => target.scope))].join(', ');
+    log(`\n  ${t(lang, 'summary')}`);
+    log(`    ${t(lang, 'summaryNpm')} ${result.npm.status}${options.skipNpm ? '' : ` (${result.npm.scope})`}`);
+    log(`    ${t(lang, 'summarySkills')} ${result.skills.targets.length} target(s), ${result.skills.totalCopied} files updated`);
+    if (result.skills.cleanupFailed > 0) {
+        log(`    Skill cleanup failures: ${result.skills.cleanupFailed} (update incomplete)`);
+    }
+    if (result.skills.totalFailed > 0) {
+        log(`    Skill failures: ${result.skills.totalFailed} (update incomplete)`);
+    }
+    if (result.rules.totalFailed > 0) {
+        log(`    Rule failures: ${result.rules.totalFailed} (update incomplete)`);
+    }
+    if (result.hooks.totalFailed > 0) {
+        log(`    Hook failures: ${result.hooks.totalFailed} (update incomplete)`);
+    }
+    for (const failure of collectComponentFailures(result)) {
+        log(`    ${failure.platformName} (${failure.scope}) ${failure.component}: ${failure.status} (${failure.failed}) - ${failure.reason}`);
+    }
+    log(`    ${t(lang, 'summaryCodegraph')} ${result.codegraph}`);
+    log(`    ${t(lang, 'summaryScope')} ${scopes}`);
+    log(`    ${t(lang, 'summaryLanguage')} ${languages}`);
+    if (hasUpdateFailures(result)) {
+        const reasons = collectCommandFailures(result)
+            .map((failure) => failure.reason)
+            .join('; ');
+        log(`\n  Update incomplete. ${reasons}.\n`);
+    }
+    else {
+        log(`\n  ${t(lang, 'updateComplete')}\n`);
+    }
+}
+async function updateAllIndexedProjects(registryProjects, options, log) {
+    const lang = options.language ?? 'en';
+    const results = [];
+    const runnableProjects = [];
+    let staleRemoved = 0;
+    for (const project of registryProjects) {
+        const projectPath = project.path;
+        try {
+            const targets = await detectInstalledCometTargets(projectPath, { scopes: ['project'] });
+            if (targets.length === 0) {
+                if (await removeProjectInstallation(projectPath))
+                    staleRemoved++;
+                results.push({
+                    projectPath,
+                    status: 'skipped',
+                    reason: 'no project-scope Comet install detected',
+                    targets: [],
+                });
+                continue;
+            }
+            runnableProjects.push({ projectPath, targets });
+        }
+        catch (error) {
+            results.push({
+                projectPath,
+                status: 'failed',
+                reason: `unable to inspect project: ${error.message}`,
+                targets: [],
+            });
+        }
+    }
+    if (!options.json) {
+        log(`  Comet will update ${runnableProjects.length} indexed project(s):`);
+        for (const project of runnableProjects) {
+            log(`    - ${project.projectPath}`);
+            log(`      ${project.targets.map((target) => target.platform.name).join(', ')}`);
+        }
+        const confirmed = await select({
+            message: t(lang, 'updateAllProjectsPrompt'),
+            choices: [
+                { name: t(lang, 'updateAllProjectsYes'), value: true },
+                { name: t(lang, 'updateAllProjectsNo'), value: false },
+            ],
+        });
+        if (!confirmed) {
+            log(`\n  ${t(lang, 'cancelled')}\n`);
+            return { status: 'complete' };
+        }
+    }
+    const runOptions = {
+        ...options,
+        scope: undefined,
+        targetScopes: ['project'],
+        currentProject: true,
+        allProjects: false,
+        failOnNpmFailure: true,
+    };
+    if (!options.json && !runOptions.installMode) {
+        runOptions.installMode = await selectInstallMode(options, lang);
+    }
+    let globalNpmAttempted = false;
+    for (let index = 0; index < runnableProjects.length; index++) {
+        const project = runnableProjects[index];
+        const { projectPath, targets } = project;
+        try {
+            const result = await updateSingleProject(projectPath, { ...runOptions, skipGlobalNpmUpdate: globalNpmAttempted }, log);
+            if (result.npm.scope === 'global' && result.npm.status !== 'skipped') {
+                globalNpmAttempted = true;
+            }
+            if (result.skills.targets.length === 0) {
+                if (await removeProjectInstallation(projectPath))
+                    staleRemoved++;
+                results.push({
+                    projectPath,
+                    status: 'skipped',
+                    reason: 'no project-scope Comet install detected',
+                    targets: [],
+                });
+                continue;
+            }
+            if (hasUpdateFailures(result)) {
+                results.push({
+                    projectPath,
+                    status: 'failed',
+                    reason: collectCommandFailures(result)
+                        .map((failure) => failure.reason)
+                        .join('; '),
+                    targets: summarizeUpdatedTargets(result.skills.targets),
+                    failures: collectCommandFailures(result),
+                });
+                continue;
+            }
+            await upsertUpdatedProjectTargets(projectPath, result);
+            results.push({
+                projectPath,
+                status: 'updated',
+                targets: summarizeUpdatedTargets(result.skills.targets),
+                summary: {
+                    skillsCopied: result.skills.totalCopied,
+                    rulesCopied: result.rules.totalCopied,
+                    hooksInstalled: result.hooks.totalInstalled,
+                    projectInstructionsUpdated: result.projectInstructions.updated,
+                },
+            });
+        }
+        catch (error) {
+            const npmFailure = isGlobalNpmUpdateFailure(error);
+            results.push({
+                projectPath,
+                status: 'failed',
+                reason: error.message,
+                targets: summarizeTargets(targets),
+                failures: npmFailure
+                    ? [
+                        {
+                            component: 'npm',
+                            scope: 'global',
+                            reason: error.message,
+                        },
+                    ]
+                    : undefined,
+            });
+            if (npmFailure) {
+                for (const remaining of runnableProjects.slice(index + 1)) {
+                    results.push({
+                        projectPath: remaining.projectPath,
+                        status: 'not_attempted',
+                        reason: 'not attempted because the global npm package update failed',
+                        targets: summarizeTargets(remaining.targets),
+                    });
+                }
+                break;
+            }
+        }
+    }
     if (options.json) {
         console.log(JSON.stringify({
-            npm: {
-                scope: options.skipNpm ? 'skipped' : packageScope,
-                status: npmStatus,
-                command: options.skipNpm ? null : formatNpmUpdateCommand(packageScope),
-            },
-            skills: {
-                totalCopied,
-                installMode,
-                targets: targetResults,
+            mode: 'all-projects',
+            status: results.some((result) => result.status === 'failed' || result.status === 'not_attempted')
+                ? 'incomplete'
+                : 'complete',
+            registry: {
+                projectsFound: registryProjects.length,
+                staleRemoved,
             },
-            rules: { totalCopied: totalRulesCopied },
-            hooks: { totalInstalled: totalHooksInstalled },
-            codegraph: codegraphStatus,
+            projects: results,
         }, null, 2));
-        return;
+        return {
+            status: results.some((result) => result.status === 'failed' || result.status === 'not_attempted')
+                ? 'incomplete'
+                : 'complete',
+        };
     }
-    const languages = [...new Set(targetResults.map((target) => target.language))].join(', ');
-    const scopes = [...new Set(targetResults.map((target) => target.scope))].join(', ');
-    log(`\n  ${t(lang, 'summary')}`);
-    log(`    ${t(lang, 'summaryNpm')} ${npmStatus}${options.skipNpm ? '' : ` (${packageScope})`}`);
-    log(`    ${t(lang, 'summarySkills')} ${targets.length} target(s), ${totalCopied} files updated`);
-    log(`    ${t(lang, 'summaryCodegraph')} ${codegraphStatus}`);
-    log(`    ${t(lang, 'summaryScope')} ${scopes}`);
-    log(`    ${t(lang, 'summaryLanguage')} ${languages}`);
-    log(`\n  ${t(lang, 'updateComplete')}\n`);
+    log(`\n  Updated ${results.filter((result) => result.status === 'updated').length} indexed project(s).`);
+    for (const result of results.filter((candidate) => candidate.status !== 'updated')) {
+        log(`    ${result.projectPath}: ${result.status} (${result.reason ?? 'no reason provided'})`);
+    }
+    return {
+        status: results.some((result) => result.status === 'failed' || result.status === 'not_attempted')
+            ? 'incomplete'
+            : 'complete',
+    };
+}
+function resolveSelfUpdateOptions(options, refreshesOnlyCurrentProject) {
+    if (options.selfUpdate && (options.skipSelfUpdate || options.skipNpm)) {
+        throw new Error('--self-update cannot be combined with --skip-self-update or --skip-npm');
+    }
+    if (options.skipSelfUpdate || options.skipNpm) {
+        return {
+            ...options,
+            skipPackageSelfUpdate: true,
+            npmSkipReason: options.skipSelfUpdate
+                ? 'self-update disabled by --skip-self-update'
+                : 'self-update disabled by --skip-npm',
+        };
+    }
+    if (refreshesOnlyCurrentProject && !options.selfUpdate) {
+        return {
+            ...options,
+            skipPackageSelfUpdate: true,
+            npmSkipReason: 'self-update disabled for current-project updates; pass --self-update to opt in',
+        };
+    }
+    return { ...options, skipPackageSelfUpdate: false };
+}
+export async function updateCommand(targetPath, options = {}) {
+    const projectPath = path.resolve(targetPath);
+    const log = options.json ? () => undefined : console.log;
+    const lang = options.language ?? 'en';
+    assertProjectScopeOptions(options);
+    if (options.platform && options.allProjects) {
+        throw new Error('--platform cannot be combined with --all-projects');
+    }
+    const registryProjects = await listProjectRegistryEntries({ strict: true });
+    log(`\n  ${t(lang, 'updateTitle')}`);
+    if (!options.json) {
+        await printVersionInfo(log);
+    }
+    log('');
+    const scopeMode = await resolveProjectScopeMode('update', options, registryProjects.length);
+    options = resolveSelfUpdateOptions(options, options.currentProject === true || scopeMode === 'current-project');
+    if (scopeMode === 'all-projects') {
+        return updateAllIndexedProjects(registryProjects, options, log);
+    }
+    const result = await updateSingleProject(projectPath, options, log);
+    if (result.skills.targets.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify(currentProjectJson(result), null, 2));
+            return { status: hasUpdateFailures(result) ? 'incomplete' : 'complete' };
+        }
+        log(`\n  ${t(lang, 'noInstallsFound')}\n`);
+        return { status: hasUpdateFailures(result) ? 'incomplete' : 'complete' };
+    }
+    if (!hasUpdateFailures(result)) {
+        await upsertUpdatedProjectTargets(result.projectPath, result);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(currentProjectJson(result), null, 2));
+        return { status: hasUpdateFailures(result) ? 'incomplete' : 'complete' };
+    }
+    logSingleProjectSummary(result, options, log);
+    return { status: hasUpdateFailures(result) ? 'incomplete' : 'complete' };
 }
-export { buildNpmUpdateArgs, detectCometPackageScope, detectInstalledCometLanguage, detectInstalledCometTargets, formatNpmUpdateCommand, formatSkillUpdateCommand, };
+export { buildNpmUpdateArgs, detectCometPackageScope, detectInstalledCometLanguage, detectInstalledCometTargets, formatNpmUpdateCommand, formatSkillUpdateCommand, resolveNpmSelfUpdatePlan, };
 //# sourceMappingURL=update.js.map