genesis-compiler 1.4.1 → 1.5.0

package/README.md

@@ -213,8 +213,23 @@ skill.
 
 `.agents/skills/.genesis-managed.json` records only copies Genesis owns.
 Genesis never overwrites an unmanaged skill and preserves locally modified
-managed skills. Run `genesis init` after manually editing `genesis/stack.md`,
-or use `genesis stack add`, to synchronize selected skills.
+managed skills. `genesis check` and `genesis inspect skills` distinguish outdated
+managed copies from local customizations. After updating Genesis or a selected
+skill package, run `genesis skills sync` to refresh only those skill directories
+and their ownership manifest. Repeating it makes no changes. It does not install
+packages, initialize project files, migrate contracts, rebuild indexes, or run
+verification.
+
+Projects that declare `genesis-compiler` use the skills from that installed
+project dependency, including when a host embeds a different compiler. An
+unprepared declared dependency is reported instead of substituting the host's
+version. Other projects use the running compiler's packaged skills. Package
+upgrades remain explicit dependency changes.
+
+Inspection, context generation, and session hooks remain read-only and report
+skill maintenance diagnostics. An assistant that already loaded old skills
+needs its supported context refresh before using their replacement; changing
+files alone does not refresh its existing context.
 
 ## Commands at a glance
 
@@ -228,9 +243,11 @@ or use `genesis stack add`, to synchronize selected skills.
 | `genesis engineering set <profile>` | Records the selected engineering profile while preserving project-specific requirements. |
 | `genesis stack list` | Lists technology components from the installed Stack catalog. |
 | `genesis stack add <piece...>` | Resolves component dependencies/conflicts, records the selection, materializes missing project contracts, synchronizes declared skills, and prints the one-time preparation prompt. It does not install application packages or run an agent. |
+| `genesis skills sync` | Refreshes selected, unmodified managed skills while preserving customized and unmanaged copies. |
 | `genesis context <path...>` | Returns path-focused Program explanations, indexed functions, selected technology guidance, exact project contracts, and relevant skills. |
 | `genesis index [function-or-path...]` | Regenerates the derived code indexes and optionally searches the existing function/method inventory. |
 | `genesis inspect environment` | Reports declared resources, public defaults, missing input names, and environment-file paths without returning secret values. |
+| `genesis inspect skills` | Reports selected skill freshness and ownership without changing files. |
 | `genesis inspect section <name>` | Returns one exact consumer-owned Stack section without interpreting or executing it. |
 | `genesis prompt [request...]` | Generates the ordinary implementation prompt. Use `--task` for opening, adoption, Deslop, explanation, review, and other explicit prompt tasks. |
 | `genesis verify` | Executes only the ordered finite commands in `## Verification` and records exact evidence. |
