@daldindev/agentic-skills 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-05
+
+### Added
+
+- `update` and `sync` now keep both changes when a local edit and an upstream change never wrote in the same place, instead of freezing the file for either. A file is only ever combined when the version it was installed from can be read and hashes to exactly what the manifest recorded, and only when no two changes touch; otherwise it stays frozen, exactly as before. Nothing local is ever dropped to make a merge possible, and no file is left half-combined.
+- `--no-merge` turns that off, leaving every edited file frozen the way earlier versions did.
+- `agentic-skills diff`: for every file a local edit froze, compares three versions - the commit you installed from, your copy, and current upstream - so every difference has a known author. Without a path it lists the frozen files and says whether each is blocked by a real overlap or only by the per-file rule; with a path it prints all three versions of every changed region. Nothing is written, and nothing is merged.
+- `--base-archive` supplies the version you installed from as a local tarball or URL, instead of downloading the commit recorded in the manifest. Used by `update`, `sync`, and `diff`.
+
+### Fixed
+
+- The manifest no longer advances the recorded hash of a file that was skipped. Nothing was written to that file, so the version it descends from has not changed; recording the newer one made it look as though the user had deleted an upstream change they had merely not taken yet.
+
 ## [0.2.0] - 2026-09-05
 
 ### Added

package/README.md

@@ -31,7 +31,7 @@ npx agentic-skills init
 Requirements:
 
 - Node.js `>=20.11`
-- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init`, `update`, or `sync`
+- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init`, `update`, `sync`, or `diff`
 
 ## Quick Start
 
@@ -57,6 +57,7 @@ Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with
 | `agentic-skills update` | Download ag-kit again and update installed files, keeping the ones you edited |
 | `agentic-skills sync` | Install if missing, update if present. One command that works in both states, for unattended runs |
 | `agentic-skills status` | Show what is installed, from which upstream commit, and which files were changed locally |
+| `agentic-skills diff` | Show why your edits froze a file, and what they are holding back |
 
 | Option | Purpose |
 | --- | --- |
@@ -64,7 +65,9 @@ Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with
 | `-d, --dir <name>` | Install directory inside the project, default `.agents` |
 | `-r, --ref <git-ref>` | Upstream branch, tag, or commit to install, default `main` |
 | `--archive <source>` | Install from a local ag-kit `.tar.gz` or a URL instead of GitHub |
+| `--base-archive <source>` | The version you installed from, instead of downloading the commit in the manifest |
 | `-f, --force` | Overwrite files that were modified locally |
+| `--no-merge` | Never combine a local edit with an upstream change; leave every edited file frozen |
 | `--dry-run` | Download and print the plan without writing anything |
 | `--json` | Print machine-readable output |
 
@@ -83,10 +86,23 @@ For each file it compares what is installed, what upstream now has, and the hash
 | Situation | Result |
 | --- | --- |
 | You never touched the file | Updated, or deleted when upstream dropped it |
-| You edited the file | Skipped and listed, unless `--force` |
+| You edited it somewhere upstream did not | Both changes kept |
+| You edited it where upstream also changed it | Skipped and listed, unless `--force` |
 | You created the file yourself | Never touched |
 | Upstream added a file | Installed |
 
+Both are only kept when the two changes can be told apart and never touch. Anywhere they do touch, or where the version you installed from cannot be read, the file stays frozen instead. **Nothing you wrote is ever dropped to make that work**, and a file is never left half-combined: it is reconciled whole or left exactly as it was. `--no-merge` turns the attempt off entirely.
+
+`diff` shows what a skipped file is holding back, and whose text is whose. It reads three versions — the commit you installed from, your copy, and current upstream — so every difference has a known author:
+
+```bash
+npx @daldindev/agentic-skills diff
+```
+
+That lists the frozen files and what each one is stuck on. Pass a path to see the three versions of every changed region in one file.
+
+Nothing is written and nothing is merged, so the decision stays yours: fold the upstream change in by hand, or take upstream and lose your edit with `--force`. Until you do one or the other, that file sits out every update.
+
 To stay on a known upstream state instead of `main`, pass a tag or commit. The same flag reproduces an earlier install exactly:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daldindev/agentic-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install the ag-kit agent roles, skills, and workflows into any project, for any model and any agent harness.",
   "author": "daldindev",
   "license": "MIT",

