genesis-compiler 1.0.0 → 1.1.0

package/src/cli.js

@@ -0,0 +1,276 @@
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+
+import {
+  addStack,
+  adoptProject,
+  check,
+  generatePrompt,
+  getContext,
+  indexCodebase,
+  initialize,
+  installCodex,
+  listStackPieces,
+  verify,
+} from './index.js';
+import {
+  codexAdoptionRecommendation,
+  codexSessionContext,
+  completeCodexTurn,
+  discardCodexTurn,
+  recordCodexTurn,
+} from './index/codex-hooks.js';
+import { asDiagnostic, fail } from './index/errors.js';
+
+const USAGE = `Usage:
+  genesis init
+  genesis adopt [product guidance...]
+  genesis codex install
+  genesis stack list
+  genesis stack add <piece...>
+  genesis context <path...>
+  genesis index [function-or-path...]
+  genesis prompt [request...]
+  genesis prompt --task <work|deslop|program|blueprint|describe|review> [request...]
+  genesis verify
+  genesis check
+
+Options:
+  --project-root <path>  Set the project root (default: current directory)
+  --task <task>          Select the prompt task (default: work)
+  --json                 Emit one machine-readable result
+  -h, --help             Show this help
+
+Genesis generates prompts; it never starts or manages an AI agent. Give the
+prompt to the agent you already use. Review all edits through the ordinary Git
+diff, then run genesis verify for the Stack's concrete checks.
+`;
+
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prompt', 'stack', 'verify']);
+
+function parseCommand(argv) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
+    return { command: 'help', operands: [], options: {} };
+  }
+  const [command, ...rest] = argv;
+  if (!COMMANDS.has(command)) fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        json: { type: 'boolean', default: false },
+        'project-root': { type: 'string' },
+        task: { type: 'string' },
+      },
+    });
+  } catch (error) {
+    fail('CLI_ARGUMENT_INVALID', error.message);
+  }
+  const options = {
+    json: parsed.values.json,
+    projectRoot: parsed.values['project-root'],
+    task: parsed.values.task,
+  };
+  const operands = parsed.positionals;
+  if (options.task !== undefined && command !== 'prompt') {
+    fail('CLI_OPTION_NOT_APPLICABLE', `Option --task is not applicable to ${command}.`);
+  }
+  if (command === 'stack') {
+    if (!['list', 'add'].includes(operands[0])) {
+      fail('CLI_STACK_ACTION_REQUIRED', 'Command stack requires list or add.');
+    }
+    if (operands[0] === 'add' && operands.length < 2) {
+      fail('CLI_STACK_PIECE_REQUIRED', 'Command stack add requires at least one piece.');
+    }
+    if (operands[0] === 'list' && operands.length !== 1) {
+      fail('CLI_EXTRA_ARGUMENT', 'Command stack list accepts no extra arguments.');
+    }
+  } else if (command === 'codex') {
+    if (operands.length !== 1 || operands[0] !== 'install') {
+      fail('CLI_CODEX_ACTION_REQUIRED', 'Command codex requires exactly: install.');
+    }
+  } else if (command === 'context' && operands.length === 0) {
+    fail('CONTEXT_PATH_REQUIRED', 'Command context requires at least one project path.');
+  } else if (command === 'hook' && (operands.length !== 1 || !['begin', 'discover', 'end', 'session', 'stop'].includes(operands[0]))) {
+    fail('CLI_HOOK_ACTION_REQUIRED', 'Command hook requires exactly one of: discover, session, begin, stop, end.');
+  } else if (!['adopt', 'context', 'hook', 'index', 'prompt'].includes(command) && operands.length > 0) {
+    fail('CLI_EXTRA_ARGUMENT', `Command ${command} accepts no arguments.`);
+  }
+  return { command, operands, options };
+}
+
+function line(stream, value = '') {
+  stream.write(`${String(value).replace(/\n$/u, '')}\n`);
+}
+
+function namedItems(label, values) {
+  if (!Array.isArray(values) || values.length === 0) return;
+  line(process.stdout, `${label}:`);
+  for (const value of values) line(process.stdout, `  - ${value}`);
+}
+
+function writeCheck(result) {
+  line(process.stdout, `Blueprint: ${result.blueprint}`);
+  line(process.stdout, `Stack: ${result.stack}`);
+  line(process.stdout, `Agent Skills: ${result.skills}`);
+  line(process.stdout, `Program: ${result.program}`);
+  line(process.stdout, `Resource inputs: ${result.resources}`);
+  line(process.stdout, `Verification: ${result.verification}`);
+  namedItems('Program files', result.programFiles);
+  namedItems('Subsystems', result.subsystems);
+  for (const item of result.diagnostics) line(process.stdout, `${item.code}: ${item.message}`);
+  if (result.guidance) line(process.stdout, result.guidance);
+  line(process.stdout, `Check: ${result.status}`);
+}
+
+function writeResult(command, result) {
+  if (command === 'prompt') {
+    process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
+    return;
+  }
+  if (command === 'adopt') {
+    if (result.summary) line(process.stdout, result.summary);
+    namedItems('Changed files', result.changedFiles);
+    if (result.guidance) line(process.stdout, result.guidance);
+    line(process.stdout, '');
+    process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
+    return;
+  }
+  if (command === 'check') {
+    writeCheck(result);
+    return;
+  }
+  if (command === 'context') {
+    process.stdout.write(result.context.endsWith('\n') ? result.context : `${result.context}\n`);
+    return;
+  }
+  if (command === 'index') {
+    line(process.stdout, result.summary);
+    line(process.stdout, `Machine City: ${result.paths.machine}`);
+    line(process.stdout, `Program City: ${result.paths.program}`);
+    if (result.totalMatches > 0) {
+      line(process.stdout, 'Matching functions:');
+      for (const entry of result.matches) {
+        const signature = `${entry.qualifiedName}(${entry.parameters.join(', ')})`;
+        line(process.stdout, `  - ${entry.visibility} ${signature} — ${entry.path}:${entry.line}`);
+      }
+      if (result.totalMatches > result.matches.length) {
+        line(process.stdout, `  - ... and ${result.totalMatches - result.matches.length} more`);
+      }
+    }
+    for (const item of result.diagnostics || []) line(process.stdout, `${item.code}: ${item.message}`);
+    line(process.stdout, `index: ${result.status}`);
+    return;
+  }
+  if (command === 'hook') {
+    if (['discover', 'session'].includes(result.kind) && result.output) line(process.stdout, result.output);
+    else if (result.kind === 'stop') line(process.stdout, JSON.stringify(result.output));
+    return;
+  }
+  if (command === 'stack' && Array.isArray(result.pieces)) {
+    for (const piece of result.pieces) {
+      line(process.stdout, `${piece.id}: ${piece.description}`);
+      if (piece.requires.length > 0) line(process.stdout, `  requires: ${piece.requires.join(', ')}`);
+      if (piece.indexers.length > 0) line(process.stdout, `  indexers: ${piece.indexers.join(', ')}`);
+    }
+    return;
+  }
+  if (result.summary) line(process.stdout, result.summary);
+  namedItems('Changed files', result.changedFiles);
+  namedItems('Commands', result.commands?.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
+  for (const item of result.diagnostics || []) {
+    line(process.stdout, `${item.code}: ${item.message}`);
+    for (const field of ['stdout', 'stderr']) {
+      const output = item.details?.[field]?.trim();
+      if (output) line(process.stdout, output);
+    }
+  }
+  if (result.guidance) line(process.stdout, result.guidance);
+  line(process.stdout, `${command}: ${result.status}`);
+}
+
+async function hookInput() {
+  if (process.stdin.isTTY) fail('CODEX_HOOK_INPUT_INVALID', 'Codex hook input must be supplied on stdin.');
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 1024 * 1024) fail('CODEX_HOOK_INPUT_INVALID', 'Codex hook input exceeds 1 MiB.');
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch (error) {
+    fail('CODEX_HOOK_INPUT_INVALID', `Codex hook input is invalid JSON: ${error.message}.`);
+  }
+}
+
+async function execute({ command, operands, options }) {
+  const projectRoot = options.projectRoot || process.cwd();
+  if (command === 'init') return initialize({ projectRoot });
+  if (command === 'adopt') {
+    return adoptProject({ projectRoot, request: operands.join(' ') });
+  }
+  if (command === 'codex') return installCodex();
+  if (command === 'stack') {
+    if (operands[0] === 'list') return { status: 'ok', pieces: await listStackPieces() };
+    return addStack({ pieces: operands.slice(1), projectRoot });
+  }
+  if (command === 'prompt') {
+    return generatePrompt({
+      projectRoot,
+      task: options.task || 'work',
+      request: operands.join(' '),
+    });
+  }
+  if (command === 'context') return getContext({ paths: operands, projectRoot });
+  if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'hook') {
+    if (operands[0] === 'discover') {
+      return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
+    }
+    if (operands[0] === 'session') {
+      return { kind: 'session', ...await codexSessionContext({ projectRoot }) };
+    }
+    const input = await hookInput();
+    if (operands[0] === 'begin') {
+      return { kind: 'begin', ...await recordCodexTurn({ input, projectRoot }) };
+    }
+    if (operands[0] === 'end') {
+      return { kind: 'end', ...await discardCodexTurn({ input, projectRoot }) };
+    }
+    return { kind: 'stop', status: 'ready', output: await completeCodexTurn({ input, projectRoot }) };
+  }
+  if (command === 'verify') {
+    return verify({
+      projectRoot,
+      onEvent: (event) => {
+        if (!options.json) line(process.stderr, event.message);
+      },
+    });
+  }
+  if (command === 'check') return check({ projectRoot });
+  fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let options = {};
+  try {
+    const parsed = parseCommand(argv);
+    if (parsed.command === 'help') {
+      process.stdout.write(USAGE);
+      return 0;
+    }
+    options = parsed.options;
+    const result = await execute(parsed);
+    if (options.json) line(process.stdout, JSON.stringify(result));
+    else writeResult(parsed.command, result);
+    return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;
+  } catch (error) {
+    const diagnostic = asDiagnostic(error);
+    if (options.json) line(process.stderr, JSON.stringify(diagnostic));
+    else line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
+    return 1;
+  }
+}

