@ikon85/agent-workflow-kit 0.35.0 → 0.36.1

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/src/cli.mjs

@@ -7,6 +7,12 @@ 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';
@@ -84,19 +90,69 @@ 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>` +
-        (cmd === 'own' ? ' [--as=contribution-bridge|explicit-fork]' : ''),
+        (cmd === 'own' ? ' [--as=explicit-fork]' : ''),
       );
     }
     const origin = cmd === 'own' ? CONSUMER_ORIGIN : KIT_ORIGIN;
-    await setOwnership({ consumerRoot, path: args[1], origin, ownershipState });
+    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> ' +
+    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown|contribute> ' +
       '[<path>] [--force] [--yes] [--owned] [--as=contribution-bridge|explicit-fork]');
     p.outro('');
   }
@@ -110,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}`);

package/src/commands/own.mjs

@@ -3,14 +3,23 @@ import { validateConsumerFile } from '../lib/consumerPath.mjs';
 import {
   CONSUMER_MANIFEST_NAME, readManifest, withOrigin, writeManifest,
 } from '../lib/manifest.mjs';
+import { sha256File } from '../lib/hash.mjs';
 
 /** Mark one tracked consumer file as kit- or consumer-owned. */
 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, ownershipState);
+  const validatedOwnership = withOrigin(manifest, path, origin, ownershipState);
   await validateConsumerFile(consumerRoot, path);
+  const installedSha256 = origin === 'consumer'
+    ? await sha256File(join(consumerRoot, path)) : undefined;
+  const next = installedSha256
+    ? withOrigin(manifest, path, origin, ownershipState, installedSha256)
+    : validatedOwnership;
   await writeManifest(manifestPath, next);
   return { path, origin, ownershipState: origin === 'consumer'
     ? (ownershipState ?? 'explicit-fork') : undefined };

package/src/commands/update.mjs

@@ -260,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;
 }
 

package/src/lib/contributionBridge.mjs

