@ikon85/agent-workflow-kit 0.10.0 → 0.12.0

package/scripts/release-state.test.mjs

@@ -0,0 +1,106 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  createCommandAdapter, githubReleaseArgs, inspectRelease, isMissingRelease,
+  npmTarballFilename, reconcileRelease,
+} from './release-state.mjs';
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const identity = {
+  name: '@ikon85/agent-workflow-kit', version: '1.2.3',
+  tarballIntegrity: 'sha512-example', manifestSha256: 'abc123',
+};
+
+function adapter({ npmPublished = false, githubReleased = false, npmIdentity = identity } = {}) {
+  const events = [];
+  let npmExists = npmPublished;
+  let githubExists = githubReleased;
+  return {
+    events,
+    local: async () => ({ identity, tarball: '/tmp/kit.tgz' }),
+    npm: async () => { events.push('read npm'); return npmExists ? npmIdentity : null; },
+    github: async () => { events.push('read github'); return githubExists ? identity : null; },
+    publishNpm: async () => { events.push('publish npm'); npmExists = true; },
+    createGithub: async () => { events.push('create github'); githubExists = true; },
+  };
+}
+
+test('a fresh release publishes npm, verifies registry readback, then creates GitHub release', async () => {
+  const fixture = adapter();
+  assert.deepEqual(await reconcileRelease(fixture), { status: 'released', identity });
+  assert.deepEqual(fixture.events, [
+    'read npm', 'read github', 'publish npm', 'read npm', 'create github', 'read github',
+  ]);
+});
+
+test('an npm-published release resumes at GitHub without a second npm publish', async () => {
+  const fixture = adapter({ npmPublished: true });
+  await reconcileRelease(fixture);
+  assert.deepEqual(fixture.events, ['read npm', 'read github', 'create github', 'read github']);
+  assert.ok(!fixture.events.includes('publish npm'));
+});
+
+test('post-merge status inspection is read-only and reports the reconstructable phase', async () => {
+  const fixture = adapter({ npmPublished: true });
+  assert.deepEqual(await inspectRelease(fixture), { status: 'awaiting-github', identity });
+  assert.deepEqual(fixture.events, ['read npm', 'read github']);
+});
+
+test('an unpublished npm version is reconstructable when npm reports ETARGET', () => {
+  assert.equal(isMissingRelease({
+    stderr: 'npm error code ETARGET\nnpm error notarget No matching version found',
+  }, 'npm'), true);
+});
+
+test('a mismatching npm package blocks GitHub release creation', async () => {
+  const fixture = adapter({
+    npmPublished: true,
+    npmIdentity: { ...identity, manifestSha256: 'wrong' },
+  });
+  await assert.rejects(reconcileRelease(fixture), /npm manifestSha256 mismatch/);
+  assert.ok(!fixture.events.includes('create github'));
+});
+
+test('release workflow uses supported OIDC trusted publishing without a long-lived npm token', async () => {
+  const workflow = await readFile(join(REPO, '.github/workflows/release.yml'), 'utf8');
+  assert.match(workflow, /node-version:\s*22\.14/);
+  assert.match(workflow, /npm@11\.5\.1/);
+  assert.match(workflow, /id-token:\s*write/);
+  assert.match(workflow, /contents:\s*write/);
+  assert.match(workflow, /registry-url:\s*['"]https:\/\/registry\.npmjs\.org['"]/);
+  assert.match(workflow, /node scripts\/release-state\.mjs/);
+  assert.doesNotMatch(workflow, /NPM_TOKEN|NODE_AUTH_TOKEN|npm_[A-Za-z0-9]/);
+});
+
+test('the production publisher explicitly requests npm provenance', async () => {
+  const commands = [];
+  const fixture = await createCommandAdapter({
+    repoRoot: REPO,
+    run: async (command, args) => { commands.push([command, ...args]); return { stdout: '' }; },
+  });
+  try {
+    await fixture.publishNpm({ tarball: '/tmp/kit.tgz' });
+    assert.deepEqual(commands, [[
+      'npm', 'publish', '/tmp/kit.tgz', '--access', 'public', '--provenance',
+    ]]);
+  } finally { await fixture.dispose(); }
+});
+
+test('an incomplete GitHub release resumes by uploading the verified registry tarball', () => {
+  assert.deepEqual(githubReleaseArgs({
+    exists: true, tag: 'v1.2.3', tarball: '/tmp/ikon85-agent-workflow-kit-1.2.3.tgz', target: 'abc123',
+  }), [
+    'release', 'upload', 'v1.2.3', '/tmp/ikon85-agent-workflow-kit-1.2.3.tgz', '--clobber',
+  ]);
+});
+
+test('a scoped npm identity maps to the registry tarball asset name', () => {
+  assert.equal(
+    npmTarballFilename('@ikon85/agent-workflow-kit', '1.2.3'),
+    'ikon85-agent-workflow-kit-1.2.3.tgz',
+  );
+});

package/scripts/test_program_planning_contract.py

@@ -0,0 +1,63 @@
+"""Contract tests for the user-visible Program planning route."""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class ProgramPlanningContractTest(unittest.TestCase):
+    def skill(self, name: str) -> str:
+        return (ROOT / ".claude" / "skills" / name / "SKILL.md").read_text()
+
+    def test_to_waves_finishes_with_every_wave_execute_ready_by_default(self):
+        text = self.skill("to-waves")
+        self.assertIn("## 7. Program completion contract", text)
+        self.assertIn("every published wave", text)
+        self.assertIn("execute-ready-check.py", text)
+        self.assertIn("X von Y Wellen ausführungsreif", text)
+
+    def test_program_preview_is_the_single_default_user_gate(self):
+        text = self.skill("to-waves")
+        self.assertIn("single user approval", text)
+        self.assertIn("do not ask for another per-wave approval", text)
+
+    def test_unresolved_work_is_modeled_as_an_explicit_gate_not_generic_late_binding(self):
+        text = self.skill("to-waves")
+        self.assertIn("Decision Gate", text)
+        self.assertIn("Verify Spike", text)
+        self.assertIn("Design-Grill", text)
+        self.assertIn("Late Binding is not the default", text)
+
+    def test_to_issues_supports_program_batch_and_keeps_human_actions_out_of_afk(self):
+        text = self.skill("to-issues")
+        self.assertIn("Program batch handoff", text)
+        self.assertIn("A mandatory human or external setup action is never AFK", text)
+
+    def test_atomic_program_wave_preserves_its_program_identity(self):
+        text = self.skill("to-issues")
+        self.assertIn("Program-batch atomic exception", text)
+        self.assertIn("preserve its existing Wave and Phase", text)
+
+    def test_atomic_program_wave_never_leaves_a_preliminary_child(self):
+        waves = self.skill("to-waves")
+        issues = self.skill("to-issues")
+        self.assertIn("do not create a preliminary child", waves)
+        self.assertIn("legacy or interrupted preliminary child", issues)
+        self.assertIn("superseded by atomic wave leaf", issues)
+        self.assertIn("Atomic supersession", waves)
+        self.assertIn("matching source marker remains discoverable after unlink", issues)
+
+    def test_program_completion_treats_audit_findings_as_blocking(self):
+        text = self.skill("to-waves")
+        self.assertIn("Program completion gate", text)
+        self.assertIn("do not count that wave as matured", text)
+
+    def test_public_program_route_promises_execute_ready_waves(self):
+        text = self.skill("scale-check")
+        self.assertIn("all waves execute-ready by default", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

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/bundle.mjs

@@ -42,6 +42,11 @@ export const HELPER_FILES = [
   // Both are invoked through package scripts by /kit-release.
   { path: 'scripts/kit-release.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-delta-guard.mjs', kind: 'script', mode: 0o644 },
+  // Neutral publish/readback parity and externally reconstructable release state.
+  // /kit-release uses these after merge; downstream update/consumer flows reuse
+  // the parity primitive rather than growing a second registry/GitHub comparison.
+  { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.

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',
+  };
+}