triad-plus 1.10.0 → 1.12.0

package/bin/triad-plus.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
-import { access, cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { access, cp, mkdir, readFile, rm, stat, writeFile, lstat, readdir } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, relative, sep } from 'node:path';
 import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { getAdapter, listAdapters, roleDefinitions, sharedSkillNames } from '../adapters/registry.mjs';
@@ -20,8 +21,21 @@ import {
   formatDoctorSection,
   formatSetupSummary
 } from '../runtime/lib/terminal.mjs';
+import {
+  buildInstallationManifest,
+  collectManagedAssetRecords,
+  installationManifestFingerprint,
+  installationManifestPath,
+  loadInstallationManifest,
+  manifestIsUninstalled,
+  manifestScopeStatus,
+  sha256Text,
+  sha256File,
+  writeInstallationManifest
+} from '../runtime/lib/installation-manifest.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageVersion = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
 
 function usage(exitCode = 0) {
   const stream = exitCode === 0 ? process.stdout : process.stderr;
@@ -29,15 +43,18 @@ function usage(exitCode = 0) {
 
 Usage:
   npx triad-plus
+  npx triad-plus --version
   npx triad-plus init --host <adapter-id> --control <path> [--global] [--team-config <path>] [--allow-product-repo]
   npx triad-plus doctor --host <adapter-id> --control <path> [--global] [--hook-config <path>]
+  npx triad-plus version --control <path>
   npx triad-plus upgrade --host <adapter-id> --control <path> [--global] [--apply]
+  npx triad-plus uninstall --host <adapter-id> --control <path> [--global] [--apply]
   npx triad-plus import-bmad-story --source <story.md> --output <card.md> [--target-repository <id>] [--provenance <record.json>] [--required-gate <id>] [--depends-on <card-id>]
 
 Adapters: ${listAdapters().map((adapter) => adapter.id).join(', ')}
 
 The control path is a project-control workspace, not a product repository.
-Installation refuses every asset overwrite. Upgrade is a dry run unless --apply is supplied.
+Installation refuses conflicting asset overwrites; identical global assets may be reused. Upgrade is a dry run unless --apply is supplied.
 `);
   process.exit(exitCode);
 }
@@ -77,6 +94,16 @@ async function requireDirectory(target) {
   if (!(await stat(target)).isDirectory()) throw new Error(`Control path is not a directory: ${target}`);
 }
 
+async function requireExistingDirectory(target) {
+  let info;
+  try { info = await stat(target); }
+  catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`Control workspace does not exist: ${target}`);
+    throw error;
+  }
+  if (!info.isDirectory()) throw new Error(`Control path is not a directory: ${target}`);
+}
+
 function codexHome() {
   return process.env.CODEX_HOME || join(homedir(), '.codex');
 }
@@ -122,6 +149,101 @@ async function installAssets(assets, root, installContext) {
   for (const asset of assets) await copyAsset(asset, root, installContext);
 }
 
+function assetDestinations(assets, root, installContext) {
+  return assets.map((asset) => resolveDestination(asset.destination, root, installContext));
+}
+
+async function sourceFiles(source) {
+  const info = await lstat(source);
+  if (info.isFile()) return [source];
+  if (!info.isDirectory()) throw new Error(`Managed asset source is not a regular file or directory: ${source}`);
+  const files = [];
+  for (const name of (await readdir(source)).sort()) files.push(...await sourceFiles(join(source, name)));
+  return files;
+}
+
+/** Expand registry assets to exact source/destination file pairs, never to a host directory. */
+async function materializedAssetPairs(assets, root, installContext) {
+  const pairs = [];
+  for (const asset of assets) {
+    const destination = resolveDestination(asset.destination, root, installContext);
+    if (asset.source === 'shared-skills') {
+      for (const name of sharedSkillNames) {
+        const source = join(packageRoot, 'skills', name);
+        const sourceRoot = resolve(source);
+        for (const file of await sourceFiles(sourceRoot)) {
+          pairs.push({ source: file, target: join(destination, name, relative(sourceRoot, file)) });
+        }
+      }
+      continue;
+    }
+    const source = sourcePath(asset.source);
+    const sourceInfo = await lstat(source);
+    if (asset.file || sourceInfo.isFile()) {
+      pairs.push({ source, target: destination });
+      continue;
+    }
+    const sourceRoot = resolve(source);
+    for (const file of await sourceFiles(sourceRoot)) pairs.push({ source: file, target: join(destination, relative(sourceRoot, file)) });
+  }
+  return pairs.map((pair) => ({ source: resolve(pair.source), target: resolve(pair.target) }));
+}
+
+/** Expand registry assets to the exact files copied, never to a host directory. */
+async function materializedAssetPaths(assets, root, installContext) {
+  return (await materializedAssetPairs(assets, root, installContext)).map((pair) => pair.target);
+}
+
+function generatedRoleAssetPaths(adapter, installContext, scope, team) {
+  if (!team || scope !== 'global' || adapter.modelBinding !== 'global-profiles' || typeof adapter.roleModelPaths !== 'function') return [];
+  return adapter.roleModelPaths(installContext);
+}
+
+async function collectInstallationAssets(adapter, controlRoot, installContext, scope, team) {
+  const assets = scope === 'global' ? adapter.globalAssets : adapter.projectAssets;
+  const paths = [
+    ...await materializedAssetPaths(assets, controlRoot, installContext),
+    ...generatedRoleAssetPaths(adapter, installContext, scope, team)
+  ];
+  return collectManagedAssetRecords(paths, {
+    scope,
+    baseRoot: scope === 'project' ? controlRoot : null
+  });
+}
+
+function overallInstallationStatus(scopeStatus) {
+  const values = Object.values(scopeStatus);
+  if (values.every((value) => ['not_configured', 'uninstalled'].includes(value))) return 'uninstalled';
+  if (values.some((value) => ['partial', 'uninstalled'].includes(value))) return 'partial';
+  return 'installed';
+}
+
+async function installationManifestFor({ adapter, controlRoot, installContext, team, global = false, previous = null, installedAt = null }) {
+  const projectAssets = await collectInstallationAssets(adapter, controlRoot, installContext, 'project', team);
+  const previousManifest = previous?.manifest ?? previous;
+  const overlayAssets = await managedOverlayRecord(controlRoot, previousManifest, team);
+  const globalConfigured = Boolean(global || previousManifest?.scopes?.global);
+  const globalAssets = global
+    ? await collectInstallationAssets(adapter, controlRoot, installContext, 'global', team)
+    : (previousManifest?.managed_assets ?? []).filter((asset) => asset.scope === 'global');
+  const scopeStatus = {
+    project: 'installed',
+    global: globalConfigured
+      ? (global ? 'installed' : manifestScopeStatus(previousManifest, 'global'))
+      : 'not_configured'
+  };
+  return buildInstallationManifest({
+    triadVersion: packageVersion,
+    adapter: adapter.id,
+    installedAt: installedAt ?? previousManifest?.installed_at ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    scopes: { project: true, global: globalConfigured },
+    scopeStatus,
+    managedAssets: [...projectAssets, ...overlayAssets, ...globalAssets],
+    status: overallInstallationStatus(scopeStatus)
+  });
+}
+
 async function replaceManagedPath(source, destination, backup, apply) {
   const present = await exists(destination);
   process.stdout.write(`  ${apply ? 'Update' : 'Would update'} ${destination}${present ? ' (backup)' : ''}\n`);
@@ -172,16 +294,26 @@ outside Triad+.
 ${overlayEnd}`;
 }
 
+function managedBlockIn(source, startMarker = overlayStart, endMarker = overlayEnd) {
+  const startCount = source.split(startMarker).length - 1;
+  const endCount = source.split(endMarker).length - 1;
+  if (startCount === 0 && endCount === 0) return null;
+  if (startCount !== 1 || endCount !== 1) throw new Error('Managed instruction block is ambiguous: duplicate or incomplete markers.');
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker, start + startMarker.length);
+  if (end < 0) throw new Error('Managed instruction block has invalid marker order.');
+  const blockEnd = end + endMarker.length;
+  return { start, end, blockEnd, content: source.slice(start, blockEnd) };
+}
+
 async function overlayPlan(controlRoot, team) {
   const target = join(controlRoot, 'AGENTS.md');
   const overlay = instructionOverlay(team);
   if (!(await exists(target))) return { target, action: 'create', content: `# Project instructions\n\n${overlay}\n` };
   const source = await readFile(target, 'utf8');
-  const start = source.indexOf(overlayStart);
-  const end = source.indexOf(overlayEnd);
-  if (start === -1 && end === -1) return { target, action: 'append', content: `${source.replace(/\s*$/, '')}\n\n${overlay}\n` };
-  if (start < 0 || end < start) throw new Error(`Cannot safely update managed instruction block: ${target}`);
-  return { target, action: 'update', content: `${source.slice(0, start)}${overlay}${source.slice(end + overlayEnd.length)}` };
+  const managed = managedBlockIn(source);
+  if (!managed) return { target, action: 'append', content: `${source}${source.endsWith('\n') ? '\n' : '\n\n'}${overlay}\n` };
+  return { target, action: 'update', content: `${source.slice(0, managed.start)}${overlay}${source.slice(managed.blockEnd)}` };
 }
 
 async function applyOverlay(controlRoot, apply, team) {
@@ -190,6 +322,23 @@ async function applyOverlay(controlRoot, apply, team) {
   if (apply) await writeFile(plan.target, plan.content, 'utf8');
 }
 
+async function managedOverlayRecord(controlRoot, previousManifest, team) {
+  const previousBlocks = (previousManifest?.managed_assets ?? []).filter((asset) => asset.kind === 'managed_block' && asset.scope === 'project');
+  if (!team) return previousBlocks;
+  const target = join(controlRoot, 'AGENTS.md');
+  const source = await readFile(target, 'utf8');
+  const managed = managedBlockIn(source);
+  if (!managed) throw new Error(`Managed instruction block is missing after materialization: ${target}`);
+  return [{
+    scope: 'project',
+    path: 'AGENTS.md',
+    kind: 'managed_block',
+    start_marker: overlayStart,
+    end_marker: overlayEnd,
+    sha256: sha256Text(managed.content)
+  }];
+}
+
 async function loadTeamConfig(options) {
   if (options.team) return validateTeamConfiguration(options.team);
   if (!options.teamConfig) return null;
@@ -306,6 +455,138 @@ async function anyExist(paths) {
   return false;
 }
 
+async function globalPathReusable(target, pairs) {
+  let info;
+  try { info = await lstat(target); } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    throw error;
+  }
+  if (info.isDirectory()) {
+    const descendants = pairs.filter((pair) => pathWithin(target, pair.target));
+    if (descendants.length === 0) return false;
+    for (const pair of descendants) {
+      let pairInfo;
+      try { pairInfo = await lstat(pair.target); } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        return false;
+      }
+      if (!pairInfo.isFile() || await sha256File(pair.target) !== await sha256File(pair.source)) return false;
+    }
+    return true;
+  }
+  const pair = pairs.find((candidate) => candidate.target === resolve(target));
+  return Boolean(pair && info.isFile() && await sha256File(target) === await sha256File(pair.source));
+}
+
+function versionTuple(value) {
+  const match = String(value ?? '').match(/^(?:v)?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareVersions(left, right) {
+  const a = versionTuple(left);
+  const b = versionTuple(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function pathWithin(root, target) {
+  const base = resolve(root);
+  const candidate = resolve(target);
+  return candidate === base || candidate.startsWith(`${base}${sep}`);
+}
+
+async function managedAssetPaths(adapter, controlRoot, installContext, scope) {
+  const assets = scope === 'global' ? adapter.globalAssets : adapter.projectAssets;
+  const paths = await materializedAssetPaths(assets, controlRoot, installContext);
+  if (scope === 'global' && adapter.modelBinding === 'global-profiles' && typeof adapter.roleModelPaths === 'function') {
+    paths.push(...adapter.roleModelPaths(installContext));
+  }
+  return new Set(paths.map((target) => resolve(target)));
+}
+
+function manifestAssetPath(controlRoot, asset) {
+  return asset.scope === 'project' ? resolve(controlRoot, asset.path) : resolve(asset.path);
+}
+
+function displayManagedAssetPath(asset) {
+  if (asset.scope !== 'global') return asset.path;
+  const home = resolve(homedir());
+  const target = resolve(asset.path);
+  return pathWithin(home, target) ? `~${relative(home, target) ? `/${relative(home, target)}` : ''}` : target;
+}
+
+function assetAllowedByRegistry(managedPaths, controlRoot, asset) {
+  const target = manifestAssetPath(controlRoot, asset);
+  if (asset.kind === 'managed_block') return asset.scope === 'project' && target === resolve(controlRoot, 'AGENTS.md');
+  return managedPaths.has(target);
+}
+
+async function installationAssetIssues(controlRoot, adapter, installContext, manifest) {
+  const issues = [];
+  for (const asset of manifest.managed_assets) {
+    const target = manifestAssetPath(controlRoot, asset);
+    const expectedState = manifestScopeStatus(manifest, asset.scope);
+    let info;
+    try { info = await lstat(target); } catch (error) {
+      if (error.code === 'ENOENT') {
+        if (expectedState !== 'uninstalled') issues.push({ asset, status: 'missing' });
+        continue;
+      }
+      issues.push({ asset, status: `unreadable:${error.code ?? 'error'}` });
+      continue;
+    }
+    if (asset.kind === 'managed_block') {
+      if (!info.isFile()) {
+        issues.push({ asset, status: 'modified' });
+        continue;
+      }
+      let source;
+      try { source = await readFile(target, 'utf8'); } catch { issues.push({ asset, status: 'unreadable' }); continue; }
+      let managed;
+      try { managed = managedBlockIn(source, asset.start_marker, asset.end_marker); } catch { managed = null; }
+      if (managed && sha256Text(managed.content) !== asset.sha256) issues.push({ asset, status: 'modified' });
+      else if (managed && expectedState === 'uninstalled') issues.push({ asset, status: 'present_after_uninstall' });
+      else if (!managed && expectedState !== 'uninstalled') issues.push({ asset, status: 'modified' });
+      continue;
+    }
+    if (!info.isFile()) {
+      issues.push({ asset, status: 'modified' });
+      continue;
+    }
+    let observed;
+    try { observed = await sha256File(target); } catch { issues.push({ asset, status: 'unreadable' }); continue; }
+    if (observed !== asset.sha256) issues.push({ asset, status: 'modified' });
+    else if (expectedState === 'uninstalled') issues.push({ asset, status: 'present_after_uninstall' });
+  }
+  return issues;
+}
+
+async function inspectInstallation(controlRoot, adapter, installContext) {
+  let loaded;
+  try { loaded = await loadInstallationManifest(controlRoot); }
+  catch (error) {
+    return { state: 'invalid', message: error.message, manifest: null, issues: [] };
+  }
+  if (!loaded) return { state: 'legacy', manifest: null, issues: [] };
+  const manifest = loaded.manifest;
+  if (manifest.adapter !== adapter.id) {
+    return {
+      state: 'invalid',
+      message: `manifest adapter ${manifest.adapter} does not match selected ${adapter.id}`,
+      manifest,
+      issues: []
+    };
+  }
+  const issues = await installationAssetIssues(controlRoot, adapter, installContext, manifest);
+  const versionRelation = compareVersions(packageVersion, manifest.triad_version);
+  return { state: manifestIsUninstalled(manifest) ? 'uninstalled' : 'valid', manifest, issues, versionRelation };
+}
+
 /** Return one status per shared skill so a partial install cannot look healthy. */
 async function sharedSkillStatuses(adapter, root, installContext, scope) {
   const roots = sharedSkillRoots(adapter, root, installContext, scope);
@@ -438,24 +719,52 @@ async function init(options) {
   if (!options.allowProductRepo && productRepositoryAt(controlRoot)) {
     throw new Error('Control path appears to be a product repository. Use a separate project-control workspace, or pass --allow-product-repo after reviewing the risk.');
   }
+  let previousManifest = null;
+  if (await exists(installationManifestPath(controlRoot))) previousManifest = await loadInstallationManifest(controlRoot);
   const installContext = context(controlRoot);
-  const planned = [
+  const projectPlanned = [
     ...adapter.projectPaths(controlRoot, installContext),
-    ...(team ? [teamConfigPath(controlRoot)] : []),
-    ...(options.global ? adapter.globalPaths(installContext) : []),
-    ...(team && options.global && adapter.modelBinding === 'global-profiles' ? adapter.roleModelPaths(installContext) : []),
-    ...(team && options.global && adapter.modelBinding === 'project-frontmatter' && adapter.globalRoleModelPaths
-      ? adapter.globalRoleModelPaths(installContext)
-      : [])
+    ...(team ? [teamConfigPath(controlRoot)] : [])
   ];
-  const existing = await collisions(planned);
-  if (existing.length > 0) throw new Error(`Installation aborted; existing paths would be overwritten:\n${existing.map((target) => `  ${target}`).join('\n')}`);
+  const existingProject = await collisions(projectPlanned);
+  if (existingProject.length > 0) throw new Error(`Installation aborted; existing paths would be overwritten:\n${existingProject.map((target) => `  ${target}`).join('\n')}`);
+  if (options.global) {
+    const globalPlanned = [
+      ...adapter.globalPaths(installContext),
+      ...(team && adapter.modelBinding === 'global-profiles' ? adapter.roleModelPaths(installContext) : []),
+      ...(team && adapter.modelBinding === 'project-frontmatter' && adapter.globalRoleModelPaths
+        ? adapter.globalRoleModelPaths(installContext)
+        : [])
+    ];
+    const globalPairs = await materializedAssetPairs(adapter.globalAssets, controlRoot, installContext);
+    const teamModelPaths = team
+      ? new Set([
+        ...(adapter.modelBinding === 'global-profiles' && typeof adapter.roleModelPaths === 'function' ? adapter.roleModelPaths(installContext) : []),
+        ...(adapter.modelBinding === 'project-frontmatter' && typeof adapter.globalRoleModelPaths === 'function' ? adapter.globalRoleModelPaths(installContext) : [])
+      ].map((target) => resolve(target)))
+      : new Set();
+    const existingGlobal = [];
+    for (const target of globalPlanned) {
+      if (!(await exists(target))) continue;
+      if (teamModelPaths.has(resolve(target)) || !(await globalPathReusable(target, globalPairs))) existingGlobal.push(target);
+    }
+    if (existingGlobal.length > 0) throw new Error(`Installation aborted; existing global paths would be overwritten:\n${existingGlobal.map((target) => `  ${target}`).join('\n')}`);
+  }
   await installAssets(adapter.projectAssets, controlRoot, installContext);
   if (team) await writeTeamConfig(controlRoot, team);
   if (team) await applyOverlay(controlRoot, true, team);
   if (options.global) await installAssets(adapter.globalAssets, controlRoot, installContext);
   if (team) await applyTeamBinding(adapter, controlRoot, team, installContext, 'project');
   if (team && options.global) await applyTeamBinding(adapter, controlRoot, team, installContext, 'global');
+  const manifest = await installationManifestFor({
+    adapter,
+    controlRoot,
+    installContext,
+    team,
+    global: options.global,
+    previous: previousManifest
+  });
+  await writeInstallationManifest(controlRoot, manifest);
   process.stdout.write(`Triad+ installed for ${adapter.label} in ${controlRoot}\n`);
   if (adapter.globalEntry) {
     process.stdout.write(`Install user-level assets with --global to expose ${adapter.entry}.\n`);
@@ -504,7 +813,12 @@ async function upgrade(options) {
   if (!adapter) throw new Error(`Choose --host ${listAdapters().map((item) => item.id).join(', ')}.`);
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
-  await requireDirectory(controlRoot);
+  await requireExistingDirectory(controlRoot);
+  let previousManifest = null;
+  if (await exists(installationManifestPath(controlRoot))) previousManifest = await loadInstallationManifest(controlRoot);
+  if (previousManifest && previousManifest.manifest.adapter !== adapter.id) {
+    throw new Error(`Installation manifest belongs to ${previousManifest.manifest.adapter}, not ${adapter.id}.`);
+  }
   const team = await currentTeam(controlRoot);
   const installContext = context(controlRoot);
   const stamp = new Date().toISOString().replaceAll(':', '-').replaceAll('.', '-');
@@ -521,6 +835,20 @@ async function upgrade(options) {
     await refreshAssets(adapter.globalAssets, controlRoot, installContext, join(backupRoot, 'global'), options.apply);
     if (team && options.apply) await applyTeamBinding(adapter, controlRoot, team, installContext, 'global');
   }
+  if (options.apply) {
+    const manifest = await installationManifestFor({
+      adapter,
+      controlRoot,
+      installContext,
+      team,
+      global: options.global,
+      previous: previousManifest
+    });
+    await writeInstallationManifest(controlRoot, manifest);
+    process.stdout.write(`  Installation manifest updated ${installationManifestPath(controlRoot)}\n`);
+  } else {
+    process.stdout.write(`  Installation manifest would be ${previousManifest ? 'updated' : 'created'} ${installationManifestPath(controlRoot)}\n`);
+  }
   if (!options.apply) process.stdout.write('Dry run only. Re-run with --apply to update managed assets.\n');
 }
 
@@ -539,6 +867,181 @@ async function importBmadStory(options) {
   process.stdout.write(`Provenance ${result.provenancePath}\n`);
 }
 
+function installationScopeText(manifest, scope) {
+  const status = manifestScopeStatus(manifest, scope);
+  if (status === 'installed') return 'yes';
+  if (status === 'not_configured') return 'no';
+  return status;
+}
+
+async function versionCommand(options) {
+  if (!options.control) throw new Error('Provide --control <project-control-path>.');
+  const controlRoot = resolve(options.control);
+  await requireExistingDirectory(controlRoot);
+  process.stdout.write(`Triad+ CLI        ${packageVersion}\n`);
+  process.stdout.write(`Workspace         ${controlRoot}\n`);
+  let loaded;
+  try { loaded = await loadInstallationManifest(controlRoot); }
+  catch (error) {
+    process.stdout.write('Installed Triad   unknown (manifest invalid)\n');
+    process.stdout.write(`Manifest          invalid — ${error.message}\n`);
+    throw error;
+  }
+  if (!loaded) {
+    process.stdout.write('Installed Triad   unknown (legacy installation)\n');
+    process.stdout.write('Manifest          legacy / manifest missing\n');
+    process.stdout.write('Adapter           unknown\n');
+    process.stdout.write('Project install   unknown\n');
+    process.stdout.write('Global install    unknown\n');
+    return;
+  }
+  const manifest = loaded.manifest;
+  const adapter = getAdapter(manifest.adapter);
+  const uninstalled = manifestIsUninstalled(manifest);
+  process.stdout.write(`Installed Triad   ${uninstalled ? 'unknown (uninstalled)' : manifest.triad_version}\n`);
+  process.stdout.write(`Manifest          ${uninstalled ? 'OK (uninstalled)' : 'OK'}\n`);
+  process.stdout.write(`Adapter           ${adapter?.label ?? manifest.adapter}\n`);
+  process.stdout.write(`Project install   ${installationScopeText(manifest, 'project')}\n`);
+  process.stdout.write(`Global install    ${installationScopeText(manifest, 'global')}\n`);
+}
+
+async function uninstall(options) {
+  const adapter = getAdapter(options.host);
+  if (!adapter) throw new Error(`Choose --host ${listAdapters().map((item) => item.id).join(', ')}.`);
+  if (!options.control) throw new Error('Provide --control <project-control-path>.');
+  const controlRoot = resolve(options.control);
+  await requireExistingDirectory(controlRoot);
+  const loaded = await loadInstallationManifest(controlRoot);
+  process.stdout.write(`Triad+ uninstall — ${adapter.label}\n`);
+  if (!loaded) {
+    process.stdout.write('Manifest          legacy / manifest missing\n');
+    process.stdout.write('No files were changed. Refusing to delete assets without an installation manifest.\n');
+    return;
+  }
+  const manifest = loaded.manifest;
+  if (manifest.adapter !== adapter.id) throw new Error(`Installation manifest belongs to ${manifest.adapter}, not ${adapter.id}.`);
+  const installContext = context(controlRoot);
+  const selectedScopes = options.global ? ['project', 'global'] : ['project'];
+  const scopeStats = Object.fromEntries(selectedScopes.map((scope) => [scope, { modified: 0, removed: 0 }]));
+  if (options.global) process.stdout.write('Global assets are preserved because cross-workspace ownership cannot be proven.\n');
+  for (const scope of selectedScopes) {
+    const registryPaths = await managedAssetPaths(adapter, controlRoot, installContext, scope);
+    process.stdout.write(`\n${scope === 'project' ? 'Project' : 'Global'} managed assets\n`);
+    const entries = manifest.managed_assets.filter((asset) => asset.scope === scope);
+    if (entries.length === 0) process.stdout.write('  (none)\n');
+    for (const asset of entries) {
+      const target = manifestAssetPath(controlRoot, asset);
+      const display = displayManagedAssetPath(asset);
+      let info;
+      try { info = await lstat(target); } catch (error) {
+        if (error.code === 'ENOENT') {
+          process.stdout.write(`  ABSENT    ${display}\n`);
+          continue;
+        }
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write(`            cannot inspect asset: ${error.message}\n`);
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (scope === 'global') {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            global ownership may be shared by another control workspace\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (!assetAllowedByRegistry(registryPaths, controlRoot, asset)) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            path is not in the current adapter managed plan\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (asset.kind === 'managed_block') {
+        if (!info.isFile()) {
+          process.stdout.write(`  PRESERVE  ${display}\n`);
+          process.stdout.write('            managed block host file is not a regular file\n');
+          scopeStats[scope].modified += 1;
+          continue;
+        }
+        let source;
+        let managed;
+        try {
+          source = await readFile(target, 'utf8');
+          managed = managedBlockIn(source, asset.start_marker, asset.end_marker);
+        } catch {
+          managed = null;
+        }
+        if (!managed || sha256Text(managed.content) !== asset.sha256) {
+          process.stdout.write(`  PRESERVE  ${display}\n`);
+          process.stdout.write('            managed block is modified, ambiguous, or unverifiable\n');
+          scopeStats[scope].modified += 1;
+          continue;
+        }
+        process.stdout.write(`  ${options.apply ? 'REMOVE' : 'WOULD REMOVE'} block ${display}\n`);
+        if (options.apply) {
+          await writeFile(target, `${source.slice(0, managed.start)}${source.slice(managed.blockEnd)}`, 'utf8');
+          scopeStats[scope].removed += 1;
+        }
+        continue;
+      }
+      if (!info.isFile()) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            asset is no longer a regular file\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      const observed = await sha256File(target);
+      if (observed !== asset.sha256) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            content differs from installation manifest\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      process.stdout.write(`  ${options.apply ? 'REMOVE' : 'WOULD REMOVE'}   ${display}\n`);
+      if (options.apply) {
+        await rm(target, { force: true });
+        scopeStats[scope].removed += 1;
+      }
+    }
+  }
+  process.stdout.write('\nPreserved state\n');
+  for (const preserved of ['.triad-plus/team.json', '.loop/', 'project.yaml', 'features/', 'artifacts/', 'evidence/']) {
+    process.stdout.write(`  KEEP      ${preserved}\n`);
+  }
+  if (!options.apply) {
+    process.stdout.write('\nNo files were changed. Re-run with --apply to uninstall managed assets.\n');
+    return;
+  }
+  const scopeStatus = { project: manifestScopeStatus(manifest, 'project'), global: manifestScopeStatus(manifest, 'global') };
+  for (const scope of selectedScopes) scopeStatus[scope] = scopeStats[scope].modified > 0 ? 'partial' : 'uninstalled';
+  const status = overallInstallationStatus(scopeStatus);
+  const updated = buildInstallationManifest({
+    triadVersion: manifest.triad_version,
+    adapter: manifest.adapter,
+    installedAt: manifest.installed_at,
+    updatedAt: new Date().toISOString(),
+    uninstalledAt: status === 'uninstalled' ? new Date().toISOString() : undefined,
+    scopes: manifest.scopes,
+    scopeStatus,
+    managedAssets: manifest.managed_assets,
+    status
+  });
+  await writeInstallationManifest(controlRoot, updated);
+  process.stdout.write(`\nInstallation manifest updated ${installationManifestPath(controlRoot)}\n`);
+  const projectPartial = scopeStatus.project === 'partial';
+  const globalPreserved = options.global && scopeStatus.global === 'partial';
+  if (status === 'uninstalled') {
+    process.stdout.write('Complete project uninstall; user state was preserved.\n');
+  } else if (projectPartial && globalPreserved) {
+    process.stdout.write('Partial uninstall; modified or unverifiable project assets and shared global assets were preserved.\n');
+  } else if (projectPartial) {
+    process.stdout.write('Partial project uninstall; modified or unverifiable assets were preserved.\n');
+  } else if (globalPreserved) {
+    process.stdout.write('Project uninstall complete; global assets were intentionally preserved because shared ownership could not be proven.\n');
+  } else {
+    process.stdout.write('Uninstall completed conservatively; preserved assets remain in place.\n');
+  }
+}
+
 async function doctor(options) {
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
@@ -551,6 +1054,7 @@ async function doctor(options) {
   }
   for (const adapter of requested) {
     const installContext = context(controlRoot);
+    const installation = await inspectInstallation(controlRoot, adapter, installContext);
     const absent = [];
     for (const target of adapter.projectPaths(controlRoot, installContext)) if (!(await exists(target))) absent.push(target);
     const globalDetected = adapter.globalPaths ? await anyExist(adapter.globalPaths(installContext)) : false;
@@ -568,7 +1072,41 @@ async function doctor(options) {
     const triadSkillTargets = targets.filter((target) => /[/\\]skills[/\\]triad$/.test(target));
     const capability = manifest ? capabilitySnapshot(controlRoot, manifestPath) : null;
     process.stdout.write(`\n${formatDoctorSection(`Triad+ doctor — ${adapter.label}`)}\n`);
-    process.stdout.write(`${formatDoctorLine(adapter.label, absent.length || globalAbsent.length ? 'incomplete' : 'OK')}\n`);
+    process.stdout.write(`${formatDoctorLine(adapter.label, absent.length || globalAbsent.length || installation.issues.length ? 'incomplete' : 'OK')}\n`);
+    process.stdout.write(`${formatDoctorSection('Triad+ installation')}\n`);
+    process.stdout.write(`  ${formatDoctorLine('CLI version', packageVersion)}\n`);
+    if (installation.state === 'legacy') {
+      process.stdout.write(`  ${formatDoctorLine('Installed version', 'unknown (legacy installation)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', 'legacy / manifest missing')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', 'unknown (legacy)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', 'unknown (legacy)')}\n`);
+    } else if (installation.state === 'invalid') {
+      process.stdout.write(`  ${formatDoctorLine('Installed version', 'unknown (manifest invalid)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', 'invalid')} — ${installation.message}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', 'unknown')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', 'unknown')}\n`);
+    } else {
+      const versionStatus = installation.state === 'uninstalled'
+        ? `unknown (uninstalled; last ${installation.manifest.triad_version})`
+        : installation.manifest.triad_version;
+      const versionWarning = installation.versionRelation === 1
+        ? ' — CLI newer / upgrade available'
+        : installation.versionRelation === -1
+        ? ' — CLI older than installed version'
+        : '';
+      const issueStatus = installation.issues.some((issue) => issue.status === 'modified' || issue.status === 'present_after_uninstall')
+        ? 'managed asset modified'
+        : installation.issues.some((issue) => issue.status === 'missing')
+        ? 'managed asset missing'
+        : installation.state === 'uninstalled' ? 'OK (uninstalled)' : 'OK';
+      process.stdout.write(`  ${formatDoctorLine('Installed version', versionStatus)}${versionWarning}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', issueStatus)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', installationScopeText(installation.manifest, 'project'))}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', installationScopeText(installation.manifest, 'global'))}\n`);
+    }
     process.stdout.write(`${formatDoctorSection('Runtime and installation')}\n`);
     process.stdout.write(`  ${formatDoctorLine('Host runtime', binary ? `OK (${binary})` : 'not installed or version unavailable')}\n`);
     process.stdout.write(`  ${formatDoctorLine('Verifier', node && await exists(join(controlRoot, '.triad-runtime', 'triad-verify.mjs')) ? 'OK' : 'incomplete')}\n`);
@@ -660,10 +1198,17 @@ async function interactiveInit() {
 }
 
 try {
-  const options = parseArgs(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) {
+    process.stdout.write(`${packageVersion}\n`);
+    process.exit(0);
+  }
+  const options = parseArgs(argv);
   if (options.command === 'init') await init(options);
   else if (options.command === 'doctor') await doctor(options);
+  else if (options.command === 'version') await versionCommand(options);
   else if (options.command === 'upgrade') await upgrade(options);
+  else if (options.command === 'uninstall') await uninstall(options);
   else if (options.command === 'import-bmad-story') await importBmadStory(options);
   else if (!options.command) await interactiveInit();
   else if (options.command === '--help' || options.command === '-h') usage(0);