@ikon85/agent-workflow-kit 0.34.6 → 0.35.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.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/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_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 };
+    }),
   };
 }

package/src/lib/ownershipClassifier.mjs

@@ -0,0 +1,54 @@
+export const OwnershipState = Object.freeze({
+  CLEAN_CORE: 'clean-core',
+  PROJECT_EXTENSION: 'project-extension',
+  CONTRIBUTION_BRIDGE: 'contribution-bridge',
+  EXPLICIT_FORK: 'explicit-fork',
+  AMBIGUOUS_COLLISION: 'ambiguous-collision',
+});
+
+const ROUTES = Object.freeze([
+  { id: 'project-extension', action: 'move Project data to docs/agents/skills/<skill>.md' },
+  { id: 'contribution-bridge', action: 'register a temporary contribution-bridge' },
+  { id: 'explicit-fork', action: 'register an explicit-fork with its own update line' },
+  { id: 'clean-core', action: 'explicitly replace the destination with Kit Core' },
+]);
+
+export function classifyOwnershipEvidence({
+  path, packageEntry, installedEntry, destinationPresent, projectExtension,
+}) {
+  const evidence = {
+    packageDeclared: Boolean(packageEntry),
+    ledgerOrigin: installedEntry?.origin ?? 'absent',
+    destination: destinationPresent ? 'present' : 'absent',
+    projectExtension: projectExtension
+      ? (projectExtension.invalid ? 'invalid' : `schema-v${projectExtension.schemaVersion}`)
+      : 'absent',
+  };
+  if (projectExtension?.invalid) evidence.extensionDiagnostic = projectExtension.invalid;
+  if (installedEntry?.origin === 'kit') {
+    return { path, state: OwnershipState.CLEAN_CORE, evidence, routes: [] };
+  }
+  if (installedEntry?.origin === 'consumer') {
+    const state = installedEntry.ownershipState ?? OwnershipState.EXPLICIT_FORK;
+    if (![
+      OwnershipState.PROJECT_EXTENSION,
+      OwnershipState.CONTRIBUTION_BRIDGE,
+      OwnershipState.EXPLICIT_FORK,
+    ].includes(state)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
+    if (state === OwnershipState.PROJECT_EXTENSION
+        && (!/^docs\/agents\/skills\/[a-z0-9-]+\.md$/.test(path)
+          || !projectExtension || projectExtension.invalid)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
+    return { path, state, evidence, routes: [] };
+  }
+  if (projectExtension && !projectExtension.invalid) {
+    return { path, state: OwnershipState.PROJECT_EXTENSION, evidence, routes: [
+      { id: 'project-extension', action: 'keep the declared Project extension' },
+      { id: 'clean-core', action: 'explicitly replace the destination with Kit Core' },
+    ] };
+  }
+  return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+}

package/src/lib/projectSkillExtension.mjs

@@ -0,0 +1,60 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { firstLineState } from './sentinel.mjs';
+
+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-]+) -->$/;
+
+export function projectSkillExtensionPath(skill) {
+  if (typeof skill !== 'string' || !SKILL_NAME.test(skill)) {
+    throw new Error(`invalid Project extension skill identity: ${skill}`);
+  }
+  return `docs/agents/skills/${skill}.md`;
+}
+
+export async function inspectProjectSkillExtension({ root, skill }) {
+  const path = projectSkillExtensionPath(skill);
+  const absolute = join(root, path);
+  let state;
+  try {
+    state = await lstat(absolute);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'inactive', reason: 'absent' };
+    throw error;
+  }
+  if (!state.isFile()) {
+    throw new Error(`Project extension is not a regular file: ${path}`);
+  }
+  const body = await readFile(absolute, 'utf8');
+  const setupState = firstLineState(body);
+  if (setupState === 'stub' || setupState === 'not-applicable') {
+    return { state: 'inactive', reason: setupState };
+  }
+  const lines = body.split('\n').map((line) => line.trim());
+  const markerLine = lines.find((line) => line.startsWith(MARKER_PREFIX));
+  if (!markerLine) {
+    if (!body.trim()) return { state: 'inactive', reason: 'empty' };
+    return { state: 'active', schemaVersion: 0, path };
+  }
+  const match = MARKER.exec(markerLine);
+  if (!match || match[1] !== 'v1') {
+    throw new Error(
+      `Project extension has unsupported schema at ${path}; ` +
+      `expected project-extension/v1 for skill=${skill}`,
+    );
+  }
+  if (match[2] !== skill) {
+    throw new Error(
+      `Project extension identity mismatch at ${path}; expected skill=${skill}, ` +
+      `found skill=${match[2]}`,
+    );
+  }
+  const content = lines.filter(
+    (line) => line && line !== markerLine && !line.startsWith('<!-- setup-workflow:'),
+  );
+  if (!content.length) {
+    throw new Error(`Project extension has no instructions after its v1 marker: ${path}`);
+  }
+  return { state: 'active', schemaVersion: 1, path };
+}