@@ -0,0 +1,176 @@
+import {
+  lstat, readFile,
+} from 'node:fs/promises';
+import {
+  isAbsolute, join, normalize, resolve,
+} from 'node:path';
+import { lineDiff, writeAtomic } from './atomicWrite.mjs';
+import { validateConsumerFile } from './consumerPath.mjs';
+import { sha256File } from './hash.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, KIT_ORIGIN, PACKAGE_MANIFEST_NAME,
+  readManifest, writeManifest,
+} from './manifest.mjs';
+
+export const CONTRIBUTION_BRIDGE_SCHEMA_VERSION = 1;
+export const CONTRIBUTION_ARTIFACT_KIND = 'agent-workflow-kit/contribution';
+const HASH = /^[a-f0-9]{64}$/;
+const OUTPUT = /^\.agent-workflow-kit\/contributions\/[a-zA-Z0-9._-]+\.json$/;
+
+export function validateContributionBridge(entry) {
+  const bridge = entry?.contributionBridge;
+  if (entry?.origin !== CONSUMER_ORIGIN
+      || entry?.ownershipState !== 'contribution-bridge'
+      || !bridge
+      || bridge.schemaVersion !== CONTRIBUTION_BRIDGE_SCHEMA_VERSION
+      || typeof bridge.baseKitVersion !== 'string'
+      || !bridge.baseKitVersion
+      || !HASH.test(bridge.baseSha256 ?? '')
+      || !HASH.test(bridge.localSha256 ?? '')
+      || bridge.baseSha256 === bridge.localSha256
+      || entry.installedSha256 !== bridge.localSha256) {
+    throw new Error(`invalid contribution bridge metadata: ${entry?.path ?? 'unknown path'}`);
+  }
+  return bridge;
+}
+
+export async function beginContributionBridge({ kitRoot, consumerRoot, path }) {
+  const { pkg, manifest, desired, tracked } = await loadCoreIdentity({
+    kitRoot, consumerRoot, path,
+  });
+  if (tracked.origin !== KIT_ORIGIN || tracked.ownershipState !== undefined) {
+    throw new Error(`contribution bridge requires clean Kit ownership: ${path}`);
+  }
+  if (manifest.kitVersion !== pkg.kitVersion
+      || tracked.installedSha256 !== desired.sha256
+      || await sha256File(join(kitRoot, path)) !== desired.sha256) {
+    throw new Error(`stale upstream base for contribution bridge: ${path}`);
+  }
+  const localSha256 = await sha256File(await validateConsumerFile(consumerRoot, path));
+  if (localSha256 === desired.sha256) {
+    throw new Error(`contribution bridge has no local Core change: ${path}`);
+  }
+  const bridge = {
+    schemaVersion: CONTRIBUTION_BRIDGE_SCHEMA_VERSION,
+    baseKitVersion: pkg.kitVersion,
+    baseSha256: desired.sha256,
+    localSha256,
+  };
+  const next = {
+    ...manifest,
+    installed: manifest.installed.map((entry) => entry.path === path ? {
+      ...entry,
+      installedSha256: localSha256,
+      origin: CONSUMER_ORIGIN,
+      ownershipState: 'contribution-bridge',
+      contributionBridge: bridge,
+    } : entry),
+  };
+  await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), next);
+  return { path, state: 'contribution-bridge', bridge };
+}
+
+export async function prepareContributionArtifact({
+  kitRoot, consumerRoot, path, output,
+}) {
+  const { pkg, desired, tracked } = await loadCoreIdentity({
+    kitRoot, consumerRoot, path,
+  });
+  const bridge = validateContributionBridge(tracked);
+  if (pkg.kitVersion !== bridge.baseKitVersion
+      || desired.sha256 !== bridge.baseSha256
+      || await sha256File(join(kitRoot, path)) !== bridge.baseSha256) {
+    throw new Error(`stale upstream base for contribution bridge: ${path}`);
+  }
+  const localPath = await validateConsumerFile(consumerRoot, path);
+  if (await sha256File(localPath) !== bridge.localSha256) {
+    throw new Error(`contribution bridge changed after classification: ${path}`);
+  }
+  const base = await readFile(join(kitRoot, path));
+  const local = await readFile(localPath);
+  const baseText = strictUtf8(base, path);
+  const localText = strictUtf8(local, path);
+  const artifact = {
+    schemaVersion: CONTRIBUTION_BRIDGE_SCHEMA_VERSION,
+    kind: CONTRIBUTION_ARTIFACT_KIND,
+    coreIdentity: {
+      path,
+      baseKitVersion: bridge.baseKitVersion,
+      baseSha256: bridge.baseSha256,
+      localSha256: bridge.localSha256,
+    },
+    diff: {
+      format: 'line-diff-v1',
+      text: lineDiff(baseText, localText),
+    },
+  };
+  const destination = await validateArtifactOutput(consumerRoot, output);
+  const content = `${JSON.stringify(artifact, null, 2)}\n`;
+  try {
+    const existing = await readFile(destination, 'utf8');
+    if (existing !== content) {
+      throw new Error(`contribution artifact already exists with different content: ${output}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await writeAtomic(destination, content, 0o600);
+  }
+  return { output, artifact };
+}
+
+async function loadCoreIdentity({ kitRoot, consumerRoot, path }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  if (!manifest) throw new Error('not initialised — run `init` first');
+  const desired = pkg.files?.find((entry) => (
+    entry.path === path && (entry.installRole ?? 'consumer') === 'consumer'
+  ));
+  if (!desired || (desired.origin ?? KIT_ORIGIN) !== KIT_ORIGIN) {
+    throw new Error(`not declared Kit Core: ${path}`);
+  }
+  const tracked = manifest.installed?.find((entry) => entry.path === path);
+  if (!tracked) throw new Error(`not declared Kit Core in Consumer ledger: ${path}`);
+  return { pkg, manifest, desired, tracked };
+}
+
+function strictUtf8(bytes, path) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text).equals(bytes)) {
+    throw new Error(`binary Kit Core requires an Explicit fork: ${path}`);
+  }
+  return text;
+}
+
+async function validateArtifactOutput(consumerRoot, output) {
+  if (typeof output !== 'string'
+      || isAbsolute(output)
+      || normalize(output) !== output
+      || !OUTPUT.test(output)) {
+    throw new Error(`unsafe contribution artifact path: ${output}`);
+  }
+  const root = resolve(consumerRoot);
+  let current = root;
+  for (const segment of output.split('/').slice(0, -1)) {
+    current = join(current, segment);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new Error(`unsafe contribution artifact path: ${output}`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  const destination = join(root, output);
+  try {
+    const entry = await lstat(destination);
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+      throw new Error(`unsafe contribution artifact path: ${output}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return destination;
+}

package/src/lib/contributionRouting.mjs

@@ -0,0 +1,152 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { validateContributionBridge } from './contributionBridge.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, readManifest,
+} from './manifest.mjs';
+
+export const CONTRIBUTION_CAPABILITY_PATH = 'docs/agents/workflow-capabilities.json';
+export const CONTRIBUTION_ROUTING_SCHEMA_VERSION = 1;
+const SURFACES = new Set(['retro', 'pre-update', 'guard']);
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const REMOTE = /^[A-Za-z0-9._-]+$/;
+const execFile = promisify(execFileCallback);
+
+const GENERIC_ROUTES = Object.freeze([
+  Object.freeze({ id: 'preserve', remoteMutation: false }),
+  Object.freeze({ id: 'explicit-fork', remoteMutation: false }),
+]);
+
+export async function inspectContributionRouting({
+  consumerRoot, path, surface, resolveRemote = defaultResolveRemote(consumerRoot),
+}) {
+  if (!SURFACES.has(surface)) {
+    throw new Error(`unknown contribution routing surface: ${surface}`);
+  }
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const tracked = manifest?.installed?.find((entry) => entry.path === path);
+  const bridge = validateContributionBridge(tracked);
+  const lifecycle = {
+    surface,
+    path,
+    lifecycleState: 'contribution-bridge',
+    baseKitVersion: bridge.baseKitVersion,
+    routes: GENERIC_ROUTES.map((route) => ({ ...route })),
+  };
+  const loaded = await readCapability(consumerRoot);
+  if (loaded.state !== 'present') {
+    return {
+      ...lifecycle,
+      capabilityState: loaded.state,
+      ...(loaded.diagnostic ? { diagnostic: loaded.diagnostic } : {}),
+    };
+  }
+  const validated = validateCapability(loaded.value);
+  if (!validated.ok) {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: validated.diagnostic,
+    };
+  }
+  if (!validated.enabled) {
+    return { ...lifecycle, capabilityState: 'disabled' };
+  }
+  let remoteUrl;
+  try {
+    remoteUrl = await resolveRemote(validated.remote);
+  } catch {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: 'configured contribution remote is not verifiable',
+    };
+  }
+  if (repositoryFromRemote(remoteUrl) !== validated.repository.toLowerCase()) {
+    return {
+      ...lifecycle,
+      capabilityState: 'invalid',
+      diagnostic: 'configured contribution remote does not match required upstream',
+    };
+  }
+  return {
+    ...lifecycle,
+    capabilityState: 'ready',
+    repository: validated.repository,
+    routes: [
+      ...lifecycle.routes,
+      { id: 'prepare-local', remoteMutation: false },
+      {
+        id: 'upstream-pull-request',
+        remoteMutation: true,
+        requiresExplicitApproval: true,
+      },
+    ],
+  };
+}
+
+async function readCapability(consumerRoot) {
+  try {
+    const raw = await readFile(join(consumerRoot, CONTRIBUTION_CAPABILITY_PATH), 'utf8');
+    const profile = JSON.parse(raw);
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+      return { state: 'invalid', diagnostic: 'workflow capability profile must be an object' };
+    }
+    if (profile.contributionRouting === undefined) return { state: 'missing' };
+    return { state: 'present', value: profile.contributionRouting };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'missing' };
+    return { state: 'invalid', diagnostic: 'workflow capability profile is unreadable or invalid' };
+  }
+}
+
+function validateCapability(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return invalid('contribution routing capability must be an object');
+  }
+  if (value.schemaVersion !== CONTRIBUTION_ROUTING_SCHEMA_VERSION) {
+    return invalid('unsupported contribution routing capability schema');
+  }
+  if (typeof value.enabled !== 'boolean') {
+    return invalid('contribution routing enabled must be boolean');
+  }
+  if (!value.enabled) return { ok: true, enabled: false };
+  const repository = value.upstream?.repository;
+  const remote = value.upstream?.remote;
+  if (!REPOSITORY.test(repository ?? '') || !REMOTE.test(remote ?? '')) {
+    return invalid('contribution routing requires an explicit upstream repository and remote');
+  }
+  if (value.workflows?.prepareLocal !== true) {
+    return invalid('enabled contribution routing requires local preparation');
+  }
+  const pullRequest = value.workflows?.upstreamPullRequest;
+  if (pullRequest?.enabled !== true || pullRequest.requiresExplicitApproval !== true) {
+    return invalid('upstream pull request route requires explicit approval');
+  }
+  return { ok: true, enabled: true, repository, remote };
+}
+
+function invalid(diagnostic) {
+  return { ok: false, diagnostic };
+}
+
+function repositoryFromRemote(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/\.git$/, '');
+  const match = trimmed.match(
+    /^(?:git@github\.com:|https?:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([^/]+\/[^/]+)$/,
+  );
+  return match?.[1]?.toLowerCase() ?? null;
+}
+
+function defaultResolveRemote(consumerRoot) {
+  return async (remote) => {
+    const { stdout } = await execFile(
+      'git', ['-C', consumerRoot, 'remote', 'get-url', remote],
+      { timeout: 5000, maxBuffer: 64 * 1024 },
+    );
+    return stdout.trim();
+  };
+}