@@ -875,6 +892,7 @@ import {
   inspectCollaboration,
   inspectEngineering,
   inspectEnvironment,
+  inspectSkills,
   inspectStackSection,
   installCodex,
   listEngineeringProfiles,
@@ -884,6 +902,7 @@ import {
   projectTurnContext,
   setCollaboration,
   setEngineeringProfile,
+  syncSkills,
   verify,
   withTrustedGitRepository,
 } from 'genesis-compiler';
@@ -900,6 +919,12 @@ codebase. `installCodex()` installs the optional global discovery plugin.
 project selection used by the CLI and hosts.
 `inspectCollaboration()` and `setCollaboration()` expose the portable
 communication declaration and Genesis-owned choice expansions.
+`inspectSkills()` and `syncSkills()` expose the same inspection and narrow
+synchronization used by the CLI. Both accept `projectRoot` and `stackPackages`.
+Inspection returns aggregate status, per-skill status for valid installed copies,
+and diagnostics for missing, invalid, outdated, customized, or unmanaged skills.
+Synchronization returns changed paths, preservation diagnostics, and the resulting
+`inspection`. Hosts own source-write exclusion and assistant context lifecycle.
 `projectSessionContext()` composes stable project guidance with one explicitly
 supplied host-driver result. `projectTurnContext()` invokes that same optional
 driver for the separate untrusted turn lane without accepting user-message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   inspectEnvironment,
   inspectStackSection,
   inspectProject,
+  inspectSkills,
   installCodex,
   listEngineeringProfiles,
   listStackPieces,
@@ -22,6 +23,7 @@ import {
   migrate,
   setCollaboration,
   setEngineeringProfile,
+  syncSkills,
   verify,
 } from './index.js';
 import {
@@ -54,6 +56,7 @@ const USAGE = `Usage:
   genesis engineering set <profile>
   genesis stack list
   genesis stack add <piece...>
+  genesis skills sync
   genesis templates list
   genesis templates apply <catalogue:technology/variant>
   genesis context <path...>
@@ -61,6 +64,7 @@ const USAGE = `Usage:
   genesis migrate
   genesis inspect environment
   genesis inspect project
+  genesis inspect skills
   genesis inspect section <name>
   genesis prompt [request...]
   genesis prompt --task <start|adopt|work|deslop|program|blueprint|describe|review> [request...]
@@ -80,7 +84,7 @@ 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', 'collaboration', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'migrate', 'prompt', 'stack', 'templates', 'verify']);
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'collaboration', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'migrate', 'prompt', 'skills', 'stack', 'templates', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -167,6 +171,10 @@ function parseCommand(argv) {
     if (action === 'set' && operands.length !== 2) {
       fail('CLI_ENGINEERING_PROFILE_REQUIRED', 'Command engineering set requires exactly one profile.');
     }
+  } else if (command === 'skills') {
+    if (operands.length !== 1 || operands[0] !== 'sync') {
+      fail('CLI_SKILLS_ACTION_REQUIRED', 'Command skills requires exactly: sync.');
+    }
   } else if (command === 'codex') {
     if (operands.length !== 1 || operands[0] !== 'install') {
       fail('CLI_CODEX_ACTION_REQUIRED', 'Command codex requires exactly: install.');
@@ -174,12 +182,12 @@ function parseCommand(argv) {
   } else if (command === 'context' && operands.length === 0) {
     fail('CONTEXT_PATH_REQUIRED', 'Command context requires at least one project path.');
   } else if (command === 'inspect') {
-    const ordinaryInspection = operands.length === 1 && ['environment', 'project'].includes(operands[0]);
+    const ordinaryInspection = operands.length === 1 && ['environment', 'project', 'skills'].includes(operands[0]);
     const sectionInspection = operands.length >= 2 && operands[0] === 'section';
     if (!ordinaryInspection && !sectionInspection) {
       fail(
         'CLI_INSPECT_TARGET_REQUIRED',
-        'Command inspect requires project, environment, or section <name>.',
+        'Command inspect requires project, environment, skills, or section <name>.',
       );
     }
   } else if (command === 'hook' && (operands.length !== 1 || !['discover', 'session', 'turn'].includes(operands[0]))) {
@@ -278,6 +286,12 @@ function writeInspection(result) {
 }
 
 function writeResult(command, result) {
+  if (command === 'inspect' && result.inspection === 'skills') {
+    line(process.stdout, `Agent Skills: ${result.status}`);
+    for (const skill of result.skills) line(process.stdout, `  - ${skill.name}: ${skill.status}`);
+    for (const diagnostic of result.diagnostics) line(process.stdout, `${diagnostic.code}: ${diagnostic.message}`);
+    return;
+  }
   if (command === 'templates') {
     if (result.templates) for (const entry of result.templates) line(process.stdout, `${entry.id}: ${entry.name} — ${entry.description}`);
     else {
@@ -419,6 +433,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
     return operands[0] === 'list' ? listTemplates(templateOptions) : applyTemplate({ ...templateOptions, templateId: operands[1] });
   }
   if (command === 'migrate') return migrate({ projectRoot, stackPackages });
+  if (command === 'skills') return syncSkills({ projectRoot, stackPackages });
   if (command === 'adopt') {
     return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
   }
@@ -496,7 +511,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
         }),
       };
     }
-    const inspections = { environment: inspectEnvironment, project: inspectProject };
+    const inspections = { environment: inspectEnvironment, project: inspectProject, skills: inspectSkills };
     return {
       inspection: operands[0],
       ...await inspections[operands[0]]({ projectRoot, stackPackages }),
@@ -611,7 +626,12 @@ export async function runCli(argv = process.argv.slice(2)) {
       formatDiagnostic,
     );
     if (options.json) line(process.stdout, JSON.stringify(result));
-    else writeResult(parsed.command, result);
+    else {
+      writeResult(parsed.command, result);
+      for (const warning of result.warnings || []) {
+        if (warning.code !== formatDiagnostic?.code) line(process.stderr, `WARNING: ${warning.code}: ${warning.message}`);
+      }
+    }
     return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;
   } catch (error) {
     const diagnostic = asDiagnostic(error);

package/src/index/agent-skills.js

@@ -242,12 +242,12 @@ async function describeSkill(directory, source) {
   };
 }
 
-async function packageDirectory(packageName, resolveFrom = null) {
+async function packageDirectory(packageName, resolveFrom = null, { projectOnly = false } = {}) {
   const roots = [
     ...(resolveFrom
       ? createRequire(path.join(resolveFrom, 'package.json')).resolve.paths(packageName) || []
       : []),
-    ...(require.resolve.paths(packageName) || []),
+    ...(projectOnly ? [] : require.resolve.paths(packageName) || []),
   ];
   for (const modulesRoot of [...new Set(roots)]) {
     const manifest = path.join(modulesRoot, packageName, 'package.json');
@@ -274,7 +274,7 @@ async function packageDirectory(packageName, resolveFrom = null) {
 async function resolveLocator(locator) {
   const root = locator.package
     ? await packageDirectory(locator.package, locator.resolveFrom)
-    : packageRoot;
+    : locator.root || packageRoot;
   const directory = path.join(root, locator.path);
   const source = locator.source || (
     locator.package
@@ -287,9 +287,23 @@ async function resolveLocator(locator) {
 }
 
 /** Resolves the three Genesis workflow skills plus authoritative selected Stack skills. */
-export async function projectSkillPlan(stack) {
+export async function projectSkillPlan(stack, { projectRoot } = {}) {
+  let coreRoot = packageRoot;
+  if (projectRoot) {
+    let manifest;
+    try { manifest = JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')); } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    }
+    if (manifest?.name === 'genesis-compiler') {
+      coreRoot = projectRoot;
+    } else if (['dependencies', 'devDependencies', 'optionalDependencies'].some((field) => (
+      Object.hasOwn(manifest?.[field] || {}, 'genesis-compiler')
+    ))) {
+      coreRoot = await packageDirectory('genesis-compiler', projectRoot, { projectOnly: true });
+    }
+  }
   const locators = [
-    ...CORE_SKILLS,
+    ...CORE_SKILLS.map((skill) => ({ ...skill, root: coreRoot })),
     ...(stack?.components || []).flatMap((component) => (
       component.skill ? [{ ...component.skill, component: component.id }] : []
     )),
@@ -386,9 +400,19 @@ function targetFiles(skill) {
   return skill.files.map(({ path: file }) => `${SKILLS_ROOT}/${skill.name}/${file}`);
 }
 
+function skillStatus(installed, managed, expected) {
+  if (!installed) return 'missing';
+  if (!managed) return 'unmanaged';
+  if (installed.hash !== managed.hash && installed.hash !== expected.hash) return 'customized';
+  if (installed.hash !== expected.hash || managed.hash !== expected.hash || managed.source !== expected.source) {
+    return 'outdated';
+  }
+  return 'current';
+}
+
 /** Installs only Genesis-owned or authoritative Stack-declared skills. */
 export async function syncProjectSkills({ projectRoot, stack } = {}) {
-  const desired = await projectSkillPlan(stack);
+  const desired = await projectSkillPlan(stack, { projectRoot });
   const desiredNames = new Set(desired.map(({ name }) => name));
   const manifest = await readManifest(projectRoot);
   const changedFiles = [];
@@ -400,13 +424,14 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
     const managed = Object.hasOwn(manifest.value.skills, skill.name)
       ? manifest.value.skills[skill.name]
       : null;
-    if (!installed) {
+    const status = skillStatus(installed, managed, skill);
+    if (status === 'missing') {
       await replaceSkill(skill.directory, target);
       manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
       changedFiles.push(...targetFiles(skill));
       continue;
     }
-    if (!managed) {
+    if (status === 'unmanaged') {
       diagnostics.push({
         code: 'AGENT_SKILL_EXTERNAL',
         message: `Preserved existing project Agent Skill ${skill.name}; Genesis does not own it.`,
@@ -414,11 +439,7 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
       });
       continue;
     }
-    if (installed.hash !== managed.hash) {
-      if (installed.hash === skill.hash) {
-        manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
-        continue;
-      }
+    if (status === 'customized') {
       diagnostics.push({
         code: 'AGENT_SKILL_CUSTOMIZED',
         message: `Preserved locally modified Agent Skill ${skill.name}.`,
@@ -426,10 +447,12 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
       });
       continue;
     }
-    if (installed.hash !== skill.hash || managed.source !== skill.source) {
-      await replaceSkill(skill.directory, target);
+    if (status === 'outdated') {
+      if (installed.hash !== skill.hash) {
+        await replaceSkill(skill.directory, target);
+        changedFiles.push(...targetFiles(installed), ...targetFiles(skill));
+      }
       manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
-      changedFiles.push(...new Set([...targetFiles(installed), ...targetFiles(skill)]));
     }
   }
 
@@ -469,13 +492,14 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
 
 /** Inspects the exact project copies without changing them. */
 export async function inspectProjectSkills({ projectRoot, stack } = {}) {
-  const desired = await projectSkillPlan(stack);
+  const desired = await projectSkillPlan(stack, { projectRoot });
   const manifest = await readManifest(projectRoot);
   const diagnostics = [];
   const skills = [];
   let customized = false;
   let invalid = false;
   let missing = false;
+  let outdated = false;
   for (const expected of desired) {
     const target = path.join(projectRoot, SKILLS_ROOT, expected.name);
     let installed;
@@ -488,7 +512,7 @@ export async function inspectProjectSkills({ projectRoot, stack } = {}) {
       missing = true;
       diagnostics.push({
         code: 'AGENT_SKILL_MISSING',
-        message: `Project Agent Skill is missing: ${SKILLS_ROOT}/${expected.name}/SKILL.md.`,
+        message: `Project Agent Skill is missing: ${SKILLS_ROOT}/${expected.name}/SKILL.md. Run \`genesis skills sync\` to install selected skills.`,
         details: { name: expected.name },
       });
       continue;
@@ -496,30 +520,39 @@ export async function inspectProjectSkills({ projectRoot, stack } = {}) {
     const managed = Object.hasOwn(manifest.value.skills, expected.name)
       ? manifest.value.skills[expected.name]
       : null;
-    if (!managed) {
+    const status = skillStatus(installed, managed, expected);
+    if (status === 'unmanaged') {
       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 && installed.hash !== expected.hash) {
+    } else if (status === 'customized') {
       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` },
       });
+    } else if (status === 'outdated') {
+      outdated = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_OUTDATED',
+        message: `Project Agent Skill ${expected.name} is outdated relative to the installed source. Run \`genesis skills sync\` to update unmodified managed skills.`,
+        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,
+      status,
     });
   }
   return {
-    status: invalid ? 'invalid' : missing ? 'missing' : customized ? 'customized' : 'current',
+    status: invalid ? 'invalid' : missing ? 'missing' : outdated ? 'outdated' : customized ? 'customized' : 'current',
     diagnostics,
     skills,
   };

package/src/index/check.js

@@ -140,7 +140,7 @@ export async function checkProject({
   if (program.status === 'missing') guidance.push('Generate an explanatory Program prompt with genesis prompt --task program.');
   if (engineering.status === 'defaulted') guidance.push('Run genesis init or genesis engineering set focused.v1 to record the default engineering approach.');
   if (program.status === 'invalid') guidance.push('Repair the Program with genesis prompt --task program.');
-  if (skills.status === 'missing') guidance.push('Run genesis init to install selected project Agent Skills.');
+  if (['missing', 'outdated'].includes(skills.status)) guidance.push('Run genesis skills sync to refresh selected project Agent Skills.');
   if (skills.status === 'invalid') guidance.push('Repair the reported Agent Skill or managed-skill manifest.');
   if (missingResources.length > 0) {
     guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
@@ -152,7 +152,7 @@ export async function checkProject({
 
   const needsAttention = program.status === 'missing'
     || engineering.status === 'defaulted'
-    || skills.status === 'missing'
+    || ['missing', 'outdated'].includes(skills.status)
     || missingResources.length > 0
     || extensionDiagnostics.length > 0
     || ['missing', 'stale', 'unconfigured'].includes(verification.status);

package/src/index/session-context.js

@@ -1,7 +1,8 @@
 import { readCollaboration } from './collaboration.js';
+import { inspectProjectSkills } from './agent-skills.js';
 import { GENESIS_CONTRACTS } from './contracts.js';
 import { readEngineering, readEngineeringBaseline } from './engineering.js';
-import { GenesisError } from './errors.js';
+import { asDiagnostic, GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { inspectProject } from './project-inspection.js';
 import { readStack } from './stack.js';
@@ -118,6 +119,11 @@ export async function projectSessionContext({
     inspectProject({ projectRoot: root, stackPackages }),
   ]);
   const availableComponents = await optionalStackComponentIds(root, stack, stackPackages);
+  const skills = stack && inspection.projectFormat.status === 'current'
+    ? await inspectProjectSkills({ projectRoot: root, stack }).catch((error) => ({
+        diagnostics: [asDiagnostic(error)],
+      }))
+    : { diagnostics: [] };
   const selected = stack?.components.map(({ id }) => id) || [];
   const stackStatus = stack
     ? (selected.length > 0 ? selected.join(', ') : 'none')
@@ -140,6 +146,8 @@ export async function projectSessionContext({
     '- When the user names an unselected technology that exactly matches this catalog, run `genesis stack list`, ask whether to add and prepare it, and wait for confirmation. If confirmed, run `genesis stack add <piece...>` and follow its returned preparation prompt in the same task; then use `genesis context` and any installed technology skill. Never infer dependency commands from a component id. If declined or unmatched, continue through authoritative technology documentation without inventing a component.',
     '- Project-owned operation sections in `genesis/stack.md` are the durable application contract. Make the implementation satisfy them or update a complete section to match evidenced reality; Genesis executes only Verification.',
     '- Use the relevant project Agent Skills below `.agents/skills/`.',
+    ...skills.diagnostics.map(({ message }) => `- Agent Skill maintenance: ${message}`),
+    ...(skills.diagnostics.length > 0 ? ['- Skill inspection is read-only. Synchronization is an explicit source change; follow the current task authorization and host write boundary before running it.'] : []),
     '- After locating source, run `genesis context <path...>`; before adding a helper or public operation, run `genesis index <name-or-path...>` and reuse an existing owner.',
     '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
     '- Keep Blueprint and affected Program explanations aligned with intentional observable product behavior in the same implementation turn. Private restructuring may need only source citations or no explanatory change.',
@@ -158,7 +166,7 @@ export async function projectSessionContext({
     collaboration.guidance,
     ...(hostContext ? ['', 'HOST CONTEXT', '', hostContext] : []),
   ].join('\n');
-  return composedContext(GENESIS_CONTRACTS.sessionContext, output);
+  return { ...composedContext(GENESIS_CONTRACTS.sessionContext, output), warnings: skills.diagnostics };
 }
 
 export async function projectTurnContext({ hostDriver, hostDriverInput } = {}) {

package/src/index.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
 
 import { checkProject } from './index/check.js';
+import { inspectProjectSkills, syncProjectSkills } from './index/agent-skills.js';
+import { gitContext } from './index/git.js';
+import { inspectProjectFormatAtRoot, requireCurrentProjectFormat } from './index/project-format.js';
 import { buildProjectIndex, GENESIS_DERIVED_ARTIFACTS } from './index/code-index.js';
 import {
   inspectProjectCollaboration,
@@ -200,3 +203,23 @@ export function verify(options) {
 export function check(options) {
   return checkProject(options);
 }
+
+async function projectSkillContext({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  requireCurrentProjectFormat(await inspectProjectFormatAtRoot(root), { allowUninitialized: true });
+  return { projectRoot: root, stack: await readStack(root, { stackPackages }) };
+}
+
+export async function inspectSkills(options) {
+  return inspectProjectSkills(await projectSkillContext(options));
+}
+
+export async function syncSkills(options) {
+  const context = await projectSkillContext(options);
+  const result = await syncProjectSkills(context);
+  return {
+    ...result,
+    inspection: await inspectProjectSkills(context),
+    guidance: 'Review changed skills in the ordinary Git diff. An assistant that already loaded them needs its supported context refresh before using the new guidance.',
+  };
+}