@ikon85/agent-workflow-kit 0.36.5 → 0.38.0

package/src/cli.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import * as p from '@clack/prompts';
@@ -20,29 +21,51 @@ import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const consumerRoot = process.cwd();
 
 function stamp() {
   // backup suffix: YYYYMMDDTHHMMSS (no separators that collide with shells)
   return new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '');
 }
 
-const args = process.argv.slice(2);
-const cmd = args[0];
-const force = args.includes('--force');
-const yes = args.includes('--yes') || args.includes('-y');
-const owned = args.includes('--owned');
-const ownershipState = args.find((arg) => arg.startsWith('--as='))?.slice('--as='.length);
+export async function runCli({
+  argv = process.argv.slice(2),
+  kitRoot = KIT_ROOT,
+  consumerRoot = process.cwd(),
+  hasTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  readUpdateRelease: releaseReader = readUpdateRelease,
+  updateCommand = update,
+} = {}) {
+  const args = argv;
+  const cmd = args[0];
+  const force = args.includes('--force');
+  const yes = args.includes('--yes') || args.includes('-y');
+  const owned = args.includes('--owned');
+  const keepDeleted = args.includes('--keep-deleted');
+  const restoreDeleted = args.includes('--restore-deleted');
+  const ownershipState = args.find((arg) => arg.startsWith('--as='))?.slice('--as='.length);
+  let exitCode = 0;
 
-p.intro('agent-workflow-kit');
+  if (cmd === 'update' && keepDeleted && restoreDeleted) {
+    process.stderr.write('Error: --keep-deleted and --restore-deleted are mutually exclusive.\n');
+    return 1;
+  }
+  if (cmd === 'update' && !hasTTY && !yes) {
+    process.stderr.write(
+      'Error: interactive prompts need a TTY. For non-interactive update, pass --yes '
+      + 'and optionally --keep-deleted or --restore-deleted.\n',
+    );
+    return 1;
+  }
+
+  p.intro('agent-workflow-kit');
 
-try {
+  try {
   if (cmd === 'init') {
     const r = await init({
-      kitRoot: KIT_ROOT,
+      kitRoot,
       consumerRoot,
       force,
-      routingProfile: routingProfileOptions(),
+      routingProfile: routingProfileOptions(yes),
     });
     p.note(
       `copied ${r.copied.length} · seeded ${r.seeded.length} stub(s)` +
@@ -53,21 +76,23 @@ try {
     p.outro('Next: run /setup-workflow to fill the project layer + board profile. ' +
       'To enable the drift-guard hook, add .claude/hooks/drift-guard.py to your settings.json hooks.');
   } else if (cmd === 'diff') {
-    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot, owned });
+    const r = await diff({ kitRoot, consumerRoot, owned });
     printPlan(r);
     p.outro('Dry run — nothing written. Run `update` to apply.');
   } else if (cmd === 'update') {
     const decide = (action, path, classification) => (
-      decideUpdate(action, path, yes, classification)
+      decideUpdate(action, path, yes, classification, {
+        deleted: keepDeleted ? 'keep' : restoreDeleted ? 'restore' : undefined,
+      })
     );
-    const releaseIdentities = await readUpdateRelease();
-    const r = await update({
-      kitRoot: KIT_ROOT,
+    const releaseIdentities = await releaseReader();
+    const r = await updateCommand({
+      kitRoot,
       consumerRoot,
       now: stamp(),
       decide,
       releaseIdentities,
-      routingProfile: routingProfileOptions(),
+      routingProfile: routingProfileOptions(yes),
     });
     printPlan(r);
     printRoutingProfile(r.routingProfile);
@@ -79,7 +104,7 @@ try {
         `not applied · conflicts ${r.conflicts.length} · ` +
         `ownership collisions ${r.collisions.length}`,
       );
-      process.exitCode = 2;
+      exitCode = 2;
     } else if (r.status === 'current') {
       p.outro(`aktuell · unchanged ${r.unchanged.length} · local modifications ${r.userModified.length}`);
     } else {
@@ -87,7 +112,7 @@ try {
     }
   } else if (cmd === 'uninstall') {
     const ok = yes || (await p.confirm({ message: 'Remove kit-installed files?' })) === true;
-    if (!ok) { p.cancel('Aborted.'); process.exit(0); }
+    if (!ok) { p.cancel('Aborted.'); return 0; }
     const r = await uninstall({ consumerRoot });
     p.outro(`removed ${r.removed.length} · retained (edited/referenced) ${r.retained.length}`);
   } else if (cmd === 'contribute') {
@@ -101,7 +126,7 @@ try {
       );
     }
     if (action === 'start') {
-      await beginContributionBridge({ kitRoot: KIT_ROOT, consumerRoot, path });
+      await beginContributionBridge({ kitRoot, consumerRoot, path });
       p.outro(`${path} is now a contribution bridge; no remote was changed`);
     } else if (action === 'status') {
       const surface = args.find((arg) => arg.startsWith('--surface='))
@@ -132,7 +157,7 @@ try {
         );
       }
       await prepareContributionArtifact({
-        kitRoot: KIT_ROOT, consumerRoot, path, output,
+        kitRoot, consumerRoot, path, output,
       });
       p.outro(`prepared local contribution artifact ${output}; no remote was changed`);
     }
@@ -145,7 +170,7 @@ try {
     }
     const origin = cmd === 'own' ? CONSUMER_ORIGIN : KIT_ORIGIN;
     if (origin === CONSUMER_ORIGIN && ownershipState === 'contribution-bridge') {
-      await beginContributionBridge({ kitRoot: KIT_ROOT, consumerRoot, path: args[1] });
+      await beginContributionBridge({ kitRoot, consumerRoot, path: args[1] });
     } else {
       await setOwnership({ consumerRoot, path: args[1], origin, ownershipState });
     }
@@ -153,12 +178,20 @@ try {
       (origin === CONSUMER_ORIGIN ? ` (${ownershipState ?? 'explicit-fork'})` : ''));
   } else {
     p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown|contribute> ' +
-      '[<path>] [--force] [--yes] [--owned] [--as=contribution-bridge|explicit-fork]');
+      '[<path>] [--force] [--yes] [--keep-deleted|--restore-deleted] [--owned] ' +
+      '[--as=contribution-bridge|explicit-fork]');
     p.outro('');
   }
 } catch (err) {
   p.cancel(`Error: ${err.message}`);
-  process.exit(1);
+  return 1;
+}
+  return exitCode;
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runCli();
 }
 
 function printPlan(r) {
@@ -190,8 +223,8 @@ function printPlan(r) {
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
 
-async function decideUpdate(action, path, yes, classification) {
-  if (yes) return nonInteractiveUpdateDecision(action);
+async function decideUpdate(action, path, yes, classification, choices = {}) {
+  if (yes) return nonInteractiveUpdateDecision(action, choices);
   if (action === 'delete') {
     return (await p.confirm({ message: `Upstream removed ${path} — delete it locally?` })) === true;
   }
@@ -213,7 +246,7 @@ async function decideUpdate(action, path, yes, classification) {
   throw new Error(`unknown update decision action: ${action}`);
 }
 
-function routingProfileOptions() {
+function routingProfileOptions(yes) {
   return {
     currentSurface: currentAgentSurface(),
     prompt: yes ? undefined : promptRoutingProfile,

package/src/lib/bundle.mjs

@@ -134,6 +134,7 @@ export const HELPER_FILES = [
   { path: 'scripts/worktree-lifecycle/profile.py', kind: 'script', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/setup.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/cleanup.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/worktree-lifecycle/session.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/worktree-lifecycle/capabilities.json', kind: 'doc', mode: 0o644 },
   { path: 'scripts/worktree-lifecycle/README.md', kind: 'doc', mode: 0o644 },
   // Shared hook utility imported by the shipped hooks (drift-guard,

package/src/lib/manifest.mjs

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join, posix } from 'node:path';
 import { writeAtomic } from './atomicWrite.mjs';
 
 // Two manifests (Codex R1#9 / R3#1):
@@ -20,6 +20,16 @@ export const READINESS_CONTRACT_VERSION = 1;
 export const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
 export { PROJECT_SKILL_REGISTRY_PATH } from './skillRegistry.mjs';
 
+const HASH = /^[a-f0-9]{64}$/;
+const KINDS = new Set(['skill', 'script', 'hook', 'template', 'doc']);
+const SURFACES = new Set(['claude', 'codex']);
+const INSTALL_ROLES = new Set([CONSUMER_INSTALL_ROLE, 'maintainer']);
+const ORIGINS = new Set([KIT_ORIGIN, CONSUMER_ORIGIN]);
+const OWNERSHIP_STATES = new Set([
+  'project-extension', 'contribution-bridge', 'explicit-fork',
+]);
+const READINESS_DECISIONS = new Set(['pending', 'not-applicable']);
+
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
  * (invalid JSON — e.g. from an aborted write before writeManifest went atomic)
@@ -35,8 +45,9 @@ export async function readManifest(path) {
     if (err.code === 'ENOENT') return null;
     throw err;
   }
+  let manifest;
   try {
-    return JSON.parse(raw);
+    manifest = JSON.parse(raw);
   } catch (err) {
     throw new Error(
       `${path} is corrupt (invalid JSON) and can't be read. ` +
@@ -44,6 +55,162 @@ export async function readManifest(path) {
       { cause: err }
     );
   }
+  const name = basename(path);
+  if (name === PACKAGE_MANIFEST_NAME) {
+    return validateManifest(manifest, { kind: 'package', path });
+  }
+  if (name === CONSUMER_MANIFEST_NAME) {
+    return validateManifest(manifest, { kind: 'consumer', path });
+  }
+  return manifest;
+}
+
+/**
+ * Validate the two persisted lifecycle manifests before their entries are
+ * indexed or trusted. Unknown extension keys remain untouched; known fields
+ * are deliberately strict. Compatibility is explicit:
+ * - package manifests before role-aware installs may omit `installRole`;
+ * - consumer ledgers before role-aware installs may omit `installRole`;
+ * - readiness fields introduced after the first consumer ledger are optional.
+ */
+export function validateManifest(manifest, { kind, path }) {
+  if (kind !== 'package' && kind !== 'consumer') {
+    throw new Error(`unknown manifest class: ${kind}`);
+  }
+  const recovery = kind === 'package'
+    ? 'Reinstall the Kit or regenerate its package manifest from a trusted checkout.'
+    : 'Restore the consumer manifest from its ".bak" backup, or delete it and re-run `init`.';
+  const fail = (detail) => {
+    throw new Error(`${path} is an invalid ${kind} manifest: ${detail} ${recovery}`);
+  };
+  if (!plainObject(manifest)) fail('the root must be a JSON object.');
+  if (typeof manifest.kitVersion !== 'string' || manifest.kitVersion.length === 0) {
+    fail('kitVersion must be a non-empty string.');
+  }
+  const key = kind === 'package' ? 'files' : 'installed';
+  if (!Array.isArray(manifest[key])) fail(`${key} must be an array.`);
+  if (kind === 'consumer') validateConsumerRoot(manifest, fail);
+
+  const seen = new Set();
+  for (const [offset, entry] of manifest[key].entries()) {
+    const ordinal = `entry #${offset + 1}`;
+    if (!plainObject(entry)) fail(`${ordinal} must be a JSON object.`);
+    if (!safeManifestPath(entry.path)) {
+      fail(`${ordinal} has an unsafe consumer path (${display(entry.path)}); use a relative POSIX path without "." or ".." segments.`);
+    }
+    const label = `${ordinal} (${entry.path})`;
+    if (seen.has(entry.path)) fail(`${label} duplicates path ${entry.path}.`);
+    seen.add(entry.path);
+    validateEnum(entry, 'kind', KINDS, label, fail, true);
+    validateOptionalString(entry, 'ownerSkill', label, fail);
+    validateEnum(entry, 'surface', SURFACES, label, fail);
+    validateEnum(entry, 'installRole', INSTALL_ROLES, label, fail);
+    validateEnum(entry, 'origin', ORIGINS, label, fail, true);
+    if (kind === 'package') {
+      validateHash(entry.sha256, `${label} sha256`, fail);
+      if (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777) {
+        fail(`${label} mode must be an integer from 0 through 511.`);
+      }
+      if (entry.origin !== KIT_ORIGIN) fail(`${label} origin must be "kit".`);
+    } else {
+      validateHash(entry.installedSha256, `${label} installedSha256`, fail);
+      if ('sha256' in entry) validateHash(entry.sha256, `${label} sha256`, fail);
+      if ('mode' in entry
+          && (!Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777)) {
+        fail(`${label} mode must be an integer from 0 through 511.`);
+      }
+      validateConsumerEntry(entry, label, fail);
+    }
+  }
+  return manifest;
+}
+
+function validateConsumerRoot(manifest, fail) {
+  if ('installRole' in manifest && manifest.installRole !== CONSUMER_INSTALL_ROLE) {
+    fail('installRole must be "consumer".');
+  }
+  if ('readinessContractVersion' in manifest
+      && (!Number.isInteger(manifest.readinessContractVersion)
+        || manifest.readinessContractVersion < 1)) {
+    fail('readinessContractVersion must be a positive integer.');
+  }
+  if ('readinessDecisions' in manifest) {
+    if (!plainObject(manifest.readinessDecisions)) {
+      fail('readinessDecisions must be a JSON object.');
+    }
+    for (const [capability, decision] of Object.entries(manifest.readinessDecisions)) {
+      if (!capability || !READINESS_DECISIONS.has(decision)) {
+        fail(`readinessDecisions.${capability || '<empty>'} has unsupported value ${display(decision)}.`);
+      }
+    }
+  }
+}
+
+function validateConsumerEntry(entry, label, fail) {
+  if ('orphanedByUninstall' in entry && typeof entry.orphanedByUninstall !== 'boolean') {
+    fail(`${label} orphanedByUninstall must be a boolean.`);
+  }
+  validateEnum(entry, 'ownershipState', OWNERSHIP_STATES, label, fail);
+  if ('ownershipState' in entry && entry.origin !== CONSUMER_ORIGIN) {
+    fail(`${label} ownershipState requires origin "consumer".`);
+  }
+  if (!('contributionBridge' in entry)) return;
+  const bridge = entry.contributionBridge;
+  if (!plainObject(bridge)
+      || bridge.schemaVersion !== 1
+      || typeof bridge.baseKitVersion !== 'string'
+      || bridge.baseKitVersion.length === 0) {
+    fail(`${label} contributionBridge must be a schemaVersion 1 object with baseKitVersion.`);
+  }
+  validateHash(bridge.baseSha256, `${label} contributionBridge.baseSha256`, fail);
+  validateHash(bridge.localSha256, `${label} contributionBridge.localSha256`, fail);
+  if (entry.origin !== CONSUMER_ORIGIN
+      || entry.ownershipState !== 'contribution-bridge'
+      || entry.installedSha256 !== bridge.localSha256) {
+    fail(`${label} contributionBridge must match consumer ownership and installedSha256.`);
+  }
+}
+
+function validateEnum(entry, field, values, label, fail, required = false) {
+  if (!(field in entry)) {
+    if (required) fail(`${label} ${field} is required.`);
+    return;
+  }
+  if (typeof entry[field] !== 'string' || !values.has(entry[field])) {
+    fail(`${label} ${field} has unsupported value ${display(entry[field])}.`);
+  }
+}
+
+function validateOptionalString(entry, field, label, fail) {
+  if (field in entry && (typeof entry[field] !== 'string' || entry[field].length === 0)) {
+    fail(`${label} ${field} must be a non-empty string when present.`);
+  }
+}
+
+function validateHash(value, field, fail) {
+  if (typeof value !== 'string' || !HASH.test(value)) {
+    fail(`${field} must be a lowercase 64-hex SHA-256.`);
+  }
+}
+
+function safeManifestPath(path) {
+  return typeof path === 'string'
+    && path.length > 0
+    && path !== '.'
+    && !path.includes('\\')
+    && !path.includes('//')
+    && !path.split('/').some((part) => part === '' || part === '.' || part === '..')
+    && !posix.isAbsolute(path)
+    && !/^[a-zA-Z]:/.test(path)
+    && posix.normalize(path) === path;
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function display(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
 }
 
 /**
@@ -90,7 +257,10 @@ export function filesForInstallRole(manifest, installRole = CONSUMER_INSTALL_ROL
 /** Map a manifest's file list (under `key`) by `path` for quick lookup. */
 export function indexByPath(manifest, key) {
   const idx = new Map();
-  for (const entry of (manifest?.[key] ?? [])) idx.set(entry.path, entry);
+  for (const entry of (manifest?.[key] ?? [])) {
+    if (idx.has(entry.path)) throw new Error(`duplicate manifest path: ${entry.path}`);
+    idx.set(entry.path, entry);
+  }
   return idx;
 }
 

package/src/lib/projectSkillExtension.mjs

@@ -6,6 +6,70 @@ 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-]+) -->$/;
 
+function meaningfulSectionBody(lines) {
+  const body = lines.join('\n').replace(/<!--[\s\S]*?-->/g, '');
+  const content = [];
+  let fence = null;
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.trim();
+    const delimiter = /^(`{3,}|~{3,})/.exec(line)?.[1];
+    if (delimiter && !fence) {
+      fence = { character: delimiter[0], length: delimiter.length };
+      continue;
+    }
+    if (fence && new RegExp(`^\\${fence.character}{${fence.length},}\\s*$`).test(line)) {
+      fence = null;
+      continue;
+    }
+    if (line && !/^#{1,6}\s+/.test(line)) content.push(line);
+  }
+  const meaningful = content
+    .filter((line) =>
+      !/^(?:(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?)?(?:TODO|TBD)(?:[.!:]*)$/i.test(line)
+      && !/^<\/?[^>\n]+>$/.test(line)
+      && !/^<(?:placeholder|fill|configure|add)(?:\s+[^>]*)?>[.!:]*$/i.test(line)
+      && !/^(?:Run|Use|Configure|Add|Replace)\s+`?<[^>]+>`?[.!:]*$/i.test(line))
+    .join('\n');
+  return meaningful.trim();
+}
+
+function sectionBodies(body, path) {
+  const sections = new Map();
+  let current = null;
+  for (const line of body.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      if (sections.has(heading[1])) {
+        throw new Error(`Project extension has duplicate section ${heading[1]} at ${path}`);
+      }
+      current = [];
+      sections.set(heading[1], current);
+    } else if (current) {
+      current.push(line);
+    }
+  }
+  return sections;
+}
+
+export function validateProjectSkillActivation(activation, path) {
+  if (activation === undefined) return null;
+  if (!activation || typeof activation !== 'object' || Array.isArray(activation)
+      || activation.mode !== 'all-sections-filled'
+      || !Array.isArray(activation.sections) || !activation.sections.length
+      || activation.sections.some((section) =>
+        typeof section !== 'string' || !section.trim())
+      || new Set(activation.sections).size !== activation.sections.length) {
+    throw new Error(`Project extension activation policy is invalid at ${path}`);
+  }
+  return activation.sections;
+}
+
+function unfilledSections(body, requiredSections, path) {
+  const sections = sectionBodies(body, path);
+  return requiredSections.filter((name) =>
+    !sections.has(name) || !meaningfulSectionBody(sections.get(name)));
+}
+
 export function projectSkillExtensionPath(skill) {
   if (typeof skill !== 'string' || !SKILL_NAME.test(skill)) {
     throw new Error(`invalid Project extension skill identity: ${skill}`);
@@ -13,8 +77,9 @@ export function projectSkillExtensionPath(skill) {
   return `docs/agents/skills/${skill}.md`;
 }
 
-export async function inspectProjectSkillExtension({ root, skill }) {
+export async function inspectProjectSkillExtension({ root, skill, activation }) {
   const path = projectSkillExtensionPath(skill);
+  const requiredSections = validateProjectSkillActivation(activation, path);
   const absolute = join(root, path);
   let state;
   try {
@@ -50,6 +115,18 @@ export async function inspectProjectSkillExtension({ root, skill }) {
       `found skill=${match[2]}`,
     );
   }
+  if (requiredSections) {
+    const missingSections = unfilledSections(body, requiredSections, path);
+    if (missingSections.length) {
+      return {
+        state: 'inactive',
+        reason: 'sections-unfilled',
+        schemaVersion: 1,
+        path,
+        missingSections,
+      };
+    }
+  }
   const content = lines.filter(
     (line) => line && line !== markerLine && !line.startsWith('<!-- setup-workflow:'),
   );

package/src/lib/updateCandidate.mjs

@@ -13,7 +13,7 @@ import { stubSentinel } from './sentinel.mjs';
 import { STUB_TARGETS } from './bundle.mjs';
 import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
-  filesForInstallRole, indexByPath, readManifest, writeManifest,
+  filesForInstallRole, indexByPath, readManifest, validateManifest, writeManifest,
 } from './manifest.mjs';
 import {
   PROJECT_SKILL_REGISTRY_PATH, emptyProjectSkillRegistry, migrateLegacySkillRegistry,
@@ -38,6 +38,7 @@ export async function materializeUpdateCandidate({
   consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
   afterInputValidation = async () => {},
 }) {
+  validateManifest(pkg, { kind: 'package', path: 'update package manifest' });
   const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
   try {
     const paths = candidateInputPaths({
@@ -208,6 +209,7 @@ export async function activateCandidate({
   afterSnapshot = async () => {}, afterGenerated = async () => {},
   beforeTargetRevalidation = async () => {},
 }) {
+  validateManifest(pkg, { kind: 'package', path: 'update package manifest' });
   const changed = [...preview.added, ...preview.updated];
   const generated = preview.generated ?? [];
   const migrations = preview.migrations ?? [];

package/src/lib/updateDecisions.mjs

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

package/src/lib/verifyUpdateCandidateProtocol.mjs

@@ -2,6 +2,10 @@ 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 {
+  projectSkillExtensionPath,
+  validateProjectSkillActivation,
+} from './projectSkillExtension.mjs';
 import { readComposedSkillRegistry } from './skillRegistry.mjs';
 
 const READINESS_MANIFEST_PATH = '.claude/skills/skill-manifest.json';
@@ -52,6 +56,17 @@ function validateReadinessManifest(manifest) {
         throw new Error(`candidate invariant schema: unsafe capability path ${name}`);
       }
     }
+    if (evidence.type === 'project-extension') {
+      try {
+        const expected = projectSkillExtensionPath(evidence.skill);
+        if (evidence.paths.length !== 1 || evidence.paths[0] !== expected) {
+          throw new Error('path mismatch');
+        }
+        validateProjectSkillActivation(evidence.activation, expected);
+      } catch {
+        throw new Error(`candidate invariant schema: invalid capability evidence ${name}`);
+      }
+    }
   }
   for (const [name, skill] of Object.entries(manifest.skills)) {
     const readiness = skill?.readiness ?? {};