@ikon85/agent-workflow-kit 0.29.1 → 0.31.0

package/src/commands/update.mjs

@@ -1,7 +1,9 @@
 import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
-import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
+import {
+  activateCandidate, adoptReadinessCandidate, readReadinessManifest, stageConsumer, verifyCandidate,
+} from '../lib/updateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
@@ -9,6 +11,12 @@ import {
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
+export function renderUpdateFailure(result) {
+  const failure = result.failure ?? { phase: 'unknown', consumerState: 'unknown' };
+  return `candidate update failed · phase: ${failure.phase} · ` +
+    `consumerState: ${failure.consumerState} · ${result.error}`;
+}
+
 /**
  * Transactionally reconcile a consumer with a parity-proven kit release.
  * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
@@ -16,7 +24,8 @@ const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 export async function update(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
-    releaseIdentities, verify = verifyCandidate, signal, onState = () => {}, resumeFrom,
+    releaseIdentities, verify = verifyCandidate, activate = activateCandidate,
+    signal, onState = () => {}, resumeFrom,
   } = options;
   const history = [];
   const transition = async (state) => { history.push(state); await onState(state); };
@@ -30,6 +39,8 @@ export async function update(options) {
     throw new Error('not initialised — run `init` first');
   }
   const consumerManifestBefore = await readFile(consumerManifestPath);
+  const priorReadinessManifest = await readReadinessManifest(consumerRoot);
+  const nextReadinessManifest = await readReadinessManifest(kitRoot);
 
   const decisions = new Map();
   const choosePreview = async (action, path) => {
@@ -39,7 +50,21 @@ export async function update(options) {
     return decisions.get(key);
   };
   const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, dryRun: true });
+  let previewFailure;
+  try {
+    Object.assign(preview, await previewReadinessAdoption({
+      kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest,
+    }));
+  } catch (error) {
+    previewFailure = error;
+  }
   await transition('preview');
+  if (previewFailure) {
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: previewFailure.message,
+      failure: { phase: 'staging', consumerState: 'unchanged' },
+    };
+  }
   if (dryRun) return { ...preview, state: 'preview', history };
   if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
   const resolvedPreview = await resolvePreview({
@@ -52,11 +77,28 @@ export async function update(options) {
     return { ...await terminal(resolvedPreview, 'applied', history, transition), status: 'current' };
   }
   return applyTransaction({
-    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   });
 }
 
+async function previewReadinessAdoption(context) {
+  const { kitRoot, consumerRoot, priorReadinessManifest, nextReadinessManifest } = context;
+  const candidateRoot = await stageConsumer(consumerRoot);
+  try {
+    await reconcile({
+      kitRoot, consumerRoot: candidateRoot,
+      decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
+    });
+    return await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+  } finally {
+    await rm(candidateRoot, { recursive: true, force: true });
+  }
+}
+
 async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decide, transition }) {
   if (preview.deleted.length || preview.keptDeleted.length || preview.collisions.length) {
     await transition('awaiting_decision');
@@ -73,11 +115,12 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
 
 async function applyTransaction(context) {
   const {
-    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
-    consumerManifestBefore, history, transition,
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, activate, signal, resumeFrom,
+    consumerManifestBefore, priorReadinessManifest, nextReadinessManifest, history, transition,
   } = context;
   let candidateRoot = resumeFrom;
   let keepCandidate = false;
+  let phase = 'staging';
   try {
     await transition('staging');
     if (candidateRoot && preview.collisionResolutions.length) {
@@ -90,6 +133,16 @@ async function applyTransaction(context) {
         decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
+    const readiness = await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      nextManifest: nextReadinessManifest,
+    });
+    preview.generated = readiness.generated;
+    preview.availability = readiness.availability;
+    if (readiness.incompatible.length) {
+      throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
+    }
+    phase = 'verification';
     await transition('verifying');
     const abort = async () => {
       keepCandidate = true;
@@ -98,12 +151,16 @@ async function applyTransaction(context) {
     if (signal?.aborted) return abort();
     await verify(candidateRoot);
     if (signal?.aborted) return abort();
-    await activateCandidate({
+    phase = 'activation';
+    await activate({
       candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
     });
     return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
   } catch (error) {
-    return { ...await terminal(preview, 'failed', history, transition), error: error.message };
+    return {
+      ...await terminal(preview, 'failed', history, transition), error: error.message,
+      failure: { phase, consumerState: error.consumerState ?? 'unchanged' },
+    };
   } finally {
     if (candidateRoot && !keepCandidate) await rm(candidateRoot, { recursive: true, force: true });
   }

package/src/lib/bundle.mjs

@@ -4,6 +4,13 @@ import { join, relative } from 'node:path';
 // The planning skills are not usable without their helper ecosystem (Codex R2#1).
 // These ship alongside the skills. Paths are relative to the bundle/consumer root.
 export const HELPER_FILES = [
+  // Readiness declarations and their deterministic consumer-side command ship
+  // together; the manifest remains the only capability/dependency registry.
+  { path: '.claude/skills/skill-manifest.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/readiness.mjs', kind: 'script', mode: 0o755 },
+  { path: 'src/lib/sentinel.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/manifest.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/atomicWrite.mjs', kind: 'script', mode: 0o644 },
   // Shared profile loader imported by the three planning scripts — they read
   // every board-specific value from docs/agents/board-sync.md through it, so it
   // MUST ship or they are broken-on-arrival. Library (imported, not run) → 0o644.

package/src/lib/manifest.mjs

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 
 // Two manifests (Codex R1#9 / R3#1):
@@ -15,6 +16,8 @@ export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
 export const CONSUMER_INSTALL_ROLE = 'consumer';
 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';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -51,8 +54,29 @@ export async function writeManifest(path, obj) {
   await writeAtomic(path, JSON.stringify(obj, null, 2) + '\n');
 }
 
-export function emptyConsumerManifest(kitVersion) {
-  return { kitVersion, installRole: CONSUMER_INSTALL_ROLE, installed: [] };
+export async function readReadinessContract(root) {
+  const manifest = await readManifest(join(root, READINESS_MANIFEST_PATH));
+  return manifest?.readiness ?? null;
+}
+
+function retainedDecisions(prior, readiness) {
+  const allowed = readiness?.capabilities ? new Set(Object.keys(readiness.capabilities)) : null;
+  return Object.fromEntries(Object.entries(prior.readinessDecisions ?? {}).filter(
+    ([name, value]) => (!allowed || allowed.has(name)) && (value === 'pending'
+      || (value === 'not-applicable' && readiness?.capabilities?.[name]?.allowNotApplicable)),
+  ));
+}
+
+export function emptyConsumerManifest(kitVersion, prior = {}, readiness = null) {
+  prior ??= {};
+  return {
+    ...prior,
+    kitVersion,
+    installRole: CONSUMER_INSTALL_ROLE,
+    readinessContractVersion: readiness?.contractVersion ?? READINESS_CONTRACT_VERSION,
+    readinessDecisions: retainedDecisions(prior, readiness),
+    installed: [],
+  };
 }
 
 /** Package entries without a role predate role-aware installs and remain consumer-owned. */

package/src/lib/updateCandidate.mjs

@@ -6,7 +6,13 @@ import { promisify } from 'node:util';
 import { writeAtomic } from './atomicWrite.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
 import { sha256File } from './hash.mjs';
-import { CONSUMER_MANIFEST_NAME, indexByPath, readManifest } from './manifest.mjs';
+import { stubSentinel } from './sentinel.mjs';
+import { STUB_TARGETS } from './bundle.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
+  indexByPath, readManifest, writeManifest,
+} from './manifest.mjs';
+import { checkSkill, evaluateCapability } from '../../scripts/readiness.mjs';
 
 const run = promisify(execFile);
 const exists = (path) => access(path).then(() => true, () => false);
