@ikon85/agent-workflow-kit 0.34.5 → 0.35.0

package/docs/adr/0004-release-intent-is-a-version-tag.md

@@ -6,6 +6,17 @@ Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
 authorize deterministic reversible release preparation, but never the
 publication tag itself.
 
+Amended 2026-07-25 by issue #257: the confirmed Semver authorizes the whole
+release, through tag and publish. The separation of integration and publication
+below is unchanged — merging still cannot publish, and only an annotated tag
+records release intent — but that intent no longer waits for a second human
+confirmation. The maintainer chooses the version once; the agent then merges,
+tags, and monitors to `released`. The second gate had proven worse than no gate:
+it left prepared versions sitting in `awaiting-tag` until someone returned,
+which is how 0.34.2 was skipped and buried under 0.34.3 (#243). Safety stays in
+the gates that run regardless of who is watching — guard, staleness, suite,
+pack, and the workflow's own tag/version/ancestry validation.
+
 The release workflow currently publishes whenever a merge to `main` changes
 `package.json`. That keeps the canonical branch and npm close together, but it
 also makes an ordinary merge an irreversible public action whose consequence is
@@ -39,11 +50,13 @@ We decided that integration and publication are separate transitions:
 
 ## Consequences
 
-- A prepared version may temporarily exist on `main` in an `awaiting-tag` state.
-- An explicit AFK Wave/Program mandate may cover the deterministic reversible
-  metadata preparation and landing that it names. It never by itself authorizes
-  creating or pushing the publication tag; that irreversible action requires a
-  separate explicit confirmation.
+- A prepared version exists on `main` in an `awaiting-tag` state only for as
+  long as the agent needs to tag it — not until a human returns (amended by
+  #257).
+- The authorizing act is the confirmed Semver. An explicit AFK Wave/Program
+  mandate that names release preparation carries the same weight, and either
+  route reaches through tag and publish for that one target. A narrower
+  build-only or single-action request never becomes this authority.
 - A single-Wave mandate does not authorize the next Program Wave. A later
   explicit whole-Program mandate does authorize all planned Waves and remains in
   force across their boundaries.

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.5",
+  "version": "0.35.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/kit-release.test.mjs

@@ -184,15 +184,21 @@ test('both release skill surfaces name only the owned scoped npm package', async
   }
 });
 
