@ikon85/agent-workflow-kit 0.34.6 → 0.36.0

package/docs/agents/skills/local-ci.md

@@ -1,4 +1,5 @@
 <!-- setup-workflow: state=filled -->
+<!-- agent-workflow-kit: project-extension/v1; skill=local-ci -->
 # Project layer — local-ci
 
 This repo is a Node + stdlib-Python repo with no database, no dev server and no

package/docs/agents/skills/orchestrate-wave.md

@@ -1,4 +1,5 @@
 <!-- setup-workflow: state=filled -->
+<!-- agent-workflow-kit: project-extension/v1; skill=orchestrate-wave -->
 # Project layer — orchestrate-wave
 
 These stable sections are intentionally empty until the kit has proven its own landing recipe. The skill uses its generic fallback meanwhile.
@@ -10,4 +11,3 @@ These stable sections are intentionally empty until the kit has proven its own l
 ## §Verify Recipe
 ## §Headless Login
 ## §Landing
-

package/docs/agents/skills/spec-self-critique.md

@@ -1,4 +1,5 @@
 <!-- setup-workflow: state=filled -->
+<!-- agent-workflow-kit: project-extension/v1; skill=spec-self-critique -->
 # Project layer — spec-self-critique
 
 The generic checklist owns the checks; `/retro` appends project-specific incidents below these stable anchors.
@@ -15,4 +16,3 @@ The generic checklist owns the checks; `/retro` appends project-specific inciden
 ## Point 10
 ## Point 11
 ## Point 12
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.6",
+  "version": "0.36.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/find-by-marker.py

@@ -29,6 +29,8 @@ def _gh(args: list[str]) -> str:
     except subprocess.TimeoutExpired as exc:
         raise RuntimeError(
             f"gh api timed out after {GH_TIMEOUT_SECONDS}s") from exc
+    except OSError as exc:
+        raise RuntimeError(f"gh CLI unavailable: {exc.strerror or exc}") from exc
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or "gh api failed")
     return result.stdout

package/scripts/project-skill-extension.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inspectProjectSkillExtension } from '../src/lib/projectSkillExtension.mjs';
+
+function argumentsFor(argv) {
+  const args = [...argv];
+  if (args.shift() !== 'inspect') {
+    throw new Error('usage: project-skill-extension.mjs inspect --skill <name> [--root <path>] --json');
+  }
+  const options = { root: process.cwd(), json: false };
+  while (args.length) {
+    const flag = args.shift();
+    if (flag === '--skill') options.skill = args.shift();
+    else if (flag === '--root') options.root = resolve(args.shift());
+    else if (flag === '--json') options.json = true;
+    else throw new Error(`unknown option: ${flag}`);
+  }
+  if (!options.skill) throw new Error('--skill is required');
+  if (!options.json) throw new Error('--json is required');
+  return options;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = argumentsFor(argv);
+  return inspectProjectSkillExtension(options);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().then(
+    (result) => console.log(JSON.stringify(result)),
+    (error) => {
+      console.log(JSON.stringify({ state: 'blocked', diagnostic: error.message }));
+      process.exitCode = 1;
+    },
+  );
+}

package/scripts/readiness.mjs

@@ -4,6 +4,7 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { firstLineState } from '../src/lib/sentinel.mjs';
 import { CONSUMER_MANIFEST_NAME, readManifest, writeManifest } from '../src/lib/manifest.mjs';
+import { readComposedSkillRegistry } from '../src/lib/skillRegistry.mjs';
 
 const SOURCE_MANIFEST = '.claude/skills/skill-manifest.json';
 const DECISIONS = new Set(['pending', 'not-applicable']);