package/src/cli.mjs

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { PACKAGE_ROOT, readJson } from "./fs-utils.mjs";
-import { DEFAULT_INSTALL_DIR, init, status, sync, update } from "./install.mjs";
+import { DEFAULT_INSTALL_DIR, init, inspect, status, sync, update } from "./install.mjs";
 import { UPSTREAM, extractPort, loadArchive, materialize } from "./upstream.mjs";
 
 const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workflows into any project
@@ -14,13 +14,19 @@ Usage:
   agentic-skills update  [options]   Download ag-kit again and update installed files, preserving local edits
   agentic-skills sync    [options]   Install if missing, update if present; safe to run unattended
   agentic-skills status  [options]   Show what is installed and which files were changed locally
+  agentic-skills diff    [path]      Show why your edits froze a file, and what they are holding back
 
 Options:
   -p, --path <dir>        Project directory (default: current directory)
   -d, --dir <name>        Install directory inside the project (default: ${DEFAULT_INSTALL_DIR})
   -r, --ref <git-ref>     Upstream branch, tag, or commit to install (default: ${UPSTREAM.ref})
       --archive <source>  Install from a local ag-kit .tar.gz or a URL instead of GitHub
+      --base-archive <s>  The version you installed from, as a local .tar.gz or URL, instead of
+                          downloading the commit in the manifest. Used to tell your changes
+                          from upstream's, by update, sync, and diff
   -f, --force             Overwrite locally modified files
+      --no-merge          Never combine a local edit with an upstream change; leave every
+                          edited file frozen, whether or not the two touch
       --dry-run           Download and show the plan without writing anything
       --json              Print machine-readable output
   -h, --help              Show this help