package/src/lib/manifest.mjs

@@ -95,7 +95,9 @@ export function indexByPath(manifest, key) {
 }
 
 /** Return a manifest with one tracked entry moved to the requested ownership state. */
-export function withOrigin(manifest, path, origin, ownershipState = 'explicit-fork') {
+export function withOrigin(
+  manifest, path, origin, ownershipState = 'explicit-fork', installedSha256,
+) {
   if (![KIT_ORIGIN, CONSUMER_ORIGIN].includes(origin)) {
     throw new Error(`invalid manifest origin: ${origin}`);
   }
@@ -109,13 +111,22 @@ export function withOrigin(manifest, path, origin, ownershipState = 'explicit-fo
     installed: manifest.installed.map((entry) => {
       if (entry.path !== path) return entry;
       if (origin === KIT_ORIGIN) {
-        const { ownershipState: _removed, ...core } = entry;
+        const {
+          ownershipState: _removed,
+          contributionBridge: _removedBridge,
+          ...core
+        } = entry;
         return { ...core, origin };
       }
-      if (!['contribution-bridge', 'explicit-fork'].includes(ownershipState)) {
+      if (ownershipState !== 'explicit-fork') {
         throw new Error(`invalid consumer ownership state: ${ownershipState}`);
       }
-      return { ...entry, origin, ownershipState };
+      return {
+        ...entry,
+        ...(installedSha256 ? { installedSha256 } : {}),
+        origin,
+        ownershipState,
+      };
     }),
   };
 }

package/src/lib/ownershipClassifier.mjs

@@ -15,6 +15,7 @@ const ROUTES = Object.freeze([
 
 export function classifyOwnershipEvidence({
   path, packageEntry, installedEntry, destinationPresent, projectExtension,
+  contributionBridge,
 }) {
   const evidence = {
     packageDeclared: Boolean(packageEntry),
@@ -24,7 +25,13 @@ export function classifyOwnershipEvidence({
       ? (projectExtension.invalid ? 'invalid' : `schema-v${projectExtension.schemaVersion}`)
       : 'absent',
   };
+  if (contributionBridge !== undefined) {
+    evidence.contributionBridge = contributionBridge
+      ? (contributionBridge.invalid ? 'invalid' : `schema-v${contributionBridge.schemaVersion}`)
+      : 'absent';
+  }
   if (projectExtension?.invalid) evidence.extensionDiagnostic = projectExtension.invalid;
+  if (contributionBridge?.invalid) evidence.bridgeDiagnostic = contributionBridge.invalid;
   if (installedEntry?.origin === 'kit') {
     return { path, state: OwnershipState.CLEAN_CORE, evidence, routes: [] };
   }
@@ -42,6 +49,10 @@ export function classifyOwnershipEvidence({
           || !projectExtension || projectExtension.invalid)) {
       return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
     }
+    if (state === OwnershipState.CONTRIBUTION_BRIDGE
+        && (!contributionBridge || contributionBridge.invalid)) {
+      return { path, state: OwnershipState.AMBIGUOUS_COLLISION, evidence, routes: [...ROUTES] };
+    }
     return { path, state, evidence, routes: [] };
   }
   if (projectExtension && !projectExtension.invalid) {

package/src/lib/updateReconcile.mjs

@@ -1,9 +1,10 @@
-import { access, readFile, rm } from 'node:fs/promises';
+import { access, lstat, readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { sha256File } from './hash.mjs';
 import { lineDiff, writeAtomic } from './atomicWrite.mjs';
 import { hookReferenced } from './settings.mjs';
 import { validateConsumerFile } from './consumerPath.mjs';
+import { validateContributionBridge } from './contributionBridge.mjs';
 import { inspectProjectSkillExtension } from './projectSkillExtension.mjs';
 import {
   OwnershipState, classifyOwnershipEvidence,
@@ -36,6 +37,8 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
     const dest = join(consumerRoot, file.path);
     const prior = installedIdx.get(file.path);
     if (prior?.origin === CONSUMER_ORIGIN) {
+      const bridge = prior.ownershipState === OwnershipState.CONTRIBUTION_BRIDGE
+        ? contributionBridgeEvidence(prior) : null;
       const classification = classifyOwnershipEvidence({
         path: file.path,
         packageEntry: file,
@@ -43,6 +46,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
         destinationPresent: await exists(dest),
         projectExtension: prior.ownershipState === OwnershipState.PROJECT_EXTENSION
           ? await projectExtensionEvidence(consumerRoot, file.path) : null,
+        contributionBridge: bridge,
       });
       result.ownershipStates.push(classification);
       if (classification.state === OwnershipState.AMBIGUOUS_COLLISION) {
@@ -52,6 +56,21 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
           diff: 'Consumer lifecycle metadata does not match its declared path/schema.',
         });
       }
+      if (classification.state === OwnershipState.CONTRIBUTION_BRIDGE) {
+        const present = await exists(dest);
+        if (present) {
+          await validateConsumerFile(consumerRoot, file.path);
+          const current = await sha256File(dest);
+          if (current === file.sha256 && current === bridge.localSha256) {
+            if (!dryRun) {
+              await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+            }
+            nextInstalled.push(entry(file, file.sha256));
+            result.bridgeRetired.push(file.path);
+            continue;
+          }
+        }
+      }
       nextInstalled.push(withInstallRole(prior));
       result.consumerOwned.push(file.path);
       continue;
@@ -95,8 +114,16 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
       }
       result.collisionResolutions.push(resolution);
       if (decision !== 'replace') {
+        const lifecycle = resolvedState === OwnershipState.CONTRIBUTION_BRIDGE ? {
+          contributionBridge: {
+            schemaVersion: 1,
+            baseKitVersion: pkg.kitVersion,
+            baseSha256: file.sha256,
+            localSha256: destinationSha256,
+          },
+        } : {};
         nextInstalled.push(entry(
-          file, destinationSha256, CONSUMER_ORIGIN, resolvedState,
+          file, destinationSha256, CONSUMER_ORIGIN, resolvedState, lifecycle,
         ));
         result.consumerOwned.push(file.path);
       } else {
@@ -114,7 +141,9 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
       continue;
     }
     const userEdited = current !== prior.installedSha256;
-    const upstreamChanged = file.sha256 !== prior.installedSha256;
+    const currentMode = (await lstat(dest)).mode & 0o777;
+    const upstreamChanged = file.sha256 !== prior.installedSha256
+      || currentMode !== file.mode;
     if (!userEdited && upstreamChanged) {
       if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
       nextInstalled.push(entry(file, file.sha256));
@@ -157,6 +186,7 @@ export async function reconcile({ kitRoot, consumerRoot, decide = () => false, d
   }
 
   result.manifestChanged = consumer.installRole !== CONSUMER_INSTALL_ROLE ||
+    result.bridgeRetired.length > 0 ||
     nextInstalled.some((next) => installedIdx.get(next.path)?.installRole !== next.installRole);
 
   if (!dryRun) {
@@ -171,14 +201,23 @@ function emptyResult() {
   return {
     unchanged: [], updated: [], conflicts: [], collisions: [], collisionResolutions: [], userModified: [],
     ownershipStates: [],
+    bridgeRetired: [],
     added: [], deleted: [], keptDeleted: [], consumerOwned: [], manifestChanged: false,
   };
 }
 
-function entry(file, installedSha256, origin = KIT_ORIGIN, ownershipState) {
+function contributionBridgeEvidence(installed) {
+  try {
+    return validateContributionBridge(installed);
+  } catch (error) {
+    return { invalid: error.message };
+  }
+}
+
+function entry(file, installedSha256, origin = KIT_ORIGIN, ownershipState, lifecycle = {}) {
   const result = {
     path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
-    installedSha256, origin, installRole: CONSUMER_INSTALL_ROLE,
+    installedSha256, origin, installRole: CONSUMER_INSTALL_ROLE, ...lifecycle,
   };
   if (ownershipState) result.ownershipState = ownershipState;
   return result;