@salaros/ai-harness 0.2.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.2.9",
+  "version": "0.3.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"
@@ -8,6 +8,8 @@
   "files": [
     "scripts/update-harness.js",
     "scripts/lib.js",
+    "scripts/project-facts.js",
+    "scripts/repo-view.js",
     "README.md",
     "LICENSE"
   ],

package/scripts/README.md

@@ -17,11 +17,13 @@ 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.
-- Scripts are safe to run from any working directory — each resolves the
-  repository root from its own location, or from `--root=<dir>` when given
-  (`lib.root()`; `lib.args()` is the arguments without that flag). The
-  suite uses the flag to run a script against a temporary repo, and a script
-  that calls another passes its own root along.
+- 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
+  (`CLAUDE_PROJECT_DIR` and its Cursor and Gemini equivalents), then the
+  checkout the file sits in (`lib.args()` is the arguments without the flag).
+  The suite uses the flag to run a script against a temporary repo, and a
+  script that calls another passes its own root along.
 - A script run as a command may `chdir` there (`lib.chdirRoot()`). A script
   another script requires takes the root as its first argument and resolves
   against it (`lib.root()` at the entry point, `path.resolve(root, …)`
@@ -36,6 +38,15 @@ part of the product.
   and hand over to `githook.js <hook>`. Nothing else belongs in them: a
   decision made in the shell is one no test can reach, and the suite asserts
   the shape.
+- A script is a thin shell around its decisions. Parsing, merging,
+  formatting and the summary it prints go in a pure module the suite tests;
+  the script only reads, writes and reports, for the same reason the hooks
+  above hold no logic.
+- What two scripts share lives in one module here instead of a copy in each,
+  so the callers cannot drift: a threshold, a list, or a whole step, the way
+  `lib.js` holds root resolution and argument parsing for every script. When
+  several scripts do one job for different sources, a runner owns the common
+  steps and each script brings only its source and its rules.
 - Scripts must be idempotent where possible — running them twice should not
   break anything.
   

package/scripts/lib.js

@@ -4,7 +4,7 @@
 // which requires this file rather than the other way around, so scripts/ never reaches into the
 // harness-specific folder.
 //   const lib = require("./lib");
-//   const root = lib.root();                 // the repo root: --root=<dir> if given, else one level above this file
+//   const root = lib.root();                 // the repo root (precedence below)
 //   const root = lib.chdirRoot();            // the same, and cd there
 //   const [cmd, ...rest] = lib.args();       // the command line, without --root=<dir>
 //   lib.stdin()                              // everything on stdin, or "" if there is none
@@ -15,21 +15,50 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
-// Every script under scripts/ resolves the repo root once, on its command line, and a script run as
-// a command chdirs there so its relative paths (SKILL.md files, README.md, stacks.tsv) work no matter
-// where it was invoked from. A script another script requires takes the root as an argument and
-// resolves against it: chdir is a process-wide effect, so a library that moves the working directory
-// moves it for its caller too.
-// The root is the repo this file sits in, unless the command was given --root=<dir>. That flag is
-// how a check reaches a repo other than its own checkout: the suite points a case at a throwaway
-// directory rather than planting files in the tree it runs in, and the installer checks a target
-// with the upstream's copy of a script. One token, so an argument parser that skips "--" flags skips
-// it too.
+// Which repo an entry point is about, in one precedence every script and hook follows:
+//   1. --root=<dir> on the command line, the explicit answer
+//   2. CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR or GEMINI_PROJECT_DIR, the harness's answer
+//   3. the checkout this file sits in
+// The flag is how a check reaches a repo other than its own checkout: the suite points a case at a
+// throwaway directory rather than planting files in the tree it runs in, and the installer checks a
+// target with the upstream's copy of a script. One token, so an argument parser that skips "--"
+// flags skips it too. The variables are how a harness says which project it is editing, which is
+// not always the checkout a hook file sits in. A variable naming another checkout is honoured and
+// reported on stderr; one naming nothing that exists is ignored and reported.
+// A script run as a command chdirs to the root so its relative paths (SKILL.md files, README.md,
+// stacks.tsv) work wherever it was invoked from. A script another script requires takes the root as
+// an argument and resolves against it: chdir is a process-wide effect, so a library that moves the
+// working directory moves it for its caller too.
 const ROOT_FLAG = "--root=";
-const root = () => {
-    const given = process.argv.slice(2).find(a => a.startsWith(ROOT_FLAG));
-    return path.resolve(given ? given.slice(ROOT_FLAG.length) : path.join(__dirname, ".."));
+const ROOT_ENV_VARS = ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "GEMINI_PROJECT_DIR"];
+const CHECKOUT = path.resolve(__dirname, "..");
+
+const win = process.platform === "win32";
+const warn = msg => process.stderr.write(`harness: ${msg}\n`);
+const same = (a, b) => win ? a.toLowerCase() === b.toLowerCase() : a === b;
+// Git Bash reports C:\x as /c/x; Windows APIs may prefix \\?\. Bring both to a form path can resolve.
+const fix = p => {
+    let s = String(p).replace(/^\\\\\?\\/, "");
+    if (win) { const m = s.match(/^\/([a-zA-Z])(?:\/(.*))?$/); if (m) s = `${m[1].toUpperCase()}:/${m[2] || ""}`; }
+    return s;
 };
+const real = p => { try { return fs.realpathSync(p); } catch { return p; } };
+
+function root() {
+    const given = process.argv.slice(2).find(a => a.startsWith(ROOT_FLAG));
+    if (given) return path.resolve(fix(given.slice(ROOT_FLAG.length)));
+    const here = real(CHECKOUT);
+    for (const v of ROOT_ENV_VARS) {
+        const val = process.env[v];
+        if (!val) continue;
+        const dir = path.resolve(fix(val));
+        let st; try { st = fs.statSync(dir); } catch { }
+        if (!st || !st.isDirectory()) { warn(`${v} is not a directory; using the checkout this file lives in`); break; }
+        if (!same(real(dir), here)) warn(`${v} (${dir}) is not the checkout this file lives in (${here}); using ${v}`);
+        return dir;
+    }
+    return here;
+}
 const args = () => process.argv.slice(2).filter(a => !a.startsWith(ROOT_FLAG));
 
 function chdirRoot() {
@@ -55,4 +84,4 @@ function readTsv(file) {
         .map(l => l.split("\t"));
 }
 
-module.exports = { root, args, ROOT_FLAG, chdirRoot, stdin, run, node, shell, readTsv };
+module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv };

package/scripts/project-facts.js

@@ -0,0 +1,113 @@
+// scripts/project-facts.js
+// The one reader of a project's facts: the labelled lines of MEMORY.md, and the name and purpose an
+// INTENT.md gives in its "## Product" section. The initialisation gate, the commit-message check,
+// docs-check, the docs portal and the installer's MEMORY.md skeleton all ask this module, so a line
+// one of them counts as present is present to every one of them, and a placeholder one of them
+// treats as unanswered is unanswered everywhere.
+// Shipped in the npm package beside update-harness.js and lib.js, because the installer builds its
+// skeleton from FACTS, so the installer must not require anything else from scripts/.
+// Usage:
+//   const facts = require("./project-facts");
+//   const f = facts.readFactsAt(root);           // { Name, Purpose, Requirements, ... }
+//   f["Issue tracker"]                            // null: no line; "": unanswered; else the value
+//   facts.unanswered(f)                           // the required labels with no answer
+const fs = require("fs");
+const path = require("path");
+
+const MEMORY = "MEMORY.md";
+const INTENT = "INTENT.md";
+
+// Every fact, in the order MEMORY.md lists them. `required` facts gate initialisation; the rest are
+// read by the skills that need them and never block. `intent` marks the two an INTENT.md owns.
+// `Issue tracker` is optional because a tracker is a choice rather than a property of the code,
+// `Frontend` because a service or a library has no UI, and `Prose language` because a missing line
+// already means English.
+const FACTS = [
+    { label: "Name", required: true, intent: true, placeholder: "<name>" },
+    { label: "Purpose", required: true, intent: true, placeholder: "<purpose>" },
+    { label: "Prose language", required: false, placeholder: "<prose language>" },
+    { label: "Requirements", required: true, placeholder: "<requirements>" },
+    { label: "Unit type", required: true, placeholder: "<unit type>" },
+    { label: "Language", required: true, placeholder: "<language>" },
+    { label: "Runtime / package manager", required: true, placeholder: "<runtime>" },
+    { label: "Frontend", required: false, placeholder: "<framework>" },
+    { label: "Issue tracker", required: false, placeholder: "<tracker>" },
+];
+
+// INTENT.md (https://www.intentdocs.com/intent-md): the product's intent, one per product, at the
+// root. Optional, so the harness neither ships nor requires one. Given its text, returns whether the
+// "# INTENT.md" title is there, the product's bold name and the prose describing it from
+// "## Product" (null when the section is missing), and whether "## MVP stories" is there; that heading
+// may run on, as in "## MVP stories — build these first". docs-check holds the file to these sections.
+function readIntent(text) {
+    const lines = text.split(/\r?\n/);
+    const h1 = lines.find(l => /^#\s/.test(l));
+    const section = name => {
+        const start = lines.findIndex(l => new RegExp(`^##\\s+${name}\\b`, "i").test(l));
+        if (start < 0) return null;
+        const end = lines.findIndex((l, i) => i > start && /^#{1,2}\s/.test(l));
+        return lines.slice(start + 1, end < 0 ? lines.length : end).join("\n").trim();
+    };
+    const body = section("Product");
+    let product = null;
+    if (body !== null) {
+        const bold = body.match(/\*\*([^*]+)\*\*/);
+        product = {
+            name: bold ? bold[1].trim().replace(/[:.]+$/, "").trim() : "",
+            purpose: body.replace(/\*\*[^*]+\*\*/, "").replace(/^[\s:.,—–-]+/, "").replace(/\s+/g, " ").trim(),
+        };
+    }
+    return { title: !!h1 && h1.trim() === "# INTENT.md", product, stories: section("MVP stories") !== null };
+}
+
+// A fact's line: a `-` or `*` bullet, then the label in bold with its colon inside or after the bold
+// (`- **Name:** Acme`, `* **Name**: Acme`). An unbolded line is prose that happens to start with the
+// word, so it is not a fact. The value is null when no line carries the label.
+function lineValue(text, label) {
+    if (text === null) return null;
+    const escaped = label.replace(/[/.*+?^${}()|[\]\\]/g, "\\$&");
+    const m = text.match(new RegExp(`^\\s*[-*]\\s*\\*\\*${escaped}(?::\\*\\*|\\*\\*:)[ \\t]*(.*)$`, "mi"));
+    return m ? m[1].trim() : null;
+}
+
+// A value is unanswered when nothing is left once every <placeholder> is removed: `<language>` and
+// `<language> <version>` are the template, `C#` and `see <link> in docs/` are answers, kept whole.
+const answer = value => value.replace(/<[^>]*>/g, "").trim() ? value : "";
+
+// Every fact, from the texts of MEMORY.md and INTENT.md, each null when that file is absent. A label
+// maps to null when nothing gives it, "" when it is unanswered, and the trimmed value otherwise.
+// With an INTENT.md, Name and Purpose come from its "## Product" alone: a MEMORY.md line for either
+// is ignored, so a stale copy there never stands in for the product's own words.
+function readFacts({ memory = null, intent = null } = {}) {
+    const product = intent === null ? null : readIntent(intent).product;
+    const facts = {};
+    for (const { label, intent: owned } of FACTS) {
+        const raw = owned && intent !== null
+            ? (product ? product[label.toLowerCase()] : null)
+            : lineValue(memory, label);
+        facts[label] = raw === null ? null : answer(raw);
+    }
+    return facts;
+}
+
+// readFacts() for the files on disk under a root. A reader holding the texts some other way, such as
+// docs-check through a repo view, calls readFacts() with them instead.
+function readFactsAt(root) {
+    const read = file => {
+        const at = path.resolve(root, file);
+        return fs.existsSync(at) ? fs.readFileSync(at, "utf8") : null;
+    };
+    return readFacts({ memory: read(MEMORY), intent: read(INTENT) });
+}
+
+// The required labels readFacts() found no answer for, in FACTS order.
+const unanswered = facts => FACTS.filter(f => f.required && !facts[f.label]).map(f => f.label);
+
+// MEMORY.md's fact lines as the installer lays them down, every one a placeholder. Beside an
+// INTENT.md, Name and Purpose give way to a line saying where they are.
+function skeleton(hasIntent) {
+    const lines = FACTS.filter(f => !(hasIntent && f.intent)).map(f => `- **${f.label}:** ${f.placeholder}`);
+    return hasIntent ? [`The name and purpose are in \`${INTENT}\`, under \`## Product\`.`, "", ...lines] : lines;
+}
+
+module.exports = { FACTS, MEMORY, INTENT, readFacts, readFactsAt, unanswered, readIntent, skeleton };

package/scripts/repo-view.js

@@ -0,0 +1,101 @@
+// scripts/repo-view.js
+// A repo as a check reads it: four questions about repo-relative paths, answered from the working
+// tree, from Git's index, or from a map a test builds. A check that takes a view reads what a
+// commit will record as easily as what is on disk, and a test hands it the files it is about
+// instead of building a tree or pointing it at a file that does not exist.
+//   exists(rel)   a file, or a folder holding one
+//   isFile(rel)   a file
+//   read(rel)     its text, or null when there is none
+//   list(rel)     the names directly inside a folder, sorted; [] when there is none
+// Paths are repo-relative with forward slashes. Nothing here writes, prints or exits.
+// indexModes() is the one reader of `git ls-files -s`: the mode Git records is how the harness
+// tells a symlink (120000) and an executable (100755) from a plain file.
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// stdout alone and untrimmed, since a blob's trailing newline is part of its text.
+const git = (dir, args) => spawnSync("git", ["-c", "core.quotepath=off", ...args], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+
+const norm = rel => path.posix.normalize(String(rel).split(path.sep).join("/")).replace(/^\.\/?$|\/+$/g, "");
+
+// Every path Git's index holds in `dir`, optionally under `paths` (pathspecs), as
+// { file, mode, object, link, exec }. null when `dir` is not a git checkout.
+function indexModes(dir, paths = []) {
+    const r = git(dir, ["ls-files", "-s", "-z", ...(paths.length ? ["--", ...paths] : [])]);
+    if (r.status !== 0) return null;
+    return r.stdout.split("\0").filter(Boolean).map(entry => {
+        const [meta, file] = entry.split("\t");
+        const [mode, object] = meta.split(" ");
+        return { file, mode, object, link: mode === "120000", exec: mode === "100755" };
+    });
+}
+
+// A view over a set of files known up front, each read on first use. Folders are whatever the
+// paths imply, which is all an index or a map has of them.
+function filesView(loaders) {
+    const cache = new Map();
+    const under = rel => rel ? rel + "/" : "";
+    return {
+        exists: rel => { rel = norm(rel); return loaders.has(rel) || [...loaders.keys()].some(f => f.startsWith(under(rel))); },
+        isFile: rel => loaders.has(norm(rel)),
+        read: rel => {
+            rel = norm(rel);
+            if (!loaders.has(rel)) return null;
+            if (!cache.has(rel)) cache.set(rel, loaders.get(rel)());
+            return cache.get(rel);
+        },
+        list: rel => {
+            const prefix = under(norm(rel));
+            const names = new Set([...loaders.keys()].filter(f => f.startsWith(prefix)).map(f => f.slice(prefix.length).split("/")[0]));
+            return [...names].sort();
+        },
+    };
+}
+
+// The files on disk under `root`. A path outside it resolves as it stands, which is what a cited
+// `../` path means.
+function worktree(root) {
+    const at = rel => path.resolve(root, String(rel));
+    const stat = rel => { try { return fs.statSync(at(rel)); } catch { return null; } };
+    return {
+        exists: rel => !!stat(rel),
+        isFile: rel => !!(stat(rel) || { isFile: () => false }).isFile(),
+        read: rel => { const s = stat(rel); return s && s.isFile() ? fs.readFileSync(at(rel), "utf8") : null; },
+        list: rel => { const s = stat(rel); return s && s.isDirectory() ? fs.readdirSync(at(rel)).sort() : []; },
+    };
+}
+
+// Git's index at `root`, limited to `paths` when given: what the next commit records, and nothing
+// the working tree holds besides. Throws when `root` is not a git checkout, since an index nobody
+// could read is not an empty one.
+function index(root, paths = []) {
+    const rows = indexModes(root, paths);
+    if (!rows) throw new Error(`could not read the git index in ${root}`);
+    const blob = object => {
+        const r = git(root, ["cat-file", "blob", object]);
+        if (r.status !== 0) throw new Error(`could not read blob ${object}: ${r.stderr}`);
+        return r.stdout;
+    };
+    return filesView(new Map(rows.map(row => [row.file, () => blob(row.object)])));
+}
+
+// What a commit will record for `paths`, and the working tree for everything else. Each of `paths`
+// is read from the index when the index holds anything under it, and from the disk when it holds
+// nothing: a repo that keeps one of them untracked still gets a meaningful answer.
+function staged(root, paths) {
+    const idx = index(root, paths), disk = worktree(root);
+    const owner = rel => { rel = norm(rel); return paths.map(norm).find(p => rel === p || rel.startsWith(p + "/")); };
+    const pick = rel => { const p = owner(rel); return p !== undefined && idx.exists(p) ? idx : disk; };
+    return {
+        exists: rel => pick(rel).exists(rel),
+        isFile: rel => pick(rel).isFile(rel),
+        read: rel => pick(rel).read(rel),
+        list: rel => pick(rel).list(rel),
+    };
+}
+
+// The files a test names, path -> text, and nothing else.
+const fromMap = files => filesView(new Map(Object.entries(files).map(([f, text]) => [norm(f), () => text])));
+
+module.exports = { worktree, index, staged, fromMap, indexModes };

package/scripts/update-harness.js

@@ -32,6 +32,8 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const lib = require("./lib");
+const projectFacts = require("./project-facts");
+const repoView = require("./repo-view");
 const { spawnSync } = require("child_process");
 
 const TEMPLATE = "https://github.com/salaros/ai-harness.git";
@@ -39,9 +41,6 @@ const LOCK = "harness-lock.json";
 const MANIFEST = "scripts/harness-files.tsv";
 const DEFAULT_REF = "master";
 
-const argv = process.argv.slice(2);
-const flag = name => argv.includes(name);
-const value = (name, fallback) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback; };
 // Every argument the installer knows. An optional part of the harness adds its own flag through the
 // manifest (optional:<flag>), so those are checked once the upstream checkout is read. Anything else
 // stops the run before a file is written: this script installs when it is run, so a mistyped
@@ -86,8 +85,31 @@ function usage() {
     for (let i = start + 1; i < lines.length && lines[i].startsWith("//   "); i++) out.push(lines[i].slice(3).replace("node scripts/update-harness.js", "npx @salaros/ai-harness"));
     return ["Installs or updates the agent harness in the current git repository.", "", "Usage:", ...out].join("\n");
 }
-const dryRun = flag("--dry-run");
-const adopt = flag("--adopt");
+
+// The arguments, read once. Everything below takes this object rather than the process's argv, so a
+// test can ask what an --adopt run would plan without being one. `wants` answers whether the run
+// asked for an optional part of the harness by its flag.
+function parseOptions(args) {
+    const flag = name => args.includes(name);
+    const value = name => { const i = args.indexOf(name); return i >= 0 && args[i + 1] ? args[i + 1] : null; };
+    return {
+        help: flag("--help") || flag("-h"),
+        dryRun: flag("--dry-run"),
+        adopt: flag("--adopt"),
+        quiet: flag("--quiet"),
+        check: !flag("--no-check"),
+        wants: name => flag(`--${name}`),
+        ref: value("--ref"),
+        target: value("--target"),
+        from: value("--from"),
+    };
+}
+
+// A reason to stop. Thrown rather than exiting, so main() is the one place the process ends, and a
+// temporary clone is still removed on the way out.
+class Stop extends Error {}
+const fail = m => { throw new Stop(m); };
+const say = m => console.log(m);
 
 // ---------------------------------------------------------------- the target
 
@@ -95,9 +117,8 @@ const adopt = flag("--adopt");
 // its scripts/ folder. Run through npx, the package is an extracted tarball with no .git of its own,
 // so the answer is the directory the user is standing in. One rule covers both, and --target covers
 // installing into a checkout from somewhere else entirely.
-function targetRoot() {
-    const given = value("--target", null);
-    if (given) return path.resolve(given);
+function targetRoot(options) {
+    if (options.target) return path.resolve(options.target);
     const beside = path.resolve(__dirname, "..");
     return fs.existsSync(path.join(beside, ".git")) ? beside : process.cwd();
 }
@@ -106,22 +127,21 @@ function targetRoot() {
 
 // A clone deep enough to read the recorded commit: an update needs that commit's version of a file
 // as the merge base, and --depth 1 would not have it. Removed again unless the caller supplied one.
-function templateCheckout(ref) {
+function templateCheckout(ref, options) {
     // The manifest is what makes a checkout usable here, so both routes are held to it: a --from
     // that points somewhere else, and a --ref naming a branch or tag from before the table existed,
     // fail the same way. Without this the run reaches readTsv and dies in a stack trace naming a
     // temporary directory the reader has never heard of.
     const usable = dir => fs.existsSync(path.join(dir, MANIFEST));
-    const given = value("--from", null);
-    if (given) {
-        const dir = path.resolve(given);
+    if (options.from) {
+        const dir = path.resolve(options.from);
         if (!usable(dir)) fail(`${dir} does not look like the upstream harness: no ${MANIFEST}`);
         return { dir, temporary: false };
     }
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
     say(`cloning ${TEMPLATE} at ${ref}`);
     const r = lib.run("git", [...GIT, "clone", "--quiet", "--branch", ref, TEMPLATE, dir]);
-    if (r.status !== 0) fail(`could not clone the upstream at ${ref}\n${r.output}`);
+    if (r.status !== 0) { fs.rmSync(dir, { recursive: true, force: true }); fail(`could not clone the upstream at ${ref}\n${r.output}`); }
     if (!usable(dir)) {
         fs.rmSync(dir, { recursive: true, force: true });
         fail(`${TEMPLATE} at ${ref} carries no ${MANIFEST}, so there is nothing to install from; try another --ref`);
@@ -151,8 +171,7 @@ function installer() {
 const GIT = ["-c", "core.longpaths=true"];
 const at = (dir, args) => lib.run("git", [...GIT, "-C", dir, ...args]);
 
-// The upstream's version of a path at a commit, or null when the file did not exist there. Also how
-// a missing base is detected: a rewritten history no longer holds the recorded commit.
+// The upstream's version of a path at a commit, or null when the file did not exist there.
 // Read raw rather than through lib.run, which trims trailing whitespace: that is right for the
 // plumbing whose output is a hash or a status line, and wrong for a file. Trimmed, every installed
 // file lost its final newline, no copy was ever byte-identical to the upstream, and so every later
@@ -173,6 +192,82 @@ 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
+// real run backs them with the upstream's git checkout and the target's directory; the suite backs
+// them with maps, so a whole install is a table row rather than a clone and a temp tree.
+
+// Every blob in one commit, read in two calls rather than one `git show` per path: an install reads
+// every file at the head, and a process per file made a first install take most of a minute on
+// Windows. Keyed by path, holding what blob() would return; a submodule entry is not a blob and is
+// left out, as `git show` would fail on it too.
+function treeBlobs(dir, commit) {
+    const listing = spawnSync("git", [...GIT, "-C", dir, "ls-tree", "-r", "-z", commit], { maxBuffer: 64 * 1024 * 1024 });
+    if (listing.status !== 0) return null;
+    const entries = listing.stdout.toString("utf8").split("\0").filter(Boolean)
+        .map(line => { const tab = line.indexOf("\t"); const [, type, oid] = line.slice(0, tab).split(" "); return { type, oid, file: line.slice(tab + 1) }; })
+        .filter(e => e.type === "blob");
+    const r = spawnSync("git", [...GIT, "-C", dir, "cat-file", "--batch"],
+        { input: entries.map(e => e.oid).join("\n") + "\n", maxBuffer: 1024 * 1024 * 1024 });
+    if (r.status !== 0) return null;
+    const blobs = new Map();
+    let at = 0;
+    for (const { file } of entries) {
+        const eol = r.stdout.indexOf(10, at);
+        const size = Number(r.stdout.toString("utf8", at, eol).split(" ")[2]);
+        const bytes = r.stdout.subarray(eol + 1, eol + 1 + size);
+        blobs.set(file, bytes.includes(0) ? Buffer.from(bytes) : bytes.toString("utf8"));
+        at = eol + 1 + size + 1;
+    }
+    return blobs;
+}
+
+function gitUpstream(dir, head) {
+    let atHead;
+    return {
+        // Every path the upstream tracks, with the mode Git recorded. Mode 120000 is a symlink, and
+        // the harness has two kinds: .claude/agents pointing at .agents/agents, and one per skill
+        // under .claude/skills. Written as ordinary files they become text files holding a path,
+        // which is how a harness ends up looking installed while the agent sees no skills at all.
+        files() {
+            const rows = repoView.indexModes(dir);
+            if (!rows) fail(`could not list the upstream's files in ${dir}`);
+            return rows.map(({ file, link, exec }) => ({ file, link, exec }));
+        },
+        // The head is read whole on first use; any other commit, which only a base or a base search
+        // asks for, one path at a time.
+        blob(commit, file) {
+            if (commit !== head) return blob(dir, commit, file);
+            if (atHead === undefined) atHead = treeBlobs(dir, head);
+            if (atHead === null) return blob(dir, commit, file);
+            return atHead.has(file) ? atHead.get(file) : null;
+        },
+        // A rewritten history no longer holds the recorded commit, which leaves the run without a base.
+        hasCommit: commit => at(dir, ["cat-file", "-e", `${commit}^{commit}`]).status === 0,
+        // The commits that touched a path, newest first.
+        history(file) {
+            const r = at(dir, ["log", "--format=%H", "--", file]);
+            return r.status === 0 ? r.output.split(/\r?\n/).filter(Boolean) : [];
+        },
+    };
+}
+
+function fsTarget(root) {
+    const full = file => path.join(root, file);
+    return {
+        exists: file => fs.existsSync(full(file)),
+        // A Buffer when asked for bytes, text otherwise.
+        read: (file, binary) => binary ? fs.readFileSync(full(file)) : fs.readFileSync(full(file), "utf8"),
+        // null when nothing is there; otherwise whether it is a symlink, and where it points.
+        lstat(file) {
+            let s;
+            try { s = fs.lstatSync(full(file)); } catch { return null; }
+            return s.isSymbolicLink() ? { link: fs.readlinkSync(full(file)).split(path.sep).join("/") } : { link: null };
+        },
+    };
+}
+
 // The receipt is missing, so the base is found instead: the upstream version this copy is closest to
 // is where the project forked from, whatever a receipt would have said. An exact match is the clean
 // case, an older copy nobody touched; a project that has since edited its own file matches nothing
@@ -183,17 +278,15 @@ const same = (a, b) => Buffer.isBuffer(a) || Buffer.isBuffer(b)
 // Under half the lines in common is a different file, not an older one, and merging against it would
 // invent a diff the project never made.
 const NEAREST = 0.5;
-function recoverBase(dir, file, ours) {
-    const r = at(dir, ["log", "--format=%H", "--", file]);
-    if (r.status !== 0) return null;
+function recoverBase(upstream, file, ours) {
     const want = lineCounts(ours);
     let best = null;
     let nearest = NEAREST;
     // Oldest first, and a tie goes to the first seen: two upstream versions one line apart score the
     // same against a copy that has neither, and the older of them is the one whose merge puts that
     // line back. The newer would drop it silently, which is the failure this policy exists to stop.
-    for (const commit of r.output.split(/\r?\n/).filter(Boolean).reverse()) {
-        const text = blob(dir, commit, file);
+    for (const commit of upstream.history(file).reverse()) {
+        const text = upstream.blob(commit, file);
         if (typeof text !== "string") continue;
         if (text === ours) return text;
         const shared = overlap(want, lineCounts(text));
@@ -242,59 +335,6 @@ function policyFor(rows, file, wants) {
     return wants(row.policy.slice("optional:".length)) ? "seed" : "template";
 }
 
-// Every path the upstream tracks, with the mode Git recorded. Mode 120000 is a symlink, and the
-// harness has two kinds: .claude/agents pointing at .agents/agents, and one per skill under
-// .claude/skills. Written as ordinary files they become text files holding a path, which is how a
-// harness ends up looking installed while the agent sees no skills and no agents at all.
-function templateFiles(dir) {
-    const r = at(dir, ["ls-files", "-s"]);
-    if (r.status !== 0) fail(`could not list the upstream's files\n${r.output}`);
-    return r.output.split(/\r?\n/).filter(Boolean).map(line => {
-        const [meta, file] = line.split("\t");
-        return { file, link: meta.startsWith("120000"), exec: meta.startsWith("100755") };
-    });
-}
-
-// Git runs a hook only if it is executable, and says nothing when it is not: an installed harness
-// whose hooks are mode 644 looks installed and gates nothing. The upstream records them 100755, so
-// that mode has to travel, and only Git can carry it. `chmod` alone is not enough -- on Windows
-// core.fileMode is false and the call does nothing, so the file would be staged 100644 later and the
-// hooks would run for whoever installed them and silently never run for anyone else. `git add
-// --chmod=+x` writes the mode into the index whether or not the file was tracked, which is why the
-// install stages these few files rather than leaving them for the project's own `git add`.
-function carryMode(target, file) {
-    try { fs.chmodSync(path.join(target, file), 0o755); } catch { /* the filesystem does not do modes */ }
-    const r = lib.run("git", [...GIT, "-C", target, "add", "--chmod=+x", "--", file]);
-    if (r.status !== 0) say(`could not mark ${file} executable: ${r.output}`);
-}
-
-// A symlink recorded in Git is a blob holding its target. Windows needs Developer Mode and
-// core.symlinks=true for this to work at all, so a refusal is reported rather than thrown: the
-// harness still functions with the links missing, it is just invisible to the harnesses that read
-// them, and README says how to turn them on.
-function link(target, file, to) {
-    const full = path.join(target, file);
-    if (dryRun) return "written";
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    let existing = null;
-    try { existing = fs.lstatSync(full); } catch { /* absent */ }
-    if (existing) {
-        // Something of the project's is in the way -- or, in a repo whose harness predates the lock
-        // file, the link itself checked out as a text file holding a path, which is the failure that
-        // leaves an agent seeing no skills at all. --adopt is the only thing that replaces it.
-        if (!existing.isSymbolicLink()) { if (!adopt) return "kept"; fs.unlinkSync(full); }
-        else if (fs.readlinkSync(full).split(path.sep).join("/") === to) return null;
-        else fs.unlinkSync(full);
-    }
-    try {
-        fs.symlinkSync(to.split("/").join(path.sep), full, "dir");
-        return existing ? "merged" : "written";
-    } catch (e) {
-        say(`could not create the symlink ${file} -> ${to}: ${e.code || e.message}`);
-        return "kept";
-    }
-}
-
 // ---------------------------------------------------------------- skeletons
 
 // Three files the upstream does not ship, because there they would be lies: MEMORY.md
@@ -311,14 +351,6 @@ const SKELETONS = {
         "`pre-commit` and `pre-push` hooks refuse to let work leave a clone while any value is still a",
         "`<placeholder>`.",
         "",
-        "- **Name:** <name>",
-        "- **Purpose:** <purpose>",
-        "- **Prose language:** <prose language>",
-        "- **Requirements:** <requirements>",
-        "- **Unit type:** <unit type>",
-        "- **Language:** <language>",
-        "- **Runtime / package manager:** <runtime>",
-        "",
     ],
     "CONTEXT.md": [
         "# Context",
@@ -338,21 +370,13 @@ const SKELETONS = {
     ],
 };
 
-// A repo that already has an INTENT.md names the product and its purpose there, so the MEMORY.md
-// laid down beside it leaves those two out rather than asking for them a second time.
-function skeletonLines(target, file, lines) {
-    if (file !== "MEMORY.md" || !fs.existsSync(path.join(target, "INTENT.md"))) return lines;
-    const facts = lines.filter(l => !/^- \*\*(?:Name|Purpose):\*\*/.test(l));
-    const first = facts.findIndex(l => l.startsWith("- **"));
-    return [...facts.slice(0, first), "The name and purpose are in `INTENT.md`, under `## Product`.", "", ...facts.slice(first)];
-}
-
-function skeletons(target) {
-    for (const [file, lines] of Object.entries(SKELETONS)) {
-        if (fs.existsSync(path.join(target, file))) { step("seed", "100644", "yours", file); continue; }
-        write(target, file, skeletonLines(target, file, lines).join("\n"));
-        step("seed", "100644", "created", file, "seeded");
-    }
+// MEMORY.md's fact lines come from scripts/project-facts.js, the table the gate checks them against,
+// so a skeleton never asks for a fact the gate does not know or leaves out one it requires. A repo
+// that already has an INTENT.md names the product and its purpose there, so the MEMORY.md laid down
+// beside it leaves those two out rather than asking for them a second time.
+function skeletonLines(file, lines, hasIntent) {
+    if (file !== projectFacts.MEMORY) return lines;
+    return [...lines, ...projectFacts.skeleton(hasIntent), ""];
 }
 
 // ---------------------------------------------------------------- merging
@@ -372,25 +396,6 @@ function threeWay(base, ours, theirs) {
     } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
-// ---------------------------------------------------------------- reporting
-
-const notes = { written: [], merged: [], conflicted: [], seeded: [], kept: [], skipped: [], template: [], unreadable: [], check: null };
-const say = m => console.log(m);
-function fail(m) { console.error(`update-harness: ${m}`); process.exit(1); }
-
-// An install rewrites someone else's repository, so it says what it did to every path while it does
-// it, and --quiet asks for the summary alone. The mode is worth a column of its own: a hook that
-// lands 100644 gates nothing and a skill link written as a regular file leaves the agent with no
-// skills, and both look installed. One call records the outcome and prints the line, so the running
-// commentary and the summary below cannot drift apart.
-const quiet = flag("--quiet");
-const mode = f => f.link ? "120000" : f.exec ? "100755" : "100644";
-function step(policy, m, outcome, file, bucket) {
-    if (bucket) notes[bucket].push(file);
-    if (!quiet) say(`  ${policy.padEnd(9)}${m}  ${outcome.padEnd(12)}${file}`);
-}
-const phase = m => { if (!quiet) say(`\n${m}`); };
-
 // 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
@@ -409,14 +414,11 @@ const asFound = (text, crlf) => crlf ? text.replace(LF, "\r\n") : text;
 //
 // 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 the caller passes them
-// in and the loop below is left reading, writing and reporting.
+// 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. Splitting them this way is what makes the table of cases testable: an install rewrites
-// someone else's repository, and every branch below used to need a git checkout and a temp tree to
-// reach even once.
+// 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.
@@ -468,246 +470,290 @@ function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recover
     return { outcome: "merged", bucket: "merged", text: result };
 }
 
-function write(target, file, text, exec) {
-    const full = path.join(target, file);
-    if (dryRun) return;
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, text);
-    if (exec) carryMode(target, file);
-}
-
-// ---------------------------------------------------------------- the self check
-
-// Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
-// still works -- an AGENTS.md whose chain table no longer parses, routing sections naming an agent
-// this repo does not have, a skill nothing links to, an upstream with no licence row. Those are the
-// harness invariants, and scripts/check-harness.js holds them as functions of a root.
+// ---------------------------------------------------------------- the plan
 //
-// So they run from the upstream checkout against the target, and nothing is written into the target
-// to run them. The upstream's copy rather than the one just installed, so the check is the one that
-// matches the files this run wrote. The suite's fixtures stay upstream: they prove the harness
-// scripts, which the upstream's own CI has already done.
-function selfCheck(target, templateDir) {
-    const script = path.join(templateDir, "scripts", "check-harness.js");
-    if (!fs.existsSync(script)) return { skipped: "this upstream ref has no scripts/check-harness.js" };
-    phase("self check: the harness invariants, run from the upstream against this repo");
-    const harness = require(script);
-    const r = harness.check(target);
-    return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
-}
-
-// ---------------------------------------------------------------- the run
-
-function main() {
-    if (flag("--help") || flag("-h")) { console.log(usage()); return; }
-    const mistyped = mistypedArgs(argv);
-    if (mistyped.length) fail(`unknown argument(s): ${mistyped.join(" ")}. Nothing was written; run with --help for the options.`);
-    const target = targetRoot();
-    if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
-
-    const lockPath = path.join(target, LOCK);
-    const previous = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : null;
-    const ref = value("--ref", previous ? previous.ref : DEFAULT_REF);
-    const { dir: templateDir, temporary } = templateCheckout(ref);
+// Everything a run will do to the target, decided before anything is written: an install rewrites
+// someone else's repository, and deciding and writing in the same loop left every branch but the
+// per-file decision reachable only through a git checkout and a temp tree. A dry run prints the plan;
+// a real run applies it. Each entry is one line of the run's output and at most one thing done to
+// one path:
+//   file, policy, mode, outcome, bucket   what the run prints, and the summary list the path joins
+//   write                                 the path's new content, text or a Buffer
+//   link, replace                         a symlink to `link`, replacing what is there when `replace`
+//   exec                                  mark the path executable, whether or not it is written
+//   mkdir                                 create the path's folder and nothing else
+//   silent                                counted in the summary, never printed as a line
+// and a { phase } entry heads each section of the output.
+const mode = f => f.link ? "120000" : f.exec ? "100755" : "100644";
+const SKILLS = ".agents/skills/";
+
+// `previous` is the target's harness-lock.json, or null; `stamp` is what the receipt records about
+// this run besides the upstream commit, passed in so a plan is the same whenever it is made.
+function plan({ upstream, target, rows, head, ref, previous, options, stamp = {} }) {
+    const entries = [];
+    const notices = [];
+    const add = e => entries.push(e);
+
+    // A base is what makes this an update rather than an overwrite. Without one -- a first install,
+    // or an upstream whose history was rewritten -- an existing file is left alone instead of being
+    // guessed at, and the run says so.
+    let base = previous ? previous.commit : null;
+    if (base && !upstream.hasCommit(base)) {
+        notices.push(`the recorded upstream commit ${base.slice(0, 8)} is not in ${TEMPLATE} any more, so this run has no merge base: existing files are left alone`);
+        base = null;
+    }
+    // --adopt is how a repo whose harness files are wrong gets them replaced, and the commonest way to
+    // reach that state is an install that wrote the receipt and kept a stale harness. So the run stays
+    // open at the recorded commit, and main() answers "nothing to update" only without --adopt.
+    if (previous && base === head) notices.push(`harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`);
+
+    // A repo carrying a harness from before harness-lock.json existed. Without a base the rule below
+    // keeps every file that is already there, which protects the project's work and also preserves
+    // the old harness: its checks then run against the new skills and agents and fail, naming rules
+    // this version dropped. Worth saying out loud, because the run otherwise looks like a success.
+    const MARKERS = [".agents/hooks/lib.js", "scripts/lib.js", ".githooks/pre-commit"];
+    const stale = previous ? [] : MARKERS.filter(f => target.exists(f));
+    if (stale.length) {
+        notices.push(options.adopt
+            ? `this repo has a harness but no ${LOCK}, and --adopt was given: harness files are replaced with ${ref}'s, and edits to them are lost`
+            : `this repo has a harness (${stale.join(", ")}) but no ${LOCK}, so it predates the receipt and there is no merge base.\nEvery harness file already here is kept, which leaves old checks running against new skills. Re-run with --adopt to replace them, or --dry-run --quiet to list them first.`);
+    }
 
-    try {
-        // Checked before anything is said about the target, so a bad argument is the only message.
-        const rows = policies(templateDir);
-        const optional = rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
-        const unknown = unknownArgs(argv, optional);
-        if (unknown.length) {
-            if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
-            fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
-        }
-        const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
-        // A base is what makes this an update rather than an overwrite. Without one -- a first
-        // install, or an upstream whose history was rewritten -- an existing file is left alone
-        // instead of being guessed at, and the run says so.
-        let base = previous ? previous.commit : null;
-        if (base && at(templateDir, ["cat-file", "-e", `${base}^{commit}`]).status !== 0) {
-            say(`the recorded upstream commit ${base.slice(0, 8)} is not in ${TEMPLATE} any more, so this run has no merge base: existing files are left alone`);
-            base = null;
+    const files = upstream.files();
+    const skills = [];
+    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 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
+        // rather than the file being absent. Said out loud: skipped quietly, the run reports a clean
+        // install of a harness missing whichever files the reader was never told about.
+        if (theirs === null) { add({ file, policy, mode: m, outcome: "UNREADABLE", bucket: "unreadable" }); continue; }
+        const exists = target.exists(file);
+        // The executable bit is not the project's content, so a file kept for its content still has
+        // its mode corrected. Git runs a hook only if it is executable and says nothing when it is
+        // not, so a hook kept at 100644 by an install that had no merge base looks installed and
+        // gates nothing at all -- the failure the mode column exists to catch.
+        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) {
+            // 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; }
+            const to = theirs.trim();
+            const found = target.lstat(file);
+            // Something of the project's in the way -- or, in a repo whose harness predates the lock
+            // file, the link itself checked out as a text file holding a path, which is the failure
+            // that leaves an agent seeing no skills at all. --adopt is the only thing that replaces it.
+            if (!found) line("written", "written", { link: to });
+            else if (!found.link) line(options.adopt ? "merged" : "yours", options.adopt ? "merged" : "kept", options.adopt ? { link: to, replace: true } : {});
+            else if (found.link === to) line("unchanged", null);
+            else line("merged", "merged", { link: to, replace: true });
+            continue;
         }
-        // --adopt is how a repo whose harness files are wrong gets them replaced, and the commonest
-        // way to reach that state is an install that wrote the receipt and kept a stale harness. So
-        // the run has to stay open at the recorded commit: short-circuiting here would answer the
-        // one command that fixes it with "nothing to update".
-        if (previous && base === head && !adopt) { say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`); return; }
-        if (previous && base === head) say(`harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`);
-
-        // A repo carrying a harness from before harness-lock.json existed. Without a base the rule
-        // below keeps every file that is already there, which protects the project's work and also
-        // preserves the old harness: its checks then run against the new skills and agents and fail,
-        // naming rules this version dropped. Worth saying out loud, because the run otherwise looks
-        // like a success.
-        const MARKERS = [".agents/hooks/lib.js", "scripts/lib.js", ".githooks/pre-commit"];
-        const stale = !previous && MARKERS.filter(f => fs.existsSync(path.join(target, f)));
-        if (stale && stale.length) {
-            if (adopt) say(`this repo has a harness but no ${LOCK}, and --adopt was given: harness files are replaced with ${ref}'s, and edits to them are lost`);
-            else say(`this repo has a harness (${stale.join(", ")}) but no ${LOCK}, so it predates the receipt and there is no merge base.\nEvery harness file already here is kept, which leaves old checks running against new skills. Re-run with --adopt to replace them, or --dry-run --quiet to list them first.`);
-        }
-
-        const wants = name => flag(`--${name}`);
-        const files = templateFiles(templateDir);
-        const skills = [];
-
-        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, wants);
-            const m = mode(entry);
-            const theirs = blob(templateDir, head, file);
-            // Git listed the path a moment ago, so failing to read it is the checkout being unhappy
-            // rather than the file being absent. Said out loud: skipped quietly, the run reports a
-            // clean install of a harness missing whichever files the reader was never told about.
-            if (theirs === null) { step(policy, m, "UNREADABLE", file, "unreadable"); continue; }
-            const full = path.join(target, file);
-            const exists = fs.existsSync(full);
-
-            // The executable bit is not the project's content, so a file kept for its content still
-            // has its mode corrected. Git runs a hook only if it is executable and says nothing when
-            // it is not, so a hook kept at 100644 by an install that had no merge base looks
-            // installed and gates nothing at all -- the failure this whole column exists to catch.
-            if (exec && exists && !dryRun) carryMode(target, file);
-
-            // 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") { notes.template.push(file); continue; }
-            if (isLink) {
-                // 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") {
-                    if (!dryRun) fs.mkdirSync(path.dirname(full), { recursive: true });
-                    continue;
-                }
-                const how = link(target, file, theirs.trim());
-                step(policy, m, how === "kept" ? "yours" : how || "unchanged", file, how);
-                continue;
-            }
-            // Reported one line per skill by mergeSkills 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(file); 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") { step(policy, m, exists ? "yours" : "absent", file, exists && "skipped"); continue; }
-
-            if (policy === "seed") {
-                if (exists) { step(policy, m, "yours", file, "kept"); continue; }
-                write(target, file, theirs, exec);
-                step(policy, m, "created", file, "seeded");
-                continue;
-            }
-            // merge
-            if (!exists) { write(target, file, theirs, exec); step(policy, m, "written", file, "written"); continue; }
-
-            // Everything the decision needs, read here; what to do with its answer, done here. The
-            // decision itself is decideBinary/decideText, which touch neither git nor the disk.
-            const hasBase = base !== null;
-            const held = Buffer.isBuffer(theirs) ? fs.readFileSync(full) : fs.readFileSync(full, "utf8");
-            const { outcome, bucket, text } = Buffer.isBuffer(theirs)
-                ? decideBinary({ held, theirs, hasBase, adopt }, { baseBytes: () => blob(templateDir, base, file) })
-                : decideText({ policy, raw: held, theirs, hasBase, adopt }, {
-                    baseText: () => blob(templateDir, base, file),
-                    recoverBase: ours => recoverBase(templateDir, file, ours),
-                    merge: threeWay,
-                });
-            if (text !== null) write(target, file, text, exec);
-            step(policy, m, outcome, file, bucket);
+        // 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") {
+            if (exists) line("yours", "kept");
+            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),
+                recoverBase: ours => recoverBase(upstream, file, ours),
+                merge: threeWay,
+            });
+        line(outcome, bucket, text === null ? {} : { write: text });
+    }
 
-        phase("skeletons a project starts with");
-        skeletons(target);
-        phase("skills, merged by name");
-        mergeSkills(target, templateDir, head, skills);
-
-        if (!dryRun) {
-            fs.writeFileSync(lockPath, JSON.stringify({
-                template: TEMPLATE, ref, commit: head, ...installer(),
-                updated: new Date().toISOString().slice(0, 10),
-            }, null, 2) + "\n");
-            finish(target);
-            // After finish(), because the invariants check the links relink has just written.
-            if (!flag("--no-check")) notes.check = selfCheck(target, templateDir);
-        }
-        report(target, head, ref, base);
-    } finally {
-        if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+    add({ phase: "skeletons a project starts with" });
+    const hasIntent = target.exists(projectFacts.INTENT);
+    for (const [file, lines] of Object.entries(SKELETONS)) {
+        if (target.exists(file)) add({ file, policy: "seed", mode: "100644", outcome: "yours", bucket: null });
+        else add({ file, policy: "seed", mode: "100644", outcome: "created", bucket: "seeded", write: skeletonLines(file, lines, hasIntent).join("\n") });
     }
+
+    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 }, null, 2) + "\n" });
+    return { entries, notices, base };
 }
 
 // Skills merge by name, not by content: the upstream's are added and updated, and a skill the
 // project vendored itself is never removed. skills-lock.json is the union, the project's entry
 // winning where both name the same skill, so a project that pinned a different source keeps it.
-function mergeSkills(target, templateDir, head, files) {
-    const SKILLS = ".agents/skills/";
-    const ours = path.join(target, "skills-lock.json");
-    const theirLock = JSON.parse(blob(templateDir, head, "skills-lock.json") || '{"skills":{}}');
-    const ourLock = fs.existsSync(ours) ? JSON.parse(fs.readFileSync(ours, "utf8")) : { skills: {} };
+function planSkills(upstream, target, head, files) {
+    const LOCKFILE = "skills-lock.json";
+    const theirLock = JSON.parse(upstream.blob(head, LOCKFILE) || '{"skills":{}}');
+    const ourLock = target.exists(LOCKFILE) ? JSON.parse(target.read(LOCKFILE)) : { skills: {} };
     ourLock.skills = ourLock.skills || {};
-
     const mine = new Set(Object.keys(ourLock.skills));
-    // One line per skill, not per file. Outcome is decided across the whole folder: a skill counts
-    // as changed the moment any file in it did, and only an untouched folder reads "unchanged".
+
+    const out = [];
+    // One line per skill, not per file. Outcome is decided across the whole folder: a skill counts as
+    // changed the moment any file in it did, and only an untouched folder reads "unchanged".
     const outcomes = new Map();
     const seen = name => outcomes.get(name) || outcomes.set(name, { added: 0, updated: 0, files: 0 }).get(name);
-    for (const file of files) {
+    for (const { file, exec } of files) {
         if (!file.startsWith(SKILLS)) continue;                 // .claude/skills links are rebuilt, not copied
         const name = file.slice(SKILLS.length).split("/")[0];
         const tally = seen(name);
         tally.files++;
+        const exists = target.exists(file);
+        // A script the skill runs keeps its executable bit whoever owns the content, as a hook does.
+        if (exec && exists) out.push({ file, silent: true, exec: true });
         // A skill the project installed under a name the upstream also uses stays the project's.
         if (mine.has(name) && !theirLock.skills[name]) { tally.yours = true; continue; }
-        const text = blob(templateDir, head, file);
+        const text = upstream.blob(head, file);
         if (text === null) continue;
-        const full = path.join(target, file);
-        const exists = fs.existsSync(full);
         // A vendored file the project has not touched still differs byte-for-byte on Windows, where
         // Git checked it out with CRLF. Compared raw, every skill would report as updated every run.
-        const held = exists ? fs.readFileSync(full) : null;
+        const held = exists ? target.read(file, true) : null;
+        let write;
         if (Buffer.isBuffer(text)) {
             if (same(held, text)) continue;
-            write(target, file, text);
+            write = text;
         } else {
             const ourText = held === null ? null : held.toString("utf8");
             if (ourText !== null && toLf(ourText) === text) continue;
-            write(target, file, asFound(text, ourText !== null && isCrlf(ourText)));
+            write = asFound(text, ourText !== null && isCrlf(ourText));
         }
-        if (exists) { tally.updated++; notes.merged.push(file); }
-        else { tally.added++; notes.written.push(file); }
+        if (exists) tally.updated++; else tally.added++;
+        out.push({ file, silent: true, write, bucket: exists ? "merged" : "written", exec: exec && !exists });
     }
     for (const [name, t] of [...outcomes].sort()) {
         const what = t.yours ? "yours" : t.added ? "added" : t.updated ? "updated" : "unchanged";
-        step("skills", "100644", what, `${SKILLS}${name}  (${t.files} file(s))`);
+        out.push({ file: `${SKILLS}${name}  (${t.files} file(s))`, policy: "skills", mode: "100644", outcome: what, bucket: null });
     }
     for (const [name, entry] of Object.entries(theirLock.skills)) {
         if (!ourLock.skills[name]) ourLock.skills[name] = entry;
     }
-    if (!dryRun) fs.writeFileSync(ours, JSON.stringify(ourLock, null, 2) + "\n");
+    out.push({ file: LOCKFILE, silent: true, write: JSON.stringify(ourLock, null, 2) + "\n" });
+    return out;
+}
+
+// ---------------------------------------------------------------- applying it
+
+// Git runs a hook only if it is executable, and says nothing when it is not: an installed harness
+// whose hooks are mode 644 looks installed and gates nothing. The upstream records them 100755, so
+// that mode has to travel, and only Git can carry it. `chmod` alone is not enough -- on Windows
+// core.fileMode is false and the call does nothing, so the file would be staged 100644 later and the
+// hooks would run for whoever installed them and silently never run for anyone else. `git add
+// --chmod=+x` writes the mode into the index whether or not the file was tracked, which is why the
+// install stages these few files rather than leaving them for the project's own `git add`.
+// Returns why it failed, or null.
+function carryMode(root, file) {
+    try { fs.chmodSync(path.join(root, file), 0o755); } catch { /* the filesystem does not do modes */ }
+    const r = lib.run("git", [...GIT, "-C", root, "add", "--chmod=+x", "--", file]);
+    return r.status === 0 ? null : `could not mark ${file} executable: ${r.output}`;
+}
+
+// Carries out one entry. Returns null when it went as planned, or what happened instead: `why` to
+// print, and the `outcome` and `bucket` the run reports in place of the plan's.
+function perform(root, e) {
+    const full = path.join(root, e.file);
+    if (e.mkdir || e.link !== undefined || e.write !== undefined) fs.mkdirSync(path.dirname(full), { recursive: true });
+    if (e.link !== undefined) {
+        if (e.replace) fs.unlinkSync(full);
+        // Windows needs Developer Mode and core.symlinks=true for this to work at all, so a refusal
+        // is reported rather than thrown: the harness still functions with the link missing, it is
+        // just invisible to the harnesses that read it, and README says how to turn them on.
+        try { fs.symlinkSync(e.link.split("/").join(path.sep), full, "dir"); }
+        catch (err) { return { outcome: "yours", bucket: "kept", why: `could not create the symlink ${e.file} -> ${e.link}: ${err.code || err.message}` }; }
+        return null;
+    }
+    if (e.write !== undefined) fs.writeFileSync(full, e.write);
+    if (e.exec) { const why = carryMode(root, e.file); if (why) return { why }; }
+    return null;
 }
 
+// An install rewrites someone else's repository, so it says what it did to every path while it does
+// it, and --quiet asks for the summary alone. The mode is worth a column of its own: a hook that
+// lands 100644 gates nothing and a skill link written as a regular file leaves the agent with no
+// skills, and both look installed. A dry run prints the same lines straight from the plan.
+// Returns the entries as they turned out, which the summary is built from.
+function apply(entries, root, options) {
+    const done = [];
+    for (const e of entries) {
+        if (e.phase) { if (!options.quiet) say(`\n${e.phase}`); continue; }
+        let shown = e;
+        if (!options.dryRun) {
+            const fix = perform(root, e);
+            if (fix && fix.why) say(fix.why);
+            if (fix && fix.outcome) shown = { ...e, outcome: fix.outcome, bucket: fix.bucket };
+        }
+        if (!shown.silent && !options.quiet) say(`  ${shown.policy.padEnd(9)}${shown.mode}  ${shown.outcome.padEnd(12)}${shown.file}`);
+        done.push(shown);
+    }
+    return done;
+}
+
+// ---------------------------------------------------------------- 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.
-function finish(target) {
-    phase("links and notices");
+// 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.
+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], { cwd: target });
+        const r = lib.node([path.join(target, "scripts/skills.js"), ...args, `${lib.ROOT_FLAG}${target}`], { cwd: target });
         say(r.status === 0 ? r.output : `${label}: ${r.output}`);
     }
 }
 
-function report(target, head, ref, base) {
+// Merging is not checking. The installer knows it wrote a file; it cannot know whether the result
+// still works -- an AGENTS.md whose chain table no longer parses, routing sections naming an agent
+// this repo does not have, a skill nothing links to, an upstream with no licence row. Those are the
+// harness invariants, and scripts/check-harness.js holds them as functions of a root.
+//
+// So they run from the upstream checkout against the target, and nothing is written into the target
+// to run them. The upstream's copy rather than the one just installed, so the check is the one that
+// matches the files this run wrote. The suite's fixtures stay upstream: they prove the harness
+// scripts, which the upstream's own CI has already done.
+function selfCheck(target, templateDir, options) {
+    const script = path.join(templateDir, "scripts", "check-harness.js");
+    if (!fs.existsSync(script)) return { skipped: "this upstream ref has no scripts/check-harness.js" };
+    if (!options.quiet) say("\nself check: the harness invariants, run from the upstream against this repo");
+    const harness = require(script);
+    const r = harness.check(target);
+    return { failed: r.failed.length > 0, summary: r.summary, output: harness.format(r) };
+}
+
+// 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 }) {
+    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
     // run never saw them and gets them in full. Conflicts are listed either way: they are what the
     // reader has to act on, and they belong beside the instructions for acting on them.
     const list = (label, arr, always) => {
         if (!arr.length) return;
-        if (quiet || always) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`);
+        if (options.quiet || always) say(`\n${label} (${arr.length}):\n  ${arr.sort().join("\n  ")}`);
         else say(`\n${label}: ${arr.length}`);
     };
     say("");
-    say(dryRun ? `dry run against ${ref} at ${head.slice(0, 8)}` : `harness updated to ${ref} at ${head.slice(0, 8)}`);
+    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");
     list("added", notes.written);
     list("merged", notes.merged);
@@ -729,21 +775,74 @@ function report(target, head, ref, base) {
         list("CONFLICTED, resolve the markers by hand", notes.conflicted, true);
         say(`\nEach one holds <<<<<<< yours / ======= / >>>>>>> upstream (new). Resolve them, then check the harness:\n  node scripts/check-harness.js`);
     }
-    const check = notes.check;
     if (check && check.skipped) say(`\nself check skipped: ${check.skipped}`);
     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 (!dryRun) {
+    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`);
     }
-    if (notes.conflicted.length || notes.unreadable.length || (check && check.failed)) process.exit(1);
+    return notes.conflicted.length || notes.unreadable.length || (check && check.failed) ? 1 : 0;
 }
 
-// The decision, and the two pure helpers 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. Everything else here writes to
-// somebody's repository and stays behind main().
-module.exports = { unknownArgs, mistypedArgs, usage, policyFor, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+// ---------------------------------------------------------------- the run
+
+// Returns the exit code, and throws Stop for a run that could not start.
+function main(args) {
+    const options = parseOptions(args);
+    if (options.help) { console.log(usage()); return 0; }
+    const mistyped = mistypedArgs(args);
+    if (mistyped.length) fail(`unknown argument(s): ${mistyped.join(" ")}. Nothing was written; run with --help for the options.`);
+    const target = targetRoot(options);
+    if (!fs.existsSync(path.join(target, ".git"))) fail(`${target} is not a git checkout`);
+
+    const lockPath = path.join(target, LOCK);
+    const previous = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : null;
+    const ref = options.ref || (previous ? previous.ref : DEFAULT_REF);
+    const { dir: templateDir, temporary } = templateCheckout(ref, options);
 
-if (require.main === module) main();
+    try {
+        // Checked before anything is said about the target, so a bad argument is the only message.
+        const rows = policies(templateDir);
+        const optional = rows.filter(r => r.policy.startsWith("optional:")).map(r => r.policy.slice("optional:".length));
+        const unknown = unknownArgs(args, optional);
+        if (unknown.length) fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
+        const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
+        if (previous && previous.commit === head && !options.adopt) {
+            say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`);
+            return 0;
+        }
+
+        const planned = plan({
+            upstream: gitUpstream(templateDir, head), target: fsTarget(target), rows, head, ref, previous, options,
+            stamp: { ...installer(), updated: new Date().toISOString().slice(0, 10) },
+        });
+        for (const notice of planned.notices) say(notice);
+        const entries = apply(planned.entries, target, options);
+        let check = null;
+        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);
+            if (options.check) check = selfCheck(target, templateDir, options);
+        }
+        return report({ entries, base: planned.base, head, ref, target, check, options });
+    } finally {
+        if (temporary) fs.rmSync(templateDir, { recursive: true, force: true });
+    }
+}
+
+// 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 = { unknownArgs, mistypedArgs, usage, parseOptions, policyFor, plan, apply, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+
+if (require.main === module) {
+    try { process.exitCode = main(process.argv.slice(2)); }
+    catch (e) {
+        if (!(e instanceof Stop)) throw e;
+        console.error(`update-harness: ${e.message}`);
+        process.exitCode = 1;
+    }
+}