@ikon85/agent-workflow-kit 0.11.0 → 0.12.0

package/.agents/skills/kit-update/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: kit-update
+description: "Preview and transactionally apply a parity-verified agent-workflow-kit release without overwriting local modifications or auto-resolving conflicts."
+---
+
+# Kit Update
+
+Update an installed consumer only from the public scoped package
+`@ikon85/agent-workflow-kit`. The unscoped `agent-workflow-kit` package belongs
+to another publisher and is never a valid update source. Existing installs from
+`npx github:iKon85/agent-workflow-kit` remain valid, but updates must use the
+scoped npm release so the shared release-parity checker can prove that npm and
+the matching GitHub release contain the same artifact.
+
+## Workflow
+
+1. Preview the delta without writing:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest diff
+   ```
+
+   Review the named added, updated, locally modified, removed, and conflicting
+   paths. Do not reinterpret a local modification as permission to overwrite it.
+
+2. Apply the update:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest update
+   ```
+
+   The command checks npm/GitHub release parity before staging. It prepares a
+   complete candidate outside the consumer, runs the consumer's existing
+   `npm test` command there, and activates only a verified candidate. A staging
+   or verification failure leaves the installed tree byte-identical.
+
+3. Read the terminal report. `aktuell` proves a second run found no upstream
+   delta. A conflict report names and counts every category and leaves every
+   consumer file untouched. Follow its recommendation and resolve each named
+   conflict manually; never auto-merge, delete a local edit, or silently choose
+   the incoming copy.
+
+4. If a candidate is interrupted, discard its reported stage directory or
+   resume the transaction through the update API's `resumeFrom` option. Do not
+   copy staged files into the consumer by hand.
+
+## State contract
+
+The update API reports `checking -> preview/awaiting_decision -> staging ->
+verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
+and `aborted` never authorize partial activation. The existing manifest,
+three-way diff, and atomic-write seams remain the source of truth.

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -19,6 +19,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 
 ## Routing Rule

package/.claude/skills/kit-update/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: kit-update
+description: "Preview and transactionally apply a parity-verified agent-workflow-kit release without overwriting local modifications or auto-resolving conflicts."
+---
+
+# Kit Update
+
+Update an installed consumer only from the public scoped package
+`@ikon85/agent-workflow-kit`. The unscoped `agent-workflow-kit` package belongs
+to another publisher and is never a valid update source. Existing installs from
+`npx github:iKon85/agent-workflow-kit` remain valid, but updates must use the
+scoped npm release so the shared release-parity checker can prove that npm and
+the matching GitHub release contain the same artifact.
+
+## Workflow
+
+1. Preview the delta without writing:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest diff
+   ```
+
+   Review the named added, updated, locally modified, removed, and conflicting
+   paths. Do not reinterpret a local modification as permission to overwrite it.
+
+2. Apply the update:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest update
+   ```
+
+   The command checks npm/GitHub release parity before staging. It prepares a
+   complete candidate outside the consumer, runs the consumer's existing
+   `npm test` command there, and activates only a verified candidate. A staging
+   or verification failure leaves the installed tree byte-identical.
+
+3. Read the terminal report. `aktuell` proves a second run found no upstream
+   delta. A conflict report names and counts every category and leaves every
+   consumer file untouched. Follow its recommendation and resolve each named
+   conflict manually; never auto-merge, delete a local edit, or silently choose
+   the incoming copy.
+
+4. If a candidate is interrupted, discard its reported stage directory or
+   resume the transaction through the update API's `resumeFrom` option. Do not
+   copy staged files into the consumer by hand.
+
+## State contract
+
+The update API reports `checking -> preview/awaiting_decision -> staging ->
+verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
+and `aborted` never authorize partial activation. The existing manifest,
+three-way diff, and atomic-write seams remain the source of truth.

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -19,6 +19,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 
 ## Routing Rule

package/.claude/skills/skill-manifest.json

@@ -384,6 +384,16 @@
         "codex"
       ],
       "provenance": "own"
+    },
+    "kit-update": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
     }
   }
 }

package/README.md

