@ikon85/agent-workflow-kit 0.27.0 → 0.28.0

package/scripts/test_retro_wrapup_contract.py

@@ -0,0 +1,111 @@
+"""Contract tests for retro enforcement and safe wrapup workflow chaining."""
+
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (".claude", ".agents")
+
+
+def skill(surface: str, name: str) -> str:
+    return (ROOT / surface / "skills" / name / "SKILL.md").read_text(
+        encoding="utf-8"
+    )
+
+
+def contract_text(surface: str, name: str) -> str:
+    """Return prose with Markdown emphasis removed for wording assertions."""
+    return re.sub(r"\s+", " ", skill(surface, name).replace("**", ""))
+
+
+class RetroEnforcementContract(unittest.TestCase):
+    def test_mechanical_check_precedes_target_and_weight_ladder(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                mechanical = text.index("### 3a. Mechanical enforcement check")
+                ladder = text.index("### 3b. Determine target + weight")
+                self.assertLess(mechanical, ladder)
+
+    def test_machine_checkable_findings_cannot_stop_at_prose(self):
+        required = (
+            "Could a machine decide this",
+            "implement the enforcement",
+            "tracked enforcement issue",
+            "explicit trade-off",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_upstream_or_own_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",
+            "docs/agents/skills/<skill>.md",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "retro")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+
+class WrapupChainingContract(unittest.TestCase):
+    def test_retro_is_model_invocable_on_both_surfaces(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                frontmatter = skill(surface, "retro").split("---", 2)[1]
+                self.assertIn("disable-model-invocation: false", frontmatter)
+
+    def test_affirmative_retro_gate_chains_without_landing(self):
+        required = (
+            "invoke the `retro` skill immediately in this run",
+            "land nothing in this run",
+            "fresh explicit `/wrapup` invocation",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_only_model_invocable_non_deploying_workflows_chain(self):
+        required = (
+            "model-invocable",
+            "non-deploying",
+            "return control to the user",
+            "state the reason",
+        )
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = contract_text(surface, "wrapup")
+                for phrase in required:
+                    self.assertIn(phrase, text)
+
+    def test_wrapup_remains_manual_and_program_propagation_remains_present(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                text = skill(surface, "wrapup")
+                self.assertIn("disable-model-invocation: true", text)
+                self.assertIn("user's `/wrapup` input IS the explicit", text)
+                self.assertIn("program-sync", text)
+                self.assertIn("Phasen-Gates", text)
+
+    def test_new_contract_is_reference_free(self):
+        for surface in SURFACES:
+            with self.subTest(surface=surface):
+                combined = skill(surface, "retro") + skill(surface, "wrapup")
+                self.assertNotIn("testreporter", combined.lower())
+                self.assertIsNone(re.search(r"#[0-9]{3,}", combined))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/scripts/test_tdd_contract.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Contract tests for existing-test-first TDD without weakening RED-first."""
+
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SURFACES = (
+    ROOT / ".claude" / "skills" / "tdd" / "SKILL.md",
+    ROOT / ".agents" / "skills" / "tdd" / "SKILL.md",
+)
+DECISIONS = ("REUSE", "EXTEND", "REPLACE", "NEW", "RETIRE", "NO-NEW-TEST")
+
+
+class TddContractTest(unittest.TestCase):
+    def texts(self):
+        return {path: path.read_text(encoding="utf-8") for path in SURFACES}
+
+    def test_each_behavior_gets_exactly_one_existing_test_first_decision(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("### 2. Existing-Test-First Decision", text)
+                self.assertIn("For each planned behavior, record exactly one", text)
+                for decision in DECISIONS:
+                    self.assertEqual(
+                        len(re.findall(rf"^- \*\*{re.escape(decision)}\*\*", text, re.MULTILINE)),
+                        1,
+                        f"{decision} must have exactly one canonical definition",
+                    )
+
+    def test_new_files_require_rejecting_the_nearest_owner_with_a_reason(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("nearest existing owner", text)
+                self.assertIn("rejected with a reason", text)
+
+    def test_red_first_is_unconditional_for_executable_behavior_and_bug_fixes(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn(
+                    "Every executable new behavior and bug fix must begin with a failing assertion",
+                    text,
+                )
+                self.assertIn("REUSE and NO-NEW-TEST never bypass this RED-first invariant", text)
+                self.assertRegex(
+                    text,
+                    r"an already-green\s+assertion does not prove the requested change",
+                )
+
+    def test_retirement_keeps_negative_tests_only_for_durable_absence(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                self.assertIn("delete the tests that specified the retired behavior", text)
+                self.assertIn("only when absence itself is a durable", text)
+
+    def test_worked_matrix_and_counted_handoff_cover_all_decisions(self):
+        for path, text in self.texts().items():
+            with self.subTest(surface=path.relative_to(ROOT)):
+                matrix = re.search(
+                    r"### Worked decision matrix\n(?P<body>.*?)(?=\n### |\n## )",
+                    text,
+                    re.DOTALL,
+                )
+                self.assertIsNotNone(matrix)
+                body = matrix.group("body")
+                for decision in DECISIONS:
+                    self.assertRegex(body, rf"\|\s*{re.escape(decision)}\s*\|")
+                self.assertIn("list every behavior and its one decision", text)
+                self.assertIn(
+                    "Reused X · Extended Y · New Z · Replaced/retired W",
+                    text,
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/cli.mjs

@@ -6,7 +6,10 @@ 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 { setOwnership } from './commands/own.mjs';
+import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
+import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const consumerRoot = process.cwd();
@@ -20,6 +23,7 @@ const args = process.argv.slice(2);
 const cmd = args[0];
 const force = args.includes('--force');
 const yes = args.includes('--yes') || args.includes('-y');
+const owned = args.includes('--owned');
 
 p.intro('agent-workflow-kit');
 
@@ -34,15 +38,11 @@ try {
     p.outro('Next: run /setup-workflow to fill the project layer + board profile. ' +
       'To enable the drift-guard hook, add .claude/hooks/drift-guard.py to your settings.json hooks.');
   } else if (cmd === 'diff') {
-    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot });
+    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot, owned });
     printPlan(r);
     p.outro('Dry run — nothing written. Run `update` to apply.');
   } else if (cmd === 'update') {
-    const decide = async (_action, path) => {
-      if (yes) return true;
-      const ok = await p.confirm({ message: `Upstream removed ${path} — delete it locally?` });
-      return ok === true;
-    };
+    const decide = (action, path) => decideUpdate(action, path, yes);
     const releaseIdentities = await readUpdateRelease();
     const r = await update({
       kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide, releaseIdentities,
@@ -64,8 +64,13 @@ 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 === 'own' || cmd === 'disown') {
+    if (!args[1]) throw new Error(`Usage: agent-workflow-kit ${cmd} <path>`);
+    const origin = cmd === 'own' ? CONSUMER_ORIGIN : KIT_ORIGIN;
+    await setOwnership({ consumerRoot, path: args[1], origin });
+    p.outro(`${args[1]} is now ${origin}-owned`);
   } else {
-    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall> [--force] [--yes]');
+    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall|own|disown> [<path>] [--force] [--yes] [--owned]');
     p.outro('');
   }
 } catch (err) {
@@ -75,20 +80,54 @@ try {
 
 function printPlan(r) {
   const lines = [];
-  for (const k of ['added', 'updated', 'userModified', 'unchanged', 'deleted', 'keptDeleted'])
+  for (const k of [
+    'added', 'updated', 'userModified', 'consumerOwned', 'unchanged',
+    'deleted', 'keptDeleted', 'collisions',
+  ])
     if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
+  for (const owned of r.ownedDiffs ?? []) {
+    lines.push(`${owned.state} ${owned.path}`);
+    if (owned.binary) {
+      lines.push(`  local: ${owned.local.size} bytes sha256:${owned.local.sha256}`);
+      lines.push(`  upstream: ${owned.upstream.size} bytes sha256:${owned.upstream.sha256}`);
+    } else if (owned.diff) {
+      lines.push(owned.diff);
+    }
+  }
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
 
+async function decideUpdate(action, path, yes) {
+  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:`,
+      options: [
+        { value: 'keep-as-owned', label: 'Keep existing file as consumer-owned' },
+        { value: 'replace', label: 'Replace with kit file' },
+      ],
+    });
+    if (p.isCancel(choice)) throw new Error(`collision decision cancelled for ${path}`);
+    return choice;
+  }
+  throw new Error(`unknown update decision action: ${action}`);
+}
+
 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) };
+    // Re-packing an unpacked install is never byte-identical to the registry
+    // tarball — the installed copy proves itself by content identity instead.
+    const installed = await installedIdentityFromDir(KIT_ROOT);
+    return { installed, npm: await adapter.npm(installed), github: await adapter.github(installed) };
   } finally {
     await adapter.dispose();
   }

package/src/commands/diff.mjs

@@ -1,6 +1,9 @@
 import { update } from './update.mjs';
+import { ownedDiff } from '../lib/ownedDiff.mjs';
 
 /** Dry-run of `update`: classifies what an update would do, writes nothing. */
-export async function diff({ kitRoot, consumerRoot }) {
-  return update({ kitRoot, consumerRoot, now: 'dry', dryRun: true });
+export async function diff({ kitRoot, consumerRoot, owned = false }) {
+  const preview = await update({ kitRoot, consumerRoot, now: 'dry', dryRun: true });
+  if (!owned) return preview;
+  return { ...preview, ownedDiffs: await ownedDiff({ kitRoot, consumerRoot }) };
 }

package/src/commands/init.mjs

@@ -8,6 +8,7 @@ import {
   readManifest, writeManifest, emptyConsumerManifest,
   filesForInstallRole, CONSUMER_INSTALL_ROLE,
   indexByPath,
+  CONSUMER_ORIGIN,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
 
@@ -27,12 +28,19 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
   if (!pkg) throw new Error('kit package manifest not found');
   const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
   const tracked = new Set((prior?.installed ?? []).map((e) => e.path));
+  const consumerOwned = new Set(
+    (prior?.installed ?? []).filter((e) => e.origin === CONSUMER_ORIGIN).map((e) => e.path),
+  );
   const packageIdx = indexByPath(pkg, 'files');
 
   const result = { copied: [], skipped: [], seeded: [] };
   const installed = [];
 
   for (const entry of prior?.installed ?? []) {
+    if (entry.origin === CONSUMER_ORIGIN) {
+      installed.push(entry);
+      continue;
+    }
     const packageEntry = packageIdx.get(entry.path);
     if (packageEntry?.installRole === CONSUMER_INSTALL_ROLE || !packageEntry?.installRole) continue;
     if (!await exists(join(consumerRoot, entry.path))) continue;
@@ -41,6 +49,10 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
 
   for (const f of filesForInstallRole(pkg)) {
     const dest = join(consumerRoot, f.path);
+    if (consumerOwned.has(f.path)) {
+      result.skipped.push(f.path);
+      continue;
+    }
     if (await exists(dest) && !tracked.has(f.path) && !force) {
       result.skipped.push(f.path); // pre-existing untracked → never-clobber
       continue;

package/src/commands/own.mjs

@@ -0,0 +1,16 @@
+import { join } from 'node:path';
+import { validateConsumerFile } from '../lib/consumerPath.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, readManifest, withOrigin, writeManifest,
+} from '../lib/manifest.mjs';
+
+/** Mark one tracked consumer file as kit- or consumer-owned. */
+export async function setOwnership({ consumerRoot, path, origin }) {
+  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);
+  await validateConsumerFile(consumerRoot, path);
+  await writeManifest(manifestPath, next);
+  return { path, origin };
+}

package/src/commands/uninstall.mjs

@@ -2,7 +2,10 @@ import { access, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { sha256File } from '../lib/hash.mjs';
 import { hookReferenced } from '../lib/settings.mjs';
-import { writeManifest, readManifest, emptyConsumerManifest, CONSUMER_MANIFEST_NAME } from '../lib/manifest.mjs';
+import {
+  writeManifest, readManifest, emptyConsumerManifest,
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN,
+} from '../lib/manifest.mjs';
 
 const exists = (p) => access(p).then(() => true, () => false);
 
@@ -22,6 +25,10 @@ export async function uninstall({ consumerRoot }) {
   for (const e of consumer.installed) {
     const dest = join(consumerRoot, e.path);
     if (!(await exists(dest))) continue; // already gone
+    if (e.origin === CONSUMER_ORIGIN) {
+      res.retained.push(e.path);
+      continue;
+    }
     const userEdited = (await sha256File(dest)) !== e.installedSha256;
     const referenced = e.kind === 'hook' && (await hookReferenced(consumerRoot, e.path));
     if (userEdited || referenced) {

package/src/commands/update.mjs

@@ -1,6 +1,6 @@
 import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { assertReleaseParity } from '../../scripts/release-parity.mjs';
+import { assertConsumerReleaseParity } from '../../scripts/release-parity.mjs';
 import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
 import { reconcile } from '../lib/updateReconcile.mjs';
 import {
@@ -32,24 +32,45 @@ export async function update(options) {
   const consumerManifestBefore = await readFile(consumerManifestPath);
 
   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 choosePreview = async (action, path) => {
+    if (action === 'collision') return undefined;
+    const key = decisionKey(action, path);
+    if (!decisions.has(key)) decisions.set(key, await decide(action, path));
+    return decisions.get(key);
   };
-  const preview = await reconcile({ kitRoot, consumerRoot, decide: choose, dryRun: true });
+  const preview = await reconcile({ kitRoot, consumerRoot, decide: choosePreview, 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' };
+  const resolvedPreview = await resolvePreview({
+    kitRoot, consumerRoot, preview, decisions, decide, transition,
+  });
+  if (resolvedPreview.conflicts.length) {
+    return terminal(resolvedPreview, 'conflicted', history, transition);
+  }
+  if (!hasUpstreamDelta(resolvedPreview)) {
+    return { ...await terminal(resolvedPreview, 'applied', history, transition), status: 'current' };
   }
   return applyTransaction({
-    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
+    kitRoot, consumerRoot, pkg, preview: resolvedPreview, decisions, verify, signal, resumeFrom,
     consumerManifestBefore, history, transition,
   });
 }
 
+async function resolvePreview({ kitRoot, consumerRoot, preview, decisions, decide, transition }) {
+  if (preview.deleted.length || preview.keptDeleted.length || preview.collisions.length) {
+    await transition('awaiting_decision');
+  }
+  for (const path of preview.collisions) {
+    decisions.set(decisionKey('collision', path), await decide('collision', path));
+  }
+  if (!preview.collisions.length) return preview;
+  return reconcile({
+    kitRoot, consumerRoot, dryRun: true,
+    decide: (action, path) => decisions.get(decisionKey(action, path)),
+  });
+}
+
 async function applyTransaction(context) {
   const {
     kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
@@ -59,11 +80,14 @@ async function applyTransaction(context) {
   let keepCandidate = false;
   try {
     await transition('staging');
+    if (candidateRoot && preview.collisionResolutions.length) {
+      throw new Error('collision-bearing candidate cannot be resumed safely');
+    }
     if (!candidateRoot) {
       candidateRoot = await stageConsumer(consumerRoot);
       await reconcile({
         kitRoot, consumerRoot: candidateRoot,
-        decide: (_action, path) => decisions.get(path) === true,
+        decide: (action, path) => decisions.get(decisionKey(action, path)),
       });
     }
     await transition('verifying');
@@ -85,8 +109,12 @@ async function applyTransaction(context) {
   }
 }
 
+function decisionKey(action, path) {
+  return `${action}\0${path}`;
+}
+
 function verifyRelease(identities, kitVersion) {
-  const release = assertReleaseParity(identities);
+  const release = assertConsumerReleaseParity(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}`);

package/src/lib/bundle.mjs

@@ -34,6 +34,7 @@ export const HELPER_FILES = [
   { path: 'scripts/board-sync.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/execute-ready-check.py', kind: 'script', mode: 0o755 },
   { path: 'scripts/pr-body-check.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/pr_body_e2e.py', kind: 'script', mode: 0o644 },
   // Mechanical executor for /wrapup (preflight/commit/land) — replaced the
   // Sonnet phase-2 subagent. Imports board_config + anchor_table
   // (both shipped above). Invokable CLI → 0o755.
@@ -91,6 +92,9 @@ export const HELPER_FILES = [
   { path: '.claude/hooks/enforce-worktree-cwd.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/enforce-worktree-discipline.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/slice-handoff-hint.py', kind: 'hook', mode: 0o755 },
+  // Advisory provenance hint for agent Edit/Write events. It reads the local
+  // consumer manifest once and fails open; setup-workflow owns activation.
+  { path: '.claude/hooks/kit-origin-edit-hint.py', kind: 'hook', mode: 0o755 },
   // Profile-driven non-blocking change-lifecycle advisories. The shell Stop
   // entry delegates to its sibling Python adapter; decisions stay in core.py.
   { path: 'scripts/workflow-advisories/core.py', kind: 'script', mode: 0o644 },

package/src/lib/consumerPath.mjs

@@ -0,0 +1,30 @@
+import { lstat } from 'node:fs/promises';
+import { isAbsolute, join, normalize, relative, resolve } from 'node:path';
+
+/** Resolve a normalized repo-relative path and require a regular, non-symlink file. */
+export async function validateConsumerFile(consumerRoot, path) {
+  if (typeof path !== 'string' || !path || path === '.' || isAbsolute(path) || normalize(path) !== path) {
+    throw new Error(`unsafe consumer path: ${path}`);
+  }
+  const root = resolve(consumerRoot);
+  const absolute = resolve(join(root, path));
+  const fromRoot = relative(root, absolute);
+  if (!fromRoot || fromRoot.startsWith(`..${separator()}`) || fromRoot === '..' || isAbsolute(fromRoot)) {
+    throw new Error(`unsafe consumer path: ${path}`);
+  }
+  let stat;
+  try {
+    stat = await lstat(absolute);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`unsafe consumer path (not a regular file): ${path}`);
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`unsafe consumer path (not a regular file): ${path}`);
+  }
+  return absolute;
+}
+
+function separator() {
+  return process.platform === 'win32' ? '\\' : '/';
+}

package/src/lib/manifest.mjs

@@ -13,6 +13,8 @@ import { writeAtomic } from './atomicWrite.mjs';
 export const CONSUMER_MANIFEST_NAME = 'agent-workflow-kit.json';
 export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
 export const CONSUMER_INSTALL_ROLE = 'consumer';
+export const KIT_ORIGIN = 'kit';
+export const CONSUMER_ORIGIN = 'consumer';
 
 /**
  * Parse a JSON manifest, or null if the file does not exist. A corrupt file
@@ -66,3 +68,19 @@ export function indexByPath(manifest, key) {
   for (const entry of (manifest?.[key] ?? [])) idx.set(entry.path, entry);
   return idx;
 }
+
+/** Return a manifest with one tracked entry moved to the requested ownership state. */
+export function withOrigin(manifest, path, origin) {
+  if (![KIT_ORIGIN, CONSUMER_ORIGIN].includes(origin)) {
+    throw new Error(`invalid manifest origin: ${origin}`);
+  }
+  const current = (manifest?.installed ?? []).find((entry) => entry.path === path);
+  if (!current) throw new Error(`unknown tracked path: ${path}`);
+  if ((current.origin ?? KIT_ORIGIN) === origin) {
+    throw new Error(`${path} is already ${origin}-owned`);
+  }
+  return {
+    ...manifest,
+    installed: manifest.installed.map((entry) => entry.path === path ? { ...entry, origin } : entry),
+  };
+}

package/src/lib/ownedDiff.mjs

@@ -0,0 +1,88 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lineDiff } from './atomicWrite.mjs';
+import { validateConsumerFile } from './consumerPath.mjs';
+import { sha256 } from './hash.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, PACKAGE_MANIFEST_NAME, indexByPath, readManifest,
+} from './manifest.mjs';
+
+/** Describe on demand how current package entries differ from consumer-owned paths. */
+export async function ownedDiff({ kitRoot, consumerRoot }) {
+  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  const packageByPath = indexByPath(pkg, 'files');
+  const results = [];
+
+  for (const installed of consumer.installed.filter(({ origin }) => origin === CONSUMER_ORIGIN)) {
+    const current = packageByPath.get(installed.path);
+    let localPath;
+    try {
+      localPath = await validateConsumerFile(consumerRoot, installed.path);
+    } catch (error) {
+      if (error.message === `unsafe consumer path (not a regular file): ${installed.path}` &&
+          await isMissing(join(consumerRoot, installed.path))) {
+        results.push({ path: installed.path, state: 'missing-locally' });
+        continue;
+      }
+      if (error.message.startsWith('unsafe consumer path')) {
+        results.push({ path: installed.path, state: 'unsafe-path' });
+        continue;
+      }
+      throw error;
+    }
+    if (!current) {
+      results.push({ path: installed.path, state: 'removed-upstream' });
+      continue;
+    }
+    const local = await readFile(localPath);
+    let packagePath;
+    try {
+      packagePath = await validateConsumerFile(kitRoot, current.path);
+    } catch (error) {
+      if (error.message.startsWith('unsafe consumer path')) {
+        results.push({ path: installed.path, state: 'unsafe-path' });
+        continue;
+      }
+      throw error;
+    }
+    const upstream = await readFile(packagePath);
+    if (local.equals(upstream)) {
+      results.push({ path: installed.path, state: 'identical' });
+      continue;
+    }
+    if (isBinary(local) || isBinary(upstream)) {
+      results.push({
+        path: installed.path,
+        state: 'changed-upstream',
+        binary: true,
+        local: { size: local.length, sha256: sha256(local) },
+        upstream: { size: upstream.length, sha256: sha256(upstream) },
+      });
+      continue;
+    }
+    results.push({
+      path: installed.path,
+      state: 'changed-upstream',
+      binary: false,
+      diff: lineDiff(local.toString('utf8'), upstream.toString('utf8')),
+    });
+  }
+  return results;
+}
+
+async function isMissing(path) {
+  try {
+    await lstat(path);
+    return false;
+  } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    throw error;
+  }
+}
+
+function isBinary(bytes) {
+  if (bytes.includes(0)) return true;
+  const text = bytes.toString('utf8');
+  return !Buffer.from(text, 'utf8').equals(bytes);
+}