-test('an explicit AFK scope can authorize reversible preparation but never publication', async () => {
+// Amended by #257: one gate, at the Semver. The previous contract required a
+// second confirmation before the tag; that gate left prepared versions stranded
+// in `awaiting-tag` and is gone. What must survive is the narrowing rule — a
+// build-only request never becomes release authority.
+test('one confirmed Semver authorizes the release through tag and publish', async () => {
   const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
   const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
-  assert.equal(codex, claude);
+  assert.equal(codex.split('\n---\n')[1], claude.split('\n---\n')[1]);
   for (const body of [claude, codex]) {
     assert.match(body, /explicit AFK end-to-end mandate/i);
     assert.match(body, /deterministic recommendation/i);
-    assert.match(body, /reversible metadata preparation/i);
-    assert.match(body, /annotated `v<version>` tag[\s\S]*separate explicit confirmation/i);
+    assert.match(body, /annotated\s+`v<version>` tag/i);
+    assert.match(body, /confirmed Semver authorizes[\s\S]*without asking again/i);
+    assert.match(body, /narrower build-only or single-action request/i);
+    assert.doesNotMatch(body, /separate explicit confirmation/i);
   }
 });
 

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_release_authorization_contract.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Release-authorization contract (#257).
+
+The confirmed Semver authorizes the whole release, through tag and publish.
+One human gate at version choice, not two — the second gate stalled every
+release at `awaiting-tag` until someone returned, which is how 0.34.2 was
+skipped and buried under 0.34.3 (#243).
+
+What this pins:
+
+- Both `kit-release` surfaces carry the carried-through authorization, and
+  neither demands a separate confirmation before tagging.
+- The safety framing survives the change: irreversibility and the pre-tag
+  gates stay named, so autonomy never reads as "tag whatever".
+- `CLAUDE.md`, `AGENTS.md` and ADR-0004 agree with the skill.
+
+Run: python3 scripts/test_release_authorization_contract.py
+"""
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude/skills/kit-release/SKILL.md", ".agents/skills/kit-release/SKILL.md")
+ADR = "docs/adr/0004-release-intent-is-a-version-tag.md"
+DOCTRINE_FILES = ("CLAUDE.md", "AGENTS.md")
+# Wording that would reinstate the second gate anywhere in the release surface.
+SECOND_GATE = (
+    "separate explicit confirmation",
+    "separately confirmed publication intent",
+    "obtain a separate",
+    "After that confirmation",
+)
+
+
+def read(relative: str) -> str:
+    return (ROOT / relative).read_text(encoding="utf-8")
+
+
+def normalized(relative: str) -> str:
+    return " ".join(read(relative).split())
+
+
+class SkillSurfaceContract(unittest.TestCase):
+    def test_both_surfaces_carry_the_authorization_through_to_the_tag(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("confirmed Semver authorizes", prose)
+                self.assertIn("tag and publish", prose)
+                self.assertIn("without asking again", prose)
+
+    def test_no_surface_reinstates_a_second_confirmation_gate(self):
+        for surface in SURFACES:
+            for phrase in SECOND_GATE:
+                with self.subTest(surface=surface, phrase=phrase):
+                    self.assertNotIn(phrase, normalized(surface))
+
+    def test_autonomy_never_drops_the_safety_framing(self):
+        """Tagging stays irreversible and gated — the gates just move earlier."""
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("irreversible", prose)
+                self.assertIn("cannot be reused", prose)
+                for gate in ("release:guard", "kit:staleness", "npm pack"):
+                    self.assertIn(gate, prose)
+
+    def test_the_tag_remains_the_sole_publication_intent(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                prose = normalized(surface)
+                self.assertIn("Merging integrates", prose)
+                self.assertIn("annotated", prose)
+
+    def test_both_surfaces_stay_mirrored_below_the_frontmatter(self):
+        bodies = [read(surface).split("\n---\n", 1)[1] for surface in SURFACES]
+        self.assertEqual(bodies[0], bodies[1])
+
+
+class ProjectDoctrineContract(unittest.TestCase):
+    def test_root_convention_files_agree_with_the_skill(self):
+        for name in DOCTRINE_FILES:
+            with self.subTest(document=name):
+                prose = normalized(name)
+                self.assertIn("confirmed Semver authorizes", prose)
+                for phrase in SECOND_GATE:
+                    self.assertNotIn(phrase, prose)
+
+    def test_the_adr_records_an_amendment_instead_of_a_silent_rewrite(self):
+        prose = normalized(ADR)
+        self.assertIn("Amended", prose)
+        self.assertIn("2026-07-25", prose)
+        self.assertIn("confirmed Semver authorizes", prose)
+        # The original decision must remain readable, not be overwritten.
+        self.assertIn("version tag", prose)
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -8,6 +8,7 @@ import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { setOwnership } from './commands/own.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 +26,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 +51,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 +69,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}`);
@@ -78,12 +85,19 @@ try {
     const r = await uninstall({ consumerRoot });
     p.outro(`removed ${r.removed.length} · retained (edited/referenced) ${r.retained.length}`);
   } 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=contribution-bridge|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`);
+    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> ' +
+      '[<path>] [--force] [--yes] [--owned] [--as=contribution-bridge|explicit-fork]');
     p.outro('');
   }
 } catch (err) {
@@ -119,18 +133,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,13 @@ 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 }) {
   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);
@@ -274,14 +285,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

package/src/lib/manifest.mjs

@@ -18,6 +18,7 @@ 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';
+export { PROJECT_SKILL_REGISTRY_PATH } from './skillRegistry.mjs';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -94,7 +95,7 @@ export function indexByPath(manifest, key) {
 }
 
 /** Return a manifest with one tracked entry moved to the requested ownership state. */
-export function withOrigin(manifest, path, origin) {
+export function withOrigin(manifest, path, origin, ownershipState = 'explicit-fork') {
   if (![KIT_ORIGIN, CONSUMER_ORIGIN].includes(origin)) {
     throw new Error(`invalid manifest origin: ${origin}`);
   }
@@ -105,6 +106,16 @@ export function withOrigin(manifest, path, origin) {
   }
   return {
     ...manifest,
-    installed: manifest.installed.map((entry) => entry.path === path ? { ...entry, origin } : entry),
+    installed: manifest.installed.map((entry) => {
+      if (entry.path !== path) return entry;
+      if (origin === KIT_ORIGIN) {
+        const { ownershipState: _removed, ...core } = entry;
+        return { ...core, origin };
+      }
+      if (!['contribution-bridge', 'explicit-fork'].includes(ownershipState)) {
+        throw new Error(`invalid consumer ownership state: ${ownershipState}`);
+      }
+      return { ...entry, origin, ownershipState };
+    }),
   };
 }