@ikon85/agent-workflow-kit 0.34.6 → 0.35.0

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);
+}

package/src/lib/updateCandidate.mjs

@@ -15,6 +15,10 @@ import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
   filesForInstallRole, indexByPath, readManifest, writeManifest,
 } from './manifest.mjs';
+import {
+  PROJECT_SKILL_REGISTRY_PATH, emptyProjectSkillRegistry, migrateLegacySkillRegistry,
+  readComposedSkillRegistry,
+} from './skillRegistry.mjs';
 import { checkSkill, evaluateCapability, inspectProdSections } from '../../scripts/readiness.mjs';
 
 const exists = (path) => access(path).then(() => true, () => false);
@@ -56,6 +60,7 @@ export async function materializeUpdateCandidate({
 export function candidateInputPaths({ pkg, manifests }) {
   const candidates = [
     CONSUMER_MANIFEST_NAME,
+    PROJECT_SKILL_REGISTRY_PATH,
     ...INTEGRATION_INPUTS,
     ...filesForInstallRole(pkg).map(({ path }) => path),
   ];
@@ -349,12 +354,18 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
 }
 
 /** Seed only newly declared, decision-free project-layer stubs in a staged candidate. */
-export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, priorManifest, nextManifest }) {
+export async function adoptReadinessCandidate({
+  candidateRoot, consumerRoot, kitRoot, priorManifest, nextManifest,
+}) {
   const priorPaths = readinessStubPaths(priorManifest);
   const manifestPath = join(candidateRoot, CONSUMER_MANIFEST_NAME);
-  const manifest = await readManifest(manifestPath);
+  let manifest = await readManifest(manifestPath);
+  const registry = await adoptProjectSkillRegistry({
+    candidateRoot, consumerRoot, kitRoot, manifest, priorManifest, nextManifest,
+  });
+  manifest = await readManifest(manifestPath);
   const candidateInstalled = indexByPath(manifest, 'installed');
-  const generated = [];
+  const generated = [...registry.generated];
   for (const path of readinessStubPaths(nextManifest)) {
     if (priorPaths.has(path)) continue;
     if (await exists(join(candidateRoot, path))) {
@@ -377,9 +388,11 @@ export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, pri
     }
     await writeManifest(manifestPath, { ...manifest, installed });
   }
-  const { migrations, migrationConflicts } = await migrateProdSections({
+  const prod = await migrateProdSections({
     candidateRoot, consumerRoot, nextManifest,
   });
+  const migrations = [...registry.migrations, ...prod.migrations];
+  const migrationConflicts = [...registry.migrationConflicts, ...prod.migrationConflicts];
   const before = await readinessSnapshot(consumerRoot, priorManifest);
   const after = await readinessSnapshot(candidateRoot, nextManifest);
   const incompatible = Object.entries(after.skills)
@@ -397,6 +410,94 @@ export async function adoptReadinessCandidate({ candidateRoot, consumerRoot, pri
   };
 }
 
+async function adoptProjectSkillRegistry({
+  candidateRoot, consumerRoot, kitRoot, manifest, priorManifest, nextManifest,
+}) {
+  if (!nextManifest) {
+    return { generated: [], migrations: [], migrationConflicts: [] };
+  }
+  const tracked = manifest.installed.find(({ path }) => path === READINESS_MANIFEST_PATH);
+  if (tracked?.origin !== CONSUMER_ORIGIN) {
+    const registryPath = join(candidateRoot, PROJECT_SKILL_REGISTRY_PATH);
+    if (!await exists(registryPath)) {
+      await writeAtomic(
+        registryPath,
+        `${JSON.stringify(emptyProjectSkillRegistry(nextManifest), null, 2)}\n`,
+      );
+      const installedSha256 = await sha256File(registryPath);
+      await writeManifest(join(candidateRoot, CONSUMER_MANIFEST_NAME), {
+        ...manifest,
+        installed: [...manifest.installed, {
+          path: PROJECT_SKILL_REGISTRY_PATH,
+          kind: 'doc',
+          installedSha256,
+          origin: CONSUMER_ORIGIN,
+          installRole: 'consumer',
+        }],
+      });
+      await readComposedSkillRegistry(candidateRoot, nextManifest);
+      return {
+        generated: [PROJECT_SKILL_REGISTRY_PATH],
+        migrations: [],
+        migrationConflicts: [],
+      };
+    }
+    await readComposedSkillRegistry(candidateRoot, nextManifest);
+    return { generated: [], migrations: [], migrationConflicts: [] };
+  }
+  const registryPath = join(candidateRoot, PROJECT_SKILL_REGISTRY_PATH);
+  if (await exists(registryPath)) {
+    return {
+      generated: [],
+      migrations: [],
+      migrationConflicts: [
+        `${PROJECT_SKILL_REGISTRY_PATH}: legacy mixed Core already has a Project registry`,
+      ],
+    };
+  }
+  let registry;
+  try {
+    registry = migrateLegacySkillRegistry({ legacyCore: priorManifest, nextCore: nextManifest });
+  } catch (error) {
+    return {
+      generated: [], migrations: [],
+      migrationConflicts: [`${READINESS_MANIFEST_PATH}: ${error.message}`],
+    };
+  }
+  const corePath = join(candidateRoot, READINESS_MANIFEST_PATH);
+  await writeAtomic(corePath, await readFile(join(kitRoot, READINESS_MANIFEST_PATH)));
+  await writeAtomic(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+  const coreHash = await sha256File(corePath);
+  const registryHash = await sha256File(registryPath);
+  const installed = manifest.installed.map((entry) => {
+    if (entry.path !== READINESS_MANIFEST_PATH) return entry;
+    const { ownershipState: _legacyLifecycle, ...coreEntry } = entry;
+    return { ...coreEntry, installedSha256: coreHash, origin: 'kit' };
+  });
+  if (!installed.some(({ path }) => path === PROJECT_SKILL_REGISTRY_PATH)) {
+    installed.push({
+      path: PROJECT_SKILL_REGISTRY_PATH,
+      kind: 'doc',
+      installedSha256: registryHash,
+      origin: CONSUMER_ORIGIN,
+      installRole: 'consumer',
+    });
+  }
+  await writeManifest(join(candidateRoot, CONSUMER_MANIFEST_NAME), {
+    ...manifest, installed,
+  });
+  return {
+    generated: [PROJECT_SKILL_REGISTRY_PATH],
+    migrations: [{
+      path: READINESS_MANIFEST_PATH,
+      beforeSha256: await sha256File(join(consumerRoot, READINESS_MANIFEST_PATH)),
+      afterSha256: coreHash,
+      ownership: 'kit-core',
+    }],
+    migrationConflicts: [],
+  };
+}
+
 async function migrateProdSections({ candidateRoot, consumerRoot, nextManifest }) {
   const paths = [...new Set(Object.values(nextManifest?.readiness?.capabilities ?? {})
     .flatMap(({ evidence }) => evidence?.type === 'prod-section' ? evidence.paths ?? [] : []))];

package/src/lib/updateDecisions.mjs

@@ -0,0 +1,5 @@
+export function nonInteractiveUpdateDecision(action) {
+  if (action === 'delete') return true;
+  if (action === 'collision') return undefined;
+  throw new Error(`unknown update decision action: ${action}`);
+}

package/src/lib/updateReconcile.mjs

@@ -4,6 +4,10 @@ import { sha256File } from './hash.mjs';
 import { lineDiff, writeAtomic } from './atomicWrite.mjs';
 import { hookReferenced } from './settings.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
+import { inspectProjectSkillExtension } from './projectSkillExtension.mjs';
+import {
+  OwnershipState, classifyOwnershipEvidence,
+} from './ownershipClassifier.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
   CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN, filesForInstallRole,
@@ -32,6 +36,22 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     const dest = join(consumerRoot, file.path);
     const prior = installedIdx.get(file.path);
     if (prior?.origin === CONSUMER_ORIGIN) {
+      const classification = classifyOwnershipEvidence({
+        path: file.path,
+        packageEntry: file,
+        installedEntry: prior,
+        destinationPresent: await exists(dest),
+        projectExtension: prior.ownershipState === OwnershipState.PROJECT_EXTENSION
+          ? await projectExtensionEvidence(consumerRoot, file.path) : null,
+      });
+      result.ownershipStates.push(classification);
+      if (classification.state === OwnershipState.AMBIGUOUS_COLLISION) {
+        result.conflicts.push({
+          path: file.path,
+          kind: 'ownership-lifecycle',
+          diff: 'Consumer lifecycle metadata does not match its declared path/schema.',
+        });
+      }
       nextInstalled.push(withInstallRole(prior));
       result.consumerOwned.push(file.path);
       continue;
@@ -39,6 +59,13 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     const present = await exists(dest);
     if (!prior && present) {
       await validateConsumerFile(consumerRoot, file.path);
+      const classification = classifyOwnershipEvidence({
+        path: file.path,
+        packageEntry: file,
+        destinationPresent: true,
+        projectExtension: await projectExtensionEvidence(consumerRoot, file.path),
+      });
+      result.ownershipStates.push(classification);
       const decision = await decide('collision', file.path);
       if (decision === false || decision === null || decision === undefined) {
         if (dryRun) {
@@ -47,15 +74,30 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
         }
         throw new Error(`collision decision required for ${file.path}`);
       }
-      if (decision !== 'keep-as-owned' && decision !== 'replace') {
-        throw new Error(`collision decision for ${file.path} must be keep-as-owned or replace`);
+      const allowed = [
+        'keep-as-owned', 'project-extension', 'contribution-bridge', 'explicit-fork', 'replace',
+      ];
+      if (!allowed.includes(decision)
+          || (decision === 'project-extension'
+            && classification.state !== OwnershipState.PROJECT_EXTENSION)) {
+        throw new Error(
+          `collision decision for ${file.path} must select a valid explicit ownership route`,
+        );
       }
       const destinationSha256 = await sha256File(dest);
-      result.collisionResolutions.push({
+      const resolvedState = decision === 'replace' ? OwnershipState.CLEAN_CORE
+        : (decision === 'keep-as-owned' ? OwnershipState.EXPLICIT_FORK : decision);
+      const resolution = {
         path: file.path, outcome: decision, destinationSha256,
-      });
-      if (decision === 'keep-as-owned') {
-        nextInstalled.push(entry(file, destinationSha256, CONSUMER_ORIGIN));
+      };
+      if (!['replace', 'keep-as-owned'].includes(decision)) {
+        resolution.ownershipState = resolvedState;
+      }
+      result.collisionResolutions.push(resolution);
+      if (decision !== 'replace') {
+        nextInstalled.push(entry(
+          file, destinationSha256, CONSUMER_ORIGIN, resolvedState,
+        ));
         result.consumerOwned.push(file.path);
       } else {
         if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
@@ -128,17 +170,31 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], collisions: [], collisionResolutions: [], userModified: [],
+    ownershipStates: [],
     added: [], deleted: [], keptDeleted: [], consumerOwned: [], manifestChanged: false,
   };
 }
 
-function entry(file, installedSha256, origin = KIT_ORIGIN) {
-  return {
+function entry(file, installedSha256, origin = KIT_ORIGIN, ownershipState) {
+  const result = {
     path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
     installedSha256, origin, installRole: CONSUMER_INSTALL_ROLE,
   };
+  if (ownershipState) result.ownershipState = ownershipState;
+  return result;
 }
 
 function withInstallRole(installed, installRole = CONSUMER_INSTALL_ROLE) {
   return { ...installed, installRole };
 }
+
+async function projectExtensionEvidence(consumerRoot, path) {
+  const match = /^docs\/agents\/skills\/([a-z0-9-]+)\.md$/.exec(path);
+  if (!match) return null;
+  try {
+    const result = await inspectProjectSkillExtension({ root: consumerRoot, skill: match[1] });
+    return result.state === 'active' ? result : null;
+  } catch (error) {
+    return { invalid: error.message };
+  }
+}

package/src/lib/verifyUpdateCandidate.mjs

@@ -189,6 +189,14 @@ function validateInstalledEntry(tracked, desired, origin) {
   if (tracked.origin === KIT_ORIGIN && tracked.installedSha256 !== desired.sha256) {
     throw new Error(`candidate invariant ownership: Kit hash identity mismatch ${tracked.path}`);
   }
+  if (tracked.origin === KIT_ORIGIN && tracked.ownershipState !== undefined) {
+    throw new Error(`candidate invariant ownership: Kit path has Consumer lifecycle ${tracked.path}`);
+  }
+  if (tracked.origin === CONSUMER_ORIGIN && ![
+    undefined, 'project-extension', 'contribution-bridge', 'explicit-fork',
+  ].includes(tracked.ownershipState)) {
+    throw new Error(`candidate invariant ownership: invalid lifecycle ${tracked.path}`);
+  }
 }
 
 function verifyLedgerMetadata(ledger, context) {
@@ -207,8 +215,12 @@ function verifyLedgerMetadata(ledger, context) {
 }
 
 function expectedOrigin(path, priorInstalled, preview) {
+  const transferredToCore = (preview.migrations ?? []).some(
+    (migration) => migration.path === path && migration.ownership === 'kit-core',
+  );
+  if (transferredToCore) return KIT_ORIGIN;
   const keptOwned = (preview.collisionResolutions ?? []).some(
-    (resolution) => resolution.path === path && resolution.outcome === 'keep-as-owned',
+    (resolution) => resolution.path === path && resolution.outcome !== 'replace',
   );
   return keptOwned || (priorInstalled.get(path)?.origin ?? KIT_ORIGIN) === CONSUMER_ORIGIN
     ? CONSUMER_ORIGIN

package/src/lib/verifyUpdateCandidateProtocol.mjs

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, filesForInstallRole } from './manifest.mjs';
 import { validateCandidateManifestPath } from './updateCandidate.mjs';
+import { readComposedSkillRegistry } from './skillRegistry.mjs';
 
 const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
 const SURFACE_ROOT = {
@@ -18,6 +19,7 @@ export async function verifyCandidateProtocol(candidateRoot, pkg, installed) {
     throw new Error('candidate invariant schema: readiness manifest is invalid JSON');
   }
   validateReadinessManifest(manifest);
+  await readComposedSkillRegistry(candidateRoot, manifest);
   validateSkillArtifactReferences(manifest, pkg);
   for (const [name, declaration] of Object.entries(manifest.skills)) {
     if (!declaration.publish

package/src/lib/verifyUpdateCandidateTransaction.mjs

@@ -109,15 +109,21 @@ function verifyCollisionRecords(preview, installablePaths, installed, actionSets
   for (const resolution of preview.collisionResolutions ?? []) {
     const path = resolution?.path;
     claimTransactionPath(path, 'collision resolution', resolutions);
+    const nonReplace = resolution?.outcome !== 'replace';
+    const expectedOwnershipState = resolution?.outcome === 'keep-as-owned'
+      ? 'explicit-fork' : resolution?.ownershipState;
     if (!installablePaths.has(path)
-        || !['keep-as-owned', 'replace'].includes(resolution?.outcome)
+        || ![
+          'keep-as-owned', 'project-extension', 'contribution-bridge', 'explicit-fork', 'replace',
+        ].includes(resolution?.outcome)
         || !HASH.test(resolution?.destinationSha256 ?? '')) {
       throw new Error(`candidate invariant transaction: invalid collision resolution ${path}`);
     }
-    const expectedOrigin = resolution.outcome === 'keep-as-owned' ? CONSUMER_ORIGIN : KIT_ORIGIN;
+    const expectedOrigin = nonReplace ? CONSUMER_ORIGIN : KIT_ORIGIN;
     if (installed.get(path)?.origin !== expectedOrigin
+        || (nonReplace && installed.get(path)?.ownershipState !== expectedOwnershipState)
         || (resolution.outcome === 'replace' && !actionSets.get('added').has(path))
-        || (resolution.outcome === 'keep-as-owned' && owners.has(path))) {
+        || (nonReplace && owners.has(path))) {
       throw new Error(`candidate invariant transaction: incoherent collision resolution ${path}`);
     }
   }