@ikon85/agent-workflow-kit 0.34.6 → 0.36.0

package/src/lib/contributionBridge.mjs

@@ -0,0 +1,176 @@
+import {
+  lstat, readFile,
+} from 'node:fs/promises';
+import {
+  isAbsolute, join, normalize, resolve,
+} from 'node:path';
+import { lineDiff, writeAtomic } from './atomicWrite.mjs';
+import { validateConsumerFile } from './consumerPath.mjs';
+import { sha256File } from './hash.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, KIT_ORIGIN, PACKAGE_MANIFEST_NAME,
+  readManifest, writeManifest,
+} from './manifest.mjs';
+
+export const CONTRIBUTION_BRIDGE_SCHEMA_VERSION = 1;
+export const CONTRIBUTION_ARTIFACT_KIND = 'agent-workflow-kit/contribution';
+const HASH = /^[a-f0-9]{64}$/;
+const OUTPUT = /^\.agent-workflow-kit\/contributions\/[a-zA-Z0-9._-]+\.json$/;
+
+export function validateContributionBridge(entry) {
+  const bridge = entry?.contributionBridge;
+  if (entry?.origin !== CONSUMER_ORIGIN
+      || entry?.ownershipState !== 'contribution-bridge'
+      || !bridge
+      || bridge.schemaVersion !== CONTRIBUTION_BRIDGE_SCHEMA_VERSION
+      || typeof bridge.baseKitVersion !== 'string'
+      || !bridge.baseKitVersion
+      || !HASH.test(bridge.baseSha256 ?? '')
+      || !HASH.test(bridge.localSha256 ?? '')
+      || bridge.baseSha256 === bridge.localSha256
+      || entry.installedSha256 !== bridge.localSha256) {
+    throw new Error(`invalid contribution bridge metadata: ${entry?.path ?? 'unknown path'}`);
+  }
+  return bridge;
+}
+
+export async function beginContributionBridge({ kitRoot, consumerRoot, path }) {
+  const { pkg, manifest, desired, tracked } = await loadCoreIdentity({
+    kitRoot, consumerRoot, path,
+  });
+  if (tracked.origin !== KIT_ORIGIN || tracked.ownershipState !== undefined) {
+    throw new Error(`contribution bridge requires clean Kit ownership: ${path}`);
+  }
+  if (manifest.kitVersion !== pkg.kitVersion
+      || tracked.installedSha256 !== desired.sha256
+      || await sha256File(join(kitRoot, path)) !== desired.sha256) {
+    throw new Error(`stale upstream base for contribution bridge: ${path}`);
+  }
+  const localSha256 = await sha256File(await validateConsumerFile(consumerRoot, path));
+  if (localSha256 === desired.sha256) {
+    throw new Error(`contribution bridge has no local Core change: ${path}`);
+  }
+  const bridge = {
+    schemaVersion: CONTRIBUTION_BRIDGE_SCHEMA_VERSION,
+    baseKitVersion: pkg.kitVersion,
+    baseSha256: desired.sha256,
+    localSha256,
+  };
+  const next = {
+    ...manifest,
+    installed: manifest.installed.map((entry) => entry.path === path ? {
+      ...entry,
+      installedSha256: localSha256,
+      origin: CONSUMER_ORIGIN,
+      ownershipState: 'contribution-bridge',
+      contributionBridge: bridge,
+    } : entry),
+  };
+  await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), next);
+  return { path, state: 'contribution-bridge', bridge };
+}
+
+export async function prepareContributionArtifact({
+  kitRoot, consumerRoot, path, output,
+}) {
+  const { pkg, desired, tracked } = await loadCoreIdentity({
+    kitRoot, consumerRoot, path,
+  });
+  const bridge = validateContributionBridge(tracked);
+  if (pkg.kitVersion !== bridge.baseKitVersion
+      || desired.sha256 !== bridge.baseSha256
+      || await sha256File(join(kitRoot, path)) !== bridge.baseSha256) {
+    throw new Error(`stale upstream base for contribution bridge: ${path}`);
+  }
+  const localPath = await validateConsumerFile(consumerRoot, path);
+  if (await sha256File(localPath) !== bridge.localSha256) {
+    throw new Error(`contribution bridge changed after classification: ${path}`);
+  }
+  const base = await readFile(join(kitRoot, path));
+  const local = await readFile(localPath);
+  const baseText = strictUtf8(base, path);
+  const localText = strictUtf8(local, path);
+  const artifact = {
+    schemaVersion: CONTRIBUTION_BRIDGE_SCHEMA_VERSION,
+    kind: CONTRIBUTION_ARTIFACT_KIND,
+    coreIdentity: {
+      path,
+      baseKitVersion: bridge.baseKitVersion,
+      baseSha256: bridge.baseSha256,
+      localSha256: bridge.localSha256,
+    },
+    diff: {
+      format: 'line-diff-v1',
+      text: lineDiff(baseText, localText),
+    },
+  };
+  const destination = await validateArtifactOutput(consumerRoot, output);
+  const content = `${JSON.stringify(artifact, null, 2)}\n`;
+  try {
+    const existing = await readFile(destination, 'utf8');
+    if (existing !== content) {
+      throw new Error(`contribution artifact already exists with different content: ${output}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await writeAtomic(destination, content, 0o600);
+  }
+  return { output, artifact };
+}
+
+async function loadCoreIdentity({ kitRoot, consumerRoot, path }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  if (!manifest) throw new Error('not initialised — run `init` first');
+  const desired = pkg.files?.find((entry) => (
+    entry.path === path && (entry.installRole ?? 'consumer') === 'consumer'
+  ));
+  if (!desired || (desired.origin ?? KIT_ORIGIN) !== KIT_ORIGIN) {
+    throw new Error(`not declared Kit Core: ${path}`);
+  }
+  const tracked = manifest.installed?.find((entry) => entry.path === path);
+  if (!tracked) throw new Error(`not declared Kit Core in Consumer ledger: ${path}`);
+  return { pkg, manifest, desired, tracked };
+}
+
+function strictUtf8(bytes, path) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text).equals(bytes)) {
+    throw new Error(`binary Kit Core requires an Explicit fork: ${path}`);
+  }
+  return text;
+}
+
+async function validateArtifactOutput(consumerRoot, output) {
+  if (typeof output !== 'string'
+      || isAbsolute(output)
+      || normalize(output) !== output
+      || !OUTPUT.test(output)) {
+    throw new Error(`unsafe contribution artifact path: ${output}`);
+  }
+  const root = resolve(consumerRoot);
+  let current = root;
+  for (const segment of output.split('/').slice(0, -1)) {
+    current = join(current, segment);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new Error(`unsafe contribution artifact path: ${output}`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  const destination = join(root, output);
+  try {
+    const entry = await lstat(destination);
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+      throw new Error(`unsafe contribution artifact path: ${output}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return destination;
+}

package/src/lib/contributionRouting.mjs

@@ -0,0 +1,152 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { validateContributionBridge } from './contributionBridge.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, readManifest,
+} from './manifest.mjs';
+
+export const CONTRIBUTION_CAPABILITY_PATH = 'docs/agents/workflow-capabilities.json';
+export const CONTRIBUTION_ROUTING_SCHEMA_VERSION = 1;
+const SURFACES = new Set(['retro', 'pre-update', 'guard']);
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const REMOTE = /^[A-Za-z0-9._-]+$/;
+const execFile = promisify(execFileCallback);
+
+const GENERIC_ROUTES = Object.freeze([
+  Object.freeze({ id: 'preserve', remoteMutation: false }),
+  Object.freeze({ id: 'explicit-fork', remoteMutation: false }),
+]);
+
+export async function inspectContributionRouting({
+  consumerRoot, path, surface, resolveRemote = defaultResolveRemote(consumerRoot),
+}) {
+  if (!SURFACES.has(surface)) {
+    throw new Error(`unknown contribution routing surface: ${surface}`);
+  }
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const tracked = manifest?.installed?.find((entry) => entry.path === path);
+  const bridge = validateContributionBridge(tracked);
+  const lifecycle = {
+    surface,
+    path,
+    lifecycleState: 'contribution-bridge',
+    baseKitVersion: bridge.baseKitVersion,
+    routes: GENERIC_ROUTES.map((route) => ({ ...route })),
+  };
+  const loaded = await readCapability(consumerRoot);
+  if (loaded.state !== 'present') {
+    return {
+      ...lifecycle,
+      capabilityState: loaded.state,
+      ...(loaded.diagnostic ? { diagnostic: loaded.diagnostic } : {}),
+    };
+  }
+  const validated = validateCapability(loaded.value);
+  if (!validated.ok) {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: validated.diagnostic,
+    };
+  }
+  if (!validated.enabled) {
+    return { ...lifecycle, capabilityState: 'disabled' };
+  }
+  let remoteUrl;
+  try {
+    remoteUrl = await resolveRemote(validated.remote);
+  } catch {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: 'configured contribution remote is not verifiable',
+    };
+  }
+  if (repositoryFromRemote(remoteUrl) !== validated.repository.toLowerCase()) {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: 'configured contribution remote does not match required upstream',
+    };
+  }
+  return {
+    ...lifecycle,
+    capabilityState: 'ready',
+    repository: validated.repository,
+    routes: [
+      ...lifecycle.routes,
+      { id: 'prepare-local', remoteMutation: false },
+      {
+        id: 'upstream-pull-request',
+        remoteMutation: true,
+        requiresExplicitApproval: true,
+      },
+    ],
+  };
+}
+
+async function readCapability(consumerRoot) {
+  try {
+    const raw = await readFile(join(consumerRoot, CONTRIBUTION_CAPABILITY_PATH), 'utf8');
+    const profile = JSON.parse(raw);
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+      return { state: 'invalid', diagnostic: 'workflow capability profile must be an object' };
+    }
+    if (profile.contributionRouting === undefined) return { state: 'missing' };
+    return { state: 'present', value: profile.contributionRouting };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'missing' };
+    return { state: 'invalid', diagnostic: 'workflow capability profile is unreadable or invalid' };
+  }
+}
+
+function validateCapability(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return invalid('contribution routing capability must be an object');
+  }
+  if (value.schemaVersion !== CONTRIBUTION_ROUTING_SCHEMA_VERSION) {
+    return invalid('unsupported contribution routing capability schema');
+  }
+  if (typeof value.enabled !== 'boolean') {
+    return invalid('contribution routing enabled must be boolean');
+  }
+  if (!value.enabled) return { ok: true, enabled: false };
+  const repository = value.upstream?.repository;
+  const remote = value.upstream?.remote;
+  if (!REPOSITORY.test(repository ?? '') || !REMOTE.test(remote ?? '')) {
+    return invalid('contribution routing requires an explicit upstream repository and remote');
+  }
+  if (value.workflows?.prepareLocal !== true) {
+    return invalid('enabled contribution routing requires local preparation');
+  }
+  const pullRequest = value.workflows?.upstreamPullRequest;
+  if (pullRequest?.enabled !== true || pullRequest.requiresExplicitApproval !== true) {
+    return invalid('upstream pull request route requires explicit approval');
+  }
+  return { ok: true, enabled: true, repository, remote };
+}
+
+function invalid(diagnostic) {
+  return { ok: false, diagnostic };
+}
+
+function repositoryFromRemote(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/\.git$/, '');
+  const match = trimmed.match(
+    /^(?:git@github\.com:|https?:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([^/]+\/[^/]+)$/,
+  );
+  return match?.[1]?.toLowerCase() ?? null;
+}
+
+function defaultResolveRemote(consumerRoot) {
+  return async (remote) => {
+    const { stdout } = await execFile(
+      'git', ['-C', consumerRoot, 'remote', 'get-url', remote],
+      { timeout: 5000, maxBuffer: 64 * 1024 },
+    );
+    return stdout.trim();
+  };
+}