@@ -30,9 +36,11 @@ export async function stageConsumer(consumerRoot) {
 /** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
 export async function activateCandidate({
   candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+  afterGenerated = async () => {},
 }) {
   const changed = [...preview.added, ...preview.updated];
-  const touched = [...changed, ...preview.deleted, CONSUMER_MANIFEST_NAME];
+  const generated = preview.generated ?? [];
+  const touched = [...changed, ...generated, ...preview.deleted, CONSUMER_MANIFEST_NAME];
   const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!currentManifest.equals(consumerManifestBefore)) {
     throw new Error('consumer manifest changed during verification');
@@ -43,6 +51,13 @@ export async function activateCandidate({
       throw new Error(`candidate hash mismatch: ${path}`);
     }
   }
+  const candidateManifest = await readManifest(join(candidateRoot, CONSUMER_MANIFEST_NAME));
+  const candidateInstalled = indexByPath(candidateManifest, 'installed');
+  for (const path of generated) {
+    if (await sha256File(join(candidateRoot, path)) !== candidateInstalled.get(path)?.installedSha256) {
+      throw new Error(`generated candidate hash mismatch: ${path}`);
+    }
+  }
   await assertConsumerStillMatchesPreview(consumerRoot, preview);
   const rollback = new Map();
   for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
@@ -50,6 +65,10 @@ export async function activateCandidate({
     for (const path of changed) {
       await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
     }
+    for (const path of generated) {
+      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)));
+    }
+    await afterGenerated();
     for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
     await writeAtomic(
       join(consumerRoot, CONSUMER_MANIFEST_NAME),
@@ -57,6 +76,7 @@ export async function activateCandidate({
     );
   } catch (error) {
     for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
+    error.consumerState = 'rolled-back';
     throw error;
   }
 }
@@ -80,6 +100,11 @@ async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
     if (replacements.has(path)) continue;
     if (await exists(join(consumerRoot, path))) throw new Error(`consumer changed during verification: ${path}`);
   }
+  for (const path of preview.generated ?? []) {
+    if (await exists(join(consumerRoot, path))) {
+      throw new Error(`consumer changed during verification: ${path}`);
+    }
+  }
   for (const path of [...preview.updated, ...preview.deleted]) {
     const prior = installed.get(path);
     const current = await exists(join(consumerRoot, path))
@@ -90,6 +115,95 @@ 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 }) {
+  const priorPaths = readinessStubPaths(priorManifest);
+  const manifestPath = join(candidateRoot, CONSUMER_MANIFEST_NAME);
+  const manifest = await readManifest(manifestPath);
+  const candidateInstalled = indexByPath(manifest, 'installed');
+  const generated = [];
+  for (const path of readinessStubPaths(nextManifest)) {
+    if (priorPaths.has(path)) continue;
+    if (await exists(join(candidateRoot, path))) {
+      if (candidateInstalled.get(path)?.origin === CONSUMER_ORIGIN
+          && !await exists(join(consumerRoot, path))) generated.push(path);
+      continue;
+    }
+    if (await exists(join(consumerRoot, path))) continue;
+    await writeAtomic(join(candidateRoot, path), `${stubSentinel()}\n`);
+    generated.push(path);
+  }
+  if (generated.length) {
+    const installed = [...manifest.installed];
+    for (const generatedPath of generated) {
+      if (candidateInstalled.has(generatedPath)) continue;
+      installed.push({
+        path: generatedPath, kind: 'doc', installedSha256: await sha256File(join(candidateRoot, generatedPath)),
+        origin: CONSUMER_ORIGIN, installRole: 'consumer',
+      });
+    }
+    await writeManifest(manifestPath, { ...manifest, installed });
+  }
+  const before = await readinessSnapshot(consumerRoot, priorManifest);
+  const after = await readinessSnapshot(candidateRoot, nextManifest);
+  const incompatible = Object.entries(after.skills)
+    .filter(([skill, current]) => before.skills[skill]?.verdict !== 'blocked'
+      && before.skills[skill] && current.verdict === 'blocked')
+    .map(([skill]) => skill)
+    .sort();
+  return { generated, availability: readinessDiff(before, after), incompatible };
+}
+
+function readinessStubPaths(manifest) {
+  const safe = new Set(STUB_TARGETS);
+  return new Set(Object.values(manifest?.readiness?.capabilities ?? {}).flatMap((capability) => {
+    if (capability.evidence?.type !== 'sentinel') return [];
+    return (capability.evidence.paths ?? []).filter((path) => safe.has(path));
+  }));
+}
+
+async function readinessSnapshot(root, manifest) {
+  const skills = {};
+  for (const [name, declaration] of Object.entries(manifest?.skills ?? {})) {
+    if (!declaration.readiness) continue;
+    skills[name] = await checkSkill({ root, skill: name, manifest });
+  }
+  const consumer = await readManifest(join(root, CONSUMER_MANIFEST_NAME));
+  const capabilities = {};
+  for (const [name, capability] of Object.entries(manifest?.readiness?.capabilities ?? {})) {
+    capabilities[name] = await evaluateCapability({
+      root, capability, decision: consumer?.readinessDecisions?.[name],
+    });
+  }
+  return { skills, capabilities };
+}
+
+function readinessDiff(before, after) {
+  const newlyAvailable = [];
+  const newlyDegraded = [];
+  const newlyBlocked = [];
+  const unresolved = new Set();
+  for (const [skill, current] of Object.entries(after.skills)) {
+    const prior = before.skills[skill];
+    if (current.verdict === 'blocked' && prior?.verdict !== 'blocked') newlyBlocked.push(skill);
+    if (current.verdict !== 'blocked' && (!prior || prior.verdict === 'blocked')) newlyAvailable.push(skill);
+    for (const block of current.inactiveBlocks) {
+      if (!prior || !prior.inactiveBlocks.includes(block)) newlyDegraded.push(`${skill}.${block}`);
+    }
+  }
+  for (const [capability, result] of Object.entries(after.capabilities)) {
+    if (result.state !== 'ready') unresolved.add(`${capability}:${result.state}`);
+  }
+  return {
+    newlyAvailable: newlyAvailable.sort(), newlyDegraded: newlyDegraded.sort(),
+    newlyBlocked: newlyBlocked.sort(), stillUnresolved: [...unresolved].sort(),
+  };
+}
+
+export async function readReadinessManifest(root) {
+  return readManifest(join(root, READINESS_MANIFEST_PATH));
+}
+
 async function snapshot(path) {
   if (!await exists(path)) return null;
   const info = await stat(path);

package/src/lib/updateReconcile.mjs

@@ -8,6 +8,7 @@ import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
   CONSUMER_INSTALL_ROLE, CONSUMER_ORIGIN, KIT_ORIGIN, filesForInstallRole,
   indexByPath, readManifest, writeManifest,
+  readReadinessContract,
 } from './manifest.mjs';
 
 const exists = (path) => access(path).then(() => true, () => false);
@@ -18,6 +19,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   if (!pkg) throw new Error('kit package manifest not found');
   const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   if (!consumer) throw new Error('not initialised — run `init` first');
+  const readiness = await readReadinessContract(kitRoot);
 
   const installedIdx = indexByPath(consumer, 'installed');
   const packageIdx = indexByPath(pkg, 'files');
@@ -117,7 +119,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
 
   if (!dryRun) {
     await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
-      ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
+      ...emptyConsumerManifest(pkg.kitVersion, consumer, readiness), installed: nextInstalled,
     });
   }
   return result;