@salaros/ai-harness 0.3.5 → 0.4.0

package/README.md

@@ -38,7 +38,17 @@ From the repository's root:
 npx @salaros/ai-harness
 ```
 
-The installer adds the harness files and leaves your own work alone: it never writes `README.md` or `LICENSE`, and it adds a folder README only where one is missing. It records the upstream commit it installed in `harness-lock.json`.
+The installer adds the harness files and leaves your own work alone: it never writes `README.md` or `LICENSE`, and it adds a folder README only where one is missing. It records the upstream commit it installed in `harness-lock.json`, then points Git at the harness's hooks in this clone. Other clones run `node scripts/githooks-init.js` once.
+
+If the repository already has agent files of its own, the first install keeps them and adds what the harness needs:
+
+| File | What the first install does |
+| --- | --- |
+| `AGENTS.md`, `docs/README.md` | Writes the harness's version and appends yours under `## This project`, for you to fold in |
+| `CLAUDE.md` | Adds `@AGENTS.md` at the top if it's missing |
+| `.claude/settings.json` | Merges by key: replaces the harness's hooks, keeps your permissions and hooks (on every update, too) |
+| `.mcp.json` | Adds the harness's MCP servers; yours win where both define one |
+| `.gitignore` | Appends the harness's patterns you don't have, under a comment |
 
 Run the same command again to update. Files you haven't edited take the new version, files you have edited keep your changes and gain the new ones, and a real conflict is written with conflict markers and reported.
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Installs and updates the agent harness from its upstream repository: hooks, skills, agents and the documentation chain, merged into an existing repository without touching its own work.",
   "bin": {
     "ai-harness": "scripts/update-harness.js"
   },
   "files": [
     "scripts/update-harness.js",
+    "scripts/install-policy.js",
     "scripts/lib.js",
     "scripts/project-facts.js",
     "scripts/repo-view.js",

package/scripts/README.md

@@ -17,6 +17,11 @@ part of the product.
 
 - One task per script, named after what it does (`githooks-init.js`,
   `build.js`, `release.js`); Node, so they run the same on every OS.
+- The scripts are CommonJS. `package.json` here, and its twin in
+  `.agents/hooks/`, says so, so a project whose root `package.json` declares
+  `"type": "module"` does not turn them into ES modules that fail on their
+  first `require`. A script of the project's own that uses `import` is
+  named `.mjs`.
 - Scripts are safe to run from any working directory — every script and hook
   asks `lib.root()` which repo it is about, and gets one answer: `--root=<dir>`
   when given, then the harness's project-dir variable

package/scripts/install-policy.js

@@ -0,0 +1,318 @@
+// scripts/install-policy.js
+// What an install does with one path the upstream ships: the policies scripts/harness-files.tsv
+// names, each decided here and nowhere else. scripts/update-harness.js walks the paths, reads what a
+// decision needs and applies what it answers; this module reads nothing and writes nothing.
+//   const policy = require("./install-policy");
+//   const { policy: name, asked } = policy.policyFor(rows, file, wants);
+//   const { outcome, bucket, write, silent } = policy.decide(name, facts, reads);
+// `facts` is what the caller already knows about the path; `reads` holds the things a decision may
+// need and costs something to find out, called only when the decision gets that far:
+//   facts  exists     the target has something at the path
+//          theirs     the upstream's content at the head: LF text, or a Buffer
+//          hasBase    the receipt names a commit the upstream still has
+//          adopt      --adopt was given
+//          asked      the path is an optional part, and the run asked for it
+//   reads  held()           the target's copy, read the way `theirs` is (text or bytes)
+//          base()           the upstream's content at the receipt's commit, or null
+//          shippedBefore()  an earlier run laid this path down, so its absence is a deletion
+//          recoverBase(ours) the upstream version nearest the target's copy, or null
+//          merge(base, ours, theirs)  a three-way merge: { text, conflicts, failed }
+// The answer: `outcome` is the word the run prints, `bucket` the summary list the path joins (null
+// for a path nothing happened to), `write` the content to write when there is any, `silent`
+// when the path is counted in the summary but never printed as a line, and `notice` a sentence the
+// run prints before its summary, for a result someone has to finish by hand.
+const lib = require("./lib");
+
+// ---------------------------------------------------------------- the manifest
+
+// First match wins, so the table's order is its precedence. A row ending in / covers everything under it.
+// `optional:<flag>` is seeded only when the run asked for it, and is otherwise not installed at all:
+// the docs site is the case, useful to some projects and dead weight in the rest.
+// `wants` answers whether the run asked for an optional part, so the table's meaning does not depend
+// on the process's own argv and a test can ask what a repo would get either way.
+const rowFor = (rows, file) => rows.find(r => r.path.endsWith("/") ? file.startsWith(r.path) : file === r.path);
+function policyFor(rows, file, wants) {
+    const row = rowFor(rows, file);
+    if (!row) return { policy: "merge", asked: false };     // anything the upstream ships and nobody classified is harness
+    if (!row.policy.startsWith("optional:")) return { policy: row.policy, asked: false };
+    const asked = wants(row.policy.slice("optional:".length));
+    return { policy: asked ? "seed" : "template", asked };
+}
+
+// ---------------------------------------------------------------- merging a file the target has
+
+// This script's own conflict label, on a line of its own, so prose about conflict markers is not
+// mistaken for one.
+const MARKED = /^<{7} yours\r?$/m;
+
+// A file with no lines to merge: it is the upstream's copy or it is the project's, and the base
+// decides which. A logo the project replaced stays replaced.
+function decideBinary({ held, theirs, hasBase, adopt }, { base }) {
+    if (lib.sameContent(held, theirs)) return { outcome: "unchanged", bucket: null };
+    const was = hasBase ? base() : null;
+    if (adopt || lib.sameContent(held, was)) return { outcome: adopt ? "adopted" : "written", bucket: "written", write: theirs };
+    return { outcome: hasBase ? "yours, binary" : "yours, no base", bucket: "kept" };
+}
+
+// A text file. `raw` is what is on disk, in whatever line endings it has; `theirs` is the upstream's,
+// always LF. The comparison and the merge happen in LF and the result is written back in the endings
+// the file already had, so a Windows checkout does not read as edited from top to bottom.
+function decideText({ policy, raw, theirs, hasBase, adopt }, { base, recoverBase, merge }) {
+    const crlf = lib.isCrlf(raw);
+    const ours = lib.toLf(raw);
+    const keep = { outcome: hasBase ? "yours, new here" : "yours, no base", bucket: "kept" };
+
+    if (ours === theirs) return { outcome: "unchanged", bucket: null };
+    // Before the base logic, not inside it: a repo that needs adopting usually has a receipt
+    // already, written by the install that kept the stale files in the first place.
+    if (adopt) return { outcome: "adopted", bucket: "written", write: lib.asFound(theirs, crlf) };
+    // Markers an earlier run wrote and nobody resolved. Left to the merge, the marked-up file is now
+    // its own nearest base, so the merge takes it whole, the run says "unchanged" and a half-merged
+    // harness passes as settled. Named instead, and the run exits 1 until someone resolves it or
+    // --adopt above throws it away.
+    if (MARKED.test(ours)) return { outcome: "STILL OPEN", bucket: "conflicted" };
+
+    // Claude Code's settings are merged by key on every run, base or none: see mergeSettings.
+    if (policy === "settings") return decideSettings(ours, theirs, crlf);
+
+    // A reconcile file is one the harness cannot work around: AGENTS.md is the map every agent reads
+    // and holds the table docs-check parses, and docs/README.md says what the chain puts where.
+    // Keeping a stale one leaves a repo that looks installed and behaves like the version it came
+    // from, so these are merged even when the receipt is missing. Nothing in the upstream's history
+    // matching means this copy was written by hand, for a project that had agent instructions before
+    // it had the harness: see appendProject.
+    let from = hasBase ? base() : null;
+    if (from === null && policy === "reconcile") from = recoverBase(ours);
+    // A union table merges by row whether or not there is a base, and even an untouched copy goes
+    // through that merge: it may hold a row the upstream dropped and the project still needs.
+    if (from === null && policy === "union") from = "";
+    if (from === null) {
+        const own = WITHOUT_BASE[policy];
+        const done = own ? own(ours, theirs) : null;
+        if (!done) return keep;
+        return { ...done, write: lib.asFound(done.write, crlf) };
+    }
+
+    if (ours === from && policy !== "union") return { outcome: "written", bucket: "written", write: lib.asFound(theirs, crlf) };
+    const merged = merge(from, ours, theirs);
+    if (merged.failed) return { outcome: "yours, merge failed", bucket: "kept" };
+    const result = lib.asFound(merged.text, crlf);
+    if (merged.conflicts) return { outcome: "CONFLICT", bucket: "conflicted", write: result };
+    // A file that keeps a local edit merges cleanly on every later run and comes out the same every
+    // time. Reported as merged each run it reads as churn, and the reader goes looking for a change
+    // nobody made, so what the run did is decided by the result, not the route.
+    if (result === raw) return { outcome: "unchanged", bucket: null };
+    return { outcome: "merged", bucket: "merged", write: result };
+}
+
+// A union table, merged row by row rather than line by line: a row is keyed by its first
+// tab-separated column, and the table is a set of them, so there is nothing to conflict over.
+// The upstream's comments and order come first. Each of its rows is the project's where only the
+// project changed it, or where both did, and the upstream's otherwise; a row the project deleted
+// stays deleted. Every row of the project's the upstream lacks follows, whether the project added it
+// or the upstream dropped it: the licence of a skill the upstream stopped shipping is still needed
+// here, because the skills merge keeps the skill. All three texts are LF; `base` is null without a
+// receipt, and then the project's copy of a row wins.
+function mergeRows(base, ours, theirs) {
+    const rows = text => new Map((text || "").split("\n").filter(l => l.trim() && !l.startsWith("#")).map(l => [l.split("\t")[0], l]));
+    const was = rows(base), mine = rows(ours), up = rows(theirs);
+    const out = [];
+    for (const line of theirs.split("\n")) {
+        const key = line.split("\t")[0];
+        if (!line.trim() || line.startsWith("#") || !up.has(key)) { out.push(line); continue; }
+        const o = mine.get(key), b = was.get(key);
+        if (o === undefined) { if (b === undefined) out.push(line); continue; }
+        out.push(o === b ? line : o);
+    }
+    const extra = [...mine].filter(([key]) => !up.has(key)).map(([, line]) => line);
+    if (!extra.length) return out.join("\n");
+    while (out.length && out[out.length - 1] === "") out.pop();
+    return [...out, ...extra, ""].join("\n");
+}
+const unionMerge = (from, ours, up) => ({ text: mergeRows(from, ours, up), conflicts: false, failed: false });
+
+// ---------------------------------------------------------------- a file that has no base
+
+// What a policy does with a text file the target already has and no upstream version to merge it
+// against: a first install into a project that set up its own agent files, ignore list or MCP
+// servers before it took the harness. Plain merge keeps the file whole, the project's work being
+// the one thing an install must not lose; these policies also bring in the part of the upstream's
+// copy the harness cannot work without. Each answers { outcome, bucket, write, notice? } in LF, or
+// null to keep the file as it is. A later run has the receipt, so each runs once per file.
+const WITHOUT_BASE = {
+    reconcile: appendProject,
+    import: addImport,
+    ignore: appendPatterns,
+    keyed: (ours, theirs) => {
+        const merged = mergeJson(ours, theirs, (o, t) => mergeKeys(o, t, 2));
+        return merged && { outcome: "merged by key", bucket: "merged", write: merged };
+    },
+};
+
+// The upstream's copy, then the project's under a heading of its own. A whole-file conflict was the
+// earlier answer, and it left the one file every agent reads full of markers, with the run exiting 1
+// on a first install. The harness's text is what the rest of the harness assumes; the project's is
+// what nobody else knows. Both stay, and the notice asks someone to fold the second into the first.
+// The project's headings move down under the new one, so its title does not compete with the file's.
+const PROJECT_HEADING = "## This project";
+function appendProject(ours, theirs) {
+    const note = "<!-- ai-harness: this project's own copy of this file, kept from before the harness was installed. Fold what still applies into the sections above, then delete this section. -->";
+    return {
+        outcome: "yours appended", bucket: "merged",
+        write: [theirs.trimEnd(), "", note, PROJECT_HEADING, "", demoteHeadings(ours).trim(), ""].join("\n"),
+        notice: `the harness's copy was written with the project's own appended under "${PROJECT_HEADING}": fold what still applies into it`,
+    };
+}
+
+// Moves every Markdown heading outside a code fence down, so the shallowest lands one level below
+// PROJECT_HEADING. Six stays six: Markdown has nothing deeper.
+function demoteHeadings(text) {
+    const lines = text.split("\n");
+    let fence = false;
+    const level = lines.map(line => {
+        if (/^\s*(```|~~~)/.test(line)) { fence = !fence; return 0; }
+        const m = !fence && /^(#{1,6})\s/.exec(line);
+        return m ? m[1].length : 0;
+    });
+    const top = Math.min(...level.filter(Boolean));
+    if (!Number.isFinite(top) || top >= 3) return text;
+    return lines.map((line, i) => level[i] ? "#".repeat(Math.min(6, level[i] + 3 - top)) + line.slice(level[i]) : line).join("\n");
+}
+
+// CLAUDE.md is how Claude Code reaches AGENTS.md. A project's own CLAUDE.md, kept whole, leaves Claude
+// reading instructions that never mention the harness, so the import goes on top and the rest stays.
+const IMPORT = "@AGENTS.md";
+function addImport(ours) {
+    if (ours.split("\n").some(l => l.trim() === IMPORT)) return null;
+    return { outcome: "import added", bucket: "merged", write: `${IMPORT}\n\n${ours}` };
+}
+
+// A .gitignore is a set of patterns, so the upstream's that this one lacks go at the end, under a
+// comment saying where they came from; nothing of the project's moves. A pattern the project
+// negates is its decision, and stays unlisted.
+function appendPatterns(ours, theirs) {
+    const have = new Set(ours.split("\n").map(l => l.trim()));
+    const missing = [...new Set(theirs.split("\n").map(l => l.trim()))]
+        .filter(l => l && !l.startsWith("#") && !have.has(l) && !have.has("!" + l));
+    if (!missing.length) return null;
+    const note = "# Added by the ai-harness install: the harness's patterns this file did not have.";
+    return { outcome: "patterns appended", bucket: "merged", write: [ours.trimEnd(), "", note, ...missing, ""].join("\n") };
+}
+
+// ---------------------------------------------------------------- JSON merged by key
+
+const isObject = v => v !== null && typeof v === "object" && !Array.isArray(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// The project's value wins at every key both have; a key only the upstream has is added. Objects are
+// merged down to `depth` levels, below which the project's value is taken whole: an MCP server the
+// project configured is its own, not a blend of two. Arrays are a union, the project's order first.
+function mergeKeys(ours, theirs, depth = Infinity) {
+    if (depth > 0 && isObject(ours) && isObject(theirs)) {
+        const out = { ...ours };
+        for (const [k, v] of Object.entries(theirs)) out[k] = k in ours ? mergeKeys(ours[k], v, depth - 1) : v;
+        return out;
+    }
+    if (Array.isArray(ours) && Array.isArray(theirs)) return [...ours, ...theirs.filter(t => !ours.some(o => same(o, t)))];
+    return ours;
+}
+
+// Both texts parsed and merged; null when either is not JSON or the merge adds nothing. The result is
+// the upstream's own text when it comes out equal to it, so the upstream's layout survives.
+function mergeJson(ours, theirs, merge) {
+    let o, t;
+    try { o = JSON.parse(ours); t = JSON.parse(theirs); } catch { return null; }
+    const merged = merge(o, t);
+    if (same(merged, o)) return null;
+    return same(merged, t) ? theirs : JSON.stringify(merged, null, 2) + "\n";
+}
+
+// .claude/settings.json holds the harness's hook launchers beside whatever the project set up: its
+// permissions, its own hooks, its environment. A line merge of that JSON either keeps a stale
+// launcher or conflicts over a brace, so it is merged by key on every run, receipt or none. Every
+// hook whose command runs a script in .agents/hooks/ is the harness's, and is replaced by the
+// upstream's current set; every other key and hook is the project's and stays.
+const HARNESS_HOOK = /\.agents\/hooks\//;
+function mergeSettings(ours, theirs) {
+    const merged = mergeKeys(ours, theirs);
+    const hooks = {};
+    for (const [event, groups] of Object.entries(isObject(ours.hooks) ? ours.hooks : {})) {
+        if (!Array.isArray(groups)) { hooks[event] = groups; continue; }
+        hooks[event] = groups.map(g => isObject(g) && Array.isArray(g.hooks)
+            ? { ...g, hooks: g.hooks.filter(h => !(isObject(h) && typeof h.command === "string" && HARNESS_HOOK.test(h.command))) }
+            : g).filter(g => !isObject(g) || !Array.isArray(g.hooks) || g.hooks.length);
+    }
+    for (const [event, groups] of Object.entries(isObject(theirs.hooks) ? theirs.hooks : {}))
+        hooks[event] = [...(Array.isArray(hooks[event]) ? hooks[event] : []), ...groups];
+    for (const event of Object.keys(hooks)) if (Array.isArray(hooks[event]) && !hooks[event].length) delete hooks[event];
+    if (Object.keys(hooks).length || "hooks" in ours) merged.hooks = hooks;
+    return merged;
+}
+
+// A project's settings that are not JSON are left for someone to read; the upstream's always are.
+function decideSettings(ours, theirs, crlf) {
+    try { JSON.parse(ours); } catch { return { outcome: "yours, not JSON", bucket: "kept" }; }
+    const merged = mergeJson(ours, theirs, mergeSettings);
+    if (merged === null) return { outcome: "unchanged", bucket: null };
+    return { outcome: "merged by key", bucket: "merged", write: lib.asFound(merged, crlf) };
+}
+
+// ---------------------------------------------------------------- the merging policies
+
+// merge, reconcile, union, import, ignore, keyed and settings: a file the target lacks is written,
+// and one it has is merged.
+function merging(policy) {
+    return (facts, reads) => {
+        if (!facts.exists) return { outcome: "written", bucket: "written", write: facts.theirs };
+        const held = reads.held();
+        if (Buffer.isBuffer(facts.theirs)) return decideBinary({ ...facts, held }, reads);
+        // A union table has no lines to conflict over, and no base means the project's rows win.
+        return decideText({ ...facts, policy, raw: held }, policy === "union" ? { ...reads, merge: unionMerge } : reads);
+    };
+}
+
+// ---------------------------------------------------------------- laying a file down once
+
+// What the project deleted stays deleted. Seed files and skeletons both go down once and are never
+// touched again, so a missing one is either new to this run or one the project removed, and
+// shippedBefore() tells the two apart: for a seed file, the receipt's commit shipped it; for a
+// skeleton, the receipt lists it.
+// TODO: an existing seed file joins the "kept" summary list and an existing skeleton joins none;
+// the two differ only because they grew apart, and unifying them changes what a run reports.
+function layDown(existing) {
+    return ({ exists, theirs, asked }, { shippedBefore }) => {
+        if (exists) return existing;
+        // An optional part is the exception: its flag is the project asking for it now, whatever an
+        // earlier run left out.
+        if (!asked && shippedBefore()) return { outcome: "deleted here", bucket: null };
+        return { outcome: "created", bucket: "seeded", write: theirs };
+    };
+}
+
+// ---------------------------------------------------------------- the policies
+
+const POLICIES = {
+    merge: merging("merge"),
+    reconcile: merging("reconcile"),
+    union: merging("union"),
+    import: merging("import"),
+    ignore: merging("ignore"),
+    keyed: merging("keyed"),
+    settings: merging("settings"),
+    seed: layDown({ outcome: "yours", bucket: "kept" }),
+    skeleton: layDown({ outcome: "yours", bucket: null }),
+    // Reported only when the target actually has it: "left alone, yours" about a file the repo does
+    // not have names something that was never there.
+    skip: ({ exists }) => exists ? { outcome: "yours", bucket: "skipped" } : { outcome: "absent", bucket: null },
+    // Not installed anywhere, and named in one line of the summary instead: sixty-five lines saying
+    // nothing happened bury the thirty-eight saying something did.
+    template: () => ({ outcome: "template", bucket: "template", silent: true }),
+};
+
+function decide(policy, facts, reads = {}) {
+    const rule = POLICIES[policy];
+    if (!rule) throw new Error(`install-policy: no policy named "${policy}"`);
+    return rule(facts, reads);
+}
+
+module.exports = { policyFor, decide };

package/scripts/lib.js

@@ -11,6 +11,8 @@
 //   lib.node(["scripts/skills.js", "missing"]) // run a script with this node; { status, output }
 //   lib.shell("npm install")                 // run a command through the OS shell
 //   lib.readTsv("scripts/stacks.tsv")        // rows as arrays of cells; blank and # lines skipped
+//   lib.toLf(text), lib.asFound(text, crlf)  // compare in LF, write back in the endings a file had
+//   lib.sameContent(a, b)                    // equal text, or equal bytes; never text against bytes
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
@@ -84,4 +86,21 @@ function readTsv(file) {
         .map(l => l.split("\t"));
 }
 
-module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv };
+// Git checks a repo out with the platform's line endings, so a Windows working copy holds CRLF where
+// the upstream stores LF. Compared raw, every line of every file reads as changed: a copy nobody
+// touched reports as edited, and a real edit is buried in a whole-file conflict nobody can read. So
+// a comparison or a merge happens in LF, and the result is written back in the endings the file
+// already had.
+const CRLF = /\r\n/g;
+const LF = /\n/g;
+const isCrlf = text => (text.match(CRLF) || []).length * 2 > (text.match(LF) || []).length;
+const toLf = text => text.replace(CRLF, "\n");
+const asFound = (text, crlf) => crlf ? text.replace(LF, "\r\n") : text;
+
+// One test for text and bytes, so a caller comparing a blob against what is on disk does not have
+// to know which it got.
+const sameContent = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
+    ? Buffer.isBuffer(a) && Buffer.isBuffer(b) && a.equals(b)
+    : a === b;
+
+module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv, isCrlf, toLf, asFound, sameContent };

package/scripts/update-harness.js

@@ -34,6 +34,7 @@ const path = require("path");
 const lib = require("./lib");
 const projectFacts = require("./project-facts");
 const repoView = require("./repo-view");
+const installPolicy = require("./install-policy");
 const { spawnSync } = require("child_process");
 
 const TEMPLATE = "https://github.com/salaros/ai-harness.git";
@@ -198,12 +199,6 @@ function blob(dir, commit, file) {
     return r.stdout.includes(0) ? r.stdout : r.stdout.toString("utf8");
 }
 
-// One test for both, so a caller comparing what blob returned against what is on disk does not have
-// to know which it got.
-const same = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
-    ? Buffer.isBuffer(a) && Buffer.isBuffer(b) && a.equals(b)
-    : a === b;
-
 // ---------------------------------------------------------------- the adapters
 //
 // What plan() reads, and nothing more: the upstream at any commit, and the target as it stands. A
@@ -335,19 +330,6 @@ function policies(templateDir) {
     return lib.readTsv(path.join(templateDir, MANIFEST)).map(([p, policy]) => ({ path: p, policy }));
 }
 
-// First match wins, so the table's order is its precedence. A row ending in / covers everything under it.
-// `optional:<flag>` is seeded only when the run asked for it, and is otherwise not installed at all:
-// the docs site is the case, useful to some projects and dead weight in the rest.
-// `wants` answers whether the run asked for an optional part, so the table's meaning does not depend
-// on the process's own argv and a test can ask what a repo would get either way.
-const rowFor = (rows, file) => rows.find(r => r.path.endsWith("/") ? file.startsWith(r.path) : file === r.path);
-function policyFor(rows, file, wants) {
-    const row = rowFor(rows, file);
-    if (!row) return "merge";               // anything the upstream ships and nobody classified is harness
-    if (!row.policy.startsWith("optional:")) return row.policy;
-    return wants(row.policy.slice("optional:".length)) ? "seed" : "template";
-}
-
 // ---------------------------------------------------------------- skeletons
 
 // Three files the upstream does not ship, because there they would be lies: MEMORY.md
@@ -428,108 +410,6 @@ function settleDropped(text) {
     return { text: out, conflicts: conflicts > 0, failed: false };
 }
 
-// Git checks a repo out with the platform's line endings, so a Windows working copy holds CRLF where
-// the upstream stores LF. Compared raw, every line of every file reads as changed: a copy nobody
-// touched reports as edited, and a real edit is buried in a whole-file conflict nobody can read. So
-// the comparison and the merge happen in LF, and the result is written back in the endings the file
-// already had.
-const CRLF = /\r\n/g;
-const LF = /\n/g;
-// This script's own conflict label, on a line of its own, so prose about conflict markers is not
-// mistaken for one.
-const MARKED = /^<{7} yours\r?$/m;
-const isCrlf = text => (text.match(CRLF) || []).length * 2 > (text.match(LF) || []).length;
-const toLf = text => text.replace(CRLF, "\n");
-const asFound = (text, crlf) => crlf ? text.replace(LF, "\r\n") : text;
-
-// ---------------------------------------------------------------- the decision
-//
-// What happens to one file the target already has, decided apart from doing it. Everything these two
-// read is an argument, including the three things they cannot compute -- the base's text, the search
-// for a base when the receipt has none, and the three-way merge itself -- so plan() passes them in.
-//
-// Both answer the same shape: `outcome` is the word the run prints, `bucket` the summary list it
-// belongs in (null for a file nothing happened to), and `text` what to write, or null to write
-// nothing.
-
-// A file with no lines to merge: it is the upstream's copy or it is the project's, and the base
-// decides which. A logo the project replaced stays replaced.
-function decideBinary({ held, theirs, hasBase, adopt }, { baseBytes }) {
-    if (same(held, theirs)) return { outcome: "unchanged", bucket: null, text: null };
-    const was = hasBase ? baseBytes() : null;
-    if (adopt || same(held, was)) return { outcome: adopt ? "adopted" : "written", bucket: "written", text: theirs };
-    return { outcome: hasBase ? "yours, binary" : "yours, no base", bucket: "kept", text: null };
-}
-
-// A text file. `raw` is what is on disk, in whatever line endings it has; `theirs` is the upstream's,
-// always LF. The comparison and the merge happen in LF and the result is written back in the endings
-// the file already had, so a Windows checkout does not read as edited from top to bottom.
-function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recoverBase, merge }) {
-    const crlf = isCrlf(raw);
-    const ours = toLf(raw);
-    const keep = { outcome: hasBase ? "yours, new here" : "yours, no base", bucket: "kept", text: null };
-
-    if (ours === theirs) return { outcome: "unchanged", bucket: null, text: null };
-    // Before the base logic, not inside it: a repo that needs adopting usually has a receipt
-    // already, written by the install that kept the stale files in the first place.
-    if (adopt) return { outcome: "adopted", bucket: "written", text: asFound(theirs, crlf) };
-    // Markers an earlier run wrote and nobody resolved. Left to the merge, the marked-up file is now
-    // its own nearest base, so the merge takes it whole, the run says "unchanged" and a half-merged
-    // harness passes as settled. Named instead, and the run exits 1 until someone resolves it or
-    // --adopt above throws it away.
-    if (MARKED.test(ours)) return { outcome: "STILL OPEN", bucket: "conflicted", text: null };
-
-    // A reconcile file is one the harness cannot work around: AGENTS.md is the map every agent reads
-    // and holds the table docs-check parses, and docs/README.md says what the chain puts where.
-    // Keeping a stale one leaves a repo that looks installed and behaves like the version it came
-    // from, so these are merged even when the receipt is missing. Nothing in the upstream's history
-    // matching means this copy was written by hand, and an empty base makes the whole file one
-    // conflict -- the honest answer: both versions are there to read, and the run exits 1.
-    let from = hasBase ? baseText() : null;
-    if (from === null && policy === "reconcile") from = recoverBase(ours);
-    if (from === null && policy === "reconcile") from = "";
-    // A union table merges by row whether or not there is a base, and even an untouched copy goes
-    // through that merge: it may hold a row the upstream dropped and the project still needs.
-    if (from === null && policy === "union") from = "";
-    if (from === null) return keep;
-
-    if (ours === from && policy !== "union") return { outcome: "written", bucket: "written", text: asFound(theirs, crlf) };
-    const merged = merge(from, ours, theirs);
-    if (merged.failed) return { outcome: "yours, merge failed", bucket: "kept", text: null };
-    const result = asFound(merged.text, crlf);
-    if (merged.conflicts) return { outcome: "CONFLICT", bucket: "conflicted", text: result };
-    // A file that keeps a local edit merges cleanly on every later run and comes out the same every
-    // time. Reported as merged each run it reads as churn, and the reader goes looking for a change
-    // nobody made, so what the run did is decided by the result, not the route.
-    if (result === raw) return { outcome: "unchanged", bucket: null, text: null };
-    return { outcome: "merged", bucket: "merged", text: result };
-}
-
-// A union table, merged row by row rather than line by line: a row is keyed by its first
-// tab-separated column, and the table is a set of them, so there is nothing to conflict over.
-// The upstream's comments and order come first. Each of its rows is the project's where only the
-// project changed it, or where both did, and the upstream's otherwise; a row the project deleted
-// stays deleted. Every row of the project's the upstream lacks follows, whether the project added it
-// or the upstream dropped it: the licence of a skill the upstream stopped shipping is still needed
-// here, because the skills merge keeps the skill. All three texts are LF; `base` is null without a
-// receipt, and then the project's copy of a row wins.
-function mergeRows(base, ours, theirs) {
-    const rows = text => new Map((text || "").split("\n").filter(l => l.trim() && !l.startsWith("#")).map(l => [l.split("\t")[0], l]));
-    const was = rows(base), mine = rows(ours), up = rows(theirs);
-    const out = [];
-    for (const line of theirs.split("\n")) {
-        const key = line.split("\t")[0];
-        if (!line.trim() || line.startsWith("#") || !up.has(key)) { out.push(line); continue; }
-        const o = mine.get(key), b = was.get(key);
-        if (o === undefined) { if (b === undefined) out.push(line); continue; }
-        out.push(o === b ? line : o);
-    }
-    const extra = [...mine].filter(([key]) => !up.has(key)).map(([, line]) => line);
-    if (!extra.length) return out.join("\n");
-    while (out.length && out[out.length - 1] === "") out.pop();
-    return [...out, ...extra, ""].join("\n");
-}
-
 // ---------------------------------------------------------------- the plan
 //
 // Everything a run will do to the target, decided before anything is written: an install rewrites
@@ -589,7 +469,7 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     add({ phase: `${files.length} path(s) in ${ref} at ${head.slice(0, 8)}` });
     for (const entry of files) {
         const { file, link: isLink, exec } = entry;
-        const policy = policyFor(rows, file, options.wants);
+        const { policy, asked } = installPolicy.policyFor(rows, file, options.wants);
         const m = mode(entry);
         const theirs = upstream.blob(head, file);
         // Git listed the path a moment ago, so failing to read it is the checkout being unhappy
@@ -604,10 +484,7 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
         const line = (outcome, bucket, act = {}) =>
             add({ file, policy, mode: m, outcome, bucket, ...act, exec: exec && (exists || act.write !== undefined) });
 
-        // Not installed anywhere, and named in one line of the summary instead: sixty-five lines
-        // saying nothing happened bury the thirty-eight saying something did.
-        if (policy === "template") { line("template", "template", { silent: true }); continue; }
-        if (isLink) {
+        if (isLink && policy !== "template") {
             // A skill link is relink's to make, once the directory it lives in exists: it knows which
             // skills this project actually has, where the upstream only knows its own.
             if (policy === "skills") { add({ file, mkdir: true, silent: true }); continue; }
@@ -625,34 +502,17 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
         // Reported one line per skill by planSkills below, not one per reference file: a skill is the
         // unit a project installs, and its files run to several hundred.
         if (policy === "skills") { skills.push(entry); continue; }
-        // Reported only when the target actually has it: "left alone, yours" about a file the repo
-        // does not have names something that was never there.
-        if (policy === "skip") { line(exists ? "yours" : "absent", exists ? "skipped" : null); continue; }
-        if (policy === "seed") {
-            // A seed file the recorded commit already shipped was laid down then, so its absence is
-            // the project deleting it, and it stays deleted. An optional part is the exception: its
-            // flag is the project asking for it now, whatever an earlier run left out.
-            const asked = (rowFor(rows, file) || { policy: "" }).policy.startsWith("optional:");
-            if (exists) line("yours", "kept");
-            else if (!asked && base !== null && upstream.blob(base, file) !== null) line("deleted here", null);
-            else line("created", "seeded", { write: theirs });
-            continue;
-        }
-        // merge and reconcile
-        if (!exists) { line("written", "written", { write: theirs }); continue; }
-        const hasBase = base !== null;
-        const held = target.read(file, Buffer.isBuffer(theirs));
-        const { outcome, bucket, text } = Buffer.isBuffer(theirs)
-            ? decideBinary({ held, theirs, hasBase, adopt: options.adopt }, { baseBytes: () => upstream.blob(base, file) })
-            : decideText({ policy, raw: held, theirs, hasBase, adopt: options.adopt }, {
-                baseText: () => upstream.blob(base, file),
+        const { outcome, bucket, notice, ...act } = installPolicy.decide(policy,
+            { exists, theirs, hasBase: base !== null, adopt: options.adopt, asked }, {
+                held: () => target.read(file, Buffer.isBuffer(theirs)),
+                base: () => upstream.blob(base, file),
+                // A seed file the recorded commit already shipped was laid down then.
+                shippedBefore: () => base !== null && upstream.blob(base, file) !== null,
                 recoverBase: ours => recoverBase(upstream, file, ours),
-                // A union table has no lines to conflict over, and no base means the project's rows win.
-                merge: policy === "union"
-                    ? (from, ours, up) => ({ text: mergeRows(from, ours, up), conflicts: false, failed: false })
-                    : threeWay,
+                merge: threeWay,
             });
-        line(outcome, bucket, text === null ? {} : { write: text });
+        if (notice) notices.push(`${file}: ${notice}`);
+        line(outcome, bucket, act);
     }
 
     add({ phase: "skeletons a project starts with" });
@@ -662,15 +522,19 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     // list is taken to know them all, which every install since the skeletons began has laid down.
     const known = new Set(previous && base !== null ? previous.skeletons || Object.keys(SKELETONS) : []);
     for (const [file, lines] of Object.entries(SKELETONS)) {
-        if (target.exists(file)) add({ file, policy: "seed", mode: "100644", outcome: "yours", bucket: null });
-        else if (known.has(file)) add({ file, policy: "seed", mode: "100644", outcome: "deleted here", bucket: null });
-        else add({ file, policy: "seed", mode: "100644", outcome: "created", bucket: "seeded", write: skeletonLines(file, lines, hasIntent).join("\n") });
+        const theirs = skeletonLines(file, lines, hasIntent).join("\n");
+        const decision = installPolicy.decide("skeleton", { exists: target.exists(file), theirs, asked: false }, { shippedBefore: () => known.has(file) });
+        add({ file, policy: "seed", mode: "100644", ...decision });
     }
 
     add({ phase: "skills, merged by name" });
     entries.push(...planSkills(upstream, target, head, skills));
 
-    add({ file: LOCK, silent: true, write: JSON.stringify({ template: TEMPLATE, ref, commit: head, ...stamp, skeletons: Object.keys(SKELETONS) }, null, 2) + "\n" });
+    // A list of strings on one line, as Prettier writes it: a project formatting its JSON with it
+    // would otherwise reject the receipt at every push, and the next update would undo the fix.
+    const receipt = JSON.stringify({ template: TEMPLATE, ref, commit: head, ...stamp, skeletons: Object.keys(SKELETONS) }, null, 2)
+        .replace(/\[\n\s+("[^"\n]*"(?:,\n\s+"[^"\n]*")*)\n\s*\]/g, (all, items) => `[${items.split(/,\n\s+/).join(", ")}]`);
+    add({ file: LOCK, silent: true, write: receipt + "\n" });
     return { entries, notices, base };
 }
 
@@ -706,12 +570,12 @@ function planSkills(upstream, target, head, files) {
         const held = exists ? target.read(file, true) : null;
         let write;
         if (Buffer.isBuffer(text)) {
-            if (same(held, text)) continue;
+            if (lib.sameContent(held, text)) continue;
             write = text;
         } else {
             const ourText = held === null ? null : held.toString("utf8");
-            if (ourText !== null && toLf(ourText) === text) continue;
-            write = asFound(text, ourText !== null && isCrlf(ourText));
+            if (ourText !== null && lib.toLf(ourText) === text) continue;
+            write = lib.asFound(text, ourText !== null && lib.isCrlf(ourText));
         }
         if (exists) tally.updated++; else tally.added++;
         out.push({ file, silent: true, write, bucket: exists ? "merged" : "written", exec: exec && !exists });
@@ -785,18 +649,25 @@ function apply(entries, root, options) {
 
 // ---------------------------------------------------------------- after it
 
-// Two files nothing copied: the per-harness skill links, which depend on which skills this project
-// has rather than which the upstream ships, and the third-party notice, which must describe this
-// project's lock file. Both are generated, so the install leaves a harness that works rather than a
-// list of commands to remember. Each run names the target with --root: the shared resolver prefers a
-// harness's project-dir variable to the checkout a script sits in, and an install started from a
-// session open on another repo would otherwise link and describe that repo instead.
+// First the Git hooks, pointed at .githooks/ before anything else: an install that stopped at a
+// printed reminder left clones whose hooks never ran, and nothing says so -- Git skips a hooks
+// folder it was never told about in silence. Then two files nothing copied: the per-harness skill
+// links, which depend on which skills this project has rather than which the upstream ships, and the
+// third-party notice, which must describe this project's lock file. All three are generated, so the
+// install leaves a harness that works rather than a list of commands to remember. Each run names the
+// target with --root: the shared resolver prefers a harness's project-dir variable to the checkout a
+// script sits in, and an install started from a session open on another repo would otherwise wire,
+// link and describe that repo instead. Returns whether the hooks were wired.
 function finish(target, options) {
-    if (!options.quiet) say("\nlinks and notices");
-    for (const [label, args] of [["links", ["relink"]], ["notices", ["notices"]]]) {
-        const r = lib.node([path.join(target, "scripts/skills.js"), ...args, `${lib.ROOT_FLAG}${target}`], { cwd: target });
+    if (!options.quiet) say("\nGit hooks, links and notices");
+    const steps = [["git hooks", "scripts/githooks-init.js", []], ["links", "scripts/skills.js", ["relink"]], ["notices", "scripts/skills.js", ["notices"]]];
+    let hooks = true;
+    for (const [label, script, args] of steps) {
+        const r = lib.node([path.join(target, script), ...args, `${lib.ROOT_FLAG}${target}`], { cwd: target });
         say(r.status === 0 ? r.output : `${label}: ${r.output}`);
+        if (label === "git hooks" && r.status !== 0) hooks = false;
     }
+    return hooks;
 }
 
 // Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
@@ -819,7 +690,7 @@ function selfCheck(target, templateDir, options) {
 
 // The summary, from the entries as they turned out. Returns the exit code: 1 while anything is left
 // for the reader to act on.
-function report({ entries, base, head, ref, target, check, options }) {
+function report({ entries, base, head, ref, target, check, hooks = true, options }) {
     const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], skipped: [], template: [], unreadable: [] };
     for (const e of entries) if (e.bucket) notes[e.bucket].push(e.file);
     // Every path was named as it happened, so repeating the lists here doubles the output; a quiet
@@ -832,7 +703,7 @@ function report({ entries, base, head, ref, target, check, options }) {
     };
     say("");
     say(options.dryRun ? `dry run against ${ref} at ${head.slice(0, 8)}` : `harness updated to ${ref} at ${head.slice(0, 8)}`);
-    if (!base) say("no merge base: this was an install, so nothing that already existed was changed");
+    if (!base) say("no merge base: this was an install, so a file already here was kept, or given only the part the harness needs");
     list("written", notes.written);
     list("merged", notes.merged);
     list("created for the first time", notes.seeded);
@@ -857,11 +728,10 @@ function report({ entries, base, head, ref, target, check, options }) {
     else if (check && check.failed) say(`\nSELF CHECK FAILED, so this install does not work yet:\n${check.output}`);
     else if (check) say(`\nself check: ${check.summary}`);
 
-    if (!options.dryRun) {
-        say(`\nIn ${target}, point Git at the hooks once per clone, then check the harness:`);
-        say(`  node scripts/githooks-init.js && node scripts/check-harness.js`);
-    }
-    return notes.conflicted.length || notes.unreadable.length || (check && check.failed) ? 1 : 0;
+    // Git hooks are wired per clone: this one was wired above, and every other clone runs the script once.
+    if (!options.dryRun && !hooks) say(`\nGIT HOOKS NOT WIRED: in ${target}, run node scripts/githooks-init.js`);
+    if (!options.dryRun) say(`\nEvery other clone of ${target} wires its Git hooks once with: node scripts/githooks-init.js`);
+    return notes.conflicted.length || notes.unreadable.length || (check && check.failed) || !hooks ? 1 : 0;
 }
 
 // ---------------------------------------------------------------- the run
@@ -906,13 +776,14 @@ function main(args) {
         for (const notice of planned.notices) say(notice);
         const entries = apply(planned.entries, target, options);
         let check = null;
+        let hooks = true;
         if (!options.dryRun) {
             // After the plan is applied, because relink needs the skills in place and the invariants
             // check the links relink has just written.
-            finish(target, options);
+            hooks = finish(target, options);
             if (options.check) check = selfCheck(target, templateDir, options);
         }
-        return report({ entries, base: planned.base, head, ref, target, check, options });
+        return report({ entries, base: planned.base, head, ref, target, check, hooks, options });
     } finally {
         if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
     }
@@ -921,7 +792,7 @@ function main(args) {
 // The plan and the decisions under it, so the suite can put a case in and read the answer out rather
 // than building a git checkout to reach one branch. apply() is here for its dry run, which prints and
 // writes nothing; main() writes to somebody's repository and is reached through the command line.
-module.exports = { installerStamp, upToDate, mergeRows, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, policyFor, plan, apply, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+module.exports = { installerStamp, upToDate, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, plan, apply, lineCounts, overlap, NEAREST, skeletonLines };
 
 if (require.main === module) {
     try { process.exitCode = main(process.argv.slice(2)); }