@ikon85/agent-workflow-kit 0.34.6 → 0.36.0

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,11 @@ import { sha256File } from './hash.mjs';
 import { lineDiff, writeAtomic } from './atomicWrite.mjs';
 import { hookReferenced } from './settings.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
+import { validateContributionBridge } from './contributionBridge.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 +37,40 @@ 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 bridge = prior.ownershipState === OwnershipState.CONTRIBUTION_BRIDGE
+        ? contributionBridgeEvidence(prior) : null;
+      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,
+        contributionBridge: bridge,
+      });
+      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.',
+        });
+      }
+      if (classification.state === OwnershipState.CONTRIBUTION_BRIDGE) {
+        const present = await exists(dest);
+        if (present) {
+          await validateConsumerFile(consumerRoot, file.path);
+          const current = await sha256File(dest);
+          if (current === file.sha256 && current === bridge.localSha256) {
+            if (!dryRun) {
+              await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+            }
+            nextInstalled.push(entry(file, file.sha256));
+            result.bridgeRetired.push(file.path);
+            continue;
+          }
+        }
+      }
       nextInstalled.push(withInstallRole(prior));
       result.consumerOwned.push(file.path);
       continue;
@@ -39,6 +78,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 +93,38 @@ 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') {
+        const lifecycle = resolvedState === OwnershipState.CONTRIBUTION_BRIDGE ? {
+          contributionBridge: {
+            schemaVersion: 1,
+            baseKitVersion: pkg.kitVersion,
+            baseSha256: file.sha256,
+            localSha256: destinationSha256,
+          },
+        } : {};
+        nextInstalled.push(entry(
+          file, destinationSha256, CONSUMER_ORIGIN, resolvedState, lifecycle,
+        ));
         result.consumerOwned.push(file.path);
       } else {
         if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
@@ -115,6 +184,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   }
 
   result.manifestChanged = consumer.installRole !== CONSUMER_INSTALL_ROLE ||
+    result.bridgeRetired.length > 0 ||
     nextInstalled.some((next) => installedIdx.get(next.path)?.installRole !== next.installRole);
 
   if (!dryRun) {
@@ -128,17 +198,40 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], collisions: [], collisionResolutions: [], userModified: [],
+    ownershipStates: [],
+    bridgeRetired: [],
     added: [], deleted: [], keptDeleted: [], consumerOwned: [], manifestChanged: false,
   };
 }
 
-function entry(file, installedSha256, origin = KIT_ORIGIN) {
-  return {
+function contributionBridgeEvidence(installed) {
+  try {
+    return validateContributionBridge(installed);
+  } catch (error) {
+    return { invalid: error.message };
+  }
+}
+
+function entry(file, installedSha256, origin = KIT_ORIGIN, ownershipState, lifecycle = {}) {
+  const result = {
     path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
-    installedSha256, origin, installRole: CONSUMER_INSTALL_ROLE,
+    installedSha256, origin, installRole: CONSUMER_INSTALL_ROLE, ...lifecycle,
   };
+  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

@@ -2,6 +2,7 @@ import { lstat, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sha256File } from './hash.mjs';
+import { validateContributionBridge } from './contributionBridge.mjs';
 import {
   CONSUMER_INSTALL_ROLE, CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, KIT_ORIGIN,
   emptyConsumerManifest, filesForInstallRole,
@@ -189,6 +190,27 @@ 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 === KIT_ORIGIN && tracked.contributionBridge !== undefined) {
+    throw new Error(`candidate invariant ownership: Kit path has contribution bridge ${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}`);
+  }
+  if (tracked.origin === CONSUMER_ORIGIN
+      && tracked.ownershipState === 'contribution-bridge') {
+    try {
+      validateContributionBridge(tracked);
+    } catch {
+      throw new Error(`candidate invariant ownership: invalid contribution bridge ${tracked.path}`);
+    }
+  } else if (tracked.contributionBridge !== undefined) {
+    throw new Error(`candidate invariant ownership: unexpected contribution bridge ${tracked.path}`);
+  }
 }
 
 function verifyLedgerMetadata(ledger, context) {
@@ -207,8 +229,13 @@ function verifyLedgerMetadata(ledger, context) {
 }
 
 function expectedOrigin(path, priorInstalled, preview) {
+  if ((preview.bridgeRetired ?? []).includes(path)) return KIT_ORIGIN;
+  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

@@ -60,6 +60,16 @@ export function verifyTransactionPreview(preview, installable, installed) {
     }
     actionSets.set(key, local);
   }
+  if (!Array.isArray(preview.bridgeRetired ?? [])) {
+    throw new Error('candidate invariant transaction: bridgeRetired must be an array');
+  }
+  const retired = new Set();
+  for (const path of preview.bridgeRetired ?? []) {
+    claimTransactionPath(path, 'bridgeRetired', retired, owners);
+    if (!installablePaths.has(path) || installed.get(path)?.origin !== KIT_ORIGIN) {
+      throw new Error(`candidate invariant transaction: invalid bridge retirement ${path}`);
+    }
+  }
   if (!Array.isArray(preview.migrations ?? [])) {
     throw new Error('candidate invariant transaction: migrations must be an array');
   }
@@ -109,15 +119,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}`);
     }
   }