package/src/lib/manifest.mjs

@@ -18,6 +18,7 @@ export const KIT_ORIGIN = 'kit';
 export const CONSUMER_ORIGIN = 'consumer';
 export const READINESS_CONTRACT_VERSION = 1;
 export const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
+export { PROJECT_SKILL_REGISTRY_PATH } from './skillRegistry.mjs';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -94,7 +95,7 @@ export function indexByPath(manifest, key) {
 }
 
 /** Return a manifest with one tracked entry moved to the requested ownership state. */
-export function withOrigin(manifest, path, origin) {
+export function withOrigin(manifest, path, origin, ownershipState = 'explicit-fork') {
   if (![KIT_ORIGIN, CONSUMER_ORIGIN].includes(origin)) {
     throw new Error(`invalid manifest origin: ${origin}`);
   }
@@ -105,6 +106,20 @@ export function withOrigin(manifest, path, origin) {
   }
   return {
     ...manifest,
-    installed: manifest.installed.map((entry) => entry.path === path ? { ...entry, origin } : entry),
+    installed: manifest.installed.map((entry) => {
+      if (entry.path !== path) return entry;
+      if (origin === KIT_ORIGIN) {
+        const {
+          ownershipState: _removed,
+          contributionBridge: _removedBridge,
+          ...core
+        } = entry;
+        return { ...core, origin };
+      }
+      if (ownershipState !== 'explicit-fork') {
+        throw new Error(`invalid consumer ownership state: ${ownershipState}`);
+      }
+      return { ...entry, origin, ownershipState };
+    }),
   };
 }

package/src/lib/ownershipClassifier.mjs

@@ -0,0 +1,65 @@
+export const OwnershipState = Object.freeze({
+  CLEAN_CORE: 'clean-core',
+  PROJECT_EXTENSION: 'project-extension',
+  CONTRIBUTION_BRIDGE: 'contribution-bridge',
+  EXPLICIT_FORK: 'explicit-fork',
+  AMBIGUOUS_COLLISION: 'ambiguous-collision',
+});
+
+const ROUTES = Object.freeze([
+  { id: 'project-extension', action: 'move Project data to docs/agents/skills/<skill>.md' },
+  { id: 'contribution-bridge', action: 'register a temporary contribution-bridge' },
+  { id: 'explicit-fork', action: 'register an explicit-fork with its own update line' },
+  { id: 'clean-core', action: 'explicitly replace the destination with Kit Core' },
+]);
+
+export function classifyOwnershipEvidence({
+  path, packageEntry, installedEntry, destinationPresent, projectExtension,
+  contributionBridge,
+}) {
+  const evidence = {
+    packageDeclared: Boolean(packageEntry),
+    ledgerOrigin: installedEntry?.origin ?? 'absent',
+    destination: destinationPresent ? 'present' : 'absent',
+    projectExtension: projectExtension
+      ? (projectExtension.invalid ? 'invalid' : `schema-v${projectExtension.schemaVersion}`)
+      : 'absent',
+  };
+  if (contributionBridge !== undefined) {
+    evidence.contributionBridge = contributionBridge
+      ? (contributionBridge.invalid ? 'invalid' : `schema-v${contributionBridge.schemaVersion}`)
+      : 'absent';
+  }
+  if (projectExtension?.invalid) evidence.extensionDiagnostic = projectExtension.invalid;
+  if (contributionBridge?.invalid) evidence.bridgeDiagnostic = contributionBridge.invalid;
+  if (installedEntry?.origin === 'kit') {
+    return { path, state: OwnershipState.CLEAN_CORE, evidence, routes: [] };
+  }
+  if (installedEntry?.origin === 'consumer') {
+    const state = installedEntry.ownershipState ?? OwnershipState.EXPLICIT_FORK;
+    if (![
+      OwnershipState.PROJECT_EXTENSION,
+      OwnershipState.CONTRIBUTION_BRIDGE,
+      OwnershipState.EXPLICIT_FORK,
+    ].includes(state)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
+    if (state === OwnershipState.PROJECT_EXTENSION
+        && (!/^docs\/agents\/skills\/[a-z0-9-]+\.md$/.test(path)
+          || !projectExtension || projectExtension.invalid)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
+    if (state === OwnershipState.CONTRIBUTION_BRIDGE
+        && (!contributionBridge || contributionBridge.invalid)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
+    return { path, state, evidence, routes: [] };
+  }
+  if (projectExtension && !projectExtension.invalid) {
+    return { path, state: OwnershipState.PROJECT_EXTENSION, evidence, routes: [
+      { id: 'project-extension', action: 'keep the declared Project extension' },
+      { id: 'clean-core', action: 'explicitly replace the destination with Kit Core' },
+    ] };
+  }
+  return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+}

package/src/lib/projectSkillExtension.mjs

@@ -0,0 +1,60 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { firstLineState } from './sentinel.mjs';
+
+const SKILL_NAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const MARKER_PREFIX = '<!-- agent-workflow-kit: project-extension/';
+const MARKER = /^<!-- agent-workflow-kit: project-extension\/([^;]+); skill=([a-z0-9-]+) -->$/;
+
+export function projectSkillExtensionPath(skill) {
+  if (typeof skill !== 'string' || !SKILL_NAME.test(skill)) {
+    throw new Error(`invalid Project extension skill identity: ${skill}`);
+  }
+  return `docs/agents/skills/${skill}.md`;
+}
+
+export async function inspectProjectSkillExtension({ root, skill }) {
+  const path = projectSkillExtensionPath(skill);
+  const absolute = join(root, path);
+  let state;
+  try {
+    state = await lstat(absolute);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'inactive', reason: 'absent' };
+    throw error;
+  }
+  if (!state.isFile()) {
+    throw new Error(`Project extension is not a regular file: ${path}`);
+  }
+  const body = await readFile(absolute, 'utf8');
+  const setupState = firstLineState(body);
+  if (setupState === 'stub' || setupState === 'not-applicable') {
+    return { state: 'inactive', reason: setupState };
+  }
+  const lines = body.split('\n').map((line) => line.trim());
+  const markerLine = lines.find((line) => line.startsWith(MARKER_PREFIX));
+  if (!markerLine) {
+    if (!body.trim()) return { state: 'inactive', reason: 'empty' };
+    return { state: 'active', schemaVersion: 0, path };
+  }
+  const match = MARKER.exec(markerLine);
+  if (!match || match[1] !== 'v1') {
+    throw new Error(
+      `Project extension has unsupported schema at ${path}; ` +
+      `expected project-extension/v1 for skill=${skill}`,
+    );
+  }
+  if (match[2] !== skill) {
+    throw new Error(
+      `Project extension identity mismatch at ${path}; expected skill=${skill}, ` +
+      `found skill=${match[2]}`,
+    );
+  }
+  const content = lines.filter(
+    (line) => line && line !== markerLine && !line.startsWith('<!-- setup-workflow:'),
+  );
+  if (!content.length) {
+    throw new Error(`Project extension has no instructions after its v1 marker: ${path}`);
+  }
+  return { state: 'active', schemaVersion: 1, path };
+}

package/src/lib/skillRegistry.mjs

@@ -0,0 +1,167 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+export const PROJECT_SKILL_REGISTRY_PATH = 'docs/agents/skill-registry.json';
+export const PROJECT_SKILL_REGISTRY_SCHEMA_VERSION = 1;
+
+const CORE_ANNOTATION_FIELDS = new Set(['note']);
+const SURFACES = new Set(['claude', 'codex']);
+const SKILL_CLASSES = new Set(['generic', 'vendored', 'adapter', 'project-private']);
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function compatibleSubset(prior, current) {
+  if (isRecord(prior)) {
+    return isRecord(current) && Object.entries(prior).every(
+      ([key, value]) => key in current && compatibleSubset(value, current[key]),
+    );
+  }
+  return isDeepStrictEqual(prior, current);
+}
+
+function corePart(declaration) {
+  return Object.fromEntries(
+    Object.entries(declaration).filter(([key]) => !CORE_ANNOTATION_FIELDS.has(key)),
+  );
+}
+
+function annotations(declaration) {
+  return Object.fromEntries(
+    Object.entries(declaration).filter(([key]) => CORE_ANNOTATION_FIELDS.has(key)),
+  );
+}
+
+function validateCore(core, label = 'Kit Core skill registry') {
+  if (!isRecord(core) || core.schema_version !== 1
+      || !isRecord(core.readiness) || !isRecord(core.readiness.capabilities)
+      || !isRecord(core.skills)) {
+    throw new Error(`${label} has an unsupported schema`);
+  }
+  for (const [name, declaration] of Object.entries(core.skills)) {
+    for (const capability of [
+      ...(declaration?.readiness?.required ?? []),
+      ...Object.values(declaration?.readiness?.optionalBlocks ?? {}),
+    ]) {
+      if (!core.readiness.capabilities[capability]) {
+        throw new Error(
+          `candidate invariant schema: unknown readiness reference ${name}.${capability}`,
+        );
+      }
+    }
+  }
+}
+
+export function emptyProjectSkillRegistry(core) {
+  validateCore(core);
+  return {
+    schemaVersion: PROJECT_SKILL_REGISTRY_SCHEMA_VERSION,
+    coreSchemaVersion: core.schema_version,
+    skills: {},
+    annotations: {},
+  };
+}
+
+function validateProjectSkill(name, declaration, capabilities) {
+  if (!isRecord(declaration)
+      || !SKILL_CLASSES.has(declaration.class)
+      || typeof declaration.publish !== 'boolean'
+      || !Array.isArray(declaration.surfaces)
+      || declaration.surfaces.some((surface) => !SURFACES.has(surface))
+      || new Set(declaration.surfaces).size !== declaration.surfaces.length) {
+    throw new Error(`Project skill registry has an invalid local skill: ${name}`);
+  }
+  const readiness = declaration.readiness ?? {};
+  if (!isRecord(readiness)
+      || !Array.isArray(readiness.required ?? [])
+      || !isRecord(readiness.optionalBlocks ?? {})) {
+    throw new Error(`Project skill registry has invalid readiness: ${name}`);
+  }
+  for (const capability of [
+    ...(readiness.required ?? []),
+    ...Object.values(readiness.optionalBlocks ?? {}),
+  ]) {
+    if (!capabilities[capability]) {
+      throw new Error(`Project skill registry references unknown capability: ${name}.${capability}`);
+    }
+  }
+}
+
+export function validateProjectSkillRegistry(core, registry) {
+  validateCore(core);
+  if (!isRecord(registry)
+      || registry.schemaVersion !== PROJECT_SKILL_REGISTRY_SCHEMA_VERSION
+      || registry.coreSchemaVersion !== core.schema_version
+      || !isRecord(registry.skills)
+      || !isRecord(registry.annotations)) {
+    throw new Error('Project skill registry has an unsupported schema');
+  }
+  for (const [name, declaration] of Object.entries(registry.skills)) {
+    if (core.skills[name]) {
+      throw new Error(`Project skill registry collides with Kit Core: ${name}`);
+    }
+    validateProjectSkill(name, declaration, core.readiness.capabilities ?? {});
+  }
+  for (const [name, annotation] of Object.entries(registry.annotations)) {
+    if (!core.skills[name] || !isRecord(annotation)
+        || Object.keys(annotation).some((key) => !CORE_ANNOTATION_FIELDS.has(key))
+        || Object.values(annotation).some((value) => typeof value !== 'string' || !value.trim())) {
+      throw new Error(`Project skill registry has an invalid Core annotation: ${name}`);
+    }
+  }
+  return registry;
+}
+
+export function composeSkillRegistry(core, registry) {
+  validateProjectSkillRegistry(core, registry);
+  const skills = Object.fromEntries(Object.entries(core.skills).map(([name, declaration]) => [
+    name, { ...declaration, ...(registry.annotations[name] ?? {}) },
+  ]));
+  for (const [name, declaration] of Object.entries(registry.skills)) {
+    skills[name] = declaration;
+  }
+  return { ...core, skills };
+}
+
+export function migrateLegacySkillRegistry({ legacyCore, nextCore }) {
+  validateCore(legacyCore, 'Legacy mixed skill registry');
+  validateCore(nextCore);
+  if (!compatibleSubset(legacyCore.readiness, nextCore.readiness)) {
+    throw new Error('Legacy mixed skill registry has ambiguous Core readiness changes');
+  }
+  const skills = {};
+  const coreAnnotations = {};
+  for (const [name, declaration] of Object.entries(legacyCore.skills)) {
+    if (!nextCore.skills[name]) {
+      skills[name] = declaration;
+      continue;
+    }
+    if (!compatibleSubset(corePart(declaration), nextCore.skills[name])) {
+      throw new Error(`Legacy mixed skill registry has ambiguous Kit Core changes: ${name}`);
+    }
+    const local = annotations(declaration);
+    if (Object.keys(local).length) coreAnnotations[name] = local;
+  }
+  const registry = {
+    schemaVersion: PROJECT_SKILL_REGISTRY_SCHEMA_VERSION,
+    coreSchemaVersion: nextCore.schema_version,
+    skills,
+    annotations: coreAnnotations,
+  };
+  validateProjectSkillRegistry(nextCore, registry);
+  return registry;
+}
+
+export async function readComposedSkillRegistry(root, core) {
+  core ??= JSON.parse(await readFile(join(root, '.claude/skills/skill-manifest.json'), 'utf8'));
+  let registry;
+  try {
+    registry = JSON.parse(await readFile(join(root, PROJECT_SKILL_REGISTRY_PATH), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return core;
+    throw new Error(`Project skill registry is invalid: ${error.message}`, { cause: error });
+  }
+  return composeSkillRegistry(core, registry);
+}