@@ -176,7 +177,7 @@ export async function evaluateCapability({ root, capability, decision }) {
 async function loadManifest(root) {
   const body = await readText(root, SOURCE_MANIFEST);
   if (body === null) throw new Error(`readiness manifest not found: ${SOURCE_MANIFEST}`);
-  return JSON.parse(body);
+  return readComposedSkillRegistry(root, JSON.parse(body));
 }
 
 export async function checkSkill({ root, skill, manifest }) {

package/scripts/test_marker_lib.py

@@ -149,6 +149,14 @@ class MarkerLookupTest(unittest.TestCase):
             with self.assertRaisesRegex(RuntimeError, "timed out after 30s"):
                 cli._gh(["api", "--paginate", "repos/example/repo/issues"])
 
+    def test_cli_classifies_a_missing_github_binary(self):
+        with patch.object(
+            cli.subprocess, "run",
+            side_effect=FileNotFoundError(2, "No such file or directory", "gh"),
+        ):
+            with self.assertRaisesRegex(RuntimeError, "gh CLI unavailable"):
+                cli._gh(["api", "--paginate", "repos/example/repo/issues"])
+
 
 if __name__ == "__main__":
     unittest.main()

package/scripts/test_retro_wrapup_contract.py

@@ -42,13 +42,15 @@ class RetroEnforcementContract(unittest.TestCase):
                 for phrase in required:
                     self.assertIn(phrase, text)
 
-    def test_upstream_or_own_and_exact_sanitized_approval_survive(self):
+    def test_capability_route_and_exact_sanitized_approval_survive(self):
         required = (
             "generic or project-specific",
             "recommend `own`",
-            "sanitized preview",
-            "explicitly approves that exact text",
-            "does not need to be the kit maintainer",
+            "contribute status <path> --surface=retro",
+            "Missing, disabled, invalid, or unverifiable configuration",
+            "never infer maintainer status",
+            "sanitized exact preview",
+            "separate explicit approval",
             "docs/agents/skills/<skill>.md",
         )
         for surface in SURFACES:

package/scripts/test_skill_publish_audit.py

@@ -94,7 +94,7 @@ BARE_PRIVATE = [
 ]
 PARENT_REF = re.compile(r"\.\./")
 SHIPPED_SRC_IMPORT = re.compile(
-    r"^\s*import\b.*\bfrom\s+['\"]\.\./src/lib/[a-z0-9-]+\.mjs['\"];\s*$"
+    r"^\s*import\b.*\bfrom\s+['\"]\.\./src/lib/[A-Za-z0-9-]+\.mjs['\"];\s*$"
 )
 LONG_HEX = re.compile(r"\b[0-9a-f]{40,}\b")
 GH_TOKEN = re.compile(r"\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}")
@@ -317,6 +317,14 @@ class Exemptions(unittest.TestCase):
             encoding="utf-8")
         self.assertEqual(audit_dir(self.dir), [])
 
+    def test_top_level_script_may_import_camel_case_shipped_deep_module(self):
+        p = self.dir / "scripts"
+        p.mkdir()
+        (p / "readiness.mjs").write_text(
+            "import { load } from '../src/lib/skillRegistry.mjs';\n",
+            encoding="utf-8")
+        self.assertEqual(audit_dir(self.dir), [])
+
 
 class RealDistKitIsClean(unittest.TestCase):
     """Build dist-kit/ from SSOT and assert the audit passes (the publish gate)."""

package/src/cli.mjs

@@ -7,7 +7,14 @@ import { renderUpdateFailure, update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { setOwnership } from './commands/own.mjs';
+import {
+  beginContributionBridge, prepareContributionArtifact,
+} from './lib/contributionBridge.mjs';
+import {
+  inspectContributionRouting,
+} from './lib/contributionRouting.mjs';
 import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
+import { nonInteractiveUpdateDecision } from './lib/updateDecisions.mjs';
 import { currentAgentSurface } from './lib/agentSurfaceRegistry.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
@@ -25,6 +32,7 @@ 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);
 
 p.intro('agent-workflow-kit');
 
@@ -49,7 +57,9 @@ try {
     printPlan(r);
     p.outro('Dry run — nothing written. Run `update` to apply.');
   } else if (cmd === 'update') {
-    const decide = (action, path) => decideUpdate(action, path, yes);
+    const decide = (action, path, classification) => (
+      decideUpdate(action, path, yes, classification)
+    );
     const releaseIdentities = await readUpdateRelease();
     const r = await update({
       kitRoot: KIT_ROOT,
@@ -65,7 +75,10 @@ try {
     if (r.state === 'failed') throw new Error(renderUpdateFailure(r));
     if (r.state === 'conflicted') {
       p.note(r.report.recommendation, 'recommendation');
-      p.outro(`not applied · conflicts ${r.conflicts.length}`);
+      p.outro(
+        `not applied · conflicts ${r.conflicts.length} · ` +
+        `ownership collisions ${r.collisions.length}`,
+      );
       process.exitCode = 2;
     } else if (r.status === 'current') {
       p.outro(`aktuell · unchanged ${r.unchanged.length} · local modifications ${r.userModified.length}`);
@@ -77,13 +90,70 @@ try {
     if (!ok) { p.cancel('Aborted.'); process.exit(0); }
     const r = await uninstall({ consumerRoot });
     p.outro(`removed ${r.removed.length} · retained (edited/referenced) ${r.retained.length}`);
+  } else if (cmd === 'contribute') {
+    const action = args[1];
+    const path = args[2];
+    if (!['start', 'status', 'prepare'].includes(action) || !path) {
+      throw new Error(
+        'Usage: agent-workflow-kit contribute <start|status|prepare> <path> ' +
+        '[--surface=retro|pre-update|guard] ' +
+        '[--output=.agent-workflow-kit/contributions/<name>.json]',
+      );
+    }
+    if (action === 'start') {
+      await beginContributionBridge({ kitRoot: KIT_ROOT, 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='))
+        ?.slice('--surface='.length) ?? 'guard';
+      const routing = await inspectContributionRouting({
+        consumerRoot, path, surface,
+      });
+      p.note(
+        [
+          `lifecycle: ${routing.lifecycleState}`,
+          `capability: ${routing.capabilityState}`,
+          `routes: ${routing.routes.map(({ id }) => id).join(', ')}`,
+          ...(routing.diagnostic ? [`diagnostic: ${routing.diagnostic}`] : []),
+        ].join('\n'),
+        `contribution routing (${routing.surface})`,
+      );
+      p.outro('read-only routing report; no local or remote state changed');
+    } else {
+      const output = args.find((arg) => arg.startsWith('--output='))?.slice('--output='.length);
+      if (!output) throw new Error('contribute prepare requires --output=<path>');
+      const routing = await inspectContributionRouting({
+        consumerRoot, path, surface: 'guard',
+      });
+      if (!routing.routes.some(({ id }) => id === 'prepare-local')) {
+        throw new Error(
+          `local contribution preparation is unavailable: ${routing.capabilityState}` +
+          (routing.diagnostic ? ` (${routing.diagnostic})` : ''),
+        );
+      }
+      await prepareContributionArtifact({
+        kitRoot: KIT_ROOT, consumerRoot, path, output,
+      });
+      p.outro(`prepared local contribution artifact ${output}; no remote was changed`);
+    }
   } else if (cmd === 'own' || cmd === 'disown') {
-    if (!args[1]) throw new Error(`Usage: agent-workflow-kit ${cmd} <path>`);
+    if (!args[1]) {
+      throw new Error(
+        `Usage: agent-workflow-kit ${cmd} <path>` +
+        (cmd === 'own' ? ' [--as=explicit-fork]' : ''),
+      );
+    }
     const origin = cmd === 'own' ? CONSUMER_ORIGIN : KIT_ORIGIN;
-    await setOwnership({ consumerRoot, path: args[1], origin });
-    p.outro(`${args[1]} is now ${origin}-owned`);
+    if (origin === CONSUMER_ORIGIN && ownershipState === 'contribution-bridge') {
+      await beginContributionBridge({ kitRoot: KIT_ROOT, consumerRoot, path: args[1] });
+    } else {
+      await setOwnership({ consumerRoot, path: args[1], origin, ownershipState });
+    }
+    p.outro(`${args[1]} is now ${origin}-owned` +
+      (origin === CONSUMER_ORIGIN ? ` (${ownershipState ?? 'explicit-fork'})` : ''));
   } else {
-    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown> [<path>] [--force] [--yes] [--owned]');
+    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown|contribute> ' +
+      '[<path>] [--force] [--yes] [--owned] [--as=contribution-bridge|explicit-fork]');
     p.outro('');
   }
 } catch (err) {
@@ -96,6 +166,7 @@ function printPlan(r) {
   for (const k of [
     'added', 'updated', 'userModified', 'consumerOwned', 'unchanged',
     'deleted', 'keptDeleted', 'collisions', 'migrated',
+    'bridgeRetired',
   ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
@@ -119,18 +190,21 @@ function printPlan(r) {
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
 
-async function decideUpdate(action, path, yes) {
+async function decideUpdate(action, path, yes, classification) {
+  if (yes) return nonInteractiveUpdateDecision(action);
   if (action === 'delete') {
-    if (yes) return true;
     return (await p.confirm({ message: `Upstream removed ${path} — delete it locally?` })) === true;
   }
   if (action === 'collision') {
-    if (yes) return 'replace';
     const choice = await p.select({
-      message: `${path} already exists but is not tracked. Choose its ownership:`,
+      message: `${path} exists without ownership evidence. Choose an explicit route:`,
       options: [
-        { value: 'keep-as-owned', label: 'Keep existing file as consumer-owned' },
-        { value: 'replace', label: 'Replace with kit file' },
+        ...(classification?.state === 'project-extension'
+          ? [{ value: 'project-extension', label: 'Keep as declared Project extension' }]
+          : []),
+        { value: 'contribution-bridge', label: 'Keep as temporary contribution bridge' },
+        { value: 'explicit-fork', label: 'Keep as explicit fork' },
+        { value: 'replace', label: 'Replace explicitly with Kit Core' },
       ],
     });
     if (p.isCancel(choice)) throw new Error(`collision decision cancelled for ${path}`);

package/src/commands/init.mjs

@@ -9,9 +9,13 @@ import {
   filesForInstallRole, CONSUMER_INSTALL_ROLE,
   indexByPath,
   readReadinessContract,
+  READINESS_MANIFEST_PATH,
   CONSUMER_ORIGIN,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
+import {
+  PROJECT_SKILL_REGISTRY_PATH, emptyProjectSkillRegistry,
+} from '../lib/skillRegistry.mjs';
 import {
   inspectRoutingProfile, reconcileRoutingProfile, setupRoutingProfile,
 } from '../lib/routingProfile.mjs';
@@ -71,6 +75,26 @@ export async function init({ kitRoot, consumerRoot, force = false, routingProfil
     result.copied.push(f.path);
   }
 
+  if (packageIdx.has(READINESS_MANIFEST_PATH)
+      && !installed.some(({ path }) => path === PROJECT_SKILL_REGISTRY_PATH)) {
+    const projectRegistryPath = join(consumerRoot, PROJECT_SKILL_REGISTRY_PATH);
+    if (!await exists(projectRegistryPath)) {
+      const core = await readManifest(join(kitRoot, READINESS_MANIFEST_PATH));
+      await writeAtomic(
+        projectRegistryPath,
+        `${JSON.stringify(emptyProjectSkillRegistry(core), null, 2)}\n`,
+      );
+      result.seeded.push(PROJECT_SKILL_REGISTRY_PATH);
+    }
+    installed.push({
+      path: PROJECT_SKILL_REGISTRY_PATH,
+      kind: 'doc',
+      installedSha256: await sha256File(projectRegistryPath),
+      origin: CONSUMER_ORIGIN,
+      installRole: CONSUMER_INSTALL_ROLE,
+    });
+  }
+
   await writeManifest(
     join(consumerRoot, CONSUMER_MANIFEST_NAME),
     { ...emptyConsumerManifest(pkg.kitVersion, prior, readiness), installed }

package/src/commands/own.mjs

@@ -5,12 +5,16 @@ import {
 } from '../lib/manifest.mjs';
 
 /** Mark one tracked consumer file as kit- or consumer-owned. */
-export async function setOwnership({ consumerRoot, path, origin }) {
+export async function setOwnership({ consumerRoot, path, origin, ownershipState }) {
+  if (origin === 'consumer' && ownershipState === 'contribution-bridge') {
+    throw new Error('contribution bridge requires `contribute start` with Kit provenance');
+  }
   const manifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
   const manifest = await readManifest(manifestPath);
   if (!manifest) throw new Error('not initialised — run `init` first');
-  const next = withOrigin(manifest, path, origin);
+  const next = withOrigin(manifest, path, origin, ownershipState);
   await validateConsumerFile(consumerRoot, path);
   await writeManifest(manifestPath, next);
-  return { path, origin };
+  return { path, origin, ownershipState: origin === 'consumer'
+    ? (ownershipState ?? 'explicit-fork') : undefined };
 }

package/src/commands/update.mjs

@@ -9,7 +9,7 @@ import {
 } from '../lib/verifyUpdateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
-  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
+  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, PROJECT_SKILL_REGISTRY_PATH, readManifest,
 } from '../lib/manifest.mjs';
 import {
   inspectRoutingProfile, reconcileRoutingProfile,
@@ -81,11 +81,7 @@ async function updatePackage(options) {
     Object.assign(preview, await previewReadinessAdoption({
       kitRoot, consumerRoot, pkg, priorReadinessManifest, nextReadinessManifest,
     }));
-    preview.conflicts.push(...(preview.migrationConflicts ?? []).map((path) => ({
-      path,
-      kind: 'prod-section',
-      diff: 'Prod section differs from the other instruction surface or is malformed.',
-    })));
+    preview.conflicts.push(...(preview.migrationConflicts ?? []).map(migrationConflictRecord));
   } catch (error) {
     previewFailure = error;
   }
@@ -104,6 +100,9 @@ async function updatePackage(options) {
   const resolvedPreview = await resolvePreview({
     kitRoot, consumerRoot, preview, decisions, decide, transition,
   });
+  if (resolvedPreview.collisions.length) {
+    return terminal(resolvedPreview, 'conflicted', history, transition);
+  }
   if (resolvedPreview.conflicts.length) {
     return terminal(resolvedPreview, 'conflicted', history, transition);
   }
@@ -129,13 +128,19 @@ async function previewReadinessAdoption(context) {
       kitRoot, consumerRoot: candidateRoot,
       decide: (action) => action === 'collision' ? 'keep-as-owned' : false,
     });
-    await verifyCandidateSchema(candidateRoot, {
-      pkg, preview: candidatePreview, priorReadinessManifest, nextReadinessManifest,
-    });
-    return await adoptReadinessCandidate({
-      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+    const readiness = await adoptReadinessCandidate({
+      candidateRoot, consumerRoot, kitRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
     });
+    candidatePreview.generated = readiness.generated;
+    candidatePreview.migrations = readiness.migrations;
+    candidatePreview.migrated = readiness.migrated;
+    if (!readiness.migrationConflicts.length) {
+      await verifyCandidateSchema(candidateRoot, {
+        pkg, preview: candidatePreview, priorReadinessManifest, nextReadinessManifest,
+      });
+    }
+    return readiness;
   } finally {
     await rm(candidateRoot, { recursive: true, force: true });
   }
@@ -146,7 +151,13 @@ async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decid
     await transition('awaiting_decision');
   }
   for (const path of preview.collisions) {
-    decisions.set(decisionKey('collision', path), await decide('collision', path));
+    const classification = preview.ownershipStates?.find(
+      (candidate) => candidate.path === path,
+    );
+    decisions.set(
+      decisionKey('collision', path),
+      await decide('collision', path, classification),
+    );
   }
   if (!preview.collisions.length) return preview;
   return reconcile({
@@ -192,9 +203,8 @@ async function applyTransaction(context) {
       priorReadinessManifest: structuredClone(priorReadinessManifest),
       nextReadinessManifest: structuredClone(nextReadinessManifest),
     };
-    await verifyCandidateSchema(candidateRoot, canonicalContext);
     const readiness = await adoptReadinessCandidate({
-      candidateRoot, consumerRoot, priorManifest: priorReadinessManifest,
+      candidateRoot, consumerRoot, kitRoot, priorManifest: priorReadinessManifest,
       nextManifest: nextReadinessManifest,
     });
     preview.generated = readiness.generated;
@@ -203,12 +213,13 @@ async function applyTransaction(context) {
     preview.migrationConflicts = readiness.migrationConflicts;
     preview.availability = readiness.availability;
     if (readiness.migrationConflicts.length) {
-      throw new Error(`Prod section migration conflict: ${readiness.migrationConflicts.join(', ')}`);
+      throw new Error(`readiness migration conflict: ${readiness.migrationConflicts.join(', ')}`);
     }
     if (readiness.incompatible.length) {
       throw new Error(`monotonic compatibility would block existing skill core: ${readiness.incompatible.join(', ')}`);
     }
     canonicalContext.preview = structuredClone(preview);
+    await verifyCandidateSchema(candidateRoot, canonicalContext);
     await verifyUpdateCandidate(candidateRoot, canonicalContext);
     if (verify !== verifyUpdateCandidate) {
       const extensionContext = structuredClone(canonicalContext);
@@ -249,6 +260,7 @@ function verifyRelease(identities, kitVersion) {
 function hasUpstreamDelta(result) {
   return result.manifestChanged ||
     (result.migrations?.length ?? 0) > 0 ||
+    (result.bridgeRetired?.length ?? 0) > 0 ||
     result.added.length + result.updated.length + result.deleted.length > 0;
 }
 
@@ -274,14 +286,68 @@ async function terminal(result, state, history, transition) {
         conflicts: result.conflicts.map(({ path }) => path),
         keptDeleted: result.keptDeleted,
       },
-      recommendation: result.migrationConflicts?.length
-        ? `Prod sections differ or are malformed in: ${result.migrationConflicts.join(', ')}. ` +
-          'Resolve them manually; no consumer file was changed.'
-        : (result.conflicts.length
-          ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
-          : null),
+      recommendation: updateRecommendation(result),
     },
   };
 }
 
+function updateRecommendation(result) {
+  if (result.migrationConflicts?.length) {
+    return migrationRecommendation(result.migrationConflicts);
+  }
+  if (result.collisions.length
+      || result.conflicts.some(({ kind }) => kind === 'ownership-lifecycle')) {
+    return ownershipRecommendation(result);
+  }
+  return result.conflicts.length
+    ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
+    : null;
+}
+
+function migrationConflictRecord(detail) {
+  const path = detail.split(': ', 1)[0];
+  const projectRegistry = path === PROJECT_SKILL_REGISTRY_PATH
+    || path === '.claude/skills/skill-manifest.json';
+  return {
+    path,
+    kind: projectRegistry ? 'skill-registry' : 'prod-section',
+    diff: projectRegistry
+      ? `Skill registry migration is ambiguous: ${detail}`
+      : 'Prod section differs from the other instruction surface or is malformed.',
+  };
+}
+
+function migrationRecommendation(conflicts) {
+  const registryConflict = conflicts.some((detail) => (
+    detail.startsWith(`${PROJECT_SKILL_REGISTRY_PATH}:`)
+    || detail.startsWith('.claude/skills/skill-manifest.json:')
+  ));
+  return (registryConflict
+    ? `Readiness migration is ambiguous in: ${conflicts.join(', ')}. `
+    : `Prod sections differ or are malformed in: ${conflicts.join(', ')}. `) +
+    'Resolve them manually; no consumer file was changed.';
+}
+
+function ownershipRecommendation(result) {
+  const paths = new Set([
+    ...result.collisions,
+    ...result.conflicts.filter(({ kind }) => kind === 'ownership-lifecycle')
+      .map(({ path }) => path),
+  ]);
+  const unresolved = (result.ownershipStates ?? []).filter(
+    ({ path }) => paths.has(path),
+  );
+  return unresolved.map(({ path, state, evidence, routes }) => (
+    `${path}: ${state} ` +
+    `(package=${evidence.packageDeclared ? 'declared' : 'absent'}, ` +
+    `ledger=${evidence.ledgerOrigin}, destination=${evidence.destination}, ` +
+    `extension=${evidence.projectExtension}` +
+    (evidence.extensionDiagnostic
+      ? `, extensionDiagnostic=${evidence.extensionDiagnostic}` : '') +
+    '); explicit routes: ' +
+    routes.map(({ id, action }) => `${id} (${action})`).join(', ')
+  )).join('\n') +
+    '. No consumer file was changed; --yes cannot choose a route.';
+}
+
 export { verifyUpdateCandidate, verifyUpdateCandidate as verifyCandidate } from '../lib/verifyUpdateCandidate.mjs';

package/src/lib/bundle.mjs

@@ -8,6 +8,7 @@ export const HELPER_FILES = [
   // 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: 'scripts/project-skill-extension.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 },
@@ -77,6 +78,10 @@ export const HELPER_FILES = [
   { path: 'src/lib/reportValidator.mjs', kind: 'script', mode: 0o644 },
   // Fail-closed orchestration selector and its host-inventory adapters.
   { path: 'src/lib/capabilityMatrix.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/skillRegistry.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/projectSkillExtension.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/ownershipClassifier.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/updateDecisions.mjs', kind: 'script', mode: 0o644 },
   // Provider-neutral routing runtime: one Evidence catalog, Access graph,
   // Routing policy, resolver, spawn guard, receipt v2, and surface attestations.
   // These modules form one consumer unit; omitting one leaves shipped dispatch