@@ -332,6 +332,13 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.12.0
+
+- added: `.agents/skills/kit-update/SKILL.md`
+- added: `.claude/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
 ### 0.11.0
 
 - added: `scripts/release-parity.mjs`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.11.0",
+  "kitVersion": "0.12.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -325,6 +325,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "codex",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/local-ci/SKILL.md",
       "kind": "skill",
@@ -564,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1271,6 +1280,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "claude",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/local-ci/SKILL.md",
       "kind": "skill",
@@ -1528,7 +1546,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.11.0",
+  "version": "0.12.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/src/cli.mjs

@@ -6,6 +6,7 @@ import { init } from './commands/init.mjs';
 import { update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
+import { createCommandAdapter } from '../scripts/release-state.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const consumerRoot = process.cwd();
@@ -42,11 +43,22 @@ try {
       const ok = await p.confirm({ message: `Upstream removed ${path} — delete it locally?` });
       return ok === true;
     };
-    const r = await update({ kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide });
+    const releaseIdentities = await readUpdateRelease();
+    const r = await update({
+      kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide, releaseIdentities,
+    });
     printPlan(r);
-    for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (backed up): ${c.path}`);
-    p.outro(`updated ${r.updated.length} · added ${r.added.length} · ` +
-      `conflicts ${r.conflicts.length} · deleted ${r.deleted.length}`);
+    for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
+    if (r.state === 'failed') throw new Error(`candidate update failed: ${r.error}`);
+    if (r.state === 'conflicted') {
+      p.note(r.report.recommendation, 'recommendation');
+      p.outro(`not applied · conflicts ${r.conflicts.length}`);
+      process.exitCode = 2;
+    } else if (r.status === 'current') {
+      p.outro(`aktuell · unchanged ${r.unchanged.length} · local modifications ${r.userModified.length}`);
+    } else {
+      p.outro(`updated ${r.updated.length} · added ${r.added.length} · deleted ${r.deleted.length}`);
+    }
   } else if (cmd === 'uninstall') {
     const ok = yes || (await p.confirm({ message: 'Remove kit-installed files?' })) === true;
     if (!ok) { p.cancel('Aborted.'); process.exit(0); }
@@ -68,3 +80,16 @@ function printPlan(r) {
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
+
+async function readUpdateRelease() {
+  const adapter = await createCommandAdapter({
+    repoRoot: KIT_ROOT,
+    env: { ...process.env, GH_REPO: 'iKon85/agent-workflow-kit' },
+  });
+  try {
+    const local = (await adapter.local()).identity;
+    return { local, npm: await adapter.npm(local), github: await adapter.github(local) };
+  } finally {
+    await adapter.dispose();
+  }
+}

package/src/commands/update.mjs

@@ -1,95 +1,129 @@
-import { readFile, access, rm } from 'node:fs/promises';
+import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sha256File } from '../lib/hash.mjs';
-import { writeAtomic, backupFile, lineDiff } from '../lib/atomicWrite.mjs';
-import { hookReferenced } from '../lib/settings.mjs';
+import { assertReleaseParity } from '../../scripts/release-parity.mjs';
+import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
+import { reconcile } from '../lib/updateReconcile.mjs';
 import {
-  readManifest, writeManifest, emptyConsumerManifest,
-  PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME, indexByPath,
+  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
 } from '../lib/manifest.mjs';
 
-const exists = (p) => access(p).then(() => true, () => false);
+const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
 /**
- * Reconcile an installed consumer against the current kit (three-way: installed
- * hash vs current file = user edit?, vs package desired = upstream change?).
- *  - unmodified + upstream changed → atomic overwrite (`updated`)
- *  - user-edited + upstream changed → timestamped backup + diff, NOT clobbered (`conflicts`)
- *  - user-edited + upstream same → left as-is (`userModified`)
- *  - new upstream file → installed (`added`)
- *  - upstream-removed + unmodified → offered for deletion via `decide` (`deleted`/`keptDeleted`)
- *  - a hook file referenced by the consumer's settings is never auto-deleted (R3#7)
- * `dryRun` classifies without writing (powers `diff`). `now` = backup stamp.
+ * Transactionally reconcile a consumer with a parity-proven kit release.
+ * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
  */
-export async function update({ kitRoot, consumerRoot, now, decide = () => false, dryRun = false }) {
+export async function update(options) {
+  const {
+    kitRoot, consumerRoot, decide = () => false, dryRun = false,
+    releaseIdentities, verify = verifyCandidate, signal, onState = () => {}, resumeFrom,
+  } = options;
+  const history = [];
+  const transition = async (state) => { history.push(state); await onState(state); };
+
+  await transition('checking');
   const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
   if (!pkg) throw new Error('kit package manifest not found');
-  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
-  if (!consumer) throw new Error('not initialised — run `init` first');
-
-  const installedIdx = indexByPath(consumer, 'installed');
-  const pkgIdx = indexByPath(pkg, 'files');
-  const res = { unchanged: [], updated: [], conflicts: [], userModified: [], added: [], deleted: [], keptDeleted: [] };
-  const nextInstalled = [];
-
-  for (const f of pkg.files) {
-    const dest = join(consumerRoot, f.path);
-    const prior = installedIdx.get(f.path);
-    const cur = (await exists(dest)) ? await sha256File(dest) : null;
-
-    if (!prior || cur === null) {
-      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
-      nextInstalled.push(entry(f, f.sha256));
-      res.added.push(f.path);
-      continue;
-    }
-    const userEdited = cur !== prior.installedSha256;
-    const upstreamChanged = f.sha256 !== prior.installedSha256;
+  if (!dryRun) verifyRelease(releaseIdentities, pkg.kitVersion);
+  const consumerManifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
+  if (!await readManifest(consumerManifestPath)) {
+    throw new Error('not initialised — run `init` first');
+  }
+  const consumerManifestBefore = await readFile(consumerManifestPath);
 
-    if (!userEdited && upstreamChanged) {
-      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
-      nextInstalled.push(entry(f, f.sha256));
-      res.updated.push(f.path);
-    } else if (userEdited && upstreamChanged) {
-      const incoming = await readFile(join(kitRoot, f.path), 'utf8');
-      const diff = lineDiff(await readFile(dest, 'utf8'), incoming);
-      if (!dryRun) await backupFile(dest, now);
-      nextInstalled.push(prior); // keep installed-hash baseline; file stays user's
-      res.conflicts.push({ path: f.path, diff });
-    } else if (userEdited) {
-      nextInstalled.push(prior);
-      res.userModified.push(f.path);
-    } else {
-      nextInstalled.push(prior);
-      res.unchanged.push(f.path);
-    }
+  const decisions = new Map();
+  const choose = async (_action, path) => {
+    if (!decisions.has(path)) decisions.set(path, await decide('delete', path));
+    return decisions.get(path);
+  };
+  const preview = await reconcile({ kitRoot, consumerRoot, decide: choose, dryRun: true });
+  await transition('preview');
+  if (preview.deleted.length || preview.keptDeleted.length) await transition('awaiting_decision');
+  if (dryRun) return { ...preview, state: 'preview', history };
+  if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
+  if (!hasUpstreamDelta(preview)) {
+    return { ...await terminal(preview, 'applied', history, transition), status: 'current' };
   }
+  return applyTransaction({
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
+    consumerManifestBefore, history, transition,
+  });
+}
 
-  // upstream-removed files (in consumer manifest, gone from package)
-  for (const prior of consumer.installed) {
-    if (pkgIdx.has(prior.path)) continue;
-    const dest = join(consumerRoot, prior.path);
-    const cur = (await exists(dest)) ? await sha256File(dest) : null;
-    const userEdited = cur !== null && cur !== prior.installedSha256;
-    const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
-    if (userEdited || referenced || !(await decide('delete', prior.path))) {
-      nextInstalled.push(prior);
-      res.keptDeleted.push(prior.path);
-    } else {
-      if (!dryRun && cur !== null) await rm(dest);
-      res.deleted.push(prior.path);
+async function applyTransaction(context) {
+  const {
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
+    consumerManifestBefore, history, transition,
+  } = context;
+  let candidateRoot = resumeFrom;
+  let keepCandidate = false;
+  try {
+    await transition('staging');
+    if (!candidateRoot) {
+      candidateRoot = await stageConsumer(consumerRoot);
+      await reconcile({
+        kitRoot, consumerRoot: candidateRoot,
+        decide: (_action, path) => decisions.get(path) === true,
+      });
     }
+    await transition('verifying');
+    const abort = async () => {
+      keepCandidate = true;
+      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
+    };
+    if (signal?.aborted) return abort();
+    await verify(candidateRoot);
+    if (signal?.aborted) return abort();
+    await activateCandidate({
+      candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+    });
+    return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
+  } catch (error) {
+    return { ...await terminal(preview, 'failed', history, transition), error: error.message };
+  } finally {
+    if (candidateRoot && !keepCandidate) await rm(candidateRoot, { recursive: true, force: true });
   }
+}
 
-  if (!dryRun) {
-    await writeManifest(
-      join(consumerRoot, CONSUMER_MANIFEST_NAME),
-      { ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled }
-    );
+function verifyRelease(identities, kitVersion) {
+  const release = assertReleaseParity(identities);
+  if (release.name !== RELEASE_NAME) throw new Error(`invalid release origin: ${release.name}`);
+  if (release.version !== kitVersion) {
+    throw new Error(`release version ${release.version} does not match kit ${kitVersion}`);
   }
-  return res;
 }
 
-function entry(f, sha) {
-  return { path: f.path, kind: f.kind, ownerSkill: f.ownerSkill, surface: f.surface, installedSha256: sha, origin: 'kit' };
+function hasUpstreamDelta(result) {
+  return result.added.length + result.updated.length + result.deleted.length > 0;
 }
+
+async function terminal(result, state, history, transition) {
+  await transition(state);
+  return {
+    ...result,
+    state,
+    history,
+    report: {
+      unchanged: result.unchanged.length,
+      added: result.added.length,
+      updated: result.updated.length,
+      deleted: result.deleted.length,
+      localModified: result.userModified.length,
+      conflicts: result.conflicts.length,
+      keptDeleted: result.keptDeleted.length,
+      paths: {
+        added: result.added,
+        updated: result.updated,
+        deleted: result.deleted,
+        localModified: result.userModified,
+        conflicts: result.conflicts.map(({ path }) => path),
+        keptDeleted: result.keptDeleted,
+      },
+      recommendation: result.conflicts.length
+        ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
+        : null,
+    },
+  };
+}
+
+export { verifyCandidate } from '../lib/updateCandidate.mjs';

package/src/lib/updateCandidate.mjs

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+import { access, cp, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { writeAtomic } from './atomicWrite.mjs';
+import { sha256File } from './hash.mjs';
+import { CONSUMER_MANIFEST_NAME, indexByPath, readManifest } from './manifest.mjs';
+
+const run = promisify(execFile);
+const exists = (path) => access(path).then(() => true, () => false);
+
+/** Copy a verification candidate without duplicating git metadata or dependencies. */
+export async function stageConsumer(consumerRoot) {
+  const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
+  const nodeModules = join(consumerRoot, 'node_modules');
+  await cp(consumerRoot, candidateRoot, {
+    recursive: true,
+    filter: (source) => {
+      const rel = relative(consumerRoot, source);
+      return rel !== '.git' && !rel.startsWith('.git/') &&
+        rel !== 'node_modules' && !rel.startsWith('node_modules/');
+    },
+  });
+  if (await exists(nodeModules)) await symlink(nodeModules, join(candidateRoot, 'node_modules'), 'dir');
+  return candidateRoot;
+}
+
+/** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
+export async function activateCandidate({
+  candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+}) {
+  const changed = [...preview.added, ...preview.updated];
+  const touched = [...changed, ...preview.deleted, CONSUMER_MANIFEST_NAME];
+  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!currentManifest.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
+  const pkgIdx = indexByPath(pkg, 'files');
+  for (const path of changed) {
+    if (await sha256File(join(candidateRoot, path)) !== pkgIdx.get(path)?.sha256) {
+      throw new Error(`candidate hash mismatch: ${path}`);
+    }
+  }
+  await assertConsumerStillMatchesPreview(consumerRoot, preview);
+  const rollback = new Map();
+  for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
+  try {
+    for (const path of changed) {
+      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
+    }
+    for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
+    await writeAtomic(
+      join(consumerRoot, CONSUMER_MANIFEST_NAME),
+      await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME)),
+    );
+  } catch (error) {
+    for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
+    throw error;
+  }
+}
+
+async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const installed = indexByPath(manifest, 'installed');
+  for (const path of preview.added) {
+    if (await exists(join(consumerRoot, path))) throw new Error(`consumer changed during verification: ${path}`);
+  }
+  for (const path of [...preview.updated, ...preview.deleted]) {
+    const prior = installed.get(path);
+    const current = await exists(join(consumerRoot, path))
+      ? await sha256File(join(consumerRoot, path)) : null;
+    if (!prior || current !== prior.installedSha256) {
+      throw new Error(`consumer changed during verification: ${path}`);
+    }
+  }
+}
+
+async function snapshot(path) {
+  if (!await exists(path)) return null;
+  const info = await stat(path);
+  return { bytes: await readFile(path), mode: info.mode };
+}
+
+async function restore(path, saved) {
+  if (!saved) return rm(path, { force: true });
+  await writeAtomic(path, saved.bytes, saved.mode);
+}
+
+/** Default candidate gate: run the consumer's existing npm test command. */
+export async function verifyCandidate(candidateRoot) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(candidateRoot, 'package.json'), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error('candidate has no package.json test command');
+    throw error;
+  }
+  if (!pkg.scripts?.test) throw new Error('candidate has no package.json test command');
+  await run('npm', ['test'], { cwd: candidateRoot });
+}

package/src/lib/updateReconcile.mjs

@@ -0,0 +1,89 @@
+import { access, 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 {
+  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
+  indexByPath, readManifest, writeManifest,
+} from './manifest.mjs';
+
+const exists = (path) => access(path).then(() => true, () => false);
+
+/** Classify or apply one three-way reconcile inside a supplied root. */
+export async function reconcile({ kitRoot, consumerRoot, decide = () => false, dryRun = false }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!consumer) throw new Error('not initialised — run `init` first');
+
+  const installedIdx = indexByPath(consumer, 'installed');
+  const pkgIdx = indexByPath(pkg, 'files');
+  const result = emptyResult();
+  const nextInstalled = [];
+
+  for (const file of pkg.files) {
+    const dest = join(consumerRoot, file.path);
+    const prior = installedIdx.get(file.path);
+    const current = (await exists(dest)) ? await sha256File(dest) : null;
+    if (!prior || current === null) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+      nextInstalled.push(entry(file, file.sha256));
+      result.added.push(file.path);
+      continue;
+    }
+    const userEdited = current !== prior.installedSha256;
+    const upstreamChanged = file.sha256 !== prior.installedSha256;
+    if (!userEdited && upstreamChanged) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+      nextInstalled.push(entry(file, file.sha256));
+      result.updated.push(file.path);
+    } else if (userEdited && upstreamChanged) {
+      const incoming = await readFile(join(kitRoot, file.path), 'utf8');
+      result.conflicts.push({ path: file.path, diff: lineDiff(await readFile(dest, 'utf8'), incoming) });
+      nextInstalled.push(prior);
+    } else if (userEdited) {
+      nextInstalled.push(prior);
+      result.userModified.push(file.path);
+    } else {
+      nextInstalled.push(prior);
+      result.unchanged.push(file.path);
+    }
+  }
+
+  for (const prior of consumer.installed) {
+    if (pkgIdx.has(prior.path)) continue;
+    const dest = join(consumerRoot, prior.path);
+    const current = (await exists(dest)) ? await sha256File(dest) : null;
+    const userEdited = current !== null && current !== prior.installedSha256;
+    const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
+    if (userEdited || referenced || !(await decide('delete', prior.path))) {
+      nextInstalled.push(prior);
+      result.keptDeleted.push(prior.path);
+    } else {
+      if (!dryRun && current !== null) await rm(dest);
+      result.deleted.push(prior.path);
+    }
+  }
+
+  if (!dryRun) {
+    await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
+      ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
+    });
+  }
+  return result;
+}
+
+function emptyResult() {
+  return {
+    unchanged: [], updated: [], conflicts: [], userModified: [],
+    added: [], deleted: [], keptDeleted: [],
+  };
+}
+
+function entry(file, installedSha256) {
+  return {
+    path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
+    installedSha256, origin: 'kit',
+  };
+}