package/src/index/agent-skills.js

@@ -0,0 +1,425 @@
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import {
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+import { GenesisError } from './errors.js';
+import { sha256, stableJson, writeFileAtomic } from './utils.js';
+
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+const require = createRequire(import.meta.url);
+const SKILLS_ROOT = '.agents/skills';
+const MANIFEST_PATH = `${SKILLS_ROOT}/.genesis-managed.json`;
+const MANIFEST_VERSION = 1;
+const HASH = /^sha256:[0-9a-f]{64}$/u;
+const SKILL_FIELDS = new Set([
+  'name',
+  'description',
+  'license',
+  'compatibility',
+  'metadata',
+  'allowed-tools',
+]);
+
+const CORE_SKILLS = [
+  'genesis-project',
+  'genesis-program',
+  'genesis-deslop',
+].map((name) => ({
+  component: null,
+  package: null,
+  path: `skills/${name}`,
+  source: `genesis:skills/${name}`,
+}));
+
+function invalidSkill(message, details = {}) {
+  throw new GenesisError('AGENT_SKILL_INVALID', message, details);
+}
+
+function validSkillName(value) {
+  if (typeof value !== 'string') return false;
+  const name = value.normalize('NFKC');
+  return name.length > 0
+    && name.length <= 64
+    && name === name.toLowerCase()
+    && !name.startsWith('-')
+    && !name.endsWith('-')
+    && !name.includes('--')
+    && [...name].every((character) => character === '-' || /[\p{L}\p{N}]/u.test(character));
+}
+
+function frontmatter(source, location) {
+  const normalized = source.replace(/\r\n?/gu, '\n');
+  if (!normalized.startsWith('---\n')) invalidSkill(`Agent Skill is missing YAML frontmatter: ${location}.`);
+  const end = normalized.indexOf('\n---\n', 4);
+  if (end === -1) invalidSkill(`Agent Skill frontmatter is not closed: ${location}.`);
+  let metadata;
+  try {
+    metadata = parseYaml(normalized.slice(4, end));
+  } catch (error) {
+    invalidSkill(`Agent Skill frontmatter is invalid YAML: ${location}.`, { cause: error.message });
+  }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    invalidSkill(`Agent Skill frontmatter must be a mapping: ${location}.`);
+  }
+  return metadata;
+}
+
+async function skillTree(directory, relative = '') {
+  const entries = await readdir(path.join(directory, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) invalidSkill(`Agent Skill contains a symbolic link: ${child}.`);
+    if (entry.isDirectory()) {
+      files.push(...await skillTree(directory, child));
+      continue;
+    }
+    if (!entry.isFile()) invalidSkill(`Agent Skill contains a non-file entry: ${child}.`);
+    const location = path.join(directory, child);
+    const [content, info] = await Promise.all([readFile(location), lstat(location)]);
+    files.push({
+      path: child,
+      hash: sha256(content),
+      mode: (info.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+    });
+  }
+  return files;
+}
+
+async function describeSkill(directory, source) {
+  let info;
+  try { info = await lstat(directory); } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return null;
+    throw error;
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    invalidSkill(`Agent Skill must be an ordinary directory: ${directory}.`);
+  }
+  const skillFile = path.join(directory, 'SKILL.md');
+  let skillSource;
+  try { skillSource = await readFile(skillFile, 'utf8'); } catch (error) {
+    invalidSkill(`Agent Skill is missing SKILL.md: ${directory}.`, { cause: error.code || error.message });
+  }
+  const metadata = frontmatter(skillSource, skillFile);
+  const unexpected = Object.keys(metadata).filter((field) => !SKILL_FIELDS.has(field));
+  if (unexpected.length > 0) {
+    invalidSkill(`Agent Skill frontmatter contains unsupported fields: ${unexpected.sort().join(', ')}.`);
+  }
+  const { name } = metadata;
+  const description = typeof metadata.description === 'string' ? metadata.description.trim() : '';
+  if (
+    !validSkillName(name)
+    || name.normalize('NFKC') !== path.basename(directory).normalize('NFKC')
+  ) invalidSkill(`Agent Skill name must match its directory and use the standard lowercase format: ${directory}.`);
+  if (!description || description.length > 1024) {
+    invalidSkill(`Agent Skill description must contain 1-1024 characters: ${skillFile}.`);
+  }
+  if (
+    metadata.compatibility !== undefined
+    && (typeof metadata.compatibility !== 'string' || metadata.compatibility.length > 500)
+  ) invalidSkill(`Agent Skill compatibility must be a string of at most 500 characters: ${skillFile}.`);
+  if (metadata.license !== undefined && typeof metadata.license !== 'string') {
+    invalidSkill(`Agent Skill license must be a string: ${skillFile}.`);
+  }
+  if (metadata['allowed-tools'] !== undefined && typeof metadata['allowed-tools'] !== 'string') {
+    invalidSkill(`Agent Skill allowed-tools must be a string: ${skillFile}.`);
+  }
+  if (
+    metadata.metadata !== undefined
+    && (
+      !metadata.metadata
+      || typeof metadata.metadata !== 'object'
+      || Array.isArray(metadata.metadata)
+      || Object.values(metadata.metadata).some((value) => typeof value !== 'string')
+    )
+  ) invalidSkill(`Agent Skill metadata must map strings to strings: ${skillFile}.`);
+  const files = await skillTree(directory);
+  return {
+    name,
+    description,
+    directory,
+    source,
+    files,
+    hash: sha256(stableJson(files)),
+  };
+}
+
+async function packageDirectory(packageName) {
+  for (const modulesRoot of require.resolve.paths(packageName) || []) {
+    const manifest = path.join(modulesRoot, packageName, 'package.json');
+    try {
+      const value = JSON.parse(await readFile(manifest, 'utf8'));
+      if (value?.name === packageName) return path.dirname(manifest);
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+        throw new GenesisError(
+          'AGENT_SKILL_UNAVAILABLE',
+          `Cannot read selected Agent Skill package ${packageName}: ${error.message}.`,
+          { package: packageName },
+        );
+      }
+    }
+  }
+  throw new GenesisError(
+    'AGENT_SKILL_UNAVAILABLE',
+    `Selected Agent Skill package is unavailable: ${packageName}.`,
+    { package: packageName },
+  );
+}
+
+async function resolveLocator(locator) {
+  const root = locator.package ? await packageDirectory(locator.package) : packageRoot;
+  const directory = path.join(root, locator.path);
+  const source = locator.source || (
+    locator.package
+      ? `npm:${locator.package}/${locator.path}`
+      : `genesis:${locator.path}`
+  );
+  const skill = await describeSkill(directory, source);
+  if (!skill) invalidSkill(`Selected Agent Skill is unavailable: ${directory}.`);
+  return { ...skill, component: locator.component };
+}
+
+/** Resolves the three Genesis workflow skills plus authoritative selected Stack skills. */
+export async function projectSkillPlan(stack) {
+  const locators = [
+    ...CORE_SKILLS,
+    ...(stack?.components || []).flatMap((component) => (
+      component.skill ? [{ ...component.skill, component: component.id }] : []
+    )),
+  ];
+  const resolved = await Promise.all(locators.map(resolveLocator));
+  const skills = new Map();
+  for (const skill of resolved) {
+    const previous = skills.get(skill.name);
+    if (previous && previous.hash !== skill.hash) {
+      throw new GenesisError(
+        'AGENT_SKILL_COLLISION',
+        `Selected Stack sources provide different Agent Skills named ${skill.name}.`,
+        { name: skill.name, sources: [previous.source, skill.source] },
+      );
+    }
+    if (!previous) skills.set(skill.name, skill);
+  }
+  return [...skills.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function readManifest(projectRoot) {
+  const location = path.join(projectRoot, MANIFEST_PATH);
+  let value;
+  try { value = JSON.parse(await readFile(location, 'utf8')); } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      return { location, value: { schemaVersion: MANIFEST_VERSION, skills: {} } };
+    }
+    throw new GenesisError('AGENT_SKILLS_MANIFEST_INVALID', `${MANIFEST_PATH} is invalid: ${error.message}.`);
+  }
+  const valid = value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && value.schemaVersion === MANIFEST_VERSION
+    && value.skills
+    && typeof value.skills === 'object'
+    && !Array.isArray(value.skills)
+    && Object.entries(value.skills).every(([name, record]) => (
+      validSkillName(name)
+      && record
+      && typeof record === 'object'
+      && Object.keys(record).sort().join(',') === 'hash,source'
+      && HASH.test(record.hash)
+      && typeof record.source === 'string'
+      && record.source.length > 0
+    ));
+  if (!valid) throw new GenesisError('AGENT_SKILLS_MANIFEST_INVALID', `${MANIFEST_PATH} has an invalid shape.`);
+  return { location, value };
+}
+
+async function replaceSkill(source, target) {
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  const backup = `${target}.${randomUUID()}.backup`;
+  await mkdir(path.dirname(target), { recursive: true });
+  let replaced = false;
+  try {
+    await cp(source, temporary, { recursive: true, errorOnExist: true });
+    try {
+      await rename(target, backup);
+      replaced = true;
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    }
+    await rename(temporary, target);
+  } catch (error) {
+    if (replaced) {
+      await rm(target, { recursive: true, force: true }).catch(() => {});
+      await rename(backup, target).catch(() => {});
+    }
+    throw error;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+    await rm(backup, { recursive: true, force: true });
+  }
+}
+
+function targetFiles(skill) {
+  return skill.files.map(({ path: file }) => `${SKILLS_ROOT}/${skill.name}/${file}`);
+}
+
+/** Installs only Genesis-owned or authoritative Stack-declared skills. */
+export async function syncProjectSkills({ projectRoot, stack } = {}) {
+  const desired = await projectSkillPlan(stack);
+  const desiredNames = new Set(desired.map(({ name }) => name));
+  const manifest = await readManifest(projectRoot);
+  const changedFiles = [];
+  const diagnostics = [];
+
+  for (const skill of desired) {
+    const target = path.join(projectRoot, SKILLS_ROOT, skill.name);
+    const installed = await describeSkill(target, `project:${skill.name}`);
+    const managed = Object.hasOwn(manifest.value.skills, skill.name)
+      ? manifest.value.skills[skill.name]
+      : null;
+    if (!installed) {
+      await replaceSkill(skill.directory, target);
+      manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+      changedFiles.push(...targetFiles(skill));
+      continue;
+    }
+    if (!managed) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_EXTERNAL',
+        message: `Preserved existing project Agent Skill ${skill.name}; Genesis does not own it.`,
+        details: { name: skill.name, path: `${SKILLS_ROOT}/${skill.name}/SKILL.md` },
+      });
+      continue;
+    }
+    if (installed.hash !== managed.hash) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_CUSTOMIZED',
+        message: `Preserved locally modified Agent Skill ${skill.name}.`,
+        details: { name: skill.name, path: `${SKILLS_ROOT}/${skill.name}/SKILL.md` },
+      });
+      continue;
+    }
+    if (installed.hash !== skill.hash || managed.source !== skill.source) {
+      await replaceSkill(skill.directory, target);
+      manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+      changedFiles.push(...new Set([...targetFiles(installed), ...targetFiles(skill)]));
+    }
+  }
+
+  for (const [name, record] of Object.entries(manifest.value.skills)) {
+    if (desiredNames.has(name)) continue;
+    const target = path.join(projectRoot, SKILLS_ROOT, name);
+    const installed = await describeSkill(target, `project:${name}`);
+    if (installed?.hash === record.hash) {
+      await rm(target, { recursive: true, force: true });
+      changedFiles.push(...targetFiles(installed));
+    } else if (installed) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_PRESERVED',
+        message: `Preserved modified deselected Agent Skill ${name} and released Genesis ownership.`,
+        details: { name, path: `${SKILLS_ROOT}/${name}/SKILL.md` },
+      });
+    }
+    delete manifest.value.skills[name];
+  }
+
+  const rendered = stableJson(manifest.value);
+  let previous = null;
+  try { previous = await readFile(manifest.location, 'utf8'); } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+  }
+  if (rendered !== previous) {
+    await writeFileAtomic(manifest.location, rendered);
+    changedFiles.push(MANIFEST_PATH);
+  }
+  return {
+    status: changedFiles.length > 0 ? 'updated' : 'unchanged',
+    changedFiles: [...new Set(changedFiles)].sort(),
+    diagnostics,
+    skills: desired.map(({ name }) => name),
+  };
+}
+
+/** Inspects the exact project copies without changing them. */
+export async function inspectProjectSkills({ projectRoot, stack } = {}) {
+  const desired = await projectSkillPlan(stack);
+  const manifest = await readManifest(projectRoot);
+  const diagnostics = [];
+  const skills = [];
+  let customized = false;
+  let invalid = false;
+  let missing = false;
+  for (const expected of desired) {
+    const target = path.join(projectRoot, SKILLS_ROOT, expected.name);
+    let installed;
+    try { installed = await describeSkill(target, `project:${expected.name}`); } catch (error) {
+      invalid = true;
+      diagnostics.push({ code: error.code || 'AGENT_SKILL_INVALID', message: error.message });
+      continue;
+    }
+    if (!installed) {
+      missing = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_MISSING',
+        message: `Project Agent Skill is missing: ${SKILLS_ROOT}/${expected.name}/SKILL.md.`,
+        details: { name: expected.name },
+      });
+      continue;
+    }
+    const managed = Object.hasOwn(manifest.value.skills, expected.name)
+      ? manifest.value.skills[expected.name]
+      : null;
+    if (!managed) {
+      customized = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_EXTERNAL',
+        message: `Project Agent Skill ${expected.name} is externally managed; Genesis preserved it.`,
+        details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
+      });
+    } else if (installed.hash !== managed.hash) {
+      customized = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_CUSTOMIZED',
+        message: `Project Agent Skill ${expected.name} differs from its Genesis-managed source.`,
+        details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
+      });
+    }
+    skills.push({
+      name: installed.name,
+      description: installed.description,
+      path: `${SKILLS_ROOT}/${installed.name}/SKILL.md`,
+      component: expected.component,
+    });
+  }
+  return {
+    status: invalid ? 'invalid' : missing ? 'missing' : customized ? 'customized' : 'current',
+    diagnostics,
+    skills,
+  };
+}
+
+export function renderAgentSkillCatalog(skills) {
+  if (!skills.length) return '';
+  return [
+    'The following Agent Skills are available for progressive loading. Read a matching',
+    '`SKILL.md` completely before acting, and resolve its relative references from the',
+    'skill directory. Load scripts, references, and assets only when needed.',
+    '',
+    ...skills.flatMap(({ name, description, path: skillPath }) => [
+      `- \`${name}\` — ${description}`,
+      `  Path: \`${skillPath}\``,
+    ]),
+  ].join('\n');
+}