@@ -40,7 +46,9 @@ const { values, positionals } = parseArgs({
     dir: { type: "string", short: "d" },
     ref: { type: "string", short: "r", default: UPSTREAM.ref },
     archive: { type: "string" },
+    "base-archive": { type: "string" },
     force: { type: "boolean", short: "f", default: false },
+    "no-merge": { type: "boolean", default: false },
     "dry-run": { type: "boolean", default: false },
     json: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
@@ -59,10 +67,10 @@ const list = (label, items, format = (item) => item) => {
   for (const item of items) console.log(`  ${format(item)}`);
 };
 
-/** Download the upstream archive and lay the ported tree out in a temp dir. */
-const fetchIncoming = async () => {
-  log(values.archive ? `Reading ${values.archive}` : `Downloading ${UPSTREAM.repository} at ${values.ref}`);
-  const buffer = await loadArchive({ ref: values.ref, archive: values.archive });
+/** Download one upstream archive and lay the ported tree out in a temp dir. */
+const fetchTree = async ({ ref = null, archive = null }) => {
+  log(archive ? `Reading ${archive}` : `Downloading ${UPSTREAM.repository} at ${ref}`);
+  const buffer = await loadArchive({ ref, archive });
   const port = extractPort(buffer);
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agentic-skills-"));
   try {
@@ -76,7 +84,7 @@ const fetchIncoming = async () => {
     dir,
     upstream: {
       repository: UPSTREAM.repository,
-      ref: values.archive ? null : values.ref,
+      ref: archive ? null : ref,
       commit: port.commit,
       version: port.version,
     },
@@ -84,6 +92,31 @@ const fetchIncoming = async () => {
   };
 };
 
+/**
+ * The version the install came from, so both sides of a local edit can be told
+ * apart. Called only once something is actually frozen, and never fatal: without
+ * it the run just stays as conservative as it was before.
+ *
+ * `--archive` means this run was asked not to reach for the network, so the base
+ * has to come from `--base-archive` or not at all.
+ */
+let loadedBase = null;
+const loadBase = async (manifest) => {
+  const archive = values["base-archive"];
+  if (!archive && values.archive) return null;
+
+  const commit = manifest?.upstream?.commit;
+  if (!archive && !commit) return null;
+
+  try {
+    loadedBase = await fetchTree(archive ? { archive } : { ref: commit });
+    return loadedBase;
+  } catch (error) {
+    console.error(`warning: could not read the version you installed from: ${error.message}`);
+    return null;
+  }
+};
+
 const describeUpstream = (upstream) => {
   if (!upstream) return "unknown upstream";
   const commit = upstream.commit ? ` (${upstream.commit.slice(0, 7)})` : "";
@@ -96,10 +129,12 @@ const printPlan = (result) => {
   console.log(`${prefix}${result.mode}: ${result.installDir}`);
   console.log(`${prefix}source: ${describeUpstream(result.upstream)}`);
   console.log(
-    `${prefix}added ${plan.add.length}, updated ${plan.update.length}, removed ${plan.remove.length}, ` +
-    `skipped ${plan.skip.length}, kept ${plan.keep.length}, unchanged ${plan.unchanged.length}`,
+    `${prefix}added ${plan.add.length}, updated ${plan.update.length}, merged ${plan.merge.length}, ` +
+    `removed ${plan.remove.length}, skipped ${plan.skip.length}, kept ${plan.keep.length}, ` +
+    `unchanged ${plan.unchanged.length}`,
   );
-  list("Skipped (modified locally; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
+  list("Merged (your change and upstream's did not touch)", plan.merge, (item) => item.file);
+  list("Skipped (left frozen; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
   list("Kept (removed upstream but modified locally)", plan.keep, (item) => `${item.file}: ${item.reason}`);
   if (result.hadManifest === false && plan.skip.length) {
     console.log("\nNo manifest was found, so files that differ from upstream were skipped. Re-run with --force to overwrite them.");
@@ -109,6 +144,86 @@ const printPlan = (result) => {
   }
 };
 
+const SIDE = { base: "base ", yours: "yours", upstream: "upstr" };
+const REGION_LINES = 20;
+const plural = (count, word) => `${count} ${count === 1 ? word : `${word}s`}`;
+
+const authorPhrase = (authors) => {
+  if (authors.length === 2) return "both sides wrote here";
+  return authors[0] === "yours" ? "only you wrote here" : "only upstream wrote here";
+};
+
+/** One side of a region. A bare `|` is a blank line; no `|` means the side has nothing here. */
+const printSide = (side, lines) => {
+  if (!lines.length) {
+    console.log(`      ${SIDE[side]}   nothing here`);
+    return;
+  }
+  for (const line of lines.slice(0, REGION_LINES)) console.log(`      ${SIDE[side]} | ${line}`);
+  const rest = lines.length - REGION_LINES;
+  if (rest > 0) console.log(`      ${SIDE[side]}   ~ ${plural(rest, "more line")} ~`);
+};
+
+const printDiffFile = (report, entry) => {
+  console.log(entry.file);
+  console.log(`  installed ${describeUpstream(report.base)} -> upstream ${describeUpstream(report.upstream)}`);
+  console.log(`  ${plural(entry.regions.length, "region")} changed, ${entry.collisions} written by both sides`);
+
+  entry.regions.forEach((region, index) => {
+    console.log(`\n  [${index + 1}] ${region.where.padEnd(38)} ${authorPhrase(region.authors)}`);
+    printSide("base", region.base);
+    printSide("yours", region.yours);
+    printSide("upstream", region.upstream);
+    if (region.authors.length === 2) {
+      console.log("\n      note: no untouched line separates your lines from upstream's here,");
+      console.log("            so neither side can be applied without deciding about the other.");
+    }
+  });
+
+  console.log("\ndiff only reads - nothing was written.");
+};
+
+const printDiffSummary = (report) => {
+  console.log(`diff:   ${report.installDir}`);
+  console.log(`source: ${describeUpstream(report.upstream)}`);
+  if (report.comparedAgainstBase) console.log(`base:   ${describeUpstream(report.base)}`);
+
+  const entries = [...report.frozen, ...report.removedUpstream];
+  if (!entries.length) {
+    console.log("\nNothing is frozen: every installed file either matches upstream, tracks it cleanly, or is your own.");
+    return;
+  }
+
+  const width = Math.max(...entries.map((entry) => entry.file.length));
+  if (!report.comparedAgainstBase) {
+    console.log(`\n${plural(entries.length, "frozen file")}, and no way to tell your changes from upstream's:`);
+    console.log(report.hadManifest
+      ? "the version this install came from could not be read. Pass --base-archive to supply it."
+      : "this install has no manifest saying which version it came from.");
+    for (const entry of entries) console.log(`  ${entry.file}`);
+    return;
+  }
+
+  const blocked = report.frozen.filter((entry) => entry.collisions > 0).length;
+  const byRule = report.frozen.length - blocked;
+  const parts = [];
+  if (blocked) parts.push(`${blocked} blocked by an overlap`);
+  if (byRule) parts.push(`${byRule} frozen by the per-file rule alone`);
+  if (report.removedUpstream.length) parts.push(`${report.removedUpstream.length} removed upstream`);
+
+  console.log(`\n${plural(entries.length, "frozen file")}. ${parts.join(", ")}.`);
+  console.log("diff only reads - nothing was written.\n");
+
+  for (const entry of report.frozen) {
+    const both = entry.collisions ? `${entry.collisions} written by both sides` : "none written by both sides";
+    console.log(`  ${entry.file.padEnd(width)}  ${plural(entry.regions.length, "region")} changed, ${both}`);
+  }
+  for (const entry of report.removedUpstream) {
+    console.log(`  ${entry.file.padEnd(width)}  removed upstream, kept because you edited it`);
+  }
+  console.log('\nRun "agentic-skills diff <path>" to see the three versions of one file.');
+};
+
 const printStatus = (info) => {
   console.log(`package:   ${info.package.packageName} ${info.package.packageVersion}`);
   console.log(`target:    ${info.installDir}`);
@@ -135,7 +250,8 @@ try {
   } else if (values.help || !command || command === "help") {
     process.stdout.write(HELP);
   } else if (command === "init" || command === "update" || command === "sync") {
-    const incoming = await fetchIncoming();
+    const merging = !values.force && !values["no-merge"];
+    const incoming = await fetchTree({ ref: values.ref, archive: values.archive });
     try {
       const options = {
         path: values.path,
@@ -143,6 +259,7 @@ try {
         force: values.force,
         dryRun: values["dry-run"],
         incomingDir: incoming.dir,
+        loadBase: merging ? loadBase : null,
         upstream: incoming.upstream,
       };
       const run = { init, update, sync }[command];
@@ -152,6 +269,34 @@ try {
       if (result.plan.skip.length || result.plan.keep.length) process.exitCode = 2;
     } finally {
       await incoming.cleanup();
+      if (loadedBase) await loadedBase.cleanup();
+    }
+  } else if (command === "diff") {
+    const target = { path: values.path, dir: values.dir };
+    const incoming = await fetchTree({ ref: values.ref, archive: values.archive });
+    try {
+      const report = await inspect({
+        ...target,
+        incomingDir: incoming.dir,
+        loadBase,
+        upstream: incoming.upstream,
+      });
+
+      const wanted = positionals[1]?.replaceAll("\\", "/");
+      if (values.json) console.log(JSON.stringify(report, null, 2));
+      else if (!wanted) printDiffSummary(report);
+      else {
+        const entry = report.frozen.find((item) => item.file === wanted);
+        if (entry?.regions) printDiffFile(report, entry);
+        else if (entry) console.error(`${wanted} is frozen, but the version you installed from could not be read.`);
+        else {
+          console.error(`${wanted} is not frozen. Run "agentic-skills diff" to list the files that are.`);
+          process.exitCode = 1;
+        }
+      }
+    } finally {
+      await incoming.cleanup();
+      if (loadedBase) await loadedBase.cleanup();
     }
   } else if (command === "status") {
     const info = await status({ path: values.path, dir: values.dir });

package/src/diff.mjs

@@ -0,0 +1,219 @@
+/**
+ * Three-way comparison of one file, used to explain why a local edit froze it.
+ *
+ * Everything is measured against the version the user installed from, so every
+ * difference has a known author: the installed tree changed it, upstream
+ * changed it, or both wrote in the same place. A two-way comparison cannot
+ * tell those apart, which is the whole reason this exists.
+ *
+ * Nothing here merges anything. It only describes.
+ */
+
+/** Above this many table cells the alignment degrades to "replaced wholesale". */
+const MAX_CELLS = 4_000_000;
+
+export const toLines = (text) => {
+  const lines = text.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+};
+
+const mark = (type) => (line) => ({ type, line });
+
+/** Longest common subsequence alignment of two line arrays. */
+function align(a, b) {
+  if (!a.length) return b.map(mark("add"));
+  if (!b.length) return a.map(mark("remove"));
+  if (a.length * b.length > MAX_CELLS) return [...a.map(mark("remove")), ...b.map(mark("add"))];
+
+  const width = b.length + 1;
+  const table = new Uint32Array((a.length + 1) * width);
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i * width + j] = a[i] === b[j]
+        ? table[(i + 1) * width + j + 1] + 1
+        : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+    }
+  }
+
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+      ops.push({ type: "remove", line: a[i++] });
+    } else {
+      ops.push({ type: "add", line: b[j++] });
+    }
+  }
+  while (i < a.length) ops.push({ type: "remove", line: a[i++] });
+  while (j < b.length) ops.push({ type: "add", line: b[j++] });
+  return ops;
+}
+
+/**
+ * Compare two texts line by line. Identical head and tail are trimmed first,
+ * so an edit in one section does not pay for the rest of the file.
+ */
+export function diffLines(before, after) {
+  const a = toLines(before);
+  const b = toLines(after);
+
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+
+  return [
+    ...a.slice(0, start).map(mark("context")),
+    ...align(a.slice(start, endA), b.slice(start, endB)),
+    ...a.slice(endA).map(mark("context")),
+  ];
+}
+
+/**
+ * Rewrite the comparison as an edit script against the base: a list of
+ * `[start, end)` base ranges and the lines that replace each one. An insertion
+ * is an empty range, which is what lets two insertions at the same point be
+ * recognised as the same place.
+ */
+function editsAgainstBase(baseLines, otherLines) {
+  // Trim the identical head and tail first, so a one-line change in a long file
+  // never pays for the whole file, and never trips the size cap in `align`.
+  let start = 0;
+  while (start < baseLines.length && start < otherLines.length && baseLines[start] === otherLines[start]) start++;
+
+  let endBase = baseLines.length;
+  let endOther = otherLines.length;
+  while (endBase > start && endOther > start && baseLines[endBase - 1] === otherLines[endOther - 1]) {
+    endBase--;
+    endOther--;
+  }
+
+  const ops = align(baseLines.slice(start, endBase), otherLines.slice(start, endOther));
+  const edits = [];
+  let index = start;
+  let current = null;
+
+  for (const op of ops) {
+    if (op.type === "context") {
+      if (current) edits.push(current);
+      current = null;
+      index++;
+      continue;
+    }
+    current ||= { start: index, end: index, lines: [] };
+    if (op.type === "remove") current.end = ++index;
+    else current.lines.push(op.line);
+  }
+  if (current) edits.push(current);
+
+  return edits;
+}
+
+/** Replay one side's edits over a slice of the base. */
+function applyEdits(baseLines, start, end, edits) {
+  const out = [];
+  let cursor = start;
+  for (const edit of edits) {
+    out.push(...baseLines.slice(cursor, edit.start));
+    out.push(...edit.lines);
+    cursor = edit.end;
+  }
+  out.push(...baseLines.slice(cursor, end));
+  return out;
+}
+
+/**
+ * Every place the two sides diverged from the base, with all three versions of
+ * that place and who wrote there.
+ *
+ * Ranges that touch are one region, the way a merge tool treats them: two
+ * changes with no untouched line between them cannot be applied independently.
+ */
+export function changedRegions({ base, yours, upstream }) {
+  const baseLines = toLines(base);
+  const sides = {
+    yours: editsAgainstBase(baseLines, toLines(yours)),
+    upstream: editsAgainstBase(baseLines, toLines(upstream)),
+  };
+
+  const all = Object.entries(sides)
+    .flatMap(([side, edits]) => edits.map((edit) => ({ ...edit, side })))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+
+  const grouped = [];
+  for (const edit of all) {
+    const last = grouped[grouped.length - 1];
+    if (last && edit.start <= last.end) {
+      last.end = Math.max(last.end, edit.end);
+      last.parts.push(edit);
+    } else {
+      grouped.push({ start: edit.start, end: edit.end, parts: [edit] });
+    }
+  }
+
+  return grouped.map((region) => {
+    const authors = [...new Set(region.parts.map((part) => part.side))].sort();
+    const partsFor = (side) => region.parts.filter((part) => part.side === side);
+    return {
+      baseStart: region.start,
+      baseEnd: region.end,
+      authors,
+      base: baseLines.slice(region.start, region.end),
+      yours: applyEdits(baseLines, region.start, region.end, partsFor("yours")),
+      upstream: applyEdits(baseLines, region.start, region.end, partsFor("upstream")),
+    };
+  });
+}
+
+/**
+ * Combine both sides when, and only when, they never wrote in the same place.
+ *
+ * A region with one author is unambiguous: taking that author's text is the
+ * same operation `update` performs on a file nobody edited, with the scope
+ * corrected from the file to the region. A region with two authors has no
+ * answer that is not a guess, so the whole file is refused rather than
+ * half-merged. Nothing the user wrote is ever dropped by this function.
+ */
+export function mergeClean({ base, yours, upstream }) {
+  const regions = changedRegions({ base, yours, upstream });
+  const conflicts = regions.filter((region) => region.authors.length === 2);
+  if (conflicts.length) return { merged: null, conflicts: conflicts.length };
+
+  const baseLines = toLines(base);
+  const out = [];
+  let cursor = 0;
+  for (const region of regions) {
+    out.push(...baseLines.slice(cursor, region.baseStart));
+    out.push(...(region.authors[0] === "yours" ? region.yours : region.upstream));
+    cursor = region.baseEnd;
+  }
+  out.push(...baseLines.slice(cursor));
+
+  // The result replaces the reader's file, so it keeps the reader's line endings
+  // and their choice about a final newline. A merge should change what it says,
+  // not how every line in the file is terminated.
+  const eol = yours.includes("\r\n") ? "\r\n" : "\n";
+  const trailing = /\r?\n$/.test(yours) ? eol : "";
+  return { merged: out.length ? out.join(eol) + trailing : "", conflicts: 0 };
+}
+
+/** The nearest Markdown heading above a region, to say where in the file it sits. */
+export function locate(base, region) {
+  const baseLines = toLines(base);
+  if (region.baseStart >= baseLines.length) return "end of file";
+  for (let i = region.baseStart; i >= 0; i--) {
+    if (baseLines[i].startsWith("#")) return `line ${region.baseStart + 1}, in "${baseLines[i].trim()}"`;
+  }
+  return `line ${region.baseStart + 1}`;
+}

package/src/install.mjs

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { changedRegions, locate, mergeClean } from "./diff.mjs";
 import {
   PACKAGE_ROOT,
   copyFile,
   exists,
+  hashFile,
   readJson,
   removeEmptyParents,
   snapshotTree,
@@ -54,6 +56,29 @@ async function writeManifest(installDir, files, { previous = null, upstream = nu
   return manifest;
 }
 
+/**
+ * What each installed file descends from after this run.
+ *
+ * Only files this run actually wrote move to the incoming hash. A file left
+ * frozen keeps the hash it had, because its ancestor is still the version it was
+ * last written from; recording the new one would make a later merge read
+ * upstream's change as the user having deleted it.
+ */
+function nextManifestFiles({ previous, plan }) {
+  const kept = new Set(plan.keep.map((item) => item.file));
+  const files = {};
+
+  // Carry an entry forward only while the file is still something to track:
+  // upstream still ships it, or it is on disk because an edit saved it.
+  for (const [file, hash] of Object.entries(previous)) {
+    if (plan.incoming[file] !== undefined || kept.has(file)) files[file] = hash;
+  }
+
+  for (const file of [...plan.add, ...plan.update, ...plan.unchanged]) files[file] = plan.incoming[file];
+  for (const { file } of plan.merge ?? []) files[file] = plan.incoming[file];
+  return files;
+}
+
 /**
  * Three-way comparison between the installed tree, the incoming tree fetched
  * from upstream, and the hashes recorded at the last install or update.
@@ -103,10 +128,53 @@ export async function planUpdate({ installDir, incomingDir, manifest = null, for
   return plan;
 }
 
+/**
+ * Try to combine both sides for the files the plan would otherwise skip.
+ *
+ * A file is only ever a merge candidate when the downloaded base hashes to the
+ * exact value the manifest recorded for it. That proves the text being used as
+ * the common ancestor is the text that was installed; without that proof the
+ * file is left frozen, because a wrong ancestor is how a merge loses work.
+ */
+export async function resolveMerges({ installDir, incomingDir, baseDir, plan, manifest }) {
+  if (!baseDir || !manifest) return { merge: [], skip: plan.skip };
+
+  const merge = [];
+  const skip = [];
+
+  for (const item of plan.skip) {
+    const recorded = manifest.files?.[item.file];
+    const basePath = path.join(baseDir, item.file);
+    const provable = recorded && (await exists(basePath)) && (await hashFile(basePath)) === recorded;
+    if (!provable) {
+      skip.push({ ...item, reason: `${item.reason}; no proven common ancestor to merge from` });
+      continue;
+    }
+
+    const [base, yours, incoming] = await Promise.all([
+      fs.readFile(basePath, "utf8"),
+      fs.readFile(path.join(installDir, item.file), "utf8"),
+      fs.readFile(path.join(incomingDir, item.file), "utf8"),
+    ]);
+
+    const { merged, conflicts } = mergeClean({ base, yours, upstream: incoming });
+    if (merged === null) {
+      skip.push({ ...item, reason: `your change and upstream's overlap in ${conflicts === 1 ? "one place" : `${conflicts} places`}` });
+      continue;
+    }
+    merge.push({ file: item.file, text: merged });
+  }
+
+  return { merge, skip };
+}
+
 export async function applyPlan({ installDir, incomingDir, plan }) {
   for (const file of [...plan.add, ...plan.update]) {
     await copyFile(path.join(incomingDir, file), path.join(installDir, file));
   }
+  for (const { file, text } of plan.merge ?? []) {
+    await fs.writeFile(path.join(installDir, file), text);
+  }
   for (const file of plan.remove) {
     const target = path.join(installDir, file);
     await fs.rm(target, { force: true });
@@ -114,6 +182,17 @@ export async function applyPlan({ installDir, incomingDir, plan }) {
   }
 }
 
+/**
+ * Where the version this install came from can be read, if anywhere. `loadBase`
+ * is only called once the plan actually has something frozen, so an install with
+ * no local edits never pays for a second download.
+ */
+async function baseFor(options, plan, manifest) {
+  if (options.baseDir) return { dir: options.baseDir, upstream: options.base || null };
+  if (!plan.skip.length || !options.loadBase) return null;
+  return (await options.loadBase(manifest)) || null;
+}
+
 async function hasContent(dir) {
   if (!(await exists(dir))) return false;
   const entries = await fs.readdir(dir);
@@ -131,9 +210,22 @@ async function reconcile(mode, options) {
   const created = !(await hasContent(installDir));
   const manifest = await loadManifest(installDir);
   const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
+
+  const base = await baseFor(options, plan, manifest);
+  const resolved = await resolveMerges({
+    installDir,
+    incomingDir,
+    baseDir: base?.dir || null,
+    plan,
+    manifest,
+  });
+  plan.merge = resolved.merge;
+  plan.skip = resolved.skip;
+
   if (!options.dryRun) {
     await applyPlan({ installDir, incomingDir, plan });
-    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
+    const files = nextManifestFiles({ previous: manifest?.files || {}, plan });
+    await writeManifest(installDir, files, { previous: manifest, upstream });
   }
   return {
     mode,
@@ -180,6 +272,60 @@ export async function sync(options = {}) {
   return reconcile("sync", options);
 }
 
+/**
+ * Report what upstream changed in the files a local edit froze.
+ *
+ * `status` says which files stopped receiving updates; this says what they
+ * stopped receiving. Nothing is written, and nothing is merged: the installer
+ * never reconciles an edited file on its own, so this is the input a person
+ * needs to do it by hand.
+ */
+export async function inspect(options = {}) {
+  const { installDir } = resolveTarget(options);
+  const { incomingDir, upstream = null } = options;
+
+  if (!(await exists(installDir))) {
+    throw new Error(`${installDir} does not exist. Run "agentic-skills init" first.`);
+  }
+
+  const manifest = await loadManifest(installDir);
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force: false });
+  const base = await baseFor(options, plan, manifest);
+  const baseDir = base?.dir || null;
+  const read = async (dir, file) => (dir ? fs.readFile(path.join(dir, file), "utf8").catch(() => null) : null);
+
+  const frozen = [];
+  for (const { file, reason } of plan.skip) {
+    const yours = await read(installDir, file);
+    const incoming = await read(incomingDir, file);
+    // A file upstream added after this install has no base text; treat it as empty
+    // so both sides read as having written the whole thing, which is the truth.
+    const baseText = (await read(baseDir, file)) ?? "";
+
+    const regions = baseDir
+      ? changedRegions({ base: baseText, yours, upstream: incoming })
+        .map((region) => ({ ...region, where: locate(baseText, region) }))
+      : null;
+
+    frozen.push({
+      file,
+      reason,
+      regions,
+      collisions: regions ? regions.filter((region) => region.authors.length === 2).length : null,
+    });
+  }
+
+  return {
+    installDir,
+    upstream,
+    base: base?.upstream || null,
+    comparedAgainstBase: Boolean(baseDir),
+    hadManifest: Boolean(manifest),
+    frozen,
+    removedUpstream: plan.keep,
+  };
+}
+
 /** Local report only; nothing is fetched. */
 export async function status(options = {}) {
   const { installDir } = resolveTarget(options);