skillpacks 0.1.0 → 0.1.2

package/src/cli/lifecycle.mjs

@@ -12,12 +12,14 @@ import {
   unlinkSync,
   writeFileSync
 } from 'node:fs';
+import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   canonicalHibernatedPack,
   hibernatedPacksForSkill,
-  hibernatedSkillNamesForPack
+  hibernatedSkillNamesForPack,
+  normalizePack
 } from './pack-normalization.mjs';
 import {
   inferProjectType,
@@ -31,6 +33,8 @@ const HIBERNATED_ARCHIVE_RELATIVE_PATH = 'archive/hibernated-packs/2026-06-poket
 const HIBERNATED_REACTIVATION_TEXT =
   'Reactivation requires a stable service/API, a known auth contract, and updated smoke tests.';
 const TOOLS = ['claude', 'codex'];
+const AGENT_DOCS = ['AGENTS.md', 'CLAUDE.md'];
+const KNOWN_PROVISION_AGENTIC_CONFIG_VERSIONS = new Set(['v0.5', 'v0.6', 'v0.7', 'v0.8', 'v0.9', 'v0.10', 'v0.11']);
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(moduleDir, '..', '..');
 const checkoutRoot = resolve(packageRoot, '..', '..');
@@ -52,7 +56,7 @@ function resolvePackagedPath(relativePath) {
 function projectTypeForPack(pack) {
   if (
     [
-      'business-discovery',
+      'business-research',
       'customer-lifecycle',
       'business-growth',
       'business-ops',
@@ -85,6 +89,12 @@ function activePackNames(manifest) {
     .sort((a, b) => a.localeCompare(b));
 }
 
+function manifestPackageLabel(manifest) {
+  const name = manifest?.package?.name || 'skillpacks';
+  const version = manifest?.package?.version || 'unknown';
+  return `${name}@${version}`;
+}
+
 function availablePacksInline(manifest) {
   const names = activePackNames(manifest);
   if (names.length === 0) {
@@ -115,6 +125,12 @@ function packSkillEntries(manifest, packName, tool) {
   });
 }
 
+function baseSkillEntries(manifest, tool) {
+  return manifestSkills(manifest).filter((skill) => {
+    return skill.scope === 'base' && skill.platform === tool && skill.path;
+  });
+}
+
 function uniquePackSkillNames(manifest, packName) {
   return [
     ...new Set(
@@ -125,6 +141,16 @@ function uniquePackSkillNames(manifest, packName) {
   ].sort((a, b) => a.localeCompare(b));
 }
 
+function uniqueBaseSkillNames(manifest) {
+  return [
+    ...new Set(
+      manifestSkills(manifest)
+        .filter((skill) => skill.scope === 'base' && skill.name)
+        .map((skill) => skill.name)
+    )
+  ].sort((a, b) => a.localeCompare(b));
+}
+
 function findPackForSkill(manifest, skillName) {
   return manifestSkills(manifest).find((skill) => skill.name === skillName && skill.pack)?.pack || null;
 }
@@ -244,11 +270,11 @@ function managedMarkerField(target, field) {
 
 function sourceOwnedBySkillpacks(source) {
   const ownedPrefixes = [
-    join(packageRoot, 'global', 'claude'),
-    join(packageRoot, 'global', 'codex'),
+    join(packageRoot, 'base', 'claude'),
+    join(packageRoot, 'base', 'codex'),
     join(packageRoot, 'packs'),
-    join(checkoutRoot, 'global', 'claude'),
-    join(checkoutRoot, 'global', 'codex'),
+    join(checkoutRoot, 'base', 'claude'),
+    join(checkoutRoot, 'base', 'codex'),
     join(checkoutRoot, 'packs')
   ];
 
@@ -375,17 +401,23 @@ function linkSkill(projectRoot, tool, skillName, sourceDir, config) {
 
   if (syncSkillInstall(effective.source, target)) {
     if (effective.usingPinned) {
-      console.log(`Installed .${tool}/skills/${skillName} -> ${effective.source} (pinned ${effective.pinned})`);
+      console.log(`Installed .${tool}/skills/${skillName} (pinned ${effective.pinned})`);
     } else {
-      console.log(`Installed .${tool}/skills/${skillName} -> ${effective.source}`);
+      console.log(`Installed .${tool}/skills/${skillName}`);
     }
+    return true;
   }
+  return false;
 }
 
 function enabledPacks(config) {
   return Array.isArray(config?.enabled_packs) ? config.enabled_packs : [];
 }
 
+function baseSkillsEnabled(config) {
+  return config?.base_skills === true;
+}
+
 function pinnedVersions(config) {
   return config?.pinned_versions && typeof config.pinned_versions === 'object'
     ? config.pinned_versions
@@ -410,6 +442,40 @@ function writePackProjectConfig(projectRoot, pack, packs) {
   writeProjectConfig(projectRoot, next);
 }
 
+function writeBaseProjectConfig(projectRoot) {
+  const existing = readProjectConfig(projectRoot);
+  const next = existing
+    ? { ...existing }
+    : {
+        project_type: inferProjectType(projectRoot),
+        enabled_packs: [],
+        skill_pack_version: 1
+      };
+
+  if (!next.project_type) {
+    next.project_type = inferProjectType(projectRoot);
+  }
+  if (!Array.isArray(next.enabled_packs)) {
+    next.enabled_packs = [];
+  }
+  next.base_skills = true;
+  next.skill_pack_version = 1;
+  writeProjectConfig(projectRoot, next);
+}
+
+function installBaseSkills(projectRoot, manifest, config = readProjectConfig(projectRoot)) {
+  const skillNames = uniqueBaseSkillNames(manifest);
+  if (skillNames.length === 0) {
+    throw new Error('No base skills found in the packaged manifest');
+  }
+
+  for (const tool of TOOLS) {
+    for (const skill of baseSkillEntries(manifest, tool)) {
+      linkSkill(projectRoot, tool, skill.name, skillSourceDir(skill), config);
+    }
+  }
+}
+
 function installPack(projectRoot, manifest, pack) {
   const hibernatedPack = canonicalHibernatedPack(pack);
   if (hibernatedPack) {
@@ -545,6 +611,85 @@ function enabledSkillEntries(config) {
   return Object.entries(config.enabled_skills);
 }
 
+function staleProjectPackError(pack, location, reason = '') {
+  const detail = reason ? ` ${reason}` : '';
+  return new Error(
+    `Stale pack entry '${pack}' in .agents/project.json ${location}.${detail} ` +
+      `Run 'npx skillpacks remove ${pack}' or edit .agents/project.json to remove or rename it.`
+  );
+}
+
+function reconcileStoredPack(manifest, pack, location) {
+  const hibernatedPack = canonicalHibernatedPack(pack);
+  if (hibernatedPack) {
+    throw hibernatedPackError(pack, hibernatedPack);
+  }
+
+  if (activePackExists(manifest, pack)) {
+    return pack;
+  }
+
+  const activeMatches = normalizePack(pack).filter((candidate) => activePackExists(manifest, candidate));
+  if (activeMatches.length === 1) {
+    return activeMatches[0];
+  }
+  if (activeMatches.length > 1) {
+    throw staleProjectPackError(
+      pack,
+      location,
+      `It resolves to multiple active packs: ${activeMatches.join(', ')}.`
+    );
+  }
+
+  throw staleProjectPackError(pack, location);
+}
+
+function reconcileProjectConfig(projectRoot, manifest) {
+  const config = readProjectConfig(projectRoot);
+  if (!config) {
+    return null;
+  }
+
+  const next = { ...config };
+  let changed = false;
+
+  if (Array.isArray(config.enabled_packs)) {
+    const packs = [];
+    for (const pack of config.enabled_packs) {
+      const canonical = reconcileStoredPack(manifest, pack, 'enabled_packs');
+      if (canonical !== pack) {
+        changed = true;
+      }
+      if (!packs.includes(canonical)) {
+        packs.push(canonical);
+      } else {
+        changed = true;
+      }
+    }
+    next.enabled_packs = packs;
+  }
+
+  if (config.enabled_skills && typeof config.enabled_skills === 'object') {
+    const enabledSkills = {};
+    for (const [skillName, pack] of Object.entries(config.enabled_skills)) {
+      const canonical = findPackForSkill(manifest, skillName);
+      enabledSkills[skillName] = canonical || pack;
+      if (canonical && canonical !== pack) {
+        changed = true;
+      }
+    }
+    next.enabled_skills = enabledSkills;
+  }
+
+  if (changed) {
+    writeProjectConfig(projectRoot, next);
+    console.log('Reconciled .agents/project.json pack names');
+    return next;
+  }
+
+  return config;
+}
+
 function installedSkillTargets(projectRoot) {
   const roots = TOOLS.map((tool) => targetRoot(projectRoot, tool));
   const paths = [];
@@ -573,6 +718,9 @@ function skillInstallStatus(target) {
   const stats = lstatSync(target);
   if (stats.isSymbolicLink()) {
     const source = readlinkSync(target);
+    if (!sourceOwnedBySkillpacks(source)) {
+      return { status: 'not-managed', recordedVersion: '', currentVersion: '' };
+    }
     const version = skillSourceVersion(source);
     return { status: 'pinned', recordedVersion: version, currentVersion: version };
   }
@@ -672,7 +820,7 @@ function relinkPinnedSkill(projectRoot, manifest, pack, skillName, version) {
     }
 
     if (syncSkillInstall(source, join(root, skillName))) {
-      console.log(`Pinned .${tool}/skills/${skillName} -> ${source}`);
+      console.log(`Pinned .${tool}/skills/${skillName} (${version})`);
     }
   }
 }
@@ -691,7 +839,7 @@ function relinkUnpinnedSkill(projectRoot, manifest, pack, skillName) {
     }
 
     if (syncSkillInstall(source, join(root, skillName))) {
-      console.log(`Unpinned .${tool}/skills/${skillName} -> ${source}`);
+      console.log(`Unpinned .${tool}/skills/${skillName} (latest)`);
     }
   }
 }
@@ -699,6 +847,12 @@ function relinkUnpinnedSkill(projectRoot, manifest, pack, skillName) {
 function expectedSkillNames(manifest, config) {
   const expected = new Set();
 
+  if (baseSkillsEnabled(config)) {
+    for (const skillName of uniqueBaseSkillNames(manifest)) {
+      expected.add(skillName);
+    }
+  }
+
   for (const pack of enabledPacks(config)) {
     for (const skillName of uniquePackSkillNames(manifest, pack)) {
       expected.add(skillName);
@@ -709,6 +863,10 @@ function expectedSkillNames(manifest, config) {
     expected.add(skillName);
   }
 
+  for (const skillName of Object.keys(pinnedVersions(config))) {
+    expected.add(skillName);
+  }
+
   return expected;
 }
 
@@ -719,6 +877,40 @@ export function printSessionReloadNotice() {
   console.log('Codex: start a fresh Codex CLI session if the $ skill list does not show newly installed or removed project-local skills.');
 }
 
+export async function initProject({ manifest, projectRoot = process.cwd() }) {
+  return withProjectLock(projectRoot, 'init', async () => {
+    installBaseSkills(projectRoot, manifest);
+    writeBaseProjectConfig(projectRoot);
+    console.log('Updated .agents/project.json (base skills enabled)');
+    console.log(`Initialized project base skills to ${manifestPackageLabel(manifest)}.`);
+    printSessionReloadNotice();
+    return 0;
+  });
+}
+
+export async function uninstallGlobal({ homeRoot = homedir() } = {}) {
+  let removed = 0;
+
+  for (const tool of TOOLS) {
+    const root = join(homeRoot, `.${tool}`, 'skills');
+    if (!existsSync(root)) {
+      continue;
+    }
+
+    for (const entry of readdirSync(root).sort((a, b) => a.localeCompare(b))) {
+      const target = join(root, entry);
+      if (removeRepoSkillInstall(target)) {
+        console.log(`Removed ${relative(homeRoot, target)}`);
+        removed += 1;
+      }
+    }
+  }
+
+  console.log(`Done. Removed ${removed} repo-managed base skill install(s) from ${homeRoot}.`);
+  console.log('Base skills now install project-local via `npx skillpacks init`.');
+  return 0;
+}
+
 export async function installResolved({ manifest, projectRoot = process.cwd(), packs = [], skills = [] }) {
   return withProjectLock(projectRoot, `install ${[...packs, ...skills].join(' ')}`.trim(), async () => {
     for (const pack of packs) {
@@ -732,11 +924,312 @@ export async function installResolved({ manifest, projectRoot = process.cwd(), p
   });
 }
 
-export function doctorProject({ projectRoot = process.cwd() } = {}) {
+function syncExpectedSkillRoots(projectRoot, manifest) {
+  const config = readProjectConfig(projectRoot);
+  if (!config) {
+    return 0;
+  }
+
+  let changed = 0;
+
+  if (baseSkillsEnabled(config)) {
+    for (const tool of TOOLS) {
+      for (const skill of baseSkillEntries(manifest, tool)) {
+        if (linkSkill(projectRoot, tool, skill.name, skillSourceDir(skill), config)) {
+          changed += 1;
+        }
+      }
+    }
+  }
+
+  for (const pack of enabledPacks(config)) {
+    for (const tool of TOOLS) {
+      for (const skill of packSkillEntries(manifest, pack, tool)) {
+        if (linkSkill(projectRoot, tool, skill.name, skillSourceDir(skill), config)) {
+          changed += 1;
+        }
+      }
+    }
+  }
+
+  for (const [skillName, pack] of enabledSkillEntries(config)) {
+    for (const tool of TOOLS) {
+      const skill = findSkillEntry(manifest, pack, tool, skillName);
+      if (skill && linkSkill(projectRoot, tool, skillName, skillSourceDir(skill), config)) {
+        changed += 1;
+      }
+    }
+  }
+
+  return changed;
+}
+
+function pruneOrphanedSkillRoots({ manifest, projectRoot, dryRun = false }) {
+  const expected = expectedSkillNames(manifest, readProjectConfig(projectRoot));
+  let removed = 0;
+
+  for (const target of installedSkillTargets(projectRoot)) {
+    const status = skillInstallStatus(target);
+    if (status.status === 'not-managed') {
+      continue;
+    }
+
+    let reason = '';
+    if (status.status === 'missing-source') {
+      reason = 'source no longer exists';
+    } else if (!expected.has(basename(target))) {
+      reason = 'pack not enabled';
+    }
+
+    if (!reason) {
+      continue;
+    }
+
+    const rel = relativeProjectPath(projectRoot, target);
+    if (dryRun) {
+      console.log(`would remove  ${rel} (${reason})`);
+    } else if (removeRepoSkillInstall(target)) {
+      console.log(`removed  ${rel} (${reason})`);
+    } else if (lstatSync(target).isSymbolicLink()) {
+      unlinkSync(target);
+      console.log(`removed  ${rel} (${reason})`);
+    } else if (lstatSync(target).isDirectory()) {
+      rmSync(target, { recursive: true, force: true });
+      console.log(`removed  ${rel} (${reason})`);
+    } else {
+      console.error(`FAILED   ${rel} (${reason})`);
+    }
+
+    removed += 1;
+  }
+
+  return removed;
+}
+
+function provisionerSkillText() {
+  const sourcePath = resolvePackagedPath('base/codex/provision-agentic-config/SKILL.md');
+  if (!existsSync(sourcePath)) {
+    throw new Error(`Cannot find canonical provision-agentic-config skill at ${sourcePath}`);
+  }
+  return readFileSync(sourcePath, 'utf8');
+}
+
+function extractCanonicalProvisionBlock(fileName) {
+  const heading = fileName === 'CLAUDE.md' ? '## Required Claude Block' : '## Required AGENTS Block';
+  const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`${escapedHeading}\\r?\\n\\r?\\n\`\`\`\`(?:md|markdown)\\r?\\n([\\s\\S]*?)\\r?\\n\`\`\`\``);
+  const match = provisionerSkillText().match(pattern);
+  if (!match) {
+    throw new Error(`Cannot extract canonical ${fileName} provision block from provision-agentic-config`);
+  }
+  return match[1].replace(/\r\n/g, '\n').trimEnd();
+}
+
+function provisionNote(fileName) {
+  return `Provisioned artifact: ./${fileName}. Source: workflow.md. Verification: block appears exactly once.`;
+}
+
+function parseProvisionedAgentDoc(projectRoot, fileName) {
+  const filePath = join(projectRoot, fileName);
+  if (!existsSync(filePath)) {
+    throw new Error(`${fileName}: file not found`);
+  }
+
+  const original = readFileSync(filePath, 'utf8');
+  const markerPattern = /<!-- provision-agentic-config (v\d+\.\d+) -->/g;
+  const markers = [...original.matchAll(markerPattern)];
+  if (markers.length === 0) {
+    throw new Error(`${fileName}: missing provision-agentic-config marker`);
+  }
+  if (markers.length > 1) {
+    throw new Error(`${fileName}: duplicate provision-agentic-config markers`);
+  }
+
+  const marker = markers[0];
+  const version = marker[1];
+  if (!KNOWN_PROVISION_AGENTIC_CONFIG_VERSIONS.has(version)) {
+    throw new Error(`${fileName}: unknown provision-agentic-config version ${version}`);
+  }
+
+  const afterMarker = original.slice(marker.index);
+  const note = provisionNote(fileName).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const noteMatch = afterMarker.match(new RegExp(`^${note}$`, 'm'));
+  if (!noteMatch || noteMatch.index === undefined) {
+    throw new Error(`${fileName}: malformed provision block boundary`);
+  }
+  if (!afterMarker.slice(0, noteMatch.index).includes('## Workflow Orchestration')) {
+    throw new Error(`${fileName}: malformed provision block boundary`);
+  }
+
+  let end = marker.index + noteMatch.index + noteMatch[0].length;
+  while (original[end] === '\r' || original[end] === '\n') {
+    end += 1;
+  }
+
+  return {
+    fileName,
+    filePath,
+    original,
+    start: marker.index,
+    end,
+    prefix: original.slice(0, marker.index),
+    suffix: original.slice(end)
+  };
+}
+
+function replacementProvisionBlock(fileName, hasSuffix) {
+  const block = extractCanonicalProvisionBlock(fileName);
+  const note = provisionNote(fileName);
+  return hasSuffix ? `${block}\n\n${note}\n\n` : `${block}\n\n${note}\n`;
+}
+
+function unifiedDiff(fileName, before, after) {
+  const beforeLines = before.endsWith('\n') ? before.slice(0, -1).split('\n') : before.split('\n');
+  const afterLines = after.endsWith('\n') ? after.slice(0, -1).split('\n') : after.split('\n');
+  const output = [
+    `--- ${fileName}`,
+    `+++ ${fileName}`,
+    `@@ -1,${beforeLines.length} +1,${afterLines.length} @@`
+  ];
+  output.push(...beforeLines.map((line) => `-${line}`));
+  output.push(...afterLines.map((line) => `+${line}`));
+  return `${output.join('\n')}\n`;
+}
+
+function timestampForBackup() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function migrateAgentDocs({ projectRoot = process.cwd(), dryRun = false } = {}) {
+  const planned = [];
+  const errors = [];
+
+  for (const fileName of AGENT_DOCS) {
+    try {
+      const parsed = parseProvisionedAgentDoc(projectRoot, fileName);
+      const next =
+        parsed.prefix + replacementProvisionBlock(fileName, parsed.suffix.length > 0) + parsed.suffix;
+      planned.push({ ...parsed, next });
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Refusing agent-doc migration:\n${errors.map((error) => `  - ${error}`).join('\n')}`);
+  }
+
+  const changed = planned.filter((entry) => entry.original !== entry.next);
+  if (changed.length === 0) {
+    console.log('Agent docs already match the canonical provision blocks.');
+    return 0;
+  }
+
+  for (const entry of changed) {
+    console.log(unifiedDiff(entry.fileName, entry.original, entry.next));
+  }
+
+  if (dryRun) {
+    console.log('Dry run: no files written.');
+    return changed.length;
+  }
+
+  const backupDir = join(projectRoot, '.agents', 'backups');
+  mkdirSync(backupDir, { recursive: true });
+  const timestamp = timestampForBackup();
+  const reports = [];
+
+  for (const entry of changed) {
+    const backupPath = join(backupDir, `${entry.fileName}.${timestamp}.bak`);
+    writeFileSync(backupPath, entry.original);
+    writeFileSync(entry.filePath, entry.next);
+    reports.push({
+      fileName: entry.fileName,
+      backupPath: relativeProjectPath(projectRoot, backupPath)
+    });
+  }
+
+  console.log('Agent docs changed:');
+  for (const report of reports) {
+    console.log(`  ${report.fileName} (backup: ${report.backupPath})`);
+  }
+
+  return changed.length;
+}
+
+function parseDoctorArgs(args) {
+  const options = {
+    fix: false,
+    agentDocs: false,
+    dryRun: false
+  };
+
+  for (const arg of args) {
+    if (arg === '--fix') {
+      options.fix = true;
+      continue;
+    }
+    if (arg === '--agent-docs') {
+      options.agentDocs = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    throw new Error(`doctor: unknown option '${arg}'`);
+  }
+
+  if (options.agentDocs && !options.fix) {
+    throw new Error('doctor --agent-docs requires --fix');
+  }
+  if (options.dryRun && !options.agentDocs) {
+    throw new Error('doctor --dry-run is only supported with --fix --agent-docs');
+  }
+
+  return options;
+}
+
+export async function doctorProject({ manifest, projectRoot = process.cwd(), args = [] } = {}) {
+  const options = parseDoctorArgs(args);
+
+  if (options.fix) {
+    if (options.dryRun) {
+      migrateAgentDocs({ projectRoot, dryRun: true });
+      return 0;
+    }
+
+    return withProjectLock(projectRoot, 'doctor --fix', async () => {
+      console.log('Doctor fix: generated skill-root cleanup');
+      reconcileProjectConfig(projectRoot, manifest);
+      const synced = syncExpectedSkillRoots(projectRoot, manifest);
+      const removed = pruneOrphanedSkillRoots({ manifest, projectRoot });
+      if (synced === 0 && removed === 0) {
+        console.log('No generated skill-root changes needed.');
+      } else {
+        console.log(`Generated skill-root cleanup changed ${synced + removed} item(s).`);
+      }
+
+      if (options.agentDocs) {
+        migrateAgentDocs({ projectRoot, dryRun: false });
+      }
+
+      if (synced > 0 || removed > 0) {
+        printSessionReloadNotice();
+      }
+
+      return 0;
+    });
+  }
+
   const mode = projectSkillUpdatesMode(projectRoot) || 'warn (default)';
   console.log(`Project skill update mode: ${mode}`);
   console.log('Skill install drift (.claude/skills, .codex/skills):');
 
+  const refreshCmd = existsSync(join(checkoutRoot, '.git'))
+    ? `${checkoutRoot}/scripts/pack.sh refresh`
+    : 'npx skillpacks refresh';
+
   let found = false;
   let anyStale = false;
   for (const target of installedSkillTargets(projectRoot)) {
@@ -755,7 +1248,7 @@ export function doctorProject({ projectRoot = process.cwd() } = {}) {
         console.log(`  pinned   ${rel} (frozen ${status.recordedVersion || '?'})`);
         break;
       case 'unknown':
-        console.log(`  unknown  ${rel} — run refresh to enable drift tracking`);
+        console.log(`  unknown  ${rel} — run \`${refreshCmd}\` to enable drift tracking`);
         break;
       case 'missing-source':
         console.log(`  missing  ${rel} — canonical source no longer exists`);
@@ -777,7 +1270,7 @@ export function doctorProject({ projectRoot = process.cwd() } = {}) {
 
   if (anyStale) {
     console.log('');
-    console.log('Fix: scripts/pack.sh refresh');
+    console.log(`Fix: ${refreshCmd}`);
     return 1;
   }
 
@@ -839,43 +1332,7 @@ export async function pruneProject({
   }
 
   return withProjectLock(projectRoot, 'prune', async () => {
-    const expected = expectedSkillNames(manifest, readProjectConfig(projectRoot));
-    let removed = 0;
-
-    for (const target of installedSkillTargets(projectRoot)) {
-      const status = skillInstallStatus(target);
-      if (status.status === 'not-managed') {
-        continue;
-      }
-
-      let reason = '';
-      if (status.status === 'missing-source') {
-        reason = 'source no longer exists';
-      } else if (!expected.has(basename(target))) {
-        reason = 'pack not enabled';
-      }
-
-      if (!reason) {
-        continue;
-      }
-
-      const rel = relativeProjectPath(projectRoot, target);
-      if (dryRun) {
-        console.log(`would remove  ${rel} (${reason})`);
-      } else if (removeRepoSkillInstall(target)) {
-        console.log(`removed  ${rel} (${reason})`);
-      } else if (lstatSync(target).isSymbolicLink()) {
-        unlinkSync(target);
-        console.log(`removed  ${rel} (${reason})`);
-      } else if (lstatSync(target).isDirectory()) {
-        rmSync(target, { recursive: true, force: true });
-        console.log(`removed  ${rel} (${reason})`);
-      } else {
-        console.error(`FAILED   ${rel} (${reason})`);
-      }
-
-      removed += 1;
-    }
+    const removed = pruneOrphanedSkillRoots({ manifest, projectRoot, dryRun });
 
     if (removed === 0) {
       console.log('Nothing to prune.');
@@ -905,20 +1362,25 @@ export async function removeResolved({ manifest, projectRoot = process.cwd(), pa
 
 export async function refreshProject({ manifest, projectRoot = process.cwd() }) {
   return withProjectLock(projectRoot, 'refresh', async () => {
-    const config = readProjectConfig(projectRoot);
+    const config = reconcileProjectConfig(projectRoot, manifest);
     const packs = enabledPacks(config);
     const skills = enabledSkillEntries(config).map(([skill]) => skill);
+    const base = baseSkillsEnabled(config);
 
-    if (packs.length === 0 && skills.length === 0) {
+    if (!base && packs.length === 0 && skills.length === 0) {
       throw new Error('No enabled packs or skills in .agents/project.json');
     }
 
+    if (base) {
+      installBaseSkills(projectRoot, manifest, config);
+    }
     for (const pack of packs) {
       installPack(projectRoot, manifest, pack);
     }
     for (const skill of skills) {
       installSingleSkill(projectRoot, manifest, skill);
     }
+    console.log(`Refreshed project skills to ${manifestPackageLabel(manifest)}.`);
     printSessionReloadNotice();
     